@beyondwork/docx-react-component 1.0.22 → 1.0.24-rc

package/src/ui/WordReviewEditor.tsx

@@ -41,12 +41,14 @@ import type {
   SelectionSnapshot as PublicSelectionSnapshot,
   StyleCatalogSnapshot,
   SurfaceBlockSnapshot,
+  TrackedChangeEntrySnapshot,
   TocRefreshResult,
   UpdateFieldsResult,
   ViewMode as EditorViewMode,
   WorkflowBlockedCommandReason,
   WorkflowMarkupSnapshot,
   WorkflowScopeSnapshot,
+  WordReviewEditorChromeVisibility,
   WordReviewEditorEvent,
   WordReviewEditorProps,
   WordReviewEditorRef,
@@ -150,6 +152,7 @@ import type { MarkupDisplay } from "./headless/comment-decoration-model";
 import type {
   SelectionToolbarAnchor,
   SelectionToolbarModel,
+  SuggestionCardModel,
 } from "./headless/selection-toolbar-model";
 import { type EditorCommandBag, useCommandBag } from "./editor-command-bag.ts";
 import { deriveVisibleWorkflowBlockedRails } from "./workflow-surface-blocked-rails.ts";
@@ -464,6 +467,15 @@ export function __createWordReviewEditorRefBridge(
     getWorkflowMarkupSnapshot: () => {
       return clonePublicValue(runtime.getWorkflowMarkupSnapshot());
     },
+    setHostAnnotationOverlay: (overlay) => {
+      runtime.setHostAnnotationOverlay(clonePublicValue(overlay));
+    },
+    clearHostAnnotationOverlay: () => {
+      runtime.clearHostAnnotationOverlay();
+    },
+    getHostAnnotationSnapshot: () => {
+      return clonePublicValue(runtime.getHostAnnotationSnapshot());
+    },
     getWorkflowCandidateRanges: (options) => {
       return clonePublicValue(runtime.getWorkflowCandidateRanges(options));
     },
@@ -473,6 +485,20 @@ export function __createWordReviewEditorRefBridge(
   };
 }
 
+export function __applyRuntimeTextCommand(
+  runtime: WordReviewEditorRuntime,
+  command:
+    | { type: "insert-text"; text: string }
+    | { type: "delete-backward" }
+    | { type: "delete-forward" }
+    | { type: "insert-tab" }
+    | { type: "outdent-tab" }
+    | { type: "insert-hard-break" }
+    | { type: "split-paragraph" },
+): void {
+  applyRuntimeTextCommand(runtime, command);
+}
+
 export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditorProps>(
   function WordReviewEditor(props, ref) {
     const {
@@ -494,12 +520,15 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       onWarning,
       readOnly = false,
       reviewMode = "review",
+      suggestionsEnabled = false,
       showReviewPanel = true,
+      chromeVisibility,
     } = props;
 
     const [activeRailTab, setActiveRailTab] = useState<ReviewRailTab>("comments");
     const [showTrackedChanges, setShowTrackedChanges] = useState(false);
     const [activeRevisionId, setActiveRevisionId] = useState<string | undefined>();
+    const [suppressedSuggestionRevisionId, setSuppressedSuggestionRevisionId] = useState<string | null>(null);
     const [selectionToolbarAnchor, setSelectionToolbarAnchor] = useState<SelectionToolbarAnchor | null>(null);
     const [selectionToolbarDismissedKey, setSelectionToolbarDismissedKey] = useState<string | null>(null);
     const [selectionToolbarFocusWithin, setSelectionToolbarFocusWithin] = useState(false);
@@ -644,7 +673,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
             getValue: () => runtime.getInteractionGuardSnapshot(),
           }
         : null,
-      { blockedReasons: [] } satisfies InteractionGuardSnapshot,
+      { effectiveMode: "edit", blockedReasons: [] } satisfies InteractionGuardSnapshot,
       interactionGuardSnapshotsEqual,
     );
     const workflowMarkupSnapshot = useMemo(
@@ -655,17 +684,20 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       () => deriveVisibleWorkflowBlockedRails(snapshot.surface, workflowMarkupSnapshot),
       [snapshot.surface, workflowMarkupSnapshot],
     );
-    const sessionState = useMemo(
-      () => (runtime ? runtime.getSessionState() : loadingSessionState),
-      [loadingSessionState, runtime, snapshot.revisionToken],
+    const canonicalDocument = useMemo(
+      () => (runtime ? runtime.getCanonicalDocument() : loadingSessionState.canonicalDocument),
+      [loadingSessionState.canonicalDocument, runtime, snapshot.revisionToken],
     );
-    const canonicalDocument = sessionState.canonicalDocument;
     const effectiveViewMode = deriveEditorViewMode(snapshot.readOnly, reviewMode);
 
     useEffect(() => {
       activeRuntime.setViewMode(effectiveViewMode);
     }, [activeRuntime, effectiveViewMode]);
 
+    useEffect(() => {
+      activeRuntime.setDocumentMode(suggestionsEnabled ? "suggesting" : "editing");
+    }, [activeRuntime, suggestionsEnabled]);
+
     useEffect(() => {
       runtimeViewStateSeedRef.current = {
         workspaceMode: viewState.workspaceMode,
@@ -901,14 +933,20 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
             (r) => r.revisionId === revisionId,
           );
           if (!revision || revision.anchor.kind === "detached") return;
-          applyRuntimeSelection(activeRuntime, createSelectionFromAnchor(revision.anchor));
+          applyRuntimeSelection(
+            activeRuntime,
+            createSelectionFromAnchor(revision.anchor, revision.storyTarget),
+          );
         },
         scrollToComment: (commentId: string) => {
           const comment = activeRuntime.getRenderSnapshot().comments.threads.find(
             (t) => t.commentId === commentId,
           );
           if (!comment || comment.anchor.kind === "detached") return;
-          applyRuntimeSelection(activeRuntime, createSelectionFromAnchor(comment.anchor));
+          applyRuntimeSelection(
+            activeRuntime,
+            createSelectionFromAnchor(comment.anchor),
+          );
         },
         openStory: (target: EditorStoryTarget) => {
           activeRuntime.openStory(target);
@@ -982,6 +1020,15 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         getWorkflowMarkupSnapshot: () => {
           return clonePublicValue(activeRuntime.getWorkflowMarkupSnapshot());
         },
+        setHostAnnotationOverlay: (overlay) => {
+          activeRuntime.setHostAnnotationOverlay(clonePublicValue(overlay));
+        },
+        clearHostAnnotationOverlay: () => {
+          activeRuntime.clearHostAnnotationOverlay();
+        },
+        getHostAnnotationSnapshot: () => {
+          return clonePublicValue(activeRuntime.getHostAnnotationSnapshot());
+        },
         getWorkflowCandidateRanges: (options) => {
           return clonePublicValue(activeRuntime.getWorkflowCandidateRanges(options));
         },
@@ -1080,11 +1127,14 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       snapshot.trackedChanges.totalCount,
     ]);
 
-    function focusAnchor(anchor: PublicSelectionSnapshot["activeRange"]): void {
+    function focusAnchor(
+      anchor: PublicSelectionSnapshot["activeRange"],
+      storyTarget?: EditorStoryTarget,
+    ): void {
       if (anchor.kind === "detached") {
         return;
       }
-      applyRuntimeSelection(activeRuntime, createSelectionFromAnchor(anchor));
+      applyRuntimeSelection(activeRuntime, createSelectionFromAnchor(anchor, storyTarget));
     }
 
     function addReviewComment(): string | null {
@@ -1129,7 +1179,11 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       reviewMode,
       workflowScopeSnapshot,
     );
-    const capabilities = showReviewPanel
+    const resolvedChromeVisibility = resolveWordReviewEditorChromeVisibility(
+      chromeVisibility,
+      showReviewPanel,
+    );
+    const capabilities = resolvedChromeVisibility.reviewRail
       ? derivedCapabilities
       : { ...derivedCapabilities, reviewRailVisible: false };
     const formattingState = getFormattingStateFromRenderSnapshot(snapshot);
@@ -1152,7 +1206,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         }),
       [canonicalDocument, snapshot.selection, snapshot.surface, viewState.activeStory],
     );
-    const sourcePackage = sessionState.sourcePackage;
+    const sourcePackage = runtime
+      ? runtime.getSourcePackage()
+      : loadingSessionState.sourcePackage;
     const mediaPreviewCatalogKey = Object.values(canonicalDocument.media.items)
       .map((item) =>
         [
@@ -1214,14 +1270,26 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       documentNavigation,
       styleCatalog,
       formattingState,
+      workflowScopeSnapshot,
+      interactionGuardSnapshot,
+      addCommentDisabledReason,
+    });
+    const suggestionCard = buildSuggestionCardModel({
+      snapshot,
+      viewState,
+      capabilities,
+      workflowScopeSnapshot,
+      interactionGuardSnapshot,
+      activeRevisionId,
+      suppressedSuggestionRevisionId,
       addCommentDisabledReason,
     });
     const selectionToolbarSelectionKey = useMemo(
-      () => createSelectionToolbarSelectionKey(snapshot.selection, viewState.activeStory),
-      [snapshot.selection, viewState.activeStory],
+      () => createSelectionToolbarSelectionKey(snapshot.selection, viewState.activeStory, activeRevisionId),
+      [activeRevisionId, snapshot.selection, viewState.activeStory],
     );
-    const shouldRenderSelectionToolbar = Boolean(
-      selectionToolbar &&
+    const shouldRenderSelectionChrome = Boolean(
+      (selectionToolbar || suggestionCard) &&
       selectionToolbarSelectionKey &&
       selectionToolbarDismissedKey !== selectionToolbarSelectionKey &&
       (viewState.isFocused || selectionToolbarFocusWithin),
@@ -1341,6 +1409,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
 
     useEffect(() => {
       if (!selectionToolbarSelectionKey) {
+        setSuppressedSuggestionRevisionId(null);
         setSelectionToolbarDismissedKey(null);
         setSelectionToolbarFocusWithin(false);
         setSelectionToolbarAnchor(null);
@@ -1350,17 +1419,18 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
 
       if (lastSelectionToolbarKeyRef.current !== selectionToolbarSelectionKey) {
         lastSelectionToolbarKeyRef.current = selectionToolbarSelectionKey;
+        setSuppressedSuggestionRevisionId(null);
         setSelectionToolbarDismissedKey(null);
         setSelectionToolbarFocusWithin(false);
       }
     }, [selectionToolbarSelectionKey]);
 
     useEffect(() => {
-      if (!selectionToolbar) {
+      if (!selectionToolbar && !suggestionCard) {
         setSelectionToolbarAnchor(null);
         setSelectionToolbarFocusWithin(false);
       }
-    }, [selectionToolbar]);
+    }, [selectionToolbar, suggestionCard]);
 
     useEffect(() => {
       const shell = shellRef.current;
@@ -1389,9 +1459,26 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     }, [loadError, snapshot.fatalError]);
 
     function handleShellKeyDownCapture(event: React.KeyboardEvent<HTMLDivElement>): void {
+      const targetWithinDocument = isTargetWithinDocumentSurface(event.target);
+      const isUndoShortcut = (event.ctrlKey || event.metaKey) && !event.shiftKey && event.key.toLowerCase() === "z";
+      const isRedoShortcut =
+        ((event.ctrlKey || event.metaKey) && event.shiftKey && event.key.toLowerCase() === "z") ||
+        (event.ctrlKey && event.key.toLowerCase() === "y");
+
+      if ((isUndoShortcut || isRedoShortcut) && targetWithinDocument) {
+        event.preventDefault();
+        event.stopPropagation();
+        if (isUndoShortcut) {
+          activeRuntime.undo();
+        } else {
+          activeRuntime.redo();
+        }
+        return;
+      }
+
       if (
         event.key === "Escape" &&
-        shouldRenderSelectionToolbar &&
+        shouldRenderSelectionChrome &&
         (isTargetWithinDocumentSurface(event.target) || isTargetWithinSelectionToolbar(event.target))
       ) {
         event.preventDefault();
@@ -1430,6 +1517,13 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       onOutdentTab: () => applyRuntimeTextCommand(activeRuntime, { type: "outdent-tab" }),
       onInsertHardBreak: () => applyRuntimeTextCommand(activeRuntime, { type: "insert-hard-break" }),
       onSplitParagraph: () => applyRuntimeTextCommand(activeRuntime, { type: "split-paragraph" }),
+      onUndo: () => activeRuntime.undo(),
+      onRedo: () => activeRuntime.redo(),
+      onBlockedInput: (command: "paste" | "drop", message: string) =>
+        activeRuntime.emitBlockedCommand(command, [{
+          code: "unsupported_surface",
+          message,
+        }]),
     };
 
     const reviewCallbacks = {
@@ -1458,7 +1552,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       },
       onOpenRevision: (revision: typeof snapshot.trackedChanges.revisions[number]) => {
         setActiveRevisionId(revision.revisionId);
-        focusAnchor(revision.anchor);
+        focusAnchor(revision.anchor, revision.storyTarget);
         setActiveRailTab("changes");
       },
       onAcceptRevision: (revisionId: string) => {
@@ -1618,11 +1712,14 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         markupDisplay={liveMarkupDisplay}
         activeRevisionId={activeRevisionId}
         showTrackedChanges={showTrackedChanges}
+        suggestionsEnabled={suggestionsEnabled}
         mediaPreviews={mediaPreviews}
         isPageWorkspace={isPageWorkspace}
         workflowScopes={workflowScopeSnapshot?.scopes}
         workflowCandidates={workflowScopeSnapshot?.candidates}
         workflowBlockedReasons={workflowBlockedRails}
+        activeWorkflowWorkItemId={workflowScopeSnapshot?.activeWorkItemId ?? null}
+        activeWorkflowScopeIds={workflowScopeSnapshot?.activeWorkItem?.scopeIds ?? []}
         onSelectionToolbarAnchorChange={handleSelectionToolbarAnchorChange}
         {...editorCallbacks}
         onCommentActivated={(commentId) => {
@@ -1656,6 +1753,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         markupDisplay={liveMarkupDisplay}
         currentUserId={currentUser.userId}
         capabilities={capabilities}
+        chromeVisibility={resolvedChromeVisibility}
         documentNavigation={documentNavigation}
         reviewMode={reviewMode}
         workspaceMode={viewState.workspaceMode}
@@ -1668,9 +1766,28 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         showTrackedChanges={showTrackedChanges}
         workflowScopeSnapshot={workflowScopeSnapshot}
         interactionGuardSnapshot={interactionGuardSnapshot}
-        selectionToolbar={shouldRenderSelectionToolbar ? selectionToolbar : null}
-        selectionToolbarAnchor={shouldRenderSelectionToolbar ? selectionToolbarAnchor : null}
+        selectionToolbar={shouldRenderSelectionChrome ? selectionToolbar : null}
+        suggestionCard={shouldRenderSelectionChrome ? suggestionCard : null}
+        selectionToolbarAnchor={shouldRenderSelectionChrome ? selectionToolbarAnchor : null}
         onAddCommentFromSelection={addSelectionToolbarComment}
+        onAddCommentFromSuggestion={addSelectionToolbarComment}
+        onAcceptSuggestion={suggestionCard
+          ? () => {
+              activeRuntime.acceptChange(suggestionCard.revisionId);
+              dismissSelectionToolbar("chrome-action");
+            }
+          : undefined}
+        onRejectSuggestion={suggestionCard
+          ? () => {
+              activeRuntime.rejectChange(suggestionCard.revisionId);
+              dismissSelectionToolbar("chrome-action");
+            }
+          : undefined}
+        onEditSuggestion={suggestionCard
+          ? () => {
+              setSuppressedSuggestionRevisionId(suggestionCard.revisionId);
+            }
+          : undefined}
         onDismissSelectionToolbar={() => dismissSelectionToolbar("chrome-action")}
         onSelectionToolbarFocusCapture={handleSelectionToolbarFocusCapture}
         onSelectionToolbarBlurCapture={handleSelectionToolbarBlurCapture}
@@ -1696,7 +1813,10 @@ function applyRuntimeFormattingOperation(
     | { type: "indent" }
     | { type: "outdent" },
 ): void {
-  const context = getStoryMutationContext(runtime);
+  if (emitSuggestingUnsupportedMutation(runtime, getFormattingOperationCommandName(operation))) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, getFormattingOperationCommandName(operation));
   if (!context) {
     return;
   }
@@ -1764,7 +1884,10 @@ function applyRuntimeParagraphStyle(
   runtime: WordReviewEditorRuntime,
   styleId: string | null,
 ): void {
-  const context = getStoryMutationContext(runtime);
+  if (emitSuggestingUnsupportedMutation(runtime, "setParagraphStyle")) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "setParagraphStyle");
   if (!context) {
     return;
   }
@@ -1789,7 +1912,10 @@ function applyRuntimeTableStyle(
   runtime: WordReviewEditorRuntime,
   styleId: string | null,
 ): void {
-  const context = getStoryMutationContext(runtime);
+  if (emitSuggestingUnsupportedMutation(runtime, "setTableStyle")) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "setTableStyle");
   if (!context) {
     return;
   }
@@ -1819,7 +1945,10 @@ function applyRuntimeParagraphIndentation(
     hanging?: number;
   },
 ): void {
-  const context = getStoryMutationContext(runtime);
+  if (emitSuggestingUnsupportedMutation(runtime, "setParagraphIndentation")) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "setParagraphIndentation");
   if (!context) {
     return;
   }
@@ -1845,7 +1974,10 @@ function applyRuntimeParagraphTabStops(
   runtime: WordReviewEditorRuntime,
   tabStops: Array<{ pos: number; val?: string; leader?: string }>,
 ): void {
-  const context = getStoryMutationContext(runtime);
+  if (emitSuggestingUnsupportedMutation(runtime, "setParagraphTabStops")) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "setParagraphTabStops");
   if (!context) {
     return;
   }
@@ -1871,7 +2003,18 @@ function applyRuntimeNumberingFlow(
   runtime: WordReviewEditorRuntime,
   operation: { type: "restart"; startAt?: number } | { type: "continue" },
 ): void {
-  const context = getStoryMutationContext(runtime);
+  if (
+    emitSuggestingUnsupportedMutation(
+      runtime,
+      operation.type === "restart" ? "restartNumbering" : "continueNumbering",
+    )
+  ) {
+    return;
+  }
+  const context = getStoryMutationContext(
+    runtime,
+    operation.type === "restart" ? "restartNumbering" : "continueNumbering",
+  );
   if (!context) {
     return;
   }
@@ -1916,7 +2059,10 @@ function applyRuntimeInsertSectionBreak(
   if (!canApplyRuntimeMutation(snapshot) || snapshot.activeStory.kind !== "main") {
     return;
   }
-  if (snapshot.documentMode === "suggesting") {
+  if (emitWorkflowBlockedMutation(runtime, "insertSectionBreak")) {
+    return;
+  }
+  if (isSelectionSuggesting(runtime)) {
     runtime.emitBlockedCommand("insertSectionBreak", [{
       code: "unsupported_surface",
       message: "Section break insertion is not supported in suggesting mode.",
@@ -1952,6 +2098,56 @@ function applyRuntimeInsertSectionBreak(
   );
 }
 
+function emitSuggestingUnsupportedMutation(
+  runtime: WordReviewEditorRuntime,
+  command: string,
+): boolean {
+  if (!isSelectionSuggesting(runtime)) {
+    return false;
+  }
+
+  runtime.emitBlockedCommand(command, [{
+    code: "suggesting_unsupported",
+    message: `"${command}" is not supported in suggesting mode.`,
+  }]);
+  return true;
+}
+
+function isSelectionSuggesting(runtime: WordReviewEditorRuntime): boolean {
+  return runtime.getInteractionGuardSnapshot().effectiveMode === "suggest";
+}
+
+function getFormattingOperationCommandName(
+  operation:
+    | { type: "toggle"; mark: "bold" | "italic" | "underline" | "strikethrough" | "superscript" | "subscript" }
+    | { type: "set-font-family"; fontFamily: string | null }
+    | { type: "set-font-size"; size: number | null }
+    | { type: "set-text-color"; color: string | null }
+    | { type: "set-highlight-color"; color: string | null }
+    | { type: "set-alignment"; alignment: FormattingAlignment }
+    | { type: "indent" }
+    | { type: "outdent" },
+): string {
+  switch (operation.type) {
+    case "toggle":
+      return `toggle${operation.mark.charAt(0).toUpperCase()}${operation.mark.slice(1)}`;
+    case "set-font-family":
+      return "setFontFamily";
+    case "set-font-size":
+      return "setFontSize";
+    case "set-text-color":
+      return "setTextColor";
+    case "set-highlight-color":
+      return "setHighlightColor";
+    case "set-alignment":
+      return "setAlignment";
+    case "indent":
+      return "indent";
+    case "outdent":
+      return "outdent";
+  }
+}
+
 function applyRuntimeDeleteSectionBreak(
   runtime: WordReviewEditorRuntime,
   sectionIndex: number,
@@ -1960,6 +2156,16 @@ function applyRuntimeDeleteSectionBreak(
   if (!canApplyRuntimeMutation(snapshot) || snapshot.activeStory.kind !== "main") {
     return;
   }
+  if (emitWorkflowBlockedMutation(runtime, "deleteSectionBreak")) {
+    return;
+  }
+  if (isSelectionSuggesting(runtime)) {
+    runtime.emitBlockedCommand("deleteSectionBreak", [{
+      code: "unsupported_surface",
+      message: "Section break deletion is not supported in suggesting mode.",
+    }]);
+    return;
+  }
 
   const sessionState = runtime.getSessionState();
   const timestamp = new Date().toISOString();
@@ -1989,6 +2195,16 @@ function applyRuntimeUpdateSectionLayout(
   if (!canApplyRuntimeMutation(snapshot) || snapshot.activeStory.kind !== "main") {
     return;
   }
+  if (emitWorkflowBlockedMutation(runtime, "updateSectionLayout")) {
+    return;
+  }
+  if (isSelectionSuggesting(runtime)) {
+    runtime.emitBlockedCommand("updateSectionLayout", [{
+      code: "unsupported_surface",
+      message: "Section layout updates are not supported in suggesting mode.",
+    }]);
+    return;
+  }
 
   const sessionState = runtime.getSessionState();
   const timestamp = new Date().toISOString();
@@ -2025,6 +2241,16 @@ function applyRuntimeSetSectionPageNumbering(
   if (!canApplyRuntimeMutation(snapshot) || snapshot.activeStory.kind !== "main") {
     return;
   }
+  if (emitWorkflowBlockedMutation(runtime, "setSectionPageNumbering")) {
+    return;
+  }
+  if (isSelectionSuggesting(runtime)) {
+    runtime.emitBlockedCommand("setSectionPageNumbering", [{
+      code: "unsupported_surface",
+      message: "Section page numbering updates are not supported in suggesting mode.",
+    }]);
+    return;
+  }
 
   const sessionState = runtime.getSessionState();
   const timestamp = new Date().toISOString();
@@ -2072,6 +2298,16 @@ function applyRuntimeSetHeaderFooterLink(
   if (!canApplyRuntimeMutation(snapshot) || snapshot.activeStory.kind !== "main") {
     return;
   }
+  if (emitWorkflowBlockedMutation(runtime, "setHeaderFooterLink")) {
+    return;
+  }
+  if (isSelectionSuggesting(runtime)) {
+    runtime.emitBlockedCommand("setHeaderFooterLink", [{
+      code: "unsupported_surface",
+      message: "Header and footer linkage updates are not supported in suggesting mode.",
+    }]);
+    return;
+  }
 
   const sessionState = runtime.getSessionState();
   const timestamp = new Date().toISOString();
@@ -2094,15 +2330,14 @@ function applyRuntimeSetHeaderFooterLink(
 }
 
 function applyRuntimeInsertPageBreak(runtime: WordReviewEditorRuntime): void {
-  const snapshot = runtime.getRenderSnapshot();
-  if (snapshot.documentMode === "suggesting") {
+  if (isSelectionSuggesting(runtime)) {
     runtime.emitBlockedCommand("insertPageBreak", [{
       code: "unsupported_surface",
       message: "Page break insertion is not supported in suggesting mode.",
     }]);
     return;
   }
-  const context = getStoryMutationContext(runtime);
+  const context = getStoryMutationContext(runtime, "insertPageBreak");
   if (!context) {
     return;
   }
@@ -2119,15 +2354,14 @@ function applyRuntimeInsertTable(
   runtime: WordReviewEditorRuntime,
   options: InsertTableOptions,
 ): void {
-  const snapshot = runtime.getRenderSnapshot();
-  if (snapshot.documentMode === "suggesting") {
+  if (isSelectionSuggesting(runtime)) {
     runtime.emitBlockedCommand("insertTable", [{
       code: "unsupported_surface",
       message: "Table insertion is not supported in suggesting mode.",
     }]);
     return;
   }
-  const context = getStoryMutationContext(runtime);
+  const context = getStoryMutationContext(runtime, "insertTable");
   if (!context) {
     return;
   }
@@ -2145,15 +2379,14 @@ function applyRuntimeInsertImage(
   runtime: WordReviewEditorRuntime,
   options: InsertImageOptions,
 ): void {
-  const snapshot = runtime.getRenderSnapshot();
-  if (snapshot.documentMode === "suggesting") {
+  if (isSelectionSuggesting(runtime)) {
     runtime.emitBlockedCommand("insertImage", [{
       code: "unsupported_surface",
       message: "Image insertion is not supported in suggesting mode.",
     }]);
     return;
   }
-  const context = getStoryMutationContext(runtime);
+  const context = getStoryMutationContext(runtime, "insertImage");
   if (!context) {
     return;
   }
@@ -2191,7 +2424,10 @@ function applyRuntimeImageResize(
   if (!canApplyRuntimeMutation(snapshot)) {
     return;
   }
-  if (snapshot.documentMode === "suggesting") {
+  if (emitWorkflowBlockedMutation(runtime, "setImageLayout")) {
+    return;
+  }
+  if (isSelectionSuggesting(runtime)) {
     runtime.emitBlockedCommand("setImageLayout", [{
       code: "unsupported_surface",
       message: "Image resize is not supported in suggesting mode.",
@@ -2222,15 +2458,17 @@ function applyRuntimeImageReposition(
   mediaId: string,
   offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number },
 ): void {
-  const snapshot = runtime.getRenderSnapshot();
-  if (snapshot.documentMode === "suggesting") {
+  if (emitWorkflowBlockedMutation(runtime, "setImageFrame")) {
+    return;
+  }
+  if (isSelectionSuggesting(runtime)) {
     runtime.emitBlockedCommand("setImageFrame", [{
       code: "unsupported_surface",
       message: "Image reposition is not supported in suggesting mode.",
     }]);
     return;
   }
-  const context = getStoryMutationContext(runtime);
+  const context = getStoryMutationContext(runtime, "setImageFrame");
   if (!context) {
     return;
   }
@@ -2275,15 +2513,14 @@ function applyRuntimeTableStructureOperation(
     | { type: "split-cell" }
     | { type: "set-cell-background"; color: string },
 ): void {
-  const snapshot = runtime.getRenderSnapshot();
-  if (snapshot.documentMode === "suggesting") {
+  if (isSelectionSuggesting(runtime)) {
     runtime.emitBlockedCommand(`table.${operation.type}`, [{
       code: "unsupported_surface",
       message: `Table operation "${operation.type}" is not supported in suggesting mode.`,
     }]);
     return;
   }
-  const context = getStoryMutationContext(runtime);
+  const context = getStoryMutationContext(runtime, `table.${operation.type}`);
   if (!context) {
     return;
   }
@@ -2308,102 +2545,76 @@ function applyRuntimeTextCommand(
     | { type: "insert-hard-break" }
     | { type: "split-paragraph" },
 ): void {
-  const context = getStoryMutationContext(runtime);
+  const snapshot = runtime.getRenderSnapshot();
+  const context = getStoryMutationContext(runtime, getMountedTextCommandName(command));
   if (!context) {
     return;
   }
 
+  const effectiveSelectionMode = runtime.getInteractionGuardSnapshot().effectiveMode;
   const listAwareResult = applyListAwareTextCommand(context, command);
+  if (effectiveSelectionMode === "suggest" && listAwareResult) {
+    runtime.emitBlockedCommand(getMountedTextCommandName(command), [{
+      code: "suggesting_unsupported",
+      message: "List structure changes are not supported in suggesting mode.",
+    }]);
+    return;
+  }
+
   if (listAwareResult) {
     dispatchStoryMutationResult(runtime, context, listAwareResult, context.timestamp);
     return;
   }
 
-  if (context.activeStory.kind === "main") {
-    switch (command.type) {
-      case "insert-text":
-        runtime.dispatch({ type: "text.insert", text: command.text });
-        return;
-      case "delete-backward":
-        runtime.dispatch({ type: "text.delete-backward" });
-        return;
-      case "delete-forward":
-        runtime.dispatch({ type: "text.delete-forward" });
-        return;
-      case "insert-tab":
-        runtime.dispatch({ type: "text.insert-tab" });
-        return;
-      case "outdent-tab":
-        return;
-      case "insert-hard-break":
-        runtime.dispatch({ type: "text.insert-hard-break" });
-        return;
-      case "split-paragraph":
-        runtime.dispatch({ type: "paragraph.split" });
-        return;
-    }
+  switch (command.type) {
+    case "insert-text":
+      runtime.applyActiveStoryTextCommand({ type: "text.insert", text: command.text });
+      return;
+    case "delete-backward":
+      runtime.applyActiveStoryTextCommand({ type: "text.delete-backward" });
+      return;
+    case "delete-forward":
+      runtime.applyActiveStoryTextCommand({ type: "text.delete-forward" });
+      return;
+    case "insert-tab":
+      runtime.applyActiveStoryTextCommand({ type: "text.insert-tab" });
+      return;
+    case "outdent-tab":
+      return;
+    case "insert-hard-break":
+      runtime.applyActiveStoryTextCommand({ type: "text.insert-hard-break" });
+      return;
+    case "split-paragraph":
+      runtime.applyActiveStoryTextCommand({ type: "paragraph.split" });
+      return;
   }
+}
 
-  const selection = toRuntimeSelectionSnapshot(context.localSnapshot.selection);
-  const localResult = (() => {
-    switch (command.type) {
-      case "insert-text":
-        return insertTextInDocument(
-          context.localDocument,
-          selection,
-          command.text,
-          { timestamp: context.timestamp },
-        );
-      case "delete-backward":
-        return deleteSelectionOrBackward(
-          context.localDocument,
-          selection,
-          { timestamp: context.timestamp },
-        );
-      case "delete-forward":
-        return deleteSelectionOrForward(
-          context.localDocument,
-          selection,
-          { timestamp: context.timestamp },
-        );
-      case "insert-tab":
-        return insertTabInDocument(
-          context.localDocument,
-          selection,
-          { timestamp: context.timestamp },
-        );
-      case "outdent-tab":
-        return {
-          changed: false,
-          document: context.localDocument,
-          selection,
-        };
-      case "insert-hard-break":
-        return insertHardBreakInDocument(
-          context.localDocument,
-          selection,
-          { timestamp: context.timestamp },
-        );
-      case "split-paragraph":
-        return splitParagraphInDocument(
-          context.localDocument,
-          selection,
-          { timestamp: context.timestamp },
-        );
-    }
-  })();
-
-  dispatchStoryMutationResult(
-    runtime,
-    context,
-    {
-      changed: "changed" in localResult ? localResult.changed : true,
-      document: localResult.document,
-      selection: localResult.selection,
-      mapping: "mapping" in localResult ? localResult.mapping : undefined,
-    },
-    context.timestamp,
-  );
+function getMountedTextCommandName(
+  command:
+    | { type: "insert-text"; text: string }
+    | { type: "delete-backward" }
+    | { type: "delete-forward" }
+    | { type: "insert-tab" }
+    | { type: "outdent-tab" }
+    | { type: "insert-hard-break" }
+    | { type: "split-paragraph" },
+): string {
+  switch (command.type) {
+    case "insert-text":
+      return "text.insert";
+    case "delete-backward":
+      return "text.delete-backward";
+    case "delete-forward":
+      return "text.delete-forward";
+    case "insert-tab":
+    case "outdent-tab":
+      return "text.insert-tab";
+    case "insert-hard-break":
+      return "text.insert-hard-break";
+    case "split-paragraph":
+      return "paragraph.split";
+  }
 }
 
 function applyListAwareTextCommand(
@@ -2598,8 +2809,21 @@ function canApplyRuntimeMutation(snapshot: RuntimeRenderSnapshot): boolean {
   return snapshot.isReady && !snapshot.readOnly && !snapshot.fatalError;
 }
 
+function emitWorkflowBlockedMutation(
+  runtime: WordReviewEditorRuntime,
+  command: string,
+): boolean {
+  const interactionGuardSnapshot = runtime.getInteractionGuardSnapshot();
+  if (interactionGuardSnapshot.blockedReasons.length === 0) {
+    return false;
+  }
+  runtime.emitBlockedCommand(command, interactionGuardSnapshot.blockedReasons);
+  return true;
+}
+
 function getStoryMutationContext(
   runtime: WordReviewEditorRuntime,
+  command?: string,
 ): {
   timestamp: string;
   activeStory: EditorStoryTarget;
@@ -2611,6 +2835,9 @@ function getStoryMutationContext(
   if (!canApplyRuntimeMutation(snapshot)) {
     return null;
   }
+  if (command && emitWorkflowBlockedMutation(runtime, command)) {
+    return null;
+  }
 
   const persistedDocument = runtime.getSessionState().canonicalDocument;
   const activeStory = snapshot.activeStory;
@@ -3034,6 +3261,20 @@ function deriveEditorViewMode(
   return reviewMode === "editing" ? "editing" : "review";
 }
 
+function resolveWordReviewEditorChromeVisibility(
+  chromeVisibility: WordReviewEditorProps["chromeVisibility"],
+  showReviewPanel: boolean,
+): Partial<WordReviewEditorChromeVisibility> {
+  const legacyVisibility =
+    showReviewPanel
+      ? {}
+      : { reviewRail: false } satisfies Partial<WordReviewEditorChromeVisibility>;
+  return {
+    ...legacyVisibility,
+    ...chromeVisibility,
+  };
+}
+
 function toRuntimeSelectionSnapshot(selection: PublicSelectionSnapshot) {
   return {
     anchor: selection.anchor,
@@ -3057,6 +3298,7 @@ function toRuntimeSelectionSnapshot(selection: PublicSelectionSnapshot) {
 
 function createSelectionFromAnchor(
   anchor: PublicSelectionSnapshot["activeRange"],
+  storyTarget?: EditorStoryTarget,
 ): PublicSelectionSnapshot {
   switch (anchor.kind) {
     case "range":
@@ -3065,6 +3307,7 @@ function createSelectionFromAnchor(
         head: anchor.to,
         isCollapsed: anchor.from === anchor.to,
         activeRange: anchor,
+        ...(storyTarget ? { storyTarget } : {}),
       };
     case "node":
       return {
@@ -3072,6 +3315,7 @@ function createSelectionFromAnchor(
         head: anchor.at,
         isCollapsed: true,
         activeRange: anchor,
+        ...(storyTarget ? { storyTarget } : {}),
       };
     case "detached":
       return {
@@ -3079,6 +3323,7 @@ function createSelectionFromAnchor(
         head: anchor.lastKnownRange.to,
         isCollapsed: anchor.lastKnownRange.from === anchor.lastKnownRange.to,
         activeRange: anchor,
+        ...(storyTarget ? { storyTarget } : {}),
       };
   }
 }
@@ -3184,7 +3429,13 @@ function interactionGuardSnapshotsEqual(
   if (left === right) {
     return true;
   }
-  return workflowBlockedReasonsEqual(left.blockedReasons, right.blockedReasons);
+  return (
+    left.effectiveMode === right.effectiveMode &&
+    left.matchedScopeId === right.matchedScopeId &&
+    left.matchedScopeMode === right.matchedScopeMode &&
+    left.disabledReason === right.disabledReason &&
+    workflowBlockedReasonsEqual(left.blockedReasons, right.blockedReasons)
+  );
 }
 
 function workflowBlockedReasonsEqual(
@@ -3256,7 +3507,14 @@ function editorAnchorProjectionEqual(
 function createSelectionToolbarSelectionKey(
   selection: RuntimeRenderSnapshot["selection"],
   activeStory: EditorStoryTarget,
+  activeRevisionId?: string,
 ): string | null {
+  if (activeRevisionId) {
+    return JSON.stringify({
+      story: activeStory,
+      revisionId: activeRevisionId,
+    });
+  }
   if (selection.isCollapsed || selection.activeRange.kind !== "range") {
     return null;
   }
@@ -3275,6 +3533,8 @@ function buildSelectionToolbarModel(args: {
   documentNavigation: ReturnType<WordReviewEditorRuntime["getDocumentNavigationSnapshot"]>;
   styleCatalog: StyleCatalogSnapshot;
   formattingState: FormattingStateSnapshot;
+  workflowScopeSnapshot?: WorkflowScopeSnapshot | null;
+  interactionGuardSnapshot?: InteractionGuardSnapshot;
   addCommentDisabledReason?: string;
 }): SelectionToolbarModel | null {
   const {
@@ -3284,6 +3544,8 @@ function buildSelectionToolbarModel(args: {
     documentNavigation,
     styleCatalog,
     formattingState,
+    workflowScopeSnapshot,
+    interactionGuardSnapshot,
     addCommentDisabledReason,
   } = args;
 
@@ -3304,6 +3566,14 @@ function buildSelectionToolbarModel(args: {
 
   const badges = [
     createSelectionToolbarStoryBadge(viewState.activeStory),
+    createSelectionToolbarWorkflowBadge(
+      resolveSelectionWorkflowPosture(
+        snapshot,
+        viewState,
+        workflowScopeSnapshot,
+        interactionGuardSnapshot,
+      ),
+    ),
     viewState.workspaceMode === "page" && documentNavigation.pageCount > 0
       ? { label: `Page ${documentNavigation.activePageIndex + 1}` as const }
       : null,
@@ -3311,15 +3581,137 @@ function buildSelectionToolbarModel(args: {
     createSelectionToolbarListBadge(viewState),
   ].filter((badge): badge is SelectionToolbarModel["badges"][number] => Boolean(badge));
 
+  const workflowPosture = resolveSelectionWorkflowPosture(
+    snapshot,
+    viewState,
+    workflowScopeSnapshot,
+    interactionGuardSnapshot,
+  );
+  const canToggleFormatting = workflowPosture.mode === "edit";
+  const canAddComment = workflowPosture.mode === "view" || workflowPosture.mode === "blocked"
+    ? false
+    : capabilities.canAddComment;
+  const disabledReason =
+    workflowPosture.disabledReason ??
+    (canAddComment ? undefined : addCommentDisabledReason);
+
   return {
     previewText,
     badges,
-    canToggleFormatting: true,
+    canToggleFormatting,
     boldActive: formattingState.bold,
     italicActive: formattingState.italic,
     underlineActive: formattingState.underline,
-    canAddComment: capabilities.canAddComment,
-    ...(addCommentDisabledReason ? { disabledReason: addCommentDisabledReason } : {}),
+    canAddComment,
+    ...(disabledReason ? { disabledReason } : {}),
+  };
+}
+
+function buildSuggestionCardModel(args: {
+  snapshot: RuntimeRenderSnapshot;
+  viewState: ReturnType<WordReviewEditorRuntime["getViewState"]>;
+  capabilities: ReturnType<typeof deriveCapabilities>;
+  workflowScopeSnapshot?: WorkflowScopeSnapshot | null;
+  interactionGuardSnapshot?: InteractionGuardSnapshot;
+  activeRevisionId?: string;
+  suppressedSuggestionRevisionId?: string | null;
+  addCommentDisabledReason?: string;
+}): SuggestionCardModel | null {
+  const {
+    snapshot,
+    viewState,
+    capabilities,
+    workflowScopeSnapshot,
+    interactionGuardSnapshot,
+    activeRevisionId,
+    suppressedSuggestionRevisionId,
+    addCommentDisabledReason,
+  } = args;
+
+  if (
+    !snapshot.surface ||
+    !capabilities.canEdit ||
+    viewState.viewMode === "view"
+  ) {
+    return null;
+  }
+
+  const activeRange =
+    !snapshot.selection.isCollapsed && snapshot.selection.activeRange.kind === "range"
+      ? snapshot.selection.activeRange
+      : null;
+  const selectionFrom = activeRange
+    ? Math.min(activeRange.from, activeRange.to)
+    : null;
+  const selectionTo = activeRange
+    ? Math.max(activeRange.from, activeRange.to)
+    : null;
+  const candidateRevisions = snapshot.trackedChanges.revisions.filter((revision) =>
+    storyTargetsEqual(revision.storyTarget ?? { kind: "main" }, viewState.activeStory) &&
+    revision.status === "active" &&
+    revision.actionability === "actionable" &&
+    revision.anchor.kind === "range" &&
+    (
+      activeRevisionId === revision.revisionId ||
+      (
+        selectionFrom !== null &&
+        selectionTo !== null &&
+        rangesOverlap(
+          selectionFrom,
+          selectionTo,
+          revision.anchor.from,
+          revision.anchor.to,
+        )
+      )
+    )
+  );
+  const focusedRevision = (
+    activeRevisionId
+      ? candidateRevisions.find((revision) => revision.revisionId === activeRevisionId)
+      : null
+  ) ?? candidateRevisions[0];
+
+  if (!focusedRevision || focusedRevision.revisionId === suppressedSuggestionRevisionId) {
+    return null;
+  }
+
+  const badges = [
+    createSelectionToolbarStoryBadge(viewState.activeStory),
+    workflowScopeSnapshot?.activeWorkItem?.title
+      ? {
+          label: workflowScopeSnapshot.activeWorkItem.title,
+          tone: "accent" as const,
+        }
+      : null,
+  ].filter((badge): badge is SuggestionCardModel["badges"][number] => Boolean(badge));
+  const workflowPosture = resolveSelectionWorkflowPosture(
+    snapshot,
+    viewState,
+    workflowScopeSnapshot,
+    interactionGuardSnapshot,
+  );
+  const canReviewSuggestion = workflowPosture.mode === "edit" || workflowPosture.mode === "suggest";
+  const canAddComment = workflowPosture.mode === "view" || workflowPosture.mode === "blocked"
+    ? false
+    : capabilities.canAddComment;
+  const disabledReason =
+    workflowPosture.disabledReason ??
+    (canAddComment ? undefined : addCommentDisabledReason);
+
+  return {
+    revisionId: focusedRevision.revisionId,
+    kindLabel: getSuggestionKindLabel(focusedRevision.kind),
+    previewText:
+      focusedRevision.excerpt ??
+      focusedRevision.detail ??
+      focusedRevision.label ??
+      "Suggested change",
+    badges,
+    canAccept: canReviewSuggestion && capabilities.canAcceptChange && focusedRevision.canAccept,
+    canReject: canReviewSuggestion && capabilities.canRejectChange && focusedRevision.canReject,
+    canEditSuggestion: canReviewSuggestion,
+    canAddComment,
+    ...(disabledReason ? { disabledReason } : {}),
   };
 }
 
@@ -3377,6 +3769,149 @@ function createSelectionToolbarListBadge(
   };
 }
 
+function createSelectionToolbarWorkflowBadge(
+  posture: ReturnType<typeof resolveSelectionWorkflowPosture>,
+): SelectionToolbarModel["badges"][number] | null {
+  switch (posture.mode) {
+    case "suggest":
+      return { label: "Suggest", tone: "accent" };
+    case "comment":
+      return { label: "Comment only", tone: "accent" };
+    case "view":
+      return { label: "View only" };
+    case "blocked":
+      return { label: "Blocked" };
+    default:
+      return null;
+  }
+}
+
+function resolveSelectionWorkflowPosture(
+  snapshot: RuntimeRenderSnapshot,
+  viewState: ReturnType<WordReviewEditorRuntime["getViewState"]>,
+  workflowScopeSnapshot?: WorkflowScopeSnapshot | null,
+  interactionGuardSnapshot?: InteractionGuardSnapshot,
+): {
+  mode: "edit" | "suggest" | "comment" | "view" | "blocked";
+  disabledReason?: string;
+} {
+  const blockedReasons =
+    interactionGuardSnapshot?.blockedReasons ??
+    workflowScopeSnapshot?.blockedReasons ??
+    [];
+  const blockingReason = blockedReasons[0];
+  if (blockingReason) {
+    if (blockingReason.code === "workflow_comment_only") {
+      return {
+        mode: "comment",
+        disabledReason: blockingReason.message,
+      };
+    }
+    if (blockingReason.code === "workflow_view_only") {
+      return {
+        mode: "view",
+        disabledReason: blockingReason.message,
+      };
+    }
+    return {
+      mode: "blocked",
+      disabledReason: blockingReason.message,
+    };
+  }
+
+  if (interactionGuardSnapshot) {
+    if (interactionGuardSnapshot.effectiveMode === "suggest") {
+      return {
+        mode: "suggest",
+        disabledReason:
+          interactionGuardSnapshot.disabledReason ??
+          "Suggestion authoring is active here; direct formatting changes are blocked.",
+      };
+    }
+    if (interactionGuardSnapshot.effectiveMode === "comment") {
+      return {
+        mode: "comment",
+        disabledReason: interactionGuardSnapshot.disabledReason,
+      };
+    }
+    if (interactionGuardSnapshot.effectiveMode === "view") {
+      return {
+        mode: "view",
+        disabledReason: interactionGuardSnapshot.disabledReason,
+      };
+    }
+    if (interactionGuardSnapshot.effectiveMode === "blocked") {
+      return {
+        mode: "blocked",
+        disabledReason: interactionGuardSnapshot.disabledReason,
+      };
+    }
+  }
+
+  const activeRange =
+    !snapshot.selection.isCollapsed && snapshot.selection.activeRange.kind === "range"
+      ? snapshot.selection.activeRange
+      : null;
+  const matchingScope = activeRange && workflowScopeSnapshot
+    ? workflowScopeSnapshot.scopes.find((scope) => {
+        const scopeStoryTarget = scope.storyTarget ?? { kind: "main" as const };
+        if (!storyTargetsEqual(scopeStoryTarget, viewState.activeStory)) {
+          return false;
+        }
+        if (scope.anchor.kind === "detached") {
+          return false;
+        }
+        const scopeFrom = scope.anchor.kind === "range" ? scope.anchor.from : scope.anchor.at;
+        const scopeTo = scope.anchor.kind === "range" ? scope.anchor.to : scope.anchor.at;
+        return activeRange.from >= scopeFrom && activeRange.to <= scopeTo;
+      })
+    : null;
+
+  if (matchingScope?.mode === "suggest") {
+    return {
+      mode: "suggest",
+      disabledReason: "Suggestion authoring is active here; direct formatting changes are blocked.",
+    };
+  }
+  if (matchingScope?.mode === "comment") {
+    return {
+      mode: "comment",
+      disabledReason: `Scope "${matchingScope.label ?? matchingScope.scopeId}" allows comments only.`,
+    };
+  }
+  if (matchingScope?.mode === "view") {
+    return {
+      mode: "view",
+      disabledReason: `Scope "${matchingScope.label ?? matchingScope.scopeId}" is view-only.`,
+    };
+  }
+  return { mode: "edit" };
+}
+
+function rangesOverlap(
+  leftFrom: number,
+  leftTo: number,
+  rightFrom: number,
+  rightTo: number,
+): boolean {
+  return leftFrom < rightTo && rightFrom < leftTo;
+}
+
+function getSuggestionKindLabel(kind: TrackedChangeEntrySnapshot["kind"]): string {
+  switch (kind) {
+    case "insertion":
+      return "Suggested insertion";
+    case "deletion":
+      return "Suggested deletion";
+    case "formatting":
+      return "Suggested formatting change";
+    case "property-change":
+      return "Suggested property change";
+    case "move":
+      return "Suggested move";
+  }
+}
+
 function buildActiveImageContext(args: {
   canonicalDocument: PersistedEditorSnapshot["canonicalDocument"];
   selection: RuntimeRenderSnapshot["selection"];