@beyondwork/docx-react-component 1.0.36 → 1.0.38

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

package/src/runtime/render/render-frame-types.ts

@@ -0,0 +1,317 @@
+/**
+ * Shape definitions for the runtime-owned render kernel (Phase R1).
+ *
+ * Per runtime-rendering-and-chrome-phase.md §1 the render kernel projects the
+ * layout engine's page graph plus the decoration sources into a stable
+ * `RenderFrame` that every chrome surface reads.  Today the kernel emits a
+ * minimum-viable frame so consumers can start wiring against the shape;
+ * richer decoration resolution, wrap rects, and table render plans land as
+ * the chrome phase continues.
+ */
+
+import type {
+  EditorStoryTarget,
+  PageLayoutSnapshot,
+} from "../../api/public-types";
+import type {
+  PublicBlockFragment,
+  PublicLineBox,
+  PublicPageNode,
+  PublicPageRegion,
+  PublicMeasurementFidelity,
+} from "../layout/public-facet.ts";
+
+// ---------------------------------------------------------------------------
+// Core frame shape
+// ---------------------------------------------------------------------------
+
+export interface RenderFrame {
+  /** Revision stamp the kernel used to build this frame. */
+  revision: number;
+  /** Measurement fidelity the frame was computed against. */
+  measurementFidelity: PublicMeasurementFidelity;
+  /** Story the mounted surface renders. */
+  activeStory: EditorStoryTarget;
+  /** Zoom the frame was composed for. */
+  zoom: RenderZoom;
+  /** Page frames in document order. */
+  pages: RenderPage[];
+  /** Decoration index (per-frame, keyed by canonical runtime ranges). */
+  decorationIndex: DecorationIndex;
+  /** Anchor index for chrome placement. */
+  anchorIndex: RenderAnchorIndex;
+}
+
+export interface RenderPage {
+  page: PublicPageNode;
+  /** Top-left in frame-local pixel coordinates (post-zoom). */
+  frame: RenderFrameRect;
+  regions: RenderPageRegions;
+  chromeReservations: PageChromeReservations;
+}
+
+export interface RenderPageRegions {
+  body: RenderStoryRegion;
+  header?: RenderStoryRegion;
+  footer?: RenderStoryRegion;
+  columns?: readonly RenderStoryRegion[];
+  footnoteArea?: RenderStoryRegion;
+}
+
+export interface RenderStoryRegion {
+  storyTarget: EditorStoryTarget;
+  region: PublicPageRegion;
+  frame: RenderFrameRect;
+  blocks: RenderBlock[];
+}
+
+export interface RenderBlock {
+  fragment: PublicBlockFragment;
+  frame: RenderFrameRect;
+  kind: "paragraph" | "table" | "opaque" | "image-float" | "synthetic";
+  lines: RenderLine[];
+  blockDecorations: RenderBlockDecoration[];
+  /**
+   * Table geometry + band classes, attached only when `kind === "table"`.
+   * Populated by the layout facet's `getTableRenderPlan(blockId)` during
+   * frame construction so chrome can read columns, merges, and resize-
+   * handle origins without walking the canonical model.
+   */
+  tablePlan?: import("../layout/table-render-plan.ts").TableRenderPlan | null;
+}
+
+export interface RenderLine {
+  line: PublicLineBox;
+  frame: RenderFrameRect;
+  /**
+   * Anchor metadata for chrome hit-testing and balloon placement.  Today
+   * every line carries a single anchor covering its fragment; richer per-
+   * run anchors land with the kernel's full line-box projection.
+   */
+  anchors: RenderLineAnchor[];
+}
+
+export interface RenderLineAnchor {
+  /** Runtime offset this anchor represents. */
+  runtimeOffset: number;
+  /** Screen-relative rect the anchor occupies. */
+  frame: RenderFrameRect;
+  /** Optional fragment or block id hint. */
+  fragmentId?: string;
+  blockId?: string;
+}
+
+export interface RenderBlockDecoration {
+  kind: "workflow" | "comment" | "revision" | "search" | "locked";
+  /** Decoration identifier (scope id, comment id, revision id, etc.). */
+  refId: string;
+  frame: RenderFrameRect;
+}
+
+// ---------------------------------------------------------------------------
+// Geometry
+// ---------------------------------------------------------------------------
+
+/**
+ * All rects are in frame-local pixels at the kernel's chosen zoom.  The
+ * kernel applies `RenderZoom.pxPerTwip` to the page graph's twip values
+ * before returning a frame.
+ */
+export interface RenderFrameRect {
+  leftPx: number;
+  topPx: number;
+  widthPx: number;
+  heightPx: number;
+}
+
+export interface RenderZoom {
+  /** Pixels per twip (e.g. 96 dpi at 100% = 0.0667). */
+  pxPerTwip: number;
+  /** Viewport width in px. */
+  viewportWidthPx: number;
+  /** Fit mode the zoom was resolved from. */
+  fitMode: "fixed" | "page-width" | "one-page";
+}
+
+export interface PageChromeReservations {
+  /** Twips reserved to the left of the page frame for the workflow rail. */
+  railLaneTwips: number;
+  /** Twips reserved to the right for comment balloons. */
+  balloonLaneTwips: number;
+  /** Twips reserved at the bottom of the body for footnotes. */
+  footnoteAreaTwips: number;
+  /** Cached post-zoom page frame in pixels. */
+  pageFrameWidthPx: number;
+  pageFrameHeightPx: number;
+}
+
+// ---------------------------------------------------------------------------
+// Decoration and anchor indexes
+// ---------------------------------------------------------------------------
+
+export interface DecorationIndex {
+  workflow: readonly RenderBlockDecoration[];
+  comments: readonly RenderBlockDecoration[];
+  revisions: readonly RenderBlockDecoration[];
+  search: readonly RenderBlockDecoration[];
+  locked: readonly RenderBlockDecoration[];
+}
+
+export interface RenderAnchorIndex {
+  byRuntimeOffset(
+    offset: number,
+    story?: EditorStoryTarget,
+  ): RenderFrameRect | null;
+  byBlockId(blockId: string): RenderFrameRect | null;
+  byFragmentId(fragmentId: string): RenderFrameRect | null;
+  byPageIndex(pageIndex: number): RenderFrameRect | null;
+  /**
+   * Union rect covering a selection range.  Resolves one rect per runtime
+   * offset and unions them, so chrome surfaces anchoring on selections
+   * (selection toolbar, suggestion card, comment thread tool) get a single
+   * tight rect without repeating the union math per consumer.  Returns
+   * `null` when no offset in the range resolves to an anchor.
+   *
+   * Inclusive `fromOffset`, exclusive `toOffset` — matches the selection
+   * model used by `SelectionSnapshot`.  When `fromOffset === toOffset`,
+   * falls back to `byRuntimeOffset(fromOffset)` so collapsed carets
+   * resolve to their line-box rect.
+   */
+  bySelection(
+    fromOffset: number,
+    toOffset: number,
+    story?: EditorStoryTarget,
+  ): RenderFrameRect | null;
+  /**
+   * Locate a table cell's rect given its owning table block id and logical
+   * (rowIndex, columnIndex). Reads from the attached `TableRenderPlan` on
+   * the render block so chrome tools (border picker, cell context bar)
+   * position without re-measuring the DOM. Returns `null` when the block
+   * is not a table, the plan is absent, or the indices fall outside the
+   * cell matrix.
+   */
+  byTableCell(
+    tableBlockId: string,
+    rowIndex: number,
+    columnIndex: number,
+  ): RenderFrameRect | null;
+  /**
+   * Locate the vertical grip at the right edge of `columnIndex` on a
+   * table. Returns a zero-width rect whose `leftPx` is the grip origin
+   * and whose `heightPx` spans the table's visible height on the page.
+   */
+  byTableColumnEdge(
+    tableBlockId: string,
+    columnIndex: number,
+  ): RenderFrameRect | null;
+  /**
+   * Locate the horizontal grip at the bottom edge of `rowIndex`. Returns
+   * a zero-height rect whose `topPx` is the grip origin and whose
+   * `widthPx` spans the table's visible width.
+   */
+  byTableRowEdge(
+    tableBlockId: string,
+    rowIndex: number,
+  ): RenderFrameRect | null;
+}
+
+// ---------------------------------------------------------------------------
+// Queries + events
+// ---------------------------------------------------------------------------
+
+export interface RenderFrameQueryOptions {
+  story?: EditorStoryTarget;
+  pageRange?: { fromPageIndex: number; toPageIndex: number };
+  includeDecorations?: boolean;
+}
+
+export interface RenderAnchorQuery {
+  kind:
+    | "runtime-offset"
+    | "block-id"
+    | "fragment-id"
+    | "scope-id"
+    | "comment-id"
+    | "revision-id"
+    | "page-index";
+  value: string | number;
+  story?: EditorStoryTarget;
+}
+
+export interface RenderHitResult {
+  pageIndex: number;
+  regionKind: PublicPageRegion["kind"];
+  blockId: string;
+  fragmentId: string;
+  lineIndex: number;
+  runtimeOffset: number;
+}
+
+/**
+ * Point in the shell's overlay coordinate space (not the viewport, not
+ * the document CSS).  Chrome surfaces compute this from a pointer event
+ * via `chrome-overlay-projector.ts` (same projector that maps rects out
+ * of the overlay) and pass it into `facet.hitTest`.
+ */
+export interface RenderPoint {
+  xPx: number;
+  yPx: number;
+}
+
+export type RenderKernelEvent =
+  | { kind: "frame_built"; revision: number; reason: "full" | "incremental" }
+  | {
+      kind: "frame_diff";
+      revision: number;
+      pageRange: { fromPageIndex: number; toPageIndex: number };
+    }
+  | { kind: "decoration_resolved"; revision: number };
+
+export interface DefaultZoomInput {
+  pxPerTwip?: number;
+  viewportWidthPx?: number;
+  fitMode?: RenderZoom["fitMode"];
+}
+
+/**
+ * Conservative default zoom: 96 dpi at 100% = 1 inch per 96 pixels, and
+ * 1 inch = 1440 twips, so 1 twip = 96/1440 ≈ 0.0667 px.  Consumers pass a
+ * real zoom when they have a viewport; this keeps the kernel testable
+ * without a DOM.
+ */
+export const DEFAULT_PX_PER_TWIP = 96 / 1440;
+
+export function resolveDefaultZoom(input: DefaultZoomInput = {}): RenderZoom {
+  return {
+    pxPerTwip: input.pxPerTwip ?? DEFAULT_PX_PER_TWIP,
+    viewportWidthPx: input.viewportWidthPx ?? 900,
+    fitMode: input.fitMode ?? "fixed",
+  };
+}
+
+export const EMPTY_DECORATION_INDEX: DecorationIndex = Object.freeze({
+  workflow: Object.freeze([]) as readonly RenderBlockDecoration[],
+  comments: Object.freeze([]) as readonly RenderBlockDecoration[],
+  revisions: Object.freeze([]) as readonly RenderBlockDecoration[],
+  search: Object.freeze([]) as readonly RenderBlockDecoration[],
+  locked: Object.freeze([]) as readonly RenderBlockDecoration[],
+});
+
+/**
+ * Default chrome reservations.  Ship Letter-compatible defaults so the
+ * kernel can be instantiated without a host injecting chrome sizes; chrome
+ * consumers override via `RenderPage.chromeReservations` once they know
+ * their own layout.
+ */
+export function defaultChromeReservations(
+  layout: PageLayoutSnapshot,
+  zoom: RenderZoom,
+): PageChromeReservations {
+  return {
+    railLaneTwips: 360,
+    balloonLaneTwips: 2160,
+    footnoteAreaTwips: 0,
+    pageFrameWidthPx: layout.pageWidth * zoom.pxPerTwip,
+    pageFrameHeightPx: layout.pageHeight * zoom.pxPerTwip,
+  };
+}