Comments

The document stores comment anchors; the threads themselves (bodies, authors, resolved state) live in a CommentAdapter you provide. @stesura/comments is the ProseMirror side: plugins, commands and stores. @stesura/comments-react is the UI, see Comments (React).

Setup

Add the plugins to the mount hook, the UI extension to the editor, and wrap it in a CommentProvider:

import { commentsPlugins } from "@stesura/comments";
import { CommentProvider, commentsUiExtension } from "@stesura/comments-react";
 
const uiExtensions = [commentsUiExtension]; // module scope: must be stable
 
const Editor = ({ adapter }) => {
  const { editorState, dispatch, pluginFactory, schema } = useLocalEditor({
    extraPlugins: () => [...commentsPlugins()],
  });
 
  return (
    <CommentProvider value={adapter}>
      <StesuraEditor
        state={editorState}
        dispatchTransaction={dispatch}
        schema={schema}
        pluginFactory={pluginFactory}
        uiExtensions={uiExtensions}
      />
    </CommentProvider>
  );
};

Without an adapter the comments UI renders nothing. For collaboration, @stesura/collab-adapter-react provides one, see Collaboration.

Anchors

• Range comments: comment_open / comment_close inline atoms around the text, both carrying the threadId and an anchorId. A thread can have several anchors (e.g. after copy-paste within the document), each pair with its own anchorId.
• Node comments: a { threadId } entry in a node’s nodeComments attribute, anchored by the node’s id. Opt-in per node type with globalAttributes: { nodes: { nodeComment: { table: true } } }, see Global attributes.

Comments can’t be added in headers, footers, footnotes or endnotes.

Lifecycle

insertPendingComment / insertPendingNodeComment      composer opens on the target
adapter.createThread({ body, metadata: { editorId } })
insertComment(thread.id) / setNodeComment(thread.id) anchor written, thread selected

If the pending comment closes while createThread is in flight (the selection moved, Escape), the composer deletes the new thread instead of anchoring it. closePendingComment cancels.

commentBoundaryPlugin then keeps anchors in step with the content:

• Deleting part of a range moves its boundary to the edge of the deletion; deleting all of its content removes the anchor (Word semantics).
• A thread whose last anchor is removed is reported as orphaned, and comments-react soft-deletes it. When its anchors come back (undo, paste, drag-move) it is reported as restored and un-deleted.
• On load, broken boundary pairs are removed and duplicated anchorIds re-anchored (healDanglingCommentAnchors).
• Copy-paste keeps an anchor (with a fresh anchorId) only when it was copied from the same editor with both boundaries. Anchors from another editor or from external HTML, half pairs, and anything pasted into a header, footer or note are stripped. Node comment entries are kept.

When the editor mounts and threads have loaded, comments-react also soft-deletes threads older than a minute that have no anchor, and 30 seconds later removes anchors whose thread the adapter doesn’t know.

Plugins

commentsPlugins() returns all five, in the order they must be registered:

Commands

Exported from @stesura/comments:

The anchor-removing commands don’t call the adapter, but with comments-react mounted a thread left without anchors is then soft-deleted as orphaned.

Reading pending state

For a custom composer:

• pendingCommentPluginKey.getState(state) gives { isPending, pendingSelection, pendingNodeId }. A range target sets pendingSelection, a node target pendingNodeId; use it to choose between insertComment and setNodeComment.
• findNodeCommentTarget(doc, nodeId) resolves pendingNodeId to { node, pos }, or null if the node is gone.

Stores

Per-editor nanostores, exported from @stesura/comments (getVisibleThreadsAtom / setVisibleThreadsAtom from @stesura/core/stores, since the editor reads it too). Each getter creates the atom on first use and returns the same instance afterwards, so they are safe useStore targets.

Without comments-react you must write the visible set yourself (setVisibleThreadsAtom), or nothing is highlighted.

Orphan and restore reports are a queue: takeOrphanedThreads(editorId, ids) / takeRestoredThreads(editorId, ids) remove only the ids you handled, and the rest are re-emitted, e.g. while the adapter hasn’t synced a thread yet. clearOrphanedThreads / clearRestoredThreads drop everything. clearCommentStores(editorId) resets every store on unmount.

Helpers

Exported from @stesura/comments:

Thread serialization helpers live in @stesura/core/helpers, so adapters can use them without depending on @stesura/comments:

AI tools

@stesura/comments/ai-tools lets the AI chat read and write comments. Declare commentToolDeclarations in the chat route, and bind the executors in the editor to the adapter your comments UI uses:

// the route's tool set
import { commentToolDeclarations } from "@stesura/comments/ai-tools";
const editorTools = [...builtInAiTools, ...commentToolDeclarations];
 
// the editor page, for createAiUIExtension({ useChatTools })
import { bindCommentTools } from "@stesura/comments/ai-tools";
const useChatTools = () => {
  const adapter = useCommentCtx();
  return useMemo(() => (adapter ? [...editorTools, ...bindCommentTools(adapter)] : editorTools), [adapter]);
};

What the agent adds, replies and resolves is a pending suggestion (metadata.aiSuggestions), authored by the agent, until the user accepts or rejects it.

Next steps

• Comments (React): the CommentAdapter contract, hooks and UI components.
• Collaboration: multi-user setup.