@beyondwork/docx-react-component 1.0.50 → 1.0.52

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 };
 

package/src/runtime/render/render-kernel.ts

@@ -36,6 +36,7 @@ import {
   type SearchMatchRange,
 } from "./decoration-resolver.ts";
 import { classifyBlockKind as classifyBlockKindFromId } from "./block-fragment-projection.ts";
+import { diffRenderFrames } from "./render-frame-diff.ts";
 import {
   EMPTY_DECORATION_INDEX,
   defaultChromeReservations,
@@ -141,6 +142,11 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
   const getActiveStory = input.getActiveStory ?? (() => MAIN_STORY_TARGET);
   let zoom: RenderZoom = input.initialZoom ?? resolveDefaultZoom();
   let cache: { revision: number; frame: RenderFrame } | null = null;
+  // P10 Phase B — retained across `invalidate()` and `cache = null` so
+  // `frame_diff` can compute a meaningful diff when the next build
+  // produces a structurally-equal frame. Distinct from `cache`, which
+  // is an optimizer for repeat reads at the same revision.
+  let lastEmittedFrame: RenderFrame | null = null;
 
   const listeners = new Set<(event: RenderKernelEvent) => void>();
   const unsubscribeFacet = facet.subscribe((event) => {
@@ -254,6 +260,20 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
       if (options === undefined) {
         cache = { revision: frame.revision, frame };
         emit({ kind: "frame_built", revision: frame.revision, reason: "full" });
+        // P10 Phase B — compute structural diff vs. the last emitted
+        // frame (retained across `invalidate()`) so page-stack consumers
+        // can skip React reconciliation on unchanged pages even after
+        // a cache invalidation. On cold start (no prior emission) the
+        // diff reports every page in `addedPages`, giving the initial
+        // mount a consistent subscription contract.
+        const diffT0 =
+          typeof performance !== "undefined" ? performance.now() : 0;
+        const diff = diffRenderFrames(lastEmittedFrame, frame);
+        if (diffT0 > 0) {
+          recordPerfSample("render.frame_diff", performance.now() - diffT0);
+        }
+        emit({ kind: "frame_diff", revision: frame.revision, diff });
+        lastEmittedFrame = frame;
       }
       return frame;
     },
@@ -688,25 +708,31 @@ function buildAnchorIndex(
     }
   }
 
-  // Pending-op deltas are read here as a seam for a future decoration-
-  // resolver-driven rect shift; today the kernel does not mutate rects
-  // during the predicted-dispatch window because the correct reconciliation
-  // belongs to R4's decoration resolver (it needs per-line width info the
-  // MVP doesn't surface yet).  The deltas are still read so consumers can
-  // rely on the accessor shape landing now.
-  void pendingDeltas;
+  // P9 Phase A2 — during the predicted-dispatch window, runtime offsets
+  // passed in by chrome surfaces reflect the visible (predicted) text but
+  // the anchor-index maps are keyed on the *pre-delta* runtime offsets
+  // emitted by the last-committed page graph. Shift the lookup offset
+  // back by the sum of deltas applied at or before it so chrome rects
+  // stay aligned with the caret while the predicted text is on screen.
+  // The rect pixel positions are correct as drawn — only the offset →
+  // rect mapping needs compensation.
+  const shiftForDeltas = (offset: number): number => {
+    if (pendingDeltas.length === 0) return offset;
+    return offset - sumDeltasBefore(pendingDeltas, offset);
+  };
 
   const resolveByRuntimeOffset = (
     offset: number,
     _story?: EditorStoryTarget,
   ): RenderFrameRect | null => {
     void _story;
-    const exact = byRuntimeOffset.get(offset);
+    const lookup = shiftForDeltas(offset);
+    const exact = byRuntimeOffset.get(lookup);
     if (exact) return exact;
     let best: RenderFrameRect | null = null;
     let bestDistance = Number.POSITIVE_INFINITY;
     for (const [key, rect] of byRuntimeOffset) {
-      const distance = Math.abs(key - offset);
+      const distance = Math.abs(key - lookup);
       if (distance < bestDistance) {
         best = rect;
         bestDistance = distance;
@@ -734,9 +760,13 @@ function buildAnchorIndex(
       if (lo === hi) {
         return resolveByRuntimeOffset(lo, story);
       }
+      // Shift range endpoints back to pre-delta space before iterating
+      // the anchor maps (see `shiftForDeltas` rationale above).
+      const loShifted = shiftForDeltas(lo);
+      const hiShifted = shiftForDeltas(hi);
       let union: RenderFrameRect | null = null;
       for (const [key, rect] of byRuntimeOffset) {
-        if (key < lo || key >= hi) continue;
+        if (key < loShifted || key >= hiShifted) continue;
         union = unionRects(union, rect);
       }
       if (union) return union;

package/src/runtime/selection/cursor-ops.ts

@@ -0,0 +1,202 @@
+/**
+ * R.1 Phase 6a — SelectionLayer cursor primitives.
+ *
+ * Pure functions over `(DocumentRootNode, CursorSelection, op) → CursorSelection`.
+ * `extend: true` keeps the anchor fixed and moves only the head — the
+ * LibreOffice `SwPaM` head/anchor split that matches Shift+arrow semantics.
+ *
+ * Positions are 0-based logical positions per the canonical story layer
+ * (`createPlainText(parseTextStory(doc))`). Scope markers are zero-width;
+ * paragraph breaks are 1 wide; text / tab / hard_break / image / opaque are 1
+ * wide. The plain-text string produced by `createPlainText` is a 1:1 mapping
+ * of those logical positions to characters, which makes position-math trivial
+ * and makes `Intl.Segmenter` (for word boundaries) a drop-in fit.
+ *
+ * What this module deliberately does NOT ship yet:
+ *   - `moveUp` / `moveDown` — genuinely layout-dependent (need column tracking
+ *     + line-wrap info). Follows Phase 6b once Lane 3a P9 exposes the per-run
+ *     layout facet needed for column-preserving movement.
+ *   - `moveLineStart` / `moveLineEnd` — same; these need soft-wrap info that
+ *     the canonical story layer does not expose.
+ */
+
+import { createPlainText, parseTextStory } from "../../core/schema/text-schema.ts";
+import type { DocumentRootNode } from "../../model/canonical-document.ts";
+
+export interface CursorSelection {
+  anchor: number;
+  head: number;
+}
+
+export interface CursorMoveOptions {
+  /**
+   * When true, the anchor stays fixed and only the head moves — matches
+   * Shift+arrow "extend selection" semantics. When false (default), both
+   * anchor and head land at the new head, collapsing any range selection.
+   */
+  extend?: boolean;
+}
+
+export function moveCharLeft(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  // Word semantics (no-extend): a range selection collapses to the LEFT edge
+  // without moving; only a collapsed caret actually decrements by one.
+  if (!options.extend && selection.anchor !== selection.head) {
+    const leftEdge = Math.min(selection.anchor, selection.head);
+    return { anchor: leftEdge, head: leftEdge };
+  }
+  const currentHead = selection.head;
+  const nextHead = Math.max(0, currentHead - 1);
+  return finalize(selection, nextHead, options);
+}
+
+export function moveCharRight(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  // Word semantics (no-extend): a range selection collapses to the RIGHT edge
+  // without moving; only a collapsed caret actually increments by one.
+  if (!options.extend && selection.anchor !== selection.head) {
+    const rightEdge = Math.max(selection.anchor, selection.head);
+    return { anchor: rightEdge, head: rightEdge };
+  }
+  const currentHead = selection.head;
+  const nextHead = Math.min(text.length, currentHead + 1);
+  return finalize(selection, nextHead, options);
+}
+
+export function moveParagraphStart(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const head = options.extend ? selection.head : selection.head;
+  // Walk backward until we find a paragraph break ('\n') or reach 0. The
+  // paragraph start is the character immediately after the break.
+  let cursor = Math.max(0, Math.min(text.length, head));
+  while (cursor > 0 && text[cursor - 1] !== "\n") {
+    cursor -= 1;
+  }
+  return finalize(selection, cursor, options);
+}
+
+export function moveParagraphEnd(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const head = options.extend ? selection.head : selection.head;
+  let cursor = Math.max(0, Math.min(text.length, head));
+  while (cursor < text.length && text[cursor] !== "\n") {
+    cursor += 1;
+  }
+  return finalize(selection, cursor, options);
+}
+
+/**
+ * `Intl.Segmenter` with `granularity: "word"` returns ICU word boundaries —
+ * the standards-backed equivalent of LibreOffice's `SwBreakIt`. We walk the
+ * boundary list (cached per-`doc` call) to find the next / previous
+ * word-start relative to the head, matching Word's Ctrl+arrow behavior.
+ *
+ * Word semantics:
+ *   - Ctrl+Right: jump to the end of the current word, OR to the end of the
+ *     next word if already at word-end. In practice we land on the next
+ *     word-boundary strictly greater than the current head.
+ *   - Ctrl+Left: jump to the start of the current word, OR to the start of
+ *     the previous word if already at word-start. We land on the previous
+ *     word-boundary strictly less than the current head.
+ */
+export function moveWordRight(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const currentHead = options.extend
+    ? selection.head
+    : Math.max(selection.anchor, selection.head);
+  const boundaries = wordBoundaries(text);
+  const nextBoundary =
+    boundaries.find((pos) => pos > currentHead) ?? text.length;
+  return finalize(selection, nextBoundary, options);
+}
+
+export function moveWordLeft(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const currentHead = options.extend
+    ? selection.head
+    : Math.min(selection.anchor, selection.head);
+  const boundaries = wordBoundaries(text);
+  let prevBoundary = 0;
+  for (const pos of boundaries) {
+    if (pos >= currentHead) break;
+    prevBoundary = pos;
+  }
+  return finalize(selection, prevBoundary, options);
+}
+
+function finalize(
+  selection: CursorSelection,
+  head: number,
+  options: CursorMoveOptions,
+): CursorSelection {
+  if (options.extend) {
+    return { anchor: selection.anchor, head };
+  }
+  return { anchor: head, head };
+}
+
+function documentPlainText(doc: DocumentRootNode): string {
+  const story = parseTextStory(doc);
+  return createPlainText(story);
+}
+
+/**
+ * `Intl.Segmenter` is available in Node 16+ and all modern browsers. We lazy-
+ * init the default-locale instance; word segmentation is stateless, so one
+ * segmenter per process is fine.
+ */
+let cachedSegmenter: Intl.Segmenter | undefined;
+function wordSegmenter(): Intl.Segmenter {
+  if (!cachedSegmenter) {
+    cachedSegmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+  }
+  return cachedSegmenter;
+}
+
+/**
+ * Produce the sorted list of word-boundary positions in `text`. A boundary is
+ * the start of any segment whose `isWordLike` is true, plus the end-of-text.
+ * Whitespace and punctuation segments are skipped so caret jumps land on
+ * word endpoints rather than stopping at every space — matching Word's
+ * Ctrl+arrow behavior.
+ */
+function wordBoundaries(text: string): number[] {
+  const segments = wordSegmenter().segment(text);
+  const boundaries: number[] = [];
+  for (const segment of segments) {
+    if (segment.isWordLike) {
+      // Add both the start and the end of each word-like segment so
+      // Ctrl+Right from "hello|world" (between two words) advances to the end
+      // of "world" rather than stopping at the start.
+      boundaries.push(segment.index);
+      boundaries.push(segment.index + segment.segment.length);
+    }
+  }
+  // Dedup + sort so callers can binary-search or linear-walk deterministically.
+  boundaries.push(text.length);
+  return Array.from(new Set(boundaries)).sort((a, b) => a - b);
+}