@beyondwork/docx-react-component 1.0.50 → 1.0.52

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,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.50",
+  "version": "1.0.52",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
+  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -92,6 +93,35 @@
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css"
   },
   "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "node scripts/ci-check-layout-engine-version.mjs && node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
+    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
+    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
+    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
+    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
+    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  },
   "keywords": [
     "docx",
     "word",
@@ -175,33 +205,14 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/ci-check-layout-engine-version.mjs && node scripts/run-repo-tests.mjs core",
-    "test:repo:all": "node scripts/run-repo-tests.mjs all",
-    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
-    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
-    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
-    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
-    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
-    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
-    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
-    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "sharp"
+    ],
+    "overrides": {
+      "react": "19.2.4",
+      "react-dom": "19.2.4"
+    }
   }
 }

package/src/api/public-types.ts

@@ -3025,6 +3025,15 @@ export interface WordReviewEditorRef {
   setImageFrame(mediaId: string, offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number }): void;
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
+  /**
+   * Read the current runtime-backed `WorkflowOverlay`, or `null` when no
+   * overlay is active.  Hosts use this for read-modify-write flows against
+   * `setWorkflowOverlay(...)` — notably to preserve engine-authored scopes
+   * minted via `addScope(...)` when updating candidates / work items.
+   * Returns a defensive clone; mutating the returned object does not affect
+   * runtime state.
+   */
+  getWorkflowOverlay(): WorkflowOverlay | null;
   setSharedWorkflowState(state: SharedWorkflowState | null): void;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;

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,