@beyondwork/docx-react-component 1.0.19 → 1.0.21

package/src/runtime/document-runtime.ts

@@ -17,6 +17,7 @@ import type {
   CommentSidebarSnapshot,
   CommentSidebarThreadSnapshot,
   CompatibilityReport,
+  DocumentMode,
   DocumentNavigationSnapshot,
   EditorSessionState,
   EditorAnchorProjection,
@@ -24,17 +25,31 @@ import type {
   EditorStoryTarget,
   EditorViewStateSnapshot,
   EditorWarning,
+  FieldEntrySnapshot,
+  FieldSnapshot,
   HeaderFooterLinkPatch,
   ExportDocxOptions,
   ExportResult,
+  InteractionGuardSnapshot,
   PageLayoutSnapshot,
   PersistedEditorSnapshot,
+  ProtectionSnapshot,
   RuntimeRenderSnapshot,
   SelectionSnapshot,
   StyleCatalogSnapshot,
+  TocRefreshOptions,
+  TocRefreshResult,
   TrackedChangeEntrySnapshot,
   TrackedChangesSnapshot,
+  UpdateFieldsOptions,
+  UpdateFieldsResult,
   ViewMode,
+  WorkflowCandidateRange,
+  WorkflowCandidateRangeOptions,
+  WorkflowBlockedCommandReason,
+  WorkflowMarkupSnapshot,
+  WorkflowOverlay,
+  WorkflowScopeSnapshot,
   WorkspaceMode,
   WordReviewEditorEvent,
   ZoomLevel,
@@ -53,13 +68,20 @@ import {
 import { insertText } from "../core/commands/text-commands.ts";
 import {
   createDetachedAnchor,
+  createEmptyMapping,
   createNodeAnchor,
   createRangeAnchor,
+  mapRange,
   MAIN_STORY_TARGET,
   storyTargetsEqual,
   type EditorAnchorProjection as InternalEditorAnchorProjection,
 } from "../core/selection/mapping.ts";
 import { canCreateDocxCommentAnchor } from "../core/selection/review-anchors.ts";
+import { buildBookmarkNameMap } from "../legal/bookmarks.ts";
+import {
+  describeOpaqueFragment,
+  findOpaqueFragmentsIntersectingRange,
+} from "../preservation/store.ts";
 import { createCommentSidebarProjection } from "../review/store/comment-store.ts";
 import { createCommentStoreFromRuntimeComments } from "../review/store/runtime-comment-store.ts";
 import {
@@ -69,7 +91,14 @@ import {
 import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
 import { mergeCompatibilityReports } from "../validation/compatibility-report.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
-import { createDocumentNavigationSnapshot } from "./document-navigation.ts";
+import {
+  collectWorkflowMarkupSnapshot,
+  deriveWorkflowCandidateRangesFromMarkup,
+} from "./workflow-markup.ts";
+import {
+  createDocumentNavigationSnapshot,
+  findPageForOffset,
+} from "./document-navigation.ts";
 import {
   buildPageLayoutSnapshot,
   buildResolvedSections,
@@ -80,6 +109,7 @@ import { storyTargetKey } from "./story-targeting.ts";
 import {
   createViewState,
   setViewMode as applyViewMode,
+  setDocumentMode as applyDocumentMode,
   setWorkspaceMode as applyWorkspaceMode,
   setZoomLevel as applyZoomLevel,
   setFocused as applyFocused,
@@ -89,7 +119,25 @@ import {
   createEditorViewStateSnapshot,
   type ViewState,
 } from "./view-state.ts";
-import type { PageMargins } from "../model/canonical-document.ts";
+import type {
+  BlockNode,
+  FieldNode,
+  FieldRefreshStatus,
+  InlineNode,
+  PageMargins,
+  ParagraphNode,
+  SubPartsCatalog,
+} from "../model/canonical-document.ts";
+import {
+  buildFieldRegistry,
+  isSupportedFieldFamily,
+  parseTocLevelRange,
+  resolveRefFieldText,
+} from "../io/ooxml/parse-fields.ts";
+import {
+  incrementInvalidationCounter,
+  recordPerfSample,
+} from "../ui-tailwind/editor-surface/perf-probe.ts";
 
 export type Unsubscribe = () => void;
 
@@ -111,6 +159,7 @@ export interface DocumentRuntime {
   redo(): void;
   focus(): void;
   blur(): void;
+  setDefaultAuthorId?(authorId?: string): void;
   addComment(params: AddCommentParams): string;
   openComment(commentId: string): void;
   resolveComment(commentId: string): void;
@@ -126,15 +175,27 @@ export interface DocumentRuntime {
   getActiveStory(): EditorStoryTarget;
   getViewState(): EditorViewStateSnapshot;
   setViewMode(mode: ViewMode): void;
+  setDocumentMode(mode: DocumentMode): void;
+  getProtectionSnapshot(): ProtectionSnapshot;
   setWorkspaceMode(mode: WorkspaceMode): void;
   setZoom(level: ZoomLevel): void;
   getPageLayoutSnapshot(): PageLayoutSnapshot | null;
   getDocumentNavigationSnapshot(): DocumentNavigationSnapshot;
+  getFieldSnapshot(): FieldSnapshot;
+  updateFields(options?: UpdateFieldsOptions): UpdateFieldsResult;
+  updateTableOfContents(options?: TocRefreshOptions): TocRefreshResult;
   getSessionState(): EditorSessionState;
   getPersistedSnapshot(): PersistedEditorSnapshot;
   getCompatibilityReport(): CompatibilityReport;
   getWarnings(): EditorWarning[];
   exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
+  setWorkflowOverlay(overlay: WorkflowOverlay): void;
+  clearWorkflowOverlay(): void;
+  getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
+  getInteractionGuardSnapshot(): InteractionGuardSnapshot;
+  getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
+  getWorkflowCandidateRanges(options?: WorkflowCandidateRangeOptions): WorkflowCandidateRange[];
+  replaceWorkflowMarkupText(markupId: string, text: string): void;
 }
 
 export interface CreateDocumentRuntimeOptions {
@@ -157,6 +218,7 @@ export interface CreateDocumentRuntimeOptions {
   onWarning?: (warning: EditorWarning) => void;
   onError?: (error: EditorError) => void;
   initialViewState?: Partial<ViewState>;
+  protectionSnapshot?: ProtectionSnapshot;
 }
 
 interface HistoryState {
@@ -169,6 +231,7 @@ export function createDocumentRuntime(
 ): DocumentRuntime {
   const clock = options.clock ?? (() => new Date().toISOString());
   const editorBuild = options.editorBuild ?? "dev";
+  let defaultAuthorId = options.defaultAuthorId;
   const sessionId = createSessionId(options.documentId, clock());
   const listeners = new Set<() => void>();
   const eventListeners = new Set<(event: DocumentRuntimeEvent) => void>();
@@ -180,6 +243,17 @@ export function createDocumentRuntime(
   let activeStory: EditorStoryTarget = MAIN_STORY_TARGET;
   const storySelections = new Map<string, EditorState["selection"]>();
   let viewState: ViewState = createViewState(options.initialViewState);
+  let protectionSnapshot: ProtectionSnapshot =
+    options.protectionSnapshot ??
+    options.initialSessionState?.protectionSnapshot ??
+    options.initialSnapshot?.protectionSnapshot ?? {
+    hasDocumentProtection: false,
+    enforcementActive: false,
+    ranges: [],
+    enforcedRangeCount: 0,
+    preservedRangeCount: 0,
+  };
+  let workflowOverlay: WorkflowOverlay | null = null;
   const initialPersistedSnapshot = options.initialSessionState
     ? persistedSnapshotFromEditorSessionState(options.initialSessionState, {
         savedAt: options.initialSessionState.updatedAt,
@@ -196,7 +270,573 @@ export function createDocumentRuntime(
     fatalError: options.fatalError as never,
   });
   storySelections.set(storyTargetKey(MAIN_STORY_TARGET), state.selection);
-  let cachedRenderSnapshot = createPublicRenderSnapshot(state, history, activeStory);
+  let cachedSurface:
+    | {
+        revisionToken: string;
+        activeStoryKey: string;
+        snapshot: RuntimeRenderSnapshot["surface"];
+      }
+    | undefined;
+  let cachedCompatibility:
+    | {
+        revisionToken: string;
+        warnings: EditorState["warnings"];
+        fatalError: EditorState["fatalError"];
+        report: RuntimeRenderSnapshot["compatibility"];
+      }
+    | undefined;
+  let cachedComments:
+    | {
+        comments: CanonicalDocumentEnvelope["review"]["comments"];
+        activeCommentId: EditorState["runtime"]["activeCommentId"];
+        snapshot: CommentSidebarSnapshot;
+      }
+    | undefined;
+  let cachedTrackedChanges:
+    | {
+        revisions: CanonicalDocumentEnvelope["review"]["revisions"];
+        plainText: string;
+        snapshot: TrackedChangesSnapshot;
+      }
+    | undefined;
+  let cachedPageLayout:
+    | {
+        revisionToken: string;
+        activeStoryKey: string;
+        activeSectionIndex: number | string;
+        snapshot: PageLayoutSnapshot | null;
+      }
+    | undefined;
+  let cachedNavigation:
+    | {
+        revisionToken: string;
+        activeStoryKey: string;
+        selectionHead: number;
+        snapshot: DocumentNavigationSnapshot;
+      }
+    | undefined;
+  let cachedViewStateSnapshot:
+    | {
+        revisionToken: string;
+        activeStoryKey: string;
+        selection: EditorState["selection"];
+        viewStateRef: ViewState;
+        pageLayout: PageLayoutSnapshot | null | undefined;
+        snapshot: EditorViewStateSnapshot;
+      }
+    | undefined;
+  let cachedInteractionGuardSnapshot:
+    | {
+        revisionToken: string;
+        activeStoryKey: string;
+        selection: EditorState["selection"];
+        readOnly: boolean;
+        documentMode: DocumentMode;
+        protectionSnapshot: ProtectionSnapshot;
+        workflowOverlay: WorkflowOverlay | null;
+        snapshot: InteractionGuardSnapshot;
+      }
+    | undefined;
+  let cachedWorkflowScopeSnapshot:
+    | {
+        workflowOverlay: WorkflowOverlay;
+        interactionGuardSnapshot: InteractionGuardSnapshot;
+        snapshot: WorkflowScopeSnapshot;
+      }
+    | undefined;
+
+  function getCachedSurface(
+    document: CanonicalDocumentEnvelope,
+    nextActiveStory: EditorStoryTarget,
+  ): RuntimeRenderSnapshot["surface"] {
+    const activeStoryKey = storyTargetKey(nextActiveStory);
+    if (
+      cachedSurface &&
+      cachedSurface.revisionToken === state.revisionToken &&
+      cachedSurface.activeStoryKey === activeStoryKey
+    ) {
+      return cachedSurface.snapshot;
+    }
+
+    const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory);
+    recordPerfSample("snapshot.surface");
+    incrementInvalidationCounter("runtime.snapshot.surfaceMisses");
+    cachedSurface = {
+      revisionToken: state.revisionToken,
+      activeStoryKey,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function getCachedCompatibilityReport(
+    nextState: EditorState,
+  ): RuntimeRenderSnapshot["compatibility"] {
+    if (
+      cachedCompatibility &&
+      cachedCompatibility.revisionToken === nextState.revisionToken &&
+      cachedCompatibility.warnings === nextState.warnings &&
+      cachedCompatibility.fatalError === nextState.fatalError
+    ) {
+      return cachedCompatibility.report;
+    }
+
+    const derived = createDerivedCompatibility(nextState);
+    recordPerfSample("snapshot.compatibility");
+    incrementInvalidationCounter("runtime.snapshot.compatibilityMisses");
+    const report = {
+      blockExport: derived.blockExport,
+      blockExportReasons: listBlockExportReasons(derived),
+      warningCount: derived.warnings.length,
+      errorCount: derived.errors.length,
+      featureEntries: derived.featureEntries.map((entry) =>
+        toPublicCompatibilityFeatureEntry(entry),
+      ),
+    };
+    cachedCompatibility = {
+      revisionToken: nextState.revisionToken,
+      warnings: nextState.warnings,
+      fatalError: nextState.fatalError,
+      report,
+    };
+    return report;
+  }
+
+  function getCachedCommentSidebarSnapshot(nextState: EditorState): CommentSidebarSnapshot {
+    if (
+      cachedComments &&
+      cachedComments.comments === nextState.document.review.comments &&
+      cachedComments.activeCommentId === nextState.runtime.activeCommentId
+    ) {
+      return cachedComments.snapshot;
+    }
+
+    const snapshot = toPublicCommentSidebarSnapshot(nextState);
+    cachedComments = {
+      comments: nextState.document.review.comments,
+      activeCommentId: nextState.runtime.activeCommentId,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function getCachedTrackedChangesSnapshot(
+    nextState: EditorState,
+    surface: RuntimeRenderSnapshot["surface"],
+  ): TrackedChangesSnapshot {
+    const plainText = surface?.plainText ?? "";
+    if (
+      cachedTrackedChanges &&
+      cachedTrackedChanges.revisions === nextState.document.review.revisions &&
+      cachedTrackedChanges.plainText === plainText
+    ) {
+      return cachedTrackedChanges.snapshot;
+    }
+
+    const snapshot = toPublicTrackedChangesSnapshot(nextState, plainText);
+    cachedTrackedChanges = {
+      revisions: nextState.document.review.revisions,
+      plainText,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function getCachedDocumentNavigationSnapshot(
+    nextState: EditorState,
+    nextActiveStory: EditorStoryTarget,
+  ): DocumentNavigationSnapshot {
+    const activeStoryKey = storyTargetKey(nextActiveStory);
+    if (
+      cachedNavigation &&
+      cachedNavigation.revisionToken === nextState.revisionToken &&
+      cachedNavigation.activeStoryKey === activeStoryKey
+    ) {
+      if (cachedNavigation.selectionHead === nextState.selection.head) {
+        return cachedNavigation.snapshot;
+      }
+
+      const snapshot = createDocumentNavigationSnapshot(
+        nextState.document,
+        nextState.selection.head,
+        nextActiveStory,
+      );
+      if (
+        snapshot.activePageIndex === cachedNavigation.snapshot.activePageIndex &&
+        snapshot.activeSectionIndex === cachedNavigation.snapshot.activeSectionIndex
+      ) {
+        cachedNavigation = {
+          revisionToken: nextState.revisionToken,
+          activeStoryKey,
+          selectionHead: nextState.selection.head,
+          snapshot: cachedNavigation.snapshot,
+        };
+        return cachedNavigation.snapshot;
+      }
+      cachedNavigation = {
+        revisionToken: nextState.revisionToken,
+        activeStoryKey,
+        selectionHead: nextState.selection.head,
+        snapshot,
+      };
+      return snapshot;
+    }
+
+    const snapshot = createDocumentNavigationSnapshot(
+      nextState.document,
+      nextState.selection.head,
+      nextActiveStory,
+    );
+    recordPerfSample("snapshot.navigation");
+    incrementInvalidationCounter("runtime.snapshot.navigationMisses");
+    cachedNavigation = {
+      revisionToken: nextState.revisionToken,
+      activeStoryKey,
+      selectionHead: nextState.selection.head,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function resolvePageLayoutActiveSectionIndex(
+    nextState: EditorState,
+    nextActiveStory: EditorStoryTarget,
+  ): number | string {
+    if (nextActiveStory.kind === "main") {
+      return getCachedDocumentNavigationSnapshot(nextState, nextActiveStory).activeSectionIndex;
+    }
+
+    if ("sectionIndex" in nextActiveStory && typeof nextActiveStory.sectionIndex === "number") {
+      return nextActiveStory.sectionIndex;
+    }
+
+    return storyTargetKey(nextActiveStory);
+  }
+
+  function getCachedPageLayoutSnapshot(
+    nextState: EditorState,
+    nextActiveStory: EditorStoryTarget,
+  ): PageLayoutSnapshot | null {
+    const activeStoryKey = storyTargetKey(nextActiveStory);
+    const activeSectionIndex = resolvePageLayoutActiveSectionIndex(
+      nextState,
+      nextActiveStory,
+    );
+    if (
+      cachedPageLayout &&
+      cachedPageLayout.revisionToken === nextState.revisionToken &&
+      cachedPageLayout.activeStoryKey === activeStoryKey &&
+      cachedPageLayout.activeSectionIndex === activeSectionIndex
+    ) {
+      return cachedPageLayout.snapshot;
+    }
+
+    const snapshot = derivePageLayoutSnapshot(nextState, nextActiveStory, storySelections);
+    cachedPageLayout = {
+      revisionToken: nextState.revisionToken,
+      activeStoryKey,
+      activeSectionIndex,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function evaluateWorkflowBlockedReasons(
+    selection: EditorState["selection"],
+    commandType?: string,
+  ): WorkflowBlockedCommandReason[] {
+    const reasons: WorkflowBlockedCommandReason[] = [];
+    const selectionBounds = {
+      from: Math.min(selection.anchor, selection.head),
+      to: Math.max(selection.anchor, selection.head),
+    };
+    const selectionRange = expandSelectionRange(selectionBounds);
+    const opaqueReason = deriveOpaqueWorkflowBlockedReason(selectionRange);
+
+    if (opaqueReason) {
+      reasons.push(opaqueReason);
+    }
+
+    if (state.readOnly) {
+      reasons.push({
+        code: "document_read_only",
+        message: "Document is in read-only mode.",
+      });
+    }
+
+    if (viewState.documentMode === "viewing") {
+      reasons.push({
+        code: "document_viewing_mode",
+        message: "Document is in viewing mode.",
+      });
+    }
+
+    if (
+      isBlockedByProtection(protectionSnapshot, selection)
+    ) {
+      reasons.push({
+        code: "protected_range",
+        message: "Selection falls within a protected range.",
+      });
+    }
+
+    if (workflowOverlay) {
+      const activeScopes = getEffectiveWorkflowScopes(workflowOverlay);
+      const matchingScope = activeScopes.find((scope) => {
+        if (scope.anchor.kind === "detached") return false;
+        const scopeFrom = scope.anchor.kind === "range" ? scope.anchor.from : scope.anchor.at;
+        const scopeTo = scope.anchor.kind === "range" ? scope.anchor.to : scope.anchor.at;
+        return selectionBounds.from >= scopeFrom && selectionBounds.to <= scopeTo;
+      });
+
+      if (!matchingScope && workflowOverlay.scopes.length > 0) {
+        reasons.push({
+          code: "outside_workflow_scope",
+          message: "Selection is outside any active workflow scope.",
+        });
+      } else if (matchingScope) {
+        if (matchingScope.mode === "comment") {
+          const isCommentCommand =
+            commandType?.startsWith("comment.") ?? false;
+          if (!isCommentCommand) {
+            reasons.push({
+              code: "workflow_comment_only",
+              message: `Scope "${matchingScope.label ?? matchingScope.scopeId}" allows comments only.`,
+              scopeId: matchingScope.scopeId,
+              workItemId: matchingScope.workItemId,
+            });
+          }
+        } else if (matchingScope.mode === "view") {
+          reasons.push({
+            code: "workflow_view_only",
+            message: `Scope "${matchingScope.label ?? matchingScope.scopeId}" is view-only.`,
+            scopeId: matchingScope.scopeId,
+            workItemId: matchingScope.workItemId,
+          });
+        }
+      }
+    }
+
+    return reasons;
+  }
+
+  function expandSelectionRange(
+    range: { from: number; to: number },
+  ): { from: number; to: number } {
+    return {
+      from: range.from,
+      to: range.to > range.from ? range.to : range.from + 1,
+    };
+  }
+
+  function deriveOpaqueWorkflowBlockedReason(
+    range: { from: number; to: number },
+  ): WorkflowBlockedCommandReason | null {
+    const fragments = findOpaqueFragmentsIntersectingRange(
+      state.document.preservation,
+      range,
+    );
+
+    if (fragments.length === 0) {
+      return null;
+    }
+
+    const blockedImportFeatureKeys = new Set([
+      "alt-chunk",
+      "alternate-content",
+      "custom-xml",
+    ]);
+    const blockedImportFragment =
+      fragments.find((fragment) =>
+        blockedImportFeatureKeys.has(describeOpaqueFragment(fragment).featureKey),
+      ) ?? null;
+    const fragment = blockedImportFragment ?? fragments[0]!;
+    const descriptor = describeOpaqueFragment(fragment);
+    const isBlockedImport = blockedImportFragment !== null;
+
+    return {
+      code: isBlockedImport ? "workflow_blocked_import" : "workflow_preserve_only",
+      message: isBlockedImport
+        ? `${descriptor.label} remains a blocked import and cannot be edited.`
+        : `${descriptor.label} remains preserve-only and cannot be edited.`,
+      anchor: toPublicAnchorProjection(
+        createRangeAnchor(fragment.lastKnownRange.from, fragment.lastKnownRange.to, {
+          start: -1,
+          end: 1,
+        }),
+      ),
+      storyTarget: activeStory,
+    };
+  }
+
+  function deriveWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
+    if (!workflowOverlay) return null;
+    const blockedReasons = getCachedInteractionGuardSnapshot().blockedReasons;
+    const activeItem = workflowOverlay.activeWorkItemId
+      ? workflowOverlay.workItems?.find(
+          (item) => item.workItemId === workflowOverlay!.activeWorkItemId,
+        )
+      : undefined;
+    return {
+      overlayPresent: true,
+      activeWorkItemId: workflowOverlay.activeWorkItemId ?? null,
+      activeWorkItem: activeItem,
+      scopes: workflowOverlay.scopes,
+      candidates: workflowOverlay.candidates ?? [],
+      blockedReasons,
+    };
+  }
+
+  function getEffectiveWorkflowScopes(overlay: WorkflowOverlay): WorkflowOverlay["scopes"] {
+    const activeWorkItemId = overlay.activeWorkItemId ?? null;
+    const activeWorkItemScopeIds =
+      activeWorkItemId === null
+        ? null
+        : new Set(
+            overlay.workItems?.find((item) => item.workItemId === activeWorkItemId)?.scopeIds ?? [],
+          );
+
+    return overlay.scopes.filter((scope) => {
+      const scopeStoryTarget = scope.storyTarget ?? MAIN_STORY_TARGET;
+      if (!storyTargetsEqual(scopeStoryTarget, activeStory)) {
+        return false;
+      }
+
+      if (activeWorkItemId === null) {
+        return true;
+      }
+
+      return (
+        scope.workItemId === activeWorkItemId ||
+        activeWorkItemScopeIds?.has(scope.scopeId) === true
+      );
+    });
+  }
+
+  function getCachedInteractionGuardSnapshot(): InteractionGuardSnapshot {
+    const activeStoryKey = storyTargetKey(activeStory);
+    if (
+      cachedInteractionGuardSnapshot &&
+      cachedInteractionGuardSnapshot.revisionToken === state.revisionToken &&
+      cachedInteractionGuardSnapshot.activeStoryKey === activeStoryKey &&
+      cachedInteractionGuardSnapshot.selection === state.selection &&
+      cachedInteractionGuardSnapshot.readOnly === state.readOnly &&
+      cachedInteractionGuardSnapshot.documentMode === viewState.documentMode &&
+      cachedInteractionGuardSnapshot.protectionSnapshot === protectionSnapshot &&
+      cachedInteractionGuardSnapshot.workflowOverlay === workflowOverlay
+    ) {
+      return cachedInteractionGuardSnapshot.snapshot;
+    }
+
+    const snapshot = {
+      blockedReasons: evaluateWorkflowBlockedReasons(state.selection),
+    };
+    cachedInteractionGuardSnapshot = {
+      revisionToken: state.revisionToken,
+      activeStoryKey,
+      selection: state.selection,
+      readOnly: state.readOnly,
+      documentMode: viewState.documentMode,
+      protectionSnapshot,
+      workflowOverlay,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function getCachedWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
+    if (!workflowOverlay) {
+      return null;
+    }
+
+    const interactionGuardSnapshot = getCachedInteractionGuardSnapshot();
+    if (
+      cachedWorkflowScopeSnapshot &&
+      cachedWorkflowScopeSnapshot.workflowOverlay === workflowOverlay &&
+      cachedWorkflowScopeSnapshot.interactionGuardSnapshot === interactionGuardSnapshot
+    ) {
+      return cachedWorkflowScopeSnapshot.snapshot;
+    }
+
+    const snapshot = deriveWorkflowScopeSnapshot()!;
+    cachedWorkflowScopeSnapshot = {
+      workflowOverlay,
+      interactionGuardSnapshot,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function refreshRenderSnapshot(): RuntimeRenderSnapshot {
+    const surface = getCachedSurface(state.document, activeStory);
+    return {
+      documentId: state.documentId,
+      sessionId: state.sessionId,
+      sourceLabel: state.sourceLabel,
+      revisionToken: state.revisionToken,
+      isReady: state.phase === "ready",
+      isDirty: state.isDirty,
+      readOnly: state.readOnly,
+      documentMode: viewState.documentMode,
+      selection: toPublicSelectionSnapshot(state.selection, activeStory),
+      activeStory,
+      pageLayout: getCachedPageLayoutSnapshot(state, activeStory) ?? undefined,
+      documentStats: toPublicDocumentStats(state),
+      comments: getCachedCommentSidebarSnapshot(state),
+      trackedChanges: getCachedTrackedChangesSnapshot(state, surface),
+      compatibility: getCachedCompatibilityReport(state),
+      warnings: state.warnings.map((warning) => toPublicWarning(warning)),
+      fatalError: state.fatalError ? toPublicError(state.fatalError) : undefined,
+      commandState: {
+        canUndo: history.past.length > 0,
+        canRedo: history.future.length > 0,
+        readOnly: state.readOnly,
+      },
+      surface,
+      protectionSnapshot,
+    };
+  }
+
+  function getCachedViewStateSnapshot(): EditorViewStateSnapshot {
+    const activeStoryKey = storyTargetKey(activeStory);
+    const pageLayout = cachedRenderSnapshot.pageLayout;
+    if (
+      cachedViewStateSnapshot &&
+      cachedViewStateSnapshot.revisionToken === state.revisionToken &&
+      cachedViewStateSnapshot.activeStoryKey === activeStoryKey &&
+      cachedViewStateSnapshot.selection === state.selection &&
+      cachedViewStateSnapshot.viewStateRef === viewState &&
+      cachedViewStateSnapshot.pageLayout === pageLayout
+    ) {
+      return cachedViewStateSnapshot.snapshot;
+    }
+
+    const surface = cachedRenderSnapshot.surface;
+    const mainSurface =
+      activeStory.kind === "main"
+        ? surface
+        : getCachedSurface(state.document, MAIN_STORY_TARGET);
+    const snapshot = createEditorViewStateSnapshot(
+      viewState,
+      activeStory,
+      toPublicSelectionSnapshot(state.selection, activeStory),
+      surface,
+      mainSurface,
+      pageLayout,
+      state.document.numbering,
+    );
+    cachedViewStateSnapshot = {
+      revisionToken: state.revisionToken,
+      activeStoryKey,
+      selection: state.selection,
+      viewStateRef: viewState,
+      pageLayout,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  let cachedRenderSnapshot = refreshRenderSnapshot();
 
   emit({
     type: "ready",
@@ -239,16 +879,33 @@ export function createDocumentRuntime(
       return cachedRenderSnapshot;
     },
     dispatch(command) {
+      if (isMutationCommand(command)) {
+        const blockedReasons = evaluateWorkflowBlockedReasons(
+          getCommandSelection(command, state.selection),
+          command.type,
+        );
+        if (blockedReasons.length > 0) {
+          emit({
+            type: "command_blocked",
+            documentId: state.documentId,
+            command: command.type,
+            reasons: blockedReasons,
+          });
+          return;
+        }
+      }
+
       if (command.type === "history.undo") {
+        if (viewState.documentMode === "viewing") return;
         applyHistory("undo");
         return;
       }
 
       if (command.type === "history.redo") {
+        if (viewState.documentMode === "viewing") return;
         applyHistory("redo");
         return;
       }
-
       try {
         const transaction = executeEditorCommand(state, command, {
           timestamp: command.origin?.timestamp ?? clock(),
@@ -286,12 +943,25 @@ export function createDocumentRuntime(
         origin: createOrigin("api", clock()),
       });
     },
+    setDefaultAuthorId(authorId) {
+      defaultAuthorId = authorId;
+    },
     replaceText(text, target) {
       try {
         const timestamp = clock();
         const selection = target
           ? createSelectionFromPublicAnchor(target)
           : state.selection;
+        const blockedReasons = evaluateWorkflowBlockedReasons(selection, "text.insert");
+        if (blockedReasons.length > 0) {
+          emit({
+            type: "command_blocked",
+            documentId: state.documentId,
+            command: "replaceText",
+            reasons: blockedReasons,
+          });
+          return;
+        }
         const result = insertText(state.document, selection, text, { timestamp });
 
         this.dispatch({
@@ -299,6 +969,7 @@ export function createDocumentRuntime(
           document: result.document,
           mapping: result.mapping,
           selection: result.selection,
+          protectionSelection: selection,
           origin: createOrigin("api", timestamp),
         });
       } catch (error) {
@@ -306,10 +977,16 @@ export function createDocumentRuntime(
       }
     },
     addComment(params) {
+      if (viewState.documentMode === "viewing") {
+        throw new Error("Cannot add comments in viewing mode.");
+      }
       const commentId = createEntityId("comment", state.document.review.comments, clock());
       const anchor = params.anchor
         ? toInternalAnchorProjection(params.anchor)
         : state.selection.activeRange;
+      const selection = params.anchor
+        ? createSelectionFromPublicAnchor(params.anchor)
+        : state.selection;
       if (!canCreateDocxCommentAnchor(state.document.content, anchor)) {
         const message =
           "DOCX comments must use a non-empty range that stays within a single paragraph.";
@@ -322,7 +999,7 @@ export function createDocumentRuntime(
         });
         throw new Error(message);
       }
-      const authorId = params.authorId ?? options.defaultAuthorId ?? "unknown";
+      const authorId = params.authorId ?? defaultAuthorId ?? "unknown";
       const createdAt = clock();
       const entries: CommentEntryRecord[] = [
         {
@@ -351,6 +1028,7 @@ export function createDocumentRuntime(
       this.dispatch({
         type: "comment.add",
         comment,
+        selection,
         origin: createOrigin("api", clock()),
       });
 
@@ -367,7 +1045,7 @@ export function createDocumentRuntime(
       this.dispatch({
         type: "comment.resolve",
         commentId,
-        resolvedBy: options.defaultAuthorId ?? "unknown",
+        resolvedBy: defaultAuthorId ?? "unknown",
         origin: createOrigin("api", clock()),
       });
     },
@@ -383,7 +1061,7 @@ export function createDocumentRuntime(
         type: "comment.add-reply",
         commentId,
         body,
-        authorId: authorId ?? options.defaultAuthorId,
+        authorId: authorId ?? defaultAuthorId,
         origin: createOrigin("api", clock()),
       });
     },
@@ -449,51 +1127,88 @@ export function createDocumentRuntime(
       return activeStory;
     },
     getViewState() {
-      const surface = cachedRenderSnapshot.surface;
-      const mainSurface =
-        activeStory.kind === "main"
-          ? surface
-          : createEditorSurfaceSnapshot(state.document, state.selection, MAIN_STORY_TARGET);
-      return createEditorViewStateSnapshot(
-        viewState,
-        activeStory,
-        toPublicSelectionSnapshot(state.selection, activeStory),
-        surface,
-        mainSurface,
-        cachedRenderSnapshot.pageLayout,
-        state.document.numbering,
-      );
+      return getCachedViewStateSnapshot();
     },
     setViewMode(mode) {
       viewState = applyViewMode(viewState, mode);
-      cachedRenderSnapshot = createPublicRenderSnapshot(state, history, activeStory);
+      cachedRenderSnapshot = refreshRenderSnapshot();
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    setDocumentMode(mode) {
+      viewState = applyDocumentMode(viewState, mode);
+      cachedRenderSnapshot = refreshRenderSnapshot();
       for (const listener of listeners) {
         listener();
       }
     },
+    getProtectionSnapshot() {
+      return cachedRenderSnapshot.protectionSnapshot;
+    },
     setWorkspaceMode(mode) {
       viewState = applyWorkspaceMode(viewState, mode);
-      cachedRenderSnapshot = createPublicRenderSnapshot(state, history, activeStory);
+      cachedRenderSnapshot = refreshRenderSnapshot();
       for (const listener of listeners) {
         listener();
       }
     },
     setZoom(level) {
       viewState = applyZoomLevel(viewState, level);
-      cachedRenderSnapshot = createPublicRenderSnapshot(state, history, activeStory);
+      cachedRenderSnapshot = refreshRenderSnapshot();
       for (const listener of listeners) {
         listener();
       }
     },
     getPageLayoutSnapshot() {
-      return derivePageLayoutSnapshot(state, activeStory, storySelections);
+      return getCachedPageLayoutSnapshot(state, activeStory);
     },
     getDocumentNavigationSnapshot() {
-      return createDocumentNavigationSnapshot(
+      return getCachedDocumentNavigationSnapshot(state, activeStory);
+    },
+    getFieldSnapshot() {
+      return buildFieldSnapshot(state.document);
+    },
+    updateFields(options?: UpdateFieldsOptions): UpdateFieldsResult {
+      const refreshed = refreshDocumentFields(
+        state.document,
+        state.selection.head,
+        activeStory,
+        options,
+      );
+      if (refreshed.changed) {
+        this.dispatch({
+          type: "document.replace",
+          document: refreshed.document,
+          mapping: createEmptyMapping(),
+          protectionSelection: refreshed.protectionSelection,
+          origin: createOrigin("api", clock()),
+        });
+      }
+      const snapshot = buildFieldSnapshot(refreshed.document);
+      return {
+        totalCount: snapshot.totalCount,
+        updatedCount: refreshed.updatedCount,
+        preserveOnlyCount: snapshot.preserveOnlyCount,
+      };
+    },
+    updateTableOfContents(options?: TocRefreshOptions): TocRefreshResult {
+      const refreshed = refreshDocumentTableOfContents(
         state.document,
         state.selection.head,
         activeStory,
+        options,
       );
+      if (refreshed.changed) {
+        this.dispatch({
+          type: "document.replace",
+          document: refreshed.document,
+          mapping: createEmptyMapping(),
+          protectionSelection: refreshed.protectionSelection,
+          origin: createOrigin("api", clock()),
+        });
+      }
+      return refreshed.result;
     },
     getSessionState() {
       const compatibility = createDerivedCompatibility(state);
@@ -502,6 +1217,7 @@ export function createDocumentRuntime(
           editorBuild,
           savedAt: clock(),
           compatibility,
+          protectionSnapshot,
         }) as unknown as PersistedEditorSnapshot,
       );
     },
@@ -542,6 +1258,75 @@ export function createDocumentRuntime(
 
       return result;
     },
+    setWorkflowOverlay(overlay) {
+      workflowOverlay = structuredClone(overlay);
+      cachedRenderSnapshot = refreshRenderSnapshot();
+      const snapshot = deriveWorkflowScopeSnapshot()!;
+      emit({
+        type: "workflow_overlay_changed",
+        documentId: state.documentId,
+        snapshot,
+      });
+      if (workflowOverlay.activeWorkItemId !== undefined) {
+        emit({
+          type: "workflow_active_work_item_changed",
+          documentId: state.documentId,
+          activeWorkItemId: workflowOverlay.activeWorkItemId ?? null,
+        });
+      }
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    clearWorkflowOverlay() {
+      workflowOverlay = null;
+      cachedRenderSnapshot = refreshRenderSnapshot();
+      emit({
+        type: "workflow_active_work_item_changed",
+        documentId: state.documentId,
+        activeWorkItemId: null,
+      });
+      emit({
+        type: "workflow_overlay_changed",
+        documentId: state.documentId,
+        snapshot: {
+          overlayPresent: false,
+          activeWorkItemId: null,
+          scopes: [],
+          candidates: [],
+          blockedReasons: [],
+        },
+      });
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    getWorkflowScopeSnapshot() {
+      return getCachedWorkflowScopeSnapshot();
+    },
+    getInteractionGuardSnapshot() {
+      return getCachedInteractionGuardSnapshot();
+    },
+    getWorkflowMarkupSnapshot() {
+      return collectWorkflowMarkupSnapshot({
+        renderSnapshot: this.getRenderSnapshot(),
+        fieldSnapshot: this.getFieldSnapshot(),
+        protectionSnapshot,
+        preservation: state.document.preservation,
+      });
+    },
+    getWorkflowCandidateRanges(options) {
+      return deriveWorkflowCandidateRangesFromMarkup(this.getWorkflowMarkupSnapshot(), options);
+    },
+    replaceWorkflowMarkupText(markupId, text) {
+      const target = this
+        .getWorkflowMarkupSnapshot()
+        .items.find((item) => item.markupId === markupId);
+      if (!target || target.anchor.kind === "detached") {
+        return;
+      }
+      this.replaceText(text, target.anchor);
+    },
   };
 
   function applyHistory(direction: "undo" | "redo"): void {
@@ -560,7 +1345,7 @@ export function createDocumentRuntime(
     // autosave/export checkpoint dedup treats it as fresh content.
     state = finalizeState(target, true, clock());
     storySelections.set(storyTargetKey(activeStory), state.selection);
-    cachedRenderSnapshot = createPublicRenderSnapshot(state, history, activeStory);
+    cachedRenderSnapshot = refreshRenderSnapshot();
     notify(previous, state, {
       nextState: state,
       mapping: { steps: [] },
@@ -581,9 +1366,10 @@ export function createDocumentRuntime(
       history.future = [];
     }
 
+    protectionSnapshot = remapProtectionSnapshot(protectionSnapshot, transaction.mapping);
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
     storySelections.set(storyTargetKey(activeStory), state.selection);
-    cachedRenderSnapshot = createPublicRenderSnapshot(state, history, activeStory);
+    cachedRenderSnapshot = refreshRenderSnapshot();
     notify(previous, state, transaction);
   }
 
@@ -680,7 +1466,7 @@ export function createDocumentRuntime(
     };
     state = nextState;
     storySelections.set(storyTargetKey(activeStory), state.selection);
-    cachedRenderSnapshot = createPublicRenderSnapshot(state, history, activeStory);
+    cachedRenderSnapshot = refreshRenderSnapshot();
     const publicError = toPublicError(error);
     options.onError?.(publicError);
     emit({
@@ -706,7 +1492,7 @@ export function createDocumentRuntime(
       selection: restoredSelection,
     };
     storySelections.set(storyTargetKey(target), restoredSelection);
-    cachedRenderSnapshot = createPublicRenderSnapshot(state, history, activeStory);
+    cachedRenderSnapshot = refreshRenderSnapshot();
 
     if (selectionChanged(previousSelection, restoredSelection)) {
       emit({
@@ -800,51 +1586,6 @@ function toRuntimeError(error: unknown): InternalEditorError {
   };
 }
 
-function createPublicRenderSnapshot(
-  state: EditorState,
-  history: HistoryState,
-  activeStory: EditorStoryTarget,
-): RuntimeRenderSnapshot {
-  const compatibility = createDerivedCompatibility(state);
-  const surface = createEditorSurfaceSnapshot(state.document, state.selection, activeStory);
-  const comments = toPublicCommentSidebarSnapshot(state);
-  const trackedChanges = toPublicTrackedChangesSnapshot(state, surface.plainText);
-  const pageLayout = derivePageLayoutSnapshot(state, activeStory);
-
-  return {
-    documentId: state.documentId,
-    sessionId: state.sessionId,
-    sourceLabel: state.sourceLabel,
-    revisionToken: state.revisionToken,
-    isReady: state.phase === "ready",
-    isDirty: state.isDirty,
-    readOnly: state.readOnly,
-    selection: toPublicSelectionSnapshot(state.selection, activeStory),
-    activeStory,
-    pageLayout: pageLayout ?? undefined,
-    documentStats: toPublicDocumentStats(state),
-    comments,
-    trackedChanges,
-    compatibility: {
-      blockExport: compatibility.blockExport,
-      blockExportReasons: listBlockExportReasons(compatibility),
-      warningCount: compatibility.warnings.length,
-      errorCount: compatibility.errors.length,
-      featureEntries: compatibility.featureEntries.map((entry) =>
-        toPublicCompatibilityFeatureEntry(entry),
-      ),
-    },
-    warnings: state.warnings.map((warning) => toPublicWarning(warning)),
-    fatalError: state.fatalError ? toPublicError(state.fatalError) : undefined,
-    commandState: {
-      canUndo: history.past.length > 0,
-      canRedo: history.future.length > 0,
-      readOnly: state.readOnly,
-    },
-    surface,
-  };
-}
-
 function toPublicDocumentStats(state: Pick<EditorState, "document">) {
   const stats = deriveDocumentStats(state);
   return {
@@ -1259,3 +2000,708 @@ function derivePageLayoutSnapshot(
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+
+/** Commands that are safe in viewing mode (no document mutation). */
+const NON_MUTATION_COMMANDS = new Set([
+  "selection.set",
+  "runtime.set-read-only",
+  "runtime.focus",
+  "warning.add",
+  "warning.clear",
+  "comment.open",
+]);
+
+function isMutationCommand(command: EditorCommand): boolean {
+  return !NON_MUTATION_COMMANDS.has(command.type);
+}
+
+// ── Field snapshot helpers ──────────────────────────────────────────────────
+
+function buildFieldSnapshot(document: CanonicalDocumentEnvelope): FieldSnapshot {
+  const entries: FieldEntrySnapshot[] = [];
+  let index = 0;
+  for (const block of document.content.children) {
+    index = collectFieldsFromBlock(block, entries, index);
+  }
+  index = collectFieldsFromSubParts(document.subParts, entries, index);
+  const supportedCount = entries.filter((e) => e.supported).length;
+  return {
+    totalCount: entries.length,
+    supportedCount,
+    preserveOnlyCount: entries.length - supportedCount,
+    fields: entries,
+  };
+}
+
+function collectFieldsFromBlock(
+  block: BlockNode,
+  entries: FieldEntrySnapshot[],
+  index: number,
+): number {
+  if (block.type === "paragraph") {
+    for (const child of block.children) {
+      index = collectFieldsFromInline(child, entries, index);
+    }
+  } else if (block.type === "table") {
+    for (const row of block.rows) {
+      for (const cell of row.cells) {
+        for (const child of cell.children) {
+          index = collectFieldsFromBlock(child, entries, index);
+        }
+      }
+    }
+  } else if (block.type === "sdt" || block.type === "custom_xml") {
+    for (const child of block.children) {
+      index = collectFieldsFromBlock(child, entries, index);
+    }
+  }
+  return index;
+}
+
+function collectFieldsFromInline(
+  node: InlineNode,
+  entries: FieldEntrySnapshot[],
+  index: number,
+): number {
+  if (node.type === "field") {
+    const fieldFamily = node.fieldFamily ?? "UNKNOWN";
+    const supported = isSupportedFieldFamily(fieldFamily);
+    const displayText = extractFieldDisplayText(node);
+    entries.push({
+      index,
+      fieldFamily,
+      supported,
+      instruction: node.instruction,
+      fieldTarget: node.fieldTarget,
+      refreshStatus: node.refreshStatus ?? (supported ? "stale" : "preserve-only"),
+      displayText,
+    });
+    index++;
+    // Also walk children — fields can contain nested fields
+    for (const child of node.children) {
+      index = collectFieldsFromInline(child, entries, index);
+    }
+  } else if (node.type === "hyperlink") {
+    for (const child of node.children) {
+      index = collectFieldsFromInline(child, entries, index);
+    }
+  }
+  return index;
+}
+
+function extractFieldDisplayText(field: FieldNode): string {
+  return flattenInlineDisplayText(field.children);
+}
+
+function flattenInlineDisplayText(children: readonly InlineNode[]): string {
+  return children
+    .map((child) => {
+      switch (child.type) {
+        case "text":
+          return child.text;
+        case "tab":
+          return "\t";
+        case "hard_break":
+        case "column_break":
+          return "\n";
+        case "hyperlink":
+        case "field":
+          return flattenInlineDisplayText(child.children);
+        case "footnote_ref":
+          return child.noteId;
+        default:
+          return "";
+      }
+    })
+    .join("");
+}
+
+function refreshDocumentFields(
+  document: CanonicalDocumentEnvelope,
+  selectionHead: number,
+  activeStory: EditorStoryTarget,
+  options?: UpdateFieldsOptions,
+): {
+  document: CanonicalDocumentEnvelope;
+  updatedCount: number;
+  changed: boolean;
+  protectionSelection?: import("../core/state/editor-state.ts").SelectionSnapshot;
+} {
+  const supportedOnly = options?.supportedOnly ?? true;
+  const bookmarkMap = buildBookmarkNameMap(document);
+  const paragraphs = collectParagraphContexts(document.content.children);
+  const navigation = createDocumentNavigationSnapshot(document, selectionHead, activeStory);
+  let updatedCount = 0;
+  let changed = false;
+  let changedFrom: number | undefined;
+  let changedTo: number | undefined;
+
+  const nextChildren = refreshBlocksWithCursor(document.content.children, (field, range) => {
+    if (!field.fieldFamily || !isSupportedFieldFamily(field.fieldFamily)) {
+      return field;
+    }
+    if (supportedOnly && field.fieldFamily === "TOC") {
+      return field;
+    }
+    const display = resolveSupportedFieldDisplay(
+      field,
+      document,
+      bookmarkMap,
+      paragraphs,
+      navigation,
+    );
+    if (!display) {
+      return field;
+    }
+    updatedCount += 1;
+    const nextField: FieldNode = {
+      ...field,
+      children: buildInlineNodesFromDisplayText(display.displayText),
+      refreshStatus: display.refreshStatus,
+    };
+    if (
+      nextField.refreshStatus !== field.refreshStatus ||
+      flattenInlineDisplayText(nextField.children) !== flattenInlineDisplayText(field.children)
+    ) {
+      changed = true;
+      changedFrom = changedFrom === undefined ? range.from : Math.min(changedFrom, range.from);
+      changedTo = changedTo === undefined ? range.to : Math.max(changedTo, range.to);
+    }
+    return nextField;
+  }).blocks;
+  if (!changed) {
+    return { document, updatedCount, changed: false };
+  }
+
+  const nextDocument: CanonicalDocumentEnvelope = {
+    ...document,
+    content: {
+      ...document.content,
+      children: nextChildren,
+    },
+  };
+  const nextRegistry = buildFieldRegistry({
+    content: nextDocument.content,
+    styles: nextDocument.styles,
+    subParts: nextDocument.subParts,
+  });
+  nextDocument.fieldRegistry = nextRegistry;
+  let protectionSelection:
+    | import("../core/state/editor-state.ts").SelectionSnapshot
+    | undefined;
+  if (changedFrom !== undefined && changedTo !== undefined) {
+    protectionSelection = createSelectionSnapshot(changedFrom, changedTo);
+  }
+  return {
+    document: nextDocument,
+    updatedCount,
+    changed: true,
+    ...(protectionSelection ? { protectionSelection } : {}),
+  };
+}
+
+function refreshDocumentTableOfContents(
+  document: CanonicalDocumentEnvelope,
+  selectionHead: number,
+  activeStory: EditorStoryTarget,
+  options?: TocRefreshOptions,
+): {
+  document: CanonicalDocumentEnvelope;
+  result: TocRefreshResult;
+  changed: boolean;
+  protectionSelection?: import("../core/state/editor-state.ts").SelectionSnapshot;
+} {
+  const navigation = createDocumentNavigationSnapshot(document, selectionHead, activeStory);
+  let changed = false;
+  let resultEntries: Array<{ level: number; text: string; pageIndex: number }> = [];
+  let changedFrom: number | undefined;
+  let changedTo: number | undefined;
+  const nextChildren = refreshBlocksWithCursor(document.content.children, (field, range) => {
+    if (field.fieldFamily !== "TOC") {
+      return field;
+    }
+    const levelRange = options?.maxLevel
+      ? { from: 1, to: options.maxLevel }
+      : parseTocLevelRange(field.instruction);
+    const entries = navigation.headings
+      .filter((heading) => heading.level >= levelRange.from && heading.level <= levelRange.to)
+      .map((heading) => ({
+        level: heading.level,
+        text: heading.text,
+        pageIndex: heading.pageIndex,
+      }));
+    if (resultEntries.length === 0) {
+      resultEntries = entries;
+    }
+    const nextField: FieldNode = {
+      ...field,
+      children: buildTocInlineNodes(entries),
+      refreshStatus: "current",
+    };
+    if (flattenInlineDisplayText(nextField.children) !== flattenInlineDisplayText(field.children)) {
+      changed = true;
+      changedFrom = changedFrom === undefined ? range.from : Math.min(changedFrom, range.from);
+      changedTo = changedTo === undefined ? range.to : Math.max(changedTo, range.to);
+    }
+    return nextField;
+  }).blocks;
+  if (!changed) {
+    return {
+      document,
+      result: { entryCount: resultEntries.length, entries: resultEntries },
+      changed: false,
+    };
+  }
+
+  const nextDocument: CanonicalDocumentEnvelope = {
+    ...document,
+    content: {
+      ...document.content,
+      children: nextChildren,
+    },
+  };
+  const nextRegistry = buildFieldRegistry({
+    content: nextDocument.content,
+    styles: nextDocument.styles,
+    subParts: nextDocument.subParts,
+  });
+  nextDocument.fieldRegistry = nextRegistry.tocStructure
+    ? {
+        ...nextRegistry,
+        tocStructure: {
+          ...nextRegistry.tocStructure,
+          status: "current",
+        },
+      }
+    : nextRegistry;
+  let protectionSelection:
+    | import("../core/state/editor-state.ts").SelectionSnapshot
+    | undefined;
+  if (changedFrom !== undefined && changedTo !== undefined) {
+    protectionSelection = createSelectionSnapshot(changedFrom, changedTo);
+  }
+
+  return {
+    document: nextDocument,
+    result: { entryCount: resultEntries.length, entries: resultEntries },
+    changed: true,
+    ...(protectionSelection ? { protectionSelection } : {}),
+  };
+}
+
+function refreshBlocksWithCursor(
+  blocks: readonly BlockNode[],
+  visitField: (field: FieldNode, range: { from: number; to: number }) => FieldNode,
+  cursor = 0,
+  previousParagraph = false,
+): {
+  blocks: BlockNode[];
+  cursor: number;
+  previousParagraph: boolean;
+} {
+  const nextBlocks = blocks.map((block) => {
+    if (block.type === "paragraph") {
+      const paragraphStart = previousParagraph ? cursor + 1 : cursor;
+      const refreshedChildren = refreshInlineNodesWithCursor(
+        block.children,
+        visitField,
+        paragraphStart,
+      );
+      cursor = paragraphStart + refreshedChildren.cursor;
+      previousParagraph = true;
+      return {
+        ...block,
+        children: refreshedChildren.nodes,
+      };
+    }
+    if (block.type === "table") {
+      cursor += 1;
+      previousParagraph = false;
+      return {
+        ...block,
+        rows: block.rows.map((row) => ({
+          ...row,
+          cells: row.cells.map((cell) => ({
+            ...cell,
+            children: (() => {
+              const refreshed = refreshBlocksWithCursor(cell.children, visitField, cursor, false);
+              cursor = refreshed.cursor;
+              return refreshed.blocks;
+            })(),
+          })),
+        })),
+      };
+    }
+    if (block.type === "sdt" || block.type === "custom_xml") {
+      const refreshed = refreshBlocksWithCursor(
+        block.children,
+        visitField,
+        cursor,
+        previousParagraph,
+      );
+      cursor = refreshed.cursor;
+      previousParagraph = refreshed.previousParagraph;
+      return {
+        ...block,
+        children: refreshed.blocks,
+      };
+    }
+    cursor += 1;
+    previousParagraph = false;
+    return block;
+  });
+  return { blocks: nextBlocks, cursor, previousParagraph };
+}
+
+function refreshInlineNodesWithCursor(
+  nodes: readonly InlineNode[],
+  visitField: (field: FieldNode, range: { from: number; to: number }) => FieldNode,
+  cursor = 0,
+): {
+  nodes: InlineNode[];
+  cursor: number;
+} {
+  const nextNodes = nodes.map((node) => {
+    if (node.type === "field") {
+      const fieldStart = cursor;
+      const refreshedChildren = refreshInlineNodesWithCursor(node.children, visitField, cursor);
+      const fieldLength = measureInlineNodes(node.children);
+      cursor = fieldStart + fieldLength;
+      return visitField({
+        ...node,
+        children: refreshedChildren.nodes,
+      }, {
+        from: fieldStart,
+        to: fieldStart + fieldLength,
+      });
+    }
+    if (node.type === "hyperlink") {
+      cursor += measureInlineNodes(node.children);
+      return {
+        ...node,
+        // Hyperlinks only contain text-like children in the canonical model.
+        children: [...node.children],
+      };
+    }
+    cursor += measureInlineNode(node);
+    return node;
+  });
+  return { nodes: nextNodes, cursor };
+}
+
+function buildInlineNodesFromDisplayText(text: string): InlineNode[] {
+  if (text.length === 0) {
+    return [];
+  }
+  const children: InlineNode[] = [];
+  let buffer = "";
+  const flushBuffer = () => {
+    if (buffer.length > 0) {
+      children.push({ type: "text", text: buffer });
+      buffer = "";
+    }
+  };
+  for (const character of text) {
+    if (character === "\t") {
+      flushBuffer();
+      children.push({ type: "tab" });
+      continue;
+    }
+    if (character === "\n") {
+      flushBuffer();
+      children.push({ type: "hard_break" });
+      continue;
+    }
+    buffer += character;
+  }
+  flushBuffer();
+  return children;
+}
+
+function buildTocInlineNodes(
+  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number }>,
+): InlineNode[] {
+  const children: InlineNode[] = [];
+  entries.forEach((entry, index) => {
+    children.push({ type: "text", text: entry.text });
+    children.push({ type: "tab" });
+    children.push({ type: "text", text: String(entry.pageIndex + 1) });
+    if (index < entries.length - 1) {
+      children.push({ type: "hard_break" });
+    }
+  });
+  return children;
+}
+
+function collectFieldsFromSubParts(
+  subParts: SubPartsCatalog | undefined,
+  entries: FieldEntrySnapshot[],
+  index: number,
+): number {
+  if (!subParts) {
+    return index;
+  }
+  let nextIndex = index;
+  for (const header of subParts.headers ?? []) {
+    for (const block of header.blocks) {
+      nextIndex = collectFieldsFromBlock(block, entries, nextIndex);
+    }
+  }
+  for (const footer of subParts.footers ?? []) {
+    for (const block of footer.blocks) {
+      nextIndex = collectFieldsFromBlock(block, entries, nextIndex);
+    }
+  }
+  if (subParts.footnoteCollection) {
+    for (const note of Object.values(subParts.footnoteCollection.footnotes)) {
+      for (const block of note.blocks) {
+        nextIndex = collectFieldsFromBlock(block, entries, nextIndex);
+      }
+    }
+    for (const note of Object.values(subParts.footnoteCollection.endnotes)) {
+      for (const block of note.blocks) {
+        nextIndex = collectFieldsFromBlock(block, entries, nextIndex);
+      }
+    }
+  }
+  return nextIndex;
+}
+
+function resolveSupportedFieldDisplay(
+  field: FieldNode,
+  document: CanonicalDocumentEnvelope,
+  bookmarkMap: Map<string, { bookmarkId: string; paragraphIndex: number }>,
+  paragraphs: readonly ParagraphContext[],
+  navigation: DocumentNavigationSnapshot,
+): { displayText: string; refreshStatus: FieldRefreshStatus } | undefined {
+  if (!field.fieldFamily || !isSupportedFieldFamily(field.fieldFamily)) {
+    return undefined;
+  }
+  if (!field.fieldTarget) {
+    return field.fieldFamily === "TOC"
+      ? undefined
+      : { displayText: "", refreshStatus: "unresolvable" };
+  }
+  if (field.fieldFamily === "REF") {
+    const result = resolveRefFieldText(document, bookmarkMap, field.fieldTarget);
+    return result
+      ? { displayText: result.text, refreshStatus: result.refreshStatus }
+      : { displayText: "", refreshStatus: "unresolvable" };
+  }
+  const bookmark = bookmarkMap.get(field.fieldTarget);
+  if (!bookmark) {
+    return { displayText: "", refreshStatus: "unresolvable" };
+  }
+  if (field.fieldFamily === "PAGEREF") {
+    const paragraph = paragraphs[bookmark.paragraphIndex];
+    if (!paragraph) {
+      return { displayText: "", refreshStatus: "unresolvable" };
+    }
+    const pageIndex = findPageForOffset(navigation.pages, paragraph.startOffset);
+    return { displayText: String(pageIndex + 1), refreshStatus: "current" };
+  }
+  if (field.fieldFamily === "NOTEREF") {
+    const paragraph = paragraphs[bookmark.paragraphIndex]?.paragraph;
+    if (!paragraph) {
+      return { displayText: "", refreshStatus: "unresolvable" };
+    }
+    const noteText = resolveNoteReferenceText(paragraph, bookmark.bookmarkId);
+    return noteText
+      ? { displayText: noteText, refreshStatus: "current" }
+      : { displayText: "", refreshStatus: "unresolvable" };
+  }
+  return undefined;
+}
+
+interface ParagraphContext {
+  paragraph: ParagraphNode;
+  startOffset: number;
+}
+
+function collectParagraphContexts(blocks: readonly BlockNode[]): ParagraphContext[] {
+  const paragraphs: ParagraphContext[] = [];
+  collectParagraphContextsFromBlocks(blocks, paragraphs, 0, false);
+  return paragraphs;
+}
+
+function collectParagraphContextsFromBlocks(
+  blocks: readonly BlockNode[],
+  paragraphs: ParagraphContext[],
+  cursor: number,
+  previousParagraph: boolean,
+): { cursor: number; previousParagraph: boolean } {
+  let nextCursor = cursor;
+  let nextPreviousParagraph = previousParagraph;
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      if (nextPreviousParagraph) {
+        nextCursor += 1;
+      }
+      paragraphs.push({ paragraph: block, startOffset: nextCursor });
+      nextCursor += measureInlineNodes(block.children);
+      nextPreviousParagraph = true;
+      continue;
+    }
+    if (block.type === "table") {
+      nextCursor += 1;
+      nextPreviousParagraph = false;
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          const result = collectParagraphContextsFromBlocks(
+            cell.children,
+            paragraphs,
+            nextCursor,
+            false,
+          );
+          nextCursor = result.cursor;
+        }
+      }
+      continue;
+    }
+    if (block.type === "sdt" || block.type === "custom_xml") {
+      const result = collectParagraphContextsFromBlocks(
+        block.children,
+        paragraphs,
+        nextCursor,
+        nextPreviousParagraph,
+      );
+      nextCursor = result.cursor;
+      nextPreviousParagraph = result.previousParagraph;
+      continue;
+    }
+    nextCursor += 1;
+    nextPreviousParagraph = false;
+  }
+  return { cursor: nextCursor, previousParagraph: nextPreviousParagraph };
+}
+
+function measureInlineNodes(nodes: readonly InlineNode[]): number {
+  return nodes.reduce((size, node) => size + measureInlineNode(node), 0);
+}
+
+function measureInlineNode(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return node.text.length;
+    case "tab":
+    case "hard_break":
+    case "column_break":
+    case "footnote_ref":
+    case "image":
+    case "opaque_inline":
+    case "bookmark_start":
+    case "bookmark_end":
+      return 1;
+    case "hyperlink":
+    case "field":
+      return measureInlineNodes(node.children);
+    default:
+      return 1;
+  }
+}
+
+function resolveNoteReferenceText(paragraph: ParagraphNode, bookmarkId: string): string | undefined {
+  let inside = false;
+  let sawBoundary = false;
+  for (const child of paragraph.children) {
+    if (child.type === "bookmark_start" && child.bookmarkId === bookmarkId) {
+      inside = true;
+      sawBoundary = true;
+      continue;
+    }
+    if (child.type === "bookmark_end" && child.bookmarkId === bookmarkId) {
+      break;
+    }
+    if (!inside) {
+      continue;
+    }
+    if (child.type === "footnote_ref") {
+      return child.noteId;
+    }
+  }
+  return sawBoundary ? undefined : undefined;
+}
+
+function getCommandSelection(
+  command: EditorCommand,
+  fallbackSelection: import("../core/state/editor-state.ts").SelectionSnapshot,
+): import("../core/state/editor-state.ts").SelectionSnapshot {
+  if ("protectionSelection" in command && command.protectionSelection) {
+    return command.protectionSelection;
+  }
+  if ("selection" in command && command.selection) {
+    return command.selection;
+  }
+  return fallbackSelection;
+}
+
+function isBlockedByProtection(
+  protection: ProtectionSnapshot,
+  selection: import("../core/state/editor-state.ts").SelectionSnapshot,
+): boolean {
+  const enforcedRanges = protection.ranges.filter(
+    (range): range is typeof range & { start: number; end: number } =>
+      range.enforced && typeof range.start === "number" && typeof range.end === "number",
+  );
+  if (enforcedRanges.length === 0) {
+    return false;
+  }
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+  return !enforcedRanges.some((range) =>
+    from >= range.start && to <= range.end,
+  );
+}
+
+function remapProtectionSnapshot(
+  protection: ProtectionSnapshot,
+  mapping: import("../core/selection/mapping.ts").TransactionMapping,
+): ProtectionSnapshot {
+  if (mapping.steps.length === 0 || protection.ranges.length === 0) {
+    return protection;
+  }
+  let changed = false;
+  const nextRanges = protection.ranges.map((range) => {
+    if (
+      !range.enforced ||
+      typeof range.start !== "number" ||
+      typeof range.end !== "number"
+    ) {
+      return range;
+    }
+    const mapped = mapRange(
+      { from: range.start, to: range.end },
+      { start: -1, end: 1 },
+      mapping,
+    );
+    if (mapped.kind === "detached") {
+      changed = true;
+      return {
+        ...range,
+        start: undefined,
+        end: undefined,
+        enforced: false,
+        enforcementReason:
+          "preserve-only: permission range could not be remapped after runtime edits",
+      };
+    }
+    if (mapped.range.from !== range.start || mapped.range.to !== range.end) {
+      changed = true;
+      return {
+        ...range,
+        start: mapped.range.from,
+        end: mapped.range.to,
+      };
+    }
+    return range;
+  });
+  if (!changed) {
+    return protection;
+  }
+  return {
+    ...protection,
+    ranges: nextRanges,
+    enforcedRangeCount: nextRanges.filter((range) => range.enforced).length,
+    preservedRangeCount: nextRanges.filter((range) => !range.enforced).length,
+  };
+}