@beyondwork/docx-react-component 1.0.43 → 1.0.45

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";
+}

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/selection/post-edit-validator.ts

@@ -0,0 +1,77 @@
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { SelectionSnapshot } from "../../core/state/editor-state.ts";
+
+/**
+ * Snap a selection to a valid position relative to the document.
+ *
+ * Pure function.  O(1) on the identity (in-bounds) fast path — returns
+ * the SAME object reference when no change is needed.  Callers should
+ * compare with `!==` to detect a snap (e.g. to decide whether to
+ * re-spread runtime state).
+ *
+ * Wired into the runtime snapshot-emit chokepoint
+ * (`applyTransactionToState` -> `cachedRenderSnapshot = refreshRenderSnapshot()`),
+ * so it runs once per transaction commit.  Must NOT walk the document;
+ * the caller is responsible for passing a valid `maxOffset` (the
+ * POST-mutation `surface.storySize`, primed via
+ * `getCachedSurface(state.document, activeStory).storySize`).
+ *
+ * NodeAnchor invalidation is deferred until CanonicalDocumentEnvelope
+ * grows an O(1) node-by-id accessor.  Until then, NodeAnchor selections
+ * are returned unchanged (identity).
+ *
+ * @param document   The post-mutation canonical document.  Currently
+ *                   unused except for the deferred NodeAnchor branch;
+ *                   the parameter is kept for API stability.
+ * @param selection  The selection to validate.
+ * @param maxOffset  The POST-mutation maximum story offset.  Caller
+ *                   passes `getCachedSurface(state.document,
+ *                   activeStory).storySize` (which primes the cache
+ *                   that `refreshRenderSnapshot` reuses on its next
+ *                   call — no extra surface walk).  The validator does
+ *                   NOT walk the document to compute this.  Do NOT pass
+ *                   the pre-mutation snapshot's storySize: at end-of-doc
+ *                   inserts, the new selection legitimately exceeds the
+ *                   old bound and the validator would clamp the caret
+ *                   backward by one position per keystroke.  Pass
+ *                   `Number.POSITIVE_INFINITY` to skip the upper-bound
+ *                   clamp.
+ */
+export function validateSelectionAgainstDocument(
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- reserved for deferred NodeAnchor lookup
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  maxOffset: number,
+): SelectionSnapshot {
+  if (selection.activeRange.kind === "node") {
+    // Deferred: NodeAnchor invalidation requires an O(1) node-by-id
+    // accessor on CanonicalDocumentEnvelope.  Until that lands, return
+    // identity so we never falsely invalidate a still-valid node anchor.
+    return selection;
+  }
+
+  const anchor = clamp(selection.anchor, 0, maxOffset);
+  const head = clamp(selection.head, 0, maxOffset);
+
+  if (anchor === selection.anchor && head === selection.head) {
+    // Identity fast path — no allocation, same reference returned.
+    return selection;
+  }
+
+  const range = { from: Math.min(anchor, head), to: Math.max(anchor, head) };
+  const assoc =
+    selection.activeRange.kind === "range"
+      ? selection.activeRange.assoc
+      : { start: 1 as const, end: 1 as const };
+
+  return {
+    anchor,
+    head,
+    isCollapsed: anchor === head,
+    activeRange: { kind: "range", range, assoc },
+  };
+}
+
+function clamp(n: number, lo: number, hi: number): number {
+  return n < lo ? lo : n > hi ? hi : n;
+}