Comments

Comments are threads anchored to ranges of text. They render as chips beside the page, survive the DOCX round trip, and are readable and writable from the host.

Reading threads

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

Each thread carries its root comment, replies, the anchor it points at, and any suggestions related to it:

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

Writing

Comment bodies are markdown. Every method returns the new comment’s ID, or null when the target no longer exists.

// 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);

Mentions are supported as an optional second argument on each of these.

Panel and selection

editor.view.setCommentsOpen(true);
editor.review.selectComment(commentId); // scrolls to and highlights the thread
editor.review.selectComment(null);      // clear

There is no built-in comments button — chips render inline, and the panel opens wherever your own UI decides. See chrome.

Comments and suggestions together

A comment can be tied to the suggestions it discusses, which lets a reviewer resolve the conversation and the edit in one action:

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

Agents leaving comments

An agent reviewing a document should usually comment rather than rewrite. The leave_comment tool is the agent-facing equivalent of the above:

await editor.tools.execute("leave_comment", {
  id: "b12",
  quote: "capped at the fees paid in the preceding twelve months",
  comment: "Consider making this cap mutual.",
});

leave_comment anchors to text the agent has actually read. Call a read tool such as read_blocks_from_index first, or the quote will not resolve to a range in the loaded context.

Comment agents

For products where each thread is its own conversation with the model, the comments controller runs an agent scoped to one thread:

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 that thread’s run state, and subscribe() publishes a map of every in-flight run, so a thread list can show per-thread progress.

Getting started

Guides

API reference

Reading threads

Writing

Panel and selection

Comments and suggestions together

Agents leaving comments

Comment agents

​Reading threads

​Writing

​Panel and selection

​Comments and suggestions together

​Agents leaving comments

​Comment agents

Reading threads

Writing

Panel and selection

Comments and suggestions together

Agents leaving comments

Comment agents