@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/runtime/document-runtime.ts

@@ -16,6 +16,8 @@ import type {
   AddCommentParams,
   AddCommentReplyResult,
   AddCommentResult,
+  AddScopeParams,
+  AddScopeResult,
   CommentSidebarSnapshot,
   CommentSidebarThreadSnapshot,
   CompatibilityReport,
@@ -28,6 +30,7 @@ import type {
   DocumentTextToken,
   EditorSessionState,
   EditorAnchorProjection,
+  TextFormattingDirective,
   EditorError,
   EditorStoryTarget,
   EditorViewStateSnapshot,
@@ -74,6 +77,7 @@ import type {
   WorkflowMetadataSnapshot,
   WorkflowMarkupSnapshot,
   WorkflowOverlay,
+  WorkflowScope,
   WorkflowScopeSnapshot,
   WorkspaceMode,
   WordReviewEditorEvent,
@@ -101,7 +105,14 @@ import {
   storyTargetsEqual,
   type EditorAnchorProjection as InternalEditorAnchorProjection,
 } from "../core/selection/mapping.ts";
-import { canCreateDocxCommentAnchor } from "../core/selection/review-anchors.ts";
+import {
+  toInternalAnchorProjection,
+  toPublicAnchorProjection,
+} from "../core/selection/anchor-conversion.ts";
+import {
+  commentAnchorRejectionReason,
+  snapCommentAnchorAwayFromTable,
+} from "../core/selection/review-anchors.ts";
 import { buildBookmarkNameMap } from "../legal/bookmarks.ts";
 import {
   describeOpaqueFragment,
@@ -116,6 +127,11 @@ import {
 } from "../review/store/revision-store.ts";
 import { createSuggestionsSnapshot } from "./suggestions-snapshot.ts";
 import { validateSelectionAgainstDocument } from "./selection/post-edit-validator.ts";
+import { resolveScope } from "./scope-resolver.ts";
+import {
+  insertScopeMarkers,
+  removeScopeMarkers,
+} from "../core/commands/add-scope.ts";
 import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
 import { mergeCompatibilityReports } from "../validation/compatibility-report.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
@@ -224,6 +240,7 @@ import type {
 } from "../api/editor-state-types.ts";
 import { collectEditorStateForSerialize } from "./editor-state-integration.ts";
 import type { EditorStatePayload } from "../io/ooxml/workflow-payload.ts";
+import type { SharedWorkflowState } from "./collab/workflow-shared.ts";
 
 /** Internal extension of ExportDocxOptions that threads the collected
  *  editorState payload from the runtime to the docx serializer. */
@@ -257,7 +274,7 @@ export interface DocumentRuntime {
   getRenderSnapshot(): RuntimeRenderSnapshot;
   getCanonicalDocument(): CanonicalDocumentEnvelope;
   getSourcePackage(): EditorSessionState["sourcePackage"] | undefined;
-  replaceText(text: string, target?: EditorAnchorProjection): void;
+  replaceText(text: string, target?: EditorAnchorProjection, formatting?: TextFormattingDirective): void;
   applyActiveStoryTextCommand(command: ActiveStoryTextCommand): TextCommandAck;
   dispatch(command: EditorCommand): void;
   /**
@@ -291,6 +308,9 @@ export interface DocumentRuntime {
   reopenComment(commentId: string): void;
   addCommentReply(commentId: string, body: string, authorId?: string): AddCommentReplyResult;
   editCommentBody(commentId: string, body: string): void;
+  addScope(params: AddScopeParams): AddScopeResult;
+  getScope(scopeId: string): WorkflowScope | null;
+  removeScope(scopeId: string): void;
   acceptChange(changeId: string): void;
   rejectChange(changeId: string): void;
   acceptAllChanges(): void;
@@ -348,6 +368,7 @@ export interface DocumentRuntime {
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
   getWorkflowOverlay(): WorkflowOverlay | null;
+  setSharedWorkflowState(state: SharedWorkflowState | null): void;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
@@ -618,6 +639,9 @@ export function createDocumentRuntime(
     ?? options.initialSnapshot?.workflowMetadata?.entries
     ?? [];
   let hostAnnotationOverlay: HostAnnotationOverlay | null = null;
+  // P13 Slice B: shared workflow state from the collab Y.Map "workflow".
+  // Set via setSharedWorkflowState(); observed by evaluateWorkflowBlockedReasons.
+  let sharedWorkflowState: SharedWorkflowState | null = null;
   const initialPersistedSnapshot = options.initialSessionState
     ? persistedSnapshotFromEditorSessionState(options.initialSessionState, {
         savedAt: options.initialSessionState.updatedAt,
@@ -862,6 +886,7 @@ export function createDocumentRuntime(
         documentMode: DocumentMode;
         protectionSnapshot: ProtectionSnapshot;
         workflowOverlay: WorkflowOverlay | null;
+        sharedWorkflowState: SharedWorkflowState | null;
         snapshot: InteractionGuardSnapshot;
       }
     | undefined;
@@ -1129,6 +1154,29 @@ export function createDocumentRuntime(
     commandType?: string,
   ): WorkflowBlockedCommandReason[] {
     const reasons: WorkflowBlockedCommandReason[] = [];
+    // P13 Slice B: shared lockedMode overrides all other scope checks when
+    // non-editing. Short-circuit: no other scope reason applies when the round
+    // is locked (the round state supersedes scope/overlay-level gating).
+    // Emit a reason code whose effectiveMode mapping matches the mode intent:
+    //   "commenting" → workflow_comment_only (maps to effectiveMode: "comment")
+    //   "viewing"    → workflow_view_only    (maps to effectiveMode: "view")
+    //   "suggesting" → workflow_round_locked (no existing mapping; stays "blocked"
+    //                   for this slice — full suggesting-mode semantics will be a
+    //                   future slice that hooks getEffectiveDocumentMode instead).
+    if (sharedWorkflowState?.lockedMode && sharedWorkflowState.lockedMode !== "editing") {
+      const lockedMode = sharedWorkflowState.lockedMode;
+      const code: WorkflowBlockedCommandReason["code"] =
+        lockedMode === "commenting"
+          ? "workflow_comment_only"
+          : lockedMode === "viewing"
+            ? "workflow_view_only"
+            : "workflow_round_locked";
+      reasons.push({
+        code,
+        message: `Round is locked to ${lockedMode} mode.`,
+      });
+      return reasons;
+    }
     const selectionBounds = {
       from: Math.min(selection.anchor, selection.head),
       to: Math.max(selection.anchor, selection.head),
@@ -1541,7 +1589,8 @@ export function createDocumentRuntime(
       cachedInteractionGuardSnapshot.readOnly === state.readOnly &&
       cachedInteractionGuardSnapshot.documentMode === viewState.documentMode &&
       cachedInteractionGuardSnapshot.protectionSnapshot === protectionSnapshot &&
-      cachedInteractionGuardSnapshot.workflowOverlay === workflowOverlay
+      cachedInteractionGuardSnapshot.workflowOverlay === workflowOverlay &&
+      cachedInteractionGuardSnapshot.sharedWorkflowState === sharedWorkflowState
     ) {
       return cachedInteractionGuardSnapshot.snapshot;
     }
@@ -1602,6 +1651,7 @@ export function createDocumentRuntime(
       documentMode: viewState.documentMode,
       protectionSnapshot,
       workflowOverlay,
+      sharedWorkflowState,
       snapshot,
     };
     return snapshot;
@@ -2035,6 +2085,16 @@ export function createDocumentRuntime(
     }
   });
 
+  // R5 scratch snapshot: single pre-allocated object reused for every
+  // `applyRemoteCommand(cmd, ctx, meta)` call with a `meta.preSelection`
+  // override. Avoids the per-remote-command `{ ...cachedRenderSnapshot }`
+  // + `{ ...state }` allocations that CLAUDE.md rule 4 warns against.
+  // Mutated in place below — callers MUST NOT hold references to it
+  // across dispatches; `executeEditorCommand` + `commitRemote` consume
+  // synchronously within `applyRemoteCommand`, so this is safe today.
+  const r5ScratchReplayState: typeof state = { ...state };
+  const r5ScratchReplaySnapshot: typeof cachedRenderSnapshot = { ...cachedRenderSnapshot };
+
   return {
     subscribe(listener) {
       listeners.add(listener);
@@ -2147,28 +2207,56 @@ export function createDocumentRuntime(
           applyRuntimeStateOverlayCommand(command);
           return;
         }
-        if (meta?.activeStory && !storyTargetsEqual(meta.activeStory, activeStory)) {
-          activeStory = meta.activeStory;
-          storySelections.set(
-            storyTargetKey(activeStory),
-            meta.preSelection ?? state.selection,
-          );
+        // Story-target isolation: the remote's `meta.activeStory` scopes
+        // the replay (so the command lands in the intended region of the
+        // shared document), but must NEVER overwrite the local user's
+        // closure-level `activeStory`. Before P11 this assignment stole
+        // focus every time a remote event arrived for a different story —
+        // a local user authoring in a header would get yanked into the
+        // main body as soon as a peer edited main.
+        const replayStory = meta?.activeStory ?? activeStory;
+        const crossStoryReplay = Boolean(
+          meta?.activeStory && !storyTargetsEqual(meta.activeStory, activeStory),
+        );
+        let replayState: typeof state;
+        let replaySnapshot: typeof cachedRenderSnapshot;
+        if (meta?.preSelection) {
+          // Refresh scratch with current `state` / `cachedRenderSnapshot` (both
+          // mutate on every commit), then override only the selection fields.
+          Object.assign(r5ScratchReplayState, state);
+          r5ScratchReplayState.selection = meta.preSelection;
+          Object.assign(r5ScratchReplaySnapshot, cachedRenderSnapshot);
+          r5ScratchReplaySnapshot.selection = toPublicSelectionSnapshot(meta.preSelection, replayStory);
+          replayState = r5ScratchReplayState;
+          replaySnapshot = r5ScratchReplaySnapshot;
+        } else {
+          replayState = state;
+          replaySnapshot = cachedRenderSnapshot;
         }
-        const replayState = meta?.preSelection
-          ? { ...state, selection: meta.preSelection }
-          : state;
-        const replaySnapshot = meta?.preSelection
-          ? {
-              ...cachedRenderSnapshot,
-              selection: toPublicSelectionSnapshot(meta.preSelection, activeStory),
-            }
-          : cachedRenderSnapshot;
         const replayContext = {
           ...context,
           renderSnapshot: replaySnapshot,
         };
         const transaction = executeEditorCommand(replayState, command, replayContext);
-        commitRemote(transaction);
+        if (crossStoryReplay) {
+          // Cross-story replay: the transaction's resulting selection is
+          // in the remote story's region. Don't leak that into local
+          // `state.selection` — preserve the pre-replay local selection
+          // so the local caret stays where the user is focused. The
+          // document delta still applies; only the selection is filtered.
+          // Full position-mapping of the local cursor through the remote
+          // edit is a separate P11 sub-bullet (Awareness cursor transaction
+          // mapping).
+          commitRemote({
+            ...transaction,
+            nextState: {
+              ...transaction.nextState,
+              selection: state.selection,
+            },
+          });
+        } else {
+          commitRemote(transaction);
+        }
       } catch (error) {
         emitError(toRuntimeError(error));
       }
@@ -2207,13 +2295,14 @@ export function createDocumentRuntime(
     getDefaultAuthorId() {
       return defaultAuthorId;
     },
-    replaceText(text, target) {
+    replaceText(text, target, formatting) {
       try {
         const timestamp = clock();
         applyTextCommandInActiveStory(
           {
             type: "text.insert",
             text,
+            ...(formatting ? { formatting } : {}),
             origin: createOrigin("api", timestamp),
           },
           {
@@ -2260,22 +2349,39 @@ export function createDocumentRuntime(
         throw toStructuredRuntimeException(error);
       }
       const commentId = createEntityId("comment", state.document.review.comments, clock());
-      const anchor = params.anchor
+      let anchor = params.anchor
         ? toInternalAnchorProjection(params.anchor)
         : state.selection.activeRange;
-      const selection = params.anchor
+      let selection = params.anchor
         ? createSelectionFromPublicAnchor(params.anchor)
         : state.selection;
-      if (!canCreateDocxCommentAnchor(cachedRenderSnapshot.surface, anchor)) {
+      if (params.snapToSafeBoundary === true) {
+        const snapped = snapCommentAnchorAwayFromTable(
+          cachedRenderSnapshot.surface,
+          anchor,
+        );
+        if (snapped !== null && snapped !== anchor) {
+          anchor = snapped;
+          selection = createSelectionFromPublicAnchor(toPublicAnchorProjection(snapped));
+        }
+      }
+      const rejectionReason = commentAnchorRejectionReason(
+        cachedRenderSnapshot.surface,
+        anchor,
+      );
+      if (rejectionReason !== null) {
+        const message =
+          rejectionReason === "comment_anchor_table_adjacent"
+            ? "DOCX comments cannot currently anchor mid-run within a paragraph adjacent to a table boundary — snap the range to a paragraph or word boundary and retry."
+            : "DOCX comments must use a non-empty range that stays within a single story and does not cross table or opaque-fragment boundaries.";
         const error: InternalEditorError = {
           errorId: createSessionId("comment-anchor", clock()),
           code: "validation_failed",
           isFatal: false,
-          message:
-            "DOCX comments must use a non-empty range that stays within a single story and does not cross table or opaque-fragment boundaries.",
+          message,
           source: "runtime",
           details: {
-            reason: "invalid_comment_anchor",
+            reason: rejectionReason,
           },
         };
         emitError(error);
@@ -2362,6 +2468,155 @@ export function createDocumentRuntime(
         origin: createOrigin("api", clock()),
       });
     },
+    addScope(params): AddScopeResult {
+      const scopeId =
+        params.scopeId ??
+        `scope-${clock().replace(/[^0-9]/gu, "")}-${Math.floor(Math.random() * 1e6)}`;
+      const anchor =
+        params.anchor.kind === "range"
+          ? { from: params.anchor.from, to: params.anchor.to }
+          : null;
+
+      if (!anchor) {
+        return {
+          scopeId,
+          anchor: params.anchor,
+        };
+      }
+
+      const { document: nextDocument } = insertScopeMarkers(state.document, {
+        scopeId,
+        from: anchor.from,
+        to: anchor.to,
+      });
+
+      if (nextDocument !== state.document) {
+        this.dispatch({
+          type: "document.replace",
+          document: nextDocument,
+          origin: createOrigin("api", clock()),
+        });
+      }
+
+      const resolved = resolveScope(state.document, scopeId);
+      const publicAnchor: EditorAnchorProjection =
+        resolved && resolved.kind === "range"
+          ? resolved
+          : {
+              kind: "range",
+              from: anchor.from,
+              to: anchor.to,
+              assoc: { start: -1, end: 1 },
+            };
+
+      const currentOverlay: WorkflowOverlay = workflowOverlay ?? {
+        overlayVersion: "workflow-overlay/1",
+        scopes: [],
+      };
+      const existingScopes = currentOverlay.scopes.filter(
+        (existing) => existing.scopeId !== scopeId,
+      );
+      const scope: WorkflowScope = {
+        scopeId,
+        mode: params.mode ?? "comment",
+        anchor: publicAnchor,
+        ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
+        ...(params.label ? { label: params.label } : {}),
+      };
+      this.dispatch({
+        type: "workflow.set-overlay",
+        overlay: {
+          ...currentOverlay,
+          scopes: [...existingScopes, scope],
+        },
+        origin: createOrigin("api", clock()),
+      });
+
+      if (params.persistence && params.persistence !== "runtime-only") {
+        const entry: WorkflowMetadataEntry = {
+          entryId: `scope-metadata-${scopeId}`,
+          metadataId: "workflow.scope",
+          anchor: publicAnchor,
+          scopeId,
+          value:
+            params.persistence === "document-metadata"
+              ? { ...(params.metadata?.value ?? {}), label: params.label }
+              : params.metadata?.value,
+          metadataPersistence:
+            params.persistence === "session" ? "external" : "internal",
+        };
+        this.dispatch({
+          type: "workflow.set-metadata-entries",
+          entries: [...(workflowMetadataEntries ?? []), entry],
+          origin: createOrigin("api", clock()),
+        });
+      }
+
+      return {
+        scopeId,
+        anchor: publicAnchor,
+      };
+    },
+    getScope(scopeId) {
+      const resolved = resolveScope(state.document, scopeId);
+      if (!resolved) {
+        const stored = workflowOverlay?.scopes.find((s) => s.scopeId === scopeId);
+        return stored ?? null;
+      }
+      const stored = workflowOverlay?.scopes.find((s) => s.scopeId === scopeId);
+      if (!stored) {
+        return {
+          scopeId,
+          mode: "comment",
+          anchor: resolved,
+        };
+      }
+      return {
+        ...stored,
+        anchor: resolved,
+      };
+    },
+    removeScope(scopeId) {
+      // Step 1: drop the scope from the overlay FIRST. If the scope's mode was
+      // "comment" / "view" the workflow-blocked-reasons gate in `dispatch`
+      // would otherwise refuse the subsequent `document.replace` with
+      // `workflow_comment_only` / `workflow_view_only`. Overlay commands are
+      // routed through `applyRuntimeStateOverlayCommand` and bypass that gate.
+      if (workflowOverlay) {
+        const nextScopes = workflowOverlay.scopes.filter(
+          (scope) => scope.scopeId !== scopeId,
+        );
+        if (nextScopes.length !== workflowOverlay.scopes.length) {
+          this.dispatch({
+            type: "workflow.set-overlay",
+            overlay: { ...workflowOverlay, scopes: nextScopes },
+            origin: createOrigin("api", clock()),
+          });
+        }
+      }
+      // Step 2: now that the scope is gone, strip the markers from the doc.
+      const nextDocument = removeScopeMarkers(state.document, scopeId);
+      if (nextDocument !== state.document) {
+        this.dispatch({
+          type: "document.replace",
+          document: nextDocument,
+          origin: createOrigin("api", clock()),
+        });
+      }
+      // Step 3: clear any customXml-persisted metadata entries.
+      if (workflowMetadataEntries) {
+        const nextEntries = workflowMetadataEntries.filter(
+          (entry) => entry.scopeId !== scopeId,
+        );
+        if (nextEntries.length !== workflowMetadataEntries.length) {
+          this.dispatch({
+            type: "workflow.set-metadata-entries",
+            entries: nextEntries,
+            origin: createOrigin("api", clock()),
+          });
+        }
+      }
+    },
     acceptChange(changeId) {
       this.dispatch({
         type: "change.accept",
@@ -2756,6 +3011,13 @@ export function createDocumentRuntime(
     getWorkflowOverlay() {
       return workflowOverlay;
     },
+    setSharedWorkflowState(state) {
+      if (state === sharedWorkflowState) return;
+      sharedWorkflowState = state;
+      // Invalidate guard/scope caches so next derivation reflects the new state.
+      cachedInteractionGuardSnapshot = undefined;
+      cachedWorkflowScopeSnapshot = undefined;
+    },
     getWorkflowScopeSnapshot() {
       return getCachedWorkflowScopeSnapshot();
     },
@@ -3954,45 +4216,6 @@ function toPublicSelectionSnapshot(
   };
 }
 
-function toPublicAnchorProjection(
-  anchor: InternalEditorAnchorProjection,
-): EditorAnchorProjection {
-  switch (anchor.kind) {
-    case "range":
-      return {
-        kind: "range",
-        from: anchor.range.from,
-        to: anchor.range.to,
-        assoc: anchor.assoc,
-      };
-    case "node":
-      return {
-        kind: "node",
-        at: anchor.at,
-        assoc: anchor.assoc,
-      };
-    case "detached":
-      return {
-        kind: "detached",
-        lastKnownRange: anchor.lastKnownRange,
-        reason: anchor.reason,
-      };
-  }
-}
-
-function toInternalAnchorProjection(
-  anchor: EditorAnchorProjection,
-): InternalEditorAnchorProjection {
-  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);
-  }
-}
-
 function createSelectionFromPublicAnchor(
   anchor: EditorAnchorProjection,
 ): import("../core/state/editor-state.ts").SelectionSnapshot {

package/src/runtime/editor-surface/capabilities.ts

@@ -45,7 +45,8 @@ export type CapabilityCategory =
   | "tracked-changes"
   | "comments"
   | "structure"
-  | "system";
+  | "system"
+  | "workflow";
 
 export interface CapabilityShortcut {
   /** Canonical Windows / Linux binding string (e.g. "Ctrl+B", "Shift+Tab"). */
@@ -301,87 +302,99 @@ export const EDITOR_CAPABILITIES: readonly EditorCapability[] = [
     shortcut: { winLinux: "Ctrl+0", mac: "Cmd+0" },
     hostEvent: "onZoomRequested",
   },
-
-  // ---------------------------------------------------------------
-  // Blocked — Word shortcuts the mounted editor does not implement
-  // ---------------------------------------------------------------
   {
-    id: "replaceText",
-    kind: "blocked",
+    id: "shortcut.replace",
+    kind: "host-delegated",
     category: "navigation",
     label: "Find and replace",
     shortcut: { winLinux: "Ctrl+H", mac: "Ctrl+H" },
-    blockReason: {
-      code: UNSUPPORTED_SURFACE,
-      message: "Replace shortcuts are not supported in the mounted editor yet.",
-    },
+    hostEvent: "onReplaceRequested",
   },
   {
-    id: "goTo",
-    kind: "blocked",
+    id: "shortcut.go-to",
+    kind: "host-delegated",
     category: "navigation",
-    label: "Go to",
+    label: "Go to page / bookmark / line",
     shortcut: { winLinux: "Ctrl+G", mac: "Cmd+Option+G" },
-    blockReason: {
-      code: UNSUPPORTED_SURFACE,
-      message: "Go To shortcuts are not supported in the mounted editor yet.",
-    },
-  },
-  {
-    id: "toggleTrackChanges",
-    kind: "blocked",
-    category: "tracked-changes",
-    label: "Toggle track-changes authoring mode",
-    shortcut: { winLinux: "Ctrl+Shift+E", mac: "Cmd+Shift+E" },
-    blockReason: {
-      code: UNSUPPORTED_SURFACE,
-      message: "Track changes authoring shortcuts are not supported in the mounted editor.",
-    },
+    hostEvent: "onGoToRequested",
   },
   {
-    id: "checkSpelling",
-    kind: "blocked",
+    id: "shortcut.spell",
+    kind: "host-delegated",
     category: "system",
     label: "Check spelling",
     shortcut: { winLinux: "F7", mac: "F7" },
-    blockReason: {
-      code: UNSUPPORTED_SURFACE,
-      message: "Spelling shortcuts are not supported in the mounted editor.",
-    },
+    hostEvent: "onSpellRequested",
   },
   {
-    id: "openThesaurus",
-    kind: "blocked",
+    id: "shortcut.thesaurus",
+    kind: "host-delegated",
     category: "system",
     label: "Open thesaurus",
     shortcut: { winLinux: "Shift+F7", mac: "Shift+F7" },
-    blockReason: {
-      code: UNSUPPORTED_SURFACE,
-      message: "Thesaurus shortcuts are not supported in the mounted editor.",
-    },
+    hostEvent: "onThesaurusRequested",
   },
   {
-    id: "extendSelection",
-    kind: "blocked",
+    id: "shortcut.extend-selection",
+    kind: "host-delegated",
     category: "selection",
     label: "Extend-selection mode",
     shortcut: { winLinux: "F8", mac: "F8" },
-    blockReason: {
-      code: UNSUPPORTED_SURFACE,
-      message: "Extend-selection shortcuts are not supported in the mounted editor.",
-    },
+    hostEvent: "onExtendSelectionRequested",
   },
   {
-    id: "lastEdit",
-    kind: "blocked",
+    id: "shortcut.last-edit",
+    kind: "host-delegated",
     category: "navigation",
     label: "Return to last edit",
     shortcut: { winLinux: "Shift+F5", mac: "Shift+F5" },
+    hostEvent: "onLastEditRequested",
+  },
+
+  // ---------------------------------------------------------------
+  // Blocked — Word shortcuts the mounted editor does not implement
+  // ---------------------------------------------------------------
+  {
+    id: "toggleTrackChanges",
+    kind: "blocked",
+    category: "tracked-changes",
+    label: "Toggle track-changes authoring mode",
+    shortcut: { winLinux: "Ctrl+Shift+E", mac: "Cmd+Shift+E" },
     blockReason: {
       code: UNSUPPORTED_SURFACE,
-      message: "Last-edit shortcuts are not supported in the mounted editor.",
+      message: "Track changes authoring shortcuts are not supported in the mounted editor.",
     },
   },
+
+  // ---------------------------------------------------------------
+  // Workflow ref-methods (supported, no shortcut)
+  //
+  // These entries document ref-method API surface that has no
+  // keyboard binding — `WordReviewEditorRef.addScope` / `getScope`
+  // / `removeScope`, shipped as S1. They appear in the capability
+  // table so host integrations can introspect the full contract
+  // without parsing multiple sources. Do not remove the `kind:
+  // "supported"` discipline — they are runtime-owned mutations, not
+  // host-delegated.
+  // ---------------------------------------------------------------
+  {
+    id: "scope.add",
+    kind: "supported",
+    category: "workflow",
+    label: "Attach a workflow scope to a selection or range (ref method)",
+  },
+  {
+    id: "scope.get",
+    kind: "supported",
+    category: "workflow",
+    label: "Resolve a scopeId to a live WorkflowScope with current anchor (ref method)",
+  },
+  {
+    id: "scope.remove",
+    kind: "supported",
+    category: "workflow",
+    label: "Remove a scope's markers + metadata record (ref method)",
+  },
 ];
 
 /**