@beyondwork/docx-react-component 1.0.13 → 1.0.15

package/src/runtime/session-capabilities.ts

@@ -1,4 +1,10 @@
 import type { RuntimeRenderSnapshot } from "../api/public-types";
+import {
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+} from "../core/selection/mapping.ts";
+import { canCreateDocxCommentAnchor } from "../core/selection/review-anchors";
 
 /**
  * Session capabilities derived from the runtime snapshot.
@@ -80,7 +86,11 @@ export function deriveCapabilities(
   const canEdit = isReady && !isReadOnly && !hasFatalError;
   const canUndo = snapshot.commandState.canUndo && canEdit;
   const canRedo = snapshot.commandState.canRedo && canEdit;
-  const canAddComment = canEdit && !snapshot.selection.isCollapsed;
+  const canAddComment =
+    canEdit &&
+    !snapshot.selection.isCollapsed &&
+    Boolean(snapshot.surface) &&
+    canCreateDocxCommentAnchor(snapshot.surface, toRuntimeAnchor(snapshot.selection.activeRange));
   const canExport = isReady && !exportBlocked && !hasFatalError;
 
   // Revision capabilities
@@ -136,3 +146,14 @@ export function deriveCapabilities(
     hasFatalError,
   };
 }
+
+function toRuntimeAnchor(anchor: RuntimeRenderSnapshot["selection"]["activeRange"]) {
+  switch (anchor.kind) {
+    case "range":
+      return createRangeAnchor(anchor.from, anchor.to, anchor.assoc);
+    case "node":
+      return createNodeAnchor(anchor.at, anchor.assoc);
+    case "detached":
+      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
+  }
+}

package/src/runtime/surface-projection.ts

@@ -29,6 +29,10 @@ import {
   describeOpaqueFragment,
   getOpaqueFragment,
 } from "../preservation/store.ts";
+import {
+  createNumberingPrefixResolver,
+  type NumberingPrefixResolver,
+} from "./numbering-prefix.ts";
 
 interface ParagraphAccumulator {
   blockId: string;
@@ -37,6 +41,7 @@ interface ParagraphAccumulator {
   to: number;
   styleId?: string;
   numbering?: ParagraphNode["numbering"];
+  numberingPrefix?: string;
   segments: SurfaceInlineSegment[];
 }
 
@@ -47,6 +52,7 @@ export function createEditorSurfaceSnapshot(
   const root = normalizeDocumentRoot(document.content);
   const blocks: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
+  const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
   let cursor = 0;
   const counters = {
     paragraph: 0,
@@ -58,7 +64,13 @@ export function createEditorSurfaceSnapshot(
   };
 
   for (let index = 0; index < root.children.length; index += 1) {
-    const surfaceBlock = createSurfaceBlock(root.children[index], document, cursor, counters);
+    const surfaceBlock = createSurfaceBlock(
+      root.children[index],
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
     blocks.push(surfaceBlock.block);
     lockedFragmentIds.push(...surfaceBlock.lockedFragmentIds);
     cursor = surfaceBlock.nextCursor;
@@ -67,6 +79,8 @@ export function createEditorSurfaceSnapshot(
     }
   }
 
+  blocks.push(...createSecondaryStoryPreviewBlocks(document, cursor));
+
   return {
     storySize: cursor,
     plainText: createPlainText(blocks),
@@ -87,6 +101,7 @@ function createSurfaceBlock(
     customXml: number;
     altChunk: number;
   },
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
   if (block.type === "opaque_block") {
     const fragment = getOpaqueFragment(document.preservation as never, block.fragmentId);
@@ -115,13 +130,27 @@ function createSurfaceBlock(
   if (block.type === "table") {
     const tableIndex = counters.table;
     counters.table += 1;
-    return createTableBlock(tableIndex, block, document, cursor, counters);
+    return createTableBlock(
+      tableIndex,
+      block,
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
   }
 
   if (block.type === "sdt") {
     const sdtIndex = counters.sdt;
     counters.sdt += 1;
-    return createSdtBlock(sdtIndex, block, document, cursor, counters);
+    return createSdtBlock(
+      sdtIndex,
+      block,
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
   }
 
   if (block.type === "custom_xml") {
@@ -189,7 +218,13 @@ function createSurfaceBlock(
 
   const paragraphIndex = counters.paragraph;
   counters.paragraph += 1;
-  return createParagraphBlock(paragraphIndex, block, document, cursor);
+  return createParagraphBlock(
+    paragraphIndex,
+    block,
+    document,
+    cursor,
+    numberingPrefixResolver,
+  );
 }
 
 function createTableBlock(
@@ -205,6 +240,7 @@ function createTableBlock(
     customXml: number;
     altChunk: number;
   },
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
   const lockedFragmentIds: string[] = [];
   let innerCursor = cursor;
@@ -216,7 +252,13 @@ function createTableBlock(
     for (const [cellIndex, cell] of row.cells.entries()) {
       const cellContent: SurfaceBlockSnapshot[] = [];
       for (const child of cell.children) {
-        const result = createSurfaceBlock(child, document, innerCursor, counters);
+        const result = createSurfaceBlock(
+          child,
+          document,
+          innerCursor,
+          counters,
+          numberingPrefixResolver,
+        );
         cellContent.push(result.block);
         lockedFragmentIds.push(...result.lockedFragmentIds);
         innerCursor = result.nextCursor;
@@ -310,13 +352,20 @@ function createSdtBlock(
     customXml: number;
     altChunk: number;
   },
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
   const children: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
   let innerCursor = cursor;
 
   for (const child of block.children) {
-    const result = createSurfaceBlock(child, document, innerCursor, counters);
+    const result = createSurfaceBlock(
+      child,
+      document,
+      innerCursor,
+      counters,
+      numberingPrefixResolver,
+    );
     children.push(result.block);
     lockedFragmentIds.push(...result.lockedFragmentIds);
     innerCursor = result.nextCursor;
@@ -344,6 +393,7 @@ function createParagraphBlock(
   paragraph: ParagraphNode,
   document: CanonicalDocumentEnvelope,
   start: number,
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): {
   block: SurfaceBlockSnapshot;
   nextCursor: number;
@@ -356,12 +406,20 @@ function createParagraphBlock(
     to: start,
     ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
     ...(paragraph.numbering ? { numbering: paragraph.numbering } : {}),
+    ...(paragraph.numbering
+      ? {
+          numberingPrefix:
+            numberingPrefixResolver.resolve(paragraph.numbering) ?? undefined,
+        }
+      : {}),
     ...(paragraph.alignment ? { alignment: paragraph.alignment } : {}),
     ...(paragraph.spacing ? { spacing: paragraph.spacing } : {}),
     ...(paragraph.indentation ? { indentation: paragraph.indentation } : {}),
     ...(paragraph.borders ? { borders: paragraph.borders } : {}),
     ...(paragraph.shading ? { shading: paragraph.shading } : {}),
-    ...(paragraph.tabStops && paragraph.tabStops.length > 0 ? { tabStops: paragraph.tabStops } : {}),
+    ...(paragraph.tabStops && paragraph.tabStops.length > 0
+      ? { tabStops: paragraph.tabStops.map((tabStop) => toSurfaceTabStop(tabStop)) }
+      : {}),
     ...(paragraph.keepNext ? { keepNext: true } : {}),
     ...(paragraph.keepLines ? { keepLines: true } : {}),
     ...(paragraph.pageBreakBefore ? { pageBreakBefore: true } : {}),
@@ -459,6 +517,7 @@ function appendInlineSegments(
     case "opaque_inline": {
       const fragment = getOpaqueFragment(document.preservation as never, node.fragmentId);
       const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+      const preview = fragment ? describePreservedInlinePreview(fragment.payloadReference) : null;
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
         kind: "opaque_inline",
@@ -466,8 +525,9 @@ function appendInlineSegments(
         to: start + 1,
         fragmentId: node.fragmentId,
         warningId: node.warningId,
-        label: descriptor?.label ?? "Unsupported inline OOXML",
+        label: preview?.label ?? descriptor?.label ?? "Unsupported inline OOXML",
         detail:
+          preview?.detail ??
           descriptor?.detail ??
           "Locked whole-unit to keep unsupported inline OOXML intact through export.",
         state: "locked-preserve-only",
@@ -612,6 +672,9 @@ function createPlainText(
   const text: string[] = [];
   for (const block of blocks) {
     if (block.kind === "opaque_block") {
+      if (block.fragmentId.startsWith("preview:")) {
+        continue;
+      }
       text.push("\uFFFA");
       continue;
     }
@@ -650,6 +713,222 @@ function createPlainText(
   return text.join("");
 }
 
+function createSecondaryStoryPreviewBlocks(
+  document: CanonicalDocumentEnvelope,
+  cursor: number,
+): SurfaceBlockSnapshot[] {
+  const previews: SurfaceBlockSnapshot[] = [];
+  const subParts = document.subParts;
+  if (!subParts) {
+    return previews;
+  }
+
+  for (const header of subParts.headers ?? []) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Header · ${header.variant}`,
+        `header:${header.relationshipId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(header.partPath, header.blocks),
+      ),
+    );
+  }
+
+  for (const footer of subParts.footers ?? []) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Footer · ${footer.variant}`,
+        `footer:${footer.relationshipId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(footer.partPath, footer.blocks),
+      ),
+    );
+  }
+
+  const footnotes = Object.values(subParts.footnoteCollection?.footnotes ?? {}).sort(compareNoteIds);
+  for (const note of footnotes) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Footnote ${note.noteId}`,
+        `footnote:${note.noteId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(`/word/footnotes.xml#${note.noteId}`, note.blocks),
+      ),
+    );
+  }
+
+  const endnotes = Object.values(subParts.footnoteCollection?.endnotes ?? {}).sort(compareNoteIds);
+  for (const note of endnotes) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Endnote ${note.noteId}`,
+        `endnote:${note.noteId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(`/word/endnotes.xml#${note.noteId}`, note.blocks),
+      ),
+    );
+  }
+
+  return previews;
+}
+
+function createSecondaryStoryPreviewBlock(
+  label: string,
+  previewId: string,
+  cursor: number,
+  detail: string,
+): Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }> {
+  return {
+    blockId: `secondary-story-${previewId.replace(/[^a-z0-9._:-]+/gi, "-")}`,
+    kind: "opaque_block",
+    from: cursor,
+    to: cursor,
+    fragmentId: `preview:${previewId}`,
+    warningId: `preview:${previewId}`,
+    label,
+    detail,
+    state: "locked-preserve-only",
+  };
+}
+
+function createSecondaryStoryPreviewDetail(
+  sourceLabel: string,
+  blocks: readonly BlockNode[],
+): string {
+  const previewLines = blocks
+    .map((block) => summarizePreviewBlock(block))
+    .filter((line) => line.trim().length > 0);
+  const previewText = previewLines.length > 0 ? previewLines.join("\n\n") : "Empty story.";
+  return `Read-only preview from ${sourceLabel}.\n${previewText}`;
+}
+
+function summarizePreviewBlock(block: BlockNode): string {
+  switch (block.type) {
+    case "paragraph": {
+      const text = block.children.map((child) => summarizePreviewInline(child)).join("");
+      return text.trim().length > 0 ? text : "¶";
+    }
+    case "table":
+      return "[Table preserved in secondary story]";
+    case "opaque_block":
+      return "[Locked block preserved for export]";
+    case "sdt":
+      return "[Content control preview]";
+    case "custom_xml":
+      return "[Custom XML preview]";
+    case "alt_chunk":
+      return "[AltChunk preview]";
+    case "section_break":
+      return "[Section boundary]";
+  }
+}
+
+function summarizePreviewInline(node: InlineNode): string {
+  switch (node.type) {
+    case "text":
+      return node.text;
+    case "tab":
+      return "\t";
+    case "hard_break":
+      return "\n";
+    case "hyperlink":
+      return node.children.map((child) => summarizePreviewInline(child)).join("");
+    case "footnote_ref":
+      return node.noteKind === "footnote" ? `[fn ${node.noteId}]` : `[en ${node.noteId}]`;
+    case "field": {
+      const instruction = node.instruction.trim();
+      return instruction.length > 0 ? `[Field: ${instruction}]` : "[Field]";
+    }
+    case "bookmark_start":
+      return node.name ? `[Bookmark: ${node.name}]` : "[Bookmark]";
+    case "bookmark_end":
+      return "";
+    case "image":
+      return node.altText ? `[Image: ${node.altText}]` : "[Image]";
+    case "opaque_inline":
+      return "[Locked inline content]";
+    case "symbol":
+      return node.char ? String.fromCodePoint(parseInt(node.char, 16)) : "\uFFFD";
+    case "column_break":
+      return "[Column break]";
+    case "chart_preview":
+      return "[Chart]";
+    case "smartart_preview":
+      return "[SmartArt]";
+    case "shape":
+      return node.text ? `[Shape: ${node.text}]` : "[Shape]";
+    case "wordart":
+      return node.text ? `[WordArt: ${node.text}]` : "[WordArt]";
+    case "vml_shape":
+      return node.text ? `[VML: ${node.text}]` : "[VML shape]";
+  }
+}
+
+function compareNoteIds(
+  left: { noteId: string },
+  right: { noteId: string },
+): number {
+  return Number.parseInt(left.noteId, 10) - Number.parseInt(right.noteId, 10);
+}
+
+function toSurfaceTabStop(
+  tabStop: NonNullable<ParagraphNode["tabStops"]>[number],
+): { pos: number; val?: string; leader?: string } {
+  return {
+    pos: tabStop.position,
+    ...(tabStop.align ? { val: tabStop.align } : {}),
+    ...(tabStop.leader ? { leader: tabStop.leader } : {}),
+  };
+}
+
+function describePreservedInlinePreview(
+  payloadReference: string,
+): { label: string; detail: string } | null {
+  if (/\b(?:w:)?bookmarkStart\b/u.test(payloadReference)) {
+    const name = /\bw:name="([^"]+)"/u.exec(payloadReference)?.[1];
+    return {
+      label: name ? `Bookmark · ${name}` : "Bookmark",
+      detail: name
+        ? `Bookmark anchor \"${name}\" is preserved as a read-only inline token for export safety.`
+        : "Bookmark anchor is preserved as a read-only inline token for export safety.",
+    };
+  }
+
+  if (/\b(?:w:)?bookmarkEnd\b/u.test(payloadReference)) {
+    return {
+      label: "Bookmark end",
+      detail: "Bookmark end marker is preserved as a read-only inline token for export safety.",
+    };
+  }
+
+  if (/\b(?:w:)?fldSimple\b|\b(?:w:)?fldChar\b|\b(?:w:)?instrText\b/u.test(payloadReference)) {
+    const simpleInstruction = /\bw:instr="([^"]*)"/u.exec(payloadReference)?.[1];
+    const complexInstruction = [...payloadReference.matchAll(/<(?:\w+:)?instrText\b[^>]*>([\s\S]*?)<\/(?:\w+:)?instrText>/gu)]
+      .map((match) => decodeXmlEntities(match[1] ?? ""))
+      .join("")
+      .trim();
+    const instruction = (simpleInstruction ?? complexInstruction ?? "").trim();
+    return {
+      label: "Field",
+      detail:
+        instruction.length > 0
+          ? `Read-only field preserved for export safety. Instruction: ${instruction}.`
+          : "Read-only field preserved for export safety.",
+    };
+  }
+
+  return null;
+}
+
+function decodeXmlEntities(text: string): string {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
 function cloneMarks(marks: TextMark[]): {
   marks: SurfaceTextMark[];
   markAttrs?: {

package/src/ui/WordReviewEditor.tsx

@@ -144,16 +144,26 @@ export function __createWordReviewEditorRefBridge(
     reopenComment: (commentId) => runtime.reopenComment(commentId),
     addCommentReply: (commentId, body) => runtime.addCommentReply(commentId, body),
     editCommentBody: (commentId, body) => runtime.editCommentBody(commentId, body),
+    deleteComment: (commentId) => {
+      applyRuntimeDeleteComment(runtime, commentId);
+    },
     acceptChange: (changeId) => runtime.acceptChange(changeId),
     rejectChange: (changeId) => runtime.rejectChange(changeId),
     acceptAllChanges: () => runtime.acceptAllChanges(),
     rejectAllChanges: () => runtime.rejectAllChanges(),
     exportDocx: (options) => runtime.exportDocx(options),
     getSnapshot: () => runtime.getPersistedSnapshot(),
+    getRenderSnapshot: () => clonePublicValue(runtime.getRenderSnapshot()),
     getCompatibilityReport: () => runtime.getCompatibilityReport(),
     getWarnings: () => runtime.getWarnings(),
-    getComments: () => runtime.getRenderSnapshot().comments,
-    getTrackedChanges: () => runtime.getRenderSnapshot().trackedChanges,
+    getCommentSidebarSnapshot: () =>
+      clonePublicValue(runtime.getRenderSnapshot().comments),
+    getTrackedChangesSnapshot: () =>
+      clonePublicValue(runtime.getRenderSnapshot().trackedChanges),
+    getComments: () => clonePublicValue(runtime.getRenderSnapshot().comments),
+    getTrackedChanges: () =>
+      clonePublicValue(runtime.getRenderSnapshot().trackedChanges),
+    isDirty: () => runtime.getRenderSnapshot().isDirty,
     getFormattingState: () => getFormattingStateFromRenderSnapshot(runtime.getRenderSnapshot()),
     toggleBold: () => {
       applyRuntimeFormattingOperation(runtime, { type: "toggle", mark: "bold" });
@@ -275,6 +285,14 @@ export function __createWordReviewEditorRefBridge(
     clearSearch: () => {
       mountedSurface?.clearSearch();
     },
+    setSelection: (selection) => {
+      runtime.dispatch({
+        type: "selection.set",
+        selection: toRuntimeSelectionSnapshot(
+          normalizeRequestedSelection(runtime.getRenderSnapshot(), selection),
+        ),
+      });
+    },
     scrollToRevision: (revisionId: string) => {
       const revision = runtime.getRenderSnapshot().trackedChanges.revisions.find(
         (r) => r.revisionId === revisionId,
@@ -671,6 +689,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           activeRuntime.addCommentReply(commentId, body, currentUser.userId),
         editCommentBody: (commentId, body) =>
           activeRuntime.editCommentBody(commentId, body),
+        deleteComment: (commentId) => {
+          applyRuntimeDeleteComment(activeRuntime, commentId);
+        },
         acceptChange: (changeId) => activeRuntime.acceptChange(changeId),
         rejectChange: (changeId) => activeRuntime.rejectChange(changeId),
         acceptAllChanges: () => activeRuntime.acceptAllChanges(),
@@ -694,10 +715,18 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
                 onEvent: onEventRef.current,
               }),
         getSnapshot: () => activeRuntime.getPersistedSnapshot(),
+        getRenderSnapshot: () => clonePublicValue(activeRuntime.getRenderSnapshot()),
         getCompatibilityReport: () => activeRuntime.getCompatibilityReport(),
         getWarnings: () => activeRuntime.getWarnings(),
-        getComments: () => activeRuntime.getRenderSnapshot().comments,
-        getTrackedChanges: () => activeRuntime.getRenderSnapshot().trackedChanges,
+        getCommentSidebarSnapshot: () =>
+          clonePublicValue(activeRuntime.getRenderSnapshot().comments),
+        getTrackedChangesSnapshot: () =>
+          clonePublicValue(activeRuntime.getRenderSnapshot().trackedChanges),
+        getComments: () =>
+          clonePublicValue(activeRuntime.getRenderSnapshot().comments),
+        getTrackedChanges: () =>
+          clonePublicValue(activeRuntime.getRenderSnapshot().trackedChanges),
+        isDirty: () => activeRuntime.getRenderSnapshot().isDirty,
         getFormattingState: () =>
           getFormattingStateFromRenderSnapshot(activeRuntime.getRenderSnapshot()),
         toggleBold: () => {
@@ -838,6 +867,14 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         clearSearch: () => {
           surfaceRef.current?.clearSearch();
         },
+        setSelection: (selection) => {
+          activeRuntime.dispatch({
+            type: "selection.set",
+            selection: toRuntimeSelectionSnapshot(
+              normalizeRequestedSelection(activeRuntime.getRenderSnapshot(), selection),
+            ),
+          });
+        },
         scrollToRevision: (revisionId: string) => {
           const revision = activeRuntime.getRenderSnapshot().trackedChanges.revisions.find(
             (r) => r.revisionId === revisionId,
@@ -958,12 +995,16 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     }
 
     function addReviewComment(): void {
-      activeRuntime.addComment({
-        anchor: snapshot.selection.activeRange,
-        body: "New review comment",
-        authorId: currentUser.userId,
-      });
-      setActiveRailTab("comments");
+      try {
+        activeRuntime.addComment({
+          anchor: snapshot.selection.activeRange,
+          body: "New review comment",
+          authorId: currentUser.userId,
+        });
+        setActiveRailTab("comments");
+      } catch {
+        // Runtime already emitted a concrete export-safety error for invalid anchors.
+      }
     }
 
     function exportCurrentDocument(): void {
@@ -991,6 +1032,10 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       ? derivedCapabilities
       : { ...derivedCapabilities, reviewRailVisible: false };
     const diagnosticsModeMessage = getDiagnosticsModeMessage(loadError ?? snapshot.fatalError);
+    const addCommentDisabledReason =
+      !capabilities.canAddComment && !snapshot.selection.isCollapsed
+        ? "Select text within one paragraph to add a DOCX comment."
+        : undefined;
     const accessibilityInstructionsId = `${documentId}-accessibility-instructions`;
     const accessibilityStatusId = `${documentId}-accessibility-status`;
     const accessibilityAlertId = `${documentId}-accessibility-alert`;
@@ -1147,6 +1192,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           activeRevisionId={activeRevisionId}
           showTrackedChanges={showTrackedChanges}
           selectionPreview={selectionPreview}
+          addCommentDisabledReason={addCommentDisabledReason}
           onViewModeChange={setViewMode}
           onActiveRailTabChange={setActiveRailTab}
           onShowTrackedChangesChange={setShowTrackedChanges}
@@ -1345,6 +1391,70 @@ function dispatchRuntimeDocumentMutation(
   });
 }
 
+function applyRuntimeDeleteComment(
+  runtime: WordReviewEditorRuntime,
+  commentId: string,
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (!snapshot.isReady || snapshot.readOnly || snapshot.fatalError) {
+    return;
+  }
+
+  const persistedSnapshot = runtime.getPersistedSnapshot();
+  if (!persistedSnapshot.canonicalDocument.review.comments[commentId]) {
+    return;
+  }
+
+  const nextComments = {
+    ...persistedSnapshot.canonicalDocument.review.comments,
+  };
+  delete nextComments[commentId];
+
+  runtime.dispatch({
+    type: "document.replace",
+    document: {
+      ...persistedSnapshot.canonicalDocument,
+      review: {
+        ...persistedSnapshot.canonicalDocument.review,
+        comments: nextComments,
+      },
+    },
+    selection: toRuntimeSelectionSnapshot(snapshot.selection),
+    origin: {
+      source: "api",
+      timestamp: new Date().toISOString(),
+    },
+  });
+}
+
+function normalizeRequestedSelection(
+  snapshot: RuntimeRenderSnapshot,
+  selection: PublicSelectionSnapshot | null,
+): PublicSelectionSnapshot {
+  return selection ?? createCollapsedPublicSelection(snapshot.selection.head);
+}
+
+function createCollapsedPublicSelection(position: number): PublicSelectionSnapshot {
+  return {
+    anchor: position,
+    head: position,
+    isCollapsed: true,
+    activeRange: {
+      kind: "range",
+      from: position,
+      to: position,
+      assoc: {
+        start: -1,
+        end: 1,
+      },
+    },
+  };
+}
+
+function clonePublicValue<T>(value: T): T {
+  return structuredClone(value);
+}
+
 function searchSnapshotSurface(
   snapshot: RuntimeRenderSnapshot,
   query: string,

package/src/ui-tailwind/chrome/tw-selection-toolbar.tsx

@@ -5,6 +5,8 @@ import { MessageSquare } from "lucide-react";
 export interface TwSelectionToolbarProps {
   selectionPreview: string;
   readOnly: boolean;
+  canAddComment?: boolean;
+  disabledReason?: string;
   onAddComment?: () => void;
 }
 
@@ -12,6 +14,10 @@ const focusRingClass =
   "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas";
 
 export function TwSelectionToolbar(props: TwSelectionToolbarProps) {
+  const addCommentDisabled = props.readOnly || props.canAddComment === false;
+  const tooltipLabel = addCommentDisabled
+    ? props.disabledReason ?? "Select text within one paragraph to add a DOCX comment"
+    : "Add comment";
   return (
     <div className="mb-6 inline-flex items-center gap-1 rounded-lg bg-canvas shadow-lg ring-1 ring-border p-1">
       <Tooltip.Root>
@@ -19,7 +25,7 @@ export function TwSelectionToolbar(props: TwSelectionToolbarProps) {
           <button
             type="button"
             aria-label="Comment"
-            disabled={props.readOnly}
+            disabled={addCommentDisabled}
             onClick={props.onAddComment}
             className={`inline-flex h-7 w-7 items-center justify-center rounded-md transition-colors text-accent hover:bg-accent-soft disabled:opacity-30 disabled:cursor-not-allowed ${focusRingClass}`}
           >
@@ -31,7 +37,7 @@ export function TwSelectionToolbar(props: TwSelectionToolbarProps) {
             className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50"
             sideOffset={6}
           >
-            Add comment
+            {tooltipLabel}
           </Tooltip.Content>
         </Tooltip.Portal>
       </Tooltip.Root>