@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/layout/page-graph.ts

@@ -27,180 +27,52 @@ import type {
 import type { ResolvedDocumentSection } from "../document-layout.ts";
 
 // ---------------------------------------------------------------------------
-// Enriched graph types
+// Types — all pure data shapes relocated to `src/model/layout/`
+// per `docs/plans/cross-layer-coord-04.md §1.12`.
+//
+//   Pass 1 (2026-04-22): pure page-region / fragment / line-box / note /
+//     anchor types moved to `page-graph-types.ts`.
+//   Pass 2 (2026-04-22): `RuntimePageGraph`, `RuntimePageNode`, and
+//     `BuildPageGraphInput` moved to `runtime-page-graph-types.ts`
+//     (after `ResolvedPageStories` + `ResolvedDocumentSection` +
+//     `PageLayoutSnapshot` + `DocumentPageSnapshot` were also
+//     relocated to the model tree). This cuts Layer 01's
+//     `CacheEnvelope → RuntimePageGraph → runtime/**` transit.
+//
+// Re-exported here so every existing consumer import of these types
+// from this file continues working unchanged. Graph construction
+// functions (`buildPageGraph`, `spliceGraph`) and the `graphRevision`
+// counter stay in this file — only the type shapes moved.
 // ---------------------------------------------------------------------------
 
-export interface RuntimePageGraph {
-  /** Monotonically increasing revision stamp. */
-  revision: number;
-  /** Ordered page nodes. */
-  pages: RuntimePageNode[];
-  /** Flat list of every block fragment produced during pagination. */
-  fragments: RuntimeBlockFragment[];
-  /** Per-offset anchor index for O(log n) lookup. */
-  anchors: RuntimePageAnchor[];
-  /** Section metadata. */
-  sections: ResolvedDocumentSection[];
-  /** Total non-blank page count. */
-  contentPageCount: number;
-}
-
-export interface RuntimePageNode {
-  pageId: string;
-  pageIndex: number;
-  sectionIndex: number;
-  pageInSection: number;
-  startOffset: number;
-  endOffset: number;
-  layout: PageLayoutSnapshot;
-  stories: ResolvedPageStories;
-  /** Sub-regions on the page. */
-  regions: RuntimePageRegions;
-  /** Line boxes rendered in the body region. */
-  lineBoxes: RuntimeLineBox[];
-  /** Footnote allocations reserved at the bottom of the page. */
-  noteAllocations: RuntimeNoteAllocation[];
-  /** Whether this page is a blank filler (from even/odd page breaks). */
-  isBlankFiller: boolean;
-}
-
-export interface RuntimePageRegions {
-  body: RuntimePageRegion;
-  header?: RuntimePageRegion;
-  footer?: RuntimePageRegion;
-  /**
-   * For multi-column bodies, `body.columns` is populated.  For single-column
-   * pages, the top-level body is used and `columns` is undefined.
-   */
-  columns?: RuntimePageRegion[];
-  /**
-   * P4 — footnote regions reserved at the bottom of the page (above
-   * the footer band) when `noteAllocations` reserved space for one or
-   * more footnote bodies.  Empty until the page-graph builder
-   * populates them, which lands alongside the P8 per-page region
-   * rendering work.  The shape exists now so consumers
-   * (`getStoryRegionsOnPage` / `getLineBoxesForRegion("footnote-area")`)
-   * have a stable seam to read from when the builder catches up —
-   * pre-P8 reads return `[]` because no entries are populated.
-   */
-  footnotes?: RuntimePageRegion[];
-}
-
-export interface RuntimePageRegion {
-  kind: "body" | "header" | "footer" | "column" | "footnote-area";
-  /** Twips offset from page top (header) or similar region-specific origin. */
-  originTwips: number;
-  /** Width in twips. */
-  widthTwips: number;
-  /** Height in twips. */
-  heightTwips: number;
-  /** IDs of block fragments rendered in this region, in order. */
-  fragmentIds: string[];
-}
-
-export interface RuntimeBlockFragment {
-  fragmentId: string;
-  /** Canonical block id the fragment slices. */
-  blockId: string;
-  /** Page this fragment lives on. */
-  pageId: string;
-  /** Zero-based order within the page region. */
-  orderInRegion: number;
-  /** Region id the fragment sits in (matches RuntimePageRegion.kind). */
-  regionKind: RuntimePageRegion["kind"];
-  /** Inclusive from / exclusive to offsets within the main story. */
-  from: number;
-  to: number;
-  /** Height consumed on this page (twips). */
-  heightTwips: number;
-  /**
-   * Fragment classification.
-   * - `"whole"` (default): the fragment represents the entire block; no slicing.
-   * - `"paragraph-slice"`: one of several fragments produced by intra-paragraph
-   *   line-box splitting. `paragraphLineRange` identifies which lines this
-   *   slice renders.
-   * - `"table-slice"`: one of several fragments produced by row-boundary table
-   *   splitting (emitted by the table-fidelity workstream).
-   *   `tableRowRange` identifies which canonical rows this slice renders.
-   * Consumers that predate multi-fragment blocks may treat an absent `kind`
-   * as `"whole"`.
-   */
-  kind?: "whole" | "paragraph-slice" | "table-slice";
-  /**
-   * For `kind === "paragraph-slice"`, the inclusive-exclusive line-box index
-   * range rendered by this slice plus the total line count for the source
-   * paragraph. `from`/`to` still span the full paragraph offset range on
-   * every slice — only the visible lines differ.
-   */
-  paragraphLineRange?: {
-    from: number;
-    to: number;
-    totalLines: number;
-  };
-  /**
-   * For `kind === "table-slice"`, the inclusive-exclusive row-index range
-   * rendered by this slice. Repeated header rows (when the table has
-   * `isHeader` rows and `continuation` pages) are implied by the owning
-   * table's canonical row list — consumers prepend header rows for slices
-   * whose `from > 0`.
-   */
-  tableRowRange?: {
-    from: number;
-    to: number;
-    totalRows: number;
-  };
-  /**
-   * Slice 5 — opaque style-chain ref derived from the block's `styleId`.
-   * Used by `analyzeStylesChange` to bound invalidation to the first page
-   * that carries a fragment referencing a dirty style.
-   */
-  resolvedStyleChainRef?: string;
-  /**
-   * Slice 5 — numbering instance id copied from the block's `numbering`
-   * field. Used by `analyzeNumberingChange` to bound invalidation to the
-   * first page that carries a fragment from the affected list instance.
-   */
-  numberingInstanceId?: string;
-}
+export type {
+  RuntimePageRegions,
+  RuntimePageRegion,
+  RuntimeBlockFragment,
+  RuntimeLineBox,
+  RuntimeNoteAllocation,
+  RuntimePageAnchor,
+} from "../../model/layout/page-graph-types.ts";
+
+export type {
+  RuntimePageGraph,
+  RuntimePageNode,
+  BuildPageGraphInput,
+} from "../../model/layout/runtime-page-graph-types.ts";
 
-export interface RuntimeLineBox {
-  /** Fragment this line belongs to. */
-  fragmentId: string;
-  /** Zero-based line index inside the fragment. */
-  lineIndex: number;
-  /** Baseline twips from the region's origin. */
-  baselineTwips: number;
-  /** Line height twips. */
-  heightTwips: number;
-  /** Approximate inline width consumed on this line. */
-  widthTwips: number;
-}
-
-export interface RuntimeNoteAllocation {
-  noteKind: "footnote" | "endnote";
-  noteId: string;
-  /** Twips reserved at the bottom of the page for this note's content. */
-  reservedHeightTwips: number;
-  /**
-   * P8 — fragment ID of this note's body.  The corresponding
-   * `RuntimeBlockFragment` lives in `RuntimePageGraph.fragments` with
-   * `regionKind: "footnote-area"`.  Undefined when the engine hasn't
-   * yet emitted a fragment for the allocation (back-compat for pre-P8
-   * callers).
-   */
-  fragmentId?: string;
-}
-
-export interface RuntimePageAnchor {
-  /** Story target the anchor is for.  Main story is the common case. */
-  storyKey: string;
-  /** Offset the anchor represents. */
-  offset: number;
-  /** Page id resolved for this offset. */
-  pageId: string;
-  /** Fragment id resolved for this offset, if available. */
-  fragmentId?: string;
-}
+import type {
+  RuntimeBlockFragment,
+  RuntimeLineBox,
+  RuntimeNoteAllocation,
+  RuntimePageAnchor,
+  RuntimePageRegion,
+  RuntimePageRegions,
+} from "../../model/layout/page-graph-types.ts";
+import type {
+  RuntimePageGraph,
+  RuntimePageNode,
+  BuildPageGraphInput,
+} from "../../model/layout/runtime-page-graph-types.ts";
 
 // ---------------------------------------------------------------------------
 // Graph construction
@@ -208,36 +80,6 @@ export interface RuntimePageAnchor {
 
 let graphRevision = 0;
 
-export interface BuildPageGraphInput {
-  pages: readonly DocumentPageSnapshot[];
-  sections: readonly ResolvedDocumentSection[];
-  stories: readonly ResolvedPageStories[];
-  /** Optional block fragments pre-computed by pagination; when omitted the
-   *  graph produces one fragment per page spanning its entire offset range. */
-  fragments?: readonly RuntimeBlockFragment[];
-  /**
-   * Optional block fragments keyed by pageIndex with the `pageId` omitted.
-   * `buildPageGraph` fills in the pageId using the graph's fresh revision
-   * stamp. Use this when the caller wants to emit per-block fragments but
-   * cannot know the pageId in advance.
-   */
-  fragmentsByPageIndex?: ReadonlyMap<
-    number,
-    ReadonlyArray<Omit<RuntimeBlockFragment, "pageId">>
-  >;
-  /** Optional per-page line boxes. */
-  lineBoxes?: ReadonlyMap<string, RuntimeLineBox[]>;
-  /** Optional per-page note allocations keyed by graph-assigned pageId. */
-  noteAllocations?: ReadonlyMap<string, RuntimeNoteAllocation[]>;
-  /**
-   * P8 — per-page note allocations keyed by pageIndex (0-based).
-   * Parallel to `fragmentsByPageIndex`; `buildPageGraph` uses the index to
-   * look up allocations without requiring callers to know the graph-internal
-   * `page-${revision}-${index}` pageId in advance.
-   */
-  noteAllocationsByPageIndex?: ReadonlyMap<number, RuntimeNoteAllocation[]>;
-}
-
 export function buildPageGraph(input: BuildPageGraphInput): RuntimePageGraph;
 export function buildPageGraph(
   pages: readonly DocumentPageSnapshot[],
@@ -284,15 +126,13 @@ export function buildPageGraph(
     const pageFragments = aggregatedFragments.filter((f) => f.pageId === pageId);
     // Split fragments into body-region ones (for the body fragmentIds list)
     // and footnote-area ones (handled by buildRegions via noteAllocations).
-    const bodyPageFragments = pageFragments.filter(
+    let bodyPageFragments = pageFragments.filter(
       (f) => f.regionKind !== "footnote-area",
     );
-    const fragmentIds = bodyPageFragments.map((f) => f.fragmentId);
 
     // If no body fragments were supplied, synthesize a coarse body fragment so
     // the graph is still internally consistent.
-    let bodyFragmentIds = fragmentIds;
-    if (fragmentIds.length === 0 && page.endOffset > page.startOffset) {
+    if (bodyPageFragments.length === 0 && page.endOffset > page.startOffset) {
       const coarse: RuntimeBlockFragment = {
         fragmentId: `${pageId}-body-0`,
         blockId: "synthetic",
@@ -304,8 +144,9 @@ export function buildPageGraph(
         heightTwips: 0,
       };
       aggregatedFragments.push(coarse);
-      bodyFragmentIds = [coarse.fragmentId];
+      bodyPageFragments = [coarse];
     }
+    const bodyFragmentIds = bodyPageFragments.map((f) => f.fragmentId);
 
     // Resolve per-page note allocations: prefer noteAllocationsByPageIndex
     // (index-based, suitable when the caller doesn't know the graph-internal
@@ -325,7 +166,7 @@ export function buildPageGraph(
       endOffset: page.endOffset,
       layout: page.layout,
       stories,
-      regions: buildRegions(page.layout, bodyFragmentIds, stories, pageNoteAllocations),
+      regions: buildRegions(page.layout, bodyPageFragments, stories, pageNoteAllocations),
       lineBoxes: input.lineBoxes?.get(pageId) ?? [],
       noteAllocations: pageNoteAllocations,
       isBlankFiller: page.pageInSection === -1,
@@ -352,10 +193,11 @@ export function buildPageGraph(
 
 function buildRegions(
   layout: PageLayoutSnapshot,
-  bodyFragmentIds: readonly string[],
+  bodyFragments: readonly RuntimeBlockFragment[],
   stories: ResolvedPageStories,
   noteAllocations: readonly RuntimeNoteAllocation[] = [],
 ): RuntimePageRegions {
+  const bodyFragmentIds = bodyFragments.map((f) => f.fragmentId);
   // Gutter (w:gutter / pgMar @gutter) reduces usable body width on the bound
   // edge. Parity fix with `src/runtime/page-layout-estimation.ts:153`, which
   // already subtracts `layout.gutter`; prior to this edit the graph path
@@ -428,6 +270,17 @@ function buildRegions(
       1,
       Math.floor((bodyWidth - gap * (layout.columns - 1)) / layout.columns),
     );
+    // Refactor/04 Slice 4 — partition body fragments into per-column
+    // fragment-id lists. Fragments without `columnIndex` (e.g. blocks
+    // from a pre-Slice-4 call path, or single-column pages rendered on a
+    // multi-column layout revision) fall through to column 0 so the
+    // union of `columns[*].fragmentIds` still covers every body fragment.
+    const perColumnIds: string[][] = Array.from({ length: layout.columns }, () => []);
+    for (const frag of bodyFragments) {
+      const raw = frag.columnIndex;
+      const idx = raw !== undefined && raw >= 0 && raw < layout.columns ? raw : 0;
+      perColumnIds[idx]!.push(frag.fragmentId);
+    }
     const columns: RuntimePageRegion[] = [];
     for (let i = 0; i < layout.columns; i += 1) {
       columns.push({
@@ -435,7 +288,7 @@ function buildRegions(
         originTwips: layout.marginTop,
         widthTwips: perColumnWidth,
         heightTwips: Math.max(0, bodyHeight),
-        fragmentIds: [],
+        fragmentIds: perColumnIds[i]!,
       });
     }
     regions.columns = columns;

package/src/runtime/layout/page-story-resolver.ts

@@ -16,23 +16,18 @@ import type {
   EditorStoryTarget,
   PageLayoutSnapshot,
 } from "../../api/public-types";
+import type { ResolvedPageStories } from "../../model/layout/resolved-layout-types.ts";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-export interface ResolvedPageStories {
-  /** Header story target for this page, if any. */
-  header?: EditorStoryTarget;
-  /** Footer story target for this page, if any. */
-  footer?: EditorStoryTarget;
-  /** Whether this is a "first page" in its section (title page behavior). */
-  isFirstPage: boolean;
-  /** Whether this is an even-numbered page (1-indexed for display). */
-  isEvenPage: boolean;
-  /** The effective page number for display (accounting for page numbering settings). */
-  displayPageNumber: number;
-}
+/**
+ * Pass 2 (2026-04-22) — relocated to
+ * `src/model/layout/resolved-layout-types.ts`. Re-exported here so
+ * existing consumers of `ResolvedPageStories` keep working unchanged.
+ */
+export type { ResolvedPageStories } from "../../model/layout/resolved-layout-types.ts";
 
 // ---------------------------------------------------------------------------
 // Resolver