@beyondwork/docx-react-component 1.0.52 → 1.0.54

package/src/runtime/layout/layout-invalidation.ts

@@ -13,19 +13,21 @@
  *     edit offsets (§analyzeContentEdit).
  *   - `section-change`: bounded to the first page of the affected section
  *     onward — P10 Phase C (§analyzeSectionChange).
- *   - `numbering-change`: bounded to the whole document (dirtyPageRange
- *     spans pages [0..end]); tightening to the earliest page referencing
- *     the numbering instance requires per-fragment numbering metadata
- *     on `RuntimeBlockFragment` which is not available today.
+ *   - `styles-change` (Slice 5): when `dirtyStyleIds` is supplied, bounded
+ *     to the first page whose fragments carry a matching `resolvedStyleChainRef`.
+ *     Fallback to full rebuild when the payload is absent or no match found.
+ *   - `numbering-change` (Slice 5): when `numberingInstanceId` is supplied,
+ *     bounded to the first page whose fragments carry a matching
+ *     `numberingInstanceId`. Fallback to full rebuild when absent or no match.
  *
  * Remaining full-rebuild triggers:
- *   - `styles-change` / `theme-change`: without per-fragment style-chain
- *     metadata on the graph, we cannot safely tighten these. Flagged as
- *     follow-up for when `RuntimeBlockFragment.resolvedStyleChain` lands.
+ *   - `theme-change`: theme token changes cascade through the entire
+ *     style chain; no fragment-level tightening possible without knowing
+ *     which blocks reference theme tokens.
  */
 
 import type { LayoutInvalidationReason } from "./paginated-layout-engine.ts";
-import type { RuntimePageGraph, RuntimePageNode } from "./page-graph.ts";
+import type { RuntimeBlockFragment, RuntimePageGraph } from "./page-graph.ts";
 import type { ResolvedDocumentSection } from "../document-layout.ts";
 
 // ---------------------------------------------------------------------------
@@ -92,15 +94,16 @@ export function analyzeInvalidation(
 
   switch (reason.kind) {
     case "full":
-    case "styles-change":
     case "theme-change":
-      // These affect the entire document
       return {
         scope: "full",
         requiresFullRecompute: true,
         dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
       };
 
+    case "styles-change":
+      return analyzeStylesChange(reason, graph);
+
     case "content-edit":
       return analyzeContentEdit(reason, graph);
 
@@ -108,26 +111,9 @@ export function analyzeInvalidation(
       return analyzeSectionChange(reason, graph);
 
     case "numbering-change":
-      if (!reason.numberingInstanceId) {
-        return {
-          scope: "full",
-          requiresFullRecompute: true,
-          dirtyFieldFamilies: [],
-        };
-      }
-      return {
-        scope: "bounded",
-        requiresFullRecompute: false,
-        dirtyPageRange: {
-          firstPageIndex: 0,
-          lastPageIndex: Math.max(0, graph.pages.length - 1),
-        },
-        dirtySectionRange: null,
-        dirtyFieldFamilies: [],
-      };
+      return analyzeNumberingChange(reason, graph);
 
     case "field-refresh":
-      // Field refresh doesn't change layout, just field display values
       return {
         scope: "field-only",
         requiresFullRecompute: false,
@@ -277,12 +263,18 @@ function analyzeSectionChange(
     reason.sectionIndex,
   );
   if (firstPageOfSection < 0) {
+    // L2: Clamp `from` so the range is never backward when the affected
+    // section index exceeds the number of materialized sections (e.g.
+    // section-change on a section that hasn't rendered yet, or an empty
+    // graph). Without the clamp, {from:5, to:0} is a backward range that
+    // confuses consumers iterating [from..to].
+    const lastSectionIdx = Math.max(0, graph.sections.length - 1);
     return {
       scope: "full",
       requiresFullRecompute: true,
       dirtySectionRange: {
-        from: reason.sectionIndex,
-        to: Math.max(0, graph.sections.length - 1),
+        from: Math.min(reason.sectionIndex, lastSectionIdx),
+        to: lastSectionIdx,
       },
       dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
     };
@@ -321,3 +313,131 @@ function findFirstPageIndexForSection(
   // rendered tail. Caller treats this as a full-rebuild trigger.
   return -1;
 }
+
+/**
+ * Slice 5 — narrow `styles-change` invalidation.
+ *
+ * When `reason.dirtyStyleIds` is present, scan fragments for the first
+ * fragment whose `resolvedStyleChainRef` matches any dirty style id.
+ * The page containing that fragment is the first that must rebuild.
+ *
+ * Fallback to full rebuild when `dirtyStyleIds` is absent, empty, or no
+ * fragment matches (e.g. graphs built before Slice 5 shipped).
+ */
+function analyzeStylesChange(
+  reason: Extract<LayoutInvalidationReason, { kind: "styles-change" }>,
+  graph: RuntimePageGraph,
+): InvalidationResult {
+  if (!reason.dirtyStyleIds || reason.dirtyStyleIds.length === 0) {
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
+    };
+  }
+
+  const dirtySet = new Set(reason.dirtyStyleIds);
+  const firstDirtyPageIndex = findFirstPageIndexByFragmentPredicate(
+    graph,
+    (f) =>
+      f.resolvedStyleChainRef !== undefined &&
+      dirtySet.has(f.resolvedStyleChainRef),
+  );
+
+  if (firstDirtyPageIndex < 0) {
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
+    };
+  }
+
+  return {
+    scope: "bounded",
+    requiresFullRecompute: false,
+    dirtyPageRange: {
+      firstPageIndex: firstDirtyPageIndex,
+      lastPageIndex: Math.max(0, graph.pages.length - 1),
+    },
+    dirtySectionRange: null,
+    dirtyFieldFamilies: [],
+  };
+}
+
+/**
+ * Slice 5 — narrow `numbering-change` invalidation.
+ *
+ * When `reason.numberingInstanceId` is present, find the first page
+ * containing a fragment with matching `numberingInstanceId` and start
+ * the rebuild there. Fallback to full rebuild when absent or no match.
+ */
+function analyzeNumberingChange(
+  reason: Extract<LayoutInvalidationReason, { kind: "numbering-change" }>,
+  graph: RuntimePageGraph,
+): InvalidationResult {
+  if (!reason.numberingInstanceId) {
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyFieldFamilies: [],
+    };
+  }
+
+  const instanceId = reason.numberingInstanceId;
+  const firstDirtyPageIndex = findFirstPageIndexByFragmentPredicate(
+    graph,
+    (f) => f.numberingInstanceId === instanceId,
+  );
+
+  if (firstDirtyPageIndex < 0) {
+    // No fragment matches (e.g. graph has no fragments yet, or the
+    // numberingInstanceId references an instance that hasn't materialized on
+    // any page). Per the function's contract — "Fallback to full rebuild
+    // when absent or no match" — return a full rebuild so the caller
+    // re-paginates from scratch rather than a bounded pass over stale
+    // geometry.
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtyFieldFamilies: [],
+    };
+  }
+
+  return {
+    scope: "bounded",
+    requiresFullRecompute: false,
+    dirtyPageRange: {
+      firstPageIndex: firstDirtyPageIndex,
+      lastPageIndex: Math.max(0, graph.pages.length - 1),
+    },
+    dirtySectionRange: null,
+    dirtyFieldFamilies: [],
+  };
+}
+
+/**
+ * Find the pageIndex of the first non-filler page whose fragments include
+ * at least one fragment satisfying `predicate`. Returns -1 if none found.
+ */
+function findFirstPageIndexByFragmentPredicate(
+  graph: RuntimePageGraph,
+  predicate: (f: RuntimeBlockFragment) => boolean,
+): number {
+  const pageIdToIndex = new Map<string, number>();
+  for (const page of graph.pages) {
+    if (!page.isBlankFiller) {
+      pageIdToIndex.set(page.pageId, page.pageIndex);
+    }
+  }
+
+  let firstDirtyPageIndex = -1;
+  for (const fragment of graph.fragments) {
+    if (!predicate(fragment)) continue;
+    const pageIndex = pageIdToIndex.get(fragment.pageId);
+    if (pageIndex === undefined) continue;
+    if (firstDirtyPageIndex < 0 || pageIndex < firstDirtyPageIndex) {
+      firstDirtyPageIndex = pageIndex;
+    }
+  }
+  return firstDirtyPageIndex;
+}

package/src/runtime/layout/page-graph.ts

@@ -149,6 +149,18 @@ export interface RuntimeBlockFragment {
     to: number;
     totalRows: number;
   };
+  /**
+   * Slice 5 — opaque style-chain ref derived from the block's `styleId`.
+   * Used by `analyzeStylesChange` to bound invalidation to the first page
+   * that carries a fragment referencing a dirty style.
+   */
+  resolvedStyleChainRef?: string;
+  /**
+   * Slice 5 — numbering instance id copied from the block's `numbering`
+   * field. Used by `analyzeNumberingChange` to bound invalidation to the
+   * first page that carries a fragment from the affected list instance.
+   */
+  numberingInstanceId?: string;
 }
 
 export interface RuntimeLineBox {
@@ -629,6 +641,13 @@ function pageNodesStructurallyEqual(
   for (let i = 0; i < aFoot.length; i += 1) {
     if (!regionFragmentsEqual(aFoot[i]!, bFoot[i]!)) return false;
   }
+  // L1: Include line-box and note-allocation counts as structural proxies.
+  // Fragment IDs staying stable while line geometry changes (font-metric
+  // change, float-wrap) would allow stale node reuse without these guards.
+  // Length-only is O(1) and catches the common case; deep baseline
+  // comparison is deferred.
+  if (a.lineBoxes.length !== b.lineBoxes.length) return false;
+  if (a.noteAllocations.length !== b.noteAllocations.length) return false;
   return true;
 }
 

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

@@ -81,7 +81,7 @@ import {
 export type LayoutInvalidationReason =
   | { kind: "content-edit"; from: number; to: number }
   | { kind: "section-change"; sectionIndex: number }
-  | { kind: "styles-change" }
+  | { kind: "styles-change"; dirtyStyleIds?: readonly string[] }
   | { kind: "theme-change" }
   | { kind: "numbering-change"; numberingInstanceId?: string }
   | { kind: "field-refresh"; family?: string }
@@ -416,28 +416,137 @@ export function buildPageStackFromWithSplits(
   resumeAt: { startPageIndex: number; startOffset: number },
   measurementProvider?: LayoutMeasurementProvider,
 ): PageStackResultWithSplits {
-  void resumeAt.startOffset;
-  const full = buildPageStackWithSplits(
-    document,
-    sections as ResolvedDocumentSection[],
-    mainSurface,
-    measurementProvider,
+  const startOffset = resumeAt.startOffset;
+  const dirtyPageNumberOffset = Math.max(0, resumeAt.startPageIndex);
+
+  // Fast path: offset at document start → full paginate is identical.
+  if (startOffset <= 0) {
+    return buildPageStackWithSplits(
+      document,
+      sections as ResolvedDocumentSection[],
+      mainSurface,
+      measurementProvider,
+    );
+  }
+
+  // Find the first section that contains or starts after startOffset.
+  const firstDirtySectionIdx = (sections as ResolvedDocumentSection[]).findIndex(
+    (s) => s.end > startOffset,
   );
-  const startIndex = Math.max(0, resumeAt.startPageIndex);
-  const tailPages = full.pages.slice(startIndex);
-  const tailSplits = new Map<string, ParagraphLineSlice[]>();
-  for (const [blockId, slices] of full.splits.byBlockId) {
-    const tail = slices.filter((s) => s.pageIndex >= startIndex);
-    if (tail.length > 0) tailSplits.set(blockId, tail);
+  if (firstDirtySectionIdx < 0) {
+    // All sections end before the dirty offset — nothing to re-paginate.
+    return buildPageStackWithSplits(
+      document,
+      sections as ResolvedDocumentSection[],
+      mainSurface,
+      measurementProvider,
+    );
   }
-  const tailTableSplits = new Map<string, TableRowSlice[]>();
-  for (const [blockId, slices] of full.splits.tablesByBlockId) {
-    const tail = slices.filter((s) => s.pageIndex >= startIndex);
-    if (tail.length > 0) tailTableSplits.set(blockId, tail);
+
+  // Safety guard: if any block straddles the section boundary (to > startOffset
+  // but from < section.start), we cannot safely skip without reconstructing
+  // carry-over state — fall back to full paginate to avoid silent correctness loss.
+  const dirtySectionStart = (sections as ResolvedDocumentSection[])[firstDirtySectionIdx]!.start;
+  const straddling = mainSurface.blocks.some(
+    (b) => b.from < dirtySectionStart && b.to > startOffset,
+  );
+  // When the dirty section is section 0, there is nothing to skip — fall
+  // back to the full-build + tail-slice path so page startOffsets are
+  // correct (the section-skip path shifts only pageIndex, not startOffset,
+  // which would produce phantom pages when spliceGraph prepends page 0).
+  if (straddling || firstDirtySectionIdx === 0) {
+    const full = buildPageStackWithSplits(
+      document,
+      sections as ResolvedDocumentSection[],
+      mainSurface,
+      measurementProvider,
+    );
+    const tailPages = full.pages.slice(dirtyPageNumberOffset);
+    const tailSplits = new Map<string, ParagraphLineSlice[]>();
+    for (const [blockId, slices] of full.splits.byBlockId) {
+      const tail = slices.filter((s) => s.pageIndex >= dirtyPageNumberOffset);
+      if (tail.length > 0) tailSplits.set(blockId, tail);
+    }
+    const tailTableSplits = new Map<string, TableRowSlice[]>();
+    for (const [blockId, slices] of full.splits.tablesByBlockId) {
+      const tail = slices.filter((s) => s.pageIndex >= dirtyPageNumberOffset);
+      if (tail.length > 0) tailTableSplits.set(blockId, tail);
+    }
+    return {
+      pages: tailPages,
+      splits: { byBlockId: tailSplits, tablesByBlockId: tailTableSplits },
+    };
   }
+
+  // Section-level skip: paginate only the dirty sections onward (only
+  // reached when firstDirtySectionIdx > 0).
+  const dirtySections = (sections as ResolvedDocumentSection[]).slice(firstDirtySectionIdx);
+  const dirtyBlockSet = new Set(
+    mainSurface.blocks
+      .filter((b) => b.from >= dirtySectionStart)
+      .map((b) => b.blockId),
+  );
+  const dirtySurface: EditorSurfaceSnapshot = {
+    ...mainSurface,
+    blocks: mainSurface.blocks.filter((b) => dirtyBlockSet.has(b.blockId)),
+  };
+
+  const tailResult = buildPageStackWithSplits(
+    document,
+    dirtySections,
+    dirtySurface,
+    measurementProvider,
+  );
+
+  // Shift global page indices on all returned pages and splits so they align
+  // with the global page graph (the caller's spliceGraph prepends the head).
+  const shiftedPages = tailResult.pages.map((p) => ({
+    ...p,
+    pageIndex: p.pageIndex + dirtyPageNumberOffset,
+  }));
+  const shiftedSplits: BlockSplits = {
+    byBlockId: new Map(
+      Array.from(tailResult.splits.byBlockId.entries()).map(([id, slices]) => [
+        id,
+        slices.map((s) => ({ ...s, pageIndex: s.pageIndex + dirtyPageNumberOffset })),
+      ]),
+    ),
+    tablesByBlockId: new Map(
+      Array.from(tailResult.splits.tablesByBlockId.entries()).map(([id, slices]) => [
+        id,
+        slices.map((s) => ({ ...s, pageIndex: s.pageIndex + dirtyPageNumberOffset })),
+      ]),
+    ),
+  };
+  // Shift note-allocation page indices if present.
+  const shiftedNoteAllocs =
+    tailResult.noteAllocationsByPageIndex && tailResult.noteAllocationsByPageIndex.size > 0
+      ? new Map(
+          Array.from(tailResult.noteAllocationsByPageIndex.entries()).map(([pi, allocs]) => [
+            pi + dirtyPageNumberOffset,
+            allocs,
+          ]),
+        )
+      : undefined;
+  const shiftedNoteFragments =
+    tailResult.noteFragmentsByPageIndex && tailResult.noteFragmentsByPageIndex.size > 0
+      ? new Map(
+          Array.from(tailResult.noteFragmentsByPageIndex.entries()).map(([pi, frags]) => [
+            pi + dirtyPageNumberOffset,
+            frags,
+          ]),
+        )
+      : undefined;
+
   return {
-    pages: tailPages,
-    splits: { byBlockId: tailSplits, tablesByBlockId: tailTableSplits },
+    pages: shiftedPages,
+    splits: shiftedSplits,
+    ...(shiftedNoteAllocs !== undefined
+      ? { noteAllocationsByPageIndex: shiftedNoteAllocs }
+      : {}),
+    ...(shiftedNoteFragments !== undefined
+      ? { noteFragmentsByPageIndex: shiftedNoteFragments }
+      : {}),
   };
 }
 

package/src/runtime/layout/project-block-fragments.ts

@@ -109,6 +109,7 @@ export function projectSurfaceBlocksToPageFragments(
       from: block.from,
       to: block.to,
       heightTwips: estimateBlockHeightFromSpan(block),
+      ...deriveStyleMetadata(block),
       kind: "whole",
     };
 
@@ -138,6 +139,7 @@ function emitSlicedParagraph(
       from: block.from,
       to: block.to,
       heightTwips: estimateSliceHeightFromLines(slice.lineRange),
+      ...deriveStyleMetadata(block),
       kind: "paragraph-slice",
       paragraphLineRange: slice.lineRange,
     };
@@ -178,6 +180,7 @@ function emitSlicedTable(
       from: block.from,
       to: block.to,
       heightTwips: estimateSliceHeightFromRows(slice.rowRange),
+      ...deriveStyleMetadata(block),
       kind: "table-slice",
       tableRowRange: slice.rowRange,
     };
@@ -223,3 +226,27 @@ function estimateBlockHeightFromSpan(block: SurfaceBlockSnapshot): number {
   const lines = Math.max(1, Math.ceil(span / 80));
   return lines * 240;
 }
+
+/**
+ * Slice 5 — extract style metadata from a surface block for use in
+ * bounded invalidation. `resolvedStyleChainRef` is the block's styleId
+ * (paragraphs and tables only); `numberingInstanceId` comes from the
+ * block's list-instance (paragraphs only). Both fields are optional and
+ * absent when the block carries no style or numbering data.
+ */
+function deriveStyleMetadata(
+  block: SurfaceBlockSnapshot,
+): Pick<FragmentWithoutPageId, "resolvedStyleChainRef" | "numberingInstanceId"> {
+  const styleId =
+    block.kind === "paragraph" || block.kind === "table"
+      ? (block.styleId ?? undefined)
+      : undefined;
+  const numberingInstanceId =
+    block.kind === "paragraph"
+      ? (block.numbering?.numberingInstanceId ?? undefined)
+      : undefined;
+  return {
+    ...(styleId !== undefined ? { resolvedStyleChainRef: styleId } : {}),
+    ...(numberingInstanceId !== undefined ? { numberingInstanceId } : {}),
+  };
+}

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

@@ -560,6 +560,15 @@ export interface WordReviewEditorLayoutFacet {
     pageIndex: number,
   ): import("./table-render-plan.ts").TableRenderPlan | null;
 
+  /**
+   * Returns the Y offset (in twips from the top of the page body) where this
+   * table fragment starts on the given page. Computed by summing
+   * `heightTwips` of all body fragments with `orderInRegion` less than the
+   * table fragment's order. Returns `null` when the block is not found on
+   * the specified page.
+   */
+  getTableBodyYOffsetOnPage(blockId: string, pageIndex: number): number | null;
+
   // Fields ---------------------------------------------------------------
   getDirtyFieldFamilies(): readonly string[];
   getFieldDirtinessReport(): PublicFieldDirtinessReport;
@@ -1231,15 +1240,48 @@ export function createLayoutFacet(
       const tableHeightTwips = graph.fragments
         .filter((f) => f.blockId === blockId)
         .reduce((total, f) => total + f.heightTwips, 0);
+      // Determine if this page holds a continuation slice of the table
+      // (rows after the first slice).  Fragment kind "table-slice" with
+      // tableRowRange.from > 0 means the table was split across pages and
+      // this page carries a non-first slice — header rows should repeat.
+      const pageNode = graph.pages.find((p) => p.pageIndex === pageIndex);
+      const sliceFragment = pageNode
+        ? graph.fragments.find(
+            (f) => f.blockId === blockId && f.pageId === pageNode.pageId,
+          )
+        : undefined;
+      const isContinuationPage =
+        sliceFragment?.kind === "table-slice" &&
+        (sliceFragment.tableRowRange?.from ?? 0) > 0;
+
       return buildTableRenderPlan({
         blockId,
         pageIndex,
         block: tableBlock,
         resolved,
         tableHeightTwips,
+        isContinuationPage,
       });
     },
 
+    getTableBodyYOffsetOnPage(blockId, pageIndex) {
+      const graph = currentGraph();
+      const pageNode = graph.pages.find(
+        (p) => p.pageIndex === pageIndex && !p.isBlankFiller,
+      );
+      if (!pageNode) return null;
+      const bodyFragmentIdSet = new Set(pageNode.regions.body.fragmentIds);
+      const bodyFragments = graph.fragments
+        .filter((f) => bodyFragmentIdSet.has(f.fragmentId))
+        .sort((a, b) => a.orderInRegion - b.orderInRegion);
+      let yOffset = 0;
+      for (const frag of bodyFragments) {
+        if (frag.blockId === blockId) return yOffset;
+        yOffset += frag.heightTwips;
+      }
+      return null;
+    },
+
     getDirtyFieldFamilies() {
       return engine.getDirtyFieldFamilies();
     },
@@ -1274,11 +1316,36 @@ export function createLayoutFacet(
 // Internal: graph → public clones
 // ---------------------------------------------------------------------------
 
+/**
+ * Per-runtime-node cache for `toPublicPageNode`.
+ *
+ * P10 Phase B2. When `spliceGraph` preserves a `RuntimePageNode`
+ * reference across a bounded relayout (Phase D1 tail-convergence
+ * reuse), this cache preserves the derived `PublicPageNode` reference
+ * too — so downstream consumers (React.memo-gated page subtrees in
+ * `TwPageStackChromeLayer`, per-page test hooks) observe stable props
+ * and can skip reconciliation.
+ *
+ * The map is a WeakMap keyed on the runtime node. When a fresh runtime
+ * node replaces a prior one (divergent-tail case), the prior cache
+ * entry is garbage-collected with the prior node; no manual eviction
+ * is required. Structural contract: consumers MUST NOT mutate the
+ * returned `PublicPageNode`, which has always been a read-only clone.
+ */
+const publicPageNodeCache = new WeakMap<RuntimePageNode, PublicPageNode>();
+
 function toPublicPageNode(
   node: RuntimePageNode,
   graph: RuntimePageGraph,
 ): PublicPageNode {
-  return {
+  const cached = publicPageNodeCache.get(node);
+  // Safety guard: reuse only when the runtime node's index still
+  // matches the cached projection. Under normal D1 tail-convergence the
+  // index is preserved, but this belt-and-braces check guarantees we
+  // never hand out a stale clone if a runtime node is ever reused at a
+  // different position by a future splice strategy.
+  if (cached && cached.pageIndex === node.pageIndex) return cached;
+  const built: PublicPageNode = {
     pageId: node.pageId,
     pageIndex: node.pageIndex,
     sectionIndex: node.sectionIndex,
@@ -1295,7 +1362,9 @@ function toPublicPageNode(
     lineBoxCount: node.lineBoxes.length,
     noteAllocations: node.noteAllocations.map(toPublicNoteAllocation),
   };
+  publicPageNodeCache.set(node, built);
   void graph; // reserved for future cross-page derivations
+  return built;
 }
 
 function toPublicResolvedPageStories(

package/src/runtime/prerender/cache-envelope.ts

@@ -1,5 +1,6 @@
 import type { EditorSurfaceSnapshot } from "../../api/public-types";
 import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import type { CompatibilityReport } from "../../core/state/editor-state.ts";
 import type { RuntimePageGraph } from "../layout/page-graph.ts";
 
 /**
@@ -28,6 +29,17 @@ import type { RuntimePageGraph } from "../layout/page-graph.ts";
  *   - `canonicalDocumentHash` — sha256 of sorted-keys JSON. Also the 5th
  *     input to `deriveCacheKey`, so style/metadata/comment/preservation
  *     mutations correctly invalidate the cache.
+ *
+ * Phase 2 Finale C3 addition (schema v3):
+ *   - `compatibilityReport?` — pre-computed `CompatibilityReport`. The
+ *     report is a pure function of `canonicalDocument` (plus the
+ *     `generatedAt` timestamp, which is pinned to the fixed sentinel
+ *     `"__cache_normalized__"` at prerender write time so envelopes are
+ *     byte-identical across two prerender calls). When present on the
+ *     Plan B short-circuit path, `loadDocxEditorSessionAsync` skips the
+ *     live `buildCompatibilityReport` call (60–100 ms on extra-large).
+ *     The field is optional so v3 writers can ship envelopes without it
+ *     (graceful degradation to the existing live-computation path).
  */
 export interface CacheEnvelope {
   readonly schemaVersion: number;
@@ -38,4 +50,22 @@ export interface CacheEnvelope {
   readonly graph: RuntimePageGraph;
   readonly surface: EditorSurfaceSnapshot;
   readonly canonicalDocument: CanonicalDocument;
+  /**
+   * v3+. Optional even at v3 — absence means "compute live on read".
+   * See the Phase 2 Finale C3 banner above.
+   */
+  readonly compatibilityReport?: CompatibilityReport;
 }
+
+/**
+ * Fixed sentinel used in place of `new Date().toISOString()` when
+ * pre-computing `compatibilityReport` for the envelope. Ensures two
+ * sequential `prerenderDocument` calls on identical bytes produce
+ * byte-identical cache envelopes.
+ *
+ * Downstream consumers of `compatibilityReport.generatedAt` are
+ * diagnostic-only — the field has never been user-visible in the editor
+ * UX. Cache-hit paths observe the sentinel; cache-miss paths observe a
+ * live ISO8601 timestamp.
+ */
+export const CACHE_NORMALIZED_GENERATED_AT = "__cache_normalized__" as const;

package/src/runtime/prerender/customxml-cache.ts

@@ -194,7 +194,7 @@ function extractInlineCdata(rawXml: string): string | null {
 function isValidCacheEnvelope(value: unknown): value is CacheEnvelope {
   if (typeof value !== "object" || value === null) return false;
   const v = value as Record<string, unknown>;
-  return (
+  const requiredFieldsOk =
     v.schemaVersion === LAYCACHE_SCHEMA_VERSION &&
     v.engineVersion === LAYOUT_ENGINE_VERSION &&
     typeof v.fontFingerprint === "string" &&
@@ -205,7 +205,21 @@ function isValidCacheEnvelope(value: unknown): value is CacheEnvelope {
     typeof v.surface === "object" &&
     v.surface !== null &&
     typeof v.canonicalDocument === "object" &&
-    v.canonicalDocument !== null
-  );
+    v.canonicalDocument !== null;
+  if (!requiredFieldsOk) return false;
+  // C3 (schema v3): `compatibilityReport` is optional — if present it must
+  // be a structured object with the expected shape markers. Envelopes
+  // without the field degrade gracefully to live-computation on read.
+  if (v.compatibilityReport !== undefined) {
+    const cr = v.compatibilityReport as Record<string, unknown> | null;
+    if (typeof cr !== "object" || cr === null) return false;
+    if (cr.reportVersion !== "compatibility-report/1") return false;
+    if (typeof cr.generatedAt !== "string") return false;
+    if (typeof cr.blockExport !== "boolean") return false;
+    if (!Array.isArray(cr.featureEntries)) return false;
+    if (!Array.isArray(cr.warnings)) return false;
+    if (!Array.isArray(cr.errors)) return false;
+  }
+  return true;
 }