@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/runtime/layout/public-facet.ts

@@ -0,0 +1,1398 @@
+/**
+ * Public Layout Facet — the ergonomic surface exposed on
+ * `WordReviewEditorRef.layout`.
+ *
+ * Per the plan (Phase 7), this provides a single coherent object tree for
+ * consumers to walk the layout graph, resolve positions, inspect measurement
+ * state, and observe layout events — without needing to deal with the legacy
+ * opaque JSON snapshots.
+ *
+ * Design rules:
+ *   - Every returned value is a deep-cloned read model.  Internal graph
+ *     identities never escape the facet.
+ *   - Story-aware.  `EditorStoryTarget` is accepted anywhere a position is
+ *     interpreted so header/footer/note queries work cleanly.
+ *   - No DOM.  No PM.  No canonical model leakage.
+ */
+
+import type {
+  EditorStoryTarget,
+  PageLayoutSnapshot,
+  SelectionSnapshot,
+} from "../../api/public-types";
+import type {
+  ResolvedPageStories,
+} from "./page-story-resolver.ts";
+import type {
+  RuntimeBlockFragment,
+  RuntimeLineBox,
+  RuntimeNoteAllocation,
+  RuntimePageGraph,
+  RuntimePageNode,
+  RuntimePageRegion,
+  RuntimePageRegions,
+} from "./page-graph.ts";
+import type {
+  ResolvedFormattingState,
+  ResolvedRunFormatting,
+} from "./resolved-formatting-document.ts";
+import type { ResolvedParagraphFormatting } from "./resolved-formatting-state.ts";
+import type {
+  LayoutEngineEvent,
+  LayoutEngineInstance,
+  LayoutEngineQueryInput,
+} from "./layout-engine-instance.ts";
+import type { PageFragmentMapper } from "./page-fragment-mapper.ts";
+import {
+  PAGE_FORMAT_CATALOG,
+  matchPageFormat,
+  type PageFormatDefinition,
+  type ActivePageFormat,
+} from "./page-format-catalog.ts";
+import {
+  MARGIN_PRESET_CATALOG,
+  matchMarginPreset,
+  type MarginPresetDefinition,
+  type ActiveMarginPreset,
+} from "./margin-preset-catalog.ts";
+import {
+  collectScopeRailSegments,
+  type ScopeRailSegment,
+} from "../workflow-rail-segments.ts";
+import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
+import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
+import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
+import { resolveTableStyleResolution } from "../table-style-resolver.ts";
+import { buildTableRenderPlan } from "./table-render-plan.ts";
+import type {
+  SurfaceBlockSnapshot,
+} from "../../api/public-types";
+
+export type {
+  PageFormatDefinition,
+  ActivePageFormat,
+  MarginPresetDefinition,
+  ActiveMarginPreset,
+};
+
+export type { ScopeRailSegment };
+
+// ---------------------------------------------------------------------------
+// Public read model types (shape-stable, cloned at the facet boundary)
+// ---------------------------------------------------------------------------
+
+export interface PublicPageNode {
+  pageId: string;
+  pageIndex: number;
+  sectionIndex: number;
+  pageInSection: number;
+  startOffset: number;
+  endOffset: number;
+  /** Whether this page is a blank filler (e.g. from evenPage/oddPage). */
+  isBlankFiller: boolean;
+  /** Resolved display page number (1-based, honors section restarts). */
+  displayPageNumber: number;
+  /** Whether this is treated as the first page of its section (title page). */
+  isFirstPage: boolean;
+  /** Whether the displayed page number is even. */
+  isEvenPage: boolean;
+  /** Section-derived page layout geometry. */
+  layout: PageLayoutSnapshot;
+  /** Resolved header/footer/note stories active on this page. */
+  stories: PublicResolvedPageStories;
+  /** Sub-regions rendered on the page. */
+  regions: PublicPageRegions;
+  /** Number of line boxes rendered in the body region. */
+  lineBoxCount: number;
+  /** Footnotes reserved at the bottom of the page, if any. */
+  noteAllocations: readonly PublicNoteAllocation[];
+}
+
+export interface PublicResolvedPageStories {
+  header?: EditorStoryTarget;
+  footer?: EditorStoryTarget;
+  isFirstPage: boolean;
+  isEvenPage: boolean;
+  displayPageNumber: number;
+}
+
+export interface PublicPageRegions {
+  body: PublicPageRegion;
+  header?: PublicPageRegion;
+  footer?: PublicPageRegion;
+  columns?: readonly PublicPageRegion[];
+}
+
+export interface PublicPageRegion {
+  kind: "body" | "header" | "footer" | "column" | "footnote-area";
+  originTwips: number;
+  widthTwips: number;
+  heightTwips: number;
+  fragmentCount: number;
+}
+
+export interface PublicBlockFragment {
+  fragmentId: string;
+  blockId: string;
+  pageId: string;
+  pageIndex: number;
+  regionKind: PublicPageRegion["kind"];
+  from: number;
+  to: number;
+  heightTwips: number;
+  orderInRegion: number;
+}
+
+export interface PublicLineBox {
+  fragmentId: string;
+  lineIndex: number;
+  baselineTwips: number;
+  heightTwips: number;
+  widthTwips: number;
+}
+
+export interface PublicNoteAllocation {
+  noteKind: "footnote" | "endnote";
+  noteId: string;
+  reservedHeightTwips: number;
+}
+
+export interface PublicPageAnchor {
+  offset: number;
+  pageId: string;
+  pageIndex: number;
+  fragmentId?: string;
+  regionKind?: PublicPageRegion["kind"];
+}
+
+export interface PublicPageSpan {
+  firstPageIndex: number;
+  lastPageIndex: number;
+  pageCount: number;
+}
+
+export interface PublicSectionNode {
+  sectionIndex: number;
+  startOffset: number;
+  endOffset: number;
+  firstPageIndex: number;
+  lastPageIndex: number;
+  pageCount: number;
+  layout: PageLayoutSnapshot;
+}
+
+export interface PublicResolvedParagraphFormatting {
+  blockId: string;
+  spacingBefore: number;
+  spacingAfter: number;
+  lineHeight: number;
+  lineRule: "auto" | "exact" | "atLeast";
+  indentLeft: number;
+  indentRight: number;
+  firstLineIndent: number;
+  hangingIndent: number;
+  fontSizeHalfPoints: number;
+  averageCharWidthTwips: number;
+  tabStops: readonly {
+    positionTwips: number;
+    alignment: string;
+    leader?: string;
+  }[];
+  keepNext: boolean;
+  keepLines: boolean;
+  pageBreakBefore: boolean;
+  widowControl: boolean;
+  contextualSpacing: boolean;
+}
+
+export interface PublicResolvedRunFormatting {
+  runId: string;
+  blockId: string;
+  fontFamily?: string;
+  fontSizeHalfPoints?: number;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  strikethrough: boolean;
+  color?: string;
+  highlight?: string;
+  verticalAlign: "baseline" | "superscript" | "subscript";
+}
+
+export interface PublicBlockMeasurement {
+  blockId: string;
+  lineCount: number;
+  /** Total height the block occupies in twips. */
+  heightTwips: number;
+}
+
+export type PublicMeasurementFidelity =
+  | "empirical"
+  | "canvas"
+  | "canvas-with-font-loading";
+
+export interface PublicFieldDirtinessReport {
+  families: readonly string[];
+  revision: number;
+}
+
+export type LayoutFacetEvent =
+  | {
+      kind: "layout_recomputed";
+      revision: number;
+      reason?: LayoutFacetInvalidationReason;
+    }
+  | {
+      kind: "page_count_changed";
+      previous: number;
+      current: number;
+      revision: number;
+    }
+  | {
+      kind: "page_field_dirtied";
+      families: readonly string[];
+      revision: number;
+    }
+  | {
+      kind: "measurement_backend_ready";
+      fidelity: PublicMeasurementFidelity;
+      revision: number;
+    }
+  | {
+      kind: "incremental_relayout";
+      revision: number;
+      pageRange: { fromPageIndex: number; toPageIndex: number };
+      reason?: LayoutFacetInvalidationReason;
+    }
+  | {
+      kind: "render_frame_ready";
+      revision: number;
+      pageRange?: { fromPageIndex: number; toPageIndex: number };
+    }
+  | {
+      kind: "zoom_changed";
+      revision: number;
+      zoom: RenderZoomSummary;
+    };
+
+/**
+ * Minimal zoom summary carried with `zoom_changed`.  The render kernel
+ * (when shipped) provides richer zoom metadata; consumers today only need
+ * the resolved px-per-twip plus the fit mode to reposition chrome.
+ */
+export interface RenderZoomSummary {
+  pxPerTwip: number;
+  viewportWidthPx: number;
+  fitMode: "fixed" | "page-width" | "one-page";
+}
+
+export type LayoutFacetInvalidationReason =
+  | { kind: "content-edit"; from: number; to: number }
+  | { kind: "section-change"; sectionIndex: number }
+  | { kind: "styles-change" }
+  | { kind: "theme-change" }
+  | { kind: "numbering-change"; numberingInstanceId?: string }
+  | { kind: "field-refresh"; family?: string }
+  | { kind: "full" };
+
+// ---------------------------------------------------------------------------
+// Facet interface
+// ---------------------------------------------------------------------------
+
+export interface WordReviewEditorLayoutFacet {
+  // Structure ------------------------------------------------------------
+  getPageCount(): number;
+  getPage(pageIndex: number): PublicPageNode | null;
+  getPages(options?: { sectionIndex?: number }): PublicPageNode[];
+  getSection(sectionIndex: number): PublicSectionNode | null;
+  getSections(): PublicSectionNode[];
+
+  // Offset / selection navigation ---------------------------------------
+  getPageForOffset(
+    offset: number,
+    story?: EditorStoryTarget,
+  ): PublicPageNode | null;
+  getPageSpanForSelection(selection: SelectionSnapshot): PublicPageSpan | null;
+  getFragmentForOffset(
+    offset: number,
+    story?: EditorStoryTarget,
+  ): PublicBlockFragment | null;
+  getAnchorForOffset(
+    offset: number,
+    story?: EditorStoryTarget,
+  ): PublicPageAnchor | null;
+
+  // Per-page semantic reads ---------------------------------------------
+  getActiveStoriesOnPage(pageIndex: number): PublicResolvedPageStories | null;
+  getDisplayPageNumber(pageIndex: number): number | null;
+  getLineBoxes(
+    pageIndex: number,
+    options?: { region?: PublicPageRegion["kind"]; columnIndex?: number },
+  ): PublicLineBox[];
+  /** Back-compat alias; prefer `getLineBoxes(pageIndex, { region })`. */
+  getLineBoxesForRegion(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    options?: { columnIndex?: number },
+  ): readonly PublicLineBox[];
+  getFragmentsForPage(pageIndex: number): PublicBlockFragment[];
+
+  // Page-format catalog --------------------------------------------------
+  getPageFormatCatalog(): readonly PageFormatDefinition[];
+  getActivePageFormat(sectionIndex: number): ActivePageFormat | null;
+  getMarginPresetCatalog(): readonly MarginPresetDefinition[];
+  getActiveMarginPreset(sectionIndex: number): ActiveMarginPreset | null;
+
+  // Render-frame access (R1) --------------------------------------------
+  /**
+   * Return the active `RenderFrame` produced by the runtime-owned render
+   * kernel.  Optional when the host runtime has not yet installed a kernel
+   * — returns `null` in that case so consumers can fall back to the page-
+   * graph reads above.
+   */
+  getRenderFrame?(
+    options?: import("../render/index.ts").RenderFrameQueryOptions,
+  ): import("../render/index.ts").RenderFrame | null;
+
+  /** Return the render-kernel zoom, if a kernel is installed. */
+  getRenderZoom?(): import("../render/index.ts").RenderZoom | null;
+
+  /**
+   * Hit-test a point in the mounted shell's coordinate space against the
+   * current render frame.  Returns the deepest matching region with runtime
+   * offset, block id, fragment id, and line index so chrome surfaces can
+   * turn mouse coordinates into canonical positions without consulting the
+   * DOM.  Returns `null` when no kernel is installed, or when the point
+   * falls outside every page.
+   */
+  hitTest?(
+    pointInRoot: import("../render/index.ts").RenderPoint,
+  ): import("../render/index.ts").RenderHitResult | null;
+
+  /**
+   * Resolve anchor rects for a `RenderAnchorQuery`.  Returns `[]` when the
+   * kernel is absent or the query does not match any anchor.  Chrome
+   * surfaces that need a single rect can read `getAnchorRects(q)[0]`;
+   * selection-spanning surfaces read the full list and union as needed.
+   */
+  getAnchorRects?(
+    query: import("../render/index.ts").RenderAnchorQuery,
+  ): readonly import("../render/index.ts").RenderFrameRect[];
+
+  // Scope rail segments (R3a) -------------------------------------------
+  /**
+   * Return workflow rail segments active on a given page.  Returns an empty
+   * list when the host runtime did not supply workflow data to the facet.
+   */
+  getScopeRailSegments(
+    pageIndex: number,
+  ): readonly import("../workflow-rail-segments.ts").ScopeRailSegment[];
+  /** Return every scope rail segment across the document. */
+  getAllScopeRailSegments(): readonly import("../workflow-rail-segments.ts").ScopeRailSegment[];
+
+  // Measurement exposure -------------------------------------------------
+  getResolvedFormatting(blockId: string): PublicResolvedParagraphFormatting | null;
+  getResolvedRunFormatting(runId: string): PublicResolvedRunFormatting | null;
+  getMeasurement(blockId: string): PublicBlockMeasurement | null;
+  getMeasurementFidelity(): PublicMeasurementFidelity;
+  whenMeasurementReady(): Promise<void>;
+
+  // Table render plan (P3e consumed by the render kernel, P4) ------------
+  /**
+   * Build a `TableRenderPlan` for a table block on a given page. Returns
+   * `null` when the blockId does not resolve to a table in the current
+   * surface. The plan carries columnsTwips, bandClasses, verticalMerges,
+   * repeatedHeaderRows, and columnResizeHandles so chrome can render
+   * band-aware cell styling and place column-resize grips without
+   * walking canonical state.
+   */
+  getTableRenderPlan(
+    blockId: string,
+    pageIndex: number,
+  ): import("./table-render-plan.ts").TableRenderPlan | null;
+
+  // Fields ---------------------------------------------------------------
+  getDirtyFieldFamilies(): readonly string[];
+  getFieldDirtinessReport(): PublicFieldDirtinessReport;
+
+  // Events ---------------------------------------------------------------
+  subscribe(listener: (event: LayoutFacetEvent) => void): () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export interface CreateLayoutFacetInput {
+  engine: LayoutEngineInstance;
+  getQueryInput: () => LayoutEngineQueryInput;
+  /**
+   * Optional render-kernel accessor.  When supplied, the facet exposes
+   * `getRenderFrame` + `getRenderZoom` that delegate to the kernel.
+   */
+  renderKernel?: () =>
+    | import("../render/index.ts").RenderKernel
+    | null
+    | undefined;
+  /**
+   * Optional workflow-segments accessor.  When supplied, the facet computes
+   * `getScopeRailSegments` / `getAllScopeRailSegments` by joining the host-
+   * supplied workflow state with the current page graph.  When omitted,
+   * both methods return empty arrays.
+   */
+  getWorkflowRailInput?: () =>
+    | Omit<
+        import("../workflow-rail-segments.ts").CollectScopeRailSegmentsInput,
+        "pageGraph"
+      >
+    | null
+    | undefined;
+}
+
+export function createLayoutFacet(
+  input: CreateLayoutFacetInput,
+): WordReviewEditorLayoutFacet {
+  const { engine, getQueryInput } = input;
+
+  function currentGraph(): RuntimePageGraph {
+    return engine.getPageGraph(getQueryInput());
+  }
+  function currentMapper(): PageFragmentMapper {
+    return engine.getFragmentMapper(getQueryInput());
+  }
+  function currentFormatting(): ResolvedFormattingState {
+    return engine.getResolvedFormattingState(getQueryInput());
+  }
+
+  const listeners = new Set<(event: LayoutFacetEvent) => void>();
+  const unsubscribeEngine = engine.subscribe((event: LayoutEngineEvent) => {
+    // `incremental_relayout` needs the last page index so the facet can
+    // report a `pageRange: [fromPageIndex, toPageIndex]` without asking the
+    // engine for an extra read.  Use a best-effort lookup; on zero-page
+    // graphs the range collapses to the same index.
+    let lastPageIndex = 0;
+    try {
+      const pageCount = engine.getPageGraph(getQueryInput()).pages.length;
+      lastPageIndex = Math.max(0, pageCount - 1);
+    } catch {
+      lastPageIndex = 0;
+    }
+    const facetEvent = toFacetEvent(event, lastPageIndex);
+    if (!facetEvent) return;
+    for (const listener of listeners) {
+      try {
+        listener(facetEvent);
+      } catch {
+        // never let listener errors break the engine
+      }
+    }
+  });
+  // Keep the handle alive; the facet instance lives as long as the runtime.
+  void unsubscribeEngine;
+
+  return {
+    getPageCount() {
+      return currentGraph().pages.length;
+    },
+
+    getPage(pageIndex) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      return node ? toPublicPageNode(node, graph) : null;
+    },
+
+    getPages(options) {
+      const graph = currentGraph();
+      const filtered = options?.sectionIndex !== undefined
+        ? graph.pages.filter((p) => p.sectionIndex === options.sectionIndex)
+        : graph.pages;
+      return filtered.map((node) => toPublicPageNode(node, graph));
+    },
+
+    getSection(sectionIndex) {
+      const graph = currentGraph();
+      return toPublicSectionNode(graph, sectionIndex);
+    },
+
+    getSections() {
+      const graph = currentGraph();
+      return graph.sections
+        .map((section) => toPublicSectionNode(graph, section.index))
+        .filter((node): node is PublicSectionNode => node !== null);
+    },
+
+    getPageForOffset(offset, story) {
+      const graph = currentGraph();
+      const page = findPageForOffsetAndStory(graph, offset, story);
+      return page ? toPublicPageNode(page, graph) : null;
+    },
+
+    getPageSpanForSelection(selection) {
+      return currentMapper().mapSelectionToPageSpan(selection);
+    },
+
+    getFragmentForOffset(offset, story) {
+      const mapper = currentMapper();
+      const graph = currentGraph();
+      const location = mapper.mapOffsetToFragment(offset, story);
+      if (!location) return null;
+      const fragment = graph.fragments.find(
+        (f) => f.fragmentId === location.fragmentId,
+      );
+      if (!fragment) return null;
+      return toPublicBlockFragment(fragment, graph);
+    },
+
+    getAnchorForOffset(offset, story) {
+      const mapper = currentMapper();
+      const graph = currentGraph();
+      const anchor = mapper.getAnchorForOffset(offset, story);
+      if (!anchor) return null;
+      const page = graph.pages.find((p) => p.pageId === anchor.pageId);
+      if (!page) return null;
+      const fragmentLocation = mapper.mapOffsetToFragment(offset, story);
+      return {
+        offset: anchor.offset,
+        pageId: anchor.pageId,
+        pageIndex: page.pageIndex,
+        ...(fragmentLocation?.fragmentId !== undefined
+          ? { fragmentId: fragmentLocation.fragmentId }
+          : {}),
+        ...(fragmentLocation?.regionKind !== undefined
+          ? { regionKind: fragmentLocation.regionKind }
+          : {}),
+      };
+    },
+
+    getActiveStoriesOnPage(pageIndex) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      if (!node) return null;
+      return toPublicResolvedPageStories(node.stories);
+    },
+
+    getDisplayPageNumber(pageIndex) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      return node ? node.stories.displayPageNumber : null;
+    },
+
+    getLineBoxes(pageIndex, options) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      if (!node) return [];
+      const region = options?.region ?? "body";
+      return collectLineBoxesForRegion(
+        node,
+        region,
+        options?.columnIndex,
+      ).map((box) => toPublicLineBox(box));
+    },
+
+    getLineBoxesForRegion(pageIndex, region, options) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      if (!node) return [];
+      return collectLineBoxesForRegion(node, region, options?.columnIndex).map(
+        (box) => toPublicLineBox(box),
+      );
+    },
+
+    getPageFormatCatalog() {
+      return PAGE_FORMAT_CATALOG;
+    },
+
+    getActivePageFormat(sectionIndex) {
+      const graph = currentGraph();
+      const sectionPages = graph.pages.filter(
+        (p) => p.sectionIndex === sectionIndex,
+      );
+      const firstPage = sectionPages[0];
+      if (!firstPage) return null;
+      return matchPageFormat({
+        sectionIndex,
+        widthTwips: firstPage.layout.pageWidth,
+        heightTwips: firstPage.layout.pageHeight,
+      });
+    },
+
+    getMarginPresetCatalog() {
+      return MARGIN_PRESET_CATALOG;
+    },
+
+    getActiveMarginPreset(sectionIndex) {
+      const graph = currentGraph();
+      const sectionPages = graph.pages.filter(
+        (p) => p.sectionIndex === sectionIndex,
+      );
+      const firstPage = sectionPages[0];
+      if (!firstPage) return null;
+      const layout = firstPage.layout;
+      // `mirrorMargins` is a document-level setting
+      // (`w:mirrorMargins`) that the current canonical model does not
+      // surface onto the per-section layout snapshot; pass `false` until
+      // that plumbing exists so the Mirrored preset only matches when
+      // callers pass the preset-builder helper explicitly.
+      return matchMarginPreset({
+        sectionIndex,
+        topTwips: layout.marginTop,
+        bottomTwips: layout.marginBottom,
+        leftTwips: layout.marginLeft,
+        rightTwips: layout.marginRight,
+        gutterTwips: layout.gutter,
+        mirrored: false,
+      });
+    },
+
+    getRenderFrame(options) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return null;
+      return kernel.getRenderFrame(options);
+    },
+
+    getRenderZoom() {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return null;
+      return kernel.getZoom();
+    },
+
+    hitTest(pointInRoot) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return null;
+      const frame = kernel.getRenderFrame();
+      return resolveHitTest(frame, pointInRoot);
+    },
+
+    getAnchorRects(query) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return [];
+      const frame = kernel.getRenderFrame();
+      return resolveAnchorRects(frame, query);
+    },
+
+    getScopeRailSegments(pageIndex) {
+      return collectScopeRailSegmentsForQuery(
+        input.getWorkflowRailInput?.(),
+        currentGraph(),
+      ).filter((segment) => segment.pageIndex === pageIndex);
+    },
+
+    getAllScopeRailSegments() {
+      return collectScopeRailSegmentsForQuery(
+        input.getWorkflowRailInput?.(),
+        currentGraph(),
+      );
+    },
+
+    getFragmentsForPage(pageIndex) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      if (!node) return [];
+      return graph.fragments
+        .filter((f) => f.pageId === node.pageId)
+        .map((f) => toPublicBlockFragment(f, graph));
+    },
+
+    getResolvedFormatting(blockId) {
+      const state = currentFormatting();
+      const formatting = state.paragraphs.get(blockId);
+      if (!formatting) return null;
+      return toPublicParagraphFormatting(blockId, formatting);
+    },
+
+    getResolvedRunFormatting(runId) {
+      const state = currentFormatting();
+      const run = state.runs.get(runId);
+      if (!run) return null;
+      const blockId = runId.split(":")[0] ?? "";
+      return toPublicRunFormatting(runId, blockId, run);
+    },
+
+    getMeasurement(blockId) {
+      const graph = currentGraph();
+      const fragments = graph.fragments.filter((f) => f.blockId === blockId);
+      if (fragments.length === 0) return null;
+      const lineCount = graph.pages.reduce((total, page) => {
+        return (
+          total +
+          page.lineBoxes.filter((line) =>
+            fragments.some((f) => f.fragmentId === line.fragmentId),
+          ).length
+        );
+      }, 0);
+      const heightTwips = fragments.reduce((t, f) => t + f.heightTwips, 0);
+      return {
+        blockId,
+        lineCount,
+        heightTwips,
+      };
+    },
+
+    getMeasurementFidelity() {
+      return engine.measurementFidelity;
+    },
+
+    whenMeasurementReady() {
+      return engine.whenMeasurementReady();
+    },
+
+    getTableRenderPlan(blockId, pageIndex) {
+      const graph = currentGraph();
+      const fragment = graph.fragments.find((f) => f.blockId === blockId);
+      if (!fragment) return null;
+      const queryInput = getQueryInput();
+      const surface = lazyMainSurfaceForFacet(queryInput);
+      const tableBlock = findTableBlockByBlockId(surface.blocks, blockId);
+      if (!tableBlock) return null;
+      const resolved = resolveTableStyleResolutionForPlan(
+        tableBlock,
+        queryInput.document,
+      );
+      if (!resolved) return null;
+      // Sum all fragments for this block so the grip height spans every
+      // page the table occupies.
+      const tableHeightTwips = graph.fragments
+        .filter((f) => f.blockId === blockId)
+        .reduce((total, f) => total + f.heightTwips, 0);
+      return buildTableRenderPlan({
+        blockId,
+        pageIndex,
+        block: tableBlock,
+        resolved,
+        tableHeightTwips,
+      });
+    },
+
+    getDirtyFieldFamilies() {
+      return engine.getDirtyFieldFamilies();
+    },
+
+    getFieldDirtinessReport() {
+      const graph = currentGraph();
+      return {
+        families: engine.getDirtyFieldFamilies(),
+        revision: graph.revision,
+      };
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal: graph → public clones
+// ---------------------------------------------------------------------------
+
+function toPublicPageNode(
+  node: RuntimePageNode,
+  graph: RuntimePageGraph,
+): PublicPageNode {
+  return {
+    pageId: node.pageId,
+    pageIndex: node.pageIndex,
+    sectionIndex: node.sectionIndex,
+    pageInSection: node.pageInSection,
+    startOffset: node.startOffset,
+    endOffset: node.endOffset,
+    isBlankFiller: node.isBlankFiller,
+    displayPageNumber: node.stories.displayPageNumber,
+    isFirstPage: node.stories.isFirstPage,
+    isEvenPage: node.stories.isEvenPage,
+    layout: { ...node.layout },
+    stories: toPublicResolvedPageStories(node.stories),
+    regions: toPublicPageRegions(node.regions),
+    lineBoxCount: node.lineBoxes.length,
+    noteAllocations: node.noteAllocations.map(toPublicNoteAllocation),
+  };
+  void graph; // reserved for future cross-page derivations
+}
+
+function toPublicResolvedPageStories(
+  stories: ResolvedPageStories,
+): PublicResolvedPageStories {
+  return {
+    ...(stories.header ? { header: { ...stories.header } } : {}),
+    ...(stories.footer ? { footer: { ...stories.footer } } : {}),
+    isFirstPage: stories.isFirstPage,
+    isEvenPage: stories.isEvenPage,
+    displayPageNumber: stories.displayPageNumber,
+  };
+}
+
+function toPublicPageRegions(regions: RuntimePageRegions): PublicPageRegions {
+  return {
+    body: toPublicPageRegion(regions.body),
+    ...(regions.header ? { header: toPublicPageRegion(regions.header) } : {}),
+    ...(regions.footer ? { footer: toPublicPageRegion(regions.footer) } : {}),
+    ...(regions.columns ? { columns: regions.columns.map(toPublicPageRegion) } : {}),
+  };
+}
+
+function toPublicPageRegion(region: RuntimePageRegion): PublicPageRegion {
+  return {
+    kind: region.kind,
+    originTwips: region.originTwips,
+    widthTwips: region.widthTwips,
+    heightTwips: region.heightTwips,
+    fragmentCount: region.fragmentIds.length,
+  };
+}
+
+function toPublicBlockFragment(
+  fragment: RuntimeBlockFragment,
+  graph: RuntimePageGraph,
+): PublicBlockFragment {
+  const page = graph.pages.find((p) => p.pageId === fragment.pageId);
+  return {
+    fragmentId: fragment.fragmentId,
+    blockId: fragment.blockId,
+    pageId: fragment.pageId,
+    pageIndex: page?.pageIndex ?? -1,
+    regionKind: fragment.regionKind,
+    from: fragment.from,
+    to: fragment.to,
+    heightTwips: fragment.heightTwips,
+    orderInRegion: fragment.orderInRegion,
+  };
+}
+
+function toPublicLineBox(box: RuntimeLineBox): PublicLineBox {
+  return {
+    fragmentId: box.fragmentId,
+    lineIndex: box.lineIndex,
+    baselineTwips: box.baselineTwips,
+    heightTwips: box.heightTwips,
+    widthTwips: box.widthTwips,
+  };
+}
+
+function toPublicNoteAllocation(note: RuntimeNoteAllocation): PublicNoteAllocation {
+  return {
+    noteKind: note.noteKind,
+    noteId: note.noteId,
+    reservedHeightTwips: note.reservedHeightTwips,
+  };
+}
+
+function toPublicSectionNode(
+  graph: RuntimePageGraph,
+  sectionIndex: number,
+): PublicSectionNode | null {
+  const section = graph.sections.find((s) => s.index === sectionIndex);
+  if (!section) return null;
+  const sectionPages = graph.pages.filter(
+    (p) => p.sectionIndex === sectionIndex,
+  );
+  const firstPage = sectionPages[0];
+  const lastPage = sectionPages[sectionPages.length - 1];
+  if (!firstPage || !lastPage) return null;
+  return {
+    sectionIndex,
+    startOffset: section.start,
+    endOffset: section.end,
+    firstPageIndex: firstPage.pageIndex,
+    lastPageIndex: lastPage.pageIndex,
+    pageCount: sectionPages.length,
+    layout: { ...firstPage.layout },
+  };
+}
+
+function toPublicParagraphFormatting(
+  blockId: string,
+  formatting: ResolvedParagraphFormatting,
+): PublicResolvedParagraphFormatting {
+  return {
+    blockId,
+    spacingBefore: formatting.spacingBefore,
+    spacingAfter: formatting.spacingAfter,
+    lineHeight: formatting.lineHeight,
+    lineRule: formatting.lineRule,
+    indentLeft: formatting.indentLeft,
+    indentRight: formatting.indentRight,
+    firstLineIndent: formatting.firstLineIndent,
+    hangingIndent: formatting.hangingIndent,
+    fontSizeHalfPoints: formatting.fontSizeHalfPoints,
+    averageCharWidthTwips: formatting.averageCharWidthTwips,
+    tabStops: formatting.tabStops.map((tab) => ({
+      positionTwips: tab.position,
+      alignment: tab.align,
+      ...(tab.leader ? { leader: tab.leader } : {}),
+    })),
+    keepNext: formatting.keepNext,
+    keepLines: formatting.keepLines,
+    pageBreakBefore: formatting.pageBreakBefore,
+    widowControl: formatting.widowControl,
+    contextualSpacing: formatting.contextualSpacing,
+  };
+}
+
+function toPublicRunFormatting(
+  runId: string,
+  blockId: string,
+  run: ResolvedRunFormatting,
+): PublicResolvedRunFormatting {
+  return {
+    runId,
+    blockId,
+    ...(run.fontFamily ? { fontFamily: run.fontFamily } : {}),
+    ...(run.fontSizeHalfPoints !== undefined
+      ? { fontSizeHalfPoints: run.fontSizeHalfPoints }
+      : {}),
+    bold: run.bold,
+    italic: run.italic,
+    underline: run.underline,
+    strikethrough: run.strikethrough,
+    ...(run.color ? { color: run.color } : {}),
+    ...(run.highlight ? { highlight: run.highlight } : {}),
+    verticalAlign: run.verticalAlign,
+  };
+}
+
+function toFacetEvent(
+  event: LayoutEngineEvent,
+  lastPageIndex: number,
+): LayoutFacetEvent | null {
+  switch (event.kind) {
+    case "layout_recomputed":
+      return {
+        kind: "layout_recomputed",
+        revision: event.revision,
+        ...(event.reason ? { reason: event.reason } : {}),
+      };
+    case "page_count_changed":
+      return {
+        kind: "page_count_changed",
+        previous: event.previousPageCount ?? 0,
+        current: event.currentPageCount ?? 0,
+        revision: event.revision,
+      };
+    case "page_field_dirtied":
+      return {
+        kind: "page_field_dirtied",
+        families: event.dirtyFieldFamilies ?? [],
+        revision: event.revision,
+      };
+    case "measurement_backend_ready":
+      return {
+        kind: "measurement_backend_ready",
+        fidelity:
+          (event.fidelity as PublicMeasurementFidelity | undefined) ?? "empirical",
+        revision: event.revision,
+      };
+    case "incremental_relayout": {
+      const fromPageIndex =
+        event.firstDirtyPageIndex !== undefined
+          ? Math.max(0, event.firstDirtyPageIndex)
+          : 0;
+      const toPageIndex = Math.max(fromPageIndex, lastPageIndex);
+      return {
+        kind: "incremental_relayout",
+        revision: event.revision,
+        pageRange: { fromPageIndex, toPageIndex },
+        ...(event.reason ? { reason: event.reason } : {}),
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Resolve the page a given offset + story should surface on.
+ *
+ * Contract (per runtime-rendering-and-chrome-phase.md §2.3):
+ *   - Main story: the first content page containing the offset (unchanged).
+ *   - Header/footer story: the first page in the relevant section that
+ *     renders a header/footer matching the target variant.  When the
+ *     section-index hint is omitted, the first page rendering any
+ *     variant of this kind is returned.
+ *   - Footnote/endnote story: the first page that reserves a note
+ *     allocation for the given note (by note id); falls back to the
+ *     first content page so UI surfaces always have an anchor.
+ */
+function findPageForOffsetAndStory(
+  graph: RuntimePageGraph,
+  offset: number,
+  story?: EditorStoryTarget,
+): RuntimePageNode | null {
+  if (!story || story.kind === "main") {
+    for (const page of graph.pages) {
+      if (!page.isBlankFiller && offset < page.endOffset) {
+        return page;
+      }
+    }
+    const last = graph.pages[graph.pages.length - 1];
+    return last ?? null;
+  }
+
+  if (story.kind === "header" || story.kind === "footer") {
+    const targetKind = story.kind;
+    const targetVariant = story.variant;
+    const targetRelationshipId = story.relationshipId;
+    const sectionIndex = story.sectionIndex;
+    const candidates = graph.pages.filter((page) => {
+      if (page.isBlankFiller) return false;
+      if (sectionIndex !== undefined && page.sectionIndex !== sectionIndex) {
+        return false;
+      }
+      const side =
+        targetKind === "header" ? page.stories.header : page.stories.footer;
+      if (!side) return false;
+      if (side.kind !== "header" && side.kind !== "footer") return false;
+      if (targetVariant !== undefined && side.variant !== targetVariant) {
+        return false;
+      }
+      if (
+        targetRelationshipId !== undefined &&
+        side.relationshipId !== targetRelationshipId
+      ) {
+        return false;
+      }
+      return true;
+    });
+    if (candidates[0]) return candidates[0];
+    // Fallback: any page in the given section (or the first page overall)
+    if (sectionIndex !== undefined) {
+      const fallback = graph.pages.find(
+        (p) => p.sectionIndex === sectionIndex && !p.isBlankFiller,
+      );
+      if (fallback) return fallback;
+    }
+    const first = graph.pages.find((p) => !p.isBlankFiller);
+    return first ?? graph.pages[0] ?? null;
+  }
+
+  if (story.kind === "footnote" || story.kind === "endnote") {
+    const noteKind = story.kind;
+    const noteId = story.noteId;
+    if (noteId !== undefined) {
+      const page = graph.pages.find((p) =>
+        p.noteAllocations.some(
+          (a) => a.noteKind === noteKind && a.noteId === noteId,
+        ),
+      );
+      if (page) return page;
+    }
+    for (const page of graph.pages) {
+      if (!page.isBlankFiller && offset < page.endOffset) {
+        return page;
+      }
+    }
+    const last = graph.pages[graph.pages.length - 1];
+    return last ?? null;
+  }
+
+  return null;
+}
+
+/**
+ * Select line boxes that belong to a given region on a page.
+ *
+ * Today the engine populates body line boxes only; header/footer/column/
+ * footnote-area regions produce empty arrays until the render kernel lands
+ * (Phase R1).  The region filter is now exact: `body` returns only body
+ * line boxes, everything else returns empty.  Consumers should prefer
+ * `getLineBoxes(pageIndex, { region: "body" })` — the other kinds are
+ * scaffolded so UI can start reading through the facet without special-
+ * casing region availability.
+ */
+function collectLineBoxesForRegion(
+  node: RuntimePageNode,
+  region: PublicPageRegion["kind"],
+  _columnIndex: number | undefined,
+): readonly RuntimeLineBoxAlias[] {
+  void _columnIndex;
+  if (region === "body") {
+    return node.lineBoxes;
+  }
+  return EMPTY_LINE_BOXES;
+}
+
+// Use a shared alias so the region helper doesn't import the runtime
+// `RuntimeLineBox` type redundantly (`lineBoxes` is already strongly typed on
+// `RuntimePageNode`).
+type RuntimeLineBoxAlias = RuntimePageNode["lineBoxes"][number];
+const EMPTY_LINE_BOXES: readonly RuntimeLineBoxAlias[] = Object.freeze([]);
+
+/**
+ * Join the host-supplied workflow rail input with the current page graph.
+ * Returns an empty array when no input is available so callers can always
+ * iterate without null-checking.
+ */
+function collectScopeRailSegmentsForQuery(
+  input:
+    | Omit<
+        import("../workflow-rail-segments.ts").CollectScopeRailSegmentsInput,
+        "pageGraph"
+      >
+    | null
+    | undefined,
+  graph: RuntimePageGraph,
+): ScopeRailSegment[] {
+  if (!input) return [];
+  return collectScopeRailSegments({ ...input, pageGraph: graph });
+}
+
+function resolveHitTest(
+  frame: import("../render/index.ts").RenderFrame | null,
+  point: import("../render/index.ts").RenderPoint,
+): import("../render/index.ts").RenderHitResult | null {
+  if (!frame) return null;
+  for (const page of frame.pages) {
+    if (!containsPoint(page.frame, point)) continue;
+    const regionHit = hitTestRegion(page, point, "body");
+    if (regionHit) return regionHit;
+    const header = hitTestRegion(page, point, "header");
+    if (header) return header;
+    const footer = hitTestRegion(page, point, "footer");
+    if (footer) return footer;
+  }
+  return null;
+}
+
+function hitTestRegion(
+  page: import("../render/index.ts").RenderPage,
+  point: import("../render/index.ts").RenderPoint,
+  kind: "body" | "header" | "footer",
+): import("../render/index.ts").RenderHitResult | null {
+  const region =
+    kind === "body"
+      ? page.regions.body
+      : kind === "header"
+        ? page.regions.header
+        : page.regions.footer;
+  if (!region) return null;
+  if (!containsPoint(region.frame, point)) return null;
+  for (const block of region.blocks) {
+    if (!containsPoint(block.frame, point)) continue;
+    let bestLineIndex = -1;
+    let bestLineDistance = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < block.lines.length; i++) {
+      const line = block.lines[i]!;
+      const midY = line.frame.topPx + line.frame.heightPx / 2;
+      const distance = Math.abs(midY - point.yPx);
+      if (distance < bestLineDistance) {
+        bestLineDistance = distance;
+        bestLineIndex = i;
+      }
+    }
+    const lineIndex = bestLineIndex >= 0 ? bestLineIndex : 0;
+    const line = block.lines[lineIndex];
+    const runtimeOffset = line?.anchors[0]?.runtimeOffset ?? block.fragment.from;
+    return {
+      pageIndex: page.page.pageIndex,
+      regionKind: region.region.kind,
+      blockId: block.fragment.blockId,
+      fragmentId: block.fragment.fragmentId,
+      lineIndex,
+      runtimeOffset,
+    };
+  }
+  // Point fell inside the region but between blocks — snap to the nearest block.
+  let nearestBlock: import("../render/index.ts").RenderBlock | null = null;
+  let nearestDistance = Number.POSITIVE_INFINITY;
+  for (const block of region.blocks) {
+    const distance = Math.min(
+      Math.abs(point.yPx - block.frame.topPx),
+      Math.abs(point.yPx - (block.frame.topPx + block.frame.heightPx)),
+    );
+    if (distance < nearestDistance) {
+      nearestBlock = block;
+      nearestDistance = distance;
+    }
+  }
+  if (!nearestBlock) return null;
+  return {
+    pageIndex: page.page.pageIndex,
+    regionKind: region.region.kind,
+    blockId: nearestBlock.fragment.blockId,
+    fragmentId: nearestBlock.fragment.fragmentId,
+    lineIndex: 0,
+    runtimeOffset: nearestBlock.fragment.from,
+  };
+}
+
+function containsPoint(
+  rect: import("../render/index.ts").RenderFrameRect,
+  point: import("../render/index.ts").RenderPoint,
+): boolean {
+  return (
+    point.xPx >= rect.leftPx &&
+    point.xPx <= rect.leftPx + rect.widthPx &&
+    point.yPx >= rect.topPx &&
+    point.yPx <= rect.topPx + rect.heightPx
+  );
+}
+
+function resolveAnchorRects(
+  frame: import("../render/index.ts").RenderFrame | null,
+  query: import("../render/index.ts").RenderAnchorQuery,
+): readonly import("../render/index.ts").RenderFrameRect[] {
+  if (!frame) return [];
+  switch (query.kind) {
+    case "runtime-offset": {
+      const offset =
+        typeof query.value === "number" ? query.value : Number(query.value);
+      if (!Number.isFinite(offset)) return [];
+      const rect = frame.anchorIndex.byRuntimeOffset(offset, query.story);
+      return rect ? [rect] : [];
+    }
+    case "block-id": {
+      const rect = frame.anchorIndex.byBlockId(String(query.value));
+      return rect ? [rect] : [];
+    }
+    case "fragment-id": {
+      const rect = frame.anchorIndex.byFragmentId(String(query.value));
+      return rect ? [rect] : [];
+    }
+    case "page-index": {
+      const pageIndex =
+        typeof query.value === "number" ? query.value : Number(query.value);
+      if (!Number.isFinite(pageIndex)) return [];
+      const rect = frame.anchorIndex.byPageIndex(pageIndex);
+      return rect ? [rect] : [];
+    }
+    case "scope-id": {
+      const id = String(query.value);
+      return frame.decorationIndex.workflow
+        .filter((decoration) => decoration.refId === id)
+        .map((decoration) => decoration.frame);
+    }
+    case "comment-id": {
+      const id = String(query.value);
+      return frame.decorationIndex.comments
+        .filter((decoration) => decoration.refId === id)
+        .map((decoration) => decoration.frame);
+    }
+    case "revision-id": {
+      const id = String(query.value);
+      return frame.decorationIndex.revisions
+        .filter((decoration) => decoration.refId === id)
+        .map((decoration) => decoration.frame);
+    }
+    default: {
+      const exhaustive: never = query.kind;
+      void exhaustive;
+      return [];
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Table render plan helpers (P4)
+// ---------------------------------------------------------------------------
+
+/**
+ * Produce (or reuse) the main surface snapshot the facet needs for table
+ * plan resolution. The engine already rebuilds a surface on every full
+ * relayout, but that output is not cached externally — for a per-call
+ * `getTableRenderPlan` we reconstruct the surface with a static zero
+ * selection. This is a pure read and only runs on chrome requests, so
+ * the cost is bounded.
+ */
+function lazyMainSurfaceForFacet(
+  input: LayoutEngineQueryInput,
+): ReturnType<typeof createEditorSurfaceSnapshot> {
+  return createEditorSurfaceSnapshot(
+    input.document,
+    createSelectionSnapshot(0, 0),
+    MAIN_STORY_TARGET,
+  );
+}
+
+/**
+ * Walk a flat surface block list (with recursion into sdt/table nested
+ * children) to find a table block by its projected blockId.
+ */
+function findTableBlockByBlockId(
+  blocks: readonly SurfaceBlockSnapshot[],
+  blockId: string,
+): Extract<SurfaceBlockSnapshot, { kind: "table" }> | null {
+  for (const block of blocks) {
+    if (block.kind === "table") {
+      if (block.blockId === blockId) return block;
+      // Recurse into nested tables (cell contents may contain tables).
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          const nested = findTableBlockByBlockId(cell.content, blockId);
+          if (nested) return nested;
+        }
+      }
+    } else if (block.kind === "sdt_block") {
+      const nested = findTableBlockByBlockId(block.children, blockId);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the table-style cascade (direct properties → style chain → band
+ * conditional formatting) for a surface table block. Needs the canonical
+ * document to look up the underlying `TableNode` by blockId so the full
+ * resolver runs against canonical state, not the pre-projected surface.
+ */
+function resolveTableStyleResolutionForPlan(
+  surfaceTable: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
+  document: LayoutEngineQueryInput["document"],
+): ReturnType<typeof resolveTableStyleResolution> | null {
+  const canonicalTable = findCanonicalTableByBlockId(
+    document.content.children,
+    surfaceTable.blockId,
+    { counter: { value: 0 } },
+  );
+  if (!canonicalTable) return null;
+  return resolveTableStyleResolution(
+    canonicalTable,
+    document.styles.tables ?? {},
+  );
+}
+
+/**
+ * Walk canonical content depth-first incrementing the table counter to
+ * locate the `TableNode` whose projected blockId would be `table-${N}`.
+ * Mirrors the counter discipline in `src/runtime/surface-projection.ts`.
+ */
+function findCanonicalTableByBlockId(
+  children: import("../../model/canonical-document.ts").BlockNode[],
+  targetBlockId: string,
+  state: { counter: { value: number } },
+): import("../../model/canonical-document.ts").TableNode | null {
+  for (const child of children) {
+    if (child.type === "table") {
+      const index = state.counter.value;
+      state.counter.value += 1;
+      if (`table-${index}` === targetBlockId) return child;
+      for (const row of child.rows) {
+        for (const cell of row.cells) {
+          const nested = findCanonicalTableByBlockId(
+            cell.children,
+            targetBlockId,
+            state,
+          );
+          if (nested) return nested;
+        }
+      }
+    } else if (child.type === "sdt") {
+      const nested = findCanonicalTableByBlockId(
+        child.children,
+        targetBlockId,
+        state,
+      );
+      if (nested) return nested;
+    } else if (child.type === "custom_xml") {
+      const nested = findCanonicalTableByBlockId(
+        child.children,
+        targetBlockId,
+        state,
+      );
+      if (nested) return nested;
+    }
+  }
+  return null;
+}