Revise Editor SDK menu

Comments

Threads anchored to text, from your UI or your agent.

Comments are threads anchored to ranges of text. They render as chips beside the page and are preserved in DOCX import and export (except detached threads, below). Your code can read and write them.

Read threads#

TypeScript
const { commentThreads, activeCommentId, commentsOpen } =
  editor.review.getState();

Each thread has a root comment, replies, an anchor, and related suggestions:

TypeScript
interface ReviseCommentThread {
  root: CommentRecord;
  replies: CommentRecord[];
  anchor: { blockId: string; start: number; end: number } | null;
  relatedSuggestionIds: string[];
  detached: boolean;
}

When the text a thread is on is deleted, the thread stays in the document with detached: true and anchor: null. A Word comment needs text to anchor to, so a .docx export leaves detached threads out. On the server, ReviseDocument.export({ format: "docx" }) checks the file it wrote and says in warnings how many comments have no place in its text and will not reopen, for this or any other reason. Resolve, delete, or re-anchor them (add a new comment where they belong) before exporting if they must travel with the file.

Add comments#

Comment bodies are Markdown. Each method returns the new comment's ID, or null when the target no longer exists.

TypeScript
// At the user's current selection
editor.review.addCommentAtSelection("Is this cap mutual?");

// At a known range
editor.review.addCommentToRanges(
  [{ blockId: "b12", start: 0, end: 24 }],
  "Confirm the notice period.",
);

// On a whole block, or attached to a suggestion
editor.review.addCommentToBlock("b12", "Needs legal review.");
editor.review.addCommentForSuggestion(suggestionId, "Why this wording?");

// Replies and lifecycle
editor.review.replyToComment(commentId, "Agreed. Updated.");
editor.review.setCommentResolved(commentId, true);
editor.review.deleteComment(commentId);

Each method takes optional mentions as an additional argument.

Panel and selection#

TypeScript
editor.view.setCommentsOpen(true);
editor.review.selectComment(commentId); // scrolls to and highlights the thread
editor.review.selectComment(commentId, { openPanel: false }); // same, panel stays closed
editor.review.selectComment(null);      // clear

The SDK has no comments button. Chips render inline, and your UI opens the panel. See chrome.

Selecting text in an editable document shows an insert-comment chip in the page margin. Clicking it starts a draft on the selection, like addCommentAtSelection. The chip is hidden during a draft, in read-only documents, and on selections that already have a thread.

Comments and suggestions together#

A comment can be linked to suggestions. A reviewer can then accept or reject those suggestions from the comment:

TypeScript
const ids = editor.review.getRelatedSuggestionIds(commentId);
editor.review.acceptCommentSuggestions(commentId); // returns the count
editor.review.rejectCommentSuggestions(commentId);

Agent comments#

The leave_comment tool adds comments from an agent:

TypeScript
// Start a thread on one block with one anchor form
await editor.tools.execute("leave_comment", {
  id: "b12",
  anchor: { text: "capped at the fees paid in the preceding twelve months" },
  comment: "Consider making this cap mutual.",
});

Other anchor forms are { start_text, end_text } for a long range, and { whole_block: true } for structural or empty content.

To reply, call the same tool without an anchor:

TypeScript
await editor.tools.execute("leave_comment", {
  reply_to_comment_id: threadId,
  comment: "Agreed. The mutual version is market standard.",
});

leave_comment anchors only to text the agent has read. Call a read tool such as read_blocks_from_index first, or the anchor does not resolve.

If the anchor text is not in the block you named, but exactly one block you have read contains it, the comment goes there instead. The result reports both: data.blockId is where it landed and data.requestedBlockId is the block you asked for. Block IDs change when a file is imported again, so this keeps a stale ID from failing.

Read tools return existing threads as <comment-thread> elements in their HTML. A new thread that overlaps an unresolved thread is rejected, and the agent should reply to that thread instead. To add an overlapping thread anyway, list the overlapping IDs in acknowledge_existing_thread_ids.

Tool comments are signed "Revise Agent" unless you set agent.name.

Comment agents#

The comments controller runs an agent scoped to one thread. Use it when each thread is a separate conversation with the model:

TypeScript
await editor.comments.run(threadId, "Draft a redline that addresses this.");
editor.comments.steer(threadId, "Keep it to one sentence.");
editor.comments.cancel(threadId);

useEffect(() => editor.comments.subscribe(setThreadRuns), [editor]);

getState(threadId) returns the thread's run state. subscribe() publishes a map of every active run.