@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/geometry/hit-test.ts

@@ -0,0 +1,125 @@
+/**
+ * Layer 05 — Hit-test.
+ *
+ * Pure projection of a `RenderFrame` + `RenderPoint` onto a canonical
+ * `RenderHitResult`. Walks pages → regions → blocks → lines, snapping to
+ * the nearest line's first anchor to resolve a runtime offset.
+ *
+ * Slice 2a moves this implementation here from
+ * `src/runtime/layout/public-facet.ts`. The layout facet's deprecated
+ * `hitTest` method now delegates to `resolveHitTest` through this module —
+ * behavior is byte-identical. Slice 6 deletes the layout-facet wrapper.
+ *
+ * Contract (architecture 05 G6): hit-test is a first-class operation owned
+ * by layer 05; consumers MUST route through the geometry facet rather than
+ * re-implementing the walk.
+ */
+
+import type {
+  RenderBlock,
+  RenderFrame,
+  RenderFrameRect,
+  RenderHitResult,
+  RenderPage,
+  RenderPoint,
+  RenderStoryRegion,
+} from "../render/index.ts";
+
+export function resolveHitTest(
+  frame: RenderFrame | null,
+  point: RenderPoint,
+): RenderHitResult | null {
+  if (!frame) return null;
+  for (const page of frame.pages) {
+    if (!containsPoint(page.frame, point)) continue;
+    // Check body first — it owns the bulk of the page. Header /
+    // footer / footnotes are secondary stories and only matter when
+    // the point falls outside the body.
+    const bodyHit = hitTestStoryRegion(page, point, page.regions.body);
+    if (bodyHit) return bodyHit;
+    if (page.regions.header) {
+      const header = hitTestStoryRegion(page, point, page.regions.header);
+      if (header) return header;
+    }
+    if (page.regions.footer) {
+      const footer = hitTestStoryRegion(page, point, page.regions.footer);
+      if (footer) return footer;
+    }
+    // Refactor/05 Slice 7d: footnote regions now participate in
+    // hit-test routing so a click inside the footnote area resolves
+    // to the correct story offset rather than snapping to the
+    // enclosing body page. Each footnote area is a first-class
+    // RenderStoryRegion with its own story target + blocks.
+    if (page.regions.footnotes) {
+      for (const footnoteRegion of page.regions.footnotes) {
+        const hit = hitTestStoryRegion(page, point, footnoteRegion);
+        if (hit) return hit;
+      }
+    }
+  }
+  return null;
+}
+
+function hitTestStoryRegion(
+  page: RenderPage,
+  point: RenderPoint,
+  region: RenderStoryRegion,
+): RenderHitResult | 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: 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: RenderFrameRect, point: RenderPoint): boolean {
+  return (
+    point.xPx >= rect.leftPx &&
+    point.xPx <= rect.leftPx + rect.widthPx &&
+    point.yPx >= rect.topPx &&
+    point.yPx <= rect.topPx + rect.heightPx
+  );
+}

package/src/runtime/geometry/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Layer 05 — Geometry Projection — barrel.
+ *
+ * Public surface for the runtime-internal geometry layer. Architecture target
+ * lives at `docs/architecture/05-geometry-projection.md`; slice-by-slice
+ * migration plan at `docs/plans/refactor/05-geometry-projection.md`.
+ *
+ * Slice 1 exports the type surface + facet factory (thin proxy). Later slices
+ * add `hit-test.ts`, `project-anchors.ts`, `project-fragments.ts`,
+ * `caret-geometry.ts`, `replacement-envelope.ts`, `object-handles.ts`, and
+ * `projector.ts`.
+ */
+
+export type {
+  GeometrySpace,
+  GeometryRect,
+  PageGeometry,
+  BlockGeometry,
+  LineGeometry,
+  RunGeometry,
+  CaretGeometry,
+  HitTestPoint,
+  HitTestResult,
+  AnchorQueryKind,
+  AnchorQuery,
+  EnvelopeConfidence,
+  EnvelopeBundle,
+  Viewport,
+  ViewportListener,
+} from "./geometry-types.ts";
+
+export type {
+  GeometryFacet,
+  CreateGeometryFacetInput,
+} from "./geometry-facet.ts";
+export { createGeometryFacet } from "./geometry-facet.ts";
+export { createInertGeometryFacet } from "./inert-geometry-facet.ts";
+
+export type {
+  ViewportHandle,
+  RootViewportHandle,
+  CreateViewportFromRootInput,
+} from "./viewport.ts";
+export { createViewport, createViewportFromRoot } from "./viewport.ts";
+
+export type { GeometryCacheKey } from "./invalidation.ts";
+export { makeGeometryCacheKey } from "./invalidation.ts";
+
+export type {
+  PageOverlayRect,
+  VisiblePageIndexRange as OverlayVisiblePageIndexRange,
+} from "./overlay-rects.ts";
+export { resolvePageOverlayRectsFromGeometry } from "./overlay-rects.ts";
+
+export {
+  resolveCaretGeometry,
+  resolveSelectionRects,
+} from "./caret-geometry.ts";
+
+export { resolveObjectHandles } from "./object-handles.ts";
+
+export type { ReplacementScope } from "./replacement-envelope.ts";
+export { resolveReplacementEnvelope } from "./replacement-envelope.ts";
+
+export type {
+  GeometryDebugEntry,
+  GeometryDebugCatalog,
+  GeometryDebugSample,
+  BuildGeometryDebugEntryInputs,
+} from "./projector.ts";
+export { buildGeometryDebugEntry } from "./projector.ts";

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

@@ -0,0 +1,43 @@
+/**
+ * Inert geometry facet used during the runtime-loading phase.
+ *
+ * Returns empty or null values for every query; subscribeViewport is a no-op.
+ * Mirrors `createInertLayoutFacet` in `src/runtime/layout/inert-layout-facet.ts`.
+ * The React shell replaces this with the real facet from
+ * `createGeometryFacet(...)` once the runtime is ready, so consumers never
+ * see a "missing" facet — only an empty one.
+ */
+
+import type { GeometryFacet } from "./geometry-facet.ts";
+import type { Viewport } from "./geometry-types.ts";
+
+const INERT_VIEWPORT: Viewport = Object.freeze({
+  scrollLeftPx: 0,
+  scrollTopPx: 0,
+  dpr: 1,
+  pxPerTwip: 0,
+});
+
+export function createInertGeometryFacet(): GeometryFacet {
+  return {
+    hitTest: () => null,
+    getAnchorRects: () => [],
+    getAnchor: () => null,
+    getBlockRects: () => [],
+    getPage: () => null,
+    getBlock: () => null,
+    getLineBoxes: () => [],
+    // Scope-rail proxies removed in refactor/06 Slice 4C rail-seam inversion.
+    // Rail composition lives on `runtime.workflow.*` — the loading boundary
+    // exposes an inert workflow facet with the matching stubs.
+    getCaret: () => null,
+    getSelectionRects: () => [],
+    getReplacementEnvelope: () => null,
+    getObjectHandles: () => [],
+    // Render-kernel passthroughs — inert boundary has no kernel.
+    getRenderFrame: () => null,
+    getRenderZoom: () => null,
+    getViewport: () => INERT_VIEWPORT,
+    subscribeViewport: () => () => undefined,
+  };
+}

package/src/runtime/geometry/invalidation.ts

@@ -0,0 +1,35 @@
+/**
+ * Layer 05 — Geometry invalidation + cache-key helpers.
+ *
+ * Per architecture 05 contract G4, geometry invalidation is derived, not
+ * independent: when layout invalidates a page range, geometry for that range
+ * re-projects on next read. Per performance invariant 3 (CLAUDE.md), cache
+ * keys must be structural or content-specific — never `revisionToken` alone.
+ *
+ * Slice 1 scope: publish the key shape + stub `makeGeometryCacheKey` so
+ * later slices can thread it through the facet. No cache exists yet;
+ * Slice 2+ wires one behind the migrated `hitTest` / `getAnchorRects`
+ * implementations.
+ */
+
+import type { GeometrySpace } from "./geometry-types.ts";
+
+/**
+ * Geometry cache key. Keys are structural: `{ layoutRevision, zoom, space }`.
+ * Never `revisionToken` alone — that bypasses invariant 3 and re-computes
+ * every keystroke.
+ */
+export interface GeometryCacheKey {
+  layoutRevision: number;
+  pxPerTwip: number;
+  space: GeometrySpace;
+}
+
+/**
+ * Produce a stable string key from a `GeometryCacheKey`. Numbers are
+ * stringified via `toString()` (no locale) so cross-environment lookup is
+ * deterministic.
+ */
+export function makeGeometryCacheKey(key: GeometryCacheKey): string {
+  return `${key.layoutRevision}|${key.pxPerTwip}|${key.space}`;
+}

package/src/runtime/geometry/object-handles.ts

@@ -0,0 +1,77 @@
+/**
+ * Layer 05 — Object handle projection.
+ *
+ * `resolveObjectHandles(frame, objectId)` returns the set of
+ * `GeometryRect` handle points a chrome surface paints on a selected
+ * drawing frame / table / image: 8 resize grips (4 corners + 4 edge
+ * midpoints) plus 1 rotate anchor (centered above the top edge).
+ *
+ * Slice-7c substrate: the helper now routes through
+ * `frame.anchorIndex.byObjectId(objectId)` instead of `byBlockId`. The
+ * kernel's Slice-7c substrate delegates `byObjectId` → `byBlockId`
+ * (since object-metadata emission from the layout facet has not
+ * shipped), so behavior is unchanged today — but the consumer now
+ * reads the right seam. When the kernel grows per-object metadata
+ * (Slice 7d follow-up on the layout side), handles upgrade to the
+ * object's own bbox automatically.
+ *
+ * Each handle is a small zero-by-zero point rect (`widthPx === heightPx
+ * === 0`), letting chrome decide the painted grip size via CSS. The
+ * order is stable:
+ *
+ *   index 0 — top-left          index 4 — right
+ *   index 1 — top-center        index 5 — bottom-left
+ *   index 2 — top-right         index 6 — bottom-center
+ *   index 3 — left              index 7 — bottom-right
+ *   index 8 — rotate anchor (20 px above the top-center handle)
+ */
+
+import type { RenderFrame, RenderFrameRect } from "../render/index.ts";
+import type { GeometryRect } from "./geometry-types.ts";
+
+const ROTATE_HANDLE_OFFSET_PX = 20;
+
+export function resolveObjectHandles(
+  frame: RenderFrame | null,
+  objectId: string,
+): readonly GeometryRect[] {
+  if (!frame) return [];
+  const bbox = frame.anchorIndex.byObjectId(objectId);
+  if (!bbox) return [];
+  return buildHandles(bbox);
+}
+
+function buildHandles(bbox: RenderFrameRect): readonly GeometryRect[] {
+  const { leftPx, topPx, widthPx, heightPx } = bbox;
+  const right = leftPx + widthPx;
+  const bottom = topPx + heightPx;
+  const midX = leftPx + widthPx / 2;
+  const midY = topPx + heightPx / 2;
+  // Slice 7b (2026-04-22): object handles derive from the enclosing
+  // block's bbox (via `byBlockId`), not from the object's own bbox.
+  // When the object is a block-level drawing the bbox matches the
+  // object exactly (`within-tolerance`); when it's an inline image
+  // embedded in a paragraph the bbox is the whole paragraph rect
+  // (`heuristic`). Without an object index we can't discriminate the
+  // two cases — tag the coarser `heuristic` so consumers treat all
+  // handles as substrate-grade pending refactor/05 Slice 7 Task 4.
+  const point = (xPx: number, yPx: number): GeometryRect => ({
+    leftPx: xPx,
+    topPx: yPx,
+    widthPx: 0,
+    heightPx: 0,
+    space: "frame",
+    precision: "heuristic",
+  });
+  return [
+    point(leftPx, topPx), // 0 top-left
+    point(midX, topPx), // 1 top-center
+    point(right, topPx), // 2 top-right
+    point(leftPx, midY), // 3 left
+    point(right, midY), // 4 right
+    point(leftPx, bottom), // 5 bottom-left
+    point(midX, bottom), // 6 bottom-center
+    point(right, bottom), // 7 bottom-right
+    point(midX, topPx - ROTATE_HANDLE_OFFSET_PX), // 8 rotate
+  ];
+}

package/src/runtime/geometry/overlay-rects.ts

@@ -0,0 +1,85 @@
+/**
+ * Layer 05 — Overlay rect projection.
+ *
+ * Pure helper for projecting a `GeometryFacet` into the
+ * `PageOverlayRect[]` shape chrome overlays consume. Lives in
+ * `src/runtime/geometry/` (not alongside the `.tsx` overlay component)
+ * so layer-05 tests can consume it without crossing into
+ * `src/ui-tailwind/**`, and because the helper has no React concerns.
+ *
+ * The overlay component (`src/ui-tailwind/chrome-overlay/tw-page-stack-
+ * overlay-layer.tsx`) re-exports this via a direct import so its public
+ * API surface is unchanged.
+ *
+ * **Coordinate-space caveat (known divergence).** The kernel stacks
+ * pages with `PAGE_GAP_PX = 16` (see `src/runtime/render/render-kernel.ts`)
+ * while the DOM stacks them with `interGapPx = 48` (see
+ * `src/ui-tailwind/editor-surface/pm-page-break-decorations.ts`). Using
+ * `page.frame.topPx` directly as an overlay rect is correct only for
+ * page 0; for pages 2..N the overlay rect drifts by ~32 px per boundary.
+ * This helper is the clean substrate; a subsequent Slice-3c reconciles
+ * the two gap constants before any production consumer wires the warm
+ * path. Until then the overlay component keeps its DOM-measurement path
+ * as the default and treats the geometry path as experimental.
+ */
+
+import type { GeometryFacet } from "./geometry-facet.ts";
+
+export interface PageOverlayRect {
+  pageId: string;
+  pageIndex: number;
+  topPx: number;
+  bottomPx: number;
+  heightPx: number;
+}
+
+export interface VisiblePageIndexRange {
+  start: number;
+  end: number;
+}
+
+function normalizeVisibleRange(
+  range: VisiblePageIndexRange | null | undefined,
+  pageCount: number,
+): VisiblePageIndexRange | null {
+  if (!range || pageCount <= 0) return null;
+  const start = Math.max(0, Math.min(range.start, pageCount));
+  const end = Math.max(start, Math.min(range.end, pageCount));
+  if (start >= end) return null;
+  return { start, end };
+}
+
+/**
+ * Build the `PageOverlayRect` list from a `GeometryFacet`. Returns
+ * `null` when the facet does not resolve page 0 (cold-open) so the
+ * caller can fall back to a DOM-measurement path.
+ */
+export function resolvePageOverlayRectsFromGeometry(
+  geometryFacet: GeometryFacet,
+  pageCount: number,
+  visiblePageIndexRange: VisiblePageIndexRange | null | undefined,
+): readonly PageOverlayRect[] | null {
+  if (pageCount <= 0) return [];
+  const first = geometryFacet.getPage(0);
+  if (!first) return null;
+  const normalizedVisible = normalizeVisibleRange(
+    visiblePageIndexRange,
+    pageCount,
+  );
+  const rects: PageOverlayRect[] = [];
+  for (let i = 0; i < pageCount; i += 1) {
+    if (normalizedVisible) {
+      if (i < normalizedVisible.start || i >= normalizedVisible.end) continue;
+    }
+    const page = geometryFacet.getPage(i);
+    if (!page) continue;
+    rects.push({
+      pageId: page.pageId,
+      pageIndex: page.pageIndex,
+      topPx: page.frame.topPx,
+      bottomPx: page.frame.topPx + page.frame.heightPx,
+      heightPx: page.frame.heightPx,
+    });
+  }
+  return rects;
+}

package/src/runtime/geometry/project-anchors.ts

@@ -0,0 +1,100 @@
+/**
+ * Layer 05 — Anchor rect projection.
+ *
+ * Pure projection of a `RenderAnchorQuery` against a frame's
+ * `anchorIndex` into a rect list. Dispatches on query kind: runtime-offset,
+ * block-id, fragment-id, scope-id, comment-id, revision-id, page-index.
+ *
+ * Slice 2a moves this implementation here from
+ * `src/runtime/layout/public-facet.ts`. Layout facet's deprecated
+ * `getAnchorRects` delegates through this module — behavior byte-identical.
+ * Slice 6 deletes the layout-facet wrapper.
+ *
+ * Contract (architecture 05 G5): rects returned here are in the kernel's
+ * frame-local pixel space. Consumers that need twip or overlay coordinates
+ * convert via `chrome-overlay-projector.ts` or the caret/envelope helpers
+ * added in Slices 4–5.
+ */
+
+import type {
+  RenderAnchorQuery,
+  RenderFrame,
+  RenderFrameRect,
+} from "../render/index.ts";
+import { emitLayoutGuardWarning } from "../layout/public-facet.ts";
+
+export function resolveAnchorRects(
+  frame: RenderFrame | null,
+  query: RenderAnchorQuery,
+): readonly RenderFrameRect[] {
+  if (!frame) {
+    emitLayoutGuardWarning("resolveAnchorRects", {
+      queryKind: query.kind,
+      reason: "no-frame",
+    });
+    return [];
+  }
+  switch (query.kind) {
+    case "runtime-offset": {
+      const offset =
+        typeof query.value === "number" ? query.value : Number(query.value);
+      if (!Number.isFinite(offset)) {
+        emitLayoutGuardWarning("resolveAnchorRects", {
+          queryKind: query.kind,
+          reason: "non-finite-offset",
+          value: query.value,
+        });
+        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)) {
+        emitLayoutGuardWarning("resolveAnchorRects", {
+          queryKind: query.kind,
+          reason: "non-finite-page-index",
+          value: query.value,
+        });
+        return [];
+      }
+      const rect = frame.anchorIndex.byPageIndex(pageIndex);
+      return rect ? [rect] : [];
+    }
+    case "scope-id": {
+      return frame.anchorIndex.byScopeId(String(query.value));
+    }
+    case "comment-id": {
+      const rect = frame.anchorIndex.byCommentId(String(query.value));
+      return rect ? [rect] : [];
+    }
+    case "revision-id": {
+      const rect = frame.anchorIndex.byRevisionId(String(query.value));
+      return rect ? [rect] : [];
+    }
+    default: {
+      const exhaustive: never = query.kind;
+      void exhaustive;
+      emitLayoutGuardWarning("resolveAnchorRects", {
+        queryKind: "unknown",
+        reason: "exhaustive-default",
+      });
+      return [];
+    }
+  }
+}
+
+// collectScopeRailSegmentsForQuery moved to
+// `src/runtime/workflow/scope-rail-composer.ts` (L06 canonical home).
+// Parked here by refactor/05 Slice 2b as a transitional home; returned
+// to L06 ownership as part of the post-closure coord-doc §4 follow-up.