@beyondwork/docx-react-component 1.0.50 → 1.0.51

package/README.md

@@ -234,11 +234,14 @@ Engineering work is organized into 9 lanes (5 active now + 2 later polish + 2 fi
 | 3b | [**OOXML Fidelity & Round-Trip**](docs/plans/lane-3b-ooxml-fidelity.md) | **55%** | V1 + O3 + O4 + O2 (all 4 slices) + V7 closed; 🚨 O8 + L2.c + V6 + V2a/b/c + R3–R5 backlog |
 | 4 | [**Collab + CLM/Vallor**](docs/plans/lane-4-collab-clm-vallor.md) | **80%** | P1–P14 + all P11 sub-bullets + P12 + perf-parity + P13 A/B/C shipped; P15 / P16 / P17 left |
 | 5 | [**Charts (independent)**](docs/plans/lane-5-charts.md) | **30%** | Stages 0–2 shipped (parsers + theme); Stages 3–7 (SVG renderers + pixel-diff) left |
-| 6 | [**Visual Chrome / Layout Polish**](docs/plans/lane-6-visual-chrome-layout-polish.md) | **0%** | LATER — activates after Lane 3b V2c + Lane 2 Phase 2.2 ship; discrete paper cards, native chrome, float-wrap, validation bar |
-| 7a | [**Visual Fidelity Register**](docs/plans/lane-7a-visual-fidelity-register.md) | **0%** | LATER (gated on 6a+6b) — V5 covers, V6 REF/PAGEREF, V7 cascade audit |
-| 7b | [**Revision & Redline Completion**](docs/plans/lane-7b-revision-redline-completion.md) | **0%** | LATER (gated on 6a+6b) — X4.a/b structural table revisions, X5 ffData, move-pairing |
-| 7c | [**Preservation & Format Coverage**](docs/plans/lane-7c-preservation-format-coverage.md) | **0%** | LATER (gated on 6a+6b) — O6 Strict, OLE preserve-only, picture-SDT, w14/kern/VML defer |
-| 7d | [**Platform Hardening & Hygiene**](docs/plans/lane-7d-platform-hardening-hygiene.md) | **0%** | LATER (gated on 6a+6b) — harness-crash-hardening, fastload activation, worktree consolidation |
+| 6a | [**Tokens & Theme Foundation**](docs/plans/lane-6a-tokens-theme-foundation.md) | **~25%** | Active (no gate) — canonical token substrate: brand-accent flip, semantic families, scope-tint tokens, chart palette, hex eviction, density + reduced-motion plumbing |
+| 6b | [**Shell & Workspace Chrome**](docs/plans/lane-6b-shell-workspace-chrome.md) | **~15%** | Gated on 6a.S1+S2 — shell header + toolbar + status + alert banner + unsaved modal + collab chrome restyle; mode-dock decommission; TwCommandPalette |
+| 6c | [**Context & Review Surfaces**](docs/plans/lane-6c-context-review-surfaces.md) | **~15%** | Gated on 6a.S1+S2 — selection toolbar + suggestion card + rail + scope + context toolbars + health panel restyle; TwCommentPreview / TwEmptyState / TwShortcutHint |
+| 6d | [**Visual Fidelity**](docs/plans/lane-6d-visual-fidelity.md) | **~20%** | Gated on 6a.S1+S2 + external-lane deps — L8 A/B/C shipped; L8 Phase D + P11 overlays + P7 + P12 + P14 next |
+| 7a | [**Visual Fidelity Register**](docs/plans/lane-7a-visual-fidelity-register.md) | **0%** | LATER (gated on 6a–6d) — V5 covers, V6 REF/PAGEREF, V7 cascade audit |
+| 7b | [**Revision & Redline Completion**](docs/plans/lane-7b-revision-redline-completion.md) | **0%** | LATER (gated on 6a–6d) — X4.a/b structural table revisions, X5 ffData, move-pairing |
+| 7c | [**Preservation & Format Coverage**](docs/plans/lane-7c-preservation-format-coverage.md) | **0%** | LATER (gated on 6a–6d) — O6 Strict, OLE preserve-only, picture-SDT, w14/kern/VML defer |
+| 7d | [**Platform Hardening & Hygiene**](docs/plans/lane-7d-platform-hardening-hygiene.md) | **0%** | LATER (gated on 6a–6d) — harness-crash-hardening, fastload activation, worktree consolidation |
 | 8 | [**API Ergonomics / Errors / BC**](docs/plans/lane-8-api-ergonomics.md) | **40%** | LATER — Tracks A+C shipped (error catalog + ergonomics fixes); Tracks B+D+E + public-api.md end-to-end refactor remain |
 | 9 | [**Shipping (v2.0.0)**](docs/plans/lane-9-shipping.md) | **0%** | FINAL — API freeze, semver discipline, changelog, telemetry, customer migration guides, doc completeness audit |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.50",
+  "version": "1.0.51",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

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

@@ -52,8 +52,49 @@
  *       `frame.decorationIndex`. Cache envelopes from version 5 are
  *       invalidated on load because the anchor-index public shape
  *       changed even though pixel geometry did not.
+ *   7 — Lane 3a P9 Phase A2. Predicted-delta-aware anchor shifts.
+ *       `byRuntimeOffset` and `bySelection` now compensate incoming
+ *       offsets by `sumDeltasBefore(pendingDeltas, offset)` before the
+ *       map lookup so chrome rects stay aligned with the caret during
+ *       the predicted-dispatch window. No cached-geometry change; pure
+ *       resolver behavior change. Cache envelopes from v6 auto-
+ *       invalidate because the anchor-index now honors the previously-
+ *       stubbed `pendingDeltas` input.
+ *   8 — Lane 3a P10 Phase B. `frame_diff` kernel event now carries a
+ *       full `RenderFrameDiff` (addedPages / removedPages /
+ *       unchangedPages / changedPages) instead of the prior
+ *       `pageRange` payload. New module `src/runtime/render/render-frame-
+ *       diff.ts` exports `diffRenderFrames(prev, next)` which computes
+ *       the structural diff (blockId + rounded bbox + decoration-ref
+ *       intersection — NOT reference equality, because the layout
+ *       engine rebuilds fragment objects on every pass). Page-stack
+ *       consumers subscribe to `frame_diff` and memoize unchanged pages
+ *       to skip React reconciliation. No cached-geometry change; cache
+ *       envelopes from v7 invalidate because the event shape changed.
+ *   9 — Lane 3a P10 Phase C. `analyzeInvalidation` for
+ *       `section-change` now returns `scope: "bounded"` with
+ *       `dirtyPageRange.firstPageIndex` set to the affected section's
+ *       first rendered page (was `scope: "full"`). Pages in earlier
+ *       sections retain pagination; pages in and after the affected
+ *       section rebuild. Fallback to full rebuild when the target
+ *       section has no materialized pages. No cached-geometry change;
+ *       cache envelopes from v8 invalidate because the invalidation
+ *       classifier changed the scope contract.
+ *  10 — Lane 3a P10 Phase D1. `spliceGraph` detects structural
+ *       convergence between the fresh tail and the prior tail and
+ *       reuses the prior `RuntimePageNode` reference for every page
+ *       that matches on (sectionIndex, pageInSection, startOffset,
+ *       endOffset, isBlankFiller, body / header / footer / footnote
+ *       fragmentId lists). Downstream caches — render-frame-diff
+ *       (`unchangedPages`), prerender cache (stable pageId), React
+ *       page keys — observe stable references for the common case
+ *       where a localized edit doesn't shift content forward. Fresh
+ *       nodes are substituted from the first mismatch onward. No
+ *       pixel-geometry change; cache envelopes from v9 invalidate
+ *       because page-node identity semantics on bounded splices
+ *       changed.
  */
-export const LAYOUT_ENGINE_VERSION = 6 as const;
+export const LAYOUT_ENGINE_VERSION = 10 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

package/src/runtime/layout/layout-invalidation.ts

@@ -7,6 +7,21 @@
  * boundary inside the dirty range, style change, numbering change, etc.) we
  * fall back to a full rebuild.  The `scope` field declares which path the
  * engine should follow.
+ *
+ * Bounded scopes today:
+ *   - `content-edit`: bounded to the first page whose range overlaps the
+ *     edit offsets (§analyzeContentEdit).
+ *   - `section-change`: bounded to the first page of the affected section
+ *     onward — P10 Phase C (§analyzeSectionChange).
+ *   - `numbering-change`: bounded to the whole document (dirtyPageRange
+ *     spans pages [0..end]); tightening to the earliest page referencing
+ *     the numbering instance requires per-fragment numbering metadata
+ *     on `RuntimeBlockFragment` which is not available today.
+ *
+ * Remaining full-rebuild triggers:
+ *   - `styles-change` / `theme-change`: without per-fragment style-chain
+ *     metadata on the graph, we cannot safely tighten these. Flagged as
+ *     follow-up for when `RuntimeBlockFragment.resolvedStyleChain` lands.
  */
 
 import type { LayoutInvalidationReason } from "./paginated-layout-engine.ts";
@@ -252,15 +267,57 @@ function analyzeSectionChange(
   reason: Extract<LayoutInvalidationReason, { kind: "section-change" }>,
   graph: RuntimePageGraph,
 ): InvalidationResult {
-  // Section property changes affect from that section onward; conservative
-  // fallback is a full recompute.
+  // P10 Phase C — section property changes affect pages from the first
+  // page of the affected section onward. Earlier pages in earlier
+  // sections retain their pagination. When the target section has no
+  // materialized pages (e.g. section-change for a section that hasn't
+  // rendered yet), fall back to a full recompute.
+  const firstPageOfSection = findFirstPageIndexForSection(
+    graph,
+    reason.sectionIndex,
+  );
+  if (firstPageOfSection < 0) {
+    return {
+      scope: "full",
+      requiresFullRecompute: true,
+      dirtySectionRange: {
+        from: reason.sectionIndex,
+        to: Math.max(0, graph.sections.length - 1),
+      },
+      dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
+    };
+  }
+
+  // Bounded: rebuild from the affected section's first page to the end
+  // of the document. Rebuilding to the end (not just the section's last
+  // page) is required because a section property change — page size,
+  // margins, column count — can propagate to downstream sections if a
+  // `nextPage` / `evenPage` / `oddPage` break shifts.
   return {
-    scope: "full",
-    requiresFullRecompute: true,
+    scope: "bounded",
+    requiresFullRecompute: false,
+    dirtyPageRange: {
+      firstPageIndex: firstPageOfSection,
+      lastPageIndex: Math.max(0, graph.pages.length - 1),
+    },
     dirtySectionRange: {
       from: reason.sectionIndex,
-      to: graph.sections.length - 1,
+      to: Math.max(0, graph.sections.length - 1),
     },
     dirtyFieldFamilies: ["PAGE", "NUMPAGES", "SECTIONPAGES"],
   };
 }
+
+function findFirstPageIndexForSection(
+  graph: RuntimePageGraph,
+  sectionIndex: number,
+): number {
+  for (let i = 0; i < graph.pages.length; i += 1) {
+    const page = graph.pages[i]!;
+    if (page.isBlankFiller) continue;
+    if (page.sectionIndex === sectionIndex) return i;
+  }
+  // No page found for this section — section may be empty or past the
+  // rendered tail. Caller treats this as a full-rebuild trigger.
+  return -1;
+}

package/src/runtime/layout/page-graph.ts

@@ -522,7 +522,34 @@ export function spliceGraph(
   graphRevision += 1;
   const clampedFirst = Math.max(0, Math.min(firstDirtyIndex, prior.pages.length));
   const preserved = prior.pages.slice(0, clampedFirst);
-  const nextPages: RuntimePageNode[] = [...preserved, ...freshPages];
+
+  // P10 Phase D1 — convergence-point tail reuse. When a fresh page at
+  // index `clampedFirst + i` structurally matches the prior graph's
+  // page at the same index (same startOffset, endOffset, sectionIndex,
+  // fragment count), substitute the prior `RuntimePageNode` so
+  // downstream caches (render-frame-diff, prerender cache, React page
+  // keys) observe a stable reference. Stops at the first mismatch —
+  // everything after that re-pagination produced fresh has to flow
+  // through the fresh nodes because pagination may have shifted it.
+  // When prior has fewer pages past clampedFirst than fresh (e.g., an
+  // edit added pages), `reusedCount` caps at the prior length so we
+  // don't index past the prior tail.
+  const priorTail = prior.pages.slice(clampedFirst);
+  const reuseLimit = Math.min(priorTail.length, freshPages.length);
+  let reusedCount = 0;
+  while (
+    reusedCount < reuseLimit &&
+    pageNodesStructurallyEqual(priorTail[reusedCount]!, freshPages[reusedCount]!)
+  ) {
+    reusedCount += 1;
+  }
+  const stableTailPrefix = priorTail.slice(0, reusedCount);
+  const divergentTail = freshPages.slice(reusedCount);
+  const nextPages: RuntimePageNode[] = [
+    ...preserved,
+    ...stableTailPrefix,
+    ...divergentTail,
+  ];
 
   const survivingPageIds = new Set(nextPages.map((page) => page.pageId));
   const mergedFragments: RuntimeBlockFragment[] = [];
@@ -558,3 +585,69 @@ export function spliceGraph(
     contentPageCount,
   };
 }
+
+/**
+ * Compare two `RuntimePageNode`s by the fields that matter for
+ * pagination identity — if these all match, the fresh node represents
+ * the same content the prior graph already paginated. Used by
+ * `spliceGraph` to detect convergence between the fresh tail and the
+ * prior tail (P10 Phase D1) so downstream caches see stable references.
+ *
+ * We deliberately compare fragmentIds rather than full fragment objects
+ * because fragments are re-minted on each build even when they project
+ * identical canonical content; their id is derived from a stable
+ * structural hash.
+ */
+function pageNodesStructurallyEqual(
+  a: RuntimePageNode,
+  b: RuntimePageNode,
+): boolean {
+  if (a.sectionIndex !== b.sectionIndex) return false;
+  if (a.pageInSection !== b.pageInSection) return false;
+  if (a.startOffset !== b.startOffset) return false;
+  if (a.endOffset !== b.endOffset) return false;
+  if (a.isBlankFiller !== b.isBlankFiller) return false;
+  if (a.regions.body.fragmentIds.length !== b.regions.body.fragmentIds.length) {
+    return false;
+  }
+  for (let i = 0; i < a.regions.body.fragmentIds.length; i += 1) {
+    if (a.regions.body.fragmentIds[i] !== b.regions.body.fragmentIds[i]) {
+      return false;
+    }
+  }
+  // Header / footer fragment lists: compare if present on either side.
+  if (!optionalRegionFragmentsEqual(a.regions.header, b.regions.header)) {
+    return false;
+  }
+  if (!optionalRegionFragmentsEqual(a.regions.footer, b.regions.footer)) {
+    return false;
+  }
+  // Footnote-area regions: compare count + per-region fragment lists.
+  const aFoot = a.regions.footnotes ?? [];
+  const bFoot = b.regions.footnotes ?? [];
+  if (aFoot.length !== bFoot.length) return false;
+  for (let i = 0; i < aFoot.length; i += 1) {
+    if (!regionFragmentsEqual(aFoot[i]!, bFoot[i]!)) return false;
+  }
+  return true;
+}
+
+function optionalRegionFragmentsEqual(
+  a: RuntimePageRegion | undefined,
+  b: RuntimePageRegion | undefined,
+): boolean {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  return regionFragmentsEqual(a, b);
+}
+
+function regionFragmentsEqual(
+  a: RuntimePageRegion,
+  b: RuntimePageRegion,
+): boolean {
+  if (a.fragmentIds.length !== b.fragmentIds.length) return false;
+  for (let i = 0; i < a.fragmentIds.length; i += 1) {
+    if (a.fragmentIds[i] !== b.fragmentIds[i]) return false;
+  }
+  return true;
+}

package/src/runtime/render/index.ts

@@ -30,6 +30,13 @@ export {
   type LockedRangeInput,
 } from "./decoration-resolver.ts";
 
+export {
+  diffRenderFrames,
+  isEmptyDiff,
+  type ChangedPageEntry,
+  type RenderFrameDiff,
+} from "./render-frame-diff.ts";
+
 export {
   DEFAULT_PX_PER_TWIP,
   EMPTY_DECORATION_INDEX,

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

@@ -0,0 +1,298 @@
+/**
+ * Render-frame diff (P10 Phase B).
+ *
+ * Computes a structural diff between two `RenderFrame`s so the page-stack
+ * view can skip React reconciliation on pages whose content, geometry,
+ * and decoration anchors are unchanged. The diff is a pure function over
+ * the two frames — it performs no DOM reads, holds no state, and can run
+ * in a worker-less main-thread slice safely.
+ *
+ * Critical: comparison is structural (blockId + rounded bbox +
+ * decoration-ref intersection), NEVER reference equality. The layout
+ * engine's `buildPageStackFrom` rebuilds fragment objects on every call,
+ * so reference compare would report every page as dirty and collapse the
+ * skip-render optimization.
+ */
+
+import type { PublicPageRegion } from "../layout/public-facet.ts";
+import type {
+  RenderBlock,
+  RenderFrame,
+  RenderFrameRect,
+  RenderPage,
+  RenderStoryRegion,
+  DecorationIndex,
+} from "./render-frame-types.ts";
+
+// ---------------------------------------------------------------------------
+// Public shape
+// ---------------------------------------------------------------------------
+
+export type RegionKind = PublicPageRegion["kind"];
+
+export interface ChangedPageEntry {
+  pageIndex: number;
+  /**
+   * Regions of the page that carry structural changes. Empty means the
+   * page itself changed (added / removed region or page-frame geometry)
+   * without a single region being identifiable.
+   */
+  regions: readonly {
+    kind: RegionKind;
+    /**
+     * Block ids whose bbox, kind, decoration refs, or membership
+     * differs between prev and next. `"<added>"` and `"<removed>"`
+     * sentinel ids indicate list-length changes.
+     */
+    changedBlockIds: readonly string[];
+  }[];
+}
+
+export interface RenderFrameDiff {
+  /** Page indices present in `next` but not `prev`. */
+  addedPages: readonly number[];
+  /** Page indices present in `prev` but not `next`. */
+  removedPages: readonly number[];
+  /** Pages present in both whose content is structurally equal. */
+  unchangedPages: readonly number[];
+  /** Pages present in both with at least one structural change. */
+  changedPages: readonly ChangedPageEntry[];
+}
+
+/**
+ * Convenience flag: a diff is empty when both frames project the same
+ * set of pages and every shared page is unchanged.
+ */
+export function isEmptyDiff(diff: RenderFrameDiff): boolean {
+  return (
+    diff.addedPages.length === 0 &&
+    diff.removedPages.length === 0 &&
+    diff.changedPages.length === 0
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Diff entry point
+// ---------------------------------------------------------------------------
+
+export function diffRenderFrames(
+  prev: RenderFrame | null,
+  next: RenderFrame,
+): RenderFrameDiff {
+  if (!prev) {
+    return {
+      addedPages: next.pages.map((p) => p.page.pageIndex),
+      removedPages: [],
+      unchangedPages: [],
+      changedPages: [],
+    };
+  }
+
+  const prevByIndex = new Map<number, RenderPage>();
+  for (const page of prev.pages) {
+    prevByIndex.set(page.page.pageIndex, page);
+  }
+  const nextIndices = new Set<number>();
+  for (const page of next.pages) {
+    nextIndices.add(page.page.pageIndex);
+  }
+
+  const addedPages: number[] = [];
+  const removedPages: number[] = [];
+  const unchangedPages: number[] = [];
+  const changedPages: ChangedPageEntry[] = [];
+
+  for (const nextPage of next.pages) {
+    const pageIndex = nextPage.page.pageIndex;
+    const prevPage = prevByIndex.get(pageIndex);
+    if (!prevPage) {
+      addedPages.push(pageIndex);
+      continue;
+    }
+    const regions = diffPage(prevPage, nextPage, prev.decorationIndex, next.decorationIndex);
+    if (regions.length === 0 && rectEquals(prevPage.frame, nextPage.frame)) {
+      unchangedPages.push(pageIndex);
+    } else {
+      changedPages.push({ pageIndex, regions });
+    }
+  }
+
+  for (const prevPage of prev.pages) {
+    if (!nextIndices.has(prevPage.page.pageIndex)) {
+      removedPages.push(prevPage.page.pageIndex);
+    }
+  }
+
+  return { addedPages, removedPages, unchangedPages, changedPages };
+}
+
+// ---------------------------------------------------------------------------
+// Page / region / block compare
+// ---------------------------------------------------------------------------
+
+function diffPage(
+  prev: RenderPage,
+  next: RenderPage,
+  prevIndex: DecorationIndex,
+  nextIndex: DecorationIndex,
+): ChangedPageEntry["regions"] {
+  const changed: ChangedPageEntry["regions"][number][] = [];
+
+  const bodyChanges = diffRegion(prev.regions.body, next.regions.body, prevIndex, nextIndex);
+  if (bodyChanges.length > 0) {
+    changed.push({ kind: "body", changedBlockIds: bodyChanges });
+  }
+
+  const headerChanges = diffOptionalRegion(
+    prev.regions.header,
+    next.regions.header,
+    prevIndex,
+    nextIndex,
+  );
+  if (headerChanges.length > 0) {
+    changed.push({ kind: "header", changedBlockIds: headerChanges });
+  }
+
+  const footerChanges = diffOptionalRegion(
+    prev.regions.footer,
+    next.regions.footer,
+    prevIndex,
+    nextIndex,
+  );
+  if (footerChanges.length > 0) {
+    changed.push({ kind: "footer", changedBlockIds: footerChanges });
+  }
+
+  const prevFoot = prev.regions.footnotes ?? [];
+  const nextFoot = next.regions.footnotes ?? [];
+  if (prevFoot.length !== nextFoot.length) {
+    changed.push({ kind: "footnote-area", changedBlockIds: ["<count-changed>"] });
+  } else {
+    for (let i = 0; i < prevFoot.length; i += 1) {
+      const fChanges = diffRegion(prevFoot[i]!, nextFoot[i]!, prevIndex, nextIndex);
+      if (fChanges.length > 0) {
+        changed.push({ kind: "footnote-area", changedBlockIds: fChanges });
+      }
+    }
+  }
+
+  return changed;
+}
+
+function diffOptionalRegion(
+  prev: RenderStoryRegion | undefined,
+  next: RenderStoryRegion | undefined,
+  prevIndex: DecorationIndex,
+  nextIndex: DecorationIndex,
+): readonly string[] {
+  if (!prev && !next) return [];
+  if (!prev && next) return ["<added>"];
+  if (prev && !next) return ["<removed>"];
+  return diffRegion(prev!, next!, prevIndex, nextIndex);
+}
+
+function diffRegion(
+  prev: RenderStoryRegion,
+  next: RenderStoryRegion,
+  prevIndex: DecorationIndex,
+  nextIndex: DecorationIndex,
+): readonly string[] {
+  const changed: string[] = [];
+  if (!rectEquals(prev.frame, next.frame)) {
+    changed.push("<region-frame>");
+  }
+  // Index blocks by blockId. Same blockId across frames is expected when a
+  // block is stable even if the containing RenderBlock object is
+  // different — this is the critical structural-compare invariant.
+  const prevBlocks = new Map<string, RenderBlock>();
+  for (const block of prev.blocks) {
+    prevBlocks.set(block.fragment.blockId, block);
+  }
+  const nextIds = new Set<string>();
+  for (const block of next.blocks) {
+    nextIds.add(block.fragment.blockId);
+    const prevBlock = prevBlocks.get(block.fragment.blockId);
+    if (!prevBlock) {
+      changed.push(block.fragment.blockId);
+      continue;
+    }
+    if (!blocksStructurallyEqual(prevBlock, block, prevIndex, nextIndex)) {
+      changed.push(block.fragment.blockId);
+    }
+  }
+  for (const blockId of prevBlocks.keys()) {
+    if (!nextIds.has(blockId)) changed.push(blockId);
+  }
+  return changed;
+}
+
+function blocksStructurallyEqual(
+  a: RenderBlock,
+  b: RenderBlock,
+  aIndex: DecorationIndex,
+  bIndex: DecorationIndex,
+): boolean {
+  if (a.kind !== b.kind) return false;
+  if (a.fragment.regionKind !== b.fragment.regionKind) return false;
+  if (a.fragment.from !== b.fragment.from) return false;
+  if (a.fragment.to !== b.fragment.to) return false;
+  if (!rectEquals(a.frame, b.frame)) return false;
+  if (a.lines.length !== b.lines.length) return false;
+  for (let i = 0; i < a.lines.length; i += 1) {
+    if (!rectEquals(a.lines[i]!.frame, b.lines[i]!.frame)) return false;
+  }
+  // Decoration-ref intersection: a block's decoration set changes when
+  // any lane in the decoration index mentions a rect whose frame equals
+  // this block's frame (coarse but sufficient for skip-render). A more
+  // precise walk would key by runtime-offset overlap; we defer that to a
+  // follow-up once decoration-resolver exposes per-block lanes directly.
+  const aHash = decorationHashForBlock(a.frame, aIndex);
+  const bHash = decorationHashForBlock(b.frame, bIndex);
+  if (aHash !== bHash) return false;
+  return true;
+}
+
+function decorationHashForBlock(
+  blockFrame: RenderFrameRect,
+  index: DecorationIndex,
+): string {
+  const tokens: string[] = [];
+  for (const lane of [index.workflow, index.comments, index.revisions, index.search, index.locked] as const) {
+    for (const entry of lane) {
+      if (rectIntersects(entry.frame, blockFrame)) {
+        tokens.push(`${entry.kind}:${entry.refId}`);
+      }
+    }
+  }
+  tokens.sort();
+  return tokens.join("|");
+}
+
+// ---------------------------------------------------------------------------
+// Geometry compare
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare two rects with sub-pixel tolerance so rounding differences
+ * between frame builds don't report spurious changes. 0.1 px matches the
+ * smallest meaningful chrome movement at 200% zoom.
+ */
+const RECT_EPS = 0.1;
+
+function rectEquals(a: RenderFrameRect, b: RenderFrameRect): boolean {
+  return (
+    Math.abs(a.leftPx - b.leftPx) < RECT_EPS &&
+    Math.abs(a.topPx - b.topPx) < RECT_EPS &&
+    Math.abs(a.widthPx - b.widthPx) < RECT_EPS &&
+    Math.abs(a.heightPx - b.heightPx) < RECT_EPS
+  );
+}
+
+function rectIntersects(a: RenderFrameRect, b: RenderFrameRect): boolean {
+  return !(
+    a.leftPx + a.widthPx <= b.leftPx ||
+    b.leftPx + b.widthPx <= a.leftPx ||
+    a.topPx + a.heightPx <= b.topPx ||
+    b.topPx + b.heightPx <= a.topPx
+  );
+}

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

@@ -294,7 +294,14 @@ export type RenderKernelEvent =
   | {
       kind: "frame_diff";
       revision: number;
-      pageRange: { fromPageIndex: number; toPageIndex: number };
+      /**
+       * Full structural diff between the previously-cached frame and the
+       * newly-built frame. Shipped with P10 Phase B (2026-04-19).
+       * Consumers read `diff.unchangedPages` to skip per-page React
+       * reconciliation and `diff.changedPages[].regions[].changedBlockIds`
+       * to drive targeted sub-tree updates.
+       */
+      diff: import("./render-frame-diff.ts").RenderFrameDiff;
     }
   | { kind: "decoration_resolved"; revision: number };