@beyondwork/docx-react-component 1.0.42 → 1.0.45

package/src/runtime/document-runtime.ts

@@ -14,6 +14,8 @@ import {
 } from "../core/state/editor-state.ts";
 import type {
   AddCommentParams,
+  AddCommentReplyResult,
+  AddCommentResult,
   CommentSidebarSnapshot,
   CommentSidebarThreadSnapshot,
   CompatibilityReport,
@@ -113,6 +115,7 @@ import {
   type RevisionStore,
 } from "../review/store/revision-store.ts";
 import { createSuggestionsSnapshot } from "./suggestions-snapshot.ts";
+import { validateSelectionAgainstDocument } from "./selection/post-edit-validator.ts";
 import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
 import { mergeCompatibilityReports } from "../validation/compatibility-report.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
@@ -204,6 +207,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;
 
@@ -220,6 +247,7 @@ export type ActiveStoryTextCommand =
   | Extract<EditorCommand, { type: "text.delete-backward" }>
   | Extract<EditorCommand, { type: "text.delete-forward" }>
   | Extract<EditorCommand, { type: "text.insert-tab" }>
+  | Extract<EditorCommand, { type: "text.outdent-tab" }>
   | Extract<EditorCommand, { type: "text.insert-hard-break" }>
   | Extract<EditorCommand, { type: "paragraph.split" }>;
 
@@ -257,11 +285,11 @@ export interface DocumentRuntime {
   blur(): void;
   setDefaultAuthorId?(authorId?: string): void;
   getDefaultAuthorId?(): string | undefined;
-  addComment(params: AddCommentParams): string;
+  addComment(params: AddCommentParams): AddCommentResult;
   openComment(commentId: string): void;
   resolveComment(commentId: string): void;
   reopenComment(commentId: string): void;
-  addCommentReply(commentId: string, body: string, authorId?: string): void;
+  addCommentReply(commentId: string, body: string, authorId?: string): AddCommentReplyResult;
   editCommentBody(commentId: string, body: string): void;
   acceptChange(changeId: string): void;
   rejectChange(changeId: string): void;
@@ -341,6 +369,38 @@ 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;
+  /**
+   * Notifies the runtime that the UI's visible block range changed.
+   * The next `refreshRenderSnapshot()` (triggered by any mutation) uses this
+   * range to cull off-screen blocks in the surface projection. Calling this
+   * method alone does NOT trigger a snapshot rebuild — a subsequent mutation
+   * or an explicit `requestViewportRefresh()` is required.
+   *
+   * Safe to call at any frequency; identical ranges are a no-op.
+   */
+  setVisibleBlockRange(range: { start: number; end: number }): void;
+  /**
+   * Triggers a surface-only refresh that applies the latest visible block range
+   * without running the full commit pipeline. Used by scroll handlers.
+   */
+  requestViewportRefresh(): void;
 }
 
 export interface CommandAppliedMeta {
@@ -386,6 +446,27 @@ 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;
+  /**
+   * L7 Phase 2.5 — prerender cache seed. When set, the internal
+   * LayoutEngineInstance is seeded with this graph so the first
+   * `getPageGraph()` call returns it directly, skipping `fullRebuild`.
+   * The seeded graph must have been produced with the current
+   * `LAYOUT_ENGINE_VERSION` (callers rely on the cache-key scheme in
+   * `src/runtime/prerender/cache-key.ts` to guarantee this).
+   *
+   * See docs/plans/lane-2-render-performance.md §Phase 2.5 §3.7.
+   */
+  seedLayoutCache?: import("./layout/page-graph.ts").RuntimePageGraph;
 }
 
 interface HistoryState {
@@ -393,6 +474,84 @@ interface HistoryState {
   future: EditorState[];
 }
 
+/**
+ * L7 Phase 1.7.4 — structural-counts hash for the reviewWork cache key.
+ *
+ * `getCachedWorkflowMarkupSnapshot()` returns a NEW object on every
+ * `revisionToken` bump, so the previous reference-equality check
+ * (`cachedReviewWork.workflowMarkup === wfMarkup`) always failed on pure
+ * text edits — forcing `createReviewWorkSnapshot` to re-walk every comment,
+ * revision, protected range, and opaque fragment on every keystroke
+ * (94 % of typing latency on large-tables, 97 % on extra-large).
+ *
+ * The hash is a colon-joined string of per-category item counts. Pure text
+ * edits within unchanged blocks do not change any count, so the hash
+ * compares equal and the cached snapshot is reused. Structural changes
+ * (comment added, revision authored, block inserted/deleted) alter at
+ * least one count, so the hash diverges and the cache misses correctly.
+ *
+ * Correctness: the cached `items` include absolute-position `anchor`s that
+ * get stale under a text edit. That is safe here because this cache lives
+ * ONLY inside `getCachedRuntimeContextAnalytics`, whose consumers
+ * (`buildDocumentAnalytics`, `buildSelectionAnalytics`, etc.) read only the
+ * numeric `openCommentCount` and `actionableRevisionCount` fields — the
+ * stale `items[].anchor` never reaches a consumer. The direct
+ * `runtime.getReviewWorkSnapshot()` API does not use this cache.
+ */
+function computeWorkflowMarkupStructuralHash(
+  wfMarkup: WorkflowMarkupSnapshot,
+): string {
+  return [
+    wfMarkup.totalCount,
+    wfMarkup.highlights.length,
+    wfMarkup.metadata.length,
+    wfMarkup.comments.length,
+    wfMarkup.revisions.length,
+    wfMarkup.fields.length,
+    wfMarkup.protectedRanges.length,
+    wfMarkup.opaqueFragments.length,
+  ].join(":");
+}
+
+/**
+ * L7 Phase 1.7.4 — review-status hash for the reviewWork cache key.
+ *
+ * `state.document.review.comments` and `.revisions` are rebuilt with new
+ * object identities on every text command (via `remapReviewStateAfterContent
+ * Change` → `remapCommentThreads` → `Object.fromEntries`), so a reference
+ * check on those records always fails on pure text edits. But the
+ * `reviewWork` snapshot's observable output depends only on:
+ *   - which comments are OPEN (`openCommentCount = openCommentIds.length`)
+ *   - which revisions are ACTIONABLE
+ *     (`actionableRevisionCount = actionableChangeIds.length`)
+ * plus the per-category item counts already captured by
+ * `computeWorkflowMarkupStructuralHash`.
+ *
+ * `comments` / `revisions` keys and statuses are stable across text edits
+ * (remap only rewrites anchors and wraps in `{...thread, anchor}` — status
+ * is carried through). Hashing "id+status" for each record is O(N) over
+ * the small review set and captures the semantic identity we need.
+ *
+ * We intentionally do NOT include anchor positions in the hash: anchor
+ * shifts are exactly the staleness the cache is allowed to tolerate (see
+ * `cachedReviewWork` correctness note above).
+ */
+function computeReviewStateHash(
+  review: CanonicalDocumentEnvelope["review"],
+): string {
+  const commentParts: string[] = [];
+  for (const commentId of Object.keys(review.comments).sort()) {
+    const thread = review.comments[commentId];
+    commentParts.push(`${commentId}=${thread?.status ?? ""}`);
+  }
+  const revisionParts: string[] = [];
+  for (const revisionId of Object.keys(review.revisions).sort()) {
+    const revision = review.revisions[revisionId];
+    revisionParts.push(`${revisionId}=${revision?.status ?? ""}`);
+  }
+  return `${commentParts.join(",")}|${revisionParts.join(",")}`;
+}
+
 export function createDocumentRuntime(
   options: CreateDocumentRuntimeOptions,
 ): DocumentRuntime {
@@ -402,6 +561,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: [],
@@ -463,6 +645,16 @@ export function createDocumentRuntime(
   // upgrades to the canvas backend once fonts resolve.  `swapMeasurementProvider`
   // emits `measurement_backend_ready` so chrome consumers can re-read metrics.
   const layoutEngine: LayoutEngineInstance = createLayoutEngine();
+  if (options.seedLayoutCache) {
+    // L7 Phase 2.5 — seed the cached graph from the prerender envelope so
+    // the first getPageGraph call skips fullRebuild. Seed is keyed on the
+    // runtime's current document identity so `keyEqual` passes without
+    // triggering a rebuild. The cache-key scheme in
+    // src/runtime/prerender/cache-key.ts guarantees the seed is produced
+    // by the same LAYOUT_ENGINE_VERSION.
+    layoutEngine.seedCachedGraph(options.seedLayoutCache, state.document);
+    perfCounters.increment("loadSession.layoutCache.seeded");
+  }
   const fontLoader: DocxFontLoader = createDocxFontLoader(
     collectFontLoaderInput(state.document),
   );
@@ -480,6 +672,7 @@ export function createDocumentRuntime(
         zoomLevel: viewState.zoomLevel,
       },
     }),
+    canonicalDocument: () => state.document,
     renderKernel: () => renderKernelRef,
     getWorkflowRailInput: () => {
       if (!workflowOverlay) return null;
@@ -504,11 +697,40 @@ export function createDocumentRuntime(
     // runtime already builds for comment/revision/search consumers.
     getWorkflowMarkupMetadata: () =>
       getCachedWorkflowMarkupSnapshot().metadata,
+    // L7 Phase 2 — delegate viewport culling through the facet so the
+    // workspace (which only holds a `layoutFacet` ref) can drive culling
+    // without a separate `DocumentRuntime` prop.  The lambdas forward to
+    // the runtime's own `setVisibleBlockRange` / `requestViewportRefresh`
+    // implementations which are defined below.  Capturing by closure works
+    // because the lambdas are only invoked after the full runtime object is
+    // built and the methods below have been assigned.
+    // TODO(L7 Phase 2 post-merge): this lambda duplicates the setVisibleBlockRange
+    // logic implemented on `runtime` at line ~2874. Consolidate after Phase 2 ships
+    // so the facet forwards to the runtime method. Forward-reference pattern matches
+    // `renderKernelRef` — see that example. See spec-review notes on commit 0b03bfa7.
+    setVisibleBlockRange: (range) => {
+      if (
+        viewportBlockRange &&
+        viewportBlockRange.start === range.start &&
+        viewportBlockRange.end === range.end
+      ) {
+        return;
+      }
+      viewportBlockRange = { start: range.start, end: range.end };
+      perfCounters.increment("runtime.viewport.updates");
+    },
+    requestViewportRefresh: () => {
+      perfCounters.increment("runtime.viewport.refreshes");
+      refreshSurfaceOnly();
+    },
   });
   renderKernelRef = createRenderKernel({
     facet: layoutFacet,
     getActiveStory: () => activeStory,
   });
+  // L7 Phase 2 — viewport block range for surface culling.
+  let viewportBlockRange: { start: number; end: number } | null = null;
+
   let cachedSurface:
     | {
         revisionToken: string;
@@ -544,6 +766,66 @@ export function createDocumentRuntime(
         snapshot: SuggestionsSnapshot;
       }
     | undefined;
+  // L7 Phase 1 — review-work snapshot cache. Independent of selection.
+  //
+  // What we cache. `createReviewWorkSnapshot`'s observable output is:
+  //   - `openCommentCount` = `comments.openCommentIds.length`
+  //   - `actionableRevisionCount` = `trackedChanges.actionableChangeIds.length`
+  //   - `items[]` (each with stale-tolerable `anchor`/`sectionIndex`/
+  //     `pageIndex` — see "Correctness" below)
+  //
+  // Cache-busting inputs (L7 Phase 1.7.4 — two complementary hashes):
+  //   - `workflowMarkupHash` — structural-counts hash over wfMarkup.
+  //     Replaces the old `workflowMarkup === wfMarkup` reference check,
+  //     which always failed on pure text edits because
+  //     `getCachedWorkflowMarkupSnapshot()` is keyed on revisionToken.
+  //     Pure text edits keep all per-category item counts stable → hash
+  //     equal. A comment ADDITION, revision AUTHORED, protected-range added,
+  //     opaque-fragment added → at least one count changes → hash diverges.
+  //   - `reviewStateHash` — "id+status" hash over `state.document.review`.
+  //     Captures the open/resolved/detached distribution that item COUNTS
+  //     alone can't see (a comment RESOLVED leaves the count stable but
+  //     shifts openCommentCount). Stable across text edits because
+  //     `remapCommentThreads` preserves status on every record.
+  //
+  // Note we intentionally DO NOT key on `cachedRenderSnapshot.comments` or
+  // `.trackedChanges` (the snapshot references) because those projections
+  // are rebuilt on every revisionToken bump — their text previews depend on
+  // live document text. And we DO NOT key on `state.document.review.comments`
+  // or `.revisions` directly: every text command rebuilds those records via
+  // `remapReviewStateAfterContentChange`, producing new object identities
+  // even when no anchor or status changed. The two hashes above capture the
+  // semantic identity that actually matters for ReviewWorkSnapshot output
+  // without churning on each keystroke.
+  //
+  // We also DO NOT store a `document` or `navigation` reference: both churn
+  // on every revisionToken bump, so those checks forced a 100 % miss rate
+  // on text edits with no compensating correctness gain.
+  //
+  // Correctness. Any change that affects the cached snapshot's observable
+  // output (`openCommentCount`, `actionableRevisionCount`, or the set of
+  // workflow items) shifts at least one of (workflowMarkupHash,
+  // reviewStateHash). The per-item `anchor` positions stored on stale cached
+  // items can be out of date, but this cache is consumed only inside
+  // `getCachedRuntimeContextAnalytics` where downstream
+  // `buildDocumentAnalytics` / `buildSelectionAnalytics` /
+  // `buildWorkflowScopeAnalytics` / `buildWorkItemAnalytics` read ONLY
+  // `reviewWorkSnapshot.openCommentCount` and `.actionableRevisionCount`
+  // (numbers). The stale `items[].anchor` never reaches a consumer. The
+  // public `runtime.getReviewWorkSnapshot()` API calls
+  // `createReviewWorkSnapshot` fresh and does not use this cache.
+  //
+  // Per-keystroke profiling on CCEP fixtures showed createReviewWorkSnapshot
+  // at 188 ms/call on large-tables (40 pp) and ~5 s/call on extra-large
+  // (100 pp) — dominated by per-item createDocumentLocationSnapshot. Phase
+  // 1.7.4 takes the 20/20 miss rate on pure text edits to ≤2/20.
+  let cachedReviewWork:
+    | {
+        workflowMarkupHash: string;
+        reviewStateHash: string;
+        snapshot: ReviewWorkSnapshot;
+      }
+    | undefined;
   let cachedPageLayout:
     | {
         revisionToken: string;
@@ -606,7 +888,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;
@@ -633,7 +917,7 @@ export function createDocumentRuntime(
       return cachedSurface.snapshot;
     }
 
-    const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory);
+    const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory, { viewportBlockRange });
     recordPerfSample("snapshot.surface");
     incrementInvalidationCounter("runtime.snapshot.surfaceMisses");
     cachedSurface = {
@@ -1366,6 +1650,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,
@@ -1386,11 +1674,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 &&
@@ -1401,28 +1699,85 @@ 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;
+    // L7 Phase 1.7.4 — two structural hashes replace the old reference
+    // checks. `workflowMarkupHash` captures per-category wfMarkup item
+    // counts (see computeWorkflowMarkupStructuralHash); `reviewStateHash`
+    // captures id+status over state.document.review (see
+    // computeReviewStateHash). Together they bust on any mutation that can
+    // change ReviewWorkSnapshot's observable output
+    // (openCommentCount, actionableRevisionCount, or the item set), while
+    // staying stable under pure text edits so the expensive
+    // createReviewWorkSnapshot walk is skipped. The prior `comments` /
+    // `trackedChanges` / `workflowMarkup` / `document` / `navigation`
+    // reference checks are dropped: all of them were churned on every
+    // revisionToken bump and forced a 20/20 miss rate. See the
+    // `cachedReviewWork` declaration above for the full rationale.
+    const wfMarkupHash = computeWorkflowMarkupStructuralHash(wfMarkup);
+    const reviewStateHash = computeReviewStateHash(state.document.review);
+    if (
+      cachedReviewWork &&
+      cachedReviewWork.workflowMarkupHash === wfMarkupHash &&
+      cachedReviewWork.reviewStateHash === reviewStateHash
+    ) {
+      reviewWork = cachedReviewWork.snapshot;
+      perfCounters.increment("ctxa.reviewWork.cacheHit");
+    } else {
+      reviewWork = createReviewWorkSnapshot({
+        comments: cachedRenderSnapshot.comments,
+        trackedChanges: cachedRenderSnapshot.trackedChanges,
+        workflowMarkup: wfMarkup,
+        document: state.document,
+        navigation,
+      });
+      cachedReviewWork = {
+        workflowMarkupHash: wfMarkupHash,
+        reviewStateHash,
+        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,
@@ -1509,8 +1864,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,
@@ -1522,11 +1886,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: {
@@ -1539,6 +1903,38 @@ export function createDocumentRuntime(
     };
   }
 
+  /**
+   * L7 Phase 2 — surface-only refresh triggered by viewport scroll.
+   * Rebuilds only the surface facet (with the current viewportBlockRange) and
+   * splices it into cachedRenderSnapshot. Does NOT rebuild layout, comments,
+   * trackedChanges, or compatibility. Does NOT increment "refresh.all".
+   */
+  function refreshSurfaceOnly(): void {
+    const newSurface = createEditorSurfaceSnapshot(
+      state.document,
+      state.selection,
+      activeStory,
+      { viewportBlockRange },
+    );
+    // Refresh the cache with the just-built snapshot so a subsequent
+    // refreshRenderSnapshot (same revisionToken + activeStoryKey) hits cache.
+    // Without this repopulate, the next non-mutation refresh wastes a second
+    // createEditorSurfaceSnapshot call on an identical rebuild.
+    cachedSurface = {
+      revisionToken: state.revisionToken,
+      activeStoryKey: storyTargetKey(activeStory),
+      snapshot: newSurface,
+    };
+    cachedRenderSnapshot = {
+      ...cachedRenderSnapshot,
+      surface: newSurface,
+    };
+    // Notify listeners using the same pattern as other setX methods.
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
   function getCachedViewStateSnapshot(): EditorViewStateSnapshot {
     const activeStoryKey = storyTargetKey(activeStory);
     const pageLayout = cachedRenderSnapshot.pageLayout;
@@ -1604,6 +2000,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);
@@ -1832,13 +2262,13 @@ export function createDocumentRuntime(
       const selection = params.anchor
         ? createSelectionFromPublicAnchor(params.anchor)
         : state.selection;
-      if (!canCreateDocxCommentAnchor(state.document.content, anchor)) {
+      if (!canCreateDocxCommentAnchor(cachedRenderSnapshot.surface, 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.",
+            "DOCX comments must use a non-empty range that stays within a single story and does not cross table or opaque-fragment boundaries.",
           source: "runtime",
           details: {
             reason: "invalid_comment_anchor",
@@ -1880,7 +2310,10 @@ export function createDocumentRuntime(
         origin: createOrigin("api", clock()),
       });
 
-      return commentId;
+      return {
+        commentId,
+        anchor: toPublicAnchorProjection(anchor),
+      };
     },
     openComment(commentId) {
       this.dispatch({
@@ -1905,6 +2338,8 @@ export function createDocumentRuntime(
       });
     },
     addCommentReply(commentId, body, authorId) {
+      const priorEntryCount =
+        state.document.review.comments[commentId]?.entries?.length ?? 0;
       this.dispatch({
         type: "comment.add-reply",
         commentId,
@@ -1912,6 +2347,8 @@ export function createDocumentRuntime(
         authorId: authorId ?? defaultAuthorId,
         origin: createOrigin("api", clock()),
       });
+      const entryId = `${commentId}-entry-${priorEntryCount + 1}`;
+      return { commentId, entryId };
     },
     editCommentBody(commentId, body) {
       this.dispatch({
@@ -2254,7 +2691,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",
@@ -2270,6 +2737,11 @@ export function createDocumentRuntime(
         overlay,
         origin: createOrigin("api", clock()),
       });
+      editorStateChannel.recordMutation("workflowOverlay", {
+        namespace: "workflowOverlay",
+        schemaVersion: "workflow-overlay/1",
+        data: overlay,
+      });
     },
     clearWorkflowOverlay() {
       this.dispatch({
@@ -2308,6 +2780,11 @@ export function createDocumentRuntime(
         entries,
         origin: createOrigin("api", clock()),
       });
+      editorStateChannel.recordMutation("workflowMetadata", {
+        namespace: "workflowMetadata",
+        schemaVersion: "workflow-metadata/1",
+        data: entries,
+      });
     },
     clearWorkflowMetadataEntries() {
       this.dispatch({
@@ -2324,6 +2801,11 @@ export function createDocumentRuntime(
         overlay,
         origin: createOrigin("api", clock()),
       });
+      editorStateChannel.recordMutation("hostAnnotations", {
+        namespace: "hostAnnotations",
+        schemaVersion: "host-annotation-overlay/1",
+        data: overlay,
+      });
     },
     clearHostAnnotationOverlay() {
       this.dispatch({
@@ -2391,6 +2873,46 @@ 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();
+    },
+    setVisibleBlockRange(range) {
+      if (
+        viewportBlockRange &&
+        viewportBlockRange.start === range.start &&
+        viewportBlockRange.end === range.end
+      ) {
+        return;
+      }
+      viewportBlockRange = { start: range.start, end: range.end };
+      perfCounters.increment("runtime.viewport.updates");
+    },
+    requestViewportRefresh() {
+      perfCounters.increment("runtime.viewport.refreshes");
+      refreshSurfaceOnly();
+    },
   };
 
   function applyHistory(direction: "undo" | "redo"): void {
@@ -2438,15 +2960,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;
@@ -2459,22 +2980,56 @@ 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.  Hardening: also
-    // invalidate the measurement provider's glyph cache AND the engine's
-    // cached graph so the next pagination run re-measures with the
-    // newly-registered FontFaces (pre-hardening the canvas backend kept
-    // returning pre-refresh widths from its cache).
     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));
+
+    // I5: validate post-mutation selection against the new document bound.
+    // First call to getCachedSurface() here computes the post-mutation surface
+    // snapshot (cache miss — revisionToken just changed in finalizeState).
+    // refreshRenderSnapshot's internal call below hits the cache and reuses it.
+    // Net cost: identical to pre-I5 — one surface walk per commit, just shifted
+    // a few lines earlier so the validator can read storySize.
+    //
+    // Wired ONLY at this chokepoint. The other 12 `cachedRenderSnapshot =
+    // refreshRenderSnapshot()` sites in this file are intentionally skipped:
+    // - Initial setup (line ~1878): no prior selection to validate.
+    // - View-mode setters (lines ~2313–2351): zoom/mode/preview changes don't
+    //   change state.document; validator pass would always be identity.
+    // - applyHistory / undo-redo (line ~2813): restores a {document, selection}
+    //   snapshot that was already validated at the commit that produced it.
+    // - Workflow overlay / error / story switch (lines ~3398, 3416, 3582, 3608):
+    //   substitute a stored selection that was validated at the commit that
+    //   stored it. If a future structural command can mutate state.document
+    //   without going through applyTransactionToState, validation must be added
+    //   at that site.
+    //
+    // Using the post-mutation storySize (not cachedRenderSnapshot's pre-mutation
+    // storySize) avoids clamping the caret behind every keystroke at end-of-doc.
+    // The return type of getCachedSurface is `RuntimeRenderSnapshot["surface"]`
+    // which is optional in the public API for shape-only reasons — the helper
+    // itself always returns a defined snapshot.
+    const surfaceForValidation = getCachedSurface(state.document, activeStory)!;
+    const validatedSelection = validateSelectionAgainstDocument(
+      state.document,
+      state.selection,
+      surfaceForValidation.storySize,
+    );
+    if (validatedSelection !== state.selection) {
+      state = { ...state, selection: validatedSelection };
+      storySelections.set(storyTargetKey(activeStory), state.selection);
+    }
 
+    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(
@@ -2935,10 +3490,39 @@ 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();
     }
   }
 
@@ -3085,7 +3669,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)
@@ -4438,6 +5038,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" };
   }