@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/geometry/geometry-facet.ts

@@ -0,0 +1,364 @@
+/**
+ * Layer 05 — Geometry facet.
+ *
+ * The `GeometryFacet` is the runtime-internal surface for concrete visual
+ * geometry. Per `docs/architecture/05-geometry-projection.md`, this surface
+ * owns rects, hit-tests, carets, anchors, and replacement envelopes; it is
+ * consumed by layer 07 (Runtime API) and chrome overlays.
+ *
+ * Slice 1: scaffold as a thin proxy over the layout facet.
+ * Slice 2a: direct path — `hitTest` / `getAnchorRects` call the moved
+ *   pure helpers (`resolveHitTest` / `resolveAnchorRects`) against the
+ *   render kernel's current frame.
+ * Slice 3: viewport becomes DOM-backed; chrome overlays subscribe.
+ * Slice 4: caret geometry.
+ * Slice 5: replacement envelope + object handles.
+ * Slice 6 (2026-04-22 wrapper-deletion pass): the layout-facet
+ *   `hitTest` + `getAnchorRects` wrappers were deleted, along with the
+ *   geometry-facet's layout-facet fallback paths. `hitTest` /
+ *   `getAnchorRects` now return null / [] when no kernel is wired
+ *   (headless tests, pre-paint); production always wires the kernel
+ *   via `document-runtime.ts`.
+ */
+
+import type { EditorStoryTarget } from "../../api/public-types";
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  PublicLineBox,
+  PublicPageRegion,
+  WordReviewEditorLayoutFacet,
+} from "../layout/public-facet.ts";
+import type { RenderKernel } from "../render/index.ts";
+import { resolveScope } from "../workflow/scope-resolver.ts";
+import type { ScopeRailSegment } from "../workflow/rail/compose.ts";
+import type {
+  AnchorQuery,
+  BlockGeometry,
+  CaretGeometry,
+  EnvelopeBundle,
+  GeometryRect,
+  HitTestPoint,
+  HitTestResult,
+  PageGeometry,
+  Viewport,
+  ViewportListener,
+} from "./geometry-types.ts";
+import {
+  resolveCaretGeometry,
+  resolveSelectionRects,
+} from "./caret-geometry.ts";
+import { resolveHitTest } from "./hit-test.ts";
+import { resolveObjectHandles } from "./object-handles.ts";
+import { resolveAnchorRects } from "./project-anchors.ts";
+import {
+  resolveReplacementEnvelope,
+  type ReplacementScope,
+} from "./replacement-envelope.ts";
+import {
+  getBlockGeometryFromFrame,
+  getBlockRectsFromFrame,
+  getPageFromFrame,
+} from "./project-fragments.ts";
+import { createViewport, type ViewportHandle } from "./viewport.ts";
+
+// ---------------------------------------------------------------------------
+// Public surface
+// ---------------------------------------------------------------------------
+
+export interface GeometryFacet {
+  // Hit-test -------------------------------------------------------------
+  /**
+   * Resolve a point in the shell's overlay coordinate space to a canonical
+   * position. Routes directly to the render-kernel frame via
+   * `resolveHitTest`. Returns null when no kernel is wired (headless
+   * tests, pre-paint). The layout-facet fallback was deleted in the
+   * refactor/05 Slice 6 wrapper-deletion pass (2026-04-22).
+   */
+  hitTest(point: HitTestPoint): HitTestResult | null;
+
+  // Anchors --------------------------------------------------------------
+  /**
+   * Rect bundle for an anchor query (selection range, block id, scope id,
+   * etc.). Resolves directly via `resolveAnchorRects` against the render
+   * frame. Returns [] when no kernel is wired.
+   */
+  getAnchorRects(query: AnchorQuery): readonly GeometryRect[];
+
+  /**
+   * Convenience single-rect read — returns the first rect, or the union on
+   * spanning selections where the layout facet has already reduced it.
+   */
+  getAnchor(query: AnchorQuery): GeometryRect | null;
+
+  // Fragment projection (Slice 2b) ---------------------------------------
+  /**
+   * Rects (one per page-fragment) for a block, tagged `space: "frame"`.
+   * Resolves through the render kernel's frame — a multi-page block yields
+   * multiple rects in page order. Returns `[]` when no kernel is wired or
+   * the block has no fragments.
+   *
+   * New in Slice 2b. Slice 5 promotes `v3 runtime.geometry.getBlockRects`
+   * from `mock` to `live-with-adapter` against this method.
+   */
+  getBlockRects(blockId: string): readonly GeometryRect[];
+
+  /**
+   * Resolve a page by index or id. Returns the `PageGeometry` read from
+   * the kernel's current frame, or `null` when no kernel is wired or the
+   * target page is not in the frame. New in Slice 3a — the substrate
+   * chrome overlays consume in place of `getBoundingClientRect` on the
+   * overlay root.
+   *
+   * Dispatch: `typeof target === "number"` resolves as a 0-based page
+   * index; any other value is resolved as a `pageId` string match.
+   * Numeric-looking strings (e.g. `"0"`) are treated as pageIds, not
+   * indices — match the runtime's `RuntimePageNode.pageId` shape.
+   */
+  getPage(target: number | string): PageGeometry | null;
+
+  /**
+   * Resolve a block to its `BlockGeometry` (rects per page the block
+   * spans). Returns `null` when no kernel is wired or the block has no
+   * fragments. New in Slice 3a — the substrate `scroll-anchor` consumes
+   * in place of the `offsetTop` / `offsetParent` chain.
+   */
+  getBlock(blockId: string): BlockGeometry | null;
+
+  /**
+   * Per-region line boxes for a page — delegates to the layout facet's
+   * `getLineBoxes` since body line boxes are measured by the paginator and
+   * header/footer/column/footnote-area lines are synthesized from
+   * fragment heights (see
+   * `src/runtime/geometry/project-fragments.ts::collectLineBoxesForRegion`,
+   * moved from the layout facet in Slice 2b).
+   */
+  getLineBoxes(
+    pageIndex: number,
+    options?: { region?: PublicPageRegion["kind"]; columnIndex?: number },
+  ): readonly PublicLineBox[];
+
+  // Workflow-scope rail methods removed by Layer-06 Slice 4. Consume
+  // via `runtime.workflow.getRailSegments(pageIndex)` /
+  // `runtime.workflow.getAllRailSegments()`. Layer-05 geometry now
+  // only exposes page/anchor/caret primitives; workflow composition
+  // is Layer-06's responsibility.
+
+  // Caret + selection (Slice 4) -----------------------------------------
+  getCaret(offset: number, story?: EditorStoryTarget): CaretGeometry | null;
+  getSelectionRects(range: {
+    from: number;
+    to: number;
+    story?: EditorStoryTarget;
+  }): readonly GeometryRect[];
+
+  // Replacement envelope + object handles (Slice 5) ---------------------
+  getReplacementEnvelope(scopeId: string): EnvelopeBundle | null;
+  /**
+   * Resolve the handle points for an object. Slice-5 substrate
+   * addresses objects by `blockId` via `frame.anchorIndex.byBlockId`
+   * — so an inline image embedded in a paragraph resolves to the
+   * enclosing paragraph's rect, not the image's own rect. Callers
+   * that need per-object (not per-block) bboxes should consult the
+   * deferred-items list in the refactor/05 closure note: an object-
+   * specific anchor index is part of a later slice.
+   */
+  getObjectHandles(objectId: string): readonly GeometryRect[];
+
+  // Render-kernel passthroughs (migration target for Layer 04's
+  // deprecated `layoutFacet.getRenderFrame` / `.getRenderZoom`;
+  // tracked in `docs/plans/cross-layer-coord-05.md` §8).
+  //
+  // These return the kernel's primitive types (`RenderFrame`,
+  // `RenderZoom`) rather than geometry-projected types — callers that
+  // only need a projection should use `getPage` / `getAnchorRects` /
+  // `getCaret` instead. The passthroughs exist specifically so UI
+  // consumers (selection-anchor resolver, table-grip layer,
+  // scope-rail layer, object-selection overlay, PM surface) can flip
+  // their `layoutFacet.getRenderFrame?.()` reads onto the geometry
+  // facet before the layout-facet versions are deleted.
+  getRenderFrame(
+    options?: import("../render/index.ts").RenderFrameQueryOptions,
+  ): import("../render/index.ts").RenderFrame | null;
+  getRenderZoom(): import("../render/index.ts").RenderZoom | null;
+
+  // Viewport (Slice 3 wires real DOM reads) ------------------------------
+  getViewport(): Viewport;
+  subscribeViewport(listener: ViewportListener): () => void;
+}
+
+export interface CreateGeometryFacetInput {
+  layoutFacet: WordReviewEditorLayoutFacet;
+  /**
+   * Render-kernel getter. Geometry resolves through `resolveHitTest` /
+   * `resolveAnchorRects` against the kernel's current frame. When omitted
+   * (headless tests, pre-paint), `hitTest` returns null and
+   * `getAnchorRects` returns []. The layout-facet fallback was deleted in
+   * the refactor/05 Slice 6 wrapper-deletion pass (2026-04-22).
+   */
+  renderKernel?: () => RenderKernel | null;
+  /**
+   * Canonical document getter. Required for `getReplacementEnvelope` to
+   * resolve scope ids to runtime offset ranges (via `resolveScope`).
+   * When omitted, `getReplacementEnvelope` returns `null` — same
+   * fall-through used when no renderKernel is wired. Slice 5 added.
+   */
+  getCanonicalDocument?: () =>
+    | CanonicalDocument
+    | CanonicalDocumentEnvelope
+    | null
+    | undefined;
+  /**
+   * Optional viewport handle. When omitted, Slice 1's in-memory stub is
+   * used. Slice 3 installs a DOM-backed handle from `editor-surface`.
+   */
+  viewport?: ViewportHandle;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createGeometryFacet(
+  input: CreateGeometryFacetInput,
+): GeometryFacet {
+  const { layoutFacet } = input;
+  const viewport = input.viewport ?? createViewport();
+
+  return {
+    hitTest(point) {
+      // Slice 6 wrapper-deletion (2026-04-22): the layout-facet fallback
+      // was deleted. `hitTest` now resolves only through the render-kernel
+      // frame; returns null when no kernel is wired (headless tests,
+      // pre-paint).
+      const kernel = input.renderKernel?.();
+      if (!kernel) return null;
+      const frame = kernel.getRenderFrame();
+      const raw = resolveHitTest(frame, { xPx: point.xPx, yPx: point.yPx });
+      if (!raw) return null;
+      return {
+        pageIndex: raw.pageIndex,
+        regionKind: raw.regionKind,
+        blockId: raw.blockId,
+        fragmentId: raw.fragmentId,
+        lineIndex: raw.lineIndex,
+        runtimeOffset: raw.runtimeOffset,
+      };
+    },
+
+    getAnchorRects(query) {
+      // Slice 6 wrapper-deletion: kernel-only resolution; [] when no kernel.
+      const kernel = input.renderKernel?.();
+      if (!kernel) return [];
+      const frame = kernel.getRenderFrame();
+      const raw = resolveAnchorRects(frame, {
+        kind: query.kind,
+        value: query.value,
+        story: query.story,
+      });
+      if (raw.length === 0) return [];
+      return raw.map(
+        (r): GeometryRect => ({
+          leftPx: r.leftPx,
+          topPx: r.topPx,
+          widthPx: r.widthPx,
+          heightPx: r.heightPx,
+          space: "frame",
+        }),
+      );
+    },
+
+    getAnchor(query) {
+      const rects = this.getAnchorRects(query);
+      return rects[0] ?? null;
+    },
+
+    getBlockRects(blockId) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return [];
+      return getBlockRectsFromFrame(kernel.getRenderFrame(), blockId);
+    },
+
+    getPage(target) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return null;
+      return getPageFromFrame(kernel.getRenderFrame(), target);
+    },
+
+    getBlock(blockId) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return null;
+      return getBlockGeometryFromFrame(kernel.getRenderFrame(), blockId);
+    },
+
+    getLineBoxes(pageIndex, options) {
+      return layoutFacet.getLineBoxes(pageIndex, options);
+    },
+
+    getCaret(offset, story) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return null;
+      return resolveCaretGeometry(kernel.getRenderFrame(), offset, story);
+    },
+
+    getSelectionRects(range) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return [];
+      return resolveSelectionRects(kernel.getRenderFrame(), range);
+    },
+
+    getReplacementEnvelope(scopeId) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return null;
+      const document = input.getCanonicalDocument?.();
+      if (!document) return null;
+      const anchor = resolveScope(document, scopeId);
+      if (!anchor) return null;
+      let scope: ReplacementScope;
+      if (anchor.kind === "range") {
+        scope = { kind: "range", from: anchor.from, to: anchor.to };
+      } else if (anchor.kind === "detached") {
+        scope = {
+          kind: "detached",
+          lastKnownRange: {
+            from: anchor.lastKnownRange.from,
+            to: anchor.lastKnownRange.to,
+          },
+        };
+      } else {
+        // node-anchor kind — not a replaceable range; caller wanted a
+        // range resolution. Future slice may add node-based envelopes.
+        return null;
+      }
+      return resolveReplacementEnvelope(kernel.getRenderFrame(), scope);
+    },
+
+    getObjectHandles(objectId) {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return [];
+      return resolveObjectHandles(kernel.getRenderFrame(), objectId);
+    },
+
+    // Render-kernel passthroughs (migration target for layout-facet
+    // deprecated `getRenderFrame` / `getRenderZoom`).
+    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();
+    },
+
+    getViewport() {
+      return viewport.getViewport();
+    },
+
+    subscribeViewport(listener) {
+      return viewport.subscribe(listener);
+    },
+  };
+}

package/src/runtime/geometry/geometry-types.ts

@@ -0,0 +1,256 @@
+/**
+ * Layer 05 — Geometry Projection — type surface.
+ *
+ * Per `docs/architecture/05-geometry-projection.md`, layer 05 owns concrete
+ * visual geometry (rects, hit-tests, carets, envelopes, anchors). This module
+ * defines the public type surface consumed by the `GeometryFacet` and by
+ * consumers through layer 07.
+ *
+ * Slice 1 (this slice) reserves the directory and publishes these types while
+ * the `GeometryFacet` delegates to the existing `layout/public-facet.ts` +
+ * `render/render-kernel.ts` sites — so the Slice-1 shapes intentionally
+ * mirror `RenderFrameRect`, `RenderHitResult`, and `RenderAnchorQuery` from
+ * `../render/render-frame-types.ts`. Slices 2+ migrate the implementations
+ * here and may evolve the types independently of the render-kernel shapes.
+ *
+ * Contract references (architecture 05):
+ *   G1 — geometry is a projection of truth, not truth
+ *   G2 — no DOM reads as document-structure authority
+ *   G3 — all layout reads in callbacks coalesce via rAF
+ *   G4 — invalidation is bounded by layout invalidation
+ *   G5 — geometry coordinates are explicit (space + unit)
+ *   G6 — hit-test, caret, and envelope are first-class operations
+ *   G7 — replacement envelopes are stable under edits at the same scope
+ */
+
+import type { EditorStoryTarget } from "../../api/public-types";
+import type { PublicPageRegion } from "../layout/public-facet.ts";
+
+// ---------------------------------------------------------------------------
+// G5 · Coordinate space tags
+// ---------------------------------------------------------------------------
+
+/**
+ * Every `GeometryRect` carries an explicit coordinate space. Consumers choose;
+ * the geometry layer never silently converts.
+ *
+ *   - `twips`  — document-relative semantic units. Zoom-independent. The
+ *                representation the oracle compares against.
+ *   - `frame`  — frame-local pixels, post-zoom, origin at the frame root.
+ *                This is what the render kernel emits today.
+ *   - `overlay`— overlay-local pixels, origin at the overlay root (for
+ *                chrome surfaces that read rects projected through
+ *                `chrome-overlay-projector`).
+ */
+export type GeometrySpace = "twips" | "frame" | "overlay";
+
+// ---------------------------------------------------------------------------
+// Precision discriminator (refactor/05 Slice 7b · 2026-04-22)
+// ---------------------------------------------------------------------------
+
+/**
+ * Precision tag carried on geometry results so callers can tell exact
+ * projections from substrate placeholders.
+ *
+ *   - `"exact"`             — value comes from a real per-run / per-line
+ *                             projection and should be consumed as ground
+ *                             truth. Consumers may render with pixel-level
+ *                             confidence.
+ *   - `"within-tolerance"`  — value comes from a real projection but was
+ *                             widened to a conservative bound (e.g. union
+ *                             rect across a wrapped range). Safe for visual
+ *                             chrome; may overshoot by one line.
+ *   - `"heuristic"`         — value comes from a substrate placeholder:
+ *                             hardcoded direction, baseline derived from a
+ *                             height ratio, object handles derived from
+ *                             enclosing-block bbox, etc. Consumers that need
+ *                             correctness (not just visual) should fall back
+ *                             or gate.
+ *
+ * Fields are optional on existing result types for backward-compat; treat
+ * a missing `precision` as `"exact"` when derived from the render kernel's
+ * frame/anchor index, and as `"heuristic"` when the value is known to be a
+ * substrate placeholder (caller-side convention — the method JSDoc names
+ * which).
+ */
+export type GeometryPrecision = "exact" | "within-tolerance" | "heuristic";
+
+// ---------------------------------------------------------------------------
+// Core rect shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Rect carrying its coordinate space. Pixel-valued in `frame` / `overlay`;
+ * twip-valued in `twips`. Consumers read `space` before interpreting the
+ * numeric fields.
+ *
+ * `precision` is optional; rects emitted from exact frame/anchor projections
+ * omit it (implicitly exact), while rects derived from substrate placeholders
+ * (union-rect selection, block-bbox object handle, etc.) tag themselves so
+ * callers can discriminate.
+ */
+export interface GeometryRect {
+  leftPx: number;
+  topPx: number;
+  widthPx: number;
+  heightPx: number;
+  space: GeometrySpace;
+  precision?: GeometryPrecision;
+}
+
+// ---------------------------------------------------------------------------
+// Per-granularity geometry nodes (read models; Slice 2+ populates them)
+// ---------------------------------------------------------------------------
+
+export interface PageGeometry {
+  pageId: string;
+  pageIndex: number;
+  frame: GeometryRect;
+}
+
+export interface BlockGeometry {
+  blockId: string;
+  rects: readonly GeometryRect[];
+}
+
+export interface LineGeometry {
+  fragmentId: string;
+  lineIndex: number;
+  rect: GeometryRect;
+  /** Baseline offset from the line rect's top, in the rect's unit. */
+  baseline: number;
+}
+
+export interface RunGeometry {
+  runId: string;
+  rect: GeometryRect;
+}
+
+// ---------------------------------------------------------------------------
+// Caret + selection (Slice 4)
+// ---------------------------------------------------------------------------
+
+export interface CaretGeometry {
+  rect: GeometryRect;
+  /** Baseline offset from `rect.topPx`, in the rect's unit. */
+  baseline: number;
+  /** Caret height in the rect's unit. */
+  height: number;
+  /** Writing direction at the caret position. */
+  direction: "ltr" | "rtl";
+  /**
+   * Precision tag. Substrate caret today hardcodes `direction: "ltr"`
+   * and derives `baseline` from a `0.8 * height` heuristic — both
+   * fields are flagged `"heuristic"` until the render-kernel's per-run
+   * anchors ship. Rect position itself comes from `byRuntimeOffset` on
+   * the anchor index and is `"exact"` for unwrapped paragraphs,
+   * `"within-tolerance"` inside wrapped paragraphs. The coarsest tag
+   * wins — so today `precision` is always `"heuristic"`.
+   */
+  precision?: GeometryPrecision;
+}
+
+// ---------------------------------------------------------------------------
+// Hit-test (Slice 2 owns the real implementation)
+// ---------------------------------------------------------------------------
+
+export interface HitTestPoint {
+  xPx: number;
+  yPx: number;
+  space: GeometrySpace;
+}
+
+export interface HitTestResult {
+  pageIndex: number;
+  regionKind: PublicPageRegion["kind"];
+  blockId: string;
+  fragmentId: string;
+  lineIndex: number;
+  runtimeOffset: number;
+  /**
+   * Caret association relative to the resolved offset — reserved for Slice 4
+   * when caret geometry lands. Slice 1 proxy sets this to "after" to mirror
+   * the render-kernel's implicit association.
+   */
+  assoc?: "before" | "after";
+}
+
+// ---------------------------------------------------------------------------
+// Anchor queries (Slice 2 migrates real implementation)
+// ---------------------------------------------------------------------------
+
+export type AnchorQueryKind =
+  | "runtime-offset"
+  | "block-id"
+  | "fragment-id"
+  | "scope-id"
+  | "comment-id"
+  | "revision-id"
+  | "page-index";
+
+export interface AnchorQuery {
+  kind: AnchorQueryKind;
+  value: string | number;
+  story?: EditorStoryTarget;
+}
+
+// ---------------------------------------------------------------------------
+// Replacement envelopes + object handles (Slice 5)
+// ---------------------------------------------------------------------------
+
+export type EnvelopeConfidence = "exact" | "medium" | "detached";
+
+export interface EnvelopeBundle {
+  /**
+   * Rect coverage for the resolved scope. Slice-5 substrate produces
+   * **one** union rect for any non-collapsed range (mirrors the
+   * Slice-4 `resolveSelectionRects` contract); when the render kernel
+   * grows per-run anchors, this field upgrades to one-rect-per-line
+   * automatically. Consumers that need per-line enumeration TODAY
+   * should check `scopeRects.length` and fall back to their own line
+   * walk if the count is lower than expected.
+   */
+  scopeRects: readonly GeometryRect[];
+  /** Anchor point consumers attach chrome to (top-left of first rect). */
+  attachPoint: { xPx: number; yPx: number; space: GeometrySpace };
+  /**
+   * How confident the envelope is. `"detached"` means the scope's markers
+   * were removed; `lastKnownRange` describes the last observed rects.
+   */
+  confidence: EnvelopeConfidence;
+  /**
+   * Number of entries in `scopeRects` — NOT the number of line boxes
+   * the scope covers in the source document. Under the Slice-5
+   * substrate this is always `1` for non-collapsed ranges; the field
+   * becomes a true line-count once per-run anchors land. Renaming to
+   * `scopeRectCount` is tracked in the deferred-items list for the
+   * layer-05 closure.
+   */
+  linesCrossed: number;
+  /**
+   * Precision tag. `"exact"` when the envelope collapsed to a caret rect
+   * (single anchor position); `"within-tolerance"` when the envelope is
+   * a single union rect over a wrapped range (substrate default — may
+   * overshoot by up to one line of trailing whitespace); `"heuristic"`
+   * when the markers were detached and the envelope uses a last-known
+   * fallback. Consumers should gate per-line chrome work on
+   * `precision === "exact"`.
+   */
+  precision?: GeometryPrecision;
+}
+
+// ---------------------------------------------------------------------------
+// Viewport (Slice 3 wires the real DOM read path)
+// ---------------------------------------------------------------------------
+
+export interface Viewport {
+  /** Scroll position of the editor root, in CSS pixels. */
+  scrollLeftPx: number;
+  scrollTopPx: number;
+  /** Device-pixel-ratio snapshot at read time. */
+  dpr: number;
+  /** Current zoom pxPerTwip (mirrors `RenderZoom.pxPerTwip`). */
+  pxPerTwip: number;
+}
+
+export type ViewportListener = (viewport: Viewport) => void;