@beyondwork/docx-react-component 1.0.49 → 1.0.51

package/README.md

@@ -234,8 +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 |
-| 7 | [**Bugs / Gaps / Cross-cutting**](docs/plans/lane-7-bugs-gaps-cross-cutting.md) | **0%** | LATER — drain V#/O#/X# register, trigger-gated work, infrastructure hardening |
+| 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.49",
+  "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/api/public-types.ts

@@ -1,6 +1,6 @@
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
 import type { HarnessDebugPorts } from "../internal/harness-debug-ports.ts";
-import type { CanonicalParagraphFormatting, CanonicalRunFormatting, TextMark } from "../model/canonical-document.ts";
+import type { BlockNode, CanonicalParagraphFormatting, CanonicalRunFormatting, TextMark } from "../model/canonical-document.ts";
 import type { WordReviewEditorLayoutFacet } from "../runtime/layout/public-facet.ts";
 import type { RenderFrameRect } from "../runtime/render/index.ts";
 import type { ScopeRailPosture } from "../runtime/workflow-rail-segments.ts";
@@ -756,6 +756,17 @@ export interface InsertImageOptions {
 /** Re-export canonical `TextMark` so hosts can construct explicit-mode directives for I7 `replaceText`. */
 export type { TextMark };
 
+/**
+ * I2 Tier B Slice 1 — a block-level payload for `insertFragment` and the paste
+ * parsers that will drive it in later slices. Carries zero or more canonical
+ * block nodes (paragraphs, tables, SDTs, etc.); a host that constructs one
+ * directly is responsible for the blocks being well-formed per the canonical
+ * schema. The HTML / Word-clipboard parsers (Slices 2+3) will produce these.
+ */
+export interface CanonicalDocumentFragment {
+  blocks: BlockNode[];
+}
+
 /**
  * I7 — `replaceText` / `text.insert` formatting directive.
  *
@@ -2919,6 +2930,14 @@ export interface WordReviewEditorRef {
     target?: EditorAnchorProjection,
     formatting?: TextFormattingDirective,
   ): void;
+  /**
+   * I2 Tier B Slice 1 — splice a canonical block-level fragment at the target
+   * anchor (or at the current selection when omitted). Empty fragment = no-op.
+   * Baseline semantic: split the caret paragraph and insert fragment blocks
+   * between the halves; range selections are deleted first. Future slices will
+   * add merge-intent + richer caret placement as paste parsers come online.
+   */
+  insertFragment(fragment: CanonicalDocumentFragment, target?: EditorAnchorProjection): void;
   toggleBulletedList(): void;
   toggleNumberedList(): void;
   toggleBold(): void;

package/src/core/commands/index.ts

@@ -49,6 +49,7 @@ import type {
   RuntimeRenderSnapshot,
   SectionBreakType,
   SectionLayoutPatch,
+  CanonicalDocumentFragment,
   SectionPageNumberingPatch,
   TextFormattingDirective,
   WorkflowMetadataDefinition,
@@ -88,6 +89,7 @@ import {
   setHeaderFooterLinkAtSectionIndex,
 } from "./section-layout-commands.ts";
 import { insertPageBreak, insertTable } from "./text-commands.ts";
+import { applyFragmentInsert } from "../../runtime/structure-ops/fragment-insert.ts";
 import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
 
 export type ContentChildrenPatch =
@@ -170,6 +172,16 @@ export type EditorCommand =
       type: "paragraph.split";
       origin?: CommandOrigin;
     }
+  | {
+      /**
+       * I2 Tier B Slice 1 — splice a `CanonicalDocumentFragment` at the current
+       * selection. Baseline semantic: split the caret paragraph and insert
+       * fragment blocks between the halves; range selections are deleted first.
+       */
+      type: "fragment.insert";
+      fragment: CanonicalDocumentFragment;
+      origin?: CommandOrigin;
+    }
   | {
       type: "runtime.set-read-only";
       readOnly: boolean;
@@ -631,6 +643,15 @@ export function executeEditorCommand(
       return applyTextCommand(state, context.timestamp, (document, selection) =>
         splitParagraph(document, selection, context),
       );
+    case "fragment.insert": {
+      // I2 Tier B Slice 1 — route through the structure-ops splicer. No
+      // suggesting-mode branch yet; fragment insertion always lands as a direct
+      // edit. Future slices will gate behind track-changes when a fixture needs it.
+      const result = applyFragmentInsert(state.document, state.selection, command.fragment, {
+        timestamp: context.timestamp,
+      });
+      return buildDocumentReplaceTransaction(state, context, result);
+    }
     case "runtime.set-read-only":
       return createTransaction(
         {

package/src/io/export/serialize-comments.ts

@@ -760,11 +760,56 @@ function walkInlineNodeForBoundaries(
       return;
     }
     case "t": {
-      const text = node.children
-        .filter((child): child is XmlTextNode => child.type === "text")
-        .map((child) => child.text)
-        .join("");
-      setCursor(getCursor() + Array.from(text).length);
+      // O8 fix: emit a boundary entry for every interior code-point position
+      // so comment anchors landing mid-run resolve to a real source byte
+      // offset instead of silently dropping into skippedCommentIds. The walk
+      // advances through the raw XML source between each text child's start
+      // and end, treating XML entities (& < > " ' &#N;
+      // &#xN;) as a single code point whose byte cursor skips the whole
+      // entity. Surrogate pairs collapse to one code point to match
+      // Array.from(text).iteration used by the existing cursor math.
+      let cursor = getCursor();
+      for (const child of node.children) {
+        if (child.type !== "text") {
+          continue;
+        }
+        let byte = child.start;
+        const end = child.end;
+        while (byte < end) {
+          if (!boundaries.has(cursor)) {
+            // Preserve the outer <w:r>-entry at runStart: it maps cursor to
+            // node.start (between runs, a valid insertion point), whereas the
+            // interior byte here would point inside <w:t> where inserting
+            // commentRangeStart/End would corrupt the text node.
+            boundaries.set(cursor, byte);
+          }
+          const ch = sourceXml.charCodeAt(byte);
+          if (ch === 0x26 /* & */) {
+            const semi = sourceXml.indexOf(";", byte + 1);
+            if (semi !== -1 && semi < end) {
+              byte = semi + 1;
+            } else {
+              byte += 1;
+            }
+          } else if (ch >= 0xd800 && ch <= 0xdbff && byte + 1 < end) {
+            // High surrogate followed by low surrogate = 1 code point / 2 units.
+            byte += 2;
+          } else {
+            byte += 1;
+          }
+          cursor += 1;
+        }
+        // Trailing boundary: map the cursor immediately after the last
+        // character to the byte just before </w:t>, so an anchor at the right
+        // edge of this text node resolves inside the run. The outer <w:r>
+        // close will overwrite nothing here because it runs after the inner
+        // walk and uses boundaries.set (last-write-wins is fine: node.end
+        // points to the same logical insertion point between runs).
+        if (!boundaries.has(cursor)) {
+          boundaries.set(cursor, end);
+        }
+      }
+      setCursor(cursor);
       return;
     }
     case "tab":

package/src/io/paste/word-clipboard.ts

@@ -0,0 +1,114 @@
+/**
+ * I2 Tier B Slice 2 — Office-clipboard / WordprocessingML paste parser.
+ *
+ * Adapts the authoritative `parseMainDocumentXml` → `normalizeParsedTextDocument`
+ * pipeline to a clipboard-paste payload. Inputs from the browser clipboard under
+ * the Office MIME types (`application/x-docx-fragment`,
+ * `application/vnd.ms-word.wordprocessingml.paste`) arrive either as:
+ *
+ *   - a full `<w:document><w:body>…</w:body></w:document>` wrapper, or
+ *   - a bare `<w:body>…</w:body>` fragment.
+ *
+ * This adapter auto-wraps the bare form, runs the full parse + normalize, and
+ * returns the resulting canonical `BlockNode`s as a `CanonicalDocumentFragment`.
+ * Errors (XML parse failure, missing body) are returned as a structured result
+ * instead of thrown, so `pm-command-bridge.ts` `handlePaste` can gracefully fall
+ * through to HTML or plain-text Tier A.
+ */
+
+import type { CanonicalDocumentFragment } from "../../api/public-types.ts";
+import type { DocumentRootNode } from "../../model/canonical-document.ts";
+import { parseMainDocumentXml } from "../ooxml/parse-main-document.ts";
+import { normalizeParsedTextDocument } from "../normalize/normalize-text.ts";
+import { serializeMainDocument } from "../export/serialize-main-document.ts";
+
+export type ParseCanonicalFragmentResult =
+  | { ok: true; fragment: CanonicalDocumentFragment }
+  | { ok: false; reason: string };
+
+const WORD_NS = `xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"`;
+
+export function parseCanonicalFragmentFromWordML(xml: string): ParseCanonicalFragmentResult {
+  if (typeof xml !== "string" || xml.length === 0) {
+    return { ok: false, reason: "empty WordML payload" };
+  }
+
+  const prepared = ensureDocumentShell(xml);
+
+  try {
+    const parsed = parseMainDocumentXml(prepared);
+    const normalized = normalizeParsedTextDocument(parsed);
+    return {
+      ok: true,
+      fragment: { blocks: normalized.content.children },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : "unknown WordML parse error",
+    };
+  }
+}
+
+/**
+ * Normalize the incoming clipboard payload into a full `<w:document><w:body>…`
+ * shell. Handles three shapes:
+ *
+ *   1. Already-wrapped `<w:document>…</w:document>` → pass-through with the XML
+ *      declaration normalized.
+ *   2. Bare `<w:body>…</w:body>` — wrap in `<w:document>…</w:document>`.
+ *   3. Any other fragment — wrap the whole input in `<w:document><w:body>…`.
+ *
+ * Namespace hygiene: if the input lacks the `xmlns:w` declaration on whatever
+ * outer element survives, it's added to the outer `<w:document>` wrapper.
+ */
+function ensureDocumentShell(xml: string): string {
+  const trimmed = xml.trim();
+  const withoutDecl = trimmed.replace(/^<\?xml[^?]*\?>/, "").trim();
+
+  const hasDocumentWrapper = /^<w:document[\s>]/i.test(withoutDecl);
+  if (hasDocumentWrapper) {
+    return ensureXmlDecl(trimmed);
+  }
+
+  const hasBodyWrapper = /^<w:body[\s>]/i.test(withoutDecl);
+  const inner = hasBodyWrapper ? withoutDecl : `<w:body>${withoutDecl}</w:body>`;
+
+  const wrapped = `<w:document ${WORD_NS}>${stripRedundantNs(inner)}</w:document>`;
+  return ensureXmlDecl(wrapped);
+}
+
+function ensureXmlDecl(xml: string): string {
+  if (/^\s*<\?xml/.test(xml)) return xml;
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>${xml}`;
+}
+
+/**
+ * Strip `xmlns:w="…"` from the first child element so the outer
+ * `<w:document>` declaration is the single authoritative binding. The XML
+ * parser accepts both, but removing the duplicate keeps output clean.
+ */
+function stripRedundantNs(xml: string): string {
+  return xml.replace(/\s+xmlns:w="[^"]*"/, "");
+}
+
+/**
+ * I2 Tier B Slice 4a — inverse of `parseCanonicalFragmentFromWordML`. Produces
+ * a full `<w:document><w:body>…</w:body></w:document>` payload suitable for
+ * writing to the system clipboard under the Office MIME types, or for exchange
+ * with agents that expect WordML.
+ *
+ * Implementation reuses the authoritative `serializeMainDocument` pipeline by
+ * wrapping `fragment.blocks` in a synthetic `DocumentRootNode`. The output is
+ * the full document XML — parsers (browsers, Word, our own Slice 2 adapter)
+ * accept the full envelope, so there's no need to strip it down to a bare
+ * `<w:body>` fragment.
+ */
+export function serializeFragmentToWordML(fragment: CanonicalDocumentFragment): string {
+  const root: DocumentRootNode = {
+    type: "doc",
+    children: fragment.blocks,
+  };
+  const serialized = serializeMainDocument(root);
+  return serialized.documentXml;
+}

package/src/runtime/document-runtime.ts

@@ -30,6 +30,7 @@ import type {
   DocumentTextToken,
   EditorSessionState,
   EditorAnchorProjection,
+  CanonicalDocumentFragment,
   TextFormattingDirective,
   EditorError,
   EditorStoryTarget,
@@ -266,7 +267,8 @@ export type ActiveStoryTextCommand =
   | Extract<EditorCommand, { type: "text.insert-tab" }>
   | Extract<EditorCommand, { type: "text.outdent-tab" }>
   | Extract<EditorCommand, { type: "text.insert-hard-break" }>
-  | Extract<EditorCommand, { type: "paragraph.split" }>;
+  | Extract<EditorCommand, { type: "paragraph.split" }>
+  | Extract<EditorCommand, { type: "fragment.insert" }>;
 
 export interface DocumentRuntime {
   subscribe(listener: () => void): Unsubscribe;
@@ -275,6 +277,7 @@ export interface DocumentRuntime {
   getCanonicalDocument(): CanonicalDocumentEnvelope;
   getSourcePackage(): EditorSessionState["sourcePackage"] | undefined;
   replaceText(text: string, target?: EditorAnchorProjection, formatting?: TextFormattingDirective): void;
+  insertFragment(fragment: CanonicalDocumentFragment, target?: EditorAnchorProjection): void;
   applyActiveStoryTextCommand(command: ActiveStoryTextCommand): TextCommandAck;
   dispatch(command: EditorCommand): void;
   /**
@@ -2314,6 +2317,26 @@ export function createDocumentRuntime(
         emitError(toRuntimeError(error));
       }
     },
+    insertFragment(fragment, target) {
+      // I2 Tier B Slice 1 — dispatch `fragment.insert` against the active story. The
+      // runtime command handler routes into `applyFragmentInsert` (structure-ops).
+      try {
+        const timestamp = clock();
+        applyTextCommandInActiveStory(
+          {
+            type: "fragment.insert",
+            fragment,
+            origin: createOrigin("api", timestamp),
+          },
+          {
+            selection: target ? createSelectionFromPublicAnchor(target) : state.selection,
+            blockedCommandName: "insertFragment",
+          },
+        );
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
     applyActiveStoryTextCommand(command) {
       try {
         return applyTextCommandInActiveStory(command);

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

@@ -42,8 +42,59 @@
  *       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.
+ *   6 — Lane 3a P9 Phase A. `RenderAnchorIndex` gains three chrome-kind
+ *       resolvers (`byScopeId`, `byCommentId`, `byRevisionId`) sourced
+ *       from the resolved `DecorationIndex`, and `buildAnchorIndex`
+ *       runs in two phases inside the render kernel so the final index
+ *       carries decoration-aware lookups. No cached-geometry change;
+ *       consumers (Lane 1 R.1 SelectionLayer, Lane 6 P11 chrome rails)
+ *       can now query one unified API instead of reaching into
+ *       `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 = 5 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/layout/public-facet.ts

@@ -1824,22 +1824,15 @@ function resolveAnchorRects(
       return rect ? [rect] : [];
     }
     case "scope-id": {
-      const id = String(query.value);
-      return frame.decorationIndex.workflow
-        .filter((decoration) => decoration.refId === id)
-        .map((decoration) => decoration.frame);
+      return frame.anchorIndex.byScopeId(String(query.value));
     }
     case "comment-id": {
-      const id = String(query.value);
-      return frame.decorationIndex.comments
-        .filter((decoration) => decoration.refId === id)
-        .map((decoration) => decoration.frame);
+      const rect = frame.anchorIndex.byCommentId(String(query.value));
+      return rect ? [rect] : [];
     }
     case "revision-id": {
-      const id = String(query.value);
-      return frame.decorationIndex.revisions
-        .filter((decoration) => decoration.refId === id)
-        .map((decoration) => decoration.frame);
+      const rect = frame.anchorIndex.byRevisionId(String(query.value));
+      return rect ? [rect] : [];
     }
     default: {
       const exhaustive: never = query.kind;

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,