@beyondwork/docx-react-component 1.0.43 → 1.0.46

package/src/runtime/edit-dispatch/list-aware-dispatch.ts

@@ -0,0 +1,125 @@
+import type {
+  EditorSessionState,
+  EditorStoryTarget,
+  RuntimeRenderSnapshot,
+  SelectionSnapshot as PublicSelectionSnapshot,
+  SurfaceBlockSnapshot,
+} from "../../api/public-types";
+import { type SelectionSnapshot as InternalSelectionSnapshot } from "../../core/state/editor-state.ts";
+import {
+  backspaceAtListStart,
+  indentListItems,
+  outdentListItems,
+  splitListParagraph,
+} from "../../core/commands/list-commands.ts";
+
+export type DispatchTextCommand =
+  | { type: "insert-text"; text: string }
+  | { type: "delete-backward" }
+  | { type: "delete-forward" }
+  | { type: "insert-tab" }
+  | { type: "outdent-tab" }
+  | { type: "insert-hard-break" }
+  | { type: "split-paragraph" };
+
+export interface ListAwareParagraphContext {
+  paragraphIndex: number;
+  paragraph: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>;
+  atParagraphStart: boolean;
+  isEmpty: boolean;
+}
+
+export interface StoryMutationContext {
+  timestamp: string;
+  activeStory: EditorStoryTarget;
+  persistedDocument: EditorSessionState["canonicalDocument"];
+  localDocument: EditorSessionState["canonicalDocument"];
+  localSnapshot: RuntimeRenderSnapshot;
+}
+
+export interface ListAwareMutationResult {
+  changed: boolean;
+  document: EditorSessionState["canonicalDocument"];
+  selection: InternalSelectionSnapshot;
+}
+
+export interface ListAwareDispatchDeps {
+  resolveActiveParagraphContext(
+    snapshot: Pick<RuntimeRenderSnapshot, "surface" | "selection">,
+  ): ListAwareParagraphContext | null;
+  toRuntimeSelectionSnapshot(selection: PublicSelectionSnapshot): InternalSelectionSnapshot;
+}
+
+export function applyListAwareTextCommand(
+  context: StoryMutationContext,
+  command: DispatchTextCommand,
+  deps: ListAwareDispatchDeps,
+): ListAwareMutationResult | null {
+  const paragraphContext = deps.resolveActiveParagraphContext(context.localSnapshot);
+  if (!paragraphContext?.paragraph.numbering) {
+    return null;
+  }
+
+  switch (command.type) {
+    case "insert-tab": {
+      const result = indentListItems(
+        context.localDocument,
+        [paragraphContext.paragraphIndex],
+        { timestamp: context.timestamp },
+      );
+      return createListMutationResult(result, context.localSnapshot.selection, deps);
+    }
+    case "outdent-tab": {
+      const result = outdentListItems(
+        context.localDocument,
+        [paragraphContext.paragraphIndex],
+        { timestamp: context.timestamp },
+      );
+      return createListMutationResult(result, context.localSnapshot.selection, deps);
+    }
+    case "delete-backward": {
+      if (!paragraphContext.atParagraphStart || !context.localSnapshot.selection.isCollapsed) {
+        return null;
+      }
+      const result = backspaceAtListStart(
+        context.localDocument,
+        paragraphContext.paragraphIndex,
+        { timestamp: context.timestamp },
+      );
+      return result.handled
+        ? createListMutationResult(result, context.localSnapshot.selection, deps)
+        : null;
+    }
+    case "split-paragraph": {
+      if (!context.localSnapshot.selection.isCollapsed || !paragraphContext.isEmpty) {
+        return null;
+      }
+      const result = splitListParagraph(
+        context.localDocument,
+        paragraphContext.paragraphIndex,
+        true,
+        { timestamp: context.timestamp },
+      );
+      return result.action === "split"
+        ? null
+        : createListMutationResult(result, context.localSnapshot.selection, deps);
+    }
+    default:
+      return null;
+  }
+}
+
+function createListMutationResult(
+  result: {
+    document: EditorSessionState["canonicalDocument"];
+    affectedParagraphIndexes: number[];
+  },
+  selection: RuntimeRenderSnapshot["selection"],
+  deps: ListAwareDispatchDeps,
+): ListAwareMutationResult {
+  return {
+    changed: result.affectedParagraphIndexes.length > 0,
+    document: result.document,
+    selection: deps.toRuntimeSelectionSnapshot(selection),
+  };
+}

package/src/runtime/editor-surface/capabilities.ts

@@ -0,0 +1,411 @@
+/**
+ * Editor capability table — the single source of truth for every
+ * keyboard shortcut, context-menu action, and surface dispatch the
+ * mounted editor knows about.
+ *
+ * An `EditorCapability` classifies a binding into one of four kinds:
+ *   - `supported`      — the editor owns the mutation (runtime command
+ *                        or shell op).
+ *   - `host-delegated` — the editor recognizes the input but hands it
+ *                        off to the host via a typed callback prop.
+ *                        Host event name lives in `hostEvent`.
+ *   - `blocked`        — the editor explicitly rejects the input. The
+ *                        host sees a `command_blocked` event with the
+ *                        `blockReason.code` and `blockReason.message`.
+ *   - `passthrough`    — the editor does not intercept; the browser
+ *                        default behavior wins.
+ *
+ * This table is consumed by:
+ *   - `src/ui/runtime-shortcut-dispatch.ts` (I3 C.2) — each resolution
+ *     branch looks up by id rather than hard-coding block reasons.
+ *   - `docs/reference/editor-capabilities.md` (I3 C.4) — generated
+ *     from this table so the wiki + reference doc stay in sync.
+ *   - `src/ui/WordReviewEditor.tsx` (I3 C.3) — `host-delegated`
+ *     entries wire their `hostEvent` to the matching prop on
+ *     `WordReviewEditorProps`.
+ *
+ * C.1 (this file): enumerate every shortcut already present in
+ * `resolveShellShortcut` / `resolveSurfaceShortcut` / the PM
+ * Alt+Shift+arrow bindings. No behavior change — C.2 is the
+ * dispatcher refactor.
+ *
+ * Scope: keyboard shortcuts only in C.1. Context-menu capabilities
+ * land alongside the right-click hook (Phase F) in a later commit.
+ */
+
+export type CapabilityKind = "supported" | "host-delegated" | "blocked" | "passthrough";
+
+export type CapabilityCategory =
+  | "text-formatting"
+  | "paragraph-formatting"
+  | "navigation"
+  | "selection"
+  | "clipboard"
+  | "history"
+  | "tracked-changes"
+  | "comments"
+  | "structure"
+  | "system";
+
+export interface CapabilityShortcut {
+  /** Canonical Windows / Linux binding string (e.g. "Ctrl+B", "Shift+Tab"). */
+  winLinux: string;
+  /** Canonical Mac binding string (e.g. "Cmd+B", "Shift+Tab"). */
+  mac: string;
+}
+
+export interface CapabilityBlockReason {
+  code: string;
+  message: string;
+}
+
+export interface EditorCapability {
+  /** Stable symbolic identifier. Used for lookup + wire-format. */
+  id: string;
+  kind: CapabilityKind;
+  category: CapabilityCategory;
+  /** Human-readable description for docs + a11y help. */
+  label: string;
+  /** Present when the capability is keyboard-triggered. */
+  shortcut?: CapabilityShortcut;
+  /** For `host-delegated`: the `WordReviewEditorProps` callback name. */
+  hostEvent?: string;
+  /** For `blocked`: the reason returned in the `command_blocked` event. */
+  blockReason?: CapabilityBlockReason;
+}
+
+const UNSUPPORTED_SURFACE = "unsupported_surface";
+
+export const EDITOR_CAPABILITIES: readonly EditorCapability[] = [
+  // ---------------------------------------------------------------
+  // System — shell-level UX affordances
+  // ---------------------------------------------------------------
+  {
+    id: "shell.focus-region",
+    kind: "supported",
+    category: "system",
+    label: "Cycle focus between editor regions",
+    shortcut: { winLinux: "F6", mac: "F6" },
+  },
+  {
+    id: "shell.dismiss-selection-toolbar",
+    kind: "supported",
+    category: "system",
+    label: "Dismiss the selection toolbar",
+    shortcut: { winLinux: "Escape", mac: "Escape" },
+  },
+
+  // ---------------------------------------------------------------
+  // History
+  // ---------------------------------------------------------------
+  {
+    id: "history.undo",
+    kind: "supported",
+    category: "history",
+    label: "Undo",
+    shortcut: { winLinux: "Ctrl+Z", mac: "Cmd+Z" },
+  },
+  {
+    id: "history.redo",
+    kind: "supported",
+    category: "history",
+    label: "Redo",
+    shortcut: { winLinux: "Ctrl+Y", mac: "Cmd+Shift+Z" },
+  },
+
+  // ---------------------------------------------------------------
+  // Text formatting — shell-dispatched marks
+  // ---------------------------------------------------------------
+  {
+    id: "mark.toggle-bold",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Toggle bold",
+    shortcut: { winLinux: "Ctrl+B", mac: "Cmd+B" },
+  },
+  {
+    id: "mark.toggle-italic",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Toggle italic",
+    shortcut: { winLinux: "Ctrl+I", mac: "Cmd+I" },
+  },
+  {
+    id: "mark.toggle-underline",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Toggle underline",
+    shortcut: { winLinux: "Ctrl+U", mac: "Cmd+U" },
+  },
+
+  // ---------------------------------------------------------------
+  // Comments
+  // ---------------------------------------------------------------
+  {
+    id: "comment.add",
+    kind: "supported",
+    category: "comments",
+    label: "Insert comment at selection",
+    shortcut: { winLinux: "Ctrl+Alt+M", mac: "Cmd+Option+A" },
+  },
+
+  // ---------------------------------------------------------------
+  // Paragraph-formatting — heading levels
+  // ---------------------------------------------------------------
+  {
+    id: "heading.set-level-1",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Apply Heading 1 style",
+    shortcut: { winLinux: "Ctrl+Alt+1", mac: "Cmd+Option+1" },
+  },
+  {
+    id: "heading.set-level-2",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Apply Heading 2 style",
+    shortcut: { winLinux: "Ctrl+Alt+2", mac: "Cmd+Option+2" },
+  },
+  {
+    id: "heading.set-level-3",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Apply Heading 3 style",
+    shortcut: { winLinux: "Ctrl+Alt+3", mac: "Cmd+Option+3" },
+  },
+
+  // ---------------------------------------------------------------
+  // Surface-dispatched text commands (PM-focus path)
+  // ---------------------------------------------------------------
+  {
+    id: "text.delete-backward",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Delete character before the cursor",
+    shortcut: { winLinux: "Backspace", mac: "Backspace" },
+  },
+  {
+    id: "text.delete-forward",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Delete character after the cursor",
+    shortcut: { winLinux: "Delete", mac: "Delete" },
+  },
+  {
+    id: "paragraph.split",
+    kind: "supported",
+    category: "structure",
+    label: "Split paragraph at cursor",
+    shortcut: { winLinux: "Enter", mac: "Enter" },
+  },
+  {
+    id: "text.insert-hard-break",
+    kind: "supported",
+    category: "structure",
+    label: "Insert hard line break",
+    shortcut: { winLinux: "Shift+Enter", mac: "Shift+Enter" },
+  },
+  {
+    id: "text.insert-tab",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Indent list item; in table, move to next cell; otherwise insert tab",
+    shortcut: { winLinux: "Tab", mac: "Tab" },
+  },
+  {
+    id: "text.outdent-tab",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Outdent list item or paragraph; in table, move to previous cell",
+    shortcut: { winLinux: "Shift+Tab", mac: "Shift+Tab" },
+  },
+  {
+    id: "list.indent",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Indent current list item (Word Alt+Shift binding)",
+    shortcut: { winLinux: "Alt+Shift+Right", mac: "Option+Shift+Right" },
+  },
+  {
+    id: "list.outdent",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Outdent current list item (Word Alt+Shift binding)",
+    shortcut: { winLinux: "Alt+Shift+Left", mac: "Option+Shift+Left" },
+  },
+  {
+    id: "table.navigate-cell",
+    kind: "supported",
+    category: "navigation",
+    label: "Move to next / previous table cell (Tab / Shift+Tab while inside a table)",
+    shortcut: { winLinux: "Tab", mac: "Tab" },
+  },
+
+  // ---------------------------------------------------------------
+  // Clipboard — force-plain-text shortcut
+  //
+  // Ctrl/Cmd+Shift+V resolves to `{kind: "none"}` at the shell layer
+  // and falls through to the browser's native paste flow, which PM's
+  // handlePaste routes through the same plain-text path as Ctrl/Cmd+V.
+  // Classified as `passthrough` here: we recognize the shortcut but
+  // don't intercept — the browser + PM surface handle it.
+  // ---------------------------------------------------------------
+  {
+    id: "clipboard.paste-plain-text",
+    kind: "passthrough",
+    category: "clipboard",
+    label: "Paste as plain text (today identical to Ctrl/Cmd+V — force-plain-text semantics land with Tier B rich paste)",
+    shortcut: { winLinux: "Ctrl+Shift+V", mac: "Cmd+Shift+V" },
+  },
+
+  // ---------------------------------------------------------------
+  // Host-delegated — browser-owned gestures
+  // ---------------------------------------------------------------
+  {
+    id: "shortcut.find",
+    kind: "host-delegated",
+    category: "navigation",
+    label: "Find in document",
+    shortcut: { winLinux: "Ctrl+F", mac: "Cmd+F" },
+    hostEvent: "onFindRequested",
+  },
+  {
+    id: "shortcut.print",
+    kind: "host-delegated",
+    category: "system",
+    label: "Print document",
+    shortcut: { winLinux: "Ctrl+P", mac: "Cmd+P" },
+    hostEvent: "onPrintRequested",
+  },
+  {
+    id: "shortcut.zoom-in",
+    kind: "host-delegated",
+    category: "system",
+    label: "Zoom in",
+    shortcut: { winLinux: "Ctrl+Plus", mac: "Cmd+Plus" },
+    hostEvent: "onZoomRequested",
+  },
+  {
+    id: "shortcut.zoom-out",
+    kind: "host-delegated",
+    category: "system",
+    label: "Zoom out",
+    shortcut: { winLinux: "Ctrl+Minus", mac: "Cmd+Minus" },
+    hostEvent: "onZoomRequested",
+  },
+  {
+    id: "shortcut.zoom-reset",
+    kind: "host-delegated",
+    category: "system",
+    label: "Reset zoom",
+    shortcut: { winLinux: "Ctrl+0", mac: "Cmd+0" },
+    hostEvent: "onZoomRequested",
+  },
+
+  // ---------------------------------------------------------------
+  // Blocked — Word shortcuts the mounted editor does not implement
+  // ---------------------------------------------------------------
+  {
+    id: "replaceText",
+    kind: "blocked",
+    category: "navigation",
+    label: "Find and replace",
+    shortcut: { winLinux: "Ctrl+H", mac: "Ctrl+H" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Replace shortcuts are not supported in the mounted editor yet.",
+    },
+  },
+  {
+    id: "goTo",
+    kind: "blocked",
+    category: "navigation",
+    label: "Go to",
+    shortcut: { winLinux: "Ctrl+G", mac: "Cmd+Option+G" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Go To shortcuts are not supported in the mounted editor yet.",
+    },
+  },
+  {
+    id: "toggleTrackChanges",
+    kind: "blocked",
+    category: "tracked-changes",
+    label: "Toggle track-changes authoring mode",
+    shortcut: { winLinux: "Ctrl+Shift+E", mac: "Cmd+Shift+E" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Track changes authoring shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "checkSpelling",
+    kind: "blocked",
+    category: "system",
+    label: "Check spelling",
+    shortcut: { winLinux: "F7", mac: "F7" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Spelling shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "openThesaurus",
+    kind: "blocked",
+    category: "system",
+    label: "Open thesaurus",
+    shortcut: { winLinux: "Shift+F7", mac: "Shift+F7" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Thesaurus shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "extendSelection",
+    kind: "blocked",
+    category: "selection",
+    label: "Extend-selection mode",
+    shortcut: { winLinux: "F8", mac: "F8" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Extend-selection shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "lastEdit",
+    kind: "blocked",
+    category: "navigation",
+    label: "Return to last edit",
+    shortcut: { winLinux: "Shift+F5", mac: "Shift+F5" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Last-edit shortcuts are not supported in the mounted editor.",
+    },
+  },
+];
+
+/**
+ * O(1) lookup by capability id. Derived from `EDITOR_CAPABILITIES`
+ * at module-load; freezes the map so accidental mutation throws.
+ */
+export const CAPABILITY_BY_ID: ReadonlyMap<string, EditorCapability> = (() => {
+  const map = new Map<string, EditorCapability>();
+  for (const cap of EDITOR_CAPABILITIES) {
+    map.set(cap.id, cap);
+  }
+  return map;
+})();
+
+/** Return every capability in the given category (preserves table order). */
+export function capabilitiesByCategory(
+  category: CapabilityCategory,
+): readonly EditorCapability[] {
+  return EDITOR_CAPABILITIES.filter((cap) => cap.category === category);
+}
+
+/** Return every capability with the given kind (preserves table order). */
+export function capabilitiesByKind(
+  kind: CapabilityKind,
+): readonly EditorCapability[] {
+  return EDITOR_CAPABILITIES.filter((cap) => cap.kind === kind);
+}

package/src/runtime/event-refresh-hints.ts

@@ -43,6 +43,7 @@ export function describeEventImpact(
     case "suggestion_updated":
     case "comment_added":
     case "comment_resolved":
+    case "comments_changed":
       return {
         invalidate: [
           "render",

package/src/runtime/layout/docx-font-loader.ts

@@ -45,12 +45,35 @@ export interface DocxFontLoader {
   refresh(input: FontLoaderInput): void;
 }
 
+interface MinimalFontFace {
+  load(): Promise<MinimalFontFace>;
+}
+
+interface MinimalFontFaceDescriptors {
+  weight?: string;
+  style?: string;
+}
+
+interface MinimalFontFaceConstructor {
+  new (
+    family: string,
+    source: ArrayBuffer | ArrayBufferView | string,
+    descriptors?: MinimalFontFaceDescriptors,
+  ): MinimalFontFace;
+}
+
+interface MinimalFontFaceSet {
+  add(face: MinimalFontFace): void;
+  check(font: string): boolean;
+  ready: Promise<MinimalFontFaceSet>;
+}
+
 export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
+  const globalDocument = (globalThis as unknown as { document?: { fonts?: unknown } }).document;
   const supported =
-    typeof document !== "undefined" &&
+    globalDocument !== undefined &&
     typeof (globalThis as { FontFace?: unknown }).FontFace !== "undefined" &&
-    // Guard against jsdom which exposes FontFace but not document.fonts
-    Boolean((document as Document & { fonts?: FontFaceSet }).fonts);
+    Boolean(globalDocument.fonts);
 
   let current: FontLoaderInput = initial;
   let readyPromise: Promise<void>;
@@ -58,7 +81,7 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
   function run(input: FontLoaderInput): Promise<void> {
     if (!supported) return Promise.resolve();
-    const fontSet = (document as Document & { fonts?: FontFaceSet }).fonts;
+    const fontSet = globalDocument?.fonts as MinimalFontFaceSet | undefined;
     if (!fontSet) return Promise.resolve();
 
     const pending: Array<Promise<unknown>> = [];
@@ -70,10 +93,8 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
         for (const [descriptor, data] of variantsOf(variants)) {
           try {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const FontFaceCtor = (globalThis as any).FontFace as {
-              new (family: string, source: BufferSource, descriptors?: FontFaceDescriptors): FontFace;
-            };
+            const FontFaceCtor = (globalThis as { FontFace?: MinimalFontFaceConstructor }).FontFace;
+            if (!FontFaceCtor) continue;
             const face = new FontFaceCtor(family, data, descriptor);
             pending.push(
               face.load().then((loaded) => {
@@ -88,8 +109,6 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
       }
     }
 
-    // Mark declared families as registered if the browser already resolves
-    // them (e.g. system fonts like Calibri, Arial).
     for (const family of input.families) {
       try {
         const probe = `12px "${family.replace(/"/g, "'")}", serif`;
@@ -127,7 +146,7 @@ export function createDocxFontLoader(initial: FontLoaderInput): DocxFontLoader {
 
 function* variantsOf(
   variants: EmbeddedFontBytes,
-): IterableIterator<[FontFaceDescriptors, ArrayBuffer]> {
+): IterableIterator<[MinimalFontFaceDescriptors, ArrayBuffer]> {
   if (variants.regular) {
     yield [{ weight: "400", style: "normal" }, variants.regular];
   }

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

@@ -61,6 +61,8 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getTableRenderPlan: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,
+    setVisibleBlockRange: () => undefined,
+    requestViewportRefresh: () => undefined,
     subscribe: (_listener: (event: LayoutFacetEvent) => void) => () => undefined,
   };
 }

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;
 }
 
 // ---------------------------------------------------------------------------
@@ -737,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;
+    },
   };
 }