@beyondwork/docx-react-component 1.0.42 → 1.0.45

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

@@ -182,6 +182,35 @@ export interface LayoutEngineInstance {
    * glyphs, and the cached page graph keeps its stale page boundaries.
    */
   invalidateMeasurementCache(): void;
+
+  // ---- cache rehydration (L7 Phase 2.5) ---------------------------------
+  /**
+   * Seed the engine's cached graph from a prerendered `RuntimePageGraph`
+   * (read from IndexedDB or customXml). Subsequent `getPageGraph()` calls
+   * against the same `document` return the seeded graph directly —
+   * skipping `fullRebuild` and the pagination/measurement work that
+   * dominates cold-open on large docs.
+   *
+   * Both the graph and the source document must be seeded so the
+   * engine's internal cache-key (`content`, `styles`, `subParts`
+   * reference-equality tuple) compares equal on the next query. Passing
+   * only the graph leaves `cachedKey` null, the next query would run a
+   * full rebuild, and the seed would be discarded.
+   *
+   * Caller contract:
+   *   - The seeded graph must have been produced by the same
+   *     LAYOUT_ENGINE_VERSION as the current engine instance. Stale reads
+   *     are prevented by the cache-key scheme in
+   *     src/runtime/prerender/cache-key.ts (engine version is part of the
+   *     key), not by this method.
+   *   - The next runtime mutation triggers a normal invalidation path;
+   *     the seeded graph is treated as a fresh cache entry from the
+   *     engine's perspective.
+   */
+  seedCachedGraph(
+    graph: RuntimePageGraph,
+    document: CanonicalDocumentEnvelope,
+  ): void;
 }
 
 // ---------------------------------------------------------------------------
@@ -296,16 +325,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
@@ -413,16 +450,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;
 
@@ -722,6 +766,23 @@ export function createLayoutEngine(
       cachedFormatting = null;
       cachedMapper = null;
     },
+
+    /**
+     * L7 Phase 2.5 — seed the cached graph from a prerender envelope.
+     * Populates both `cachedGraph` and `cachedKey` (keyed on the provided
+     * document's identity-equal slots) so the next getPageGraph query
+     * returns the seeded graph directly. Any subsequent mutation
+     * invalidates normally through the existing path.
+     */
+    seedCachedGraph(graph: RuntimePageGraph, document: CanonicalDocumentEnvelope) {
+      cachedGraph = graph;
+      cachedKey = {
+        content: document.content,
+        styles: document.styles,
+        subParts: document.subParts,
+      };
+      previousPageCount = graph.contentPageCount;
+    },
   };
 }
 

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

@@ -0,0 +1,41 @@
+/**
+ * Layout engine version marker — bump when **any** file under
+ * `src/runtime/layout/**` or `src/runtime/render/**` changes, or when
+ * the page-break widget DOM shape under `src/ui-tailwind/editor-surface/`
+ * changes in a way that affects cached render-frame diffs or persisted
+ * layout caches.
+ *
+ * Enforcement: `scripts/ci-check-layout-engine-version.mjs` inspects the
+ * PR diff; if any file in the watched trees is touched without this
+ * constant being co-touched, CI fails.  See CLAUDE.md → *Performance
+ * Invariants* for the full contract.
+ *
+ * Persisted caches should key their stored snapshots on this version so a
+ * bump automatically invalidates stale entries — no corruption path
+ * exists because the version is the cache's top-level discriminator.
+ *
+ * History:
+ *   1 — initial materialization (L8 Phase B).
+ *   2 — L8 Phase B retired the page-posture widget's inline band-gap-band
+ *       DOM in favor of a transparent spacer.  Widget DOM shape changed;
+ *       cached render frames from version 1 are incompatible.
+ *   3 — L7 Phase 2.5 Plan A. Adds `seedCachedGraph(graph, document)` to
+ *       `LayoutEngineInstance` so prerender-cache consumers can seed the
+ *       internal cachedGraph + cachedKey without triggering fullRebuild.
+ *       Does not change geometry — but the public interface changed, so
+ *       persisted envelopes MUST re-derive their cacheKey under 3.
+ */
+export const LAYOUT_ENGINE_VERSION = 3 as const;
+
+/**
+ * Serialization schema version for the LayCache payload (the cache envelope
+ * stored in IndexedDB, and — post Plan B — the customXml editor-state
+ * namespace). Bump independently of LAYOUT_ENGINE_VERSION when the
+ * envelope shape changes but the layout engine itself has not.
+ *
+ * History:
+ *   1 — initial envelope shape: { schemaVersion, engineVersion,
+ *       fontFingerprint, structuralHash, graph, surface }. Ships with
+ *       L7 Phase 2.5 Plan A.
+ */
+export const LAYCACHE_SCHEMA_VERSION = 1 as const;

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

@@ -41,6 +41,10 @@ import type {
   FootnoteCollection,
 } from "../../model/canonical-document.ts";
 import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  RuntimeNoteAllocation,
+  RuntimeBlockFragment,
+} from "./page-graph.ts";
 import {
   buildPageLayoutSnapshot,
   buildResolvedSections,
@@ -138,6 +142,19 @@ export interface BlockSplits {
 export interface PageStackResultWithSplits {
   pages: DocumentPageSnapshot[];
   splits: BlockSplits;
+  /**
+   * P8.1b — per-page note allocations emitted by the engine.
+   * Keyed by zero-based global page index.
+   * Absent entries mean the page has no footnotes.
+   * Endnote allocations are deferred to P8 Task 7.
+   */
+  noteAllocationsByPageIndex?: ReadonlyMap<number, RuntimeNoteAllocation[]>;
+  /**
+   * P8.1b — per-page note body fragments emitted by the engine.
+   * Each fragment has `regionKind: "footnote-area"`.
+   * Parallel to `noteAllocationsByPageIndex`.
+   */
+  noteFragmentsByPageIndex?: ReadonlyMap<number, Array<Omit<RuntimeBlockFragment, "pageId">>>;
 }
 
 // ---------------------------------------------------------------------------
@@ -182,6 +199,13 @@ export function buildPageStackWithSplits(
 ): PageStackResultWithSplits {
   const pages: DocumentPageSnapshot[] = [];
   const splitsByBlock = new Map<string, ParagraphLineSlice[]>();
+  // P8.1b — aggregate note allocations and fragments across all sections,
+  // keyed by global page index.
+  const globalNoteAllocationsByPageIndex = new Map<number, RuntimeNoteAllocation[]>();
+  const globalNoteFragmentsByPageIndex = new Map<
+    number,
+    Array<Omit<RuntimeBlockFragment, "pageId">>
+  >();
   let globalPageIndex = 0;
   // A single cache lives for the whole pagination pass so cross-section
   // re-measurement (rare but possible through keepNext heuristics) still
@@ -305,6 +329,21 @@ export function buildPageStackWithSplits(
       }
       if (existing.length > 0) splitsByBlock.set(blockId, existing);
     }
+
+    // P8.1b — resolve per-section note allocations + fragments to global
+    // page index and merge into the global maps.
+    for (const [pageInSec, sectionAllocs] of paginatedResult.noteAllocationsByPageInSection) {
+      const globalPageIdx = pageInSectionToGlobal.get(pageInSec);
+      if (globalPageIdx === undefined) continue;
+      const existing = globalNoteAllocationsByPageIndex.get(globalPageIdx) ?? [];
+      globalNoteAllocationsByPageIndex.set(globalPageIdx, [...existing, ...sectionAllocs]);
+    }
+    for (const [pageInSec, sectionFrags] of paginatedResult.noteFragmentsByPageInSection) {
+      const globalPageIdx = pageInSectionToGlobal.get(pageInSec);
+      if (globalPageIdx === undefined) continue;
+      const existing = globalNoteFragmentsByPageIndex.get(globalPageIdx) ?? [];
+      globalNoteFragmentsByPageIndex.set(globalPageIdx, [...existing, ...sectionFrags]);
+    }
   }
 
   // Guarantee at least one page
@@ -328,6 +367,12 @@ export function buildPageStackWithSplits(
   return {
     pages,
     splits: { byBlockId: splitsByBlock, tablesByBlockId: tableSplitsByBlock },
+    noteAllocationsByPageIndex: globalNoteAllocationsByPageIndex.size > 0
+      ? globalNoteAllocationsByPageIndex
+      : undefined,
+    noteFragmentsByPageIndex: globalNoteFragmentsByPageIndex.size > 0
+      ? globalNoteFragmentsByPageIndex
+      : undefined,
   };
 }
 
@@ -984,6 +1029,10 @@ interface SectionLocalSlice {
 interface SectionPaginationResult {
   pages: Omit<DocumentPageSnapshot, "pageIndex">[];
   splits: { byBlockId: Map<string, SectionLocalSlice[]> };
+  /** P8.1b — per-page note allocations keyed by pageInSection index. */
+  noteAllocationsByPageInSection: Map<number, RuntimeNoteAllocation[]>;
+  /** P8.1b — per-page note body fragments keyed by pageInSection index. */
+  noteFragmentsByPageInSection: Map<number, Array<Omit<RuntimeBlockFragment, "pageId">>>;
 }
 
 /**
@@ -1009,7 +1058,7 @@ function paginateSectionBlocks(
   ).pages;
 }
 
-function paginateSectionBlocksWithSplits(
+export function paginateSectionBlocksWithSplits(
   section: ResolvedDocumentSection,
   blocks: readonly SurfaceBlockSnapshot[],
   layout: DocumentPageSnapshot["layout"],
@@ -1029,6 +1078,8 @@ function paginateSectionBlocksWithSplits(
         },
       ],
       splits: { byBlockId: new Map() }, // section-local; global map includes tablesByBlockId via collectTableRowSlices
+      noteAllocationsByPageInSection: new Map(),
+      noteFragmentsByPageInSection: new Map(),
     };
   }
 
@@ -1048,14 +1099,104 @@ function paginateSectionBlocksWithSplits(
   // table is fully placed.
   const tableProgress = new Map<string, number>();
 
+  // P8.1b — per-page note tracking.
+  // `pendingNoteKeys` parallels `reservedNotes` but is only snapshotted on
+  // page-push (finalization), NOT on column break.
+  // `pendingNoteBlockFroms` records the referencing block's `from` offset
+  // for each note key, enabling hit-test via `RuntimeBlockFragment.from`.
+  const noteAllocationsByPageInSection = new Map<number, RuntimeNoteAllocation[]>();
+  const noteFragmentsByPageInSection = new Map<
+    number,
+    Array<Omit<RuntimeBlockFragment, "pageId">>
+  >();
+  const pendingNoteKeys = new Set<string>();
+  const pendingNoteBlockFroms = new Map<string, { blockFrom: number; blockTo: number }>();
+  // Track the columnWidth at the time each note was accumulated so the
+  // measurement is reproducible at page-close time.
+  const pendingNoteColumnWidths = new Map<string, number>();
+
+  /**
+   * Snapshot the pending note state into `noteAllocationsByPageInSection` and
+   * `noteFragmentsByPageInSection` for the page that is about to close.
+   * Must be called BEFORE clearing `pendingNoteKeys`.
+   */
+  const snapshotNoteAllocations = (closingPageInSection: number, columnWidth: number): void => {
+    if (pendingNoteKeys.size === 0 || !footnotes) return;
+
+    const allocations: RuntimeNoteAllocation[] = [];
+    const fragments: Array<Omit<RuntimeBlockFragment, "pageId">> = [];
+    let orderInRegion = 0;
+
+    for (const noteKey of pendingNoteKeys) {
+      const colonIdx = noteKey.indexOf(":");
+      if (colonIdx === -1) continue;
+      const noteKind = noteKey.slice(0, colonIdx) as "footnote" | "endnote";
+      const noteId = noteKey.slice(colonIdx + 1);
+
+      // P8.1b: endnote allocations are deferred to P8 Task 7 (endnote area
+      // component).  The existing reservedNoteHeight math still reserves space
+      // for endnotes, but we do not emit RuntimeNoteAllocation for them here.
+      // See P8 plan, Task 7.
+      if (noteKind === "endnote") continue;
+
+      const effectiveColumnWidth =
+        pendingNoteColumnWidths.get(noteKey) ?? columnWidth;
+      const { heightTwips } = measureNoteBody(
+        noteKind,
+        noteId,
+        footnotes,
+        effectiveColumnWidth,
+      );
+
+      const fragmentId = `note-${closingPageInSection}-${noteKind}-${noteId}`;
+      const refRange = pendingNoteBlockFroms.get(noteKey) ?? {
+        blockFrom: pageStart,
+        blockTo: pageStart + 1,
+      };
+
+      const allocation: RuntimeNoteAllocation = {
+        noteKind,
+        noteId,
+        reservedHeightTwips: heightTwips + FOOTNOTE_REFERENCE_RESERVATION_TWIPS,
+        fragmentId,
+      };
+
+      const fragment: Omit<RuntimeBlockFragment, "pageId"> = {
+        fragmentId,
+        blockId: `note-body-${noteKind}-${noteId}`,
+        orderInRegion,
+        regionKind: "footnote-area",
+        from: refRange.blockFrom,
+        to: refRange.blockTo,
+        heightTwips: heightTwips + FOOTNOTE_REFERENCE_RESERVATION_TWIPS,
+        kind: "whole",
+      };
+
+      allocations.push(allocation);
+      fragments.push(fragment);
+      orderInRegion += 1;
+    }
+
+    if (allocations.length > 0) {
+      noteAllocationsByPageInSection.set(closingPageInSection, allocations);
+      noteFragmentsByPageInSection.set(closingPageInSection, fragments);
+    }
+  };
+
   const pushPage = (endOffset: number): void => {
     const boundedEnd = Math.max(pageStart, Math.min(endOffset, section.end));
     if (boundedEnd === pageStart && pages.length > 0) {
       return;
     }
+    const closingPageInSection = pageInSection;
+    const columnWidth =
+      columnMetrics[Math.min(columnIndex, columnMetrics.length - 1)]?.width ??
+      getUsableColumnWidth(layout);
+    // Snapshot note allocations for the page being closed BEFORE clearing state.
+    snapshotNoteAllocations(closingPageInSection, columnWidth);
     pages.push({
       sectionIndex: section.index,
-      pageInSection,
+      pageInSection: closingPageInSection,
       startOffset: pageStart,
       endOffset: boundedEnd,
       layout,
@@ -1066,6 +1207,10 @@ function paginateSectionBlocksWithSplits(
     columnIndex = 0;
     reservedNoteHeight = 0;
     reservedNotes.clear();
+    // P8.1b: also clear pending note tracking on page finalization.
+    pendingNoteKeys.clear();
+    pendingNoteBlockFroms.clear();
+    pendingNoteColumnWidths.clear();
   };
 
   for (let index = 0; index < blocks.length; index += 1) {
@@ -1183,10 +1328,15 @@ function paginateSectionBlocksWithSplits(
       // Overflow check — paragraph doesn't fit on current page
       if (projectedHeight > usableHeight && pageStart < block.from) {
         if (columnIndex < maxColumns - 1) {
+          // Advance to next column without a page break — do NOT snapshot.
           columnIndex += 1;
           columnHeight = 0;
           reservedNoteHeight = 0;
           reservedNotes.clear();
+          // P8.1b: clear pending note state WITHOUT snapshotting.
+          pendingNoteKeys.clear();
+          pendingNoteBlockFroms.clear();
+          pendingNoteColumnWidths.clear();
           continue;
         }
 
@@ -1264,10 +1414,15 @@ function paginateSectionBlocksWithSplits(
       // span the full page if it's truly larger than a page).
       if (keepLinesActive && columnHeight > 0 && baseHeight > usableHeight - columnHeight && pageStart < block.from) {
         if (columnIndex < maxColumns - 1) {
+          // Column advance without page break — do NOT snapshot.
           columnIndex += 1;
           columnHeight = 0;
           reservedNoteHeight = 0;
           reservedNotes.clear();
+          // P8.1b: clear pending note state WITHOUT snapshotting.
+          pendingNoteKeys.clear();
+          pendingNoteBlockFroms.clear();
+          pendingNoteColumnWidths.clear();
           continue;
         }
         pushPage(block.from);
@@ -1282,14 +1437,32 @@ function paginateSectionBlocksWithSplits(
       );
       columnHeight += baseHeight;
       reservedNoteHeight += effectiveNoteHeight;
-      currentPageNoteIds(block).forEach((noteKey) => reservedNotes.add(noteKey));
+      currentPageNoteIds(block).forEach((noteKey) => {
+        reservedNotes.add(noteKey);
+        // P8.1b: also track the referencing block range for hit-test.
+        // Only record the first reference (earliest block.from) per noteKey
+        // so the fragment's from/to points to the paragraph that introduced it.
+        if (!pendingNoteKeys.has(noteKey)) {
+          pendingNoteKeys.add(noteKey);
+          pendingNoteBlockFroms.set(noteKey, { blockFrom: block.from, blockTo: block.to });
+          pendingNoteColumnWidths.set(noteKey, columnWidth);
+        }
+      });
 
       if (hasColumnBreak(block)) {
         if (columnIndex < maxColumns - 1) {
+          // Column break within a multi-column layout: advance to next column.
+          // DO NOT snapshot note allocations — only page-push triggers snapshotting.
+          // Clear pending note state alongside reservedNotes so notes that only
+          // appeared before the column break don't get double-counted.
           columnIndex += 1;
           columnHeight = 0;
           reservedNoteHeight = 0;
           reservedNotes.clear();
+          // P8.1b: clear pending note state WITHOUT snapshotting.
+          pendingNoteKeys.clear();
+          pendingNoteBlockFroms.clear();
+          pendingNoteColumnWidths.clear();
         } else {
           pushPage(nextBoundary);
         }
@@ -1317,9 +1490,37 @@ function paginateSectionBlocksWithSplits(
             },
           ],
     splits: { byBlockId: splitsByBlock },
+    noteAllocationsByPageInSection,
+    noteFragmentsByPageInSection,
   };
 }
 
+/**
+ * Measure the height consumed by one note's body blocks, plus return those
+ * blocks for use in building a `RuntimeBlockFragment`.
+ *
+ * Factored out of `estimateFootnoteReservation` so both the reservation-math
+ * path and the P8.1b allocation-emission path share the same measurement.
+ */
+function measureNoteBody(
+  noteKind: "footnote" | "endnote",
+  noteId: string,
+  footnotes: FootnoteCollection,
+  columnWidth: number,
+): { heightTwips: number } {
+  const noteCollection =
+    noteKind === "endnote" ? footnotes.endnotes : footnotes.footnotes;
+  const note = noteCollection[noteId];
+  if (!note) {
+    return { heightTwips: 0 };
+  }
+  const heightTwips = note.blocks.reduce(
+    (total, child) => total + estimateCanonicalNoteBlockHeight(child, columnWidth),
+    0,
+  );
+  return { heightTwips };
+}
+
 function estimateFootnoteReservation(
   block: SurfaceBlockSnapshot,
   footnotes: FootnoteCollection | undefined,
@@ -1336,17 +1537,13 @@ function estimateFootnoteReservation(
       continue;
     }
 
-    const [noteKind, noteId] = noteKey.split(":");
-    const noteCollection =
-      noteKind === "endnote" ? footnotes.endnotes : footnotes.footnotes;
-    const note = noteCollection[noteId];
-    reservation += FOOTNOTE_REFERENCE_RESERVATION_TWIPS;
-    if (note) {
-      reservation += note.blocks.reduce(
-        (total, child) => total + estimateCanonicalNoteBlockHeight(child, columnWidth),
-        0,
-      );
-    }
+    const colonIdx = noteKey.indexOf(":");
+    if (colonIdx === -1) continue;
+    const noteKind = noteKey.slice(0, colonIdx) as "footnote" | "endnote";
+    const noteId = noteKey.slice(colonIdx + 1);
+    // Use measureNoteBody so reservation math and emission share the same path.
+    const { heightTwips } = measureNoteBody(noteKind, noteId, footnotes, columnWidth);
+    reservation += FOOTNOTE_REFERENCE_RESERVATION_TWIPS + heightTwips;
   }
 
   return reservation;