@beyondwork/docx-react-component 1.0.37 → 1.0.38

package/src/runtime/layout/table-render-plan.ts

@@ -0,0 +1,229 @@
+/**
+ * Table render plan (P3e).
+ *
+ * Per `docs/reference/docx/runtime-rendering-and-chrome-phase.md` §1, the
+ * render kernel consumes a `TableRenderPlan` per table per page so the
+ * chrome can:
+ *   - render band-aware cell styling without pre-flattening into inline
+ *     CSS strings,
+ *   - position column-resize grips at logical column edges without
+ *     re-measuring the DOM,
+ *   - show repeated header rows on continuation pages (when row-level
+ *     pagination lands; today the field is empty),
+ *   - walk vertical-merge chains for merged-cell hit-testing.
+ *
+ * The plan is a pure function of the table block + resolved style
+ * resolution + gridColumns + the effective page column width. It does
+ * not read DOM or mutate state.
+ */
+
+import type {
+  SurfaceBlockSnapshot,
+  SurfaceTableCellSnapshot,
+  SurfaceTableRowSnapshot,
+} from "../../api/public-types";
+import type { TableStyleConditionalRegion } from "../../model/canonical-document.ts";
+import type { ResolvedTableStyleResolution } from "../table-style-resolver.ts";
+
+// ─── Public shapes ───────────────────────────────────────────────────────────
+
+export type TableBandRegion = TableStyleConditionalRegion;
+
+export interface TableCellBandAssignment {
+  rowIndex: number;
+  columnIndex: number;
+  regions: readonly TableBandRegion[];
+}
+
+export interface TableRowBandAssignment {
+  rowIndex: number;
+  regions: readonly TableBandRegion[];
+}
+
+export interface TableBandClasses {
+  /** Active regions per row (firstRow, lastRow, band1Horz, band2Horz). */
+  rows: readonly TableRowBandAssignment[];
+  /** Active regions per cell (row regions ∪ column regions). */
+  cells: readonly TableCellBandAssignment[];
+}
+
+export interface VerticalMergeRef {
+  /** Logical column the chain lives in. */
+  columnIndex: number;
+  /** Row where the chain starts (verticalMerge: "restart"). */
+  startRowIndex: number;
+  /** Inclusive row where the chain ends. */
+  endRowIndex: number;
+  /** Horizontal span of the merged cell. */
+  columnSpan: number;
+}
+
+export interface RepeatedHeaderRowRef {
+  /** Row index in the source table whose header is repeated. */
+  sourceRowIndex: number;
+  /** Virtual fragment id the render kernel uses to address this repeat. */
+  virtualFragmentId: string;
+}
+
+export interface ColumnResizeHandle {
+  /** Logical column index the handle sits at (0-based, right edge of column i). */
+  columnIndex: number;
+  /** X-origin of the handle in twips, measured from the table's left edge. */
+  originTwips: number;
+  /** Handle height in twips (table visual height). */
+  heightTwips: number;
+}
+
+export interface TableRenderPlan {
+  blockId: string;
+  pageIndex: number;
+  /** Logical column widths in twips (may be scaled from canonical). */
+  columnsTwips: readonly number[];
+  /** Band-class assignments derived from resolved table style. */
+  bandClasses: TableBandClasses;
+  /** Vertical-merge chains in the visible table range. */
+  verticalMerges: readonly VerticalMergeRef[];
+  /** Header rows repeated on this page (empty until row-level split lands). */
+  repeatedHeaderRows: readonly RepeatedHeaderRowRef[];
+  /** Column-resize handle origins for chrome grip placement. */
+  columnResizeHandles: readonly ColumnResizeHandle[];
+}
+
+// ─── Builder ────────────────────────────────────────────────────────────────
+
+export interface BuildTableRenderPlanInput {
+  blockId: string;
+  pageIndex: number;
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>;
+  resolved: ResolvedTableStyleResolution;
+  /** Total height of the table in twips (for grip geometry). */
+  tableHeightTwips: number;
+  /** If `columnsTwips` was scaled to the canvas width, pass the scale
+   *  factor here; otherwise leave undefined. */
+  columnsTwipsScale?: number;
+}
+
+export function buildTableRenderPlan(
+  input: BuildTableRenderPlanInput,
+): TableRenderPlan {
+  const { blockId, pageIndex, block, resolved, tableHeightTwips } = input;
+  const scale = input.columnsTwipsScale ?? 1;
+  const columnsTwips = block.gridColumns.map((w) => Math.round(w * scale));
+
+  const bandClasses = buildBandClasses(block.rows, resolved);
+  const verticalMerges = collectVerticalMerges(block.rows);
+  const repeatedHeaderRows: RepeatedHeaderRowRef[] = [];
+  const columnResizeHandles = buildColumnResizeHandles(columnsTwips, tableHeightTwips);
+
+  return {
+    blockId,
+    pageIndex,
+    columnsTwips,
+    bandClasses,
+    verticalMerges,
+    repeatedHeaderRows,
+    columnResizeHandles,
+  };
+}
+
+// ─── Internals ───────────────────────────────────────────────────────────────
+
+function buildBandClasses(
+  rows: readonly SurfaceTableRowSnapshot[],
+  resolved: ResolvedTableStyleResolution,
+): TableBandClasses {
+  const rowAssignments: TableRowBandAssignment[] = [];
+  const cellAssignments: TableCellBandAssignment[] = [];
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const resolvedRow = resolved.rows[rowIndex];
+    const rowRegions = resolvedRow?.style.activeConditionalRegions ?? [];
+    rowAssignments.push({ rowIndex, regions: rowRegions });
+
+    const resolvedCells = resolvedRow?.cells ?? [];
+    const sourceRow = rows[rowIndex]!;
+    let columnCursor = sourceRow.gridBefore ?? 0;
+    for (let cellIndex = 0; cellIndex < sourceRow.cells.length; cellIndex += 1) {
+      const cell = sourceRow.cells[cellIndex]!;
+      const columnSpan = Math.max(1, cell.colspan ?? 1);
+      const resolvedCell = resolvedCells[cellIndex];
+      const regions = resolvedCell?.activeConditionalRegions ?? [];
+      cellAssignments.push({
+        rowIndex,
+        columnIndex: columnCursor,
+        regions,
+      });
+      columnCursor += columnSpan;
+    }
+  }
+
+  return { rows: rowAssignments, cells: cellAssignments };
+}
+
+function collectVerticalMerges(
+  rows: readonly SurfaceTableRowSnapshot[],
+): VerticalMergeRef[] {
+  const merges: VerticalMergeRef[] = [];
+  // Track active chains by column: maps startColumn → { startRow, span }.
+  const active = new Map<number, { startRow: number; span: number }>();
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const row = rows[rowIndex]!;
+    let columnCursor = row.gridBefore ?? 0;
+    const seenThisRow = new Set<number>();
+
+    for (const cell of row.cells) {
+      const span = Math.max(1, cell.colspan ?? 1);
+      if (cell.verticalMerge === "restart") {
+        active.set(columnCursor, { startRow: rowIndex, span });
+        seenThisRow.add(columnCursor);
+      } else if (cell.verticalMerge === "continue") {
+        seenThisRow.add(columnCursor);
+        // chain stays open; ended rowIndex extends via the flush below
+      }
+      columnCursor += span;
+    }
+
+    // Flush chains that did NOT appear as a continue in this row.
+    for (const [startColumn, chain] of [...active.entries()]) {
+      if (!seenThisRow.has(startColumn)) {
+        merges.push({
+          columnIndex: startColumn,
+          startRowIndex: chain.startRow,
+          endRowIndex: rowIndex - 1,
+          columnSpan: chain.span,
+        });
+        active.delete(startColumn);
+      }
+    }
+  }
+
+  // Flush any still-open chains at end of table.
+  for (const [startColumn, chain] of active.entries()) {
+    merges.push({
+      columnIndex: startColumn,
+      startRowIndex: chain.startRow,
+      endRowIndex: rows.length - 1,
+      columnSpan: chain.span,
+    });
+  }
+
+  return merges;
+}
+
+function buildColumnResizeHandles(
+  columnsTwips: readonly number[],
+  heightTwips: number,
+): ColumnResizeHandle[] {
+  const handles: ColumnResizeHandle[] = [];
+  let cursor = 0;
+  for (let i = 0; i < columnsTwips.length - 1; i += 1) {
+    cursor += columnsTwips[i] ?? 0;
+    handles.push({
+      columnIndex: i,
+      originTwips: cursor,
+      heightTwips,
+    });
+  }
+  return handles;
+}

package/src/runtime/render/block-fragment-projection.ts

@@ -0,0 +1,35 @@
+/**
+ * Block fragment projection (P4b).
+ *
+ * Classifies each `PublicBlockFragment` produced by the layout facet into
+ * a `RenderBlock["kind"]` so the render kernel's output is accurate across
+ * paragraph / table / opaque / synthetic blocks.  Previously the kernel's
+ * `classifyBlockKind` stub always returned `"paragraph"`.
+ *
+ * The classification is driven by the deterministic blockId prefix scheme
+ * emitted by `src/runtime/surface-projection.ts`:
+ *   - `paragraph-*`  → "paragraph"
+ *   - `table-*`      → "table"
+ *   - `opaque-*`     → "opaque"
+ *   - `section-break-*` → "opaque" (read-only boundary marker)
+ *   - `sdt-*`, `sdt-wrapper-*` → "opaque"
+ *   - `custom-xml-*` → "opaque"
+ *   - `alt-chunk-*`  → "opaque"
+ *   - `synthetic-*`  → "synthetic"
+ * Unknown prefixes fall back to `"paragraph"` so the render frame stays
+ * usable while a new surface node type is in development.
+ */
+
+import type { RenderBlock } from "./render-frame-types.ts";
+
+export function classifyBlockKind(blockId: string): RenderBlock["kind"] {
+  if (blockId.startsWith("paragraph")) return "paragraph";
+  if (blockId.startsWith("table")) return "table";
+  if (blockId.startsWith("opaque")) return "opaque";
+  if (blockId.startsWith("section-break")) return "opaque";
+  if (blockId.startsWith("sdt")) return "opaque";
+  if (blockId.startsWith("custom-xml")) return "opaque";
+  if (blockId.startsWith("alt-chunk")) return "opaque";
+  if (blockId.startsWith("synthetic")) return "synthetic";
+  return "paragraph";
+}

package/src/runtime/render/decoration-resolver.ts

@@ -0,0 +1,189 @@
+/**
+ * Decoration resolver — single pass that turns canonical decoration sources
+ * (workflow scopes, comments, revisions, search, locked zones) into the
+ * five lanes of `DecorationIndex` that chrome consumes.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §1, the kernel's MVP leaves
+ * `DecorationIndex` empty; chrome surfaces that need per-decoration anchor
+ * rects re-project from runtime offsets themselves.  The resolver fixes
+ * that by walking each source once, resolving its body rect through the
+ * kernel's anchor index, and emitting a `RenderBlockDecoration` entry with
+ * the stable rect.  Chrome reads the resolved lanes directly and never
+ * touches the DOM or re-runs anchor math.
+ *
+ * The resolver is pure: same inputs produce the same output.  The kernel
+ * invokes it once per frame build, cached against the frame's revision.
+ */
+
+import type {
+  CommentDecorationModel,
+  CommentDecorationThread,
+} from "../../ui/headless/comment-decoration-model.ts";
+import type {
+  RevisionDecorationModel,
+  RevisionDecorationEntry,
+} from "../../ui/headless/revision-decoration-model.ts";
+import type { ScopeRailSegment } from "../workflow-rail-segments.ts";
+import type {
+  DecorationIndex,
+  RenderAnchorIndex,
+  RenderBlockDecoration,
+  RenderFrameRect,
+} from "./render-frame-types.ts";
+
+// ---------------------------------------------------------------------------
+// Input shapes
+// ---------------------------------------------------------------------------
+
+export interface SearchMatchRange {
+  /** Stable identifier the search plugin emits for each match. */
+  matchId: string;
+  /** Inclusive runtime offset. */
+  from: number;
+  /** Exclusive runtime offset. */
+  to: number;
+  /** True when this match is the currently-focused "active" result. */
+  isActive?: boolean;
+}
+
+export interface LockedRangeInput {
+  /** Stable id of the lock (fragmentId for locked zones, scopeId for preserve-only scopes). */
+  lockId: string;
+  /** Inclusive runtime offset. */
+  from: number;
+  /** Exclusive runtime offset. */
+  to: number;
+  /** Optional human label. */
+  label?: string;
+}
+
+export interface ResolveDecorationIndexInput {
+  anchorIndex: RenderAnchorIndex;
+  /**
+   * Scope rail segments covering the active story.  The resolver re-uses
+   * their anchor rects when present (`bodyTintRect`) and falls back to
+   * `anchorIndex.bySelection(from, to)` otherwise.
+   */
+  workflowSegments?: readonly ScopeRailSegment[];
+  comments?: CommentDecorationModel | null | undefined;
+  revisions?: RevisionDecorationModel | null | undefined;
+  searchMatches?: readonly SearchMatchRange[];
+  lockedRanges?: readonly LockedRangeInput[];
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+export function resolveDecorationIndex(
+  input: ResolveDecorationIndexInput,
+): DecorationIndex {
+  const workflow: RenderBlockDecoration[] = [];
+  const comments: RenderBlockDecoration[] = [];
+  const revisions: RenderBlockDecoration[] = [];
+  const search: RenderBlockDecoration[] = [];
+  const locked: RenderBlockDecoration[] = [];
+
+  if (input.workflowSegments) {
+    for (const segment of input.workflowSegments) {
+      const frame =
+        segment.bodyTintRect ??
+        input.anchorIndex.bySelection(segment.fromOffset, segment.toOffset);
+      if (!frame) continue;
+      workflow.push({
+        kind: "workflow",
+        refId: segment.scopeId,
+        frame,
+      });
+    }
+  }
+
+  if (input.comments) {
+    for (const thread of input.comments.threads) {
+      const frame = resolveRange(
+        input.anchorIndex,
+        thread.from,
+        thread.to,
+      );
+      if (!frame) continue;
+      comments.push({
+        kind: "comment",
+        refId: thread.commentId,
+        frame,
+      });
+      // Track active thread separately so chrome can prioritize rendering.
+      // (We don't have a per-decoration "isActive" field today; chrome
+      // reads `CommentDecorationModel.activeCommentId` alongside the
+      // decoration lane and picks out the matching refId.)
+      void asCommentThread(thread);
+    }
+  }
+
+  if (input.revisions) {
+    for (const revision of input.revisions.revisions) {
+      const frame = resolveRange(
+        input.anchorIndex,
+        revision.from,
+        revision.to,
+      );
+      if (!frame) continue;
+      revisions.push({
+        kind: "revision",
+        refId: revision.revisionId,
+        frame,
+      });
+      void asRevisionEntry(revision);
+    }
+  }
+
+  if (input.searchMatches) {
+    for (const match of input.searchMatches) {
+      const frame = resolveRange(input.anchorIndex, match.from, match.to);
+      if (!frame) continue;
+      search.push({
+        kind: "search",
+        refId: match.matchId,
+        frame,
+      });
+    }
+  }
+
+  if (input.lockedRanges) {
+    for (const lock of input.lockedRanges) {
+      const frame = resolveRange(input.anchorIndex, lock.from, lock.to);
+      if (!frame) continue;
+      locked.push({
+        kind: "locked",
+        refId: lock.lockId,
+        frame,
+      });
+    }
+  }
+
+  return { workflow, comments, revisions, search, locked };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function resolveRange(
+  anchorIndex: RenderAnchorIndex,
+  from: number,
+  to: number,
+): RenderFrameRect | null {
+  if (from >= to) {
+    return anchorIndex.byRuntimeOffset(from);
+  }
+  return anchorIndex.bySelection(from, to);
+}
+
+// Type preservation helpers so the input shapes stay referenced and
+// `tsgo --noEmit` catches shape drift if the upstream models change.
+function asCommentThread(thread: CommentDecorationThread): CommentDecorationThread {
+  return thread;
+}
+
+function asRevisionEntry(entry: RevisionDecorationEntry): RevisionDecorationEntry {
+  return entry;
+}

package/src/runtime/render/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Runtime-owned render kernel — internal API surface.
+ *
+ * The kernel consumes the layout facet and emits `RenderFrame` objects
+ * that every chrome surface reads.  Nothing in this module is part of
+ * the package's public API; consumers go through `ref.layout.getRenderFrame`
+ * (facet) rather than wiring the kernel directly.
+ */
+
+export {
+  createRenderKernel,
+  sumDeltasBefore,
+  type RenderKernel,
+  type CreateRenderKernelInput,
+  type DecorationSources,
+  type PendingOpDelta,
+} from "./render-kernel.ts";
+
+export {
+  createPendingOpDeltaReader,
+  type PendingOpDeltaReader,
+  type PendingOpDeltaSnapshot,
+  type CreatePendingOpDeltaReaderInput,
+} from "./pending-op-delta-reader.ts";
+
+export {
+  resolveDecorationIndex,
+  type ResolveDecorationIndexInput,
+  type SearchMatchRange,
+  type LockedRangeInput,
+} from "./decoration-resolver.ts";
+
+export {
+  DEFAULT_PX_PER_TWIP,
+  EMPTY_DECORATION_INDEX,
+  defaultChromeReservations,
+  resolveDefaultZoom,
+  type DecorationIndex,
+  type PageChromeReservations,
+  type RenderAnchorIndex,
+  type RenderAnchorQuery,
+  type RenderBlock,
+  type RenderBlockDecoration,
+  type RenderFrame,
+  type RenderFrameQueryOptions,
+  type RenderFrameRect,
+  type RenderHitResult,
+  type RenderKernelEvent,
+  type RenderPoint,
+  type RenderLine,
+  type RenderLineAnchor,
+  type RenderPage,
+  type RenderPageRegions,
+  type RenderStoryRegion,
+  type RenderZoom,
+  type DefaultZoomInput,
+} from "./render-frame-types.ts";

package/src/runtime/render/pending-op-delta-reader.ts

@@ -0,0 +1,129 @@
+/**
+ * Pending-op delta reader — thin accessor over `createRenderKernel`'s
+ * `getPendingOpDeltas` seam so chrome surfaces can reason about the
+ * predicted-dispatch window without reaching into the kernel's internals.
+ *
+ * Chrome must NOT mutate anchor rects during the predicted-dispatch window —
+ * per `bounded-local-first-interaction-architecture.md`, the rects settle
+ * when `TextCommandAck` reconciles.  Chrome surfaces that want to *mask*
+ * during that window (disable buttons, show a spinner) read a flag from
+ * this module instead of polling the kernel directly.
+ *
+ * The reader is decoupled from the kernel so the predicted lane can be
+ * swapped or gated without touching chrome code.
+ */
+
+import type { PendingOpDelta } from "./render-kernel.ts";
+
+// ---------------------------------------------------------------------------
+// Reader contract
+// ---------------------------------------------------------------------------
+
+/**
+ * Snapshot of the predicted-dispatch state at the moment it was read.
+ *
+ * `deltas` is the same shape the kernel's anchor index receives; chrome
+ * uses the summary fields below instead of walking the array in hot paths.
+ */
+export interface PendingOpDeltaSnapshot {
+  /** Raw delta array, identical to what the kernel received. */
+  deltas: readonly PendingOpDelta[];
+  /** True when any pending op is outstanding. */
+  hasPending: boolean;
+  /** Count of pending ops (for perf probe sampling). */
+  pendingCount: number;
+  /** Net character delta summed across all pending ops. */
+  netCharacterDelta: number;
+  /** Lowest runtime offset touched by any pending op, or null when empty. */
+  earliestTouchedOffset: number | null;
+  /** Highest runtime offset touched by any pending op, or null when empty. */
+  latestTouchedOffset: number | null;
+}
+
+export interface PendingOpDeltaReader {
+  /** Read the current snapshot.  Safe to call every render. */
+  read(): PendingOpDeltaSnapshot;
+  /**
+   * Predicate: is a given runtime offset inside the range touched by the
+   * pending window?  Chrome uses this to decide whether a selection anchor
+   * is stable yet.
+   */
+  isOffsetPending(offset: number): boolean;
+}
+
+export interface CreatePendingOpDeltaReaderInput {
+  /**
+   * Reads the current pending-op deltas — typically
+   * `() => localEditSessionState.getPendingDeltas()` or the kernel's own
+   * `getPendingOpDeltas` accessor.  When absent, the reader returns an
+   * empty snapshot.
+   */
+  getDeltas?: () => readonly PendingOpDelta[];
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+const EMPTY_SNAPSHOT: PendingOpDeltaSnapshot = Object.freeze({
+  deltas: [],
+  hasPending: false,
+  pendingCount: 0,
+  netCharacterDelta: 0,
+  earliestTouchedOffset: null,
+  latestTouchedOffset: null,
+});
+
+export function createPendingOpDeltaReader(
+  input: CreatePendingOpDeltaReaderInput = {},
+): PendingOpDeltaReader {
+  const getDeltas = input.getDeltas;
+
+  function read(): PendingOpDeltaSnapshot {
+    if (!getDeltas) {
+      return EMPTY_SNAPSHOT;
+    }
+    const deltas = getDeltas();
+    if (deltas.length === 0) {
+      return EMPTY_SNAPSHOT;
+    }
+    return summarize(deltas);
+  }
+
+  return {
+    read,
+    isOffsetPending(offset) {
+      const snapshot = read();
+      if (!snapshot.hasPending) return false;
+      const earliest = snapshot.earliestTouchedOffset;
+      const latest = snapshot.latestTouchedOffset;
+      if (earliest === null || latest === null) return false;
+      return offset >= earliest && offset <= latest;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function summarize(
+  deltas: readonly PendingOpDelta[],
+): PendingOpDeltaSnapshot {
+  let net = 0;
+  let earliest = Number.POSITIVE_INFINITY;
+  let latest = Number.NEGATIVE_INFINITY;
+  for (const delta of deltas) {
+    net += delta.delta;
+    if (delta.fromRuntime < earliest) earliest = delta.fromRuntime;
+    if (delta.fromRuntime > latest) latest = delta.fromRuntime;
+  }
+  return {
+    deltas,
+    hasPending: true,
+    pendingCount: deltas.length,
+    netCharacterDelta: net,
+    earliestTouchedOffset: Number.isFinite(earliest) ? earliest : null,
+    latestTouchedOffset: Number.isFinite(latest) ? latest : null,
+  };
+}