@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/runtime/document-runtime.ts

@@ -204,6 +204,30 @@ import {
   incrementInvalidationCounter,
   recordPerfSample,
 } from "../ui-tailwind/editor-surface/perf-probe.ts";
+import {
+  createLoadScheduler,
+  type LoadScheduler,
+} from "../io/load-scheduler.ts";
+import {
+  createEditorStateChannel,
+  type EditorStateChannel,
+} from "./editor-state-channel.ts";
+import { PerfCounters } from "./perf-counters.ts";
+import type {
+  EditorStateNamespace,
+  EditorStatePolicy,
+  EditorStateResolver,
+  EditorStatePersister,
+} from "../api/editor-state-types.ts";
+import { collectEditorStateForSerialize } from "./editor-state-integration.ts";
+import type { EditorStatePayload } from "../io/ooxml/workflow-payload.ts";
+
+/** Internal extension of ExportDocxOptions that threads the collected
+ *  editorState payload from the runtime to the docx serializer. */
+interface InternalExportDocxOptions extends ExportDocxOptions {
+  /** @internal Schema 1.2 — collected by runtime before serialize. */
+  _editorState?: EditorStatePayload;
+}
 
 export type Unsubscribe = () => void;
 
@@ -319,6 +343,7 @@ export interface DocumentRuntime {
   getSuggestionsSnapshot(): SuggestionsSnapshot;
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
+  getWorkflowOverlay(): WorkflowOverlay | null;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
@@ -340,6 +365,23 @@ export interface DocumentRuntime {
   getRuntimeContextAnalytics(
     query?: RuntimeContextAnalyticsQuery,
   ): RuntimeContextAnalyticsSnapshot | null;
+  // Schema 1.2 — EditorStateChannel delegation
+  configureEditorStatePolicy(policy: EditorStatePolicy): void;
+  registerEditorStateResolver(resolver: EditorStateResolver | null): void;
+  registerEditorStatePersister(persister: EditorStatePersister | null): void;
+  getEditorStateKey(namespace: EditorStateNamespace): string | undefined;
+  retryPendingPersist(namespace?: EditorStateNamespace): Promise<void>;
+  /** Internal: exposes the channel for load-path hydration in editor-runtime-boundary. */
+  readonly editorStateChannel: EditorStateChannel;
+  /**
+   * L7 render-perf instrumentation. Returns a string→number map of internal
+   * perf counters incremented during runtime activity. Used by perf benches
+   * and tests to assert that a given facet rebuild ran (or did not run) for
+   * a given operation. Counter names are not part of the public API contract
+   * — they may be added or renamed across L7 phases.
+   */
+  getPerfCountersSnapshot(): Record<string, number>;
+  resetPerfCounters(): void;
 }
 
 export interface CommandAppliedMeta {
@@ -385,6 +427,16 @@ export interface CreateDocumentRuntimeOptions {
   ) => void;
   initialViewState?: Partial<ViewState>;
   protectionSnapshot?: ProtectionSnapshot;
+  /**
+   * Optional main-thread time-slicing scheduler. When provided, the runtime
+   * schedules post-`ready` idle work (e.g., sub-part hydration, compatibility
+   * report — reserved for future fastload passes) through it. When omitted,
+   * the runtime falls back to the sync scheduler — behavior is byte-identical
+   * to the pre-fastload runtime.
+   *
+   * See `docs/plans/fastload.md` and `src/io/load-scheduler.ts`.
+   */
+  loadScheduler?: LoadScheduler;
 }
 
 interface HistoryState {
@@ -401,6 +453,29 @@ export function createDocumentRuntime(
   const sessionId = createSessionId(options.documentId, clock());
   const listeners = new Set<() => void>();
   const eventListeners = new Set<(event: DocumentRuntimeEvent) => void>();
+  // Fastload P2: optional time-slicing scheduler. When caller does not pass
+  // one, use the sync backend so the runtime keeps its pre-fastload behavior
+  // end-to-end (no deferred work, idle tasks run inline). Future fastload
+  // passes (P6 async loader) will consume `scheduler.scheduleIdle` for
+  // post-ready work.
+  const loadScheduler: LoadScheduler =
+    options.loadScheduler ?? createLoadScheduler({ backendOverride: "sync" });
+
+  // L7 Phase 0 — perf counters. Each `refreshRenderSnapshot` call increments
+  // `refresh.all`. Phase 1 will add per-facet `facet.<name>.build` counters
+  // wired to the per-facet cached builders. Cost is one Map.set per call.
+  const perfCounters = new PerfCounters();
+
+  // L7 Phase 1 — context-analytics emit coalescing flag. Multiple events that
+  // each trigger context-analytics within one synchronous call stack collapse
+  // to a single microtask-deferred emit. Declared early because emit() (which
+  // checks this flag) runs during construction.
+  let analyticsEmitScheduled = false;
+
+  // Schema 1.2 — editor-state channel (policy, resolver/persister, debounce queues).
+  // Instantiated once per runtime; forwarded to the public interface.
+  const editorStateChannel = createEditorStateChannel();
+
   const history: HistoryState = {
     past: [],
     future: [],
@@ -479,6 +554,7 @@ export function createDocumentRuntime(
         zoomLevel: viewState.zoomLevel,
       },
     }),
+    canonicalDocument: () => state.document,
     renderKernel: () => renderKernelRef,
     getWorkflowRailInput: () => {
       if (!workflowOverlay) return null;
@@ -543,6 +619,21 @@ export function createDocumentRuntime(
         snapshot: SuggestionsSnapshot;
       }
     | undefined;
+  // L7 Phase 1 — review-work snapshot cache. Independent of selection.
+  // Inputs that bust it: workflowMarkup, comments, trackedChanges,
+  // document, navigation references. Per-keystroke profiling on the
+  // 40-page CCEP fixture showed createReviewWorkSnapshot at 211ms/call
+  // with no cache, dominated by per-item createDocumentLocationSnapshot.
+  let cachedReviewWork:
+    | {
+        comments: CommentSidebarSnapshot;
+        trackedChanges: TrackedChangesSnapshot;
+        workflowMarkup: WorkflowMarkupSnapshot;
+        document: CanonicalDocumentEnvelope;
+        navigation: DocumentNavigationSnapshot;
+        snapshot: ReviewWorkSnapshot;
+      }
+    | undefined;
   let cachedPageLayout:
     | {
         revisionToken: string;
@@ -605,7 +696,9 @@ export function createDocumentRuntime(
     {
       revisionToken: string;
       activeStoryKey: string;
-      selection: EditorState["selection"];
+      // L7 Phase 1.6: null for non-selection queries (doc/scope/work_item)
+      // so selection movement doesn't invalidate these scope-stable analytics.
+      selection: EditorState["selection"] | null;
       readOnly: boolean;
       documentMode: DocumentMode;
       workflowOverlay: WorkflowOverlay | null;
@@ -1365,6 +1458,10 @@ export function createDocumentRuntime(
       protectionSnapshot,
       preservation: state.document.preservation,
       workflowMetadataSnapshot: deriveWorkflowMetadataSnapshot(),
+      perfStage: (name, durationMs) => {
+        perfCounters.increment(`wfMarkup.${name}.us`, Math.round(durationMs * 1000));
+        perfCounters.increment(`wfMarkup.${name}.calls`);
+      },
     });
     cachedWorkflowMarkupSnapshot = {
       revisionToken: state.revisionToken,
@@ -1385,11 +1482,21 @@ export function createDocumentRuntime(
     const activeStoryKey = storyTargetKey(activeStory);
     const queryKey = getRuntimeContextAnalyticsQueryKey(query);
     const cachedEntry = cachedContextAnalyticsSnapshots.get(queryKey);
+    // L7 Phase 1.6 — only `scopeKind: "selection"` queries actually read
+    // selection-anchored data (buildSelectionAnalytics filters markup items
+    // that intersect the selection anchor). For document / workflow_scope /
+    // work_item queries the selection is not an input, so changing it
+    // shouldn't invalidate the cache. When selection moves within the same
+    // workflow scope without text editing, document/scope/work_item analytics
+    // hit; cursor-navigation bench drops accordingly.
+    const effectiveScopeKind = query?.scopeKind ?? "selection";
+    const selectionCacheKey =
+      effectiveScopeKind === "selection" ? state.selection : null;
     if (
       cachedEntry &&
       cachedEntry.revisionToken === state.revisionToken &&
       cachedEntry.activeStoryKey === activeStoryKey &&
-      cachedEntry.selection === state.selection &&
+      cachedEntry.selection === selectionCacheKey &&
       cachedEntry.readOnly === state.readOnly &&
       cachedEntry.documentMode === viewState.documentMode &&
       cachedEntry.workflowOverlay === workflowOverlay &&
@@ -1400,28 +1507,76 @@ export function createDocumentRuntime(
       return cachedEntry.snapshot;
     }
 
+    const tWf = performance.now();
+    const wfScope = getCachedWorkflowScopeSnapshot();
+    const wfGuard = getCachedInteractionGuardSnapshot();
+    const wfMarkup = getCachedWorkflowMarkupSnapshot();
+    perfCounters.increment("ctxa.workflow.us", Math.round((performance.now() - tWf) * 1000));
+
+    const tSugg = performance.now();
+    const suggestions = getCachedSuggestionsSnapshot(state);
+    perfCounters.increment("ctxa.suggestions.us", Math.round((performance.now() - tSugg) * 1000));
+
+    const tNav = performance.now();
+    const navigation = getCachedDocumentNavigationSnapshot(state, activeStory);
+    perfCounters.increment("ctxa.navigation.us", Math.round((performance.now() - tNav) * 1000));
+
+    const tReview = performance.now();
+    let reviewWork: ReviewWorkSnapshot;
+    if (
+      cachedReviewWork &&
+      cachedReviewWork.comments === cachedRenderSnapshot.comments &&
+      cachedReviewWork.trackedChanges === cachedRenderSnapshot.trackedChanges &&
+      cachedReviewWork.workflowMarkup === wfMarkup &&
+      cachedReviewWork.document === state.document &&
+      cachedReviewWork.navigation === navigation
+    ) {
+      reviewWork = cachedReviewWork.snapshot;
+      perfCounters.increment("ctxa.reviewWork.cacheHit");
+    } else {
+      reviewWork = createReviewWorkSnapshot({
+        comments: cachedRenderSnapshot.comments,
+        trackedChanges: cachedRenderSnapshot.trackedChanges,
+        workflowMarkup: wfMarkup,
+        document: state.document,
+        navigation,
+      });
+      cachedReviewWork = {
+        comments: cachedRenderSnapshot.comments,
+        trackedChanges: cachedRenderSnapshot.trackedChanges,
+        workflowMarkup: wfMarkup,
+        document: state.document,
+        navigation,
+        snapshot: reviewWork,
+      };
+      perfCounters.increment("ctxa.reviewWork.cacheMiss");
+    }
+    perfCounters.increment("ctxa.reviewWork.us", Math.round((performance.now() - tReview) * 1000));
+
+    const tCompat = performance.now();
+    const compat = toPublicCompatibilityReport(createDerivedCompatibility(state));
+    perfCounters.increment("ctxa.compat.us", Math.round((performance.now() - tCompat) * 1000));
+
+    const tBuild = performance.now();
     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),
-      }),
+      workflowScopeSnapshot: wfScope,
+      interactionGuardSnapshot: wfGuard,
+      workflowMarkupSnapshot: wfMarkup,
+      suggestionsSnapshot: suggestions,
+      reviewWorkSnapshot: reviewWork,
       warnings: state.warnings.map(toPublicWarning),
-      compatibility: toPublicCompatibilityReport(createDerivedCompatibility(state)),
+      compatibility: compat,
     });
+    perfCounters.increment("ctxa.build.us", Math.round((performance.now() - tBuild) * 1000));
     cachedContextAnalyticsSnapshots.set(queryKey, {
       revisionToken: state.revisionToken,
       activeStoryKey,
-      selection: state.selection,
+      // L7 Phase 1.6: store the selectionCacheKey we tested against, so the
+      // same scopeKind invariant applies to future reads.
+      selection: selectionCacheKey,
       readOnly: state.readOnly,
       documentMode: viewState.documentMode,
       workflowOverlay,
@@ -1508,8 +1663,17 @@ export function createDocumentRuntime(
     return true;
   }
 
+  function timeFacet<T>(name: string, fn: () => T): T {
+    const t0 = performance.now();
+    const result = fn();
+    perfCounters.increment(`facet.${name}.us`, Math.round((performance.now() - t0) * 1000));
+    perfCounters.increment(`facet.${name}.calls`);
+    return result;
+  }
+
   function refreshRenderSnapshot(): RuntimeRenderSnapshot {
-    const surface = getCachedSurface(state.document, activeStory);
+    perfCounters.increment("refresh.all");
+    const surface = timeFacet("surface", () => getCachedSurface(state.document, activeStory));
     return {
       documentId: state.documentId,
       sessionId: state.sessionId,
@@ -1521,11 +1685,11 @@ export function createDocumentRuntime(
       documentMode: viewState.documentMode,
       selection: toPublicSelectionSnapshot(state.selection, activeStory),
       activeStory,
-      pageLayout: getCachedPageLayoutSnapshot(state, activeStory) ?? undefined,
+      pageLayout: timeFacet("layout", () => getCachedPageLayoutSnapshot(state, activeStory)) ?? undefined,
       documentStats: toPublicDocumentStats(state),
-      comments: getCachedCommentSidebarSnapshot(state),
-      trackedChanges: getCachedTrackedChangesSnapshot(state, surface),
-      compatibility: getCachedCompatibilityReport(state),
+      comments: timeFacet("comments", () => getCachedCommentSidebarSnapshot(state)),
+      trackedChanges: timeFacet("trackedChanges", () => getCachedTrackedChangesSnapshot(state, surface)),
+      compatibility: timeFacet("compatibility", () => getCachedCompatibilityReport(state)),
       warnings: state.warnings.map((warning) => toPublicWarning(warning)),
       fatalError: state.fatalError ? toPublicError(state.fatalError) : undefined,
       commandState: {
@@ -1603,6 +1767,40 @@ export function createDocumentRuntime(
     });
   }
 
+  // Schema 1.2: forward channel events to the runtime event bus.
+  editorStateChannel.addListener((event) => {
+    switch (event.kind) {
+      case "load_failed":
+        emit({
+          type: "editor_state_part_load_failed",
+          documentId: state.documentId,
+          failure: event.failure,
+        });
+        break;
+      case "persist_failed":
+        emit({
+          type: "editor_state_part_persist_failed",
+          documentId: state.documentId,
+          failure: event.failure,
+        });
+        break;
+      case "policy_migrated":
+        emit({
+          type: "editor_state_policy_migrated",
+          documentId: state.documentId,
+          migration: event.migration,
+        });
+        break;
+      case "unknown_namespace":
+        emit({
+          type: "editor_state_unknown_namespace",
+          documentId: state.documentId,
+          namespace: event.namespace,
+        });
+        break;
+    }
+  });
+
   return {
     subscribe(listener) {
       listeners.add(listener);
@@ -1662,11 +1860,34 @@ export function createDocumentRuntime(
         applyHistory("redo");
         return;
       }
+
+      if (isRuntimeStateOverlayCommand(command)) {
+        applyRuntimeStateOverlayCommand(command);
+        const context = {
+          timestamp: normalizeCommandTimestamp(command.origin?.timestamp) ?? clock(),
+          documentMode: getEffectiveDocumentMode(commandSelection),
+          defaultAuthorId: defaultAuthorId ?? undefined,
+        } as const;
+        const noopTransaction: EditorTransaction = {
+          nextState: state,
+          mapping: createEmptyMapping(),
+          effects: { warningsAdded: [], warningsCleared: [] },
+          historyBoundary: "skip",
+          markDirty: false,
+        };
+        options.onCommandApplied?.(command, noopTransaction, context, {
+          preSelection: state.selection,
+          activeStory,
+        });
+        return;
+      }
+
       try {
         const context = {
           timestamp: normalizeCommandTimestamp(command.origin?.timestamp) ?? clock(),
           documentMode: getEffectiveDocumentMode(commandSelection),
           defaultAuthorId: defaultAuthorId ?? undefined,
+          renderSnapshot: cachedRenderSnapshot,
         } as const;
         const preSelection = commandSelection;
         const preActiveStory = activeStory;
@@ -1685,6 +1906,10 @@ export function createDocumentRuntime(
         if (command.type === "history.undo" || command.type === "history.redo") {
           return;
         }
+        if (isRuntimeStateOverlayCommand(command)) {
+          applyRuntimeStateOverlayCommand(command);
+          return;
+        }
         if (meta?.activeStory && !storyTargetsEqual(meta.activeStory, activeStory)) {
           activeStory = meta.activeStory;
           storySelections.set(
@@ -1695,7 +1920,17 @@ export function createDocumentRuntime(
         const replayState = meta?.preSelection
           ? { ...state, selection: meta.preSelection }
           : state;
-        const transaction = executeEditorCommand(replayState, command, context);
+        const replaySnapshot = meta?.preSelection
+          ? {
+              ...cachedRenderSnapshot,
+              selection: toPublicSelectionSnapshot(meta.preSelection, activeStory),
+            }
+          : cachedRenderSnapshot;
+        const replayContext = {
+          ...context,
+          renderSnapshot: replaySnapshot,
+        };
+        const transaction = executeEditorCommand(replayState, command, replayContext);
         commitRemote(transaction);
       } catch (error) {
         emitError(toRuntimeError(error));
@@ -2156,6 +2391,9 @@ export function createDocumentRuntime(
         state.selection.head,
         activeStory,
         options,
+        // P5 — TOC entries print Word's display number (honors page-
+        // number restarts), not the raw 0-based pageIndex+1.
+        (pageIndex: number) => layoutFacet.getDisplayPageNumber(pageIndex),
       );
       if (refreshed.changed) {
         this.dispatch({
@@ -2213,7 +2451,37 @@ export function createDocumentRuntime(
         throw toStructuredRuntimeException(error);
       }
 
-      const result = await options.exportDocx(this.getSessionState(), exportOptions);
+      // Schema 1.2: collect editor-state payload (flushes pending persists).
+      const collectedEditorState = await collectEditorStateForSerialize({
+        channel: editorStateChannel,
+        getNamespaceData: (ns) => {
+          switch (ns) {
+            case "hostAnnotations": {
+              const snap = deriveHostAnnotationSnapshot();
+              if (!snap || snap.annotations.length === 0) return null;
+              return { schemaVersion: "host-annotation-overlay/1", data: snap };
+            }
+            case "workflowOverlay": {
+              const ov = workflowOverlay;
+              if (!ov) return null;
+              return { schemaVersion: "workflow-overlay/1", data: ov };
+            }
+            case "workflowMetadata": {
+              const meta = deriveWorkflowMetadataSnapshot();
+              if (!meta || (meta.definitions.length === 0 && meta.entries.length === 0)) return null;
+              return { schemaVersion: "workflow-metadata/1", data: meta };
+            }
+            case "workItems":
+              return null;
+          }
+        },
+      });
+      const internalOptions: InternalExportDocxOptions = {
+        ...exportOptions,
+        _editorState: collectedEditorState,
+      };
+
+      const result = await options.exportDocx(this.getSessionState(), internalOptions);
 
       emit({
         type: "export_completed",
@@ -2224,47 +2492,25 @@ export function createDocumentRuntime(
       return result;
     },
     setWorkflowOverlay(overlay) {
-      workflowOverlay = structuredClone(overlay);
-      cachedRenderSnapshot = refreshRenderSnapshot();
-      const snapshot = deriveWorkflowScopeSnapshot()!;
-      emit({
-        type: "workflow_overlay_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.set-overlay",
+        overlay,
+        origin: createOrigin("api", clock()),
+      });
+      editorStateChannel.recordMutation("workflowOverlay", {
+        namespace: "workflowOverlay",
+        schemaVersion: "workflow-overlay/1",
+        data: overlay,
       });
-      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: [],
-        },
+      this.dispatch({
+        type: "workflow.clear-overlay",
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
+    },
+    getWorkflowOverlay() {
+      return workflowOverlay;
     },
     getWorkflowScopeSnapshot() {
       return getCachedWorkflowScopeSnapshot();
@@ -2276,77 +2522,56 @@ export function createDocumentRuntime(
       return getCachedWorkflowMarkupSnapshot();
     },
     setWorkflowMetadataDefinitions(definitions) {
-      workflowMetadataDefinitions = structuredClone(definitions);
-      const snapshot = deriveWorkflowMetadataSnapshot();
-      emit({
-        type: "workflow_metadata_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.set-metadata-definitions",
+        definitions,
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     clearWorkflowMetadataDefinitions() {
-      workflowMetadataDefinitions = [];
-      const snapshot = deriveWorkflowMetadataSnapshot();
-      emit({
-        type: "workflow_metadata_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.clear-metadata-definitions",
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     setWorkflowMetadataEntries(entries) {
-      workflowMetadataEntries = structuredClone(entries);
-      const snapshot = deriveWorkflowMetadataSnapshot();
-      emit({
-        type: "workflow_metadata_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.set-metadata-entries",
+        entries,
+        origin: createOrigin("api", clock()),
+      });
+      editorStateChannel.recordMutation("workflowMetadata", {
+        namespace: "workflowMetadata",
+        schemaVersion: "workflow-metadata/1",
+        data: entries,
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     clearWorkflowMetadataEntries() {
-      workflowMetadataEntries = [];
-      const snapshot = deriveWorkflowMetadataSnapshot();
-      emit({
-        type: "workflow_metadata_changed",
-        documentId: state.documentId,
-        snapshot,
+      this.dispatch({
+        type: "workflow.clear-metadata-entries",
+        origin: createOrigin("api", clock()),
       });
-      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(),
+      this.dispatch({
+        type: "host-annotation.set-overlay",
+        overlay,
+        origin: createOrigin("api", clock()),
+      });
+      editorStateChannel.recordMutation("hostAnnotations", {
+        namespace: "hostAnnotations",
+        schemaVersion: "host-annotation-overlay/1",
+        data: overlay,
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     clearHostAnnotationOverlay() {
-      hostAnnotationOverlay = null;
-      emit({
-        type: "host_annotation_overlay_changed",
-        documentId: state.documentId,
-        snapshot: deriveHostAnnotationSnapshot(),
+      this.dispatch({
+        type: "host-annotation.clear-overlay",
+        origin: createOrigin("api", clock()),
       });
-      for (const listener of listeners) {
-        listener();
-      }
     },
     getHostAnnotationSnapshot() {
       return deriveHostAnnotationSnapshot();
@@ -2408,6 +2633,31 @@ export function createDocumentRuntime(
     getRuntimeContextAnalytics(query) {
       return getCachedRuntimeContextAnalytics(query);
     },
+    // Schema 1.2 — EditorStateChannel delegation
+    configureEditorStatePolicy(policy) {
+      editorStateChannel.setPolicy(policy);
+    },
+    registerEditorStateResolver(resolver) {
+      editorStateChannel.setResolver(resolver);
+    },
+    registerEditorStatePersister(persister) {
+      editorStateChannel.setPersister(persister);
+    },
+    getEditorStateKey(namespace) {
+      return editorStateChannel.getKey(namespace);
+    },
+    async retryPendingPersist(namespace) {
+      await editorStateChannel.retry(namespace);
+    },
+    get editorStateChannel() {
+      return editorStateChannel;
+    },
+    getPerfCountersSnapshot() {
+      return perfCounters.snapshot();
+    },
+    resetPerfCounters() {
+      perfCounters.reset();
+    },
   };
 
   function applyHistory(direction: "undo" | "redo"): void {
@@ -2455,15 +2705,14 @@ export function createDocumentRuntime(
   function applyTransactionToState(transaction: EditorTransaction): void {
     const previous = state;
 
+    const tApply0 = performance.now();
     protectionSnapshot = remapProtectionSnapshot(protectionSnapshot, transaction.mapping);
+    const tFinalize0 = performance.now();
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
+    perfCounters.increment("commit.finalizeState.us", Math.round((performance.now() - tFinalize0) * 1000));
     storySelections.set(storyTargetKey(activeStory), state.selection);
 
-    // Signal a bounded content-edit invalidation to the layout engine so the
-    // next layout query can splice rather than rebuild the full graph.  The
-    // engine analyzes the reason against its cached graph and falls back to
-    // a full rebuild when the edit crosses section boundaries or reaches a
-    // page the engine cannot safely resume from.
+    const tInvalidate0 = performance.now();
     if (transaction.markDirty && transaction.mapping.steps.length > 0) {
       let minFrom = Infinity;
       let maxTo = -Infinity;
@@ -2476,17 +2725,20 @@ export function createDocumentRuntime(
         layoutEngine.invalidate({ kind: "content-edit", from: minFrom, to: maxTo });
       }
     }
-
-    // Font-loader refresh on subParts identity change — this is the
-    // lightweight proxy for "a change that could affect which fonts the
-    // canvas backend measures against".  Typing edits don't rebuild
-    // subParts; style + font + numbering imports do.
     if (previous.document.subParts !== state.document.subParts) {
       fontLoader.refresh(collectFontLoaderInput(state.document));
+      layoutEngine.invalidateMeasurementCache();
     }
+    perfCounters.increment("commit.invalidate.us", Math.round((performance.now() - tInvalidate0) * 1000));
 
+    const tRefresh0 = performance.now();
     cachedRenderSnapshot = refreshRenderSnapshot();
+    perfCounters.increment("commit.refresh.us", Math.round((performance.now() - tRefresh0) * 1000));
+
+    const tNotify0 = performance.now();
     notify(previous, state, transaction);
+    perfCounters.increment("commit.notify.us", Math.round((performance.now() - tNotify0) * 1000));
+    perfCounters.increment("commit.total.us", Math.round((performance.now() - tApply0) * 1000));
   }
 
   function notify(
@@ -2715,6 +2967,7 @@ export function createDocumentRuntime(
       timestamp,
       documentMode: getEffectiveDocumentMode(selection),
       defaultAuthorId: defaultAuthorId ?? undefined,
+      renderSnapshot: cachedRenderSnapshot,
     } as const;
     const baseState = selection === state.selection
       ? state
@@ -2946,10 +3199,142 @@ export function createDocumentRuntime(
     return nextReview;
   }
 
+  // L7 Phase 1 — context-analytics emissions are coalesced per microtask.
+  // A single keystroke commit fires multiple events that each independently
+  // trigger `emitContextAnalyticsChanged` (selection_changed, change_authored,
+  // …). Each emission re-walks every workflow markup item (~211 ms on a
+  // 40-page CCEP fixture) so unbatched, an N-event commit costs N × 211 ms.
+  // Coalescing collapses the burst to a single emit at the tail of the
+  // synchronous call stack — one per commit. (Flag declared above near
+  // perfCounters so it is initialized before construction-time emits run.)
+  function scheduleContextAnalyticsEmit(): void {
+    if (analyticsEmitScheduled) {
+      perfCounters.increment("emit.contextAnalytics.coalesced");
+      return;
+    }
+    analyticsEmitScheduled = true;
+    queueMicrotask(() => {
+      // Reset BEFORE the emit so any synchronous re-entrant emits triggered
+      // by listener callbacks schedule a fresh second microtask (no lost
+      // updates). Reversing this order would drop bursts originating in
+      // listeners.
+      analyticsEmitScheduled = false;
+      const t = performance.now();
+      emitContextAnalyticsChanged();
+      perfCounters.increment("emit.contextAnalytics.us", Math.round((performance.now() - t) * 1000));
+    });
+  }
+
   function emit(event: DocumentRuntimeEvent): void {
+    perfCounters.increment(`emit.${event.type}.calls`);
+    const t0 = performance.now();
     emitInternal(event);
+    perfCounters.increment(`emit.${event.type}.internal.us`, Math.round((performance.now() - t0) * 1000));
     if (shouldEmitContextAnalyticsChanged(event)) {
-      emitContextAnalyticsChanged();
+      scheduleContextAnalyticsEmit();
+    }
+  }
+
+  function applyRuntimeStateOverlayCommand(
+    command: RuntimeStateOverlayCommand,
+  ): void {
+    switch (command.type) {
+      case "workflow.set-overlay": {
+        workflowOverlay = structuredClone(command.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,
+          });
+        }
+        break;
+      }
+      case "workflow.clear-overlay": {
+        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: [],
+          },
+        });
+        break;
+      }
+      case "workflow.set-metadata-definitions": {
+        workflowMetadataDefinitions = structuredClone(command.definitions);
+        emit({
+          type: "workflow_metadata_changed",
+          documentId: state.documentId,
+          snapshot: deriveWorkflowMetadataSnapshot(),
+        });
+        break;
+      }
+      case "workflow.clear-metadata-definitions": {
+        workflowMetadataDefinitions = [];
+        emit({
+          type: "workflow_metadata_changed",
+          documentId: state.documentId,
+          snapshot: deriveWorkflowMetadataSnapshot(),
+        });
+        break;
+      }
+      case "workflow.set-metadata-entries": {
+        workflowMetadataEntries = structuredClone(command.entries);
+        emit({
+          type: "workflow_metadata_changed",
+          documentId: state.documentId,
+          snapshot: deriveWorkflowMetadataSnapshot(),
+        });
+        break;
+      }
+      case "workflow.clear-metadata-entries": {
+        workflowMetadataEntries = [];
+        emit({
+          type: "workflow_metadata_changed",
+          documentId: state.documentId,
+          snapshot: deriveWorkflowMetadataSnapshot(),
+        });
+        break;
+      }
+      case "host-annotation.set-overlay": {
+        hostAnnotationOverlay = structuredClone(command.overlay);
+        emit({
+          type: "host_annotation_overlay_changed",
+          documentId: state.documentId,
+          snapshot: deriveHostAnnotationSnapshot(),
+        });
+        break;
+      }
+      case "host-annotation.clear-overlay": {
+        hostAnnotationOverlay = null;
+        emit({
+          type: "host_annotation_overlay_changed",
+          documentId: state.documentId,
+          snapshot: deriveHostAnnotationSnapshot(),
+        });
+        break;
+      }
+    }
+    for (const listener of listeners) {
+      listener();
     }
   }
 
@@ -2993,7 +3378,23 @@ export function createDocumentRuntime(
   }
 
   function emitContextAnalyticsChanged(): void {
+    // L7 Phase 1 — short-circuit when no consumer can observe the event.
+    // The downstream cost is dominated by createRuntimeContextAnalyticsSnapshot,
+    // which assembles ~8 facets (suggestions, navigation, review-work,
+    // workflow-markup, etc.) and runs > 300 ms on a 40-page CCEP fixture
+    // because its cache key includes `selection` and selection moves on
+    // every keystroke. Skipping here when nobody is subscribed eliminates
+    // the cost in headless/SSR/test usage. Production keeps its `onEvent`
+    // handler, so the production typing-latency win lives in Phase 1.5
+    // (microtask coalescing) and Phase 1.6 (per-input-axis caching of the
+    // analytics inputs).
+    if (options.onEvent === undefined && eventListeners.size === 0) {
+      perfCounters.increment("emit.contextAnalytics.skippedNoListeners");
+      return;
+    }
+    const t0 = performance.now();
     const trackedSnapshots = collectTrackedContextAnalyticsSnapshots();
+    perfCounters.increment("emit.contextAnalytics.collect.us", Math.round((performance.now() - t0) * 1000));
     if (
       lastEmittedContextAnalyticsSnapshots !== undefined &&
       trackedContextAnalyticsSnapshotsEqual(lastEmittedContextAnalyticsSnapshots, trackedSnapshots)
@@ -3111,6 +3512,39 @@ function normalizeCommandTimestamp(value: unknown): string | undefined {
   return undefined;
 }
 
+type RuntimeStateOverlayCommand = Extract<
+  EditorCommand,
+  {
+    type:
+      | "workflow.set-overlay"
+      | "workflow.clear-overlay"
+      | "workflow.set-metadata-definitions"
+      | "workflow.clear-metadata-definitions"
+      | "workflow.set-metadata-entries"
+      | "workflow.clear-metadata-entries"
+      | "host-annotation.set-overlay"
+      | "host-annotation.clear-overlay";
+  }
+>;
+
+function isRuntimeStateOverlayCommand(
+  command: EditorCommand,
+): command is RuntimeStateOverlayCommand {
+  switch (command.type) {
+    case "workflow.set-overlay":
+    case "workflow.clear-overlay":
+    case "workflow.set-metadata-definitions":
+    case "workflow.clear-metadata-definitions":
+    case "workflow.set-metadata-entries":
+    case "workflow.clear-metadata-entries":
+    case "host-annotation.set-overlay":
+    case "host-annotation.clear-overlay":
+      return true;
+    default:
+      return false;
+  }
+}
+
 function finalizeState(
   state: EditorState,
   markDirty: boolean,
@@ -3684,6 +4118,14 @@ const NON_MUTATION_COMMANDS = new Set([
   "warning.add",
   "warning.clear",
   "comment.open",
+  "workflow.set-overlay",
+  "workflow.clear-overlay",
+  "workflow.set-metadata-definitions",
+  "workflow.clear-metadata-definitions",
+  "workflow.set-metadata-entries",
+  "workflow.clear-metadata-entries",
+  "host-annotation.set-overlay",
+  "host-annotation.clear-overlay",
 ]);
 
 /** Mutation commands that are not yet supported in suggesting mode. */
@@ -4008,6 +4450,7 @@ function refreshDocumentTableOfContents(
   selectionHead: number,
   activeStory: EditorStoryTarget,
   options?: TocRefreshOptions,
+  resolveDisplayPageNumber?: (pageIndex: number) => number | null,
 ): {
   document: CanonicalDocumentEnvelope;
   result: TocRefreshResult;
@@ -4038,7 +4481,7 @@ function refreshDocumentTableOfContents(
     }
     const nextField: FieldNode = {
       ...field,
-      children: buildTocInlineNodes(entries),
+      children: buildTocInlineNodes(entries, resolveDisplayPageNumber),
       refreshStatus: "current",
     };
     if (flattenInlineDisplayText(nextField.children) !== flattenInlineDisplayText(field.children)) {
@@ -4221,14 +4664,26 @@ function buildInlineNodesFromDisplayText(text: string): InlineNode[] {
   return children;
 }
 
+/**
+ * P5 — TOC entry rendering with display-number resolution.  When
+ * `resolveDisplayPageNumber` is supplied, TOC entries print the number
+ * Word would print on the page (honors `w:pgNumType/@w:start` restarts
+ * for front-matter roman numerals → body arabic restart).  Without the
+ * resolver, falls back to the raw `pageIndex + 1` (pre-P5 behavior).
+ */
 function buildTocInlineNodes(
   entries: ReadonlyArray<{ level: number; text: string; pageIndex: number }>,
+  resolveDisplayPageNumber?: (pageIndex: number) => number | null,
 ): 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) });
+    const displayed = resolveDisplayPageNumber?.(entry.pageIndex);
+    children.push({
+      type: "text",
+      text: String(displayed ?? entry.pageIndex + 1),
+    });
     if (index < entries.length - 1) {
       children.push({ type: "hard_break" });
     }
@@ -4236,6 +4691,14 @@ function buildTocInlineNodes(
   return children;
 }
 
+/** Test-only export of `buildTocInlineNodes` (P5 unit tests). */
+export function __buildTocInlineNodes(
+  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number }>,
+  resolveDisplayPageNumber?: (pageIndex: number) => number | null,
+): InlineNode[] {
+  return buildTocInlineNodes(entries, resolveDisplayPageNumber);
+}
+
 function collectFieldsFromSubParts(
   subParts: SubPartsCatalog | undefined,
   entries: FieldEntrySnapshot[],
@@ -4284,6 +4747,25 @@ function resolveSupportedFieldDisplay(
   if (field.fieldFamily === "TOC") {
     return undefined;
   }
+  if (field.fieldFamily === "PAGE") {
+    const page = resolveRepresentativePageForStory(navigation, storyTarget);
+    if (!page) {
+      return { displayText: "", refreshStatus: "unresolvable" };
+    }
+    return {
+      displayText: String(resolveDisplayedPageNumber(page)),
+      refreshStatus: "current",
+    };
+  }
+  if (field.fieldFamily === "NUMPAGES") {
+    if (navigation.pageCount === 0) {
+      return { displayText: "", refreshStatus: "unresolvable" };
+    }
+    return {
+      displayText: String(navigation.pageCount),
+      refreshStatus: "current",
+    };
+  }
   if (!field.fieldTarget) {
     return { displayText: "", refreshStatus: "unresolvable" };
   }
@@ -4575,8 +5057,38 @@ function remapProtectionSnapshot(
  * let the loader register system fonts it finds via
  * `document.fonts.check(...)`.
  */
+// P14.d — memoize the font-family walk by `(content, styles)` reference
+// identity.  Both shapes change identity only on a real edit / import /
+// style mutation; per-keystroke edits keep the same references because
+// `finalizeState` shallow-spreads `state.document`.  WeakMap two-level
+// cache so the entries free with the documents that own them.
+const fontLoaderInputCache = new WeakMap<
+  object,
+  WeakMap<object, { families: readonly string[] }>
+>();
+
 function collectFontLoaderInput(
   document: CanonicalDocumentEnvelope,
+): { families: readonly string[] } {
+  const contentKey = document.content as unknown as object;
+  const stylesKey = (document.styles ?? FONT_LOADER_EMPTY_STYLES_KEY) as unknown as object;
+  let stylesCache = fontLoaderInputCache.get(contentKey);
+  if (stylesCache) {
+    const cached = stylesCache.get(stylesKey);
+    if (cached) return cached;
+  } else {
+    stylesCache = new WeakMap();
+    fontLoaderInputCache.set(contentKey, stylesCache);
+  }
+  const result = collectFontLoaderInputUncached(document);
+  stylesCache.set(stylesKey, result);
+  return result;
+}
+
+const FONT_LOADER_EMPTY_STYLES_KEY = Object.freeze({});
+
+function collectFontLoaderInputUncached(
+  document: CanonicalDocumentEnvelope,
 ): { families: readonly string[] } {
   try {
     const families = new Set<string>();
@@ -4604,6 +5116,9 @@ function collectFontLoaderInput(
   }
 }
 
+/** Test-only export of the uncached walk so memoization tests can spy on it. */
+export const __collectFontLoaderInputUncached = collectFontLoaderInputUncached;
+
 /**
  * Asynchronously upgrade the engine's measurement backend to canvas once
  * the platform supports it and fonts have resolved.  Errors are swallowed