@beyondwork/docx-react-component 1.0.42 → 1.0.45

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

@@ -62,8 +62,12 @@ import {
   type ScopeRailSegment,
 } from "../workflow-rail-segments.ts";
 import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
+import { storyTargetKey } from "../story-targeting.ts";
 import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
-import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
+import {
+  createSelectionSnapshot,
+  type CanonicalDocumentEnvelope,
+} from "../../core/state/editor-state.ts";
 import { resolveTableStyleResolution } from "../table-style-resolver.ts";
 import { buildTableRenderPlan } from "./table-render-plan.ts";
 import { recordPerfSample } from "../../ui-tailwind/editor-surface/perf-probe.ts";
@@ -124,6 +128,13 @@ export interface PublicPageRegions {
   header?: PublicPageRegion;
   footer?: PublicPageRegion;
   columns?: readonly PublicPageRegion[];
+  /**
+   * P8.3 — Footnote regions reserved at the bottom of the page (above the
+   * footer band). Mirrors `RuntimePageRegions.footnotes`. Present only
+   * when at least one allocation on this page produced a fragment — see
+   * `noteAllocations` for per-note metadata. Additive / back-compat safe.
+   */
+  footnotes?: readonly PublicPageRegion[];
 }
 
 export interface PublicPageRegion {
@@ -134,6 +145,15 @@ export interface PublicPageRegion {
   fragmentCount: number;
 }
 
+/**
+ * P8 — Region kind discriminator used by `PublicRegionBlock` and the
+ * `getStoryBlocksForRegion` API.  Mirrors `PublicPageRegion["kind"]` plus
+ * `"endnote-area"`, which is only ever surfaced via
+ * `getDocumentEndnoteBlocks` (endnotes have document-end placement and
+ * never sit on a body page).
+ */
+export type PublicRegionKind = PublicPageRegion["kind"] | "endnote-area";
+
 export interface PublicBlockFragment {
   fragmentId: string;
   blockId: string;
@@ -146,6 +166,29 @@ export interface PublicBlockFragment {
   orderInRegion: number;
 }
 
+/**
+ * P8 — One block snapshot rendered into a region of a page.  Returned by
+ * `WordReviewEditorLayoutFacet.getStoryBlocksForRegion` and
+ * `getDocumentEndnoteBlocks`.
+ *
+ * The `blockSnapshot` field is the same `SurfaceBlockSnapshot` consumed by
+ * the body block renderer (`tw-page-block-view`), so region renderers reuse
+ * body typography verbatim.  For body fragments `runtimeFromOffset`/`To`
+ * mirror the underlying `RuntimeBlockFragment.from`/`to`.  For header /
+ * footer / footnote-area blocks the offsets are local to the host story
+ * (header story, footer story, or note body).
+ */
+export interface PublicRegionBlock {
+  blockId: string;
+  fragmentId: string;
+  pageIndex: number;
+  regionKind: PublicRegionKind;
+  runtimeFromOffset: number;
+  runtimeToOffset: number;
+  heightTwips: number;
+  blockSnapshot: SurfaceBlockSnapshot;
+}
+
 export interface PublicLineBox {
   fragmentId: string;
   lineIndex: number;
@@ -376,6 +419,29 @@ export interface WordReviewEditorLayoutFacet {
   getStoryRegionsOnPage(pageIndex: number): readonly PublicPageRegion[];
   getFragmentsForPage(pageIndex: number): PublicBlockFragment[];
 
+  /**
+   * P8 — Returns per-region block snapshots for a page.  Body resolves the
+   * page's body fragments to their `SurfaceBlockSnapshot`s; header / footer
+   * resolve via the page's active story target + `subParts.headers/footers`
+   * lookup; footnote-area resolves per-page `noteAllocations` against
+   * `subParts.footnoteCollection.footnotes`.  Endnote-area is always empty
+   * per-page — document-end placement is handled by
+   * `getDocumentEndnoteBlocks`.  Column falls through to body (multi-column
+   * splitting is a P10 follow-up).  Cached per revision; busts on
+   * `graph.revision` change.
+   */
+  getStoryBlocksForRegion(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    options?: { columnIndex?: number },
+  ): readonly PublicRegionBlock[];
+
+  /**
+   * P8 — Returns endnote bodies in document order for document-end
+   * placement (per OOXML default `w:endnotePr/w:pos="docEnd"`).
+   */
+  getDocumentEndnoteBlocks(): readonly PublicRegionBlock[];
+
   // Page-format catalog --------------------------------------------------
   getPageFormatCatalog(): readonly PageFormatDefinition[];
   getActivePageFormat(sectionIndex: number): ActivePageFormat | null;
@@ -498,6 +564,19 @@ export interface WordReviewEditorLayoutFacet {
   getDirtyFieldFamilies(): readonly string[];
   getFieldDirtinessReport(): PublicFieldDirtinessReport;
 
+  // Viewport culling (L7 Phase 2) ----------------------------------------
+  /**
+   * Notifies the runtime that the visible block range changed.  Delegates to
+   * `DocumentRuntime.setVisibleBlockRange`.  Safe to call at any frequency;
+   * identical ranges are a no-op inside the runtime.
+   */
+  setVisibleBlockRange(range: { start: number; end: number }): void;
+  /**
+   * Triggers a surface-only refresh applying the latest visible block range.
+   * Delegates to `DocumentRuntime.requestViewportRefresh`.
+   */
+  requestViewportRefresh(): void;
+
   // Events ---------------------------------------------------------------
   subscribe(listener: (event: LayoutFacetEvent) => void): () => void;
 }
@@ -509,6 +588,13 @@ export interface WordReviewEditorLayoutFacet {
 export interface CreateLayoutFacetInput {
   engine: LayoutEngineInstance;
   getQueryInput: () => LayoutEngineQueryInput;
+  /**
+   * P8 — Canonical document accessor used by `getStoryBlocksForRegion` /
+   * `getDocumentEndnoteBlocks` to resolve header / footer / footnote /
+   * endnote stories in `subParts`.  When omitted the facet falls back to
+   * the document available on the engine query input.
+   */
+  canonicalDocument?: () => CanonicalDocumentEnvelope;
   /**
    * Optional render-kernel accessor.  When supplied, the facet exposes
    * `getRenderFrame` + `getRenderZoom` that delegate to the kernel.
@@ -541,6 +627,14 @@ export interface CreateLayoutFacetInput {
     | readonly import("../../api/public-types.ts").WorkflowMetadataMarkup[]
     | null
     | undefined;
+  /**
+   * L7 Phase 2 — optional viewport culling hooks wired from the owning
+   * `DocumentRuntime`.  When supplied, `facet.setVisibleBlockRange` /
+   * `facet.requestViewportRefresh` delegate directly to these; when omitted
+   * (e.g. tests, inert facet, standalone use) both methods are no-ops.
+   */
+  setVisibleBlockRange?: (range: { start: number; end: number }) => void;
+  requestViewportRefresh?: () => void;
   /**
    * R3 — optional suggestions snapshot accessor.  Used by
    * `getAllScopeCardModels` to attach `SuggestionGroup` entries whose
@@ -593,6 +687,151 @@ export function createLayoutFacet(
   // Keep the handle alive; the facet instance lives as long as the runtime.
   void unsubscribeEngine;
 
+  // P8 — per-revision cache for getStoryBlocksForRegion.  Identity is
+  // preserved within a single graph revision so consumers can `===`-compare
+  // results across band renders, and the cache flushes whenever the engine
+  // produces a fresh page graph.
+  let regionBlocksCache: {
+    revision: number;
+    byKey: Map<string, readonly PublicRegionBlock[]>;
+  } = { revision: -1, byKey: new Map() };
+  // P8.2.1 — secondary cache keyed by header/footer story-target identity.
+  // A 38-page doc with one default header projects the story once instead of
+  // 38 times; per-page `PublicRegionBlock[]`s still differ (each carries the
+  // page's `pageIndex`), but the underlying `SurfaceBlockSnapshot[]` and
+  // every `blockSnapshot` reference are shared.  Busts together with
+  // `regionBlocksCache` on `graph.revision` change.
+  let storyProjectionCache: {
+    revision: number;
+    byKey: Map<string, readonly SurfaceBlockSnapshot[]>;
+  } = { revision: -1, byKey: new Map() };
+  // P8 — per-revision cache for getDocumentEndnoteBlocks (single key).
+  let endnoteBlocksCache: {
+    revision: number;
+    blocks: readonly PublicRegionBlock[] | null;
+  } = { revision: -1, blocks: null };
+
+  function resolveCanonicalDocument(): CanonicalDocumentEnvelope {
+    if (input.canonicalDocument) {
+      return input.canonicalDocument();
+    }
+    return getQueryInput().document;
+  }
+
+  /**
+   * Build the body story's `SurfaceBlockSnapshot[]` so body fragment
+   * `blockId`s can be resolved.  Cached against the canonical document
+   * identity to avoid re-walking the body on every region read.
+   */
+  let cachedBodySurface: {
+    document: CanonicalDocumentEnvelope;
+    blocks: readonly SurfaceBlockSnapshot[];
+  } | null = null;
+  function bodySurfaceBlocks(): readonly SurfaceBlockSnapshot[] {
+    const document = resolveCanonicalDocument();
+    if (cachedBodySurface && cachedBodySurface.document === document) {
+      return cachedBodySurface.blocks;
+    }
+    const surface = createEditorSurfaceSnapshot(
+      document,
+      createSelectionSnapshot(0, 0),
+      MAIN_STORY_TARGET,
+    );
+    cachedBodySurface = { document, blocks: surface.blocks };
+    return surface.blocks;
+  }
+
+  function findBodyBlockById(
+    blockId: string,
+  ): SurfaceBlockSnapshot | undefined {
+    return bodySurfaceBlocks().find((b) => b.blockId === blockId);
+  }
+
+  function getRegionBlocksCached(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    columnIndex: number | undefined,
+  ): readonly PublicRegionBlock[] {
+    const graph = currentGraph();
+    if (regionBlocksCache.revision !== graph.revision) {
+      regionBlocksCache = { revision: graph.revision, byKey: new Map() };
+      // P8.2.1 — bust the secondary story-projection cache in lock-step so
+      // shared `SurfaceBlockSnapshot`s never outlive their graph revision.
+      storyProjectionCache = { revision: graph.revision, byKey: new Map() };
+      // Body surface depends on the canonical document; the document
+      // identity check inside `bodySurfaceBlocks` keeps it warm across
+      // pure-layout invalidations (zoom, font, etc.).
+    }
+    const key = `${pageIndex}:${region}:${columnIndex ?? "_"}`;
+    const cached = regionBlocksCache.byKey.get(key);
+    if (cached) return cached;
+    const fresh = computeRegionBlocks(pageIndex, region, columnIndex, graph);
+    regionBlocksCache.byKey.set(key, fresh);
+    return fresh;
+  }
+
+  /**
+   * P8.2.1 — shared projection for a header/footer story.  Returns the same
+   * `SurfaceBlockSnapshot[]` array identity for repeated calls at the same
+   * revision so per-page `PublicRegionBlock[]`s can share every
+   * `blockSnapshot` reference.
+   */
+  function getStoryProjectionCached(
+    storyTarget: EditorStoryTarget,
+    document: CanonicalDocumentEnvelope,
+  ): readonly SurfaceBlockSnapshot[] {
+    const key = storyTargetKey(storyTarget);
+    const cached = storyProjectionCache.byKey.get(key);
+    if (cached) return cached;
+    const surface = createEditorSurfaceSnapshot(
+      document,
+      createSelectionSnapshot(0, 0),
+      storyTarget,
+    );
+    const fresh = surface.blocks;
+    storyProjectionCache.byKey.set(key, fresh);
+    return fresh;
+  }
+
+  function computeRegionBlocks(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    columnIndex: number | undefined,
+    graph: RuntimePageGraph,
+  ): readonly PublicRegionBlock[] {
+    const node = graph.pages[pageIndex];
+    if (!node) return Object.freeze([]);
+    const document = resolveCanonicalDocument();
+    if (region === "body") {
+      return resolveBodyRegionBlocks(node, graph, findBodyBlockById);
+    }
+    if (region === "header" || region === "footer") {
+      const story =
+        region === "header" ? node.stories.header : node.stories.footer;
+      if (!story) return Object.freeze([]);
+      // P8.2.1 — share the projected `SurfaceBlockSnapshot[]` across every
+      // page that renders the same story target.
+      const projectedBlocks = getStoryProjectionCached(story, document);
+      return resolveHeaderFooterRegionBlocks(
+        node.pageIndex,
+        region,
+        story,
+        projectedBlocks,
+      );
+    }
+    if (region === "footnote-area") {
+      return resolveFootnoteAreaRegionBlocks(node, document);
+    }
+    if (region === "column") {
+      // Multi-column body splitting is a P10 follow-up.  For now reuse
+      // the body fragments for the indexed column.
+      void columnIndex;
+      return resolveBodyRegionBlocks(node, graph, findBodyBlockById);
+    }
+    // endnote-area: empty per-page; document-end via getDocumentEndnoteBlocks.
+    return Object.freeze([]);
+  }
+
   return {
     getPageCount() {
       return currentGraph().pages.length;
@@ -732,6 +971,69 @@ export function createLayoutFacet(
       return result;
     },
 
+    getStoryBlocksForRegion(pageIndex, region, options) {
+      return getRegionBlocksCached(pageIndex, region, options?.columnIndex);
+    },
+
+    getDocumentEndnoteBlocks() {
+      const graph = currentGraph();
+      if (endnoteBlocksCache.revision === graph.revision && endnoteBlocksCache.blocks) {
+        return endnoteBlocksCache.blocks;
+      }
+      const document = resolveCanonicalDocument();
+      const collection = document.subParts?.footnoteCollection;
+      const blocks: PublicRegionBlock[] = [];
+      if (collection) {
+        // P8.2.1 — batch every endnote body into one
+        // `createEditorSurfaceSnapshot` call.  Previously we called the
+        // projector once per block (50 endnotes × 1 block → 50 full
+        // projections); now we project the flat concatenation once and
+        // slice the result back into per-note groups using the original
+        // block counts.  `runtimeFromOffset` / `runtimeToOffset` inherit
+        // the projection's cumulative cursor (a stable "all-endnotes"
+        // meta-story offset); fragment ids still scope per-note so
+        // consumers can tell which endnote a block belongs to.
+        const groups: Array<{ noteId: string; count: number }> = [];
+        const flat: import("../../model/canonical-document.ts").BlockNode[] = [];
+        for (const noteId of Object.keys(collection.endnotes)) {
+          const note = collection.endnotes[noteId];
+          if (!note || note.blocks.length === 0) continue;
+          groups.push({ noteId, count: note.blocks.length });
+          for (const block of note.blocks) flat.push(block);
+        }
+        if (flat.length > 0) {
+          const surface = createEditorSurfaceSnapshot(
+            {
+              ...document,
+              content: { type: "doc", children: flat },
+            } as CanonicalDocumentEnvelope,
+            createSelectionSnapshot(0, 0),
+          );
+          let cursor = 0;
+          for (const group of groups) {
+            for (let i = 0; i < group.count; i += 1) {
+              const blockSnapshot = surface.blocks[cursor + i];
+              if (!blockSnapshot) continue;
+              blocks.push({
+                blockId: blockSnapshot.blockId,
+                fragmentId: `endnote-${group.noteId}-${i}`,
+                pageIndex: -1,
+                regionKind: "endnote-area",
+                runtimeFromOffset: blockSnapshot.from,
+                runtimeToOffset: blockSnapshot.to,
+                heightTwips: 0,
+                blockSnapshot,
+              });
+            }
+            cursor += group.count;
+          }
+        }
+      }
+      const frozen = Object.freeze(blocks);
+      endnoteBlocksCache = { revision: graph.revision, blocks: frozen };
+      return frozen;
+    },
+
     getPageFormatCatalog() {
       return PAGE_FORMAT_CATALOG;
     },
@@ -950,6 +1252,15 @@ export function createLayoutFacet(
       };
     },
 
+    // L7 Phase 2 — viewport culling delegates
+    setVisibleBlockRange(range) {
+      input.setVisibleBlockRange?.(range);
+    },
+
+    requestViewportRefresh() {
+      input.requestViewportRefresh?.();
+    },
+
     subscribe(listener) {
       listeners.add(listener);
       return () => {
@@ -1005,6 +1316,9 @@ function toPublicPageRegions(regions: RuntimePageRegions): PublicPageRegions {
     ...(regions.header ? { header: toPublicPageRegion(regions.header) } : {}),
     ...(regions.footer ? { footer: toPublicPageRegion(regions.footer) } : {}),
     ...(regions.columns ? { columns: regions.columns.map(toPublicPageRegion) } : {}),
+    ...(regions.footnotes && regions.footnotes.length > 0
+      ? { footnotes: regions.footnotes.map(toPublicPageRegion) }
+      : {}),
   };
 }
 
@@ -1648,3 +1962,118 @@ function findCanonicalTableByBlockId(
   }
   return null;
 }
+
+// ---------------------------------------------------------------------------
+// P8 — region-block resolvers
+// ---------------------------------------------------------------------------
+
+function resolveBodyRegionBlocks(
+  node: RuntimePageNode,
+  graph: RuntimePageGraph,
+  findBodyBlockById: (blockId: string) => SurfaceBlockSnapshot | undefined,
+): readonly PublicRegionBlock[] {
+  const fragmentsById = new Map<string, RuntimeBlockFragment>();
+  for (const fragment of graph.fragments) {
+    fragmentsById.set(fragment.fragmentId, fragment);
+  }
+  const blocks: PublicRegionBlock[] = [];
+  for (const fragmentId of node.regions.body.fragmentIds) {
+    const fragment = fragmentsById.get(fragmentId);
+    if (!fragment) continue;
+    const blockSnapshot = findBodyBlockById(fragment.blockId);
+    if (!blockSnapshot) continue;
+    blocks.push({
+      blockId: fragment.blockId,
+      fragmentId,
+      pageIndex: node.pageIndex,
+      regionKind: "body",
+      runtimeFromOffset: fragment.from,
+      runtimeToOffset: fragment.to,
+      heightTwips: fragment.heightTwips,
+      blockSnapshot,
+    });
+  }
+  return Object.freeze(blocks);
+}
+
+function resolveHeaderFooterRegionBlocks(
+  pageIndex: number,
+  regionKind: "header" | "footer",
+  storyTarget: EditorStoryTarget,
+  projectedBlocks: readonly SurfaceBlockSnapshot[],
+): readonly PublicRegionBlock[] {
+  if (storyTarget.kind !== regionKind) return Object.freeze([]);
+  if (projectedBlocks.length === 0) return Object.freeze([]);
+  const fragmentBase = `story-${storyTarget.kind}-${storyTarget.relationshipId}-${storyTarget.variant}-${storyTarget.sectionIndex ?? "_"}`;
+  return Object.freeze(
+    projectedBlocks.map((blockSnapshot, index): PublicRegionBlock => ({
+      blockId: blockSnapshot.blockId,
+      fragmentId: `${fragmentBase}-${index}`,
+      pageIndex,
+      regionKind,
+      runtimeFromOffset: blockSnapshot.from,
+      runtimeToOffset: blockSnapshot.to,
+      // Header/footer fragments aren't measured per-block — consumers read
+      // the region's `heightTwips` from `getStoryRegionsOnPage`.
+      heightTwips: 0,
+      blockSnapshot,
+    })),
+  );
+}
+
+function resolveFootnoteAreaRegionBlocks(
+  node: RuntimePageNode,
+  document: CanonicalDocumentEnvelope,
+): readonly PublicRegionBlock[] {
+  const collection = document.subParts?.footnoteCollection;
+  if (!collection) return Object.freeze([]);
+  // P8.2.1 — batch every allocation's body into one
+  // `createEditorSurfaceSnapshot` call and slice the result back into
+  // per-allocation groups.  Amplification per-page is small (a handful of
+  // footnotes), but this mirrors the endnote batching so both paths take
+  // the same shape.  The existence guard on `note` is sufficient — the
+  // previous `void note;` marker is gone.
+  const groups: Array<{
+    allocation: RuntimeNoteAllocation;
+    count: number;
+  }> = [];
+  const flat: import("../../model/canonical-document.ts").BlockNode[] = [];
+  for (const allocation of node.noteAllocations) {
+    if (allocation.noteKind !== "footnote") continue;
+    const note = collection.footnotes[allocation.noteId];
+    if (!note || note.blocks.length === 0) continue;
+    groups.push({ allocation, count: note.blocks.length });
+    for (const block of note.blocks) flat.push(block);
+  }
+  if (flat.length === 0) return Object.freeze([]);
+  const surface = createEditorSurfaceSnapshot(
+    {
+      ...document,
+      content: { type: "doc", children: flat },
+    } as CanonicalDocumentEnvelope,
+    createSelectionSnapshot(0, 0),
+  );
+  const blocks: PublicRegionBlock[] = [];
+  let cursor = 0;
+  for (const group of groups) {
+    const fragmentBase = group.allocation.fragmentId
+      ?? `note-${node.pageIndex}-${group.allocation.noteId}`;
+    for (let i = 0; i < group.count; i += 1) {
+      const blockSnapshot = surface.blocks[cursor + i];
+      if (!blockSnapshot) continue;
+      blocks.push({
+        blockId: blockSnapshot.blockId,
+        fragmentId: `${fragmentBase}-${i}`,
+        pageIndex: node.pageIndex,
+        regionKind: "footnote-area",
+        runtimeFromOffset: blockSnapshot.from,
+        runtimeToOffset: blockSnapshot.to,
+        heightTwips: group.allocation.reservedHeightTwips,
+        blockSnapshot,
+      });
+    }
+    cursor += group.count;
+  }
+  return Object.freeze(blocks);
+}
+

package/src/runtime/perf-counters.ts

@@ -0,0 +1,28 @@
+/**
+ * Lightweight string-keyed counters for L7 render-perf instrumentation.
+ *
+ * Used by the runtime to prove (in tests and benchmarks) that a given
+ * facet rebuild ran or did not run during a sequence of operations.
+ * Phase 0 wires `refresh.all`; Phase 1 will add `facet.<name>.build`
+ * keyed on the per-facet builder.
+ *
+ * Cost guarantee: a `Map<string, number>` increment is < 100 ns. We do
+ * not need atomic counters — JS is single-threaded — and we deliberately
+ * keep the surface tiny so this module can never become a perf footgun
+ * on its own.
+ */
+export class PerfCounters {
+  private readonly counts = new Map<string, number>();
+
+  increment(key: string, delta = 1): void {
+    this.counts.set(key, (this.counts.get(key) ?? 0) + delta);
+  }
+
+  snapshot(): Record<string, number> {
+    return Object.fromEntries(this.counts);
+  }
+
+  reset(): void {
+    this.counts.clear();
+  }
+}

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

@@ -0,0 +1,29 @@
+import type { EditorSurfaceSnapshot } from "../../api/public-types";
+import type { RuntimePageGraph } from "../layout/page-graph.ts";
+
+/**
+ * L7 Phase 2.5 Task 2.5.3 — prerender cache envelope shape.
+ *
+ * The envelope is the unit written to IndexedDB (Plan A) and — after Plan B
+ * ships — to the `laycache` customXml editor-state namespace. Two consumers
+ * must agree on this shape: the prerender pipeline that populates it, and
+ * the warm-path loader that rehydrates it.
+ *
+ * Load-time invariants checked by consumers before trusting the envelope:
+ *   - `schemaVersion === LAYCACHE_SCHEMA_VERSION`  — bump invalidates
+ *   - `engineVersion === LAYOUT_ENGINE_VERSION`    — bump invalidates
+ *   - `graph.revision === 0`                       — canonical marker
+ *
+ * The envelope MUST be structured-clone-safe because IndexedDB and Plan B's
+ * customXml path both rely on structured-clone semantics. Keep fields as
+ * JSON-serializable primitives, plain objects, or arrays — no class
+ * instances, functions, or symbols.
+ */
+export interface CacheEnvelope {
+  readonly schemaVersion: number;
+  readonly engineVersion: number;
+  readonly fontFingerprint: string;
+  readonly structuralHash: string;
+  readonly graph: RuntimePageGraph;
+  readonly surface: EditorSurfaceSnapshot;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * L7 Phase 2.5 Task 2.5.1 — prerender cache-key derivation.
+ *
+ * The cache key is the composite identity the IndexedDB (Plan A) and
+ * customXml (Plan B) backends index on. It has five inputs:
+ *
+ *   1. structuralHash(blocks)  — sha256 of the ordered kind:blockId list.
+ *                                Stable across text-only edits; changes on
+ *                                insert/delete/reorder because blockIds are
+ *                                kind-counter pairs (paragraph-5 stays 5
+ *                                under typing, shifts to paragraph-6 after
+ *                                an insert).
+ *   2. fontFingerprint         — identifies the measurement-backend + font-
+ *                                metric source. "empirical-backend" in Plan A;
+ *                                a real font-derived string after Phase 8.
+ *   3. engineVersion           — LAYOUT_ENGINE_VERSION from src/runtime/
+ *                                layout/layout-engine-version.ts. Bumped by
+ *                                CI gate on any layout/render shape change.
+ *   4. schemaVersion           — LAYCACHE_SCHEMA_VERSION for envelope format.
+ *
+ * Returns a 64-char lower-case hex digest. Uses the Web Crypto API
+ * (globalThis.crypto.subtle), available in Node 18+ and all target browsers —
+ * keeping src/** free of node: builtins so the shipped browser bundle stays
+ * clean.
+ */
+export interface CacheKeyBlock {
+  readonly kind: string;
+  readonly blockId: string;
+}
+
+export interface CacheKeyInputs {
+  readonly blocks: readonly CacheKeyBlock[];
+  readonly fontFingerprint: string;
+  readonly engineVersion: string | number;
+  readonly schemaVersion: number;
+}
+
+const BLOCK_SEPARATOR = "\u0000";
+const FIELD_SEPARATOR = "|";
+const textEncoder = new TextEncoder();
+
+async function sha256Hex(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", textEncoder.encode(input));
+  const bytes = new Uint8Array(digest);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i]!.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+export async function computeStructuralHash(blocks: readonly CacheKeyBlock[]): Promise<string> {
+  const payload = blocks.map((block) => `${block.kind}:${block.blockId}`).join(BLOCK_SEPARATOR);
+  return sha256Hex(payload);
+}
+
+export async function deriveCacheKey(inputs: CacheKeyInputs): Promise<string> {
+  const structuralHash = await computeStructuralHash(inputs.blocks);
+  const composite = [
+    structuralHash,
+    inputs.fontFingerprint,
+    String(inputs.engineVersion),
+    String(inputs.schemaVersion),
+  ].join(FIELD_SEPARATOR);
+  return sha256Hex(composite);
+}

package/src/runtime/prerender/font-fingerprint.ts

@@ -0,0 +1,17 @@
+/**
+ * L7 Phase 2.5 Task 2.5.1 — font fingerprint stub for the prerender cache.
+ *
+ * The cache key composition includes a font fingerprint so cache entries
+ * invalidate when the set of fonts available to the measurement backend
+ * changes. In Plan A the prerender pipeline forces the empirical
+ * measurement backend (see `createLayoutEngine({ autoUpgradeToCanvasBackend:
+ * false })`), which is deterministic and font-metric-agnostic — so the
+ * fingerprint is a constant literal.
+ *
+ * Phase 8 (font-metrics precompute via fontkit) replaces this stub with a
+ * real font-derived fingerprint that makes Plan B customXml caches portable
+ * across machines with different installed fonts.
+ */
+export function resolveFontFingerprint(): string {
+  return "empirical-backend";
+}