@beyondwork/docx-react-component 1.0.37 → 1.0.38

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