@beyondwork/docx-react-component 1.0.42 → 1.0.45

package/src/runtime/prerender/graph-canonicalize.ts

@@ -0,0 +1,121 @@
+import type {
+  RuntimeBlockFragment,
+  RuntimePageAnchor,
+  RuntimePageGraph,
+  RuntimePageNode,
+  RuntimePageRegion,
+  RuntimePageRegions,
+} from "../layout/page-graph.ts";
+
+/**
+ * L7 Phase 2.5 Task 2.5.3 — graph canonicalization (determinism fix).
+ *
+ * `src/runtime/layout/page-graph.ts` increments a module-level
+ * `graphRevision` counter on every `buildPageGraph()` call and embeds it
+ * into `pageId = page-${revision}-${index}` and dependent
+ * `fragmentId = ${pageId}-<suffix>` strings. Two consecutive
+ * `prerenderDocument(buf)` calls in the same process would therefore emit
+ * different pageIds — the cacheBlob hash would flip on every call even
+ * though the document bytes were identical.
+ *
+ * This module rewrites all identifier strings to a canonical revision-free
+ * shape:
+ *   `page-${index}`                                   (canonical pageId)
+ *   `page-${index}-<suffix>`                          (canonical fragmentId)
+ *
+ * The live runtime's graphRevision contract stays intact — only the
+ * serialized cache envelope is canonicalized.
+ */
+
+const PAGE_PREFIX = "page-";
+
+export function canonicalizeGraph(graph: RuntimePageGraph): RuntimePageGraph {
+  // Build a map from live pageId → canonical pageId ("page-<index>").
+  const rename = new Map<string, string>();
+  for (const page of graph.pages) {
+    rename.set(page.pageId, `${PAGE_PREFIX}${page.pageIndex}`);
+  }
+
+  const rewriteId = (id: string): string => {
+    // pageIds map directly.
+    const direct = rename.get(id);
+    if (direct !== undefined) return direct;
+    // fragmentIds have shape `${livePageId}-<suffix>`; find the matching
+    // live prefix and swap it for the canonical pageId.
+    for (const [livePageId, canonPageId] of rename) {
+      if (id.startsWith(`${livePageId}-`)) {
+        return `${canonPageId}${id.slice(livePageId.length)}`;
+      }
+    }
+    return id;
+  };
+
+  const canonicalPages: RuntimePageNode[] = graph.pages.map((page) => ({
+    ...page,
+    pageId: rewriteId(page.pageId),
+    regions: rewriteRegions(page.regions, rewriteId),
+    lineBoxes: page.lineBoxes.map((line) => ({
+      ...line,
+      fragmentId: rewriteId(line.fragmentId),
+    })),
+    noteAllocations: page.noteAllocations.map((note) =>
+      note.fragmentId === undefined
+        ? note
+        : { ...note, fragmentId: rewriteId(note.fragmentId) },
+    ),
+  }));
+
+  const canonicalFragments: RuntimeBlockFragment[] = graph.fragments.map((fragment) => ({
+    ...fragment,
+    fragmentId: rewriteId(fragment.fragmentId),
+    pageId: rewriteId(fragment.pageId),
+  }));
+
+  const canonicalAnchors: RuntimePageAnchor[] = graph.anchors.map((anchor) => ({
+    ...anchor,
+    pageId: rewriteId(anchor.pageId),
+    fragmentId: anchor.fragmentId === undefined ? undefined : rewriteId(anchor.fragmentId),
+  }));
+
+  return {
+    ...graph,
+    revision: 0,
+    pages: canonicalPages,
+    fragments: canonicalFragments,
+    anchors: canonicalAnchors,
+  };
+}
+
+function rewriteRegions(
+  regions: RuntimePageRegions,
+  rewriteId: (id: string) => string,
+): RuntimePageRegions {
+  const result: {
+    body: RuntimePageRegion;
+    header?: RuntimePageRegion;
+    footer?: RuntimePageRegion;
+    columns?: RuntimePageRegion[];
+    footnotes?: RuntimePageRegion[];
+  } = {
+    body: rewriteRegion(regions.body, rewriteId),
+  };
+  if (regions.header !== undefined) result.header = rewriteRegion(regions.header, rewriteId);
+  if (regions.footer !== undefined) result.footer = rewriteRegion(regions.footer, rewriteId);
+  if (regions.columns !== undefined) {
+    result.columns = regions.columns.map((region) => rewriteRegion(region, rewriteId));
+  }
+  if (regions.footnotes !== undefined) {
+    result.footnotes = regions.footnotes.map((region) => rewriteRegion(region, rewriteId));
+  }
+  return result;
+}
+
+function rewriteRegion(
+  region: RuntimePageRegion,
+  rewriteId: (id: string) => string,
+): RuntimePageRegion {
+  return {
+    ...region,
+    fragmentIds: region.fragmentIds.map(rewriteId),
+  };
+}

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

@@ -0,0 +1,184 @@
+/**
+ * L7 Phase 2.5 Task 2.5.2 — IndexedDB cache backend (Plan A).
+ *
+ * Validation-stage storage for the prerender cache. Stores the cache
+ * envelope (see cache-envelope.ts in Task 2.5.3) keyed by the SHA-256
+ * cacheKey from cache-key.ts. LRU eviction caps the store at
+ * LAYCACHE_MAX_ENTRIES so the cache never unbounds.
+ *
+ * Uses the Web IndexedDB API directly — no idb wrapper, keeping this
+ * module dependency-free. Tests use `fake-indexeddb/auto` which installs
+ * a spec-compliant in-memory IDB on globalThis.
+ *
+ * Plan B (customXml persistence) will layer on top of this: customXml is
+ * consulted first, IndexedDB second. For Plan A, this is the only backend.
+ */
+
+const DB_NAME = "beyondwork-laycache";
+const DB_VERSION = 1;
+const STORE_NAME = "envelopes";
+const ACCESSED_AT_INDEX = "accessedAt";
+
+export const LAYCACHE_MAX_ENTRIES = 100;
+
+interface CacheRecord<T> {
+  readonly cacheKey: string;
+  readonly envelope: T;
+  readonly accessedAt: number;
+}
+
+let dbPromise: Promise<IDBDatabase> | null = null;
+
+/**
+ * Monotonic "logical timestamp" for LRU ordering. `Date.now()` returns the
+ * same millisecond for writes issued in rapid succession (common in tests
+ * and in our own LRU-eviction scan), which makes cursor-based eviction
+ * non-deterministic when entries collide. A process-lifetime counter
+ * produces strictly increasing values regardless of wall-clock resolution.
+ * Persisted across DB opens: the store's max stored `accessedAt` seeds the
+ * counter on first open so a reopen still respects prior recency order.
+ */
+let accessedAtCounter = 0;
+
+function nextAccessedAt(): number {
+  accessedAtCounter += 1;
+  return accessedAtCounter;
+}
+
+function requestIndexedDB(): IDBFactory {
+  const factory = (globalThis as { indexedDB?: IDBFactory }).indexedDB;
+  if (!factory) {
+    throw new Error(
+      "indexeddb-cache: globalThis.indexedDB is undefined. In tests, import 'fake-indexeddb/auto'.",
+    );
+  }
+  return factory;
+}
+
+function promisifyRequest<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("indexeddb-cache: request failed"));
+  });
+}
+
+function promisifyTransaction(tx: IDBTransaction): Promise<void> {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error ?? new Error("indexeddb-cache: transaction failed"));
+    tx.onabort = () => reject(tx.error ?? new Error("indexeddb-cache: transaction aborted"));
+  });
+}
+
+function openDatabase(): Promise<IDBDatabase> {
+  if (dbPromise !== null) return dbPromise;
+  dbPromise = new Promise((resolve, reject) => {
+    const request = requestIndexedDB().open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        const store = db.createObjectStore(STORE_NAME, { keyPath: "cacheKey" });
+        store.createIndex(ACCESSED_AT_INDEX, "accessedAt", { unique: false });
+      }
+    };
+    request.onsuccess = () => {
+      const db = request.result;
+      void seedCounterFromStore(db).then(() => resolve(db));
+    };
+    request.onerror = () => reject(request.error ?? new Error("indexeddb-cache: open failed"));
+  });
+  return dbPromise;
+}
+
+async function seedCounterFromStore(db: IDBDatabase): Promise<void> {
+  // On first open, initialise the counter from the highest persisted
+  // `accessedAt`. On subsequent opens inside the same process we keep the
+  // existing counter — it's already ahead of anything in the store.
+  if (accessedAtCounter > 0) return;
+  const tx = db.transaction(STORE_NAME, "readonly");
+  const index = tx.objectStore(STORE_NAME).index(ACCESSED_AT_INDEX);
+  const request = index.openCursor(null, "prev");
+  await new Promise<void>((resolve, reject) => {
+    request.onsuccess = () => {
+      const cursor = request.result;
+      if (cursor) {
+        const value = cursor.value as CacheRecord<unknown>;
+        if (typeof value.accessedAt === "number" && value.accessedAt > accessedAtCounter) {
+          accessedAtCounter = value.accessedAt;
+        }
+      }
+      resolve();
+    };
+    request.onerror = () =>
+      reject(request.error ?? new Error("indexeddb-cache: seedCounterFromStore failed"));
+  });
+}
+
+export async function readCache<T>(cacheKey: string): Promise<T | null> {
+  const db = await openDatabase();
+  const tx = db.transaction(STORE_NAME, "readwrite");
+  const store = tx.objectStore(STORE_NAME);
+  const existing = (await promisifyRequest(store.get(cacheKey))) as CacheRecord<T> | undefined;
+  if (!existing) {
+    await promisifyTransaction(tx);
+    return null;
+  }
+  const touched: CacheRecord<T> = { ...existing, accessedAt: nextAccessedAt() };
+  store.put(touched);
+  await promisifyTransaction(tx);
+  return existing.envelope;
+}
+
+export async function writeCache<T>(cacheKey: string, envelope: T): Promise<void> {
+  const db = await openDatabase();
+  const tx = db.transaction(STORE_NAME, "readwrite");
+  const store = tx.objectStore(STORE_NAME);
+  const record: CacheRecord<T> = { cacheKey, envelope, accessedAt: nextAccessedAt() };
+  store.put(record);
+  const count = await promisifyRequest(store.count());
+  if (count > LAYCACHE_MAX_ENTRIES) {
+    const toDrop = count - LAYCACHE_MAX_ENTRIES;
+    await evictOldest(store, toDrop);
+  }
+  await promisifyTransaction(tx);
+}
+
+async function evictOldest(store: IDBObjectStore, count: number): Promise<void> {
+  if (count <= 0) return;
+  const index = store.index(ACCESSED_AT_INDEX);
+  let remaining = count;
+  await new Promise<void>((resolve, reject) => {
+    const request = index.openCursor();
+    request.onsuccess = () => {
+      const cursor = request.result;
+      if (!cursor || remaining === 0) {
+        resolve();
+        return;
+      }
+      cursor.delete();
+      remaining -= 1;
+      cursor.continue();
+    };
+    request.onerror = () =>
+      reject(request.error ?? new Error("indexeddb-cache: eviction cursor failed"));
+  });
+}
+
+export async function clearCache(): Promise<void> {
+  const db = await openDatabase();
+  const tx = db.transaction(STORE_NAME, "readwrite");
+  tx.objectStore(STORE_NAME).clear();
+  await promisifyTransaction(tx);
+}
+
+/**
+ * Close the cached connection. Used by tests to tear down between cases so
+ * the singleton dbPromise does not leak state across runs. Production code
+ * can ignore this — the connection is process-scoped and lives until exit.
+ */
+export async function closeCacheDatabase(): Promise<void> {
+  if (dbPromise === null) return;
+  const db = await dbPromise;
+  db.close();
+  dbPromise = null;
+}

package/src/runtime/prerender/prerender-document.ts

@@ -0,0 +1,145 @@
+import type { EditorSurfaceSnapshot } from "../../api/public-types";
+import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
+import { loadDocxEditorSessionAsync } from "../../io/docx-session.ts";
+import { createLoadScheduler } from "../../io/load-scheduler.ts";
+import {
+  LAYCACHE_SCHEMA_VERSION,
+  LAYOUT_ENGINE_VERSION,
+} from "../layout/layout-engine-version.ts";
+import { createLayoutEngine } from "../layout/layout-engine-instance.ts";
+import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
+import type { CacheEnvelope } from "./cache-envelope.ts";
+import {
+  computeStructuralHash,
+  deriveCacheKey,
+  type CacheKeyBlock,
+} from "./cache-key.ts";
+import { resolveFontFingerprint } from "./font-fingerprint.ts";
+import { canonicalizeGraph } from "./graph-canonicalize.ts";
+
+/**
+ * L7 Phase 2.5 Task 2.5.3 — prerenderDocument public API.
+ *
+ * Runs the parse + layout pipeline for a .docx buffer without mounting
+ * React, PM, or any DOM. Produces a CacheEnvelope suitable for writing to
+ * the IndexedDB backend (Plan A) or the `laycache` customXml namespace
+ * (Plan B, follow-up PR).
+ *
+ * Determinism contract:
+ *   - Identical input bytes produce identical cacheKey on two sequential
+ *     calls. Two sources of non-determinism are handled:
+ *       (1) `page-graph.ts` graphRevision counter — stripped by
+ *           `canonicalizeGraph`.
+ *       (2) A fixed `documentId` ("prerender") is passed to the loader so
+ *           `createCanonicalDocumentId` is deterministic. Timestamps in
+ *           `canonicalDocument.createdAt/updatedAt` are loader-controlled
+ *           but do not enter the envelope.
+ *
+ * Node-safety:
+ *   - Uses `createLoadScheduler({ backendOverride: "sync" })` so the
+ *     async loader runs without DOM scheduler.yield.
+ *   - Layout engine is constructed with
+ *     `autoUpgradeToCanvasBackend: false` so the empirical measurement
+ *     backend is used (no Canvas2D, no node-canvas).
+ */
+
+export interface PrerenderOptions {
+  readonly fontFingerprint?: string;
+  /**
+   * Plan B hook — when true, prerenderDocument will inject the cache
+   * envelope into the document's `laycache` customXml namespace and
+   * return the re-serialized bytes in `docWithCustomXml`. In Plan A
+   * (this task) the flag is accepted for API stability but ignored;
+   * `docWithCustomXml` returns the input unchanged.
+   */
+  readonly persistToCustomXml?: boolean;
+}
+
+export interface PrerenderCounters {
+  readonly blockCount: number;
+  readonly pageCount: number;
+  readonly prerenderMs: number;
+}
+
+export interface PrerenderResult {
+  readonly docWithCustomXml: Uint8Array;
+  readonly cacheBlob: CacheEnvelope;
+  readonly cacheKey: string;
+  readonly counters: PrerenderCounters;
+}
+
+const PRERENDER_DOCUMENT_ID = "prerender";
+
+function toUint8Array(input: ArrayBuffer | Uint8Array): Uint8Array {
+  if (input instanceof Uint8Array) return input;
+  return new Uint8Array(input);
+}
+
+function blocksToCacheKeyBlocks(surface: EditorSurfaceSnapshot): CacheKeyBlock[] {
+  return surface.blocks.map((block) => ({ kind: block.kind, blockId: block.blockId }));
+}
+
+export async function prerenderDocument(
+  input: ArrayBuffer | Uint8Array,
+  options: PrerenderOptions = {},
+): Promise<PrerenderResult> {
+  const t0 = performance.now();
+  const bytes = toUint8Array(input);
+  const fontFingerprint = options.fontFingerprint ?? resolveFontFingerprint();
+
+  const scheduler = createLoadScheduler({ backendOverride: "sync" });
+  let session;
+  try {
+    session = await loadDocxEditorSessionAsync({
+      documentId: PRERENDER_DOCUMENT_ID,
+      bytes,
+      editorBuild: "prerender",
+      scheduler,
+    });
+  } finally {
+    scheduler.dispose();
+  }
+
+  if (session.fatalError) {
+    throw new Error(
+      `prerenderDocument: failed to load input — ${session.fatalError.message ?? "fatal error"}`,
+    );
+  }
+
+  const envelope = session.initialSessionState.canonicalDocument;
+  const surface = createEditorSurfaceSnapshot(envelope, createSelectionSnapshot(), { kind: "main" });
+
+  const engine = createLayoutEngine({ autoUpgradeToCanvasBackend: false });
+  const rawGraph = engine.getPageGraph({ document: envelope });
+  const graph = canonicalizeGraph(rawGraph);
+
+  const structuralHash = await computeStructuralHash(blocksToCacheKeyBlocks(surface));
+  const cacheKey = await deriveCacheKey({
+    blocks: blocksToCacheKeyBlocks(surface),
+    fontFingerprint,
+    engineVersion: LAYOUT_ENGINE_VERSION,
+    schemaVersion: LAYCACHE_SCHEMA_VERSION,
+  });
+
+  const cacheBlob: CacheEnvelope = {
+    schemaVersion: LAYCACHE_SCHEMA_VERSION,
+    engineVersion: LAYOUT_ENGINE_VERSION,
+    fontFingerprint,
+    structuralHash,
+    graph,
+    surface,
+  };
+
+  const prerenderMs = performance.now() - t0;
+
+  return {
+    docWithCustomXml: bytes,
+    cacheBlob,
+    cacheKey,
+    counters: {
+      blockCount: surface.blocks.length,
+      pageCount: graph.pages.length,
+      prerenderMs,
+    },
+  };
+}

package/src/runtime/render/block-fragment-projection.ts

@@ -10,6 +10,7 @@
  * emitted by `src/runtime/surface-projection.ts`:
  *   - `paragraph-*`  → "paragraph"
  *   - `table-*`      → "table"
+ *   - `placeholder-culled-*` → "opaque" (viewport-culled size-preserving stub)
  *   - `opaque-*`     → "opaque"
  *   - `section-break-*` → "opaque" (read-only boundary marker)
  *   - `sdt-*`, `sdt-wrapper-*` → "opaque"
@@ -25,6 +26,7 @@ import type { RenderBlock } from "./render-frame-types.ts";
 export function classifyBlockKind(blockId: string): RenderBlock["kind"] {
   if (blockId.startsWith("paragraph")) return "paragraph";
   if (blockId.startsWith("table")) return "table";
+  if (blockId.startsWith("placeholder-culled-")) return "opaque";
   if (blockId.startsWith("opaque")) return "opaque";
   if (blockId.startsWith("section-break")) return "opaque";
   if (blockId.startsWith("sdt")) return "opaque";

package/src/runtime/render/render-frame-types.ts

@@ -56,6 +56,23 @@ export interface RenderPageRegions {
   footer?: RenderStoryRegion;
   columns?: readonly RenderStoryRegion[];
   footnoteArea?: RenderStoryRegion;
+  /**
+   * P8.3 — footnote areas reserved at the bottom of the page (above the
+   * footer band). Mirrors the page graph's `RuntimePageRegions.footnotes`
+   * — one entry per allocated region (typically one per page today, but
+   * shape allows for multiple should allocation-splitting land).
+   * Populated only when `PublicPageRegions.footnotes` is non-empty.
+   * Additive — back-compat safe; consumers that ignore this field see no
+   * change.
+   */
+  footnotes?: readonly RenderStoryRegion[];
+  /**
+   * P8.3 — endnote regions. Reserved seam; per-page endnote projection is
+   * NOT populated today (endnotes use document-end placement via
+   * `facet.getDocumentEndnoteBlocks()`). Shape exists so a future
+   * per-section endnote renderer has a stable read surface.
+   */
+  endnotes?: readonly RenderStoryRegion[];
 }
 
 export interface RenderStoryRegion {