@beyondwork/docx-react-component 1.0.103 → 1.0.105

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

@@ -24,7 +24,10 @@
  */
 
 import type { EditorStoryTarget } from "../../api/public-types";
-import type { PublicPageRegion } from "../layout/public-facet.ts";
+import type {
+  PublicMeasurementFidelity,
+  PublicPageRegion,
+} from "../layout/public-facet.ts";
 
 // ---------------------------------------------------------------------------
 // G5 · Coordinate space tags
@@ -75,6 +78,11 @@ export type GeometrySpace = "twips" | "frame" | "overlay";
  */
 export type GeometryPrecision = "exact" | "within-tolerance" | "heuristic";
 
+export type GeometryRehydrationStatus =
+  | "realized"
+  | "requires-rehydration"
+  | "unavailable";
+
 // ---------------------------------------------------------------------------
 // Core rect shape
 // ---------------------------------------------------------------------------
@@ -98,6 +106,206 @@ export interface GeometryRect {
   precision?: GeometryPrecision;
 }
 
+// ---------------------------------------------------------------------------
+// PE2 geometry index (Slice 1 · page-slice projection substrate)
+// ---------------------------------------------------------------------------
+
+export interface GeometryPrecisionCounts {
+  exact: number;
+  "within-tolerance": number;
+  heuristic: number;
+}
+
+export interface GeometryIndexCoverage {
+  status: GeometryRehydrationStatus;
+  pageCount: number;
+  regionCount: number;
+  sliceCount: number;
+  lineCount: number;
+  anchorCount: number;
+  hitTargetCount: number;
+  semanticEntryCount: number;
+  replacementEnvelopeCount: number;
+  objectHandleCount: number;
+  precision: GeometryPrecisionCounts;
+}
+
+export type GeometrySourceIdentityJoinKind = "direct" | "block-scoped";
+
+/**
+ * Stable canonical identity joined onto projected geometry when the current
+ * substrate can prove the correspondence without consulting renderer state.
+ *
+ * `joinKind: "direct"` means the geometry node maps to the named canonical
+ * table/row/cell. `joinKind: "block-scoped"` means the geometry rect still
+ * belongs to the enclosing rendered block/line; object fields identify the
+ * canonical object carried by that block, not a true object bbox.
+ */
+export interface GeometrySourceIdentity {
+  storyKey: string;
+  blockPath?: string;
+  tableKey?: string;
+  rowKey?: string;
+  cellKey?: string;
+  scopeKey?: string;
+  scopeId?: string;
+  objectKey?: string;
+  inlinePath?: string;
+  objectKind?: string;
+  editPosture?: string;
+  joinKind: GeometrySourceIdentityJoinKind;
+}
+
+export interface GeometryIndex {
+  /**
+   * Source adapter for this index. PE2's target input is L04 page slices; the
+   * current substrate projects the render frame because it is the runtime's
+   * already materialized page-slice view.
+   */
+  source: "render-frame-adapter";
+  revision: number;
+  measurementFidelity: PublicMeasurementFidelity;
+  activeStory: EditorStoryTarget;
+  pages: readonly GeometryIndexPage[];
+  regions: readonly GeometryIndexRegion[];
+  slices: readonly GeometryIndexSlice[];
+  lines: readonly GeometryIndexLine[];
+  anchors: readonly AnchorGeometry[];
+  hitTargets: readonly GeometryHitTarget[];
+  semanticEntries: readonly SemanticDisplayEntry[];
+  replacementEnvelopes: readonly GeometryReplacementEnvelopeEntry[];
+  objectHandles: readonly GeometryObjectHandleEntry[];
+  coverage: GeometryIndexCoverage;
+}
+
+export interface GeometryIndexPage {
+  pageId: string;
+  pageIndex: number;
+  rect: GeometryRect;
+  regionIds: readonly string[];
+}
+
+export interface GeometryIndexRegion {
+  regionId: string;
+  pageId: string;
+  pageIndex: number;
+  kind: PublicPageRegion["kind"];
+  ordinal: number;
+  rect: GeometryRect;
+  sliceIds: readonly string[];
+}
+
+export interface GeometryIndexSlice {
+  sliceId: string;
+  pageId: string;
+  pageIndex: number;
+  regionId: string;
+  regionKind: PublicPageRegion["kind"];
+  blockId: string;
+  fragmentId: string;
+  kind: "paragraph" | "table" | "opaque" | "image-float" | "synthetic";
+  rect: GeometryRect;
+  lineIds: readonly string[];
+  sourceIdentity?: GeometrySourceIdentity;
+}
+
+export interface GeometryIndexLine {
+  lineId: string;
+  pageId: string;
+  pageIndex: number;
+  regionId: string;
+  regionKind: PublicPageRegion["kind"];
+  blockId: string;
+  fragmentId: string;
+  lineIndex: number;
+  rect: GeometryRect;
+  /** Baseline offset from the line rect's top, in frame pixels. */
+  baseline?: number;
+  baselinePrecision?: GeometryPrecision;
+  anchorIds: readonly string[];
+}
+
+export interface AnchorGeometry {
+  anchorId: string;
+  pageId: string;
+  pageIndex: number;
+  regionId: string;
+  regionKind: PublicPageRegion["kind"];
+  blockId?: string;
+  fragmentId?: string;
+  lineId?: string;
+  runtimeOffset?: number;
+  rect: GeometryRect;
+  precision: GeometryPrecision;
+  sourceIdentity?: GeometrySourceIdentity;
+}
+
+export interface GeometryHitTarget {
+  targetId: string;
+  pageId: string;
+  pageIndex: number;
+  regionId: string;
+  regionKind: PublicPageRegion["kind"];
+  blockId: string;
+  fragmentId: string;
+  lineIndex: number;
+  rect: GeometryRect;
+  precision: GeometryPrecision;
+}
+
+export type SemanticDisplayEntryKind =
+  | "text-line"
+  | "numbering-marker"
+  | "table-frame"
+  | "table-row"
+  | "table-cell"
+  | "toc-leader"
+  | "toc-page-label"
+  | "field-result"
+  | "inline-object"
+  | "floating-object"
+  | "placeholder"
+  | "background"
+  | "border"
+  | "debug-classification";
+
+export interface SemanticDisplayEntry {
+  entryId: string;
+  kind: SemanticDisplayEntryKind;
+  pageId: string;
+  pageIndex: number;
+  regionId?: string;
+  regionKind?: PublicPageRegion["kind"];
+  sliceId?: string;
+  lineId?: string;
+  blockId?: string;
+  fragmentId?: string;
+  rowIndex?: number;
+  columnIndex?: number;
+  rect: GeometryRect;
+  status: GeometryRehydrationStatus;
+  precision: GeometryPrecision;
+  sourceIdentity?: GeometrySourceIdentity;
+}
+
+export interface GeometryReplacementEnvelopeEntry {
+  scopeId: string;
+  pageIds?: readonly string[];
+  rects: readonly GeometryRect[];
+  status: GeometryRehydrationStatus;
+  precision: GeometryPrecision;
+  sourceIdentity?: GeometrySourceIdentity;
+}
+
+export interface GeometryObjectHandleEntry {
+  objectId: string;
+  pageIds?: readonly string[];
+  rects: readonly GeometryRect[];
+  status: GeometryRehydrationStatus;
+  precision: GeometryPrecision;
+  sourceIdentity?: GeometrySourceIdentity;
+}
+
 // ---------------------------------------------------------------------------
 // Per-granularity geometry nodes (read models; Slice 2+ populates them)
 // ---------------------------------------------------------------------------
@@ -200,6 +408,14 @@ export interface AnchorQuery {
 
 export type EnvelopeConfidence = "exact" | "medium" | "detached";
 
+export interface EnvelopeContinuationState {
+  pageIds: readonly string[];
+  pageCount: number;
+  crossesPageBoundary: boolean;
+  continuedFromPreviousPage: boolean;
+  continuesToNextPage: boolean;
+}
+
 export interface EnvelopeBundle {
   /**
    * Rect coverage for the resolved scope. Slice-5 substrate produces
@@ -211,6 +427,10 @@ export interface EnvelopeBundle {
    * walk if the count is lower than expected.
    */
   scopeRects: readonly GeometryRect[];
+  /** Page ids whose projected page frames intersect `scopeRects`. */
+  pageIds: readonly string[];
+  /** Continuation metadata for multi-page / partial-page replacement scopes. */
+  continuation: EnvelopeContinuationState;
   /** Anchor point consumers attach chrome to (top-left of first rect). */
   attachPoint: { xPx: number; yPx: number; space: GeometrySpace };
   /**
@@ -227,6 +447,12 @@ export interface EnvelopeBundle {
    * layer-05 closure.
    */
   linesCrossed: number;
+  /**
+   * Realized for live range scopes. Detached scopes are projected from a
+   * last-known range and are marked `requires-rehydration` so callers do not
+   * mistake the geometry for current document truth.
+   */
+  rehydrationStatus: GeometryRehydrationStatus;
   /**
    * Precision tag. `"exact"` when the envelope collapsed to a caret rect
    * (single anchor position); `"within-tolerance"` when the envelope is

package/src/runtime/geometry/index.ts

@@ -13,7 +13,24 @@
 
 export type {
   GeometrySpace,
+  GeometryPrecision,
   GeometryRect,
+  GeometryRehydrationStatus,
+  GeometryPrecisionCounts,
+  GeometrySourceIdentityJoinKind,
+  GeometrySourceIdentity,
+  GeometryIndexCoverage,
+  GeometryIndex,
+  GeometryIndexPage,
+  GeometryIndexRegion,
+  GeometryIndexSlice,
+  GeometryIndexLine,
+  AnchorGeometry,
+  GeometryHitTarget,
+  SemanticDisplayEntryKind,
+  SemanticDisplayEntry,
+  GeometryReplacementEnvelopeEntry,
+  GeometryObjectHandleEntry,
   PageGeometry,
   BlockGeometry,
   LineGeometry,
@@ -24,11 +41,20 @@ export type {
   AnchorQueryKind,
   AnchorQuery,
   EnvelopeConfidence,
+  EnvelopeContinuationState,
   EnvelopeBundle,
   Viewport,
   ViewportListener,
 } from "./geometry-types.ts";
 
+export {
+  createUnavailableGeometryCoverage,
+  projectGeometryIndexFromFrame,
+  summarizeGeometryCoverageFromFrame,
+} from "./geometry-index.ts";
+
+export type { GeometryIndexProjectionOptions } from "./geometry-index.ts";
+
 export type {
   GeometryFacet,
   CreateGeometryFacetInput,

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

@@ -10,6 +10,7 @@
 
 import type { GeometryFacet } from "./geometry-facet.ts";
 import type { Viewport } from "./geometry-types.ts";
+import { createUnavailableGeometryCoverage } from "./geometry-index.ts";
 
 const INERT_VIEWPORT: Viewport = Object.freeze({
   scrollLeftPx: 0,
@@ -20,6 +21,8 @@ const INERT_VIEWPORT: Viewport = Object.freeze({
 
 export function createInertGeometryFacet(): GeometryFacet {
   return {
+    getGeometryIndex: () => null,
+    getGeometryCoverage: () => createUnavailableGeometryCoverage(),
     hitTest: () => null,
     getAnchorRects: () => [],
     getAnchor: () => null,

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

@@ -27,7 +27,7 @@
  */
 
 import type { RenderFrame, RenderFrameRect } from "../render/index.ts";
-import type { GeometryRect } from "./geometry-types.ts";
+import type { GeometryPrecision, GeometryRect } from "./geometry-types.ts";
 
 const ROTATE_HANDLE_OFFSET_PX = 20;
 
@@ -38,10 +38,13 @@ export function resolveObjectHandles(
   if (!frame) return [];
   const bbox = frame.anchorIndex.byObjectId(objectId);
   if (!bbox) return [];
-  return buildHandles(bbox);
+  return buildObjectHandleRectsFromRect(bbox);
 }
 
-function buildHandles(bbox: RenderFrameRect): readonly GeometryRect[] {
+export function buildObjectHandleRectsFromRect(
+  bbox: RenderFrameRect,
+  precision: GeometryPrecision = "heuristic",
+): readonly GeometryRect[] {
   const { leftPx, topPx, widthPx, heightPx } = bbox;
   const right = leftPx + widthPx;
   const bottom = topPx + heightPx;
@@ -61,7 +64,7 @@ function buildHandles(bbox: RenderFrameRect): readonly GeometryRect[] {
     widthPx: 0,
     heightPx: 0,
     space: "frame",
-    precision: "heuristic",
+    precision,
   });
   return [
     point(leftPx, topPx), // 0 top-left

package/src/runtime/geometry/replacement-envelope.ts

@@ -75,7 +75,7 @@ export function resolveReplacementEnvelope(
     if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
     const rects = resolveSelectionRects(frame, { from, to, story });
     if (rects.length === 0) return null;
-    return buildBundle(rects, "exact");
+    return buildBundle(frame, rects, "exact");
   }
 
   // Detached: project the last-known range and tag confidence as such.
@@ -83,10 +83,11 @@ export function resolveReplacementEnvelope(
   if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
   const rects = resolveSelectionRects(frame, { from, to, story });
   if (rects.length === 0) return null;
-  return buildBundle(rects, "detached");
+  return buildBundle(frame, rects, "detached");
 }
 
 function buildBundle(
+  frame: RenderFrame,
   rects: readonly GeometryRect[],
   confidence: EnvelopeBundle["confidence"],
 ): EnvelopeBundle {
@@ -104,8 +105,17 @@ function buildBundle(
   const rectPrecision = coarsestRectPrecision(rects);
   const envelopePrecision: EnvelopeBundle["precision"] =
     confidence === "detached" ? "heuristic" : rectPrecision;
+  const pageIds = resolveIntersectingPageIds(frame, rects);
   return {
     scopeRects: rects,
+    pageIds,
+    continuation: {
+      pageIds,
+      pageCount: pageIds.length,
+      crossesPageBoundary: pageIds.length > 1,
+      continuedFromPreviousPage: false,
+      continuesToNextPage: false,
+    },
     attachPoint: {
       xPx: first.leftPx,
       yPx: first.topPx,
@@ -113,10 +123,39 @@ function buildBundle(
     },
     confidence,
     linesCrossed: rects.length,
+    rehydrationStatus:
+      confidence === "detached" ? "requires-rehydration" : "realized",
     precision: envelopePrecision,
   };
 }
 
+function resolveIntersectingPageIds(
+  frame: RenderFrame,
+  rects: readonly GeometryRect[],
+): readonly string[] {
+  if (!Array.isArray(frame.pages)) return [];
+  const ids: string[] = [];
+  for (const page of frame.pages) {
+    if (rects.some((rect) => intersects(rect, page.frame))) {
+      ids.push(page.page.pageId);
+    }
+  }
+  return ids;
+}
+
+function intersects(rect: GeometryRect, page: { leftPx: number; topPx: number; widthPx: number; heightPx: number }): boolean {
+  const rectRight = rect.leftPx + rect.widthPx;
+  const rectBottom = rect.topPx + rect.heightPx;
+  const pageRight = page.leftPx + page.widthPx;
+  const pageBottom = page.topPx + page.heightPx;
+  return (
+    rect.leftPx <= pageRight &&
+    rectRight >= page.leftPx &&
+    rect.topPx <= pageBottom &&
+    rectBottom >= page.topPx
+  );
+}
+
 function coarsestRectPrecision(
   rects: readonly GeometryRect[],
 ): "exact" | "within-tolerance" | "heuristic" {

package/src/runtime/layout/layout-engine-instance.ts

@@ -490,6 +490,7 @@ export function createLayoutEngine(
       fragmentsByPageIndex,
       lineBoxesByPageIndex,
       noteAllocationsByPageIndex: pageStack.noteAllocationsByPageIndex,
+      subParts: document.subParts,
     });
 
     // Field dirtiness diff from previous graph
@@ -669,6 +670,7 @@ export function createLayoutEngine(
       fragmentsByPageIndex: freshFragmentsByPageIndex,
       lineBoxesByPageIndex: freshLineBoxesByPageIndex,
       noteAllocationsByPageIndex: freshResult.noteAllocationsByPageIndex,
+      subParts: document.subParts,
     });
     const freshNodes = freshGraph.pages;
 

package/src/runtime/layout/layout-engine-version.ts

@@ -1031,8 +1031,51 @@
  *   content instead of checking only top-level paragraphs. This honors
  *   `<w:br w:type="page"/>` inside cover-page SDTs such as the CCEP SOW
  *   template, changing page assignment from the v61 cache shape.
+ *
+ *  63 — PE2 geometry-projection substrate (Layer 05). Adds the new
+ *   geometry-index module (`src/runtime/geometry/geometry-index.ts`,
+ *   `geometry-facet.ts`, `caret-geometry.ts`, `replacement-envelope.ts`,
+ *   `inert-geometry-facet.ts`, `geometry-types.ts`, `index.ts`) and
+ *   advances the geometry projections that downstream caches consume.
+ *   Persisted layout caches keyed on the v62 geometry shape must
+ *   re-derive. Shipped via pe2 commits `957069161` + `1f36767d7`.
+ *
+ *  64 — PE2 Slice 2 page-frame graph substrate (Layer 04). `RuntimePageNode`
+ *   built by L04 now carries a twips-only `RuntimePageFrame` payload, explicit
+ *   `rectTwips` on resolved page regions, and typed layout divergence lists.
+ *   Existing `regions` remain the compatibility surface, but cache envelopes
+ *   from v63 invalidate because the page graph payload shape changed.
+ *   Shipped via pe2 commit `24a316af2`.
+ *
+ *  65 — PE2 Slice 2 page-local story instances (Layer 04). `RuntimePageFrame`
+ *   now carries stable header/footer `pageLocalStories` records with story
+ *   keys, variants, relationship ids, measured frame heights, and empty
+ *   field/object ledgers for later Slice 2/4 population. Cache envelopes
+ *   from v64 invalidate because the page-frame payload shape changed again.
+ *   Shipped via pe2 commit `06fe6f692`.
+ *
+ *  66 — PE2 Slice 2 page-local field ledgers (Layer 04). Page graph
+ *   construction now walks canonical header/footer subparts for each
+ *   page-local story instance and records resolved PAGE / NUMPAGES /
+ *   SECTIONPAGES display text in the story's `resolvedFields` ledger.
+ *   Cache envelopes from v65 invalidate because page-frame story payloads
+ *   now carry field-resolution data. Shipped via pe2 commit `a3a42bec9`.
+ *
+ *  67 — PE2 Slice 2 page-local object ledgers (Layer 04). Header/footer
+ *   page-local story instances now record canonical image/drawing/preserve-only
+ *   objects as twips/plain anchored-object ledger rows and emit typed
+ *   unsupported-wrap / preserve-only-placeholder divergences. Cache envelopes
+ *   from v66 invalidate because page-frame story payloads and divergence ids
+ *   can change. Shipped via pe2 commit `7d8bb94ac`.
+ *
+ *  68 — PE2 Slice 3 typed continuation cursors (Layer 04). Paragraph and
+ *   table slice fragments now carry a twips/plain continuation cursor with
+ *   sequence position, line/row range, continuation direction, repeated
+ *   table header rows, and vertical-merge carry metadata. Cache envelopes
+ *   from v67 invalidate because fragment payloads can now include
+ *   continuation state. Shipped via pe2 commit `33fbf45ac`.
  */
-export const LAYOUT_ENGINE_VERSION = 62 as const;
+export const LAYOUT_ENGINE_VERSION = 68 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope