@beyondwork/docx-react-component 1.0.49 → 1.0.51

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

@@ -230,6 +230,20 @@ export interface RenderAnchorIndex {
     tableBlockId: string,
     rowIndex: number,
   ): RenderFrameRect | null;
+  /**
+   * Chrome-kind resolvers (P9 Phase A). Read against the frame's
+   * `decorationIndex` so chrome surfaces (scope rails, comment balloons,
+   * revision margin bars, Lane 1 R.1 SelectionLayer) query one unified
+   * API instead of reaching into `frame.decorationIndex` directly.
+   *
+   * `byScopeId` returns every rect because a single workflow scope may
+   * cover multiple pages (one `RenderBlockDecoration` per page); chrome
+   * rails read the list. `byCommentId` and `byRevisionId` return a single
+   * rect — `resolveDecorationIndex` emits one entry per thread/revision.
+   */
+  byScopeId(scopeId: string): readonly RenderFrameRect[];
+  byCommentId(commentId: string): RenderFrameRect | null;
+  byRevisionId(revisionId: string): RenderFrameRect | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -280,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) => {
@@ -192,7 +198,16 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
     }
 
     const pendingDeltas = input.getPendingOpDeltas?.() ?? [];
-    const anchorIndex = buildAnchorIndex(renderPages, pendingDeltas, zoom.pxPerTwip);
+    // P9 Phase A — two-phase anchor-index build. The decoration resolver
+    // reads the anchor index to map runtime ranges to frame rects; the
+    // final anchor index then exposes chrome-kind resolvers that read
+    // back from the resolved decoration index. Rebuilding the index with
+    // the resolved decoration data avoids a post-hoc mutation seam.
+    const baseAnchorIndex = buildAnchorIndex(
+      renderPages,
+      pendingDeltas,
+      zoom.pxPerTwip,
+    );
     const includeDecorations = options?.includeDecorations ?? true;
     const sources = input.getDecorationSources?.();
     const hasSources =
@@ -205,8 +220,14 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
     const decorationIndex: DecorationIndex = !includeDecorations
       ? EMPTY_DECORATION_INDEX
       : hasSources
-        ? resolveDecorationIndex({ anchorIndex, ...sources })
+        ? resolveDecorationIndex({ anchorIndex: baseAnchorIndex, ...sources })
         : buildDecorationIndex(renderPages);
+    const anchorIndex = buildAnchorIndex(
+      renderPages,
+      pendingDeltas,
+      zoom.pxPerTwip,
+      decorationIndex,
+    );
 
     // Revision: keyed off the engine's current page graph so repeated reads
     // at the same revision return the same cached frame.  We derive it
@@ -239,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;
     },
@@ -634,6 +669,7 @@ function buildAnchorIndex(
   pages: readonly RenderPage[],
   pendingDeltas: readonly PendingOpDelta[] = [],
   pxPerTwip = 1,
+  decorationIndex: DecorationIndex = EMPTY_DECORATION_INDEX,
 ): RenderAnchorIndex {
   const byRuntimeOffset = new Map<number, RenderFrameRect>();
   const byFragmentId = new Map<string, RenderFrameRect>();
@@ -672,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;
@@ -718,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;
@@ -739,6 +785,28 @@ function buildAnchorIndex(
     byTableRowEdge(tableBlockId, rowIndex) {
       return tableRowEdges.get(`${tableBlockId}:${rowIndex}`) ?? null;
     },
+    // P9 Phase A — chrome-kind resolvers sourced from the resolved
+    // decoration index. Empty by default (the initial frame build passes
+    // `EMPTY_DECORATION_INDEX` until decoration resolution runs); the
+    // kernel re-invokes `buildAnchorIndex` with the resolved index so the
+    // final anchor index carries chrome-aware lookups.
+    byScopeId(scopeId) {
+      return decorationIndex.workflow
+        .filter((decoration) => decoration.refId === scopeId)
+        .map((decoration) => decoration.frame);
+    },
+    byCommentId(commentId) {
+      const match = decorationIndex.comments.find(
+        (decoration) => decoration.refId === commentId,
+      );
+      return match?.frame ?? null;
+    },
+    byRevisionId(revisionId) {
+      const match = decorationIndex.revisions.find(
+        (decoration) => decoration.refId === revisionId,
+      );
+      return match?.frame ?? null;
+    },
   };
 }