@beyondwork/docx-react-component 1.0.56 → 1.0.58

package/src/runtime/document-runtime.ts

@@ -12,6 +12,11 @@ import {
   type EditorState,
   type EditorWarning as InternalEditorWarning,
 } from "../core/state/editor-state.ts";
+import {
+  logicalPositionToUnitIndex,
+  parseTextStory,
+  serializeTextStory,
+} from "../core/schema/text-schema.ts";
 import type {
   AddCommentParams,
   AddCommentReplyResult,
@@ -61,6 +66,7 @@ import type {
   SurfaceInlineSegment,
   StoryTextStreamSnapshot,
   TextCommandAck,
+  TocRefreshTrigger,
   TocSnapshot,
   StyleCatalogSnapshot,
   TocRefreshOptions,
@@ -80,6 +86,8 @@ import type {
   WorkflowOverlay,
   WorkflowScope,
   WorkflowScopeSnapshot,
+  ScopeQueryFilter,
+  ScopeQueryResult,
   WorkspaceMode,
   WordReviewEditorEvent,
   ZoomLevel,
@@ -115,6 +123,8 @@ import {
   snapCommentAnchorAwayFromTable,
 } from "../core/selection/review-anchors.ts";
 import { buildBookmarkNameMap } from "../legal/bookmarks.ts";
+import { createFieldResolver, type FieldResolver } from "./field-resolver.ts";
+import { createFootnoteResolver, type FootnoteResolver } from "./footnote-resolver.ts";
 import {
   describeOpaqueFragment,
   findOpaqueFragmentsIntersectingRange,
@@ -128,7 +138,16 @@ 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 {
+  collectScopeLocations,
+  findAllScopesAt,
+  findScopesIntersecting,
+  resolveScope,
+} from "./scope-resolver.ts";
+import {
+  projectScopeQueryResults,
+  queryScopes as runQueryScopes,
+} from "./query-scopes.ts";
 import {
   insertScopeMarkers,
   removeScopeMarkers,
@@ -205,13 +224,16 @@ import {
   createEditorViewStateSnapshot,
   type ViewState,
 } from "./view-state.ts";
+import { ThemeColorResolver } from "./theme-color-resolver.ts";
 import type {
   BlockNode,
+  CanonicalDocument,
   FieldNode,
   FieldRefreshStatus,
   InlineNode,
   PageMargins,
   ParagraphNode,
+  SectionProperties,
   SubPartsCatalog,
 } from "../model/canonical-document.ts";
 import {
@@ -240,6 +262,14 @@ import type {
   EditorStatePersister,
 } from "../api/editor-state-types.ts";
 import { collectEditorStateForSerialize } from "./editor-state-integration.ts";
+import { serializeFragmentToWordML } from "../io/paste/word-clipboard.ts";
+import {
+  createObjectGrabState,
+  deselectObject as grabDeselectObject,
+  getGrabbedObject as grabGetGrabbedObject,
+  selectObject as grabSelectObject,
+  type ObjectGrabState,
+} from "./object-grab/index.ts";
 import type { EditorStatePayload } from "../io/ooxml/workflow-payload.ts";
 import type { SharedWorkflowState } from "./collab/workflow-shared.ts";
 import { formatPageNumber } from "./page-number-format.ts";
@@ -277,8 +307,77 @@ export interface DocumentRuntime {
   getRenderSnapshot(): RuntimeRenderSnapshot;
   getCanonicalDocument(): CanonicalDocumentEnvelope;
   getSourcePackage(): EditorSessionState["sourcePackage"] | undefined;
+  /** Return the parsed fontTable, if present in the loaded package. */
+  getFontTable(): CanonicalDocumentEnvelope["fontTable"];
+  /**
+   * Convenience accessor — return the `CanonicalFontEntry` for `name`, or
+   * undefined when the loaded package has no fontTable or no matching entry.
+   */
+  getFontEntry(
+    name: string,
+  ): NonNullable<CanonicalDocumentEnvelope["fontTable"]>["fonts"][string] | undefined;
   replaceText(text: string, target?: EditorAnchorProjection, formatting?: TextFormattingDirective): void;
   insertFragment(fragment: CanonicalDocumentFragment, target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — serialize the selection range to a
+   * `CanonicalDocumentFragment` and store it in an internal clipboard buffer.
+   * No document mutation. `target` defaults to the current selection.
+   */
+  copy(target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — `copy(target)` + delete the range. Safe on empty /
+   * collapsed ranges (no-op).
+   */
+  cut(target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — return the last fragment stored via `cut` / `copy`,
+   * or `null` when no clipboard operation has been performed yet. Mirrors
+   * what a browser `clipboardData.getData("web application/x-clip")` would
+   * return in a system-clipboard-aware build; for now hosts can use this to
+   * feed `insertFragment` directly.
+   */
+  getClipboardBuffer(): CanonicalDocumentFragment | null;
+  /**
+   * v5 close-out — return the current clipboard buffer serialized to the
+   * wire formats browsers/Word accept, or `null` when no clipboard op has
+   * been performed. Hosts pair this with `navigator.clipboard.write` inside
+   * their own DOM `copy`/`cut` event handler; the editor does not install
+   * the DOM handler itself because hosts often route cut/copy through their
+   * own protocol. Three formats: WordML (`application/x-docx-fragment`),
+   * HTML (`text/html`), and plain text (`text/plain`).
+   */
+  getClipboardWireFormats(): { wordml: string; html: string; plainText: string } | null;
+  /**
+   * R.3 ObjectGrabLayer — grab an inline / floating object (image, shape)
+   * by its stable id. Single-select model. Local-only state; not broadcast
+   * through collab. Lane 6 P11 paints the chrome handles.
+   */
+  selectObject(objectId: string): void;
+  /**
+   * R.3 — release any grabbed object. Safe to call when nothing is grabbed.
+   */
+  deselectObject(): void;
+  /**
+   * R.3 — return the currently grabbed object id, or `null` when no
+   * object is grabbed.
+   */
+  getGrabbedObject(): string | null;
+  /**
+   * R.5.a — open an action bracket. Hosts use this to group compound edits
+   * (paste → insertFragment, cut → copy+delete, agent suggestion-apply) so
+   * snapshot emission + collab broadcast + undo grouping see them as one
+   * action. Nested brackets are tracked by depth; only the outermost
+   * `endAction` completes the bracket.
+   *
+   * Phase 1 (Item E): this API ships opt-in. Commands don't auto-bracket
+   * themselves yet — hosts that want single-undo paste must call
+   * `startAction` / `endAction` around their `insertFragment` call.
+   */
+  startAction(name: string): void;
+  /** R.5.a — close one level of action bracketing. Unbalanced calls are no-ops. */
+  endAction(): void;
+  /** R.5.a — `true` when the runtime is inside one or more action brackets. */
+  isInAction(): boolean;
   applyActiveStoryTextCommand(command: ActiveStoryTextCommand): TextCommandAck;
   dispatch(command: EditorCommand): void;
   /**
@@ -382,6 +481,20 @@ export interface DocumentRuntime {
   }): DocumentSectionSnapshot | null;
   describeEventImpact(event: WordReviewEditorEvent): SnapshotRefreshHints;
   getFieldSnapshot(): FieldSnapshot;
+  /**
+   * CO3.5 — Field resolver exposing `resolve(entry)` for PAGE / NUMPAGES /
+   * PAGEREF / REF / STYLEREF. TOC entries return `undefined`. Reads
+   * `layoutEngine.getPageGraph()` + the active page index + the bookmark
+   * name map + paragraph start-offsets, so it updates naturally with the
+   * current document state.
+   */
+  getFieldResolver(): FieldResolver;
+  /**
+   * CO3.5 — Footnote / endnote resolver. Returns `undefined` when the
+   * document has no footnote collection attached (no `footnotes.xml`
+   * part).
+   */
+  getFootnoteResolver(): FootnoteResolver | undefined;
   updateFields(options?: UpdateFieldsOptions): UpdateFieldsResult;
   updateTableOfContents(options?: TocRefreshOptions): TocRefreshResult;
   getSessionState(): EditorSessionState;
@@ -402,6 +515,27 @@ export interface DocumentRuntime {
   setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
   clearWorkflowMetadataEntries(): void;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  /**
+   * Phase C §C1 — snapshot-based filter + join projection. See
+   * `WordReviewEditorRef.queryScopes` for contract.
+   */
+  queryScopes(filter?: ScopeQueryFilter): ScopeQueryResult[];
+  /**
+   * Phase C §C2 — geometric scope queries. See `WordReviewEditorRef`
+   * for contract. Non-range anchors yield `[]`.
+   */
+  findScopesAt(
+    position: EditorAnchorProjection,
+    options?: { includeHidden?: boolean; includeInvisible?: boolean },
+  ): ScopeQueryResult[];
+  findScopesIntersecting(
+    range: EditorAnchorProjection,
+    options?: {
+      includeHidden?: boolean;
+      includeInvisible?: boolean;
+      mode?: "overlap" | "contain";
+    },
+  ): ScopeQueryResult[];
   setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
   clearHostAnnotationOverlay(): void;
   getHostAnnotationSnapshot(): HostAnnotationSnapshot;
@@ -638,6 +772,12 @@ export function createDocumentRuntime(
   // checks this flag) runs during construction.
   let analyticsEmitScheduled = false;
 
+  // V6c — heading fingerprint for TOC auto-invalidation. Compared in notify();
+  // a mismatch schedules a microtask refresh of TOC fields.
+  let lastHeadingFingerprint: string = "";
+  let tocAutoRefreshScheduled = false;
+  let pendingTocTrigger: TocRefreshTrigger | null = null;
+
   // Schema 1.2 — editor-state channel (policy, resolver/persister, debounce queues).
   // Instantiated once per runtime; forwarded to the public interface.
   const editorStateChannel = createEditorStateChannel();
@@ -693,7 +833,21 @@ export function createDocumentRuntime(
     canonicalDocument: options.initialCanonicalDocument,
     fatalError: options.fatalError as never,
   });
+  // I2 Tier B Slice 4b — internal clipboard buffer for cut/copy. System-
+  // clipboard write lands with Slice 5 drag; for now hosts read this via
+  // `getClipboardBuffer()` and feed it to `insertFragment`.
+  let clipboardBuffer: CanonicalDocumentFragment | null = null;
+  // R.3 ObjectGrabLayer — local-only grab state for inline / floating objects.
+  // Not broadcast through collab; each peer has their own (mirrors text selection).
+  let grabState: ObjectGrabState = createObjectGrabState();
+  // R.5.a action bracketing — depth counter. `startAction` increments,
+  // `endAction` decrements (clamped at 0). `isInAction` returns `depth > 0`.
+  // Phase 2 (follow-up) will use this to gate snapshot emission so nested
+  // commands observe a single boundary.
+  let actionDepth = 0;
+  const actionStack: string[] = [];
   storySelections.set(storyTargetKey(MAIN_STORY_TARGET), state.selection);
+  lastHeadingFingerprint = computeHeadingFingerprint(state.document);
 
   // Runtime-owned paginated layout engine (Phase 1+ of the layout facet work).
   // The engine caches graph + resolved-formatting + fragment mapper keyed on
@@ -736,17 +890,18 @@ export function createDocumentRuntime(
     canonicalDocument: () => state.document,
     renderKernel: () => renderKernelRef,
     getWorkflowRailInput: () => {
-      if (!workflowOverlay) return null;
-      const activeWorkItemId = workflowOverlay.activeWorkItemId ?? null;
+      const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
+      if (!normalizedWorkflowOverlay) return null;
+      const activeWorkItemId = normalizedWorkflowOverlay.activeWorkItemId ?? null;
       const activeWorkItem =
         activeWorkItemId !== null
-          ? workflowOverlay.workItems?.find(
+          ? normalizedWorkflowOverlay.workItems?.find(
               (item) => item.workItemId === activeWorkItemId,
             )
           : undefined;
       return {
-        scopes: workflowOverlay.scopes,
-        candidates: workflowOverlay.candidates,
+        scopes: normalizedWorkflowOverlay.scopes,
+        candidates: normalizedWorkflowOverlay.candidates,
         activeWorkItemScopeIds: activeWorkItem?.scopeIds ?? [],
         activeStory,
       };
@@ -933,6 +1088,13 @@ export function createDocumentRuntime(
         snapshot: WorkflowScopeSnapshot;
       }
     | undefined;
+  let cachedNormalizedWorkflowOverlay:
+    | {
+        document: CanonicalDocumentEnvelope;
+        workflowOverlay: WorkflowOverlay;
+        normalized: WorkflowOverlay;
+      }
+    | undefined;
   let cachedWorkflowMarkupSnapshot:
     | {
         revisionToken: string;
@@ -1258,10 +1420,12 @@ export function createDocumentRuntime(
       }
     }
 
-    if (workflowOverlay) {
+    const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
+    if (normalizedWorkflowOverlay) {
       const matchingScope = getMatchingWorkflowScope(selection);
+      const activeScopes = getEffectiveWorkflowScopes(normalizedWorkflowOverlay);
 
-      if (!matchingScope && workflowOverlay.scopes.length > 0) {
+      if (!matchingScope && activeScopes.length > 0) {
         reasons.push({
           code: "outside_workflow_scope",
           message: "Selection is outside any active workflow scope.",
@@ -1557,20 +1721,114 @@ export function createDocumentRuntime(
     return left.from < right.to && right.from < left.to;
   }
 
-  function deriveWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
+  function workflowAnchorsEqual(
+    left: EditorAnchorProjection,
+    right: EditorAnchorProjection,
+  ): boolean {
+    if (left.kind !== right.kind) return false;
+    switch (left.kind) {
+      case "range":
+        return (
+          right.kind === "range" &&
+          left.from === right.from &&
+          left.to === right.to &&
+          left.assoc.start === right.assoc.start &&
+          left.assoc.end === right.assoc.end
+        );
+      case "node":
+        return right.kind === "node" && left.at === right.at;
+      case "detached":
+        return (
+          right.kind === "detached" &&
+          left.reason === right.reason &&
+          left.lastKnownRange.from === right.lastKnownRange.from &&
+          left.lastKnownRange.to === right.lastKnownRange.to
+        );
+      default:
+        return false;
+    }
+  }
+
+  function normalizeWorkflowOverlayForDocument(
+    document: CanonicalDocumentEnvelope,
+    overlay: WorkflowOverlay,
+  ): WorkflowOverlay {
+    if (
+      cachedNormalizedWorkflowOverlay &&
+      cachedNormalizedWorkflowOverlay.document === document &&
+      cachedNormalizedWorkflowOverlay.workflowOverlay === overlay
+    ) {
+      return cachedNormalizedWorkflowOverlay.normalized;
+    }
+
+    const scopeIdCounts = new Map<string, number>();
+    for (const scope of overlay.scopes) {
+      scopeIdCounts.set(scope.scopeId, (scopeIdCounts.get(scope.scopeId) ?? 0) + 1);
+    }
+    const locations = collectScopeLocations(document);
+    let changed = false;
+    const normalizedScopes = overlay.scopes.map((scope) => {
+      if ((scopeIdCounts.get(scope.scopeId) ?? 0) !== 1) {
+        return scope;
+      }
+      const location = locations.get(scope.scopeId);
+      if (
+        !location ||
+        location.startPos === undefined ||
+        location.endPos === undefined
+      ) {
+        return scope;
+      }
+      const nextAnchor: EditorAnchorProjection = {
+        kind: "range",
+        from: Math.min(location.startPos, location.endPos),
+        to: Math.max(location.startPos, location.endPos),
+        assoc: { start: -1, end: 1 },
+      };
+      if (workflowAnchorsEqual(scope.anchor, nextAnchor)) {
+        return scope;
+      }
+      changed = true;
+      return {
+        ...scope,
+        anchor: nextAnchor,
+      };
+    });
+
+    const normalized = changed
+      ? {
+          ...overlay,
+          scopes: normalizedScopes,
+        }
+      : overlay;
+    cachedNormalizedWorkflowOverlay = {
+      document,
+      workflowOverlay: overlay,
+      normalized,
+    };
+    return normalized;
+  }
+
+  function getNormalizedWorkflowOverlay(): WorkflowOverlay | null {
     if (!workflowOverlay) return null;
+    return normalizeWorkflowOverlayForDocument(state.document, workflowOverlay);
+  }
+
+  function deriveWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
+    const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
+    if (!normalizedWorkflowOverlay) return null;
     const blockedReasons = getCachedInteractionGuardSnapshot().blockedReasons;
-    const activeItem = workflowOverlay.activeWorkItemId
-      ? workflowOverlay.workItems?.find(
-          (item) => item.workItemId === workflowOverlay!.activeWorkItemId,
+    const activeItem = normalizedWorkflowOverlay.activeWorkItemId
+      ? normalizedWorkflowOverlay.workItems?.find(
+          (item) => item.workItemId === normalizedWorkflowOverlay.activeWorkItemId,
         )
       : undefined;
     return {
       overlayPresent: true,
-      activeWorkItemId: workflowOverlay.activeWorkItemId ?? null,
+      activeWorkItemId: normalizedWorkflowOverlay.activeWorkItemId ?? null,
       activeWorkItem: activeItem,
-      scopes: workflowOverlay.scopes,
-      candidates: workflowOverlay.candidates ?? [],
+      scopes: normalizedWorkflowOverlay.scopes,
+      candidates: normalizedWorkflowOverlay.candidates ?? [],
       blockedReasons,
     };
   }
@@ -1590,15 +1848,16 @@ export function createDocumentRuntime(
   }
 
   function getEffectiveWorkflowScopes(overlay: WorkflowOverlay): WorkflowOverlay["scopes"] {
-    const activeWorkItemId = overlay.activeWorkItemId ?? null;
+    const normalizedOverlay = normalizeWorkflowOverlayForDocument(state.document, overlay);
+    const activeWorkItemId = normalizedOverlay.activeWorkItemId ?? null;
     const activeWorkItemScopeIds =
       activeWorkItemId === null
         ? null
         : new Set(
-            overlay.workItems?.find((item) => item.workItemId === activeWorkItemId)?.scopeIds ?? [],
+            normalizedOverlay.workItems?.find((item) => item.workItemId === activeWorkItemId)?.scopeIds ?? [],
           );
 
-    return overlay.scopes.filter((scope) => {
+    return normalizedOverlay.scopes.filter((scope) => {
       const scopeStoryTarget = scope.storyTarget ?? MAIN_STORY_TARGET;
       if (!storyTargetsEqual(scopeStoryTarget, activeStory)) {
         return false;
@@ -1844,12 +2103,13 @@ export function createDocumentRuntime(
     const tCompat = performance.now();
     const compat = toPublicCompatibilityReport(createDerivedCompatibility(state));
     perfCounters.increment("ctxa.compat.us", Math.round((performance.now() - tCompat) * 1000));
+    const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
 
     const tBuild = performance.now();
     const snapshot = createRuntimeContextAnalyticsSnapshot({
       query,
       renderSnapshot: cachedRenderSnapshot,
-      workflowOverlay,
+      workflowOverlay: normalizedWorkflowOverlay,
       workflowScopeSnapshot: wfScope,
       interactionGuardSnapshot: wfGuard,
       workflowMarkupSnapshot: wfMarkup,
@@ -1987,6 +2247,7 @@ export function createDocumentRuntime(
       },
       surface,
       protectionSnapshot,
+      grabbedObjectId: grabState.objectId,
     };
   }
 
@@ -2022,6 +2283,47 @@ export function createDocumentRuntime(
     }
   }
 
+  function invalidateDerivedRuntimeCaches(): void {
+    cachedSurface = undefined;
+    cachedCompatibility = undefined;
+    cachedComments = undefined;
+    cachedTrackedChanges = undefined;
+    cachedSuggestions = undefined;
+    cachedReviewWork = undefined;
+    cachedPageLayout = undefined;
+    cachedNavigation = undefined;
+    cachedViewStateSnapshot = undefined;
+    cachedInteractionGuardSnapshot = undefined;
+    cachedWorkflowScopeSnapshot = undefined;
+    cachedNormalizedWorkflowOverlay = undefined;
+    cachedWorkflowMarkupSnapshot = undefined;
+    cachedContextAnalyticsSnapshots.clear();
+    lastEmittedContextAnalyticsSnapshots = undefined;
+  }
+
+  function hydrateCanonicalDocumentInternally(
+    document: CanonicalDocumentEnvelope,
+  ): boolean {
+    if (document === state.document) {
+      return false;
+    }
+    const previousDocument = state.document;
+    state = {
+      ...state,
+      document,
+    };
+    if (previousDocument.subParts !== document.subParts) {
+      fontLoader.refresh(collectFontLoaderInput(document));
+      layoutEngine.invalidateMeasurementCache();
+    }
+    invalidateDerivedRuntimeCaches();
+    cachedRenderSnapshot = refreshRenderSnapshot();
+    for (const listener of listeners) {
+      listener();
+    }
+    return true;
+  }
+
   function getCachedViewStateSnapshot(): EditorViewStateSnapshot {
     const activeStoryKey = storyTargetKey(activeStory);
     const pageLayout = cachedRenderSnapshot.pageLayout;
@@ -2131,7 +2433,11 @@ export function createDocumentRuntime(
   const r5ScratchReplayState: typeof state = { ...state };
   const r5ScratchReplaySnapshot: typeof cachedRenderSnapshot = { ...cachedRenderSnapshot };
 
-  return {
+  const runtime: DocumentRuntime & {
+    hydrateCanonicalDocumentInternally(
+      document: CanonicalDocumentEnvelope,
+    ): boolean;
+  } = {
     subscribe(listener) {
       listeners.add(listener);
       return () => {
@@ -2153,6 +2459,12 @@ export function createDocumentRuntime(
     getSourcePackage() {
       return state.sourcePackage;
     },
+    getFontTable() {
+      return state.document.fontTable;
+    },
+    getFontEntry(name: string) {
+      return state.document.fontTable?.fonts[name];
+    },
     emitBlockedCommand(command, reasons) {
       emit({
         type: "command_blocked",
@@ -2480,6 +2792,11 @@ export function createDocumentRuntime(
     insertFragment(fragment, target) {
       // I2 Tier B Slice 1 — dispatch `fragment.insert` against the active story. The
       // runtime command handler routes into `applyFragmentInsert` (structure-ops).
+      // v5 B1: auto-bracketed via R.5.a so a host that wants single-undo paste
+      // gets one action. Idempotent on nested brackets: if a caller already
+      // opened `startAction`, this bracket just increments / decrements depth.
+      actionDepth += 1;
+      actionStack.push("insertFragment");
       try {
         const timestamp = clock();
         applyTextCommandInActiveStory(
@@ -2495,8 +2812,144 @@ export function createDocumentRuntime(
         );
       } catch (error) {
         emitError(toRuntimeError(error));
+      } finally {
+        actionDepth -= 1;
+        actionStack.pop();
       }
     },
+    copy(target) {
+      // I2 Tier B Slice 4b — serialize the selection range to a fragment, store
+      // it in the internal buffer. Does NOT mutate the document.
+      // v5 A1 fix: story-aware extraction — footnote / header / endnote
+      // selections read the right content tree, not main body.
+      try {
+        const selection = target ? createSelectionFromPublicAnchor(target) : state.selection;
+        const fragment = extractSelectionFragment(state.document, selection, activeStory);
+        clipboardBuffer = fragment;
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
+    cut(target) {
+      // I2 Tier B Slice 4b — copy into buffer, then delete the range by
+      // replacing it with empty text. (Empty fragment.insert is a deliberate
+      // no-op in the splicer per Slice 1, so we use the text.insert path with
+      // an empty string to delete the selected content.)
+      // v5 B1: auto-bracketed so a host that wants single-undo paste-at-drop
+      // gets one action even if its own bracket isn't open.
+      try {
+        const selection = target ? createSelectionFromPublicAnchor(target) : state.selection;
+        const fragment = extractSelectionFragment(state.document, selection, activeStory);
+        clipboardBuffer = fragment;
+        if (selection.anchor !== selection.head) {
+          actionDepth += 1;
+          actionStack.push("cut");
+          try {
+            const timestamp = clock();
+            applyTextCommandInActiveStory(
+              {
+                type: "text.insert",
+                text: "",
+                origin: createOrigin("api", timestamp),
+              },
+              {
+                selection,
+                blockedCommandName: "cut",
+              },
+            );
+          } finally {
+            actionDepth -= 1;
+            actionStack.pop();
+          }
+        }
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
+    getClipboardBuffer() {
+      return clipboardBuffer;
+    },
+    getClipboardWireFormats() {
+      // v5 close-out — serialize the buffer to WordML + HTML + plain text for
+      // host-owned `navigator.clipboard.write`. Returns null if nothing has
+      // been cut/copied yet. Zero allocation on the null path.
+      if (!clipboardBuffer || clipboardBuffer.blocks.length === 0) return null;
+      const wordml = serializeFragmentToWordML(clipboardBuffer);
+      // Minimal HTML: walk paragraph children emitting <p> wrappers with
+      // text content. Keeps parity with our own parser (round-trips
+      // cleanly) without implementing full CSS export.
+      const htmlParts: string[] = [];
+      const plainParts: string[] = [];
+      for (const block of clipboardBuffer.blocks) {
+        if (block.type !== "paragraph") continue;
+        const runs: string[] = [];
+        const plainRuns: string[] = [];
+        for (const child of block.children) {
+          if (child.type === "text") {
+            const text = (child.text ?? "")
+              .replace(/&/g, "&amp;")
+              .replace(/</g, "&lt;")
+              .replace(/>/g, "&gt;");
+            let wrapped = text;
+            const marks = child.marks ?? [];
+            if (marks.some((m) => m.type === "bold")) wrapped = `<b>${wrapped}</b>`;
+            if (marks.some((m) => m.type === "italic")) wrapped = `<i>${wrapped}</i>`;
+            if (marks.some((m) => m.type === "underline")) wrapped = `<u>${wrapped}</u>`;
+            if (marks.some((m) => m.type === "strikethrough")) wrapped = `<s>${wrapped}</s>`;
+            runs.push(wrapped);
+            plainRuns.push(child.text ?? "");
+          } else if (child.type === "hard_break") {
+            runs.push("<br/>");
+            plainRuns.push("\n");
+          }
+        }
+        htmlParts.push(`<p>${runs.join("")}</p>`);
+        plainParts.push(plainRuns.join(""));
+      }
+      return {
+        wordml,
+        html: htmlParts.join(""),
+        plainText: plainParts.join("\n"),
+      };
+    },
+    selectObject(objectId) {
+      // R.3 — local grab state mutation. No command dispatch; this is pure UI
+      // state that chrome (Lane 6 P11) reads to paint handles.
+      //
+      // v5 A3: when the grab state actually changes, notify subscribers so
+      // chrome can re-render. We do NOT bump `revisionToken` — grab state is
+      // local UI state, not a document mutation, so collab/autosave/undo
+      // should not observe a change.
+      const next = grabSelectObject(grabState, objectId);
+      if (next === grabState) return;
+      grabState = next;
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    deselectObject() {
+      const next = grabDeselectObject(grabState);
+      if (next === grabState) return;
+      grabState = next;
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    getGrabbedObject() {
+      return grabGetGrabbedObject(grabState);
+    },
+    startAction(name) {
+      actionDepth += 1;
+      actionStack.push(name);
+    },
+    endAction() {
+      if (actionDepth === 0) return; // unbalanced — ignore
+      actionDepth -= 1;
+      actionStack.pop();
+    },
+    isInAction() {
+      return actionDepth > 0;
+    },
     applyActiveStoryTextCommand(command) {
       try {
         return applyTextCommandInActiveStory(command);
@@ -2553,15 +3006,14 @@ export function createDocumentRuntime(
         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.";
+        // Post-O8: only `invalid_comment_anchor` remains as a rejection
+        // reason (empty range / crosses opaque block / out-of-story).
         const error: InternalEditorError = {
           errorId: createSessionId("comment-anchor", clock()),
           code: "validation_failed",
           isFatal: false,
-          message,
+          message:
+            "DOCX comments must use a non-empty range that stays within a single story and does not cross table or opaque-fragment boundaries.",
           source: "runtime",
           details: {
             reason: rejectionReason,
@@ -2681,7 +3133,7 @@ export function createDocumentRuntime(
         });
       }
 
-      const resolved = resolveScope(state.document, scopeId);
+      const resolved = resolveScope(nextDocument, scopeId);
       const publicAnchor: EditorAnchorProjection =
         resolved && resolved.kind === "range"
           ? resolved
@@ -2741,21 +3193,19 @@ export function createDocumentRuntime(
       };
     },
     getScope(scopeId) {
+      const normalizedScope =
+        getNormalizedWorkflowOverlay()?.scopes.find((scope) => scope.scopeId === scopeId) ??
+        null;
+      if (normalizedScope) {
+        return normalizedScope;
+      }
       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 null;
       }
       return {
-        ...stored,
+        scopeId,
+        mode: "comment",
         anchor: resolved,
       };
     },
@@ -2907,6 +3357,33 @@ export function createDocumentRuntime(
     getDocumentNavigationSnapshot() {
       return getCachedDocumentNavigationSnapshot(state, activeStory);
     },
+    getFieldResolver(): FieldResolver {
+      const pageGraph = layoutEngine.getPageGraph({
+        document: state.document,
+        viewState: {
+          activeStory,
+          workspaceMode: viewState.workspaceMode,
+          zoomLevel: viewState.zoomLevel,
+        },
+      });
+      const navigation = getCachedDocumentNavigationSnapshot(state, activeStory);
+      const bookmarkMap = buildBookmarkNameMap(state.document);
+      const paragraphContexts = collectParagraphContexts(state.document.content.children);
+      const paragraphOffsets = paragraphContexts.map((p) => p.startOffset);
+      return createFieldResolver({
+        pageGraph,
+        activePageIndex: navigation.activePageIndex,
+        bookmarkMap,
+        paragraphOffsets,
+        styles: state.document.styles,
+        contentRoot: state.document.content as unknown as import("./field-resolver.ts").DocumentContainerNode,
+      });
+    },
+    getFootnoteResolver(): FootnoteResolver | undefined {
+      const collection = state.document.subParts?.footnoteCollection;
+      if (!collection) return undefined;
+      return createFootnoteResolver(collection, collectSectionPropertiesInOrder(state.document));
+    },
     layout: layoutFacet,
     getCurrentLocation() {
       const navigation = getCachedDocumentNavigationSnapshot(state, activeStory);
@@ -3090,6 +3567,7 @@ export function createDocumentRuntime(
     },
     getSessionState() {
       const compatibility = createDerivedCompatibility(state);
+      const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
       return editorSessionStateFromPersistedSnapshot(
         {
           ...(createPersistedEditorSnapshot(state, {
@@ -3098,7 +3576,7 @@ export function createDocumentRuntime(
             compatibility,
             protectionSnapshot,
           }) as unknown as PersistedEditorSnapshot),
-          workflowOverlay: workflowOverlay ?? undefined,
+          workflowOverlay: normalizedWorkflowOverlay ?? undefined,
           workflowMetadata: deriveWorkflowMetadataSnapshot(),
         },
       );
@@ -3144,7 +3622,7 @@ export function createDocumentRuntime(
               return { schemaVersion: "host-annotation-overlay/1", data: snap };
             }
             case "workflowOverlay": {
-              const ov = workflowOverlay;
+              const ov = getNormalizedWorkflowOverlay();
               if (!ov) return null;
               return { schemaVersion: "workflow-overlay/1", data: ov };
             }
@@ -3179,10 +3657,11 @@ export function createDocumentRuntime(
         overlay,
         origin: createOrigin("api", clock()),
       });
+      const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
       editorStateChannel.recordMutation("workflowOverlay", {
         namespace: "workflowOverlay",
         schemaVersion: "workflow-overlay/1",
-        data: overlay,
+        data: normalizedWorkflowOverlay ?? overlay,
       });
     },
     clearWorkflowOverlay() {
@@ -3192,7 +3671,7 @@ export function createDocumentRuntime(
       });
     },
     getWorkflowOverlay() {
-      return workflowOverlay;
+      return getNormalizedWorkflowOverlay();
     },
     setSharedWorkflowState(state) {
       if (state === sharedWorkflowState) return;
@@ -3244,6 +3723,40 @@ export function createDocumentRuntime(
     getWorkflowMetadataSnapshot() {
       return deriveWorkflowMetadataSnapshot();
     },
+    queryScopes(filter) {
+      return runQueryScopes(
+        {
+          overlay: workflowOverlay,
+          entries: workflowMetadataEntries,
+          document: state.document,
+        },
+        filter,
+      );
+    },
+    findScopesAt(position, options) {
+      const pos =
+        position.kind === "range"
+          ? position.from
+          : position.kind === "node"
+            ? position.at
+            : null;
+      if (pos === null) return [];
+      const hits = findAllScopesAt(state.document, pos);
+      return projectScopeQueryResults(
+        { overlay: workflowOverlay, entries: workflowMetadataEntries, document: state.document },
+        hits.map((h) => h.scopeId),
+        options,
+      );
+    },
+    findScopesIntersecting(range, options) {
+      if (range.kind !== "range") return [];
+      const hits = findScopesIntersecting(state.document, range.from, range.to, options?.mode);
+      return projectScopeQueryResults(
+        { overlay: workflowOverlay, entries: workflowMetadataEntries, document: state.document },
+        hits.map((h) => h.scopeId),
+        options,
+      );
+    },
     setHostAnnotationOverlay(overlay) {
       this.dispatch({
         type: "host-annotation.set-overlay",
@@ -3341,6 +3854,9 @@ export function createDocumentRuntime(
     get editorStateChannel() {
       return editorStateChannel;
     },
+    hydrateCanonicalDocumentInternally(document: CanonicalDocumentEnvelope) {
+      return hydrateCanonicalDocumentInternally(document);
+    },
     getPerfCountersSnapshot() {
       return perfCounters.snapshot();
     },
@@ -3364,6 +3880,8 @@ export function createDocumentRuntime(
     },
   };
 
+  return runtime;
+
   function applyHistory(direction: "undo" | "redo"): void {
     const source = direction === "undo" ? history.past : history.future;
     const target = source.pop();
@@ -3486,6 +4004,18 @@ export function createDocumentRuntime(
     next: EditorState,
     transaction: EditorTransaction,
   ): void {
+    // V6c — heading-fingerprint comparison schedules an automatic TOC rebuild
+    // when paragraph styleIds or heading text drift. Short-circuit on
+    // document-identity equality (selection-only commits) to skip the walk.
+    if (previous.document !== next.document) {
+      const nextFingerprint = computeHeadingFingerprint(next.document);
+      if (nextFingerprint !== lastHeadingFingerprint) {
+        const trigger = deriveTocTrigger(lastHeadingFingerprint, nextFingerprint);
+        lastHeadingFingerprint = nextFingerprint;
+        scheduleTocAutoRefresh(trigger);
+      }
+    }
+
     const emittedSuggestionIds = new Set<string>();
     if (previous.isDirty !== next.isDirty) {
       emit({
@@ -3982,6 +4512,80 @@ export function createDocumentRuntime(
     });
   }
 
+  // V6c — TOC auto-refresh scheduler. Mirrors scheduleContextAnalyticsEmit's
+  // microtask-coalesce shape. Bursts of heading edits within one synchronous
+  // call stack collapse to a single rebuild + a single toc_auto_refreshed
+  // event. Trigger flags accumulate across coalesced edits.
+  function scheduleTocAutoRefresh(trigger: TocRefreshTrigger): void {
+    if (pendingTocTrigger) {
+      pendingTocTrigger = {
+        headingContentChanged:
+          pendingTocTrigger.headingContentChanged || trigger.headingContentChanged,
+        headingStructureChanged:
+          pendingTocTrigger.headingStructureChanged || trigger.headingStructureChanged,
+      };
+    } else {
+      pendingTocTrigger = trigger;
+    }
+    if (tocAutoRefreshScheduled) {
+      perfCounters.increment("toc.autoRefresh.coalesced");
+      return;
+    }
+    tocAutoRefreshScheduled = true;
+    queueMicrotask(() => {
+      tocAutoRefreshScheduled = false;
+      const flushedTrigger = pendingTocTrigger;
+      pendingTocTrigger = null;
+      if (!flushedTrigger) return;
+      const t = performance.now();
+      const refreshed = refreshDocumentTableOfContents(
+        state.document,
+        state.selection.head,
+        activeStory,
+        undefined,
+        (pageIndex: number) => layoutFacet.getDisplayPageNumber(pageIndex),
+      );
+      perfCounters.increment("toc.autoRefresh.us", Math.round((performance.now() - t) * 1000));
+      if (!refreshed.changed) {
+        perfCounters.increment("toc.autoRefresh.noopRebuild");
+        return;
+      }
+      // Replay through executeEditorCommand so history, mapping, and the
+      // downstream notify() stay consistent. The replay's notify() will
+      // recompute the heading fingerprint and find no change (TOC field
+      // text is not heading text), so this does not loop.
+      const ctx = {
+        timestamp: clock(),
+        documentMode: getEffectiveDocumentMode(state.selection),
+        defaultAuthorId: defaultAuthorId ?? undefined,
+        renderSnapshot: cachedRenderSnapshot,
+      } as const;
+      try {
+        const transaction = executeEditorCommand(
+          state,
+          {
+            type: "document.replace",
+            document: refreshed.document,
+            mapping: createEmptyMapping(),
+            protectionSelection: refreshed.protectionSelection,
+            origin: createOrigin("api", clock()),
+          },
+          ctx,
+        );
+        commit(transaction);
+      } catch (error) {
+        emitError(toRuntimeError(error));
+        return;
+      }
+      emit({
+        type: "toc_auto_refreshed",
+        documentId: state.documentId,
+        entryCount: refreshed.result.entryCount,
+        trigger: flushedTrigger,
+      });
+    });
+  }
+
   function emit(event: DocumentRuntimeEvent): void {
     perfCounters.increment(`emit.${event.type}.calls`);
     const t0 = performance.now();
@@ -3998,6 +4602,7 @@ export function createDocumentRuntime(
     switch (command.type) {
       case "workflow.set-overlay": {
         workflowOverlay = structuredClone(command.overlay);
+        cachedNormalizedWorkflowOverlay = undefined;
         cachedRenderSnapshot = refreshRenderSnapshot();
         const snapshot = deriveWorkflowScopeSnapshot()!;
         emit({
@@ -4016,6 +4621,7 @@ export function createDocumentRuntime(
       }
       case "workflow.clear-overlay": {
         workflowOverlay = null;
+        cachedNormalizedWorkflowOverlay = undefined;
         cachedRenderSnapshot = refreshRenderSnapshot();
         emit({
           type: "workflow_active_work_item_changed",
@@ -4415,6 +5021,61 @@ function createSelectionFromPublicAnchor(
   }
 }
 
+/**
+ * I2 Tier B Slice 4b — extract the selection range from a document as a
+ * `CanonicalDocumentFragment`. The fragment preserves text + marks +
+ * hard-breaks + paragraph-breaks + tabs that fall inside the range.
+ *
+ * Uses the linear story layer (`parseTextStory` + `logicalPositionToUnitIndex`
+ * + `serializeTextStory`) so the result is a properly-structured block list
+ * that `insertFragment` can splice back in. Collapsed ranges return an empty
+ * fragment.
+ *
+ * Story-aware (v5 A1 fix): `activeStory` selects which content tree the
+ * selection offsets apply to. `getStoryBlocks` is the same helper
+ * `applyTextCommandInActiveStory` uses, so cut/copy in footnote / header /
+ * endnote stories extract from the right content rather than from main body.
+ *
+ * Complex content (tables, opaque blocks) inside the range serializes per
+ * the underlying story layer's semantics — for a richer table-aware
+ * clipboard, callers should use `serializeFragmentToWordML` (Slice 4a) on
+ * the result of this extraction.
+ */
+function extractSelectionFragment(
+  document: CanonicalDocumentEnvelope,
+  selection: import("../core/state/editor-state.ts").SelectionSnapshot,
+  activeStory: EditorStoryTarget,
+): CanonicalDocumentFragment {
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+  if (from === to) {
+    return { blocks: [] };
+  }
+  // Resolve the content node for the active story. For main body this is the
+  // document root; for secondary stories (header / footer / footnote / endnote)
+  // we wrap the story's blocks in a doc root so parseTextStory produces
+  // offsets in the same frame as the selection.
+  const storyBlocks = getStoryBlocks(document, activeStory);
+  const storyContent =
+    activeStory.kind === "main"
+      ? document.content
+      : { type: "doc" as const, children: [...storyBlocks] };
+  const story = parseTextStory(storyContent);
+  const unitFrom = logicalPositionToUnitIndex(story.units, from, "before");
+  const unitTo = logicalPositionToUnitIndex(story.units, to, "after");
+  const slicedUnits = story.units.slice(unitFrom, unitTo);
+  if (slicedUnits.length === 0) {
+    return { blocks: [] };
+  }
+  const slicedStory = {
+    firstParagraph: story.firstParagraph,
+    units: slicedUnits,
+    size: 0,
+  };
+  const root = serializeTextStory(slicedStory);
+  return { blocks: root.children };
+}
+
 /**
  * Collect the stable ids of comment threads whose entry differs
  * (present in one side but not the other, OR present in both but
@@ -4960,6 +5621,31 @@ function extractFieldDisplayText(field: FieldNode): string {
   return flattenInlineDisplayText(field.children);
 }
 
+// V6c — heading fingerprint over (styleId, visible text) pairs in document
+// order. Walks top-level paragraphs only; matches what
+// buildHeadingOutline()/createDocumentNavigationSnapshot read.
+function computeHeadingFingerprint(
+  document: CanonicalDocumentEnvelope,
+): string {
+  const parts: string[] = [];
+  for (const block of document.content.children) {
+    if (block.type !== "paragraph") continue;
+    const styleId = block.styleId ?? "";
+    if (!styleId.toLowerCase().startsWith("heading")) continue;
+    parts.push(`${styleId}\u0001${flattenInlineDisplayText(block.children)}`);
+  }
+  return parts.join("\u0002");
+}
+
+function deriveTocTrigger(prev: string, next: string): TocRefreshTrigger {
+  const prevCount = prev === "" ? 0 : prev.split("\u0002").length;
+  const nextCount = next === "" ? 0 : next.split("\u0002").length;
+  return {
+    headingStructureChanged: prevCount !== nextCount,
+    headingContentChanged: prevCount === nextCount,
+  };
+}
+
 function flattenInlineDisplayText(children: readonly InlineNode[]): string {
   return children
     .map((child) => {
@@ -5368,6 +6054,17 @@ function refreshBlocksWithCursor(
   return { blocks: nextBlocks, cursor, previousParagraph };
 }
 
+/**
+ * Get a ThemeColorResolver for the given document, or undefined if the
+ * document has no theme part. Use this rather than reaching into subParts.canonicalTheme.
+ */
+export function getThemeColorResolver(
+  doc: CanonicalDocument,
+): ThemeColorResolver | undefined {
+  const ct = doc.subParts?.canonicalTheme;
+  return ct ? new ThemeColorResolver(ct) : undefined;
+}
+
 function refreshInlineNodesWithCursor(
   nodes: readonly InlineNode[],
   visitField: (field: FieldNode, range: { from: number; to: number }) => FieldNode,
@@ -5701,6 +6398,28 @@ function collectParagraphContexts(blocks: readonly BlockNode[]): ParagraphContex
   return paragraphs;
 }
 
+/**
+ * Collect every section's `SectionProperties` in document order. Each
+ * `section_break` block contributes its own section; the final section
+ * (the implicit one after the last break) is read from
+ * `subParts.finalSectionProperties`. Used by `getFootnoteResolver()` so
+ * per-section `footnotePr`/`endnotePr` can be resolved by section index.
+ */
+function collectSectionPropertiesInOrder(
+  document: CanonicalDocumentEnvelope,
+): SectionProperties[] {
+  const sections: SectionProperties[] = [];
+  for (const block of document.content.children) {
+    if (block.type === "section_break" && block.sectionProperties) {
+      sections.push(block.sectionProperties);
+    }
+  }
+  if (document.subParts?.finalSectionProperties) {
+    sections.push(document.subParts.finalSectionProperties);
+  }
+  return sections;
+}
+
 function collectParagraphContextsFromBlocks(
   blocks: readonly BlockNode[],
   paragraphs: ParagraphContext[],