@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/runtime/editor-state-integration.ts

@@ -0,0 +1,217 @@
+/**
+ * editor-state-integration.ts — Schema 1.2 Task D + E helpers.
+ *
+ * Factored out of document-runtime.ts / docx-session.ts to keep
+ * those files focused.  Two entry points:
+ *
+ * - `hydrateEditorStateFromEnvelope`: called right after the runtime
+ *   is created and the envelope parsed; drives the load-path.
+ * - `collectEditorStateForSerialize`: called inside exportDocx before
+ *   `buildWorkflowPayloadParts`; drives the save-path.
+ */
+
+import type { EditorStateNamespace } from "../api/editor-state-types.ts";
+import type { EditorStateChannel } from "./editor-state-channel.ts";
+import type {
+  EditorStatePayload,
+  EditorStatePayloadNamespaceEntry,
+} from "../io/ooxml/workflow-payload.ts";
+
+// All namespaces the runtime currently knows about.
+export const ALL_EDITOR_STATE_NAMESPACES: readonly EditorStateNamespace[] = [
+  "hostAnnotations",
+  "workflowOverlay",
+  "workflowMetadata",
+  "workItems",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Load-path: hydrateEditorStateFromEnvelope
+// ---------------------------------------------------------------------------
+
+export interface HydrateEditorStateArgs {
+  /** The editorState block parsed from the workflow-payload envelope. */
+  editorState: EditorStatePayload;
+  channel: EditorStateChannel;
+  /**
+   * Called for each namespace whose blob has been resolved/loaded.
+   * Responsible for applying the blob to the appropriate subsystem store
+   * (e.g. calling runtime.setHostAnnotationOverlay).
+   */
+  applyBlob: (namespace: EditorStateNamespace, data: unknown) => void;
+}
+
+/**
+ * Drives the load-path for schema 1.2 editor-state entries.
+ *
+ * - Unknown namespaces → preserved opaquely, `unknown_namespace` event.
+ * - Inline entries under in-document policy → applied directly.
+ * - Keyed entries → resolver called; result applied (or failure handled).
+ * - Policy mismatch → `policy_migrated` event.
+ *
+ * Returns a promise that resolves when all namespaces have been
+ * processed.  Rejects only when `onResolveError` is `"block"` for a
+ * namespace and the resolver fails — the caller should fail the load.
+ */
+export async function hydrateEditorStateFromEnvelope(
+  args: HydrateEditorStateArgs,
+): Promise<void> {
+  const { editorState, channel, applyBlob } = args;
+
+  // Record unknown namespaces first — they are preserved opaquely by
+  // the payload layer; we emit the warning event AND hand the raw XML
+  // to the channel so the next save round-trips it verbatim.
+  for (const unknown of editorState.unknownNamespaces ?? []) {
+    channel.recordUnknownNamespace(unknown.name, { rawXml: unknown.rawXml });
+  }
+
+  for (const entry of editorState.entries) {
+    await hydrateEntry({ entry, channel, applyBlob });
+  }
+}
+
+async function hydrateEntry(args: {
+  entry: EditorStatePayloadNamespaceEntry;
+  channel: EditorStateChannel;
+  applyBlob: (namespace: EditorStateNamespace, data: unknown) => void;
+}): Promise<void> {
+  const { entry, channel, applyBlob } = args;
+  const ns = entry.namespace;
+  const policyEntry = channel.getPolicyEntry(ns);
+
+  // Malformed inline JSON: surface as a load failure; don't apply.
+  if (entry.malformedInline) {
+    channel.recordLoadFailure({
+      namespace: ns,
+      error: new Error(`Malformed inline JSON for namespace "${ns}"`),
+      fallback: policyEntry.onResolveError === "block" ? "empty" : policyEntry.onResolveError,
+    });
+    return;
+  }
+
+  // Policy-migration detection: compare payload-written location vs
+  // current policy location.
+  const payloadLocation: string = entry.storageRef
+    ? entry.storageRef.location
+    : "in-document";
+  if (payloadLocation !== policyEntry.location) {
+    channel.recordPolicyMigration({
+      namespace: ns,
+      from: payloadLocation as import("../api/editor-state-types.ts").EditorStateLocation,
+      to: policyEntry.location,
+      key: entry.storageRef?.entryKey,
+    });
+  }
+
+  // Inline path: apply directly when both payload and policy agree on
+  // in-document.
+  if (entry.inline !== undefined && policyEntry.location === "in-document") {
+    applyBlob(ns, entry.inline);
+    channel.recordLoaded(ns, {
+      namespace: ns,
+      schemaVersion: entry.schemaVersion,
+      data: entry.inline,
+    });
+    return;
+  }
+
+  // Keyed path: set the key from the payload, then call the resolver.
+  if (entry.storageRef) {
+    channel.setKey(ns, entry.storageRef.entryKey);
+    // Under keyed policy the resolver wins over any inline blob.
+    const result = await channel.resolve(ns, entry.storageRef.entryKey);
+    if (result.blob !== null) {
+      applyBlob(ns, result.blob.data);
+      if (!result.appliedFallback) {
+        channel.recordLoaded(ns, result.blob);
+      }
+    }
+    // result.blob === null → failure already handled by channel (event
+    // emitted, fallback mode applied).  Nothing more to apply.
+    return;
+  }
+
+  // Mismatch: payload is inline but policy is keyed.  Apply inline as
+  // fallback (no key to resolve against).
+  if (entry.inline !== undefined) {
+    applyBlob(ns, entry.inline);
+    channel.recordLoaded(ns, {
+      namespace: ns,
+      schemaVersion: entry.schemaVersion,
+      data: entry.inline,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Save-path: collectEditorStateForSerialize
+// ---------------------------------------------------------------------------
+
+export interface CollectEditorStateArgs {
+  channel: EditorStateChannel;
+  /**
+   * Returns the current in-memory blob for a namespace, or null if
+   * the namespace has no data to persist.
+   */
+  getNamespaceData: (ns: EditorStateNamespace) => { schemaVersion: string; data: unknown } | null;
+}
+
+/**
+ * Builds the `EditorStatePayload` for the serializer.
+ *
+ * 1. Flushes any pending debounced persists so the docx captures
+ *    the last-known-good state for rowstore namespaces.
+ * 2. For each namespace with data: emits inline or storageRef per policy.
+ * 3. Returns undefined when no namespaces have data — the serializer
+ *    then omits `<bw:editorState>` entirely (downgrade to 1.1/1.0).
+ */
+export async function collectEditorStateForSerialize(
+  args: CollectEditorStateArgs,
+): Promise<EditorStatePayload | undefined> {
+  const { channel, getNamespaceData } = args;
+
+  // Flush pending debounced persists before serialize resolves.
+  await channel.flush();
+
+  const entries: EditorStatePayloadNamespaceEntry[] = [];
+
+  for (const ns of ALL_EDITOR_STATE_NAMESPACES) {
+    const current = getNamespaceData(ns);
+    if (!current) continue;
+
+    const policyEntry = channel.getPolicyEntry(ns);
+
+    if (policyEntry.location === "in-document") {
+      entries.push({
+        namespace: ns,
+        schemaVersion: current.schemaVersion,
+        inline: current.data,
+      });
+    } else {
+      const key = channel.getKey(ns);
+      if (!key) continue; // Keyed policy without a key — can't serialize ref.
+      entries.push({
+        namespace: ns,
+        schemaVersion: current.schemaVersion,
+        storageRef: {
+          location: policyEntry.location as Exclude<
+            import("../api/editor-state-types.ts").EditorStateLocation,
+            "in-document"
+          >,
+          entryKey: key,
+        },
+      });
+    }
+  }
+
+  const unknownEntries = channel.getUnknownEntries();
+  const unknownNamespaces = unknownEntries
+    .filter((u): u is typeof u & { rawXml: string } => typeof u.rawXml === "string")
+    .map((u) => ({ name: u.name, rawXml: u.rawXml }));
+
+  if (entries.length === 0 && unknownNamespaces.length === 0) return undefined;
+  return {
+    entries,
+    ...(unknownNamespaces.length > 0 ? { unknownNamespaces } : {}),
+  };
+}

package/src/runtime/external-send-runtime.ts

@@ -0,0 +1,117 @@
+import {
+  sendToExternal,
+  type SendToExternalBlock,
+  type SendToExternalResult,
+} from "../io/export/external-send.ts";
+import type {
+  ExternalCustodyResolver,
+} from "../api/external-custody-types.ts";
+import type { CollabSessionBridge } from "./collab-session-bridge.ts";
+import { resignPayload } from "./resign-payload.ts";
+import type { PayloadSigner } from "../io/ooxml/payload-signature.ts";
+import type { TamperGate } from "./tamper-gate.ts";
+
+/**
+ * Runtime-level composition of the P7 pure pipeline with:
+ *   - the P8c `CollabSessionBridge` (snapshots of negotiation /
+ *     presentation / participants)
+ *   - the P8e `TamperGate` (blocks when `metadataIntegrity === "tampered"`)
+ *   - the P8a `resignPayload()` hook (every write re-signs)
+ *
+ * Callers supply the raw workflow-payload XML alongside the collab
+ * state. On success the result carries:
+ *   - the custody receipt (to be emitted inside bw:extensions)
+ *   - the kept snapshots (to replace the pre-send facet state)
+ *   - the re-signed payload XML (to persist in the shipped docx)
+ *
+ * This helper does NOT rewrite `word/document.xml` / `word/comments.xml`
+ * or the three companion parts; the caller owns the zip rewrite using
+ * `result.stripped.commentIds`. This keeps the runtime layer isolated
+ * from OPC packaging.
+ */
+export interface RuntimeSendToExternalArgs {
+  bridge: CollabSessionBridge;
+  tamperGate: TamperGate;
+  signer: PayloadSigner;
+
+  /** The raw `<bw:workflowPayload …>…</bw:workflowPayload>` XML. */
+  payloadXml: string;
+
+  role: "author" | "reviewer" | "observer";
+
+  originDocumentId: string;
+  originPayloadId: string;
+  /** sha256:{hex} of canonicalized word/document.xml at send time. */
+  originContentHash: string;
+
+  resolver: ExternalCustodyResolver;
+  recipient: string;
+  sentBy: string;
+  archiveRef: string;
+
+  /** Optional deterministic overrides for tests. */
+  custodyId?: string;
+  now?: string;
+}
+
+export type RuntimeSendToExternalResult =
+  | { ok: false; reason: "collab_role_restricted" }
+  | { ok: false; reason: "metadata_tampered" }
+  | {
+      ok: true;
+      custody: SendToExternalResult["custody"];
+      kept: SendToExternalResult["kept"];
+      stripped: SendToExternalResult["stripped"];
+      /** Re-signed `<bw:workflowPayload …>…</bw:workflowPayload>` ready to persist. */
+      payloadXml: string;
+    };
+
+export async function runtimeSendToExternal(
+  args: RuntimeSendToExternalArgs,
+): Promise<RuntimeSendToExternalResult> {
+  const guard = args.tamperGate.guard();
+  if (!guard.ok) {
+    return { ok: false, reason: guard.reason };
+  }
+
+  const presentation = args.bridge.getCommentPresentationSnapshot();
+  const negotiation = args.bridge.getCommentNegotiationSnapshot();
+  const participants = args.bridge.getParticipantRoster();
+
+  const pipelineArgs = {
+    presentation,
+    negotiation,
+    participants,
+    role: args.role,
+    metadataIntegrity:
+      args.tamperGate.state === "unsigned" ? "verified" : args.tamperGate.state,
+    originDocumentId: args.originDocumentId,
+    originPayloadId: args.originPayloadId,
+    originContentHash: args.originContentHash,
+    resolver: args.resolver,
+    recipient: args.recipient,
+    sentBy: args.sentBy,
+    archiveRef: args.archiveRef,
+    ...(args.custodyId !== undefined ? { custodyId: args.custodyId } : {}),
+    ...(args.now !== undefined ? { now: args.now } : {}),
+  } as const;
+
+  const pipeline: SendToExternalBlock = await sendToExternal(pipelineArgs);
+  if (!pipeline.ok) {
+    return { ok: false, reason: pipeline.reason };
+  }
+
+  const { payloadXml } = await resignPayload({
+    payloadXml: args.payloadXml,
+    signer: args.signer,
+    ...(args.now !== undefined ? { now: args.now } : {}),
+  });
+
+  return {
+    ok: true,
+    custody: pipeline.result.custody,
+    kept: pipeline.result.kept,
+    stripped: pipeline.result.stripped,
+    payloadXml,
+  };
+}

package/src/runtime/layout/docx-font-loader.ts

@@ -45,35 +45,12 @@ export interface DocxFontLoader {
   refresh(input: FontLoaderInput): void;
 }
 
-interface MinimalFontFace {
-  load(): Promise<MinimalFontFace>;
-}
-
-interface MinimalFontFaceDescriptors {
-  weight?: string;
-  style?: string;
-}
-
-interface MinimalFontFaceConstructor {
-  new (
-    family: string,
-    source: ArrayBuffer | ArrayBufferView | string,
-    descriptors?: MinimalFontFaceDescriptors,
-  ): MinimalFontFace;
-}
-
-interface MinimalFontFaceSet {
-  add(face: MinimalFontFace): void;
-  check(font: string): boolean;
-  ready: Promise<MinimalFontFaceSet>;
-}
-
 export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
-  const globalDocument = (globalThis as unknown as { document?: { fonts?: unknown } }).document;
   const supported =
-    globalDocument !== undefined &&
+    typeof document !== "undefined" &&
     typeof (globalThis as { FontFace?: unknown }).FontFace !== "undefined" &&
-    Boolean(globalDocument.fonts);
+    // Guard against jsdom which exposes FontFace but not document.fonts
+    Boolean((document as Document & { fonts?: FontFaceSet }).fonts);
 
   let current: FontLoaderInput = initial;
   let readyPromise: Promise<void>;
@@ -81,7 +58,7 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
   function run(input: FontLoaderInput): Promise<void> {
     if (!supported) return Promise.resolve();
-    const fontSet = globalDocument?.fonts as MinimalFontFaceSet | undefined;
+    const fontSet = (document as Document & { fonts?: FontFaceSet }).fonts;
     if (!fontSet) return Promise.resolve();
 
     const pending: Array<Promise<unknown>> = [];
@@ -93,8 +70,10 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
         for (const [descriptor, data] of variantsOf(variants)) {
           try {
-            const FontFaceCtor = (globalThis as { FontFace?: MinimalFontFaceConstructor }).FontFace;
-            if (!FontFaceCtor) continue;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const FontFaceCtor = (globalThis as any).FontFace as {
+              new (family: string, source: BufferSource, descriptors?: FontFaceDescriptors): FontFace;
+            };
             const face = new FontFaceCtor(family, data, descriptor);
             pending.push(
               face.load().then((loaded) => {
@@ -109,6 +88,8 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
       }
     }
 
+    // Mark declared families as registered if the browser already resolves
+    // them (e.g. system fonts like Calibri, Arial).
     for (const family of input.families) {
       try {
         const probe = `12px "${family.replace(/"/g, "'")}", serif`;
@@ -146,7 +127,7 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
 function* variantsOf(
   variants: EmbeddedFontBytes,
-): IterableIterator<[MinimalFontFaceDescriptors, ArrayBuffer]> {
+): IterableIterator<[FontFaceDescriptors, ArrayBuffer]> {
   if (variants.regular) {
     yield [{ weight: "400", style: "normal" }, variants.regular];
   }

package/src/runtime/layout/index.ts

@@ -172,6 +172,8 @@ export {
   type PublicPageNode,
   type PublicPageRegions,
   type PublicPageRegion,
+  type PublicRegionBlock,
+  type PublicRegionKind,
   type PublicBlockFragment,
   type PublicLineBox,
   type PublicNoteAllocation,

package/src/runtime/layout/inert-layout-facet.ts

@@ -35,6 +35,9 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getDisplayPageNumber: () => null,
     getLineBoxes: () => [],
     getLineBoxesForRegion: () => [],
+    getStoryRegionsOnPage: () => [],
+    getStoryBlocksForRegion: () => [],
+    getDocumentEndnoteBlocks: () => [],
     getFragmentsForPage: () => [],
     getPageFormatCatalog: () => PAGE_FORMAT_CATALOG,
     getActivePageFormat: () => null,
@@ -54,6 +57,7 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     whenMeasurementReady: () => Promise.resolve(),
     getFirstPageIndexForBlock: () => null,
     swapMeasurementProvider: () => undefined,
+    invalidateMeasurementCache: () => undefined,
     getTableRenderPlan: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,

package/src/runtime/layout/layout-engine-instance.ts

@@ -104,7 +104,19 @@ export interface LayoutEngineEvent {
     | "incremental_relayout"
     | "page_count_changed"
     | "page_field_dirtied"
-    | "measurement_backend_ready";
+    | "measurement_backend_ready"
+    /**
+     * P14.b — coalesced "the engine just finished a build" event.  Emitted
+     * exactly once per `fullRebuild` / `incrementalRelayout` AFTER the
+     * granular events, carrying the union of dirty-field families, page-
+     * count delta, and page-range info.  Subscribers that only need to
+     * react to "something layout-affecting changed" can listen to this
+     * single event and skip the multi-event subscription pattern that
+     * triggered N React re-renders per applyPatch.  The granular events
+     * still fire for backward compat with consumers (TwStatusBar fidelity
+     * badge, etc.) that care about specific kinds.
+     */
+    | "layout_committed";
   revision: number;
   previousPageCount?: number;
   currentPageCount?: number;
@@ -113,6 +125,17 @@ export interface LayoutEngineEvent {
   fidelity?: LayoutMeasurementProvider["fidelity"];
   /** First dirty page index for incremental_relayout events. */
   firstDirtyPageIndex?: number;
+  /**
+   * P14.b — page-count delta for `layout_committed`.  Present when the
+   * commit produced a different total page count than the prior graph.
+   */
+  pageCountDelta?: { previous: number; current: number };
+  /**
+   * P14.b — when `layout_committed` came from a bounded incremental
+   * relayout, the page range that was re-paginated.  Absent for full
+   * rebuilds.
+   */
+  pageRange?: { fromPageIndex: number; toPageIndex: number };
 }
 
 export interface LayoutEngineInstance {
@@ -149,6 +172,16 @@ export interface LayoutEngineInstance {
 
   // ---- measurement plumbing --------------------------------------------
   swapMeasurementProvider(provider: LayoutMeasurementProvider): void;
+  /**
+   * Invalidate the active measurement provider's internal caches (canvas
+   * glyph / run-width LRU) AND clear the engine's cached page graph so
+   * the next query re-paginates with fresh measurements.  Host runtime
+   * calls this after `docxFontLoader.refresh(...)` registers new
+   * FontFace families — without this call the canvas backend's glyph
+   * cache keeps returning pre-refresh widths for already-measured
+   * glyphs, and the cached page graph keeps its stale page boundaries.
+   */
+  invalidateMeasurementCache(): void;
 }
 
 // ---------------------------------------------------------------------------
@@ -263,16 +296,24 @@ export function createLayoutEngine(
     );
     const pages = pageStack.pages;
     const stories = resolvePageStories(pages);
-    const fragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
+    const bodyFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
       mainSurface,
       pages,
       pageStack.splits,
     );
+    // P8.1b — merge per-note fragments (regionKind: "footnote-area") into the
+    // main fragments map so buildPageGraph sees them alongside body fragments.
+    const fragmentsByPageIndex = new Map(bodyFragmentsByPageIndex);
+    for (const [pageIndex, noteFragments] of (pageStack.noteFragmentsByPageIndex ?? new Map())) {
+      const existing = fragmentsByPageIndex.get(pageIndex) ?? [];
+      fragmentsByPageIndex.set(pageIndex, [...existing, ...noteFragments]);
+    }
     const graph = buildPageGraph({
       pages,
       sections,
       stories,
       fragmentsByPageIndex,
+      noteAllocationsByPageIndex: pageStack.noteAllocationsByPageIndex,
     });
 
     // Field dirtiness diff from previous graph
@@ -284,14 +325,30 @@ export function createLayoutEngine(
     const formatting = buildResolvedFormattingState(document, mainSurface);
 
     const currentPageCount = resolveTotalPageCount(pages);
+    let pageCountDelta: { previous: number; current: number } | undefined;
     if (currentPageCount !== previousPageCount) {
+      pageCountDelta = { previous: previousPageCount, current: currentPageCount };
+      previousPageCount = currentPageCount;
+    }
+
+    // MUST publish cache before emit: re-entrant getPageGraph() calls from
+    // subscribers during emit would otherwise trigger runaway rebuilds.
+    cachedKey = {
+      content: document.content,
+      styles: document.styles,
+      subParts: document.subParts,
+    };
+    cachedGraph = graph;
+    cachedFormatting = formatting;
+    cachedMapper = createPageFragmentMapper(graph);
+
+    if (pageCountDelta) {
       emit({
         kind: "page_count_changed",
         revision: graph.revision,
-        previousPageCount,
-        currentPageCount,
+        previousPageCount: pageCountDelta.previous,
+        currentPageCount: pageCountDelta.current,
       });
-      previousPageCount = currentPageCount;
     }
 
     if (dirtyFamilies.length > 0) {
@@ -308,14 +365,16 @@ export function createLayoutEngine(
       ...(reason ? { reason } : {}),
     });
 
-    cachedKey = {
-      content: document.content,
-      styles: document.styles,
-      subParts: document.subParts,
-    };
-    cachedGraph = graph;
-    cachedFormatting = formatting;
-    cachedMapper = createPageFragmentMapper(graph);
+    emit({
+      kind: "layout_committed",
+      revision: graph.revision,
+      ...(reason ? { reason } : {}),
+      ...(dirtyFamilies.length > 0
+        ? { dirtyFieldFamilies: dirtyFamilies }
+        : {}),
+      ...(pageCountDelta ? { pageCountDelta } : {}),
+    });
+
     return graph;
   }
 
@@ -362,16 +421,23 @@ export function createLayoutEngine(
     const freshStories = resolvePageStories(freshSnapshots);
     // Project fragments for the fresh tail pages, threading paragraph
     // line-range splits produced by intra-paragraph pagination.
-    const freshFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
+    const freshBodyFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
       mainSurface,
       freshSnapshots,
       freshResult.splits,
     );
+    // P8.1b — merge per-note fragments into the fresh fragments map.
+    const freshFragmentsByPageIndex = new Map(freshBodyFragmentsByPageIndex);
+    for (const [pageIndex, noteFragments] of (freshResult.noteFragmentsByPageIndex ?? new Map())) {
+      const existing = freshFragmentsByPageIndex.get(pageIndex) ?? [];
+      freshFragmentsByPageIndex.set(pageIndex, [...existing, ...noteFragments]);
+    }
     const freshGraph = buildPageGraph({
       pages: freshSnapshots,
       sections,
       stories: freshStories,
       fragmentsByPageIndex: freshFragmentsByPageIndex,
+      noteAllocationsByPageIndex: freshResult.noteAllocationsByPageIndex,
     });
     const freshNodes = freshGraph.pages;
 
@@ -388,7 +454,9 @@ export function createLayoutEngine(
     const currentPageCount = resolveTotalPageCount(
       deriveDocumentPageSnapshots(splicedGraph),
     );
+    let pageCountDelta: { previous: number; current: number } | undefined;
     if (currentPageCount !== previousPageCount) {
+      pageCountDelta = { previous: previousPageCount, current: currentPageCount };
       emit({
         kind: "page_count_changed",
         revision: splicedGraph.revision,
@@ -413,6 +481,30 @@ export function createLayoutEngine(
       firstDirtyPageIndex: firstDirty,
     });
 
+    // P14.b — coalesced commit event for the bounded-incremental path.
+    //
+    // Page-range semantics: the current `incrementalRelayout` path uses
+    // `buildPageStackFromWithSplits` + `spliceGraph`, which always
+    // re-paginates from `firstDirty` through the document tail (we
+    // discard the prior tail and replace it with the freshly-paginated
+    // pages).  So `toPageIndex = pages.length - 1` is correct for every
+    // commit produced by this path.  Future bounded-middle splices
+    // (e.g., a middle-style change that doesn't touch the tail) would
+    // need to track an explicit upper bound — guard the assumption
+    // here so the contract drift becomes a test failure rather than a
+    // silent over-iteration in consumers (Chrome overlay, render kernel
+    // diff).
+    emit({
+      kind: "layout_committed",
+      revision: splicedGraph.revision,
+      reason: pending.reason,
+      pageRange: { fromPageIndex: firstDirty, toPageIndex: splicedGraph.pages.length - 1 },
+      ...(dirtyFamilies.length > 0
+        ? { dirtyFieldFamilies: dirtyFamilies }
+        : {}),
+      ...(pageCountDelta ? { pageCountDelta } : {}),
+    });
+
     cachedKey = {
       content: document.content,
       styles: document.styles,
@@ -605,13 +697,46 @@ export function createLayoutEngine(
     },
 
     swapMeasurementProvider(provider) {
+      const previousFidelity = measurementProvider.fidelity;
       measurementProvider = provider;
+      // Hardening: a backend swap changes the measurement numerics the
+      // cached graph was built against.  Empirical → canvas typically
+      // reduces line counts (canvas-accurate glyph widths pack more
+      // text per line); canvas → canvas-with-font-loading applies the
+      // correct FontFace metrics for embedded DOCX fonts.  Either way,
+      // the cached graph is stale — invalidate so the next
+      // `getGraph()` query re-paginates with the new provider.  Skip
+      // invalidation when fidelity is unchanged (e.g., an empirical
+      // → empirical swap, or a canvas fallback that resolved back to
+      // the same backend) so we don't churn.
+      if (previousFidelity !== provider.fidelity) {
+        cachedKey = null;
+        cachedGraph = null;
+        cachedFormatting = null;
+        cachedMapper = null;
+      }
       emit({
         kind: "measurement_backend_ready",
         revision: cachedGraph?.revision ?? 0,
         fidelity: provider.fidelity,
       });
     },
+    /**
+     * Invalidate the current measurement provider's internal glyph /
+     * run-width cache.  Called by the host runtime after
+     * `fontLoader.refresh(...)` so canvas-backed measurements re-read
+     * the newly-registered FontFaces instead of returning stale widths
+     * from the pre-refresh glyph cache.  The graph cache itself is
+     * also cleared because a font change can shift line breaks and
+     * therefore page boundaries.
+     */
+    invalidateMeasurementCache() {
+      measurementProvider.invalidateCache();
+      cachedKey = null;
+      cachedGraph = null;
+      cachedFormatting = null;
+      cachedMapper = null;
+    },
   };
 }