@beyondwork/docx-react-component 1.0.37 → 1.0.39

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

@@ -42,7 +42,42 @@ import type {
   LayoutEngineInstance,
   LayoutEngineQueryInput,
 } from "./layout-engine-instance.ts";
+import type { LayoutMeasurementProvider } from "./layout-measurement-provider.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 { recordPerfSample } from "../../ui-tailwind/editor-surface/perf-probe.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)
@@ -224,8 +259,35 @@ export type LayoutFacetEvent =
       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 }
@@ -267,16 +329,111 @@ export interface WordReviewEditorLayoutFacet {
   getDisplayPageNumber(pageIndex: number): number | null;
   getLineBoxes(
     pageIndex: number,
-    options?: { region?: "body" | "header" | "footer" },
+    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>;
+  swapMeasurementProvider(provider: LayoutMeasurementProvider): void;
+
+  // Table render plan (P3e consumed by the render kernel, P4) ------------
+  /**
+   * 0-based page index where the first fragment of `blockId` lands, or
+   * `null` when the block has no fragments in the current page graph.
+   * Used by the tables facet to determine which page to request plans for
+   * without needing PM document offsets.
+   */
+  getFirstPageIndexForBlock(blockId: string): number | null;
+  /**
+   * 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;
+
+  // 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[];
@@ -293,6 +450,27 @@ export interface WordReviewEditorLayoutFacet {
 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(
@@ -312,7 +490,18 @@ export function createLayoutFacet(
 
   const listeners = new Set<(event: LayoutFacetEvent) => void>();
   const unsubscribeEngine = engine.subscribe((event: LayoutEngineEvent) => {
-    const facetEvent = toFacetEvent(event);
+    // `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 {
@@ -356,15 +545,10 @@ export function createLayoutFacet(
         .filter((node): node is PublicSectionNode => node !== null);
     },
 
-    getPageForOffset(offset, _story) {
+    getPageForOffset(offset, story) {
       const graph = currentGraph();
-      for (const page of graph.pages) {
-        if (!page.isBlankFiller && offset < page.endOffset) {
-          return toPublicPageNode(page, graph);
-        }
-      }
-      const last = graph.pages[graph.pages.length - 1];
-      return last ? toPublicPageNode(last, graph) : null;
+      const page = findPageForOffsetAndStory(graph, offset, story);
+      return page ? toPublicPageNode(page, graph) : null;
     },
 
     getPageSpanForSelection(selection) {
@@ -422,11 +606,109 @@ export function createLayoutFacet(
       const node = graph.pages[pageIndex];
       if (!node) return [];
       const region = options?.region ?? "body";
-      // Today all line boxes live on the body.  The region filter is
-      // defensive for when header/footer metrics are also populated.
-      return node.lineBoxes
-        .filter(() => region === "body")
-        .map((box) => toPublicLineBox(box));
+      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 t0 = typeof performance !== "undefined" ? performance.now() : 0;
+      const frame = kernel.getRenderFrame();
+      const result = resolveHitTest(frame, pointInRoot);
+      if (t0 > 0) recordPerfSample("chrome.hit_test", performance.now() - t0);
+      return result;
+    },
+
+    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) {
@@ -481,6 +763,45 @@ export function createLayoutFacet(
       return engine.whenMeasurementReady();
     },
 
+    getFirstPageIndexForBlock(blockId) {
+      const graph = currentGraph();
+      const fragment = graph.fragments.find((f) => f.blockId === blockId);
+      if (!fragment) return null;
+      const page = graph.pages.find((p) => p.pageId === fragment.pageId);
+      return page?.pageIndex ?? null;
+    },
+
+    swapMeasurementProvider(provider) {
+      engine.swapMeasurementProvider(provider);
+    },
+
+    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();
     },
@@ -671,7 +992,10 @@ function toPublicRunFormatting(
   };
 }
 
-function toFacetEvent(event: LayoutEngineEvent): LayoutFacetEvent | null {
+function toFacetEvent(
+  event: LayoutEngineEvent,
+  lastPageIndex: number,
+): LayoutFacetEvent | null {
   switch (event.kind) {
     case "layout_recomputed":
       return {
@@ -699,7 +1023,415 @@ function toFacetEvent(event: LayoutEngineEvent): LayoutFacetEvent | null {
           (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;
+}