@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/runtime/document-runtime.ts

@@ -0,0 +1,4055 @@
+import {
+  createEditorState,
+  createPersistedEditorSnapshot,
+  deriveDocumentStats,
+  createSelectionSnapshot,
+  type CanonicalDocumentEnvelope,
+  type CommentEntryRecord,
+  type CommentThreadRecord,
+  type CompatibilityFeatureEntry as InternalCompatibilityFeatureEntry,
+  type CompatibilityReport as InternalCompatibilityReport,
+  type EditorError as InternalEditorError,
+  type EditorState,
+  type EditorWarning as InternalEditorWarning,
+} from "../core/state/editor-state.ts";
+import type {
+  AddCommentParams,
+  CommentSidebarSnapshot,
+  CommentSidebarThreadSnapshot,
+  CompatibilityReport,
+  DocumentChunkSnapshot,
+  DocumentLocationSnapshot,
+  DocumentMode,
+  DocumentNavigationSnapshot,
+  DocumentOutlineSnapshot,
+  DocumentSectionSnapshot,
+  DocumentTextToken,
+  EditorSessionState,
+  EditorAnchorProjection,
+  EditorError,
+  EditorStoryTarget,
+  EditorViewStateSnapshot,
+  EditorWarning,
+  FieldEntrySnapshot,
+  FieldSnapshot,
+  HeaderFooterLinkPatch,
+  ExportDocxOptions,
+  ExportResult,
+  HostAnnotationOverlay,
+  HostAnnotationSnapshot,
+  InteractionGuardSnapshot,
+  PageLayoutSnapshot,
+  PersistedEditorSnapshot,
+  ProtectionSnapshot,
+  RestorePointSnapshot,
+  RestoreResult,
+  ReviewWorkSnapshot,
+  RuntimeContextAnalyticsQuery,
+  RuntimeContextAnalyticsSnapshot,
+  RuntimeRenderSnapshot,
+  SelectionSnapshot,
+  SnapshotRefreshHints,
+  SuggestionsSnapshot,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+  StoryTextStreamSnapshot,
+  TocSnapshot,
+  StyleCatalogSnapshot,
+  TocRefreshOptions,
+  TocRefreshResult,
+  TrackedChangeEntrySnapshot,
+  TrackedChangesSnapshot,
+  UpdateFieldsOptions,
+  UpdateFieldsResult,
+  ViewMode,
+  WorkflowCandidateRange,
+  WorkflowCandidateRangeOptions,
+  WorkflowBlockedCommandReason,
+  WorkflowMetadataDefinition,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+  WorkflowMarkupSnapshot,
+  WorkflowOverlay,
+  WorkflowScopeSnapshot,
+  WorkspaceMode,
+  WordReviewEditorEvent,
+  ZoomLevel,
+} from "../api/public-types";
+import {
+  editorSessionStateFromPersistedSnapshot,
+  persistedSnapshotFromEditorSessionState,
+} from "../api/session-state.ts";
+import {
+  executeEditorCommand,
+  selectionChanged,
+  type CommandOrigin,
+  type EditorCommand,
+  type EditorTransaction,
+} from "../core/commands/index.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,
+  isBlockedImportFeatureKey,
+} from "../preservation/store.ts";
+import { createCommentSidebarProjection } from "../review/store/comment-store.ts";
+import { createCommentStoreFromRuntimeComments } from "../review/store/runtime-comment-store.ts";
+import {
+  createRevisionSidebarProjection,
+  type RevisionStore,
+} from "../review/store/revision-store.ts";
+import { createSuggestionsSnapshot } from "./suggestions-snapshot.ts";
+import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
+import { mergeCompatibilityReports } from "../validation/compatibility-report.ts";
+import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
+import {
+  collectWorkflowMarkupSnapshot,
+  deriveWorkflowCandidateRangesFromMarkup,
+} from "./workflow-markup.ts";
+import {
+  createDocumentNavigationSnapshot,
+  findPageForOffset,
+} from "./document-navigation.ts";
+import {
+  createDocumentOutlineSnapshot,
+  createDocumentSectionSnapshots,
+  createSectionLocations,
+  createTocSnapshot,
+  findDocumentSectionSnapshot,
+} from "./document-outline.ts";
+import {
+  createCurrentLocation,
+  createDocumentChunks,
+  createDocumentLocationSnapshot,
+  createDocumentTextStreamSnapshots,
+  createLocationFromSelection,
+  createRestorePoint,
+  createReviewWorkSnapshot,
+  createWorkflowChunks,
+} from "./document-locations.ts";
+import { describeEventImpact } from "./event-refresh-hints.ts";
+import {
+  createRuntimeContextAnalyticsSnapshot,
+  resolveCurrentContextAnalyticsQuery,
+  runtimeContextAnalyticsSnapshotsEqual,
+} from "./context-analytics.ts";
+import {
+  buildPageLayoutSnapshot,
+  buildResolvedSections,
+  resolveActiveSection,
+} from "./document-layout.ts";
+import { normalizeHeaderFooterTarget } from "./story-context.ts";
+import {
+  getStoryBlocks,
+  replaceStoryBlocks,
+  storyTargetKey,
+} from "./story-targeting.ts";
+import {
+  createViewState,
+  setViewMode as applyViewMode,
+  setDocumentMode as applyDocumentMode,
+  setWorkspaceMode as applyWorkspaceMode,
+  setZoomLevel as applyZoomLevel,
+  setFocused as applyFocused,
+  setCaretAffinity as applyCaretAffinity,
+  setActivePageRegion as applyActivePageRegion,
+  setActiveObjectFrame as applyActiveObjectFrame,
+  createEditorViewStateSnapshot,
+  type ViewState,
+} from "./view-state.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;
+
+type RuntimeReadySource = "docx" | "session" | "snapshot" | "datastore" | "canonical";
+
+export type DocumentRuntimeEvent =
+  | (Omit<Extract<WordReviewEditorEvent, { type: "ready" }>, "source"> & {
+      source: RuntimeReadySource;
+    })
+  | Exclude<WordReviewEditorEvent, { type: "ready" }>;
+
+export type ActiveStoryTextCommand =
+  | Extract<EditorCommand, { type: "text.insert" }>
+  | Extract<EditorCommand, { type: "text.delete-backward" }>
+  | Extract<EditorCommand, { type: "text.delete-forward" }>
+  | Extract<EditorCommand, { type: "text.insert-tab" }>
+  | Extract<EditorCommand, { type: "text.insert-hard-break" }>
+  | Extract<EditorCommand, { type: "paragraph.split" }>;
+
+export interface DocumentRuntime {
+  subscribe(listener: () => void): Unsubscribe;
+  subscribeToEvents(listener: (event: DocumentRuntimeEvent) => void): Unsubscribe;
+  getRenderSnapshot(): RuntimeRenderSnapshot;
+  getCanonicalDocument(): CanonicalDocumentEnvelope;
+  getSourcePackage(): EditorSessionState["sourcePackage"] | undefined;
+  replaceText(text: string, target?: EditorAnchorProjection): void;
+  applyActiveStoryTextCommand(command: ActiveStoryTextCommand): void;
+  dispatch(command: EditorCommand): void;
+  emitBlockedCommand(command: string, reasons: WorkflowBlockedCommandReason[]): void;
+  undo(): void;
+  redo(): void;
+  focus(): void;
+  blur(): void;
+  setDefaultAuthorId?(authorId?: string): void;
+  getDefaultAuthorId?(): string | undefined;
+  addComment(params: AddCommentParams): string;
+  openComment(commentId: string): void;
+  resolveComment(commentId: string): void;
+  reopenComment(commentId: string): void;
+  addCommentReply(commentId: string, body: string, authorId?: string): void;
+  editCommentBody(commentId: string, body: string): void;
+  acceptChange(changeId: string): void;
+  rejectChange(changeId: string): void;
+  acceptAllChanges(): void;
+  rejectAllChanges(): void;
+  openStory(target: EditorStoryTarget): boolean;
+  closeStory(): void;
+  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;
+  getCurrentLocation(): DocumentLocationSnapshot | null;
+  getLocationForSelection(selection: SelectionSnapshot): DocumentLocationSnapshot | null;
+  getLocationForAnchor(
+    anchor: EditorAnchorProjection,
+    storyTarget?: EditorStoryTarget,
+  ): DocumentLocationSnapshot | null;
+  captureRestorePoint(
+    input?: SelectionSnapshot | EditorAnchorProjection,
+  ): RestorePointSnapshot | null;
+  restoreToPoint(
+    point: RestorePointSnapshot,
+    options?: { behavior?: "exact" | "semantic"; scroll?: boolean },
+  ): RestoreResult;
+  getOutlineSnapshot(): DocumentOutlineSnapshot;
+  getTocSnapshot(): TocSnapshot | null;
+  getSections(): DocumentSectionSnapshot[];
+  getSectionSnapshot(input: {
+    sectionIndex?: number;
+    headingId?: string;
+    bookmarkName?: string;
+  }): DocumentSectionSnapshot | null;
+  describeEventImpact(event: WordReviewEditorEvent): SnapshotRefreshHints;
+  getFieldSnapshot(): FieldSnapshot;
+  updateFields(options?: UpdateFieldsOptions): UpdateFieldsResult;
+  updateTableOfContents(options?: TocRefreshOptions): TocRefreshResult;
+  getSessionState(): EditorSessionState;
+  getPersistedSnapshot(): PersistedEditorSnapshot;
+  getCompatibilityReport(): CompatibilityReport;
+  getWarnings(): EditorWarning[];
+  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
+  getSuggestionsSnapshot(): SuggestionsSnapshot;
+  setWorkflowOverlay(overlay: WorkflowOverlay): void;
+  clearWorkflowOverlay(): void;
+  getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
+  getInteractionGuardSnapshot(): InteractionGuardSnapshot;
+  getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
+  setWorkflowMetadataDefinitions(definitions: WorkflowMetadataDefinition[]): void;
+  clearWorkflowMetadataDefinitions(): void;
+  setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
+  clearWorkflowMetadataEntries(): void;
+  getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
+  clearHostAnnotationOverlay(): void;
+  getHostAnnotationSnapshot(): HostAnnotationSnapshot;
+  getWorkflowCandidateRanges(options?: WorkflowCandidateRangeOptions): WorkflowCandidateRange[];
+  replaceWorkflowMarkupText(markupId: string, text: string): void;
+  getDocumentTextStream(): StoryTextStreamSnapshot[];
+  getStoryTextStream(target: EditorStoryTarget): StoryTextStreamSnapshot | null;
+  getDocumentChunks(): DocumentChunkSnapshot[];
+  getWorkflowChunks(): DocumentChunkSnapshot[];
+  getReviewWorkSnapshot(): ReviewWorkSnapshot;
+  getRuntimeContextAnalytics(
+    query?: RuntimeContextAnalyticsQuery,
+  ): RuntimeContextAnalyticsSnapshot | null;
+}
+
+export interface CreateDocumentRuntimeOptions {
+  documentId: string;
+  initialSessionState?: EditorSessionState;
+  initialSnapshot?: PersistedEditorSnapshot;
+  initialCanonicalDocument?: CanonicalDocumentEnvelope;
+  sourceLabel?: string;
+  sourceKind?: RuntimeReadySource;
+  readOnly?: boolean;
+  editorBuild?: string;
+  defaultAuthorId?: string;
+  fatalError?: EditorError;
+  clock?: () => string;
+  exportDocx?: (
+    sessionState: EditorSessionState,
+    options?: ExportDocxOptions,
+  ) => Promise<ExportResult>;
+  onEvent?: (event: DocumentRuntimeEvent) => void;
+  onWarning?: (warning: EditorWarning) => void;
+  onError?: (error: EditorError) => void;
+  initialViewState?: Partial<ViewState>;
+  protectionSnapshot?: ProtectionSnapshot;
+}
+
+interface HistoryState {
+  past: EditorState[];
+  future: EditorState[];
+}
+
+export function createDocumentRuntime(
+  options: CreateDocumentRuntimeOptions,
+): 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>();
+  const history: HistoryState = {
+    past: [],
+    future: [],
+  };
+
+  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;
+  let workflowMetadataDefinitions: WorkflowMetadataDefinition[] =
+    options.initialSessionState?.workflowMetadata?.definitions
+    ?? options.initialSnapshot?.workflowMetadata?.definitions
+    ?? [];
+  let workflowMetadataEntries: WorkflowMetadataEntry[] =
+    options.initialSessionState?.workflowMetadata?.entries
+    ?? options.initialSnapshot?.workflowMetadata?.entries
+    ?? [];
+  let hostAnnotationOverlay: HostAnnotationOverlay | null = null;
+  const initialPersistedSnapshot = options.initialSessionState
+    ? persistedSnapshotFromEditorSessionState(options.initialSessionState, {
+        savedAt: options.initialSessionState.updatedAt,
+      })
+    : options.initialSnapshot;
+
+  let state = createEditorState({
+    documentId: options.documentId,
+    sessionId,
+    sourceLabel: options.sourceLabel,
+    readOnly: options.readOnly,
+    persistedSnapshot: initialPersistedSnapshot as never,
+    canonicalDocument: options.initialCanonicalDocument,
+    fatalError: options.fatalError as never,
+  });
+  storySelections.set(storyTargetKey(MAIN_STORY_TARGET), state.selection);
+  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"];
+        revisionToken: string;
+        snapshot: TrackedChangesSnapshot;
+      }
+    | undefined;
+  let cachedSuggestions:
+    | {
+        trackedChanges: TrackedChangesSnapshot;
+        snapshot: SuggestionsSnapshot;
+      }
+    | 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;
+  let cachedWorkflowMarkupSnapshot:
+    | {
+        revisionToken: string;
+        activeStoryKey: string;
+        protectionSnapshot: ProtectionSnapshot;
+        preservation: CanonicalDocumentEnvelope["preservation"];
+        workflowOverlay: WorkflowOverlay | null;
+        workflowMetadataDefinitions: WorkflowMetadataDefinition[];
+        workflowMetadataEntries: WorkflowMetadataEntry[];
+        snapshot: WorkflowMarkupSnapshot;
+      }
+    | undefined;
+  const cachedContextAnalyticsSnapshots = new Map<
+    string,
+    {
+      revisionToken: string;
+      activeStoryKey: string;
+      selection: EditorState["selection"];
+      readOnly: boolean;
+      documentMode: DocumentMode;
+      workflowOverlay: WorkflowOverlay | null;
+      protectionSnapshot: ProtectionSnapshot;
+      warnings: EditorState["warnings"];
+      fatalError: EditorState["fatalError"];
+      snapshot: RuntimeContextAnalyticsSnapshot | null;
+    }
+  >();
+  let lastEmittedContextAnalyticsSnapshots:
+    | Map<string, RuntimeContextAnalyticsSnapshot | null>
+    | 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 {
+    if (
+      cachedTrackedChanges &&
+      cachedTrackedChanges.revisions === nextState.document.review.revisions &&
+      cachedTrackedChanges.revisionToken === nextState.revisionToken
+    ) {
+      return cachedTrackedChanges.snapshot;
+    }
+
+    const snapshot = toPublicTrackedChangesSnapshot(nextState);
+    cachedTrackedChanges = {
+      revisions: nextState.document.review.revisions,
+      revisionToken: nextState.revisionToken,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function getCachedSuggestionsSnapshot(nextState: EditorState): SuggestionsSnapshot {
+    const trackedChanges = getCachedTrackedChangesSnapshot(nextState, undefined);
+    if (
+      cachedSuggestions &&
+      cachedSuggestions.trackedChanges === trackedChanges
+    ) {
+      return cachedSuggestions.snapshot;
+    }
+
+    const snapshot = createSuggestionsSnapshot(trackedChanges);
+    cachedSuggestions = {
+      trackedChanges,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function findSuggestionByChangeId(
+    snapshot: SuggestionsSnapshot,
+    changeId: string,
+  ) {
+    return snapshot.suggestions.find((suggestion) => suggestion.changeIds.includes(changeId));
+  }
+
+  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.",
+      });
+    }
+
+    const effectiveDocumentMode = getEffectiveDocumentMode(selection);
+
+    if (effectiveDocumentMode === "suggesting" && commandType) {
+      if (SUGGESTING_UNSUPPORTED_COMMANDS.has(commandType)) {
+        reasons.push({
+          code: "suggesting_unsupported",
+          message: `"${commandType}" is not supported in suggesting mode.`,
+        });
+      }
+    }
+
+    if (workflowOverlay) {
+      const matchingScope = getMatchingWorkflowScope(selection);
+
+      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 getMatchingWorkflowScope(
+    selection: EditorState["selection"],
+  ): WorkflowOverlay["scopes"][number] | null {
+    if (!workflowOverlay) {
+      return null;
+    }
+
+    const selectionBounds = {
+      from: Math.min(selection.anchor, selection.head),
+      to: Math.max(selection.anchor, selection.head),
+    };
+    const activeScopes = getEffectiveWorkflowScopes(workflowOverlay);
+    return 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;
+    }) ?? null;
+  }
+
+  function getEffectiveDocumentMode(
+    selection: EditorState["selection"],
+  ): DocumentMode {
+    if (viewState.documentMode === "viewing") {
+      return "viewing";
+    }
+    const matchingScope = getMatchingWorkflowScope(selection);
+    if (matchingScope?.mode === "suggest") {
+      return "suggesting";
+    }
+    return viewState.documentMode;
+  }
+
+  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 surfaceReason = deriveSurfaceOpaqueWorkflowBlockedReason(range);
+    if (surfaceReason) {
+      return surfaceReason;
+    }
+
+    const targetPartPath = getStoryTargetOpaquePartPath(activeStory);
+    if (!targetPartPath) {
+      return null;
+    }
+    const fragments = findOpaqueFragmentsIntersectingRange(
+      state.document.preservation,
+      range,
+    ).filter((fragment) => fragment.packagePartName === targetPartPath);
+
+    if (fragments.length === 0) {
+      return null;
+    }
+
+    const blockedImportFragment =
+      fragments.find((fragment) =>
+        isBlockedImportFeatureKey(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 deriveSurfaceOpaqueWorkflowBlockedReason(
+    range: { from: number; to: number },
+  ): WorkflowBlockedCommandReason | null {
+    const blocks = getActiveStorySurfaceBlocks();
+    if (!blocks) {
+      return null;
+    }
+
+    const opaqueTarget = findSurfaceOpaqueTargetIntersectingRange(blocks, range);
+    if (!opaqueTarget) {
+      return null;
+    }
+
+    const code = opaqueTarget.blockedReasonCode ?? "workflow_preserve_only";
+    return {
+      code,
+      message:
+        code === "workflow_blocked_import"
+          ? `${opaqueTarget.label} remains a blocked import and cannot be edited.`
+          : `${opaqueTarget.label} remains preserve-only and cannot be edited.`,
+      anchor: toPublicAnchorProjection(
+        createRangeAnchor(opaqueTarget.from, opaqueTarget.to, {
+          start: -1,
+          end: 1,
+        }),
+      ),
+      storyTarget: activeStory,
+    };
+  }
+
+  function getActiveStorySurfaceBlocks(): readonly SurfaceBlockSnapshot[] | null {
+    const surface = cachedRenderSnapshot.surface;
+    if (!surface) {
+      return null;
+    }
+
+    if (activeStory.kind === "main") {
+      return surface.blocks;
+    }
+
+    const activeStoryKey = storyTargetKey(activeStory);
+    return (
+      surface.secondaryStories.find((story) => storyTargetKey(story.target) === activeStoryKey)?.blocks ??
+      null
+    );
+  }
+
+  function findSurfaceOpaqueTargetIntersectingRange(
+    blocks: readonly SurfaceBlockSnapshot[],
+    range: { from: number; to: number },
+  ): {
+    from: number;
+    to: number;
+    label: string;
+    blockedReasonCode: "workflow_preserve_only" | "workflow_blocked_import";
+  } | null {
+    for (const block of blocks) {
+      if (block.kind === "paragraph") {
+        for (const segment of block.segments) {
+          const match = matchOpaqueInlineSegment(segment, range);
+          if (match) {
+            return match;
+          }
+        }
+        continue;
+      }
+
+      if (block.kind === "table") {
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            const match = findSurfaceOpaqueTargetIntersectingRange(cell.content, range);
+            if (match) {
+              return match;
+            }
+          }
+        }
+        continue;
+      }
+
+      if (block.kind === "sdt_block") {
+        const match = findSurfaceOpaqueTargetIntersectingRange(block.children, range);
+        if (match) {
+          return match;
+        }
+        continue;
+      }
+
+      if (block.kind !== "opaque_block") {
+        continue;
+      }
+
+      const blockRange = {
+        from: block.from,
+        to: block.to > block.from ? block.to : block.from + 1,
+      };
+      if (rangesIntersect(blockRange, range)) {
+        if (!block.blockedReasonCode) {
+          continue;
+        }
+        return {
+          from: blockRange.from,
+          to: blockRange.to,
+          label: block.label,
+          blockedReasonCode: block.blockedReasonCode,
+        };
+      }
+    }
+
+    return null;
+  }
+
+  function matchOpaqueInlineSegment(
+    segment: SurfaceInlineSegment,
+    range: { from: number; to: number },
+  ): {
+    from: number;
+    to: number;
+    label: string;
+    blockedReasonCode: "workflow_preserve_only" | "workflow_blocked_import";
+  } | null {
+    if (segment.kind !== "opaque_inline") {
+      return null;
+    }
+    if (!segment.blockedReasonCode) {
+      return null;
+    }
+
+    const segmentRange = {
+      from: segment.from,
+      to: segment.to > segment.from ? segment.to : segment.from + 1,
+    };
+    if (!rangesIntersect(segmentRange, range)) {
+      return null;
+    }
+
+    return {
+      from: segmentRange.from,
+      to: segmentRange.to,
+      label: segment.label,
+      blockedReasonCode: segment.blockedReasonCode,
+    };
+  }
+
+  function getStoryTargetOpaquePartPath(storyTarget: EditorStoryTarget): string | null {
+    if (storyTarget.kind === "main") {
+      return "/word/document.xml";
+    }
+    if (storyTarget.kind === "header") {
+      return state.document.subParts?.headers.find(
+        (header) =>
+          header.relationshipId === storyTarget.relationshipId
+          && header.variant === storyTarget.variant
+          && header.sectionIndex === storyTarget.sectionIndex,
+      )?.partPath ?? null;
+    }
+    if (storyTarget.kind === "footer") {
+      return state.document.subParts?.footers.find(
+        (footer) =>
+          footer.relationshipId === storyTarget.relationshipId
+          && footer.variant === storyTarget.variant
+          && footer.sectionIndex === storyTarget.sectionIndex,
+      )?.partPath ?? null;
+    }
+    if (storyTarget.kind === "footnote") {
+      return "/word/footnotes.xml";
+    }
+    if (storyTarget.kind === "endnote") {
+      return "/word/endnotes.xml";
+    }
+    return null;
+  }
+
+  function rangesIntersect(
+    left: { from: number; to: number },
+    right: { from: number; to: number },
+  ): boolean {
+    return left.from < right.to && right.from < left.to;
+  }
+
+  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 deriveHostAnnotationSnapshot(): HostAnnotationSnapshot {
+    return {
+      totalCount: hostAnnotationOverlay?.annotations.length ?? 0,
+      annotations: structuredClone(hostAnnotationOverlay?.annotations ?? []),
+    };
+  }
+
+  function deriveWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot {
+    return {
+      definitions: structuredClone(workflowMetadataDefinitions),
+      entries: structuredClone(workflowMetadataEntries),
+    };
+  }
+
+  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 blockedReasons = evaluateWorkflowBlockedReasons(state.selection);
+    const matchingScope = getMatchingWorkflowScope(state.selection);
+    const primaryBlockedReason = blockedReasons[0];
+    const effectiveMode = primaryBlockedReason
+      ? (
+        primaryBlockedReason.code === "workflow_comment_only"
+          ? "comment"
+          : primaryBlockedReason.code === "workflow_view_only"
+            ? "view"
+            : "blocked"
+      )
+      : getEffectiveDocumentMode(state.selection) === "suggesting"
+        ? "suggest"
+        : matchingScope?.mode ?? "edit";
+    const snapshot: InteractionGuardSnapshot = {
+      effectiveMode,
+      ...(matchingScope?.scopeId ? { matchedScopeId: matchingScope.scopeId } : {}),
+      ...(matchingScope?.mode ? { matchedScopeMode: matchingScope.mode } : {}),
+      targetAccess:
+        effectiveMode === "edit"
+          ? "direct-edit"
+          : effectiveMode === "suggest"
+            ? "suggest"
+            : effectiveMode === "comment"
+              ? "comment-only"
+              : effectiveMode === "view"
+                ? "view-only"
+                : "blocked",
+      commandCapabilities: [
+        {
+          family: "text",
+          supported: evaluateWorkflowBlockedReasons(state.selection, "text.insert").length === 0,
+          blockedReasons: evaluateWorkflowBlockedReasons(state.selection, "text.insert"),
+        },
+        {
+          family: "formatting",
+          supported: evaluateWorkflowBlockedReasons(state.selection, "toggleBold").length === 0,
+          blockedReasons: evaluateWorkflowBlockedReasons(state.selection, "toggleBold"),
+        },
+        {
+          family: "structure",
+          supported: evaluateWorkflowBlockedReasons(state.selection, "insertTable").length === 0,
+          blockedReasons: evaluateWorkflowBlockedReasons(state.selection, "insertTable"),
+        },
+      ],
+      ...(primaryBlockedReason ? { disabledReason: primaryBlockedReason.message } : {}),
+      blockedReasons,
+    };
+    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 getCachedWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot {
+    const activeStoryKey = storyTargetKey(activeStory);
+    if (
+      cachedWorkflowMarkupSnapshot &&
+      cachedWorkflowMarkupSnapshot.revisionToken === state.revisionToken &&
+      cachedWorkflowMarkupSnapshot.activeStoryKey === activeStoryKey &&
+      cachedWorkflowMarkupSnapshot.protectionSnapshot === protectionSnapshot &&
+      cachedWorkflowMarkupSnapshot.preservation === state.document.preservation &&
+      cachedWorkflowMarkupSnapshot.workflowOverlay === workflowOverlay &&
+      cachedWorkflowMarkupSnapshot.workflowMetadataDefinitions === workflowMetadataDefinitions &&
+      cachedWorkflowMarkupSnapshot.workflowMetadataEntries === workflowMetadataEntries
+    ) {
+      return cachedWorkflowMarkupSnapshot.snapshot;
+    }
+
+    const snapshot = collectWorkflowMarkupSnapshot({
+      renderSnapshot: cachedRenderSnapshot,
+      fieldSnapshot: buildFieldSnapshot(state.document),
+      protectionSnapshot,
+      preservation: state.document.preservation,
+      workflowMetadataSnapshot: deriveWorkflowMetadataSnapshot(),
+    });
+    cachedWorkflowMarkupSnapshot = {
+      revisionToken: state.revisionToken,
+      activeStoryKey,
+      protectionSnapshot,
+      preservation: state.document.preservation,
+      workflowOverlay,
+      workflowMetadataDefinitions,
+      workflowMetadataEntries,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function getCachedRuntimeContextAnalytics(
+    query?: RuntimeContextAnalyticsQuery,
+  ): RuntimeContextAnalyticsSnapshot | null {
+    const activeStoryKey = storyTargetKey(activeStory);
+    const queryKey = getRuntimeContextAnalyticsQueryKey(query);
+    const cachedEntry = cachedContextAnalyticsSnapshots.get(queryKey);
+    if (
+      cachedEntry &&
+      cachedEntry.revisionToken === state.revisionToken &&
+      cachedEntry.activeStoryKey === activeStoryKey &&
+      cachedEntry.selection === state.selection &&
+      cachedEntry.readOnly === state.readOnly &&
+      cachedEntry.documentMode === viewState.documentMode &&
+      cachedEntry.workflowOverlay === workflowOverlay &&
+      cachedEntry.protectionSnapshot === protectionSnapshot &&
+      cachedEntry.warnings === state.warnings &&
+      cachedEntry.fatalError === state.fatalError
+    ) {
+      return cachedEntry.snapshot;
+    }
+
+    const snapshot = createRuntimeContextAnalyticsSnapshot({
+      query,
+      renderSnapshot: cachedRenderSnapshot,
+      workflowOverlay,
+      workflowScopeSnapshot: getCachedWorkflowScopeSnapshot(),
+      interactionGuardSnapshot: getCachedInteractionGuardSnapshot(),
+      workflowMarkupSnapshot: getCachedWorkflowMarkupSnapshot(),
+      suggestionsSnapshot: getCachedSuggestionsSnapshot(state),
+      reviewWorkSnapshot: createReviewWorkSnapshot({
+        comments: cachedRenderSnapshot.comments,
+        trackedChanges: cachedRenderSnapshot.trackedChanges,
+        workflowMarkup: getCachedWorkflowMarkupSnapshot(),
+        document: state.document,
+        navigation: getCachedDocumentNavigationSnapshot(state, activeStory),
+      }),
+      warnings: state.warnings.map(toPublicWarning),
+      compatibility: toPublicCompatibilityReport(createDerivedCompatibility(state)),
+    });
+    cachedContextAnalyticsSnapshots.set(queryKey, {
+      revisionToken: state.revisionToken,
+      activeStoryKey,
+      selection: state.selection,
+      readOnly: state.readOnly,
+      documentMode: viewState.documentMode,
+      workflowOverlay,
+      protectionSnapshot,
+      warnings: state.warnings,
+      fatalError: state.fatalError,
+      snapshot,
+    });
+    return snapshot;
+  }
+
+  function getRuntimeContextAnalyticsQueryKey(query?: RuntimeContextAnalyticsQuery): string {
+    return JSON.stringify({
+      scopeKind: query?.scopeKind ?? "selection",
+      scopeId: query?.scopeId ?? null,
+      workItemId: query?.workItemId ?? null,
+    });
+  }
+
+  function getTrackedContextAnalyticsQueries(): Array<RuntimeContextAnalyticsQuery | undefined> {
+    const queries: Array<RuntimeContextAnalyticsQuery | undefined> = [
+      undefined,
+      { scopeKind: "document" },
+    ];
+    const workflowScopeSnapshot = getCachedWorkflowScopeSnapshot();
+    const seenScopeIds = new Set<string>();
+    for (const scope of workflowScopeSnapshot?.scopes ?? []) {
+      if (seenScopeIds.has(scope.scopeId)) {
+        continue;
+      }
+      seenScopeIds.add(scope.scopeId);
+      queries.push({
+        scopeKind: "workflow_scope",
+        scopeId: scope.scopeId,
+      });
+    }
+    const seenWorkItemIds = new Set<string>();
+    for (const workItem of workflowOverlay?.workItems ?? []) {
+      if (seenWorkItemIds.has(workItem.workItemId)) {
+        continue;
+      }
+      seenWorkItemIds.add(workItem.workItemId);
+      queries.push({
+        scopeKind: "work_item",
+        workItemId: workItem.workItemId,
+      });
+    }
+    const activeWorkItemId = workflowScopeSnapshot?.activeWorkItemId ?? null;
+    if (activeWorkItemId && !seenWorkItemIds.has(activeWorkItemId)) {
+      queries.push({
+        scopeKind: "work_item",
+        workItemId: activeWorkItemId,
+      });
+    }
+    return queries;
+  }
+
+  function collectTrackedContextAnalyticsSnapshots(): Map<string, RuntimeContextAnalyticsSnapshot | null> {
+    const snapshots = new Map<string, RuntimeContextAnalyticsSnapshot | null>();
+    for (const query of getTrackedContextAnalyticsQueries()) {
+      snapshots.set(
+        getRuntimeContextAnalyticsQueryKey(query),
+        getCachedRuntimeContextAnalytics(query),
+      );
+    }
+    return snapshots;
+  }
+
+  function trackedContextAnalyticsSnapshotsEqual(
+    left: Map<string, RuntimeContextAnalyticsSnapshot | null>,
+    right: Map<string, RuntimeContextAnalyticsSnapshot | null>,
+  ): boolean {
+    if (left.size !== right.size) {
+      return false;
+    }
+    for (const [key, snapshot] of left.entries()) {
+      if (!right.has(key)) {
+        return false;
+      }
+      if (!runtimeContextAnalyticsSnapshotsEqual(snapshot, right.get(key) ?? null)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  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",
+    documentId: state.documentId,
+    sessionId: state.sessionId,
+    source:
+      options.sourceKind ??
+      (options.initialSessionState
+        ? "session"
+        : options.initialSnapshot
+          ? "snapshot"
+          : "canonical"),
+    stats: toPublicDocumentStats(state),
+    compatibility: toPublicCompatibilityReport(createDerivedCompatibility(state)),
+    comments: cachedRenderSnapshot.comments,
+    trackedChanges: cachedRenderSnapshot.trackedChanges,
+  });
+  if (options.fatalError) {
+    emit({
+      type: "error",
+      documentId: state.documentId,
+      error: options.fatalError,
+    });
+  }
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    subscribeToEvents(listener) {
+      eventListeners.add(listener);
+      return () => {
+        eventListeners.delete(listener);
+      };
+    },
+    getRenderSnapshot() {
+      return cachedRenderSnapshot;
+    },
+    getCanonicalDocument() {
+      return state.document;
+    },
+    getSourcePackage() {
+      return state.sourcePackage;
+    },
+    emitBlockedCommand(command, reasons) {
+      emit({
+        type: "command_blocked",
+        documentId: state.documentId,
+        command,
+        reasons,
+      });
+    },
+    dispatch(command) {
+      const commandSelection = getCommandSelection(command, state.selection);
+      if (isMutationCommand(command)) {
+        const blockedReasons = evaluateWorkflowBlockedReasons(
+          commandSelection,
+          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(),
+          documentMode: getEffectiveDocumentMode(commandSelection),
+          defaultAuthorId: defaultAuthorId ?? undefined,
+        });
+        commit(transaction);
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
+    undo() {
+      this.dispatch({
+        type: "history.undo",
+        origin: createOrigin("runtime", clock()),
+      });
+    },
+    redo() {
+      this.dispatch({
+        type: "history.redo",
+        origin: createOrigin("runtime", clock()),
+      });
+    },
+    focus() {
+      viewState = applyFocused(viewState, true);
+      this.dispatch({
+        type: "runtime.focus",
+        focused: true,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    blur() {
+      viewState = applyFocused(viewState, false);
+      this.dispatch({
+        type: "runtime.focus",
+        focused: false,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    setDefaultAuthorId(authorId) {
+      defaultAuthorId = authorId;
+    },
+    getDefaultAuthorId() {
+      return defaultAuthorId;
+    },
+    replaceText(text, target) {
+      try {
+        const timestamp = clock();
+        applyTextCommandInActiveStory(
+          {
+            type: "text.insert",
+            text,
+            origin: createOrigin("api", timestamp),
+          },
+          {
+            selection: target ? createSelectionFromPublicAnchor(target) : state.selection,
+            blockedCommandName: "replaceText",
+          },
+        );
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
+    applyActiveStoryTextCommand(command) {
+      try {
+        applyTextCommandInActiveStory(command);
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
+    addComment(params) {
+      if (viewState.documentMode === "viewing") {
+        const error: InternalEditorError = {
+          errorId: createSessionId("comment-viewing-mode", clock()),
+          code: "validation_failed",
+          isFatal: false,
+          message: "Cannot add comments in viewing mode.",
+          source: "runtime",
+          details: {
+            reason: "viewing_mode",
+          },
+        };
+        emitError(error);
+        throw toStructuredRuntimeException(error);
+      }
+      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 error: InternalEditorError = {
+          errorId: createSessionId("comment-anchor", clock()),
+          code: "validation_failed",
+          isFatal: false,
+          message:
+            "DOCX comments must use a non-empty range that stays within a single paragraph.",
+          source: "runtime",
+          details: {
+            reason: "invalid_comment_anchor",
+          },
+        };
+        emitError(error);
+        throw toStructuredRuntimeException(error);
+      }
+      const authorId = params.authorId ?? defaultAuthorId ?? "unknown";
+      const createdAt = clock();
+      const entries: CommentEntryRecord[] = [
+        {
+          entryId: `${commentId}-entry-1`,
+          authorId,
+          body: params.body ?? "",
+          createdAt,
+        },
+      ];
+      const comment: CommentThreadRecord = {
+        commentId,
+        anchor,
+        createdAt,
+        createdBy: authorId,
+        authorId,
+        body: params.body ?? "",
+        entries,
+        status: anchor.kind === "detached" ? "detached" : "open",
+        warningIds: [],
+        isResolved: false,
+        metadata: {
+          source: "runtime",
+        },
+      };
+
+      this.dispatch({
+        type: "comment.add",
+        comment,
+        selection,
+        origin: createOrigin("api", clock()),
+      });
+
+      return commentId;
+    },
+    openComment(commentId) {
+      this.dispatch({
+        type: "comment.open",
+        commentId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    resolveComment(commentId) {
+      this.dispatch({
+        type: "comment.resolve",
+        commentId,
+        resolvedBy: defaultAuthorId ?? "unknown",
+        origin: createOrigin("api", clock()),
+      });
+    },
+    reopenComment(commentId) {
+      this.dispatch({
+        type: "comment.reopen",
+        commentId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    addCommentReply(commentId, body, authorId) {
+      this.dispatch({
+        type: "comment.add-reply",
+        commentId,
+        body,
+        authorId: authorId ?? defaultAuthorId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    editCommentBody(commentId, body) {
+      this.dispatch({
+        type: "comment.edit-body",
+        commentId,
+        body,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    acceptChange(changeId) {
+      this.dispatch({
+        type: "change.accept",
+        changeId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    rejectChange(changeId) {
+      this.dispatch({
+        type: "change.reject",
+        changeId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    acceptAllChanges() {
+      this.dispatch({
+        type: "change.accept-all",
+        origin: createOrigin("api", clock()),
+      });
+    },
+    rejectAllChanges() {
+      this.dispatch({
+        type: "change.reject-all",
+        origin: createOrigin("api", clock()),
+      });
+    },
+    openStory(target) {
+      const normalizedTarget =
+        target.kind === "header" || target.kind === "footer"
+          ? normalizeHeaderFooterTarget(
+              state.document,
+              target,
+              cachedRenderSnapshot.pageLayout?.sectionIndex,
+            ) ?? target
+          : target;
+      if (storyTargetsEqual(activeStory, normalizedTarget)) {
+        return true;
+      }
+      if (!isValidStoryTarget(state, normalizedTarget)) {
+        return false;
+      }
+      switchActiveStory(normalizedTarget);
+      return true;
+    },
+    closeStory() {
+      if (activeStory.kind === "main") {
+        return;
+      }
+      switchActiveStory(MAIN_STORY_TARGET);
+    },
+    getActiveStory() {
+      return activeStory;
+    },
+    getViewState() {
+      return getCachedViewStateSnapshot();
+    },
+    setViewMode(mode) {
+      viewState = applyViewMode(viewState, mode);
+      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 = refreshRenderSnapshot();
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    setZoom(level) {
+      viewState = applyZoomLevel(viewState, level);
+      cachedRenderSnapshot = refreshRenderSnapshot();
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    getPageLayoutSnapshot() {
+      return getCachedPageLayoutSnapshot(state, activeStory);
+    },
+    getDocumentNavigationSnapshot() {
+      return getCachedDocumentNavigationSnapshot(state, activeStory);
+    },
+    getCurrentLocation() {
+      const navigation = getCachedDocumentNavigationSnapshot(state, activeStory);
+      return createCurrentLocation({
+        document: state.document,
+        renderSnapshot: cachedRenderSnapshot,
+        navigation,
+        sections: createDocumentSectionSnapshots(state.document, navigation),
+      });
+    },
+    getLocationForSelection(selection: SelectionSnapshot) {
+      const selectionStory = selection.storyTarget ?? activeStory;
+      const navigation = getCachedDocumentNavigationSnapshot(state, selectionStory);
+      return createLocationFromSelection({
+        document: state.document,
+        navigation,
+        sections: createDocumentSectionSnapshots(state.document, navigation),
+        selection,
+      });
+    },
+    getLocationForAnchor(anchor: EditorAnchorProjection, storyTarget?: EditorStoryTarget) {
+      const resolvedStory = storyTarget ?? activeStory;
+      const navigation = getCachedDocumentNavigationSnapshot(state, resolvedStory);
+      return createDocumentLocationSnapshot({
+        document: state.document,
+        navigation,
+        sections: createDocumentSectionSnapshots(state.document, navigation),
+        anchor,
+        storyTarget: resolvedStory,
+        source: { kind: "navigation" },
+      });
+    },
+    captureRestorePoint(input?: SelectionSnapshot | EditorAnchorProjection) {
+      const location =
+        input === undefined
+          ? this.getCurrentLocation()
+          : "activeRange" in input
+            ? this.getLocationForSelection(input)
+            : this.getLocationForAnchor(input, activeStory);
+      if (!location) {
+        return null;
+      }
+      return createRestorePoint({
+        location,
+        revisionToken: state.revisionToken,
+        createdAt: clock(),
+        checkpointType:
+          input === undefined
+            ? "selection"
+            : "activeRange" in input
+              ? "selection"
+              : "manual",
+      });
+    },
+    restoreToPoint(point, options) {
+      if (point.location.anchor.kind === "detached") {
+        return {
+          status: "detached",
+          reasons: [point.location.anchor.reason],
+          location: point.location,
+        };
+      }
+
+      const behavior = options?.behavior ?? "semantic";
+      if (behavior === "exact" && point.revisionToken !== state.revisionToken) {
+        return {
+          status: "blocked",
+          reasons: [
+            "restore point no longer matches the current revision; use semantic replay after content changes",
+          ],
+          location: point.location,
+        };
+      }
+
+      if (
+        point.location.storyTarget &&
+        !storyTargetsEqual(activeStory, point.location.storyTarget)
+      ) {
+        if (point.location.storyTarget.kind === "main") {
+          this.closeStory();
+        } else {
+          this.openStory(point.location.storyTarget);
+        }
+      }
+      const selection = createSelectionFromPublicAnchor(point.location.anchor);
+      this.dispatch({
+        type: "selection.set",
+        selection,
+        origin: createOrigin("api", clock()),
+      });
+      const location = this.getCurrentLocation() ?? point.location;
+      return {
+        status: point.revisionToken === state.revisionToken ? "restored" : "remapped",
+        selection: cachedRenderSnapshot.selection,
+        location,
+      };
+    },
+    getOutlineSnapshot() {
+      return createDocumentOutlineSnapshot({
+        navigation: getCachedDocumentNavigationSnapshot(state, activeStory),
+        activeStory,
+        selectionHead: state.selection.head,
+      });
+    },
+    getTocSnapshot() {
+      return createTocSnapshot(
+        state.document,
+        getCachedDocumentNavigationSnapshot(state, activeStory),
+      );
+    },
+    getSections() {
+      return createDocumentSectionSnapshots(
+        state.document,
+        getCachedDocumentNavigationSnapshot(state, activeStory),
+      );
+    },
+    getSectionSnapshot(input) {
+      const navigation = getCachedDocumentNavigationSnapshot(state, activeStory);
+      const sections = createDocumentSectionSnapshots(state.document, navigation);
+      if (input.headingId) {
+        const heading = navigation.headings.find((entry) => entry.headingId === input.headingId);
+        if (heading) {
+          return sections.find((section) => section.sectionIndex === heading.sectionIndex) ?? null;
+        }
+      }
+      return findDocumentSectionSnapshot(
+        sections,
+        input,
+        createSectionLocations(state.document, sections),
+      );
+    },
+    describeEventImpact(event) {
+      return describeEventImpact(event);
+    },
+    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);
+      return editorSessionStateFromPersistedSnapshot(
+        {
+          ...(createPersistedEditorSnapshot(state, {
+            editorBuild,
+            savedAt: clock(),
+            compatibility,
+            protectionSnapshot,
+          }) as unknown as PersistedEditorSnapshot),
+          workflowMetadata: deriveWorkflowMetadataSnapshot(),
+        },
+      );
+    },
+    getPersistedSnapshot() {
+      return persistedSnapshotFromEditorSessionState(this.getSessionState(), {
+        savedAt: clock(),
+      });
+    },
+    getCompatibilityReport() {
+      return toPublicCompatibilityReport(createDerivedCompatibility(state));
+    },
+    getWarnings() {
+      return state.warnings.map((warning) => toPublicWarning(warning));
+    },
+    getSuggestionsSnapshot() {
+      return getCachedSuggestionsSnapshot(state);
+    },
+    async exportDocx(exportOptions) {
+      if (!options.exportDocx) {
+        const error: InternalEditorError = {
+          errorId: createEntityId("error", {}, clock()),
+          code: "export_failed",
+          isFatal: false,
+          message: "DOCX export requires an injected exporter until the IO substrate lands.",
+          source: "export",
+          details: {
+            requestedOptions: exportOptions ?? {},
+          },
+        };
+        emitError(error);
+        throw toStructuredRuntimeException(error);
+      }
+
+      const result = await options.exportDocx(this.getSessionState(), exportOptions);
+
+      emit({
+        type: "export_completed",
+        documentId: state.documentId,
+        result,
+      });
+
+      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 getCachedWorkflowMarkupSnapshot();
+    },
+    setWorkflowMetadataDefinitions(definitions) {
+      workflowMetadataDefinitions = structuredClone(definitions);
+      const snapshot = deriveWorkflowMetadataSnapshot();
+      emit({
+        type: "workflow_metadata_changed",
+        documentId: state.documentId,
+        snapshot,
+      });
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    clearWorkflowMetadataDefinitions() {
+      workflowMetadataDefinitions = [];
+      const snapshot = deriveWorkflowMetadataSnapshot();
+      emit({
+        type: "workflow_metadata_changed",
+        documentId: state.documentId,
+        snapshot,
+      });
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    setWorkflowMetadataEntries(entries) {
+      workflowMetadataEntries = structuredClone(entries);
+      const snapshot = deriveWorkflowMetadataSnapshot();
+      emit({
+        type: "workflow_metadata_changed",
+        documentId: state.documentId,
+        snapshot,
+      });
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    clearWorkflowMetadataEntries() {
+      workflowMetadataEntries = [];
+      const snapshot = deriveWorkflowMetadataSnapshot();
+      emit({
+        type: "workflow_metadata_changed",
+        documentId: state.documentId,
+        snapshot,
+      });
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    getWorkflowMetadataSnapshot() {
+      return deriveWorkflowMetadataSnapshot();
+    },
+    setHostAnnotationOverlay(overlay) {
+      hostAnnotationOverlay = structuredClone(overlay);
+      emit({
+        type: "host_annotation_overlay_changed",
+        documentId: state.documentId,
+        snapshot: deriveHostAnnotationSnapshot(),
+      });
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    clearHostAnnotationOverlay() {
+      hostAnnotationOverlay = null;
+      emit({
+        type: "host_annotation_overlay_changed",
+        documentId: state.documentId,
+        snapshot: deriveHostAnnotationSnapshot(),
+      });
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    getHostAnnotationSnapshot() {
+      return deriveHostAnnotationSnapshot();
+    },
+    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;
+      }
+      const targetStory = target.storyTarget ?? MAIN_STORY_TARGET;
+      if (!storyTargetsEqual(activeStory, targetStory)) {
+        if (targetStory.kind === "main") {
+          this.closeStory();
+        } else if (!this.openStory(targetStory)) {
+          return;
+        }
+      }
+      this.replaceText(text, target.anchor);
+    },
+    getDocumentTextStream() {
+      return cachedRenderSnapshot.surface
+        ? createDocumentTextStreamSnapshots({
+            surface: cachedRenderSnapshot.surface,
+            navigation: getCachedDocumentNavigationSnapshot(state, activeStory),
+          })
+        : [];
+    },
+    getStoryTextStream(target: EditorStoryTarget) {
+      return this.getDocumentTextStream().find((stream) => storyTargetsEqual(stream.target, target)) ?? null;
+    },
+    getDocumentChunks() {
+      return createDocumentChunks({
+        document: state.document,
+        renderSnapshot: cachedRenderSnapshot,
+        navigation: getCachedDocumentNavigationSnapshot(state, activeStory),
+      });
+    },
+    getWorkflowChunks() {
+      return createWorkflowChunks({
+        document: state.document,
+        navigation: getCachedDocumentNavigationSnapshot(state, activeStory),
+        workflowMarkup: getCachedWorkflowMarkupSnapshot(),
+      });
+    },
+    getReviewWorkSnapshot() {
+      return createReviewWorkSnapshot({
+        comments: cachedRenderSnapshot.comments,
+        trackedChanges: cachedRenderSnapshot.trackedChanges,
+        workflowMarkup: getCachedWorkflowMarkupSnapshot(),
+        document: state.document,
+        navigation: getCachedDocumentNavigationSnapshot(state, activeStory),
+      });
+    },
+    getRuntimeContextAnalytics(query) {
+      return getCachedRuntimeContextAnalytics(query);
+    },
+  };
+
+  function applyHistory(direction: "undo" | "redo"): void {
+    const source = direction === "undo" ? history.past : history.future;
+    const target = source.pop();
+
+    if (!target) {
+      return;
+    }
+
+    const counterpart = direction === "undo" ? history.future : history.past;
+    counterpart.push(state);
+
+    const previous = state;
+    // Undo/redo changes the document — must mint a new revisionToken so
+    // autosave/export checkpoint dedup treats it as fresh content.
+    state = finalizeState(target, true, clock(), previous.revision);
+    storySelections.set(storyTargetKey(activeStory), state.selection);
+    cachedRenderSnapshot = refreshRenderSnapshot();
+    notify(previous, state, {
+      nextState: state,
+      mapping: { steps: [] },
+      effects: {
+        warningsAdded: [],
+        warningsCleared: [],
+      },
+      historyBoundary: "skip",
+      markDirty: true,
+    });
+  }
+
+  function commit(transaction: EditorTransaction): void {
+    const previous = state;
+
+    if (transaction.historyBoundary === "push") {
+      history.past.push(state);
+      history.future = [];
+    }
+
+    protectionSnapshot = remapProtectionSnapshot(protectionSnapshot, transaction.mapping);
+    state = finalizeState(transaction.nextState, transaction.markDirty, clock());
+    storySelections.set(storyTargetKey(activeStory), state.selection);
+    cachedRenderSnapshot = refreshRenderSnapshot();
+    notify(previous, state, transaction);
+  }
+
+  function notify(
+    previous: EditorState,
+    next: EditorState,
+    transaction: EditorTransaction,
+  ): void {
+    const emittedSuggestionIds = new Set<string>();
+    if (previous.isDirty !== next.isDirty) {
+      emit({
+        type: "dirty_changed",
+        documentId: next.documentId,
+        isDirty: next.isDirty,
+      });
+    }
+
+    if (selectionChanged(previous.selection, next.selection)) {
+      emit({
+        type: "selection_changed",
+        documentId: next.documentId,
+        selection: toPublicSelectionSnapshot(next.selection, activeStory),
+      });
+    }
+
+    if (transaction.effects.commentAdded) {
+      emit({
+        type: "comment_added",
+        documentId: next.documentId,
+        commentId: transaction.effects.commentAdded.commentId,
+        anchor: toPublicAnchorProjection(transaction.effects.commentAdded.anchor),
+      });
+    }
+
+    if (transaction.effects.commentResolved) {
+      emit({
+        type: "comment_resolved",
+        documentId: next.documentId,
+        commentId: transaction.effects.commentResolved.commentId,
+      });
+    }
+
+    if (transaction.effects.changeAccepted) {
+      emit({
+        type: "change_accepted",
+        documentId: next.documentId,
+        changeId: transaction.effects.changeAccepted.changeId,
+      });
+      const updatedSuggestion = findSuggestionByChangeId(
+        getCachedSuggestionsSnapshot(next),
+        transaction.effects.changeAccepted.changeId,
+      );
+      if (updatedSuggestion) {
+        emit({
+          type: "suggestion_updated",
+          documentId: next.documentId,
+          suggestionId: updatedSuggestion.suggestionId,
+          changeIds: updatedSuggestion.changeIds,
+          suggestionKind: updatedSuggestion.kind,
+          status: updatedSuggestion.status,
+          storyTarget: updatedSuggestion.storyTarget,
+          anchor: updatedSuggestion.anchor,
+        });
+      }
+    }
+
+    if (transaction.effects.changeRejected) {
+      emit({
+        type: "change_rejected",
+        documentId: next.documentId,
+        changeId: transaction.effects.changeRejected.changeId,
+      });
+      const updatedSuggestion = findSuggestionByChangeId(
+        getCachedSuggestionsSnapshot(next),
+        transaction.effects.changeRejected.changeId,
+      );
+      if (updatedSuggestion) {
+        emit({
+          type: "suggestion_updated",
+          documentId: next.documentId,
+          suggestionId: updatedSuggestion.suggestionId,
+          changeIds: updatedSuggestion.changeIds,
+          suggestionKind: updatedSuggestion.kind,
+          status: updatedSuggestion.status,
+          storyTarget: updatedSuggestion.storyTarget,
+          anchor: updatedSuggestion.anchor,
+        });
+      }
+    }
+
+    if (transaction.effects.revisionAuthored) {
+      emit({
+        type: "change_authored",
+        documentId: next.documentId,
+        changeId: transaction.effects.revisionAuthored.changeId,
+        kind: transaction.effects.revisionAuthored.kind,
+      });
+      const authoredSuggestion = findSuggestionByChangeId(
+        getCachedSuggestionsSnapshot(next),
+        transaction.effects.revisionAuthored.changeId,
+      );
+      if (authoredSuggestion) {
+        emittedSuggestionIds.add(authoredSuggestion.suggestionId);
+        emit({
+          type: "suggestion_authored",
+          documentId: next.documentId,
+          suggestionId: authoredSuggestion.suggestionId,
+          changeIds: authoredSuggestion.changeIds,
+          suggestionKind: authoredSuggestion.kind,
+          storyTarget: authoredSuggestion.storyTarget,
+          anchor: authoredSuggestion.anchor,
+          isReplacement: authoredSuggestion.isReplacement,
+        });
+      }
+    }
+
+    const addedRevisionIds = Object.keys(next.document.review.revisions).filter(
+      (revisionId) => previous.document.review.revisions[revisionId] === undefined,
+    );
+    if (addedRevisionIds.length > 0) {
+      const suggestionsSnapshot = getCachedSuggestionsSnapshot(next);
+      for (const revisionId of addedRevisionIds) {
+        const authoredSuggestion = findSuggestionByChangeId(suggestionsSnapshot, revisionId);
+        if (!authoredSuggestion || emittedSuggestionIds.has(authoredSuggestion.suggestionId)) {
+          continue;
+        }
+        emittedSuggestionIds.add(authoredSuggestion.suggestionId);
+        emit({
+          type: "suggestion_authored",
+          documentId: next.documentId,
+          suggestionId: authoredSuggestion.suggestionId,
+          changeIds: authoredSuggestion.changeIds,
+          suggestionKind: authoredSuggestion.kind,
+          storyTarget: authoredSuggestion.storyTarget,
+          anchor: authoredSuggestion.anchor,
+          isReplacement: authoredSuggestion.isReplacement,
+        });
+      }
+    }
+
+    if (transaction.effects.commandBlocked) {
+      emit({
+        type: "command_blocked",
+        documentId: next.documentId,
+        command: transaction.effects.commandBlocked.code,
+        reasons: [{
+          code: transaction.effects.commandBlocked.code as WorkflowBlockedCommandReason["code"],
+          message: transaction.effects.commandBlocked.message,
+        }],
+      });
+    }
+
+    for (const warning of transaction.effects.warningsAdded) {
+      const publicWarning = toPublicWarning(warning);
+      emit({
+        type: "warning_added",
+        documentId: next.documentId,
+        warning: publicWarning,
+      });
+      options.onWarning?.(publicWarning);
+    }
+
+    for (const cleared of transaction.effects.warningsCleared) {
+      emit({
+        type: "warning_cleared",
+        documentId: next.documentId,
+        warningId: cleared.warningId,
+        code: cleared.code,
+      });
+    }
+
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  function applyTextCommandInActiveStory(
+    command: ActiveStoryTextCommand,
+    options: {
+      selection?: EditorState["selection"];
+      blockedCommandName?: string;
+    } = {},
+  ): void {
+    const selection = options.selection ?? state.selection;
+    if (
+      activeStory.kind !== "main" &&
+      getEffectiveDocumentMode(selection) === "suggesting" &&
+      command.type === "paragraph.split"
+    ) {
+      emit({
+        type: "command_blocked",
+        documentId: state.documentId,
+        command: options.blockedCommandName ?? command.type,
+        reasons: [{
+          code: "suggesting_unsupported",
+          message: `"${command.type}" is not supported in suggesting mode for this story.`,
+          storyTarget: activeStory,
+        }],
+      });
+      return;
+    }
+    const blockedReasons = evaluateWorkflowBlockedReasons(selection, command.type);
+    if (blockedReasons.length > 0) {
+      emit({
+        type: "command_blocked",
+        documentId: state.documentId,
+        command: options.blockedCommandName ?? command.type,
+        reasons: blockedReasons,
+      });
+      return;
+    }
+
+    const timestamp = command.origin?.timestamp ?? clock();
+    const context = {
+      timestamp,
+      documentMode: getEffectiveDocumentMode(selection),
+      defaultAuthorId: defaultAuthorId ?? undefined,
+    } as const;
+    const baseState = selection === state.selection
+      ? state
+      : {
+          ...state,
+          selection,
+        };
+
+    if (activeStory.kind === "main") {
+      commit(executeEditorCommand(baseState, command, context));
+      return;
+    }
+
+    const localState = createEditorState({
+      documentId: state.documentId,
+      sessionId,
+      sourceLabel: state.sourceLabel,
+      readOnly: state.readOnly,
+      canonicalDocument: {
+        ...state.document,
+        content: {
+          type: "doc",
+          children: [...getStoryBlocks(state.document, activeStory)],
+        },
+        review: createSecondaryStoryLocalReviewState(state.document.review, activeStory),
+      },
+      compatibility: state.compatibility,
+      warnings: state.warnings,
+      fatalError: state.fatalError,
+    });
+    localState.selection = selection;
+    const localTransaction = executeEditorCommand(localState, command, context);
+
+    if (!localTransaction.markDirty) {
+      notify(state, state, {
+        nextState: state,
+        mapping: createEmptyMapping(),
+        effects: localTransaction.effects,
+        historyBoundary: "skip",
+        markDirty: false,
+      });
+      return;
+    }
+
+    const nextDocument = replaceStoryBlocks(
+      state.document,
+      activeStory,
+      localTransaction.nextState.document.content.children,
+    );
+    const nextDocumentWithReview = {
+      ...nextDocument,
+      review: mergeSecondaryStoryReviewState(
+        state.document.review,
+        localTransaction.nextState.document.review,
+        localTransaction.effects,
+        activeStory,
+      ),
+    };
+    const fullTransaction = executeEditorCommand(
+      baseState,
+      {
+        type: "document.replace",
+        document: nextDocumentWithReview,
+        selection: localTransaction.nextState.selection,
+        mapping: createEmptyMapping(),
+        protectionSelection: selection,
+        origin: command.origin,
+      },
+      context,
+    );
+
+    commit({
+      ...fullTransaction,
+      effects: mergeTransactionEffects(fullTransaction.effects, localTransaction.effects),
+    });
+  }
+
+  function mergeTransactionEffects(
+    base: EditorTransaction["effects"],
+    local: EditorTransaction["effects"],
+  ): EditorTransaction["effects"] {
+    return {
+      warningsAdded: [...base.warningsAdded, ...local.warningsAdded],
+      warningsCleared: [...base.warningsCleared, ...local.warningsCleared],
+      commentAdded: base.commentAdded ?? local.commentAdded,
+      commentResolved: base.commentResolved ?? local.commentResolved,
+      commentReopened: base.commentReopened ?? local.commentReopened,
+      commentReplyAdded: base.commentReplyAdded ?? local.commentReplyAdded,
+      commentBodyEdited: base.commentBodyEdited ?? local.commentBodyEdited,
+      changeAccepted: base.changeAccepted ?? local.changeAccepted,
+      changeRejected: base.changeRejected ?? local.changeRejected,
+      revisionAuthored: base.revisionAuthored ?? local.revisionAuthored,
+      commandBlocked: base.commandBlocked ?? local.commandBlocked,
+    };
+  }
+
+  function mergeSecondaryStoryReviewState(
+    currentReview: EditorState["document"]["review"],
+    localReview: EditorState["document"]["review"],
+    effects: EditorTransaction["effects"],
+    storyTarget: EditorStoryTarget,
+  ): EditorState["document"]["review"] {
+    const nextReview: EditorState["document"]["review"] = {
+      comments: { ...currentReview.comments },
+      revisions: { ...currentReview.revisions },
+    };
+
+    const currentStoryRevisionIds = Object.values(currentReview.revisions)
+      .filter((revision) => storyTargetsEqual(getRevisionStoryTarget(revision), storyTarget))
+      .map((revision) => revision.changeId);
+    for (const revisionId of currentStoryRevisionIds) {
+      delete nextReview.revisions[revisionId];
+    }
+    for (const revision of Object.values(localReview.revisions)) {
+      nextReview.revisions[revision.changeId] = {
+        ...revision,
+        metadata: {
+          ...revision.metadata,
+          storyTarget: createRevisionStoryTargetRecord(storyTarget),
+        },
+      };
+    }
+
+    if (effects.commentAdded) {
+      const commentId = effects.commentAdded.commentId;
+      const comment = localReview.comments[commentId];
+      if (comment) {
+        nextReview.comments[commentId] = comment;
+      }
+    }
+
+    return nextReview;
+  }
+
+  function emit(event: DocumentRuntimeEvent): void {
+    emitInternal(event);
+    if (shouldEmitContextAnalyticsChanged(event)) {
+      emitContextAnalyticsChanged();
+    }
+  }
+
+  function emitInternal(event: DocumentRuntimeEvent): void {
+    options.onEvent?.(event);
+    for (const listener of eventListeners) {
+      listener(event);
+    }
+  }
+
+  function shouldEmitContextAnalyticsChanged(event: DocumentRuntimeEvent): boolean {
+    switch (event.type) {
+      case "selection_changed":
+      case "story_changed":
+      case "workflow_overlay_changed":
+      case "workflow_active_work_item_changed":
+      case "change_authored":
+      case "change_accepted":
+      case "change_rejected":
+      case "comment_added":
+      case "comment_resolved":
+      case "warning_added":
+      case "warning_cleared":
+      case "error":
+      case "ready":
+      case "command_blocked":
+      case "suggestion_authored":
+      case "suggestion_updated":
+        return true;
+      case "context_analytics_changed":
+      case "dirty_changed":
+      case "autosave_state":
+      case "snapshot_saved":
+      case "session_saved":
+      case "export_completed":
+      case "host_annotation_overlay_changed":
+        return false;
+      default:
+        return false;
+    }
+  }
+
+  function emitContextAnalyticsChanged(): void {
+    const trackedSnapshots = collectTrackedContextAnalyticsSnapshots();
+    if (
+      lastEmittedContextAnalyticsSnapshots !== undefined &&
+      trackedContextAnalyticsSnapshotsEqual(lastEmittedContextAnalyticsSnapshots, trackedSnapshots)
+    ) {
+      return;
+    }
+    lastEmittedContextAnalyticsSnapshots = trackedSnapshots;
+    emitInternal({
+      type: "context_analytics_changed",
+      documentId: state.documentId,
+      snapshot:
+        trackedSnapshots.get(
+          getRuntimeContextAnalyticsQueryKey(
+            resolveCurrentContextAnalyticsQuery({
+              workflowScopeSnapshot: getCachedWorkflowScopeSnapshot(),
+              interactionGuardSnapshot: getCachedInteractionGuardSnapshot(),
+            }),
+          ),
+        ) ?? null,
+    });
+  }
+
+  function emitError(error: InternalEditorError): void {
+    const nextState: EditorState = {
+      ...state,
+      phase: error.isFatal ? "error" : state.phase,
+      fatalError: error.isFatal ? error : state.fatalError,
+    };
+    state = nextState;
+    storySelections.set(storyTargetKey(activeStory), state.selection);
+    cachedRenderSnapshot = refreshRenderSnapshot();
+    const publicError = toPublicError(error);
+    options.onError?.(publicError);
+    emit({
+      type: "error",
+      documentId: state.documentId,
+      error: publicError,
+    });
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  function switchActiveStory(target: EditorStoryTarget): void {
+    const previousStory = activeStory;
+    const previousSelection = state.selection;
+    storySelections.set(storyTargetKey(previousStory), previousSelection);
+
+    const restoredSelection =
+      storySelections.get(storyTargetKey(target)) ?? createSelectionSnapshot(0, 0);
+    activeStory = target;
+    state = {
+      ...state,
+      selection: restoredSelection,
+    };
+    storySelections.set(storyTargetKey(target), restoredSelection);
+    cachedRenderSnapshot = refreshRenderSnapshot();
+
+    if (selectionChanged(previousSelection, restoredSelection)) {
+      emit({
+        type: "selection_changed",
+        documentId: state.documentId,
+        selection: toPublicSelectionSnapshot(restoredSelection, activeStory),
+      });
+    }
+
+    emit({
+      type: "story_changed",
+      documentId: state.documentId,
+      activeStory,
+    });
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+}
+
+function createSessionId(documentId: string, timestamp: string): string {
+  return `session-${documentId}-${timestamp.replace(/[^0-9]/gu, "")}`;
+}
+
+function createOrigin(
+  source: CommandOrigin["source"],
+  timestamp: string,
+): CommandOrigin {
+  return {
+    source,
+    timestamp,
+  };
+}
+
+function createEntityId(
+  prefix: string,
+  existing: Record<string, unknown>,
+  timestamp: string,
+): string {
+  let counter = Object.keys(existing).length;
+  let nextId = `${prefix}-${timestamp.replace(/[^0-9]/gu, "")}-${counter}`;
+
+  while (existing[nextId]) {
+    counter += 1;
+    nextId = `${prefix}-${timestamp.replace(/[^0-9]/gu, "")}-${counter}`;
+  }
+
+  return nextId;
+}
+
+function finalizeState(
+  state: EditorState,
+  markDirty: boolean,
+  timestamp: string,
+  baseRevision?: number,
+): EditorState {
+  // Only increment revision on actual document mutations (markDirty=true).
+  // Selection-only changes must not churn the revisionToken, which would
+  // cause autosave/checkpoint dedup to treat cursor movement as new content.
+  const revision = markDirty ? (baseRevision ?? state.revision) + 1 : state.revision;
+
+  return {
+    ...state,
+    document: {
+      ...state.document,
+      updatedAt: markDirty ? timestamp : state.document.updatedAt,
+    },
+    selection: state.selection,
+    revision,
+    revisionToken: `${state.sessionId}:${revision}`,
+    isDirty: state.isDirty || markDirty,
+  };
+}
+
+function toRuntimeError(error: unknown): InternalEditorError {
+  if (typeof error === "object" && error && "message" in error) {
+    if (
+      "code" in error
+      && "source" in error
+      && "isFatal" in error
+      && typeof (error as { code?: unknown }).code === "string"
+      && typeof (error as { source?: unknown }).source === "string"
+      && typeof (error as { isFatal?: unknown }).isFatal === "boolean"
+    ) {
+      return {
+        errorId:
+          typeof (error as { errorId?: unknown }).errorId === "string"
+            ? String((error as { errorId?: unknown }).errorId)
+            : createSessionId("runtime-error", new Date().toISOString()),
+        code: (error as { code: InternalEditorError["code"] }).code,
+        isFatal: (error as { isFatal: boolean }).isFatal,
+        message: String((error as { message?: unknown }).message ?? "Runtime error"),
+        source: (error as { source: InternalEditorError["source"] }).source,
+        details:
+          typeof (error as { details?: unknown }).details === "object"
+            && (error as { details?: unknown }).details !== null
+            ? ((error as { details?: Record<string, unknown> }).details)
+            : undefined,
+      };
+    }
+    return {
+      errorId: createSessionId("runtime-error", new Date().toISOString()),
+      code: "internal_invariant",
+      isFatal: false,
+      message: String((error as { message?: unknown }).message ?? "Runtime error"),
+      source: "runtime",
+    };
+  }
+
+  return {
+    errorId: createSessionId("runtime-error", new Date().toISOString()),
+    code: "internal_invariant",
+    isFatal: false,
+    message: "Runtime error",
+    source: "runtime",
+  };
+}
+
+function toStructuredRuntimeException<T extends InternalEditorError>(
+  error: T,
+): Error & T {
+  return Object.assign(new Error(error.message), error);
+}
+
+function toPublicDocumentStats(state: Pick<EditorState, "document">) {
+  const stats = deriveDocumentStats(state);
+  return {
+    storyLength: stats.characterCount,
+    commentCount: stats.commentCount,
+    revisionCount: stats.revisionCount,
+    opaqueFragmentCount: countOpaqueFragments(state.document.preservation.opaqueFragments),
+  };
+}
+
+function toPublicSelectionSnapshot(
+  selection: EditorState["selection"],
+  storyTarget?: EditorStoryTarget,
+): SelectionSnapshot {
+  return {
+    anchor: selection.anchor,
+    head: selection.head,
+    isCollapsed: selection.isCollapsed,
+    activeRange: toPublicAnchorProjection(selection.activeRange),
+    ...(storyTarget && storyTarget.kind !== "main" ? { storyTarget } : {}),
+  };
+}
+
+function toPublicAnchorProjection(
+  anchor: InternalEditorAnchorProjection,
+): EditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        kind: "range",
+        from: anchor.range.from,
+        to: anchor.range.to,
+        assoc: anchor.assoc,
+      };
+    case "node":
+      return {
+        kind: "node",
+        at: anchor.at,
+        assoc: anchor.assoc,
+      };
+    case "detached":
+      return {
+        kind: "detached",
+        lastKnownRange: anchor.lastKnownRange,
+        reason: anchor.reason,
+      };
+  }
+}
+
+function toInternalAnchorProjection(
+  anchor: EditorAnchorProjection,
+): InternalEditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range":
+      return createRangeAnchor(anchor.from, anchor.to, anchor.assoc);
+    case "node":
+      return createNodeAnchor(anchor.at, anchor.assoc);
+    case "detached":
+      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
+  }
+}
+
+function createSelectionFromPublicAnchor(
+  anchor: EditorAnchorProjection,
+): import("../core/state/editor-state.ts").SelectionSnapshot {
+  switch (anchor.kind) {
+    case "range":
+      return createSelectionSnapshot(anchor.from, anchor.to);
+    case "node":
+      return createSelectionSnapshot(anchor.at, anchor.at);
+    case "detached":
+      return createSelectionSnapshot(
+        anchor.lastKnownRange.from,
+        anchor.lastKnownRange.to,
+      );
+  }
+}
+
+function toPublicCompatibilityReport(
+  report: InternalCompatibilityReport,
+): CompatibilityReport {
+  return {
+    reportVersion: report.reportVersion,
+    generatedAt: report.generatedAt,
+    blockExport: report.blockExport,
+    featureEntries: report.featureEntries.map((entry) =>
+      toPublicCompatibilityFeatureEntry(entry),
+    ),
+    warnings: report.warnings.map((warning) => toPublicWarning(warning)),
+    errors: report.errors.map((error) => toPublicError(error)),
+  };
+}
+
+function toPublicCompatibilityFeatureEntry(
+  entry: InternalCompatibilityFeatureEntry,
+) {
+  return {
+    ...entry,
+    affectedAnchor: entry.affectedAnchor
+      ? toPublicAnchorProjection(entry.affectedAnchor)
+      : undefined,
+  };
+}
+
+function toPublicWarning(warning: InternalEditorWarning): EditorWarning {
+  return {
+    ...warning,
+    affectedAnchor: warning.affectedAnchor
+      ? toPublicAnchorProjection(warning.affectedAnchor)
+      : undefined,
+  };
+}
+
+function toPublicError(error: InternalEditorError): EditorError {
+  return { ...error };
+}
+
+function countOpaqueFragments(opaqueFragments: Record<string, unknown>): number {
+  return Object.keys(opaqueFragments).length;
+}
+
+function createDerivedCompatibility(state: EditorState): InternalCompatibilityReport {
+  const derived = buildCompatibilityReport({
+    document: state.document,
+    warnings: state.warnings,
+    fatalError: state.fatalError,
+    generatedAt: state.document.updatedAt,
+  });
+
+  return mergeCompatibilityReports([state.compatibility as never, derived as never], {
+    generatedAt: state.document.updatedAt,
+    blockExport: state.compatibility.blockExport || derived.blockExport,
+  }) as InternalCompatibilityReport;
+}
+
+function toPublicCommentSidebarSnapshot(
+  state: EditorState,
+): CommentSidebarSnapshot {
+  const projection = createCommentSidebarProjection(
+    createCommentStoreFromRuntimeComments(state.document.review.comments),
+    state.runtime.activeCommentId,
+  );
+
+  return {
+    activeCommentId: state.runtime.activeCommentId,
+    openCommentIds: projection.openCommentIds,
+    resolvedCommentIds: projection.resolvedCommentIds,
+    detachedCommentIds: projection.detachedCommentIds,
+    totalCount: projection.totalCount,
+    threads: projection.threads.map((thread): CommentSidebarThreadSnapshot => {
+      const sourceThread = state.document.review.comments[thread.commentId];
+      const projectedEntries =
+        sourceThread?.entries?.map((entry) => ({
+          entryId: entry.entryId,
+          authorId: entry.authorId,
+          body: entry.body,
+          createdAt: entry.createdAt,
+        })) ??
+        (sourceThread?.body
+          ? [
+              {
+                entryId: `${thread.commentId}-entry-1`,
+                authorId:
+                  sourceThread.authorId ?? sourceThread.createdBy ?? "unknown",
+                body: sourceThread.body,
+                createdAt: sourceThread.createdAt,
+              },
+            ]
+          : []);
+
+      return {
+        commentId: thread.commentId,
+        status: thread.status,
+        anchor: toPublicAnchorProjection(
+          sourceThread?.anchor ??
+            createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
+        ),
+        excerpt: thread.excerpt,
+        entryCount: thread.entryCount,
+        createdAt: thread.createdAt,
+        createdBy: thread.createdBy,
+        warningCount: thread.warningCount,
+        anchorLabel: thread.anchorLabel,
+        detachedReason: sourceThread?.metadata?.detachedReason,
+        actionabilityNote: sourceThread?.metadata?.actionabilityNote,
+        isActive: thread.isActive,
+        resolvedAt: thread.resolvedAt,
+        resolvedBy: thread.resolvedBy,
+        entries: projectedEntries,
+      };
+    }),
+  };
+}
+
+function toPublicTrackedChangesSnapshot(
+  state: EditorState,
+): TrackedChangesSnapshot {
+  const projection = createRevisionSidebarProjection(
+    createRevisionStoreFromDocument(state),
+  );
+  const storyPlainTextCache = new Map<string, string>();
+
+  return {
+    pendingChangeIds: projection.activeRevisionIds,
+    acceptedChangeIds: projection.acceptedRevisionIds,
+    rejectedChangeIds: projection.rejectedRevisionIds,
+    detachedChangeIds: projection.detachedRevisionIds,
+    actionableChangeIds: projection.actionableRevisionIds,
+    preserveOnlyChangeIds: projection.preserveOnlyRevisionIds,
+    totalCount: projection.totalCount,
+    revisions: projection.revisions.map((revision): TrackedChangeEntrySnapshot => {
+      const sourceRevision = state.document.review.revisions[revision.revisionId];
+      const storyTarget = getRevisionStoryTarget(sourceRevision);
+      const preview = describeRevisionPreview(
+        revision,
+        sourceRevision?.anchor ??
+          createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
+        getStoryPlainText(state.document, storyTarget, storyPlainTextCache),
+      );
+
+      return {
+        revisionId: revision.revisionId,
+        kind: revision.kind,
+        source: sourceRevision?.metadata?.source ?? "runtime",
+        suggestionId: sourceRevision?.metadata?.suggestionId,
+        semanticKind: sourceRevision?.metadata?.semanticKind,
+        linkedRevisionIds: sourceRevision?.metadata?.linkedRevisionIds,
+        predecessorSuggestionId: sourceRevision?.metadata?.predecessorSuggestionId,
+        label: revision.label,
+        status: revision.status,
+        actionability: revision.actionability,
+        storyTarget,
+        anchor: toPublicAnchorProjection(
+          sourceRevision?.anchor ??
+            createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
+        ),
+        anchorLabel: revision.anchorLabel,
+        createdAt: revision.createdAt,
+        authorId: revision.authorId,
+        warningCount: revision.warningCount,
+        canAccept: revision.canAccept,
+        canReject: revision.canReject,
+        importedRevisionForm: sourceRevision?.metadata?.importedRevisionForm,
+        preserveOnlyReason: revision.preserveOnlyReason,
+        excerpt: preview.excerpt,
+        detail: preview.detail,
+      };
+    }),
+  };
+}
+
+function createRevisionStoreFromDocument(
+  state: Pick<EditorState, "document">,
+): RevisionStore {
+  return {
+    version: "revision-store/1",
+    revisions: Object.fromEntries(
+      Object.values(state.document.review.revisions).map((revision) => [
+        revision.changeId,
+        {
+          revisionId: revision.changeId,
+          kind: revision.kind,
+          anchor: revision.anchor,
+          authorId: revision.authorId ?? "unknown",
+          createdAt: revision.createdAt,
+          status:
+            revision.status === "open"
+              ? "active"
+              : revision.status,
+          warningIds: [...(revision.warningIds ?? [])],
+          metadata: {
+            source: revision.metadata?.source ?? "runtime",
+            storyTarget: revision.metadata?.storyTarget,
+            preserveOnlyReason: revision.metadata?.preserveOnlyReason,
+            suggestionId: revision.metadata?.suggestionId,
+            semanticKind: revision.metadata?.semanticKind,
+            linkedRevisionIds: revision.metadata?.linkedRevisionIds,
+            predecessorSuggestionId: revision.metadata?.predecessorSuggestionId,
+            importedRevisionForm: revision.metadata?.importedRevisionForm,
+            originalRevisionType: revision.metadata?.originalRevisionType,
+            ooxmlRevisionId: revision.metadata?.ooxmlRevisionId,
+          },
+        },
+      ]),
+    ),
+  };
+}
+
+function getRevisionStoryTarget(
+  revision: EditorState["document"]["review"]["revisions"][string] | undefined,
+): EditorStoryTarget {
+  const storyTarget = revision?.metadata?.storyTarget;
+  return storyTarget ? { ...storyTarget } : MAIN_STORY_TARGET;
+}
+
+function findSuggestionByChangeId(
+  snapshot: SuggestionsSnapshot,
+  changeId: string,
+) {
+  return snapshot.suggestions.find((suggestion) => suggestion.changeIds.includes(changeId));
+}
+
+function createSecondaryStoryLocalReviewState(
+  review: EditorState["document"]["review"],
+  storyTarget: EditorStoryTarget,
+): EditorState["document"]["review"] {
+  return {
+    comments: {},
+    revisions: Object.fromEntries(
+      Object.values(review.revisions)
+        .filter((revision) => storyTargetsEqual(getRevisionStoryTarget(revision), storyTarget))
+        .map((revision) => [
+          revision.changeId,
+          {
+            ...revision,
+            metadata: {
+              ...revision.metadata,
+              storyTarget: createRevisionStoryTargetRecord(storyTarget),
+            },
+          },
+        ]),
+    ),
+  };
+}
+
+function getStoryPlainText(
+  document: CanonicalDocumentEnvelope,
+  storyTarget: EditorStoryTarget,
+  cache: Map<string, string>,
+): string {
+  const key = storyTargetKey(storyTarget);
+  const cached = cache.get(key);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const plainText = createEditorSurfaceSnapshot(
+    document,
+    createSelectionSnapshot(0, 0),
+    storyTarget,
+  ).plainText;
+  cache.set(key, plainText);
+  return plainText;
+}
+
+function createRevisionStoryTargetRecord(
+  storyTarget: EditorStoryTarget,
+): NonNullable<NonNullable<EditorState["document"]["review"]["revisions"][string]["metadata"]>["storyTarget"]> {
+  return { ...storyTarget };
+}
+
+function listBlockExportReasons(
+  report: InternalCompatibilityReport,
+): string[] {
+  return [
+    ...report.featureEntries
+      .filter((entry) => entry.featureClass === "unsupported-fatal")
+      .map((entry) => entry.message),
+    ...report.errors
+      .filter((error) => error.isFatal)
+      .map((error) => error.message),
+  ];
+}
+
+function describeRevisionPreview(
+  revision: ReturnType<typeof createRevisionSidebarProjection>["revisions"][number],
+  anchor: InternalEditorAnchorProjection,
+  plainText: string,
+): { excerpt: string; detail: string } {
+  const { from, to } = toAnchorBounds(anchor);
+  const excerpt = summarizeRevisionExcerpt(plainText, from, to, revision.label);
+
+  if (revision.actionability === "preserve-only") {
+    return {
+      excerpt,
+      detail:
+        revision.preserveOnlyReason ??
+        "Visible for review, but this change remains preserve-only in the current runtime.",
+    };
+  }
+
+  if (revision.status === "accepted") {
+    return {
+      excerpt,
+      detail: "Accepted in the live review runtime and retained here for audit visibility.",
+    };
+  }
+
+  if (revision.status === "rejected") {
+    return {
+      excerpt,
+      detail: "Rejected in the live review runtime and retained here for audit visibility.",
+    };
+  }
+
+  return {
+    excerpt,
+    detail:
+      revision.kind === "deletion"
+        ? "Deleted content stays reviewable here until it is accepted or rejected."
+        : "Runtime-backed change. Review it here or reopen the anchor in the canvas.",
+  };
+}
+
+function toAnchorBounds(anchor: InternalEditorAnchorProjection): { from: number; to: number } {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        from: Math.min(anchor.range.from, anchor.range.to),
+        to: Math.max(anchor.range.from, anchor.range.to),
+      };
+    case "node":
+      return {
+        from: anchor.at,
+        to: anchor.at + 1,
+      };
+    case "detached":
+      return {
+        from: Math.min(anchor.lastKnownRange.from, anchor.lastKnownRange.to),
+        to: Math.max(anchor.lastKnownRange.from, anchor.lastKnownRange.to),
+      };
+  }
+}
+
+function summarizeRevisionExcerpt(
+  plainText: string,
+  from: number,
+  to: number,
+  fallback: string,
+): string {
+  const normalizedFrom = Math.max(0, Math.min(from, plainText.length));
+  const normalizedTo = Math.max(normalizedFrom, Math.min(to, plainText.length));
+  const collapsed = plainText
+    .slice(normalizedFrom, normalizedTo)
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!collapsed) {
+    return fallback;
+  }
+
+  return collapsed.length > 96 ? `${collapsed.slice(0, 93)}...` : collapsed;
+}
+
+function isValidStoryTarget(
+  state: EditorState,
+  target: EditorStoryTarget,
+): boolean {
+  if (target.kind === "main") return true;
+  const subParts = state.document.subParts;
+  if (!subParts) return false;
+
+  switch (target.kind) {
+    case "header":
+      return Boolean(normalizeHeaderFooterTarget(state.document, target));
+    case "footer":
+      return Boolean(normalizeHeaderFooterTarget(state.document, target));
+    case "footnote":
+      return Boolean(subParts.footnoteCollection?.footnotes?.[target.noteId]);
+    case "endnote":
+      return Boolean(subParts.footnoteCollection?.endnotes?.[target.noteId]);
+  }
+}
+
+function derivePageLayoutSnapshot(
+  state: EditorState,
+  activeStory: EditorStoryTarget,
+  storySelections?: ReadonlyMap<string, EditorState["selection"]>,
+): PageLayoutSnapshot | null {
+  const subParts = state.document.subParts;
+  const sections = buildResolvedSections(state.document);
+  if (!subParts && sections.length === 0) {
+    return null;
+  }
+
+  const activeSection = resolveActiveSection(
+    state,
+    activeStory,
+    sections,
+    storySelections,
+  );
+  return buildPageLayoutSnapshot(
+    activeSection?.index ?? 0,
+    activeSection?.properties ?? subParts?.finalSectionProperties,
+    subParts,
+  );
+}
+
+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",
+]);
+
+/** Mutation commands that are not yet supported in suggesting mode. */
+const SUGGESTING_UNSUPPORTED_COMMANDS = new Set<string>([]);
+
+const SUGGESTING_SECONDARY_STORY_UNSUPPORTED_COMMANDS = new Set<string>([
+  "text.insert",
+  "text.delete-backward",
+  "text.delete-forward",
+  "text.insert-tab",
+  "text.insert-hard-break",
+]);
+
+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,
+  };
+}