@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/shell/ref-commands.ts

@@ -0,0 +1,1697 @@
+/**
+ * Shell helper — ref-method command dispatch.
+ *
+ * Extracted from `src/ui/WordReviewEditor.tsx` by refactor/11 Slice 4
+ * (Track A, "ref-bridge carve-out"). Every `applyRuntime*` /
+ * `applySuggesting*` helper these exports correspond to is an
+ * imperative ref-verb dispatch path: it takes the mounted
+ * `WordReviewEditorRuntime`, consults interaction-guard / workflow
+ * state, optionally rewrites the canonical document through a core
+ * command, and dispatches the result via `runtime.dispatch(...)`.
+ *
+ * These helpers have zero React dependencies — they operate on the
+ * runtime handle + public-API request shapes + substrate commands.
+ * They lived in WRE for historical reasons (WRE compiled the
+ * `ref.current` surface inline) and are moved here so WRE is no
+ * longer the single largest `src/ui/**` entry in the Layer 11
+ * boundary register (see
+ * `docs/plans/refactor/11-presentation-surfaces-boundary-exceptions.json`).
+ *
+ * Retirement path: these functions are the component-facing
+ * implementations of the v3 Runtime API mutation verbs. As refactor/07
+ * and refactor/10 ship their respective API façades, each helper
+ * graduates to `src/api/v3/runtime/**` and the shell file loses that
+ * import — the goal is to drop the count here to 0 over time.
+ *
+ * See `docs/architecture/11-presentation-surfaces.md` §8.8 ("mounted
+ * shell allowed to touch substrate") for the layering rationale.
+ */
+
+import type {
+  EditorSessionState,
+  EditorStoryTarget,
+  FormattingAlignment,
+  HeaderFooterLinkPatch,
+  InsertImageOptions,
+  InsertTableOptions,
+  RuntimeRenderSnapshot,
+  SectionBreakType,
+  SectionLayoutPatch,
+  SectionPageNumberingPatch,
+  SelectionSnapshot as PublicSelectionSnapshot,
+  StyleCatalogSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+  TableOp,
+} from "../api/public-types";
+import {
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+  storyTargetsEqual,
+  type TransactionMapping,
+} from "../core/selection/mapping.ts";
+import { applyFormattingOperationToDocument } from "../core/commands/formatting-commands.ts";
+import {
+  applyParagraphStyleToDocument,
+  applyTableStyleToDocument,
+} from "../core/commands/style-commands.ts";
+import {
+  continueNumbering as continueListNumbering,
+  restartNumbering as restartListNumbering,
+  toggleBulletedList,
+  toggleNumberedList,
+} from "../core/commands/list-commands.ts";
+import { type DispatchContext } from "../runtime/edit-dispatch/index.ts";
+import {
+  resolveActiveParagraphIndex,
+  setActiveParagraphIndentation,
+  setActiveParagraphTabStops,
+} from "../core/commands/paragraph-layout-commands.ts";
+import {
+  deleteSectionBreakAtSectionIndex,
+  insertSectionBreakAfterSectionIndex,
+  setHeaderFooterLinkAtSectionIndex,
+  setSectionPageNumberingAtSectionIndex,
+  updateSectionLayoutAtSectionIndex,
+} from "../core/commands/section-layout-commands.ts";
+import {
+  insertImage as insertImageInDocument,
+  resizeImage as resizeImageInCatalog,
+  repositionFloatingImage as repositionFloatingImageInDocument,
+} from "../core/commands/image-commands.ts";
+import {
+  applyTableStructureOperation as applyTableStructureOperationInDocument,
+  type TableStructureOperation,
+} from "../core/commands/table-structure-commands.ts";
+import {
+  insertPageBreak as insertPageBreakInDocument,
+  insertTable as insertTableInDocument,
+} from "../core/commands/text-commands.ts";
+import { type SelectionSnapshot as InternalSelectionSnapshot } from "../core/state/editor-state.ts";
+import {
+  getStoryBlocks,
+  replaceStoryBlocks,
+} from "../runtime/story-targeting.ts";
+import type { TwProseMirrorSurfaceRef } from "../ui-tailwind/editor-surface/tw-prosemirror-surface";
+import type { WordReviewEditorRuntime } from "./session-bootstrap.ts";
+
+// ---------------------------------------------------------------------------
+// Re-exports so WRE (and tests) can thread the operation discriminator
+// through without re-importing substrate.
+// ---------------------------------------------------------------------------
+
+export type { TableStructureOperation };
+
+// ---------------------------------------------------------------------------
+// Suggestion-group fan-out
+// ---------------------------------------------------------------------------
+
+/**
+ * R3 — best-effort suggestion-group accept/reject fan-out. Resolves
+ * the group's suggestions from the current snapshot, then fans out
+ * `acceptChange` / `rejectChange` across every changeId in each
+ * group member. P2 batches these in rapid succession; the runtime
+ * commit boundary collapses them into a single logical transaction.
+ * A future phase adds true atomicity at the runtime level.
+ */
+export function applySuggestionGroupAction(
+  runtime: WordReviewEditorRuntime,
+  groupId: string,
+  action: "accept" | "reject",
+): void {
+  const snapshot = runtime.getSuggestionsSnapshot();
+  const group = snapshot.groups?.find((entry) => entry.groupId === groupId);
+  const op = action === "accept" ? "acceptSuggestionGroup" : "rejectSuggestionGroup";
+  if (!group) {
+    runtime.emitTransientWarning({
+      warningId: `suggestion-group-unknown-${groupId}-${Date.now()}`,
+      code: "review_target_not_found",
+      severity: "info",
+      message: `${op}("${groupId}") skipped: unknown groupId.`,
+      source: "review",
+      details: { op, targetId: groupId, reason: "group_unknown" },
+    });
+    return;
+  }
+  const byId = new Map(
+    snapshot.suggestions.map((entry) => [entry.suggestionId, entry]),
+  );
+  const skippedSuggestions: string[] = [];
+  for (const suggestionId of group.suggestionIds) {
+    const suggestion = byId.get(suggestionId);
+    if (!suggestion) {
+      skippedSuggestions.push(suggestionId);
+      continue;
+    }
+    for (const changeId of suggestion.changeIds) {
+      if (action === "accept") {
+        runtime.acceptChange(changeId);
+      } else {
+        runtime.rejectChange(changeId);
+      }
+    }
+  }
+  if (skippedSuggestions.length > 0) {
+    runtime.emitTransientWarning({
+      warningId: `suggestion-group-stale-${groupId}-${Date.now()}`,
+      code: "review_target_not_found",
+      severity: "info",
+      message: `${op}("${groupId}") partially skipped: ${skippedSuggestions.length} suggestion(s) no longer in snapshot.`,
+      source: "review",
+      details: {
+        op,
+        targetId: groupId,
+        reason: "suggestion_stale",
+        skippedSuggestionIds: skippedSuggestions,
+      },
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Style-catalog projection
+// ---------------------------------------------------------------------------
+
+export function getRuntimeStyleCatalog(
+  input:
+    | WordReviewEditorRuntime
+    | EditorSessionState["canonicalDocument"]["styles"],
+): StyleCatalogSnapshot {
+  const styles =
+    "getSessionState" in input
+      ? input.getSessionState().canonicalDocument.styles
+      : input;
+  const mapRecord = <
+    T extends {
+      styleId: string;
+      displayName: string;
+      kind: "paragraph" | "character" | "table";
+      isDefault: boolean;
+      basedOn?: string;
+      nextStyle?: string;
+    },
+  >(
+    record: Record<string, T>,
+  ) =>
+    Object.values(record)
+      .map((entry) => ({
+        styleId: entry.styleId,
+        displayName: entry.displayName,
+        kind: entry.kind,
+        isDefault: entry.isDefault,
+        ...(entry.basedOn ? { basedOn: entry.basedOn } : {}),
+        ...(entry.nextStyle ? { nextStyle: entry.nextStyle } : {}),
+      }))
+      .sort((left, right) =>
+        left.displayName.localeCompare(right.displayName) ||
+        left.styleId.localeCompare(right.styleId),
+      );
+
+  return {
+    paragraphs: mapRecord(styles.paragraphs),
+    characters: mapRecord(styles.characters),
+    tables: mapRecord(styles.tables),
+    fromPackage: styles.fromPackage === true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Formatting (flat + suggesting-mode)
+// ---------------------------------------------------------------------------
+
+type FormattingOperation =
+  | { 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" };
+
+export function applyRuntimeFormattingOperation(
+  runtime: WordReviewEditorRuntime,
+  operation: FormattingOperation,
+): void {
+  if (isSelectionSuggesting(runtime)) {
+    if (applySuggestingFormattingOperation(runtime, operation)) {
+      return;
+    }
+  }
+  if (emitSuggestingUnsupportedMutation(runtime, getFormattingOperationCommandName(operation))) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, getFormattingOperationCommandName(operation));
+  if (!context) {
+    return;
+  }
+
+  const result = applyFormattingOperationToDocument(
+    context.localDocument,
+    context.localSnapshot,
+    operation,
+  );
+  dispatchStoryMutationResult(
+    runtime,
+    context,
+    {
+      ...result,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    context.timestamp,
+  );
+}
+
+function applySuggestingFormattingOperation(
+  runtime: WordReviewEditorRuntime,
+  operation: FormattingOperation,
+): boolean {
+  const commandName = getFormattingOperationCommandName(operation);
+  const context = getStoryMutationContext(runtime, commandName);
+  if (!context) {
+    return true;
+  }
+  if (context.activeStory.kind !== "main") {
+    runtime.emitBlockedCommand(commandName, [{
+      code: "suggesting_unsupported",
+      message: `"${commandName}" is not supported in suggesting mode for this story.`,
+    }]);
+    return true;
+  }
+
+  if (operation.type === "set-alignment" || operation.type === "indent" || operation.type === "outdent") {
+    const paragraphContext = resolveActiveParagraphContext(context.localSnapshot);
+    if (!paragraphContext) {
+      return true;
+    }
+    const beforeXml = buildParagraphPropertyBeforeXml(paragraphContext.paragraph);
+    const result = applyFormattingOperationToDocument(
+      context.localDocument,
+      context.localSnapshot,
+      operation,
+    );
+    if (!result.changed) {
+      return true;
+    }
+    const nextDocument = appendPropertyChangeSuggestion(
+      result.document,
+      {
+        from: paragraphContext.paragraph.from,
+        to: paragraphContext.paragraph.to,
+      },
+      {
+        originalRevisionType: "pPrChange",
+        xmlTag: "pPrChange",
+        beforeXml,
+        semanticKind: "paragraph-property-change",
+        storyTarget: context.activeStory,
+        authorId: runtime.getDefaultAuthorId?.(),
+      },
+      context.timestamp,
+    );
+    dispatchStoryMutationResult(
+      runtime,
+      context,
+      {
+        changed: true,
+        document: nextDocument,
+        selection: toRuntimeSelectionSnapshot(result.selection),
+      },
+      context.timestamp,
+    );
+    return true;
+  }
+
+  const segment = findSingleSelectedTextSegment(context.localSnapshot);
+  if (!segment) {
+    runtime.emitBlockedCommand(commandName, [{
+      code: "suggesting_unsupported",
+      message: `"${commandName}" requires one bounded text segment in suggesting mode.`,
+    }]);
+    return true;
+  }
+  const beforeXml = buildRunPropertyBeforeXml(segment);
+  const result = applyFormattingOperationToDocument(
+    context.localDocument,
+    context.localSnapshot,
+    operation,
+  );
+  if (!result.changed) {
+    return true;
+  }
+  const nextDocument = appendPropertyChangeSuggestion(
+    result.document,
+    {
+      from: segment.from,
+      to: segment.to,
+    },
+    {
+      originalRevisionType: "rPrChange",
+      xmlTag: "rPrChange",
+      beforeXml,
+      semanticKind: "formatting-change",
+      storyTarget: context.activeStory,
+      authorId: runtime.getDefaultAuthorId?.(),
+    },
+    context.timestamp,
+  );
+  dispatchStoryMutationResult(
+    runtime,
+    context,
+    {
+      changed: true,
+      document: nextDocument,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    context.timestamp,
+  );
+  return true;
+}
+
+function getFormattingOperationCommandName(operation: FormattingOperation): 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";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Suggesting-mode property-change plumbing
+// ---------------------------------------------------------------------------
+
+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 appendPropertyChangeSuggestion(
+  document: EditorSessionState["canonicalDocument"],
+  anchor: { from: number; to: number },
+  input: {
+    originalRevisionType: "rPrChange" | "pPrChange";
+    xmlTag: "rPrChange" | "pPrChange";
+    beforeXml: string;
+    semanticKind: "formatting-change" | "paragraph-property-change";
+    storyTarget: EditorStoryTarget;
+    authorId?: string;
+  },
+  timestamp: string,
+): EditorSessionState["canonicalDocument"] {
+  const existing = document.review.revisions;
+  const changeId = createRuntimeSuggestionChangeId(existing, timestamp);
+  const resolvedAuthorId = input.authorId ?? "unknown";
+  return {
+    ...document,
+    review: {
+      ...document.review,
+      revisions: {
+        ...existing,
+        [changeId]: {
+          changeId,
+          kind: "property-change",
+          anchor: createRangeAnchor(anchor.from, anchor.to, { start: 1, end: -1 }),
+          authorId: resolvedAuthorId,
+          createdAt: timestamp,
+          warningIds: [],
+          metadata: {
+            source: "runtime",
+            storyTarget: input.storyTarget,
+            suggestionId: changeId,
+            semanticKind: input.semanticKind,
+            originalRevisionType: input.originalRevisionType,
+            propertyChangeData: {
+              xmlTag: input.xmlTag,
+              beforeXml: input.beforeXml,
+            },
+          },
+          status: "open",
+        },
+      },
+    },
+  };
+}
+
+function createRuntimeSuggestionChangeId(
+  existing: EditorSessionState["canonicalDocument"]["review"]["revisions"],
+  timestamp: string,
+): string {
+  const base = `change-${timestamp.replace(/[^0-9]/gu, "")}`;
+  let counter = Object.keys(existing).length + 1;
+  let candidate = `${base}-p${counter}`;
+  while (existing[candidate]) {
+    counter += 1;
+    candidate = `${base}-p${counter}`;
+  }
+  return candidate;
+}
+
+function findSingleSelectedTextSegment(
+  snapshot: Pick<RuntimeRenderSnapshot, "surface" | "selection">,
+): Extract<SurfaceInlineSegment, { kind: "text" }> | null {
+  if (!snapshot.surface || snapshot.selection.activeRange.kind !== "range" || snapshot.selection.isCollapsed) {
+    return null;
+  }
+  const selectionFrom = Math.min(snapshot.selection.anchor, snapshot.selection.head);
+  const selectionTo = Math.max(snapshot.selection.anchor, snapshot.selection.head);
+  const segments = collectSelectedTextSegments(snapshot.surface.blocks, selectionFrom, selectionTo);
+  if (segments.length !== 1) {
+    return null;
+  }
+  const [segment] = segments;
+  if (!segment || segment.from !== selectionFrom || segment.to !== selectionTo) {
+    return null;
+  }
+  return segment;
+}
+
+function collectSelectedTextSegments(
+  blocks: readonly SurfaceBlockSnapshot[],
+  selectionFrom: number,
+  selectionTo: number,
+  output: Array<Extract<SurfaceInlineSegment, { kind: "text" }>> = [],
+): Array<Extract<SurfaceInlineSegment, { kind: "text" }>> {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      for (const segment of block.segments) {
+        if (
+          segment.kind === "text" &&
+          rangesOverlap(selectionFrom, selectionTo, segment.from, segment.to)
+        ) {
+          output.push(segment);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectSelectedTextSegments(cell.content, selectionFrom, selectionTo, output);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "sdt_block") {
+      collectSelectedTextSegments(block.children, selectionFrom, selectionTo, output);
+    }
+  }
+  return output;
+}
+
+function rangesOverlap(
+  leftFrom: number,
+  leftTo: number,
+  rightFrom: number,
+  rightTo: number,
+): boolean {
+  return leftFrom < rightTo && rightFrom < leftTo;
+}
+
+function buildRunPropertyBeforeXml(
+  segment: Extract<SurfaceInlineSegment, { kind: "text" }>,
+): string {
+  const parts: string[] = [];
+  const marks = new Set(segment.marks ?? []);
+  if (marks.has("bold")) parts.push("<w:b/>");
+  if (marks.has("italic")) parts.push("<w:i/>");
+  if (marks.has("underline")) parts.push("<w:u w:val=\"single\"/>");
+  if (marks.has("strikethrough")) parts.push("<w:strike/>");
+  if (marks.has("superscript")) parts.push("<w:vertAlign w:val=\"superscript\"/>");
+  if (marks.has("subscript")) parts.push("<w:vertAlign w:val=\"subscript\"/>");
+  if (segment.markAttrs?.fontFamily) {
+    parts.push(`<w:rFonts w:ascii="${escapeAttributeXml(segment.markAttrs.fontFamily)}" w:hAnsi="${escapeAttributeXml(segment.markAttrs.fontFamily)}"/>`);
+  }
+  if (segment.markAttrs?.fontSize !== undefined) {
+    parts.push(`<w:sz w:val="${segment.markAttrs.fontSize}"/>`);
+  }
+  if (segment.markAttrs?.textColor) {
+    parts.push(`<w:color w:val="${escapeAttributeXml(segment.markAttrs.textColor)}"/>`);
+  }
+  if (segment.markAttrs?.backgroundColor) {
+    parts.push(`<w:shd w:val="clear" w:color="auto" w:fill="${escapeAttributeXml(segment.markAttrs.backgroundColor)}"/>`);
+  }
+  return `<w:rPr>${parts.join("")}</w:rPr>`;
+}
+
+function buildParagraphPropertyBeforeXml(
+  paragraph: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): string {
+  const parts: string[] = [];
+  if (paragraph.styleId) {
+    parts.push(`<w:pStyle w:val="${escapeAttributeXml(paragraph.styleId)}"/>`);
+  }
+  if (paragraph.numbering) {
+    parts.push(
+      `<w:numPr><w:ilvl w:val="${paragraph.numbering.level}"/><w:numId w:val="${escapeAttributeXml(
+        paragraph.numbering.numberingInstanceId.replace(/^num:/u, ""),
+      )}"/></w:numPr>`,
+    );
+  }
+  if (paragraph.alignment) {
+    parts.push(`<w:jc w:val="${escapeAttributeXml(paragraph.alignment)}"/>`);
+  }
+  if (paragraph.indentation) {
+    const attrs: string[] = [];
+    if (paragraph.indentation.left !== undefined) attrs.push(`w:left="${paragraph.indentation.left}"`);
+    if (paragraph.indentation.right !== undefined) attrs.push(`w:right="${paragraph.indentation.right}"`);
+    if (paragraph.indentation.firstLine !== undefined) attrs.push(`w:firstLine="${paragraph.indentation.firstLine}"`);
+    if (paragraph.indentation.hanging !== undefined) attrs.push(`w:hanging="${paragraph.indentation.hanging}"`);
+    if (attrs.length > 0) {
+      parts.push(`<w:ind ${attrs.join(" ")}/>`);
+    }
+  }
+  return `<w:pPr>${parts.join("")}</w:pPr>`;
+}
+
+function escapeAttributeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+// ---------------------------------------------------------------------------
+// List toggle / paragraph style / table style
+// ---------------------------------------------------------------------------
+
+export function applyRuntimeListToggle(
+  runtime: WordReviewEditorRuntime,
+  kind: "bulleted" | "numbered",
+): void {
+  const commandName =
+    kind === "bulleted" ? "toggleBulletedList" : "toggleNumberedList";
+  if (emitSuggestingUnsupportedMutation(runtime, commandName)) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, commandName);
+  if (!context) {
+    return;
+  }
+
+  const paragraphContext = resolveActiveParagraphContext(context.localSnapshot);
+  if (!paragraphContext) {
+    return;
+  }
+
+  const result =
+    kind === "bulleted"
+      ? toggleBulletedList(
+          context.localDocument,
+          [paragraphContext.paragraphIndex],
+          { timestamp: context.timestamp },
+        )
+      : toggleNumberedList(
+          context.localDocument,
+          [paragraphContext.paragraphIndex],
+          { timestamp: context.timestamp },
+        );
+  dispatchStoryMutationResult(
+    runtime,
+    context,
+    {
+      changed: result.affectedParagraphIndexes.length > 0,
+      document: result.document,
+      selection: toRuntimeSelectionSnapshot(context.localSnapshot.selection),
+    },
+    context.timestamp,
+  );
+}
+
+export function applyRuntimeParagraphStyle(
+  runtime: WordReviewEditorRuntime,
+  styleId: string | null,
+): void {
+  if (emitSuggestingUnsupportedMutation(runtime, "setParagraphStyle")) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "setParagraphStyle");
+  if (!context) {
+    return;
+  }
+
+  const result = applyParagraphStyleToDocument(
+    context.localDocument,
+    context.localSnapshot,
+    styleId,
+  );
+  dispatchStoryMutationResult(
+    runtime,
+    context,
+    {
+      ...result,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    context.timestamp,
+  );
+}
+
+export function applyRuntimeTableStyle(
+  runtime: WordReviewEditorRuntime,
+  styleId: string | null,
+): void {
+  if (emitSuggestingUnsupportedMutation(runtime, "setTableStyle")) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "setTableStyle");
+  if (!context) {
+    return;
+  }
+
+  const result = applyTableStyleToDocument(
+    context.localDocument,
+    context.localSnapshot,
+    styleId,
+  );
+  dispatchStoryMutationResult(
+    runtime,
+    context,
+    {
+      ...result,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    context.timestamp,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Paragraph layout / numbering flow
+// ---------------------------------------------------------------------------
+
+export function applyRuntimeParagraphIndentation(
+  runtime: WordReviewEditorRuntime,
+  indentation: {
+    left?: number;
+    right?: number;
+    firstLine?: number;
+    hanging?: number;
+  },
+): void {
+  if (emitSuggestingUnsupportedMutation(runtime, "setParagraphIndentation")) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "setParagraphIndentation");
+  if (!context) {
+    return;
+  }
+
+  const result = setActiveParagraphIndentation(
+    context.localDocument,
+    context.localSnapshot,
+    indentation,
+    { timestamp: context.timestamp },
+  );
+  dispatchStoryMutationResult(
+    runtime,
+    context,
+    {
+      ...result,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    context.timestamp,
+  );
+}
+
+export function applyRuntimeParagraphTabStops(
+  runtime: WordReviewEditorRuntime,
+  tabStops: Array<{ pos: number; val?: string; leader?: string }>,
+): void {
+  if (emitSuggestingUnsupportedMutation(runtime, "setParagraphTabStops")) {
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "setParagraphTabStops");
+  if (!context) {
+    return;
+  }
+
+  const result = setActiveParagraphTabStops(
+    context.localDocument,
+    context.localSnapshot,
+    tabStops,
+    { timestamp: context.timestamp },
+  );
+  dispatchStoryMutationResult(
+    runtime,
+    context,
+    {
+      ...result,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    context.timestamp,
+  );
+}
+
+export function applyRuntimeNumberingFlow(
+  runtime: WordReviewEditorRuntime,
+  operation: { type: "restart"; startAt?: number } | { type: "continue" },
+): void {
+  if (
+    emitSuggestingUnsupportedMutation(
+      runtime,
+      operation.type === "restart" ? "restartNumbering" : "continueNumbering",
+    )
+  ) {
+    return;
+  }
+  const context = getStoryMutationContext(
+    runtime,
+    operation.type === "restart" ? "restartNumbering" : "continueNumbering",
+  );
+  if (!context) {
+    return;
+  }
+
+  const paragraphContext = resolveActiveParagraphContext(context.localSnapshot);
+  if (!paragraphContext?.paragraph.numbering) {
+    return;
+  }
+
+  const result =
+    operation.type === "restart"
+      ? restartListNumbering(
+          context.localDocument,
+          paragraphContext.paragraphIndex,
+          { timestamp: context.timestamp },
+          operation.startAt,
+        )
+      : continueListNumbering(
+          context.localDocument,
+          paragraphContext.paragraphIndex,
+          { timestamp: context.timestamp },
+        );
+
+  dispatchStoryMutationResult(
+    runtime,
+    context,
+    {
+      changed: result.affectedParagraphIndexes.length > 0,
+      document: result.document,
+      selection: toRuntimeSelectionSnapshot(context.localSnapshot.selection),
+    },
+    context.timestamp,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Section break / section layout
+// ---------------------------------------------------------------------------
+
+export function applyRuntimeInsertSectionBreak(
+  runtime: WordReviewEditorRuntime,
+  breakType: SectionBreakType,
+  options?: { afterSectionIndex?: number },
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (!canApplyRuntimeMutation(snapshot) || snapshot.activeStory.kind !== "main") {
+    return;
+  }
+  if (emitWorkflowBlockedMutation(runtime, "insertSectionBreak")) {
+    return;
+  }
+  if (isSelectionSuggesting(runtime)) {
+    runtime.emitBlockedCommand("insertSectionBreak", [{
+      code: "unsupported_surface",
+      message: "Section break insertion is not supported in suggesting mode.",
+    }]);
+    return;
+  }
+
+  const sessionState = runtime.getSessionState();
+  const timestamp = new Date().toISOString();
+  const result =
+    typeof options?.afterSectionIndex === "number"
+      ? insertSectionBreakAfterSectionIndex(
+          sessionState.canonicalDocument,
+          options.afterSectionIndex,
+          breakType,
+          { timestamp },
+        )
+      : insertSectionBreakAfterSectionIndex(
+          sessionState.canonicalDocument,
+          runtime.getDocumentNavigationSnapshot().activeSectionIndex,
+          breakType,
+          { timestamp },
+        );
+
+  dispatchRuntimeDocumentMutation(
+    runtime,
+    {
+      changed: result.changed,
+      document: result.document,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    timestamp,
+  );
+}
+
+export function applyRuntimeDeleteSectionBreak(
+  runtime: WordReviewEditorRuntime,
+  sectionIndex: number,
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  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();
+  const result = deleteSectionBreakAtSectionIndex(
+    sessionState.canonicalDocument,
+    sectionIndex,
+    { timestamp },
+  );
+
+  dispatchRuntimeDocumentMutation(
+    runtime,
+    {
+      changed: result.changed,
+      document: result.document,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    timestamp,
+  );
+}
+
+export function applyRuntimeUpdateSectionLayout(
+  runtime: WordReviewEditorRuntime,
+  sectionIndex: number,
+  patch: SectionLayoutPatch,
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  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();
+  const result = updateSectionLayoutAtSectionIndex(
+    sessionState.canonicalDocument,
+    sectionIndex,
+    {
+      ...(patch.pageSize ? { pageSize: patch.pageSize } : {}),
+      ...(patch.pageMargins ? { pageMargins: patch.pageMargins } : {}),
+      ...(patch.columns ? { columns: patch.columns } : {}),
+      ...(patch.titlePage !== undefined ? { titlePage: patch.titlePage } : {}),
+      ...(patch.sectionType ? { sectionType: patch.sectionType } : {}),
+    },
+    { timestamp },
+  );
+
+  dispatchRuntimeDocumentMutation(
+    runtime,
+    {
+      changed: result.changed,
+      document: result.document,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    timestamp,
+  );
+}
+
+export function applyRuntimeSetSectionPageNumbering(
+  runtime: WordReviewEditorRuntime,
+  sectionIndex: number,
+  patch: SectionPageNumberingPatch | null,
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  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();
+  const normalizedPatch =
+    patch === null
+      ? null
+      : {
+          ...(patch.format !== undefined
+            ? { format: patch.format ?? undefined }
+            : {}),
+          ...(patch.start !== undefined
+            ? { start: patch.start ?? undefined }
+            : {}),
+          ...(patch.chapterStyle !== undefined
+            ? { chapStyle: patch.chapterStyle ?? undefined }
+            : {}),
+          ...(patch.chapterSeparator !== undefined
+            ? { chapSep: patch.chapterSeparator ?? undefined }
+            : {}),
+        };
+  const result = setSectionPageNumberingAtSectionIndex(
+    sessionState.canonicalDocument,
+    sectionIndex,
+    normalizedPatch,
+    { timestamp },
+  );
+
+  dispatchRuntimeDocumentMutation(
+    runtime,
+    {
+      changed: result.changed,
+      document: result.document,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    timestamp,
+  );
+}
+
+export function applyRuntimeSetHeaderFooterLink(
+  runtime: WordReviewEditorRuntime,
+  sectionIndex: number,
+  patch: HeaderFooterLinkPatch,
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  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();
+  const result = setHeaderFooterLinkAtSectionIndex(
+    sessionState.canonicalDocument,
+    sectionIndex,
+    patch,
+    { timestamp },
+  );
+
+  dispatchRuntimeDocumentMutation(
+    runtime,
+    {
+      changed: result.changed,
+      document: result.document,
+      selection: toRuntimeSelectionSnapshot(result.selection),
+    },
+    timestamp,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Page break / table insert / image insert + resize + reposition
+// ---------------------------------------------------------------------------
+
+export function applyRuntimeInsertPageBreak(runtime: WordReviewEditorRuntime): void {
+  if (isSelectionSuggesting(runtime)) {
+    runtime.emitBlockedCommand("insertPageBreak", [{
+      code: "unsupported_surface",
+      message: "Page break insertion is not supported in suggesting mode.",
+    }]);
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "insertPageBreak");
+  if (!context) {
+    return;
+  }
+
+  const result = insertPageBreakInDocument(
+    context.localDocument,
+    toRuntimeSelectionSnapshot(context.localSnapshot.selection),
+    { timestamp: context.timestamp },
+  );
+  dispatchStoryMutationResult(runtime, context, result, context.timestamp);
+}
+
+export function applyRuntimeInsertTable(
+  runtime: WordReviewEditorRuntime,
+  options: InsertTableOptions,
+): void {
+  if (isSelectionSuggesting(runtime)) {
+    runtime.emitBlockedCommand("insertTable", [{
+      code: "unsupported_surface",
+      message: "Table insertion is not supported in suggesting mode.",
+    }]);
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "insertTable");
+  if (!context) {
+    return;
+  }
+
+  const result = insertTableInDocument(
+    context.localDocument,
+    toRuntimeSelectionSnapshot(context.localSnapshot.selection),
+    options,
+    { timestamp: context.timestamp },
+  );
+  dispatchStoryMutationResult(runtime, context, result, context.timestamp);
+}
+
+export function applyRuntimeInsertImage(
+  runtime: WordReviewEditorRuntime,
+  options: InsertImageOptions,
+): void {
+  if (isSelectionSuggesting(runtime)) {
+    runtime.emitBlockedCommand("insertImage", [{
+      code: "unsupported_surface",
+      message: "Image insertion is not supported in suggesting mode.",
+    }]);
+    return;
+  }
+  const context = getStoryMutationContext(runtime, "insertImage");
+  if (!context) {
+    return;
+  }
+
+  try {
+    const result = insertImageInDocument(
+      context.localDocument,
+      toRuntimeSelectionSnapshot(context.localSnapshot.selection),
+      options.data,
+      options.mimeType,
+      options.width,
+      options.height,
+      {
+        timestamp: context.timestamp,
+        altText: options.altText,
+      },
+    );
+    dispatchStoryMutationResult(runtime, context, {
+      changed: true,
+      document: result.document,
+      selection: result.selection,
+      mapping: result.mapping,
+    }, context.timestamp);
+  } catch {
+    return;
+  }
+}
+
+export function applyRuntimeImageResize(
+  runtime: WordReviewEditorRuntime,
+  mediaId: string,
+  dimensions: { widthEmu: number; heightEmu: number },
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (!canApplyRuntimeMutation(snapshot)) {
+    return;
+  }
+  if (emitWorkflowBlockedMutation(runtime, "setImageLayout")) {
+    return;
+  }
+  if (isSelectionSuggesting(runtime)) {
+    runtime.emitBlockedCommand("setImageLayout", [{
+      code: "unsupported_surface",
+      message: "Image resize is not supported in suggesting mode.",
+    }]);
+    return;
+  }
+
+  try {
+    const sessionState = runtime.getSessionState();
+    const result = resizeImageInCatalog(
+      sessionState.canonicalDocument,
+      mediaId,
+      dimensions,
+    );
+    runtime.dispatch({
+      type: "document.replace",
+      document: result.document,
+      selection: toRuntimeSelectionSnapshot(snapshot.selection),
+      origin: { source: "api", timestamp: new Date().toISOString() },
+    });
+  } catch {
+    return;
+  }
+}
+
+export function applyRuntimeImageReposition(
+  runtime: WordReviewEditorRuntime,
+  mediaId: string,
+  offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number },
+): void {
+  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, "setImageFrame");
+  if (!context) {
+    return;
+  }
+
+  try {
+    const result = repositionFloatingImageInDocument(
+      context.localDocument,
+      mediaId,
+      offsets,
+      context.timestamp,
+    );
+    dispatchStoryMutationResult(
+      runtime,
+      context,
+      {
+        changed: true,
+        document: result.document,
+        selection: toRuntimeSelectionSnapshot(context.localSnapshot.selection),
+      },
+      context.timestamp,
+    );
+  } catch {
+    return;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Table structure dispatch
+// ---------------------------------------------------------------------------
+
+export function applyRuntimeTableStructureOperation(
+  runtime: WordReviewEditorRuntime,
+  mountedSurface: TwProseMirrorSurfaceRef | null | undefined,
+  operation: TableStructureOperation,
+): { changed: boolean; coercedReason: string | null } {
+  if (isSelectionSuggesting(runtime)) {
+    const coercedReason = `Table operation "${operation.type}" is not supported in suggesting mode.`;
+    runtime.emitBlockedCommand(`table.${operation.type}`, [{
+      code: "unsupported_surface",
+      message: coercedReason,
+    }]);
+    return { changed: false, coercedReason };
+  }
+  const context = getStoryMutationContext(runtime, `table.${operation.type}`);
+  if (!context) {
+    return { changed: false, coercedReason: "No active mutation context." };
+  }
+
+  const result = applyTableStructureOperationInDocument(
+    context.localDocument,
+    context.localSnapshot,
+    mountedSurface?.getTableSelection() ?? null,
+    operation,
+  );
+  dispatchStoryMutationResult(runtime, context, result, context.timestamp);
+  return {
+    changed: result.changed,
+    coercedReason: result.changed ? null : "Op was a no-op against the active selection.",
+  };
+}
+
+/**
+ * Translate a public-API `TableOp` (kebab-case `kind` discriminator)
+ * to the internal `TableStructureOperation` (`type` discriminator).
+ * The shape values are identical aside from the discriminator name.
+ */
+export function publicTableOpToInternal(op: TableOp): TableStructureOperation {
+  const { kind, ...rest } = op as { kind: string } & Record<string, unknown>;
+  if (kind === "insert") {
+    throw new Error(
+      "TableOp kind \"insert\" is not routed through ref.tables.apply; use ref.insertTable(...).",
+    );
+  }
+  return { type: kind, ...rest } as TableStructureOperation;
+}
+
+// ---------------------------------------------------------------------------
+// Selection routing + paragraph resolution
+// ---------------------------------------------------------------------------
+
+export function applyRuntimeSelection(
+  runtime: WordReviewEditorRuntime,
+  selection: PublicSelectionSnapshot,
+): void {
+  const requestedStory = selection.storyTarget ?? { kind: "main" };
+  if (requestedStory.kind === "main") {
+    runtime.closeStory();
+  } else if (!storyTargetsEqual(runtime.getActiveStory(), requestedStory)) {
+    if (!runtime.openStory(requestedStory)) {
+      return;
+    }
+  }
+
+  runtime.dispatch({
+    type: "selection.set",
+    selection: toRuntimeSelectionSnapshot(stripStoryTarget(selection)),
+  });
+}
+
+function resolveActiveParagraphContext(
+  snapshot: Pick<RuntimeRenderSnapshot, "surface" | "selection">,
+): {
+  paragraphIndex: number;
+  paragraph: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>;
+  atParagraphStart: boolean;
+  isEmpty: boolean;
+} | null {
+  if (!snapshot.surface) {
+    return null;
+  }
+
+  const paragraphIndex = resolveActiveParagraphIndex(
+    snapshot.surface.blocks,
+    snapshot.selection,
+  );
+  if (paragraphIndex === null) {
+    return null;
+  }
+
+  const selectionPosition =
+    snapshot.selection.activeRange.kind === "node"
+      ? snapshot.selection.activeRange.at
+      : snapshot.selection.head;
+  const paragraph = findSurfaceParagraphAtPosition(snapshot.surface.blocks, selectionPosition);
+  if (!paragraph) {
+    return null;
+  }
+
+  return {
+    paragraphIndex,
+    paragraph,
+    atParagraphStart:
+      snapshot.selection.isCollapsed &&
+      snapshot.selection.activeRange.kind !== "node" &&
+      snapshot.selection.anchor === snapshot.selection.head &&
+      snapshot.selection.head === paragraph.from,
+    isEmpty: isSurfaceParagraphEmpty(paragraph),
+  };
+}
+
+function findSurfaceParagraphAtPosition(
+  blocks: readonly SurfaceBlockSnapshot[],
+  position: number,
+): Extract<SurfaceBlockSnapshot, { kind: "paragraph" }> | null {
+  for (const block of blocks) {
+    if (position < block.from || position > block.to) {
+      continue;
+    }
+    if (block.kind === "paragraph") {
+      return block;
+    }
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          const paragraph = findSurfaceParagraphAtPosition(cell.content, position);
+          if (paragraph) {
+            return paragraph;
+          }
+        }
+      }
+      continue;
+    }
+    if (block.kind === "sdt_block") {
+      const paragraph = findSurfaceParagraphAtPosition(block.children, position);
+      if (paragraph) {
+        return paragraph;
+      }
+    }
+  }
+  return null;
+}
+
+function isSurfaceParagraphEmpty(
+  paragraph: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): boolean {
+  if (paragraph.segments.length === 0) {
+    return true;
+  }
+  return paragraph.segments.every((segment) => segment.kind === "text" && segment.text.length === 0);
+}
+
+// ---------------------------------------------------------------------------
+// Shared dispatch helpers
+// ---------------------------------------------------------------------------
+
+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;
+  persistedDocument: EditorSessionState["canonicalDocument"];
+  localDocument: EditorSessionState["canonicalDocument"];
+  localSnapshot: RuntimeRenderSnapshot;
+} | null {
+  const snapshot = runtime.getRenderSnapshot();
+  if (!canApplyRuntimeMutation(snapshot)) {
+    return null;
+  }
+  if (command && emitWorkflowBlockedMutation(runtime, command)) {
+    return null;
+  }
+
+  const persistedDocument = runtime.getSessionState().canonicalDocument;
+  const activeStory = snapshot.activeStory;
+  if (activeStory.kind === "main") {
+    return {
+      timestamp: new Date().toISOString(),
+      activeStory,
+      persistedDocument,
+      localDocument: persistedDocument,
+      localSnapshot: snapshot,
+    };
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    activeStory,
+    persistedDocument,
+    localDocument: {
+      ...persistedDocument,
+      content: {
+        type: "doc",
+        children: [...getStoryBlocks(persistedDocument, activeStory)],
+      },
+    },
+    localSnapshot: {
+      ...snapshot,
+      activeStory: { kind: "main" },
+      selection: stripStoryTarget(snapshot.selection),
+    },
+  };
+}
+
+function dispatchStoryMutationResult(
+  runtime: WordReviewEditorRuntime,
+  context: {
+    activeStory: EditorStoryTarget;
+    persistedDocument: EditorSessionState["canonicalDocument"];
+  },
+  result: {
+    changed: boolean;
+    document: EditorSessionState["canonicalDocument"];
+    selection: InternalSelectionSnapshot;
+    mapping?: TransactionMapping;
+  },
+  timestamp: string,
+): void {
+  if (context.activeStory.kind === "main") {
+    dispatchRuntimeDocumentMutation(runtime, result, timestamp);
+    return;
+  }
+
+  if (!result.changed) {
+    return;
+  }
+
+  const nextDocument = replaceStoryBlocks(
+    context.persistedDocument,
+    context.activeStory,
+    result.document.content.children,
+  );
+  dispatchRuntimeDocumentMutation(
+    runtime,
+    {
+      changed: true,
+      document: nextDocument,
+      selection: result.selection,
+    },
+    timestamp,
+  );
+}
+
+function dispatchRuntimeDocumentMutation(
+  runtime: WordReviewEditorRuntime,
+  result: {
+    changed: boolean;
+    document: EditorSessionState["canonicalDocument"];
+    selection: InternalSelectionSnapshot;
+    mapping?: TransactionMapping;
+  },
+  timestamp: string,
+): void {
+  if (!result.changed) {
+    return;
+  }
+
+  runtime.dispatch({
+    type: "document.replace",
+    document: {
+      ...result.document,
+      updatedAt: timestamp,
+    },
+    mapping: result.mapping,
+    selection: result.selection,
+    origin: {
+      source: "api",
+      timestamp,
+    },
+  });
+}
+
+function isSelectionSuggesting(runtime: WordReviewEditorRuntime): boolean {
+  return runtime.getInteractionGuardSnapshot().effectiveMode === "suggest";
+}
+
+function stripStoryTarget(
+  selection: PublicSelectionSnapshot,
+): PublicSelectionSnapshot {
+  const { storyTarget: _storyTarget, ...rest } = selection;
+  return rest;
+}
+
+// ---------------------------------------------------------------------------
+// Comment deletion
+// ---------------------------------------------------------------------------
+
+export function applyRuntimeDeleteComment(
+  runtime: WordReviewEditorRuntime,
+  commentId: string,
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  // Pre-ready / fatal states stay silent: the host called too early, and
+  // there is no meaningful document yet to signal against. Emitting a
+  // warning here would only add noise to load-time error handling.
+  if (!snapshot.isReady || snapshot.fatalError) {
+    return;
+  }
+  if (snapshot.readOnly) {
+    runtime.emitTransientWarning({
+      warningId: `delete-comment-readonly-${commentId}-${Date.now()}`,
+      code: "review_target_not_found",
+      severity: "info",
+      message: `deleteComment("${commentId}") skipped: editor is read-only.`,
+      source: "review",
+      details: { op: "deleteComment", targetId: commentId, reason: "read_only" },
+    });
+    return;
+  }
+
+  const sessionState = runtime.getSessionState();
+  if (!sessionState.canonicalDocument.review.comments[commentId]) {
+    runtime.emitTransientWarning({
+      warningId: `delete-comment-unknown-${commentId}-${Date.now()}`,
+      code: "review_target_not_found",
+      severity: "info",
+      message: `deleteComment("${commentId}") skipped: unknown commentId.`,
+      source: "review",
+      details: { op: "deleteComment", targetId: commentId, reason: "comment_unknown" },
+    });
+    return;
+  }
+
+  const nextComments = {
+    ...sessionState.canonicalDocument.review.comments,
+  };
+  delete nextComments[commentId];
+
+  runtime.dispatch({
+    type: "document.replace",
+    document: {
+      ...sessionState.canonicalDocument,
+      review: {
+        ...sessionState.canonicalDocument.review,
+        comments: nextComments,
+      },
+    },
+    selection: toRuntimeSelectionSnapshot(snapshot.selection),
+    origin: {
+      source: "api",
+      timestamp: new Date().toISOString(),
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public-selection construction utilities
+// ---------------------------------------------------------------------------
+
+export function normalizeRequestedSelection(
+  snapshot: RuntimeRenderSnapshot,
+  selection: PublicSelectionSnapshot | null,
+): PublicSelectionSnapshot {
+  return (
+    selection ??
+    createCollapsedPublicSelection(
+      snapshot.selection.head,
+      snapshot.activeStory.kind === "main" ? undefined : snapshot.activeStory,
+    )
+  );
+}
+
+export function createCollapsedPublicSelection(
+  position: number,
+  storyTarget?: EditorStoryTarget,
+): PublicSelectionSnapshot {
+  return {
+    anchor: position,
+    head: position,
+    isCollapsed: true,
+    activeRange: {
+      kind: "range",
+      from: position,
+      to: position,
+      assoc: {
+        start: -1,
+        end: 1,
+      },
+    },
+    ...(storyTarget ? { storyTarget } : {}),
+  };
+}
+
+export function createSelectionFromAnchor(
+  anchor: PublicSelectionSnapshot["activeRange"],
+  storyTarget?: EditorStoryTarget,
+): PublicSelectionSnapshot {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        anchor: anchor.from,
+        head: anchor.to,
+        isCollapsed: anchor.from === anchor.to,
+        activeRange: anchor,
+        ...(storyTarget ? { storyTarget } : {}),
+      };
+    case "node":
+      return {
+        anchor: anchor.at,
+        head: anchor.at,
+        isCollapsed: true,
+        activeRange: anchor,
+        ...(storyTarget ? { storyTarget } : {}),
+      };
+    case "detached":
+      return {
+        anchor: anchor.lastKnownRange.from,
+        head: anchor.lastKnownRange.to,
+        isCollapsed: anchor.lastKnownRange.from === anchor.lastKnownRange.to,
+        activeRange: anchor,
+        ...(storyTarget ? { storyTarget } : {}),
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal <-> public selection conversion
+// ---------------------------------------------------------------------------
+
+export function toRuntimeSelectionSnapshot(selection: PublicSelectionSnapshot) {
+  return {
+    anchor: selection.anchor,
+    head: selection.head,
+    isCollapsed: selection.isCollapsed,
+    activeRange:
+      selection.activeRange.kind === "range"
+        ? createRangeAnchor(
+            selection.activeRange.from,
+            selection.activeRange.to,
+            selection.activeRange.assoc,
+          )
+        : selection.activeRange.kind === "node"
+          ? createNodeAnchor(selection.activeRange.at, selection.activeRange.assoc)
+          : createDetachedAnchor(
+              selection.activeRange.lastKnownRange,
+              selection.activeRange.reason,
+            ),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shared dispatch-context handle for the text-command bridge.
+//
+// `dispatchTextCommand` (in `src/runtime/edit-dispatch/`) expects a
+// `DispatchContext` with the four mutation primitives it needs to rewrite
+// the canonical document on text events. WRE used to build this inline —
+// it now imports the same const from the shell module so both surfaces
+// dispatch through one codepath.
+// ---------------------------------------------------------------------------
+
+export const DISPATCH_CONTEXT: DispatchContext = {
+  getStoryMutationContext,
+  dispatchStoryMutationResult,
+  resolveActiveParagraphContext,
+  toRuntimeSelectionSnapshot,
+};