@beyondwork/docx-react-component 1.0.46 → 1.0.48

package/src/runtime/document-runtime.ts

@@ -16,6 +16,8 @@ import type {
   AddCommentParams,
   AddCommentReplyResult,
   AddCommentResult,
+  AddScopeParams,
+  AddScopeResult,
   CommentSidebarSnapshot,
   CommentSidebarThreadSnapshot,
   CompatibilityReport,
@@ -74,6 +76,7 @@ import type {
   WorkflowMetadataSnapshot,
   WorkflowMarkupSnapshot,
   WorkflowOverlay,
+  WorkflowScope,
   WorkflowScopeSnapshot,
   WorkspaceMode,
   WordReviewEditorEvent,
@@ -116,6 +119,11 @@ import {
 } from "../review/store/revision-store.ts";
 import { createSuggestionsSnapshot } from "./suggestions-snapshot.ts";
 import { validateSelectionAgainstDocument } from "./selection/post-edit-validator.ts";
+import { resolveScope } from "./scope-resolver.ts";
+import {
+  insertScopeMarkers,
+  removeScopeMarkers,
+} from "../core/commands/add-scope.ts";
 import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
 import { mergeCompatibilityReports } from "../validation/compatibility-report.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
@@ -291,6 +299,9 @@ export interface DocumentRuntime {
   reopenComment(commentId: string): void;
   addCommentReply(commentId: string, body: string, authorId?: string): AddCommentReplyResult;
   editCommentBody(commentId: string, body: string): void;
+  addScope(params: AddScopeParams): AddScopeResult;
+  getScope(scopeId: string): WorkflowScope | null;
+  removeScope(scopeId: string): void;
   acceptChange(changeId: string): void;
   rejectChange(changeId: string): void;
   acceptAllChanges(): void;
@@ -406,6 +417,7 @@ export interface DocumentRuntime {
 export interface CommandAppliedMeta {
   preSelection: import("../core/state/editor-state.ts").SelectionSnapshot;
   activeStory: EditorStoryTarget;
+  priorDocument: CanonicalDocumentEnvelope;
 }
 
 export interface CreateDocumentRuntimeOptions {
@@ -2034,6 +2046,16 @@ export function createDocumentRuntime(
     }
   });
 
+  // R5 scratch snapshot: single pre-allocated object reused for every
+  // `applyRemoteCommand(cmd, ctx, meta)` call with a `meta.preSelection`
+  // override. Avoids the per-remote-command `{ ...cachedRenderSnapshot }`
+  // + `{ ...state }` allocations that CLAUDE.md rule 4 warns against.
+  // Mutated in place below — callers MUST NOT hold references to it
+  // across dispatches; `executeEditorCommand` + `commitRemote` consume
+  // synchronously within `applyRemoteCommand`, so this is safe today.
+  const r5ScratchReplayState: typeof state = { ...state };
+  const r5ScratchReplaySnapshot: typeof cachedRenderSnapshot = { ...cachedRenderSnapshot };
+
   return {
     subscribe(listener) {
       listeners.add(listener);
@@ -2111,6 +2133,7 @@ export function createDocumentRuntime(
         options.onCommandApplied?.(command, noopTransaction, context, {
           preSelection: state.selection,
           activeStory,
+          priorDocument: state.document,
         });
         return;
       }
@@ -2124,11 +2147,13 @@ export function createDocumentRuntime(
         } as const;
         const preSelection = commandSelection;
         const preActiveStory = activeStory;
+        const priorDocument = state.document;
         const transaction = executeEditorCommand(state, command, context);
         commit(transaction);
         options.onCommandApplied?.(command, transaction, context, {
           preSelection,
           activeStory: preActiveStory,
+          priorDocument,
         });
       } catch (error) {
         emitError(toRuntimeError(error));
@@ -2143,28 +2168,56 @@ export function createDocumentRuntime(
           applyRuntimeStateOverlayCommand(command);
           return;
         }
-        if (meta?.activeStory && !storyTargetsEqual(meta.activeStory, activeStory)) {
-          activeStory = meta.activeStory;
-          storySelections.set(
-            storyTargetKey(activeStory),
-            meta.preSelection ?? state.selection,
-          );
+        // Story-target isolation: the remote's `meta.activeStory` scopes
+        // the replay (so the command lands in the intended region of the
+        // shared document), but must NEVER overwrite the local user's
+        // closure-level `activeStory`. Before P11 this assignment stole
+        // focus every time a remote event arrived for a different story —
+        // a local user authoring in a header would get yanked into the
+        // main body as soon as a peer edited main.
+        const replayStory = meta?.activeStory ?? activeStory;
+        const crossStoryReplay = Boolean(
+          meta?.activeStory && !storyTargetsEqual(meta.activeStory, activeStory),
+        );
+        let replayState: typeof state;
+        let replaySnapshot: typeof cachedRenderSnapshot;
+        if (meta?.preSelection) {
+          // Refresh scratch with current `state` / `cachedRenderSnapshot` (both
+          // mutate on every commit), then override only the selection fields.
+          Object.assign(r5ScratchReplayState, state);
+          r5ScratchReplayState.selection = meta.preSelection;
+          Object.assign(r5ScratchReplaySnapshot, cachedRenderSnapshot);
+          r5ScratchReplaySnapshot.selection = toPublicSelectionSnapshot(meta.preSelection, replayStory);
+          replayState = r5ScratchReplayState;
+          replaySnapshot = r5ScratchReplaySnapshot;
+        } else {
+          replayState = state;
+          replaySnapshot = cachedRenderSnapshot;
         }
-        const replayState = meta?.preSelection
-          ? { ...state, selection: meta.preSelection }
-          : state;
-        const replaySnapshot = meta?.preSelection
-          ? {
-              ...cachedRenderSnapshot,
-              selection: toPublicSelectionSnapshot(meta.preSelection, activeStory),
-            }
-          : cachedRenderSnapshot;
         const replayContext = {
           ...context,
           renderSnapshot: replaySnapshot,
         };
         const transaction = executeEditorCommand(replayState, command, replayContext);
-        commitRemote(transaction);
+        if (crossStoryReplay) {
+          // Cross-story replay: the transaction's resulting selection is
+          // in the remote story's region. Don't leak that into local
+          // `state.selection` — preserve the pre-replay local selection
+          // so the local caret stays where the user is focused. The
+          // document delta still applies; only the selection is filtered.
+          // Full position-mapping of the local cursor through the remote
+          // edit is a separate P11 sub-bullet (Awareness cursor transaction
+          // mapping).
+          commitRemote({
+            ...transaction,
+            nextState: {
+              ...transaction.nextState,
+              selection: state.selection,
+            },
+          });
+        } else {
+          commitRemote(transaction);
+        }
       } catch (error) {
         emitError(toRuntimeError(error));
       }
@@ -2358,6 +2411,155 @@ export function createDocumentRuntime(
         origin: createOrigin("api", clock()),
       });
     },
+    addScope(params): AddScopeResult {
+      const scopeId =
+        params.scopeId ??
+        `scope-${clock().replace(/[^0-9]/gu, "")}-${Math.floor(Math.random() * 1e6)}`;
+      const anchor =
+        params.anchor.kind === "range"
+          ? { from: params.anchor.from, to: params.anchor.to }
+          : null;
+
+      if (!anchor) {
+        return {
+          scopeId,
+          anchor: params.anchor,
+        };
+      }
+
+      const { document: nextDocument } = insertScopeMarkers(state.document, {
+        scopeId,
+        from: anchor.from,
+        to: anchor.to,
+      });
+
+      if (nextDocument !== state.document) {
+        this.dispatch({
+          type: "document.replace",
+          document: nextDocument,
+          origin: createOrigin("api", clock()),
+        });
+      }
+
+      const resolved = resolveScope(state.document, scopeId);
+      const publicAnchor: EditorAnchorProjection =
+        resolved && resolved.kind === "range"
+          ? resolved
+          : {
+              kind: "range",
+              from: anchor.from,
+              to: anchor.to,
+              assoc: { start: -1, end: 1 },
+            };
+
+      const currentOverlay: WorkflowOverlay = workflowOverlay ?? {
+        overlayVersion: "workflow-overlay/1",
+        scopes: [],
+      };
+      const existingScopes = currentOverlay.scopes.filter(
+        (existing) => existing.scopeId !== scopeId,
+      );
+      const scope: WorkflowScope = {
+        scopeId,
+        mode: params.mode ?? "comment",
+        anchor: publicAnchor,
+        ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
+        ...(params.label ? { label: params.label } : {}),
+      };
+      this.dispatch({
+        type: "workflow.set-overlay",
+        overlay: {
+          ...currentOverlay,
+          scopes: [...existingScopes, scope],
+        },
+        origin: createOrigin("api", clock()),
+      });
+
+      if (params.persistence && params.persistence !== "runtime-only") {
+        const entry: WorkflowMetadataEntry = {
+          entryId: `scope-metadata-${scopeId}`,
+          metadataId: "workflow.scope",
+          anchor: publicAnchor,
+          scopeId,
+          value:
+            params.persistence === "document-metadata"
+              ? { ...(params.metadata?.value ?? {}), label: params.label }
+              : params.metadata?.value,
+          metadataPersistence:
+            params.persistence === "session" ? "external" : "internal",
+        };
+        this.dispatch({
+          type: "workflow.set-metadata-entries",
+          entries: [...(workflowMetadataEntries ?? []), entry],
+          origin: createOrigin("api", clock()),
+        });
+      }
+
+      return {
+        scopeId,
+        anchor: publicAnchor,
+      };
+    },
+    getScope(scopeId) {
+      const resolved = resolveScope(state.document, scopeId);
+      if (!resolved) {
+        const stored = workflowOverlay?.scopes.find((s) => s.scopeId === scopeId);
+        return stored ?? null;
+      }
+      const stored = workflowOverlay?.scopes.find((s) => s.scopeId === scopeId);
+      if (!stored) {
+        return {
+          scopeId,
+          mode: "comment",
+          anchor: resolved,
+        };
+      }
+      return {
+        ...stored,
+        anchor: resolved,
+      };
+    },
+    removeScope(scopeId) {
+      // Step 1: drop the scope from the overlay FIRST. If the scope's mode was
+      // "comment" / "view" the workflow-blocked-reasons gate in `dispatch`
+      // would otherwise refuse the subsequent `document.replace` with
+      // `workflow_comment_only` / `workflow_view_only`. Overlay commands are
+      // routed through `applyRuntimeStateOverlayCommand` and bypass that gate.
+      if (workflowOverlay) {
+        const nextScopes = workflowOverlay.scopes.filter(
+          (scope) => scope.scopeId !== scopeId,
+        );
+        if (nextScopes.length !== workflowOverlay.scopes.length) {
+          this.dispatch({
+            type: "workflow.set-overlay",
+            overlay: { ...workflowOverlay, scopes: nextScopes },
+            origin: createOrigin("api", clock()),
+          });
+        }
+      }
+      // Step 2: now that the scope is gone, strip the markers from the doc.
+      const nextDocument = removeScopeMarkers(state.document, scopeId);
+      if (nextDocument !== state.document) {
+        this.dispatch({
+          type: "document.replace",
+          document: nextDocument,
+          origin: createOrigin("api", clock()),
+        });
+      }
+      // Step 3: clear any customXml-persisted metadata entries.
+      if (workflowMetadataEntries) {
+        const nextEntries = workflowMetadataEntries.filter(
+          (entry) => entry.scopeId !== scopeId,
+        );
+        if (nextEntries.length !== workflowMetadataEntries.length) {
+          this.dispatch({
+            type: "workflow.set-metadata-entries",
+            entries: nextEntries,
+            origin: createOrigin("api", clock()),
+          });
+        }
+      }
+    },
     acceptChange(changeId) {
       this.dispatch({
         type: "change.accept",
@@ -3283,12 +3485,14 @@ export function createDocumentRuntime(
 
     const preSelection = selection;
     const preActiveStory = activeStory;
+    const priorDocument = state.document;
     if (activeStory.kind === "main") {
       const mainTransaction = executeEditorCommand(baseState, command, context);
       commit(mainTransaction);
       options.onCommandApplied?.(command, mainTransaction, context, {
         preSelection,
         activeStory: preActiveStory,
+        priorDocument,
       });
       return classifyAck({
         command,
@@ -3370,6 +3574,7 @@ export function createDocumentRuntime(
     options.onCommandApplied?.(broadcastCommand, mergedTransaction, context, {
       preSelection,
       activeStory: preActiveStory,
+      priorDocument,
     });
     return classifyAck({
       command,

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

@@ -45,7 +45,8 @@ export type CapabilityCategory =
   | "tracked-changes"
   | "comments"
   | "structure"
-  | "system";
+  | "system"
+  | "workflow";
 
 export interface CapabilityShortcut {
   /** Canonical Windows / Linux binding string (e.g. "Ctrl+B", "Shift+Tab"). */
@@ -301,87 +302,99 @@ export const EDITOR_CAPABILITIES: readonly EditorCapability[] = [
     shortcut: { winLinux: "Ctrl+0", mac: "Cmd+0" },
     hostEvent: "onZoomRequested",
   },
-
-  // ---------------------------------------------------------------
-  // Blocked — Word shortcuts the mounted editor does not implement
-  // ---------------------------------------------------------------
   {
-    id: "replaceText",
-    kind: "blocked",
+    id: "shortcut.replace",
+    kind: "host-delegated",
     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.",
-    },
+    hostEvent: "onReplaceRequested",
   },
   {
-    id: "goTo",
-    kind: "blocked",
+    id: "shortcut.go-to",
+    kind: "host-delegated",
     category: "navigation",
-    label: "Go to",
+    label: "Go to page / bookmark / line",
     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.",
-    },
+    hostEvent: "onGoToRequested",
   },
   {
-    id: "checkSpelling",
-    kind: "blocked",
+    id: "shortcut.spell",
+    kind: "host-delegated",
     category: "system",
     label: "Check spelling",
     shortcut: { winLinux: "F7", mac: "F7" },
-    blockReason: {
-      code: UNSUPPORTED_SURFACE,
-      message: "Spelling shortcuts are not supported in the mounted editor.",
-    },
+    hostEvent: "onSpellRequested",
   },
   {
-    id: "openThesaurus",
-    kind: "blocked",
+    id: "shortcut.thesaurus",
+    kind: "host-delegated",
     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.",
-    },
+    hostEvent: "onThesaurusRequested",
   },
   {
-    id: "extendSelection",
-    kind: "blocked",
+    id: "shortcut.extend-selection",
+    kind: "host-delegated",
     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.",
-    },
+    hostEvent: "onExtendSelectionRequested",
   },
   {
-    id: "lastEdit",
-    kind: "blocked",
+    id: "shortcut.last-edit",
+    kind: "host-delegated",
     category: "navigation",
     label: "Return to last edit",
     shortcut: { winLinux: "Shift+F5", mac: "Shift+F5" },
+    hostEvent: "onLastEditRequested",
+  },
+
+  // ---------------------------------------------------------------
+  // Blocked — Word shortcuts the mounted editor does not implement
+  // ---------------------------------------------------------------
+  {
+    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: "Last-edit shortcuts are not supported in the mounted editor.",
+      message: "Track changes authoring shortcuts are not supported in the mounted editor.",
     },
   },
+
+  // ---------------------------------------------------------------
+  // Workflow ref-methods (supported, no shortcut)
+  //
+  // These entries document ref-method API surface that has no
+  // keyboard binding — `WordReviewEditorRef.addScope` / `getScope`
+  // / `removeScope`, shipped as S1. They appear in the capability
+  // table so host integrations can introspect the full contract
+  // without parsing multiple sources. Do not remove the `kind:
+  // "supported"` discipline — they are runtime-owned mutations, not
+  // host-delegated.
+  // ---------------------------------------------------------------
+  {
+    id: "scope.add",
+    kind: "supported",
+    category: "workflow",
+    label: "Attach a workflow scope to a selection or range (ref method)",
+  },
+  {
+    id: "scope.get",
+    kind: "supported",
+    category: "workflow",
+    label: "Resolve a scopeId to a live WorkflowScope with current anchor (ref method)",
+  },
+  {
+    id: "scope.remove",
+    kind: "supported",
+    category: "workflow",
+    label: "Remove a scope's markers + metadata record (ref method)",
+  },
 ];
 
 /**

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

@@ -24,8 +24,26 @@
  *       internal cachedGraph + cachedKey without triggering fullRebuild.
  *       Does not change geometry — but the public interface changed, so
  *       persisted envelopes MUST re-derive their cacheKey under 3.
+ *   4 — PR #188 `fix(export)` bumped the version to satisfy the
+ *       `src/runtime/layout/**` gate, even though the font-loader
+ *       type-def restoration intended for that PR did not survive the
+ *       squash-merge. Runtime and cached geometry unchanged.
+ *   5 — PR #187 `joakim/commentevents` restores the local `Minimal*`
+ *       font-loader type defs under `src/runtime/layout/docx-font-loader.ts`
+ *       (re-application of previously-shipped PRs #162/#163 which a
+ *       subsequent merge reverted) so downstream consumers whose
+ *       TS `lib` does not expose `FontFaceSet.add` can type-check the
+ *       package, and adds the `comments_changed` event plumbing in
+ *       runtime domains outside `src/runtime/layout/**`. TypeScript-
+ *       surface-only from the layout engine's perspective: no cached
+ *       geometry or cache-key derivation changes. The bump exists
+ *       solely to satisfy the
+ *       `scripts/ci-check-layout-engine-version.mjs` gate because a
+ *       file under `src/runtime/layout/**` changed. Safe to treat
+ *       versions 3, 4, and 5 as cache-compatible if a migration ever
+ *       needs to collapse them.
  */
-export const LAYOUT_ENGINE_VERSION = 3 as const;
+export const LAYOUT_ENGINE_VERSION = 5 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope
@@ -37,5 +55,12 @@ export const LAYOUT_ENGINE_VERSION = 3 as const;
  *   1 — initial envelope shape: { schemaVersion, engineVersion,
  *       fontFingerprint, structuralHash, graph, surface }. Ships with
  *       L7 Phase 2.5 Plan A.
+ *   2 — L7 Phase 2.5 Plan B: adds `canonicalDocument` + `canonicalDocumentHash`
+ *       fields so the receiving client can skip the DOCX parse entirely on
+ *       cache hit. `canonicalDocumentHash` is also a 5th input to the cache
+ *       key so any state mutation (styles, metadata, comments, preservation)
+ *       correctly invalidates. v1 envelopes are rejected on load under v2 —
+ *       no corruption path exists because schemaVersion is the top-level
+ *       discriminator.
  */
-export const LAYCACHE_SCHEMA_VERSION = 1 as const;
+export const LAYCACHE_SCHEMA_VERSION = 2 as const;

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

@@ -1,13 +1,14 @@
 import type { EditorSurfaceSnapshot } from "../../api/public-types";
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
 import type { RuntimePageGraph } from "../layout/page-graph.ts";
 
 /**
- * L7 Phase 2.5 Task 2.5.3 — prerender cache envelope shape.
+ * L7 Phase 2.5 — 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.
+ * The envelope is the unit written to IndexedDB (Plan A) and — under Plan B
+ * (schema v2) — 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
@@ -15,15 +16,26 @@ import type { RuntimePageGraph } from "../layout/page-graph.ts";
  *   - `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
+ * customXml path both rely on structured-clone / JSON semantics. Keep fields
+ * as JSON-serializable primitives, plain objects, or arrays — no class
  * instances, functions, or symbols.
+ *
+ * Plan B additions (schema v2):
+ *   - `canonicalDocument` — the full parsed model, so the warm-path loader
+ *     can skip `parseMainDocumentXml` + `createImportedCanonicalDocument` +
+ *     `buildCompatibilityReport` + `createImportedSnapshot` on cache hit.
+ *     Saves ~584 ms of the 976 ms cold-upload on `extra-large` CCEP.
+ *   - `canonicalDocumentHash` — sha256 of sorted-keys JSON. Also the 5th
+ *     input to `deriveCacheKey`, so style/metadata/comment/preservation
+ *     mutations correctly invalidate the cache.
  */
 export interface CacheEnvelope {
   readonly schemaVersion: number;
   readonly engineVersion: number;
   readonly fontFingerprint: string;
   readonly structuralHash: string;
+  readonly canonicalDocumentHash: string;
   readonly graph: RuntimePageGraph;
   readonly surface: EditorSurfaceSnapshot;
+  readonly canonicalDocument: CanonicalDocument;
 }

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

@@ -1,22 +1,31 @@
 /**
- * L7 Phase 2.5 Task 2.5.1 — prerender cache-key derivation.
+ * L7 Phase 2.5 — 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.
+ *   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.
+ *   5. canonicalDocumentHash     — (Plan B, schema v2) sha256 of sorted-keys
+ *                                  JSON of the CanonicalDocument. Catches
+ *                                  non-structural mutations (styles,
+ *                                  metadata, comments, preservation) that
+ *                                  `structuralHash` alone misses. Computed
+ *                                  via `computeCanonicalDocumentHash()` from
+ *                                  `./canonical-document-hash.ts`.
  *
  * Returns a 64-char lower-case hex digest. Uses the Web Crypto API
  * (globalThis.crypto.subtle), available in Node 18+ and all target browsers —
@@ -33,6 +42,7 @@ export interface CacheKeyInputs {
   readonly fontFingerprint: string;
   readonly engineVersion: string | number;
   readonly schemaVersion: number;
+  readonly canonicalDocumentHash: string;
 }
 
 const BLOCK_SEPARATOR = "\u0000";
@@ -61,6 +71,7 @@ export async function deriveCacheKey(inputs: CacheKeyInputs): Promise<string> {
     inputs.fontFingerprint,
     String(inputs.engineVersion),
     String(inputs.schemaVersion),
+    inputs.canonicalDocumentHash,
   ].join(FIELD_SEPARATOR);
   return sha256Hex(composite);
 }