@beyondwork/docx-react-component 1.0.37 → 1.0.38

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

@@ -0,0 +1,755 @@
+/**
+ * Render kernel (Phase R1 MVP).
+ *
+ * Projects the runtime-owned layout engine's page graph into a
+ * `RenderFrame` that every chrome surface reads.  Keeps workflow scope
+ * and decoration projection minimal so consumers can land on a stable
+ * shape while the richer projectors (line-box per run, decoration
+ * resolver, frame diff, table render plan) are built out in R1 and R4.
+ *
+ * Ownership:
+ *   - the kernel is a pure projection over the layout facet.  It never
+ *     mutates runtime or layout state.
+ *   - it never consults the DOM.  Zoom/viewport come in as input.
+ */
+
+import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
+import type { EditorStoryTarget } from "../../api/public-types";
+import type {
+  PublicPageNode,
+  WordReviewEditorLayoutFacet,
+} from "../layout/public-facet.ts";
+import type {
+  CommentDecorationModel,
+} from "../../ui/headless/comment-decoration-model.ts";
+import type {
+  RevisionDecorationModel,
+} from "../../ui/headless/revision-decoration-model.ts";
+import type { ScopeRailSegment } from "../workflow-rail-segments.ts";
+import {
+  resolveDecorationIndex,
+  type LockedRangeInput,
+  type SearchMatchRange,
+} from "./decoration-resolver.ts";
+import { classifyBlockKind as classifyBlockKindFromId } from "./block-fragment-projection.ts";
+import {
+  EMPTY_DECORATION_INDEX,
+  defaultChromeReservations,
+  resolveDefaultZoom,
+  type DecorationIndex,
+  type PageChromeReservations,
+  type RenderAnchorIndex,
+  type RenderBlock,
+  type RenderFrame,
+  type RenderFrameQueryOptions,
+  type RenderFrameRect,
+  type RenderKernelEvent,
+  type RenderLine,
+  type RenderLineAnchor,
+  type RenderPage,
+  type RenderPageRegions,
+  type RenderStoryRegion,
+  type RenderZoom,
+} from "./render-frame-types.ts";
+
+// ---------------------------------------------------------------------------
+// Kernel interface
+// ---------------------------------------------------------------------------
+
+export interface RenderKernel {
+  /** Build (or return from cache) the RenderFrame for a query. */
+  getRenderFrame(options?: RenderFrameQueryOptions): RenderFrame;
+  /** Active zoom the kernel uses when no zoom is supplied. */
+  getZoom(): RenderZoom;
+  /** Swap the zoom the kernel composes frames at. */
+  setZoom(zoom: RenderZoom): void;
+  /** Subscribe to kernel-scoped events. */
+  subscribe(listener: (event: RenderKernelEvent) => void): () => void;
+  /** Invalidate the cache so the next read rebuilds. */
+  invalidate(): void;
+}
+
+export interface CreateRenderKernelInput {
+  facet: WordReviewEditorLayoutFacet;
+  getActiveStory?: () => EditorStoryTarget;
+  /** Initial zoom; see `resolveDefaultZoom`. */
+  initialZoom?: RenderZoom;
+  /**
+   * Optional accessor for pending predicted-op deltas.  When supplied, the
+   * kernel shifts anchor resolution through these deltas so chrome
+   * overlays stay aligned with the visible (predicted) text during the
+   * predicted-dispatch window.  Returns `+N` for insert, `-N` for delete.
+   */
+  getPendingOpDeltas?: () => readonly PendingOpDelta[];
+  /**
+   * Optional decoration sources.  When any of these is supplied, the
+   * kernel invokes `resolveDecorationIndex` to populate
+   * `RenderFrame.decorationIndex` with per-decoration anchor rects so
+   * chrome surfaces can read them directly instead of re-projecting.  When
+   * all are omitted, the kernel falls back to the MVP walk over
+   * `block.blockDecorations` (typically empty today).
+   */
+  getDecorationSources?: () => DecorationSources;
+}
+
+/**
+ * Canonical decoration sources the kernel aggregates into
+ * `DecorationIndex`.  Every field is optional; unspecified lanes stay
+ * empty.
+ */
+export interface DecorationSources {
+  workflowSegments?: readonly ScopeRailSegment[];
+  comments?: CommentDecorationModel | null | undefined;
+  revisions?: RevisionDecorationModel | null | undefined;
+  searchMatches?: readonly SearchMatchRange[];
+  lockedRanges?: readonly LockedRangeInput[];
+}
+
+export interface PendingOpDelta {
+  /** Runtime offset at which the op was applied. */
+  fromRuntime: number;
+  /** Signed character delta applied at that offset. */
+  delta: number;
+}
+
+/**
+ * Sum the pending-op deltas that apply at or before a runtime offset.  Used
+ * by the kernel's anchor index to shift anchor resolution during the
+ * predicted-dispatch window.
+ */
+export function sumDeltasBefore(
+  deltas: readonly PendingOpDelta[],
+  runtimeOffset: number,
+): number {
+  let total = 0;
+  for (const d of deltas) {
+    if (d.fromRuntime <= runtimeOffset) total += d.delta;
+  }
+  return total;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel {
+  const { facet } = input;
+  const getActiveStory = input.getActiveStory ?? (() => MAIN_STORY_TARGET);
+  let zoom: RenderZoom = input.initialZoom ?? resolveDefaultZoom();
+  let cache: { revision: number; frame: RenderFrame } | null = null;
+
+  const listeners = new Set<(event: RenderKernelEvent) => void>();
+  const unsubscribeFacet = facet.subscribe((event) => {
+    // Any layout-changing event invalidates the cached frame.  We rely on
+    // the frame cache check below rather than rebuilding eagerly so single
+    // layout events don't produce multiple kernel builds.
+    if (
+      event.kind === "layout_recomputed" ||
+      event.kind === "incremental_relayout" ||
+      event.kind === "measurement_backend_ready" ||
+      event.kind === "zoom_changed"
+    ) {
+      cache = null;
+    }
+  });
+  void unsubscribeFacet;
+
+  function emit(event: RenderKernelEvent): void {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch {
+        // never let listener errors break the kernel
+      }
+    }
+  }
+
+  function buildFrame(options?: RenderFrameQueryOptions): RenderFrame {
+    const activeStory = options?.story ?? getActiveStory();
+    const measurementFidelity = facet.getMeasurementFidelity();
+    const rawPages = facet.getPages();
+    const pageRange = options?.pageRange;
+    const filteredPages = pageRange
+      ? rawPages.filter(
+          (p) =>
+            p.pageIndex >= pageRange.fromPageIndex &&
+            p.pageIndex <= pageRange.toPageIndex,
+        )
+      : rawPages;
+
+    // Compose pages sequentially with a running y-cursor in pixels.
+    let y = 0;
+    const renderPages: RenderPage[] = [];
+    for (const page of filteredPages) {
+      const renderPage = buildPage(page, y, zoom, activeStory, facet);
+      renderPages.push(renderPage);
+      y += renderPage.frame.heightPx + PAGE_GAP_PX;
+    }
+
+    const pendingDeltas = input.getPendingOpDeltas?.() ?? [];
+    const anchorIndex = buildAnchorIndex(renderPages, pendingDeltas, zoom.pxPerTwip);
+    const includeDecorations = options?.includeDecorations ?? true;
+    const sources = input.getDecorationSources?.();
+    const hasSources =
+      sources !== undefined &&
+      ((sources.workflowSegments && sources.workflowSegments.length > 0) ||
+        (sources.comments?.threads?.length ?? 0) > 0 ||
+        (sources.revisions?.revisions?.length ?? 0) > 0 ||
+        (sources.searchMatches && sources.searchMatches.length > 0) ||
+        (sources.lockedRanges && sources.lockedRanges.length > 0));
+    const decorationIndex: DecorationIndex = !includeDecorations
+      ? EMPTY_DECORATION_INDEX
+      : hasSources
+        ? resolveDecorationIndex({ anchorIndex, ...sources })
+        : buildDecorationIndex(renderPages);
+
+    // Revision: keyed off the engine's current page graph so repeated reads
+    // at the same revision return the same cached frame.  We derive it
+    // from the first page since the engine stamps every page with the
+    // graph's revision indirectly via pageId; fall back to 0 if empty.
+    const revision = filteredPages[0]
+      ? Number(extractRevisionFromPageId(filteredPages[0].pageId))
+      : 0;
+
+    return {
+      revision: Number.isFinite(revision) ? revision : 0,
+      measurementFidelity,
+      activeStory,
+      zoom: { ...zoom },
+      pages: renderPages,
+      decorationIndex,
+      anchorIndex,
+    };
+  }
+
+  return {
+    getRenderFrame(options) {
+      const rebuild = options !== undefined || cache === null;
+      if (!rebuild && cache) {
+        return cache.frame;
+      }
+      const frame = buildFrame(options);
+      if (options === undefined) {
+        cache = { revision: frame.revision, frame };
+        emit({ kind: "frame_built", revision: frame.revision, reason: "full" });
+      }
+      return frame;
+    },
+
+    getZoom() {
+      return { ...zoom };
+    },
+
+    setZoom(next) {
+      zoom = { ...next };
+      cache = null;
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    invalidate() {
+      cache = null;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+const PAGE_GAP_PX = 16;
+
+function buildPage(
+  page: PublicPageNode,
+  topPx: number,
+  zoom: RenderZoom,
+  activeStory: EditorStoryTarget,
+  facet: WordReviewEditorLayoutFacet,
+): RenderPage {
+  const layout = page.layout;
+  const widthPx = layout.pageWidth * zoom.pxPerTwip;
+  const heightPx = layout.pageHeight * zoom.pxPerTwip;
+
+  const frame: RenderFrameRect = {
+    leftPx: 0,
+    topPx,
+    widthPx,
+    heightPx,
+  };
+
+  const bodyRegion: RenderStoryRegion = buildBodyRegion(
+    page,
+    topPx,
+    zoom,
+    activeStory,
+    facet,
+  );
+
+  const regions: RenderPageRegions = {
+    body: bodyRegion,
+  };
+
+  if (page.stories.header) {
+    regions.header = buildHeaderFooterRegion(
+      page,
+      topPx,
+      zoom,
+      "header",
+      page.stories.header,
+    );
+  }
+  if (page.stories.footer) {
+    regions.footer = buildHeaderFooterRegion(
+      page,
+      topPx,
+      zoom,
+      "footer",
+      page.stories.footer,
+    );
+  }
+
+  const chromeReservations: PageChromeReservations = {
+    ...defaultChromeReservations(layout, zoom),
+  };
+
+  return {
+    page,
+    frame,
+    regions,
+    chromeReservations,
+  };
+}
+
+function buildBodyRegion(
+  page: PublicPageNode,
+  pageTopPx: number,
+  zoom: RenderZoom,
+  activeStory: EditorStoryTarget,
+  facet: WordReviewEditorLayoutFacet,
+): RenderStoryRegion {
+  const layout = page.layout;
+  const bodyLeftTwips = layout.marginLeft;
+  const bodyTopTwips = layout.marginTop;
+  const bodyWidthTwips = page.regions.body.widthTwips;
+  const bodyHeightTwips = page.regions.body.heightTwips;
+
+  const regionFrame: RenderFrameRect = {
+    leftPx: bodyLeftTwips * zoom.pxPerTwip,
+    topPx: pageTopPx + bodyTopTwips * zoom.pxPerTwip,
+    widthPx: bodyWidthTwips * zoom.pxPerTwip,
+    heightPx: bodyHeightTwips * zoom.pxPerTwip,
+  };
+
+  const fragments = facet.getFragmentsForPage(page.pageIndex);
+  const bodyLineBoxes = facet.getLineBoxes(page.pageIndex, { region: "body" });
+
+  // Current layout engine does not track per-fragment line boxes with
+  // baselines that have been laid out against a cursor.  The kernel
+  // distributes height across fragments proportional to their
+  // `heightTwips`, giving chrome a stable anchor per block; richer
+  // per-line projection lands with the full kernel in later phases.
+  const blocks: RenderBlock[] = [];
+  let blockY = regionFrame.topPx;
+  const totalFragmentHeight = fragments.reduce(
+    (acc, fragment) => acc + Math.max(0, fragment.heightTwips),
+    0,
+  );
+
+  for (const fragment of fragments) {
+    if (fragment.regionKind !== "body") continue;
+    const fragmentHeightTwips = fragment.heightTwips > 0
+      ? fragment.heightTwips
+      : totalFragmentHeight === 0
+        ? bodyHeightTwips / Math.max(1, fragments.length)
+        : 0;
+    const blockHeightPx = fragmentHeightTwips * zoom.pxPerTwip;
+    const blockFrame: RenderFrameRect = {
+      leftPx: regionFrame.leftPx,
+      topPx: blockY,
+      widthPx: regionFrame.widthPx,
+      heightPx: blockHeightPx,
+    };
+
+    const blockLines = bodyLineBoxes
+      .filter((box) => box.fragmentId === fragment.fragmentId)
+      .map<RenderLine>((box) => {
+        const lineTopPx =
+          pageTopPx + (bodyTopTwips + box.baselineTwips) * zoom.pxPerTwip;
+        const lineFrame: RenderFrameRect = {
+          leftPx: regionFrame.leftPx,
+          topPx: lineTopPx,
+          widthPx: Math.min(
+            regionFrame.widthPx,
+            box.widthTwips * zoom.pxPerTwip,
+          ),
+          heightPx: box.heightTwips * zoom.pxPerTwip,
+        };
+        const anchors: RenderLineAnchor[] = [
+          {
+            runtimeOffset: fragment.from,
+            frame: lineFrame,
+            fragmentId: fragment.fragmentId,
+            blockId: fragment.blockId,
+          },
+        ];
+        return {
+          line: box,
+          frame: lineFrame,
+          anchors,
+        };
+      });
+
+    const kind = classifyBlockKindFromId(fragment.blockId);
+    const tablePlan =
+      kind === "table"
+        ? facet.getTableRenderPlan(fragment.blockId, page.pageIndex)
+        : undefined;
+
+    blocks.push({
+      fragment,
+      frame: blockFrame,
+      kind,
+      lines: blockLines,
+      blockDecorations: [],
+      ...(tablePlan !== undefined ? { tablePlan } : {}),
+    });
+
+    blockY += blockHeightPx;
+  }
+
+  return {
+    storyTarget: activeStory,
+    region: page.regions.body,
+    frame: regionFrame,
+    blocks,
+  };
+}
+
+function buildHeaderFooterRegion(
+  page: PublicPageNode,
+  pageTopPx: number,
+  zoom: RenderZoom,
+  kind: "header" | "footer",
+  storyTarget: EditorStoryTarget,
+): RenderStoryRegion {
+  const layout = page.layout;
+  const widthTwips =
+    layout.pageWidth - layout.marginLeft - layout.marginRight;
+  let topTwips = 0;
+  let heightTwips = 0;
+  if (kind === "header") {
+    topTwips = layout.headerMargin ?? 720;
+    heightTwips = Math.max(0, layout.marginTop - topTwips);
+  } else {
+    topTwips = layout.pageHeight - layout.marginBottom;
+    heightTwips = Math.max(0, layout.marginBottom - (layout.footerMargin ?? 720));
+  }
+
+  const frame: RenderFrameRect = {
+    leftPx: layout.marginLeft * zoom.pxPerTwip,
+    topPx: pageTopPx + topTwips * zoom.pxPerTwip,
+    widthPx: widthTwips * zoom.pxPerTwip,
+    heightPx: heightTwips * zoom.pxPerTwip,
+  };
+
+  const region = kind === "header" ? page.regions.header : page.regions.footer;
+  if (!region) {
+    return {
+      storyTarget,
+      region: {
+        kind,
+        originTwips: topTwips,
+        widthTwips,
+        heightTwips,
+        fragmentCount: 0,
+      },
+      frame,
+      blocks: [],
+    };
+  }
+
+  return {
+    storyTarget,
+    region,
+    frame,
+    blocks: [],
+  };
+}
+
+// classifyBlockKind moved to `./block-fragment-projection.ts` (P4).
+
+function buildAnchorIndex(
+  pages: readonly RenderPage[],
+  pendingDeltas: readonly PendingOpDelta[] = [],
+  pxPerTwip = 1,
+): RenderAnchorIndex {
+  const byRuntimeOffset = new Map<number, RenderFrameRect>();
+  const byFragmentId = new Map<string, RenderFrameRect>();
+  const byBlockId = new Map<string, RenderFrameRect>();
+  const byPageIndex = new Map<number, RenderFrameRect>();
+  // Per-table geometry: cell rects (key = `${blockId}:${row}:${col}`),
+  // column edges (key = `${blockId}:${columnIndex}`), row edges
+  // (key = `${blockId}:${rowIndex}`).
+  const tableCellRects = new Map<string, RenderFrameRect>();
+  const tableColumnEdges = new Map<string, RenderFrameRect>();
+  const tableRowEdges = new Map<string, RenderFrameRect>();
+
+  for (const page of pages) {
+    byPageIndex.set(page.page.pageIndex, page.frame);
+    for (const block of page.regions.body.blocks) {
+      byFragmentId.set(block.fragment.fragmentId, block.frame);
+      byBlockId.set(block.fragment.blockId, block.frame);
+      byRuntimeOffset.set(block.fragment.from, block.frame);
+      for (const line of block.lines) {
+        for (const anchor of line.anchors) {
+          byRuntimeOffset.set(anchor.runtimeOffset, anchor.frame);
+        }
+      }
+      // P4d: derive per-table cell/edge rects from the attached plan.
+      if (block.kind === "table" && block.tablePlan) {
+        recordTableAnchors(
+          block.fragment.blockId,
+          block.frame,
+          block.tablePlan,
+          pxPerTwip,
+          tableCellRects,
+          tableColumnEdges,
+          tableRowEdges,
+        );
+      }
+    }
+  }
+
+  // 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;
+
+  const resolveByRuntimeOffset = (
+    offset: number,
+    _story?: EditorStoryTarget,
+  ): RenderFrameRect | null => {
+    void _story;
+    const exact = byRuntimeOffset.get(offset);
+    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);
+      if (distance < bestDistance) {
+        best = rect;
+        bestDistance = distance;
+      }
+    }
+    return best;
+  };
+
+  return {
+    byRuntimeOffset(offset, story) {
+      return resolveByRuntimeOffset(offset, story);
+    },
+    byBlockId(blockId) {
+      return byBlockId.get(blockId) ?? null;
+    },
+    byFragmentId(fragmentId) {
+      return byFragmentId.get(fragmentId) ?? null;
+    },
+    byPageIndex(pageIndex) {
+      return byPageIndex.get(pageIndex) ?? null;
+    },
+    bySelection(fromOffset, toOffset, story) {
+      const lo = Math.min(fromOffset, toOffset);
+      const hi = Math.max(fromOffset, toOffset);
+      if (lo === hi) {
+        return resolveByRuntimeOffset(lo, story);
+      }
+      let union: RenderFrameRect | null = null;
+      for (const [key, rect] of byRuntimeOffset) {
+        if (key < lo || key >= hi) continue;
+        union = unionRects(union, rect);
+      }
+      if (union) return union;
+      // Fallback: union the endpoint resolutions so callers always get a
+      // rect when at least one endpoint is in the document.
+      const fromRect = resolveByRuntimeOffset(lo, story);
+      const toRect = resolveByRuntimeOffset(hi - 1, story);
+      return unionRects(fromRect, toRect);
+    },
+    byTableCell(tableBlockId, rowIndex, columnIndex) {
+      return tableCellRects.get(`${tableBlockId}:${rowIndex}:${columnIndex}`) ?? null;
+    },
+    byTableColumnEdge(tableBlockId, columnIndex) {
+      return tableColumnEdges.get(`${tableBlockId}:${columnIndex}`) ?? null;
+    },
+    byTableRowEdge(tableBlockId, rowIndex) {
+      return tableRowEdges.get(`${tableBlockId}:${rowIndex}`) ?? null;
+    },
+  };
+}
+
+/**
+ * Emit cell, column-edge, and row-edge anchor rects for a single table
+ * block from its attached render plan. Uses the block's frame (pixel
+ * coordinates at the frame's zoom) as the origin and lays out cell rects
+ * by summing `columnsTwips` horizontally and letting rows inherit the
+ * block's vertical height (row-level splits will refine this in a
+ * follow-up).
+ */
+function recordTableAnchors(
+  tableBlockId: string,
+  blockFrame: RenderFrameRect,
+  plan: import("./render-frame-types.ts").RenderBlock["tablePlan"],
+  pxPerTwip: number,
+  cellRects: Map<string, RenderFrameRect>,
+  columnEdges: Map<string, RenderFrameRect>,
+  rowEdges: Map<string, RenderFrameRect>,
+): void {
+  if (!plan) return;
+  const columnCount = plan.columnsTwips.length;
+  if (columnCount === 0) return;
+
+  // Column x-positions in px, starting from the block's leftPx.
+  const columnLeftsPx: number[] = [blockFrame.leftPx];
+  for (let i = 0; i < columnCount; i += 1) {
+    columnLeftsPx.push(
+      columnLeftsPx[i]! + (plan.columnsTwips[i] ?? 0) * pxPerTwip,
+    );
+  }
+
+  // Row y-positions: even split of blockFrame height across rows (row-
+  // level heights require per-row pagination in a future phase).
+  const rowCount = Math.max(
+    1,
+    plan.bandClasses.rows.length ||
+      plan.bandClasses.cells.reduce(
+        (max, c) => Math.max(max, c.rowIndex + 1),
+        0,
+      ),
+  );
+  const rowHeightPx = rowCount > 0 ? blockFrame.heightPx / rowCount : blockFrame.heightPx;
+  const rowTopsPx: number[] = [];
+  for (let r = 0; r <= rowCount; r += 1) {
+    rowTopsPx.push(blockFrame.topPx + r * rowHeightPx);
+  }
+
+  // Cell rects from bandClasses.cells (single entry per logical origin).
+  for (const cell of plan.bandClasses.cells) {
+    // Determine the columnSpan for this origin by checking whether the
+    // next cell in the same row has a columnIndex > this + 1 (sparse
+    // representation: only origins are emitted).
+    const sameRow = plan.bandClasses.cells.filter((c) => c.rowIndex === cell.rowIndex);
+    const sorted = [...sameRow].sort((a, b) => a.columnIndex - b.columnIndex);
+    const idx = sorted.findIndex((c) => c === cell);
+    const next = sorted[idx + 1];
+    const columnSpan = (next?.columnIndex ?? columnCount) - cell.columnIndex;
+
+    const left = columnLeftsPx[cell.columnIndex] ?? blockFrame.leftPx;
+    const right =
+      columnLeftsPx[cell.columnIndex + columnSpan] ??
+      blockFrame.leftPx + blockFrame.widthPx;
+    const top = rowTopsPx[cell.rowIndex] ?? blockFrame.topPx;
+    const bottom =
+      rowTopsPx[cell.rowIndex + 1] ?? blockFrame.topPx + blockFrame.heightPx;
+
+    cellRects.set(`${tableBlockId}:${cell.rowIndex}:${cell.columnIndex}`, {
+      leftPx: left,
+      topPx: top,
+      widthPx: Math.max(0, right - left),
+      heightPx: Math.max(0, bottom - top),
+    });
+  }
+
+  // Column edges — zero-width rect at each internal column boundary.
+  for (const handle of plan.columnResizeHandles) {
+    const x = blockFrame.leftPx + handle.originTwips * pxPerTwip;
+    columnEdges.set(`${tableBlockId}:${handle.columnIndex}`, {
+      leftPx: x,
+      topPx: blockFrame.topPx,
+      widthPx: 0,
+      heightPx: handle.heightTwips * pxPerTwip,
+    });
+  }
+
+  // Row edges — zero-height rect at each internal row boundary.
+  for (let r = 0; r < rowCount - 1; r += 1) {
+    const y = rowTopsPx[r + 1] ?? blockFrame.topPx + blockFrame.heightPx;
+    rowEdges.set(`${tableBlockId}:${r}`, {
+      leftPx: blockFrame.leftPx,
+      topPx: y,
+      widthPx: blockFrame.widthPx,
+      heightPx: 0,
+    });
+  }
+}
+
+function unionRects(
+  a: RenderFrameRect | null,
+  b: RenderFrameRect | null,
+): RenderFrameRect | null {
+  if (!a) return b ?? null;
+  if (!b) return a;
+  const left = Math.min(a.leftPx, b.leftPx);
+  const top = Math.min(a.topPx, b.topPx);
+  const right = Math.max(a.leftPx + a.widthPx, b.leftPx + b.widthPx);
+  const bottom = Math.max(a.topPx + a.heightPx, b.topPx + b.heightPx);
+  return {
+    leftPx: left,
+    topPx: top,
+    widthPx: right - left,
+    heightPx: bottom - top,
+  };
+}
+
+function buildDecorationIndex(pages: readonly RenderPage[]): DecorationIndex {
+  // Minimum-viable decoration projection: collect block decorations directly
+  // off the rendered blocks.  The full kernel phase adds a dedicated
+  // decoration-resolver that unions workflow scopes, comments, revisions,
+  // search matches, and locked zones into a single pass.
+  const workflow: import("./render-frame-types.ts").RenderBlockDecoration[] = [];
+  const comments: import("./render-frame-types.ts").RenderBlockDecoration[] = [];
+  const revisions: import("./render-frame-types.ts").RenderBlockDecoration[] = [];
+  const search: import("./render-frame-types.ts").RenderBlockDecoration[] = [];
+  const locked: import("./render-frame-types.ts").RenderBlockDecoration[] = [];
+
+  for (const page of pages) {
+    for (const block of page.regions.body.blocks) {
+      for (const decoration of block.blockDecorations) {
+        switch (decoration.kind) {
+          case "workflow":
+            workflow.push(decoration);
+            break;
+          case "comment":
+            comments.push(decoration);
+            break;
+          case "revision":
+            revisions.push(decoration);
+            break;
+          case "search":
+            search.push(decoration);
+            break;
+          case "locked":
+            locked.push(decoration);
+            break;
+        }
+      }
+    }
+  }
+
+  return { workflow, comments, revisions, search, locked };
+}
+
+function extractRevisionFromPageId(pageId: string): number | string {
+  // pageIds look like `page-<revision>-<index>`; extract the revision so the
+  // kernel's frame-level cache keys track graph revisions.
+  const match = /^page-(\d+)-/.exec(pageId);
+  if (!match) return pageId;
+  return Number(match[1]);
+}