@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/model/canonical-document.ts

@@ -10,6 +10,7 @@ import {
   expectString,
   expectStringAllowEmpty,
   expectUuid,
+  isUuid,
   stableStringify,
 } from "./cds-1.0.0.ts";
 import type {
@@ -57,25 +58,132 @@ const ID_PATTERNS = {
 type StableIdDomain = keyof typeof ID_PATTERNS;
 
 export interface CanonicalDocument {
-  schemaVersion: typeof CDS_SCHEMA_VERSION;
-  docId: UUID;
-  createdAt: ISO8601DateTime;
-  updatedAt: ISO8601DateTime;
-  metadata: DocumentMetadata;
-  styles: StylesCatalog;
-  numbering: NumberingCatalog;
-  media: MediaCatalog;
-  content: DocumentRootNode;
-  review: ReviewStore;
-  preservation: PreservationStore;
-  diagnostics: DiagnosticStore;
-  subParts?: SubPartsCatalog;
+  readonly schemaVersion: typeof CDS_SCHEMA_VERSION;
+  readonly docId: UUID;
+  readonly createdAt: ISO8601DateTime;
+  readonly updatedAt: ISO8601DateTime;
+  readonly metadata: DocumentMetadata;
+  readonly styles: StylesCatalog;
+  readonly numbering: NumberingCatalog;
+  readonly media: MediaCatalog;
+  readonly content: DocumentRootNode;
+  readonly review: ReviewStore;
+  readonly preservation: PreservationStore;
+  readonly diagnostics: DiagnosticStore;
+  readonly subParts?: SubPartsCatalog;
   /** Package-backed field registry for supported field families. */
-  fieldRegistry?: FieldRegistry;
+  readonly fieldRegistry?: FieldRegistry;
   /** Parsed fontTable.xml. Undefined when the package has no fontTable part. */
-  fontTable?: CanonicalFontTable;
+  readonly fontTable?: CanonicalFontTable;
 }
 
+/**
+ * A detachable slice of canonical document content. The inverse of
+ * `DocumentRootNode` in the narrow sense — a fragment is block-level
+ * children that can be spliced into a target range on the main story or
+ * on any secondary story (header, footer, footnote, endnote) without
+ * carrying the enclosing envelope.
+ *
+ * Owned by Layer 02 because it is a shape of canonical content, not a
+ * layout or runtime concern. Consumed by the Layer 08 scope compiler's
+ * structured-replacement path (`paragraph.compileReplacement` with
+ * `proposedContent.kind === "structured"`) and by any future command
+ * that performs block-level splicing. The fragment does not carry its
+ * own catalogs / stores / registries — those are resolved against the
+ * destination document at splice time.
+ *
+ * Structural invariants:
+ * - Every `BlockNode` inside `blocks` is structurally valid in
+ *   isolation (passes `validateDocumentNode` when walked).
+ * - The fragment carries no anchors to the source document; splicing
+ *   is by target range supplied at apply time, not by fragment
+ *   identity.
+ * - Styles / numbering / media referenced by inline children must
+ *   resolve in the destination document; the fragment itself does not
+ *   own catalog entries. A splice that introduces unresolved
+ *   references is a caller error, not a fragment shape violation.
+ */
+export interface CanonicalDocumentFragment {
+  /** Block-level children of the fragment, in document order. */
+  readonly blocks: ReadonlyArray<BlockNode>;
+}
+
+/**
+ * Draft-only mutable view of `CanonicalDocumentFragment`. Same
+ * semantics as {@link Mutable}. Used at fragment-construction sites;
+ * callers widen back to `CanonicalDocumentFragment` at the function
+ * boundary.
+ */
+export type MutableCanonicalDocumentFragment = Mutable<CanonicalDocumentFragment>;
+
+/**
+ * Strip every `readonly` modifier from an interface / type. The sanctioned
+ * "local draft → freeze" escape hatch for constructing a new canonical value:
+ * declare the draft as `Mutable<CanonicalType>`, populate it by in-place
+ * assignment, and return it widened back to the readonly type. Widening is
+ * identity at runtime; TypeScript preserves the immutability contract at the
+ * function boundary.
+ *
+ * Contract D2 (architecture §02) forbids consumers from mutating a
+ * `CanonicalDocument` or any nested canonical value received from elsewhere.
+ * This helper is the ONE acceptable cast for locally-owned drafts:
+ *
+ *   function refreshStyles(doc: CanonicalDocument, fresh: StylesCatalog): CanonicalDocument {
+ *     const draft: MutableCanonicalDocument = { ...doc };
+ *     draft.styles = fresh;
+ *     draft.updatedAt = new Date().toISOString();
+ *     return draft; // widens back to CanonicalDocument
+ *   }
+ *
+ * Never cast a value received as a parameter. Only cast values you just
+ * created via object literal, spread, `structuredClone`, or `createCanonicalDocument`.
+ *
+ * **Shallow only.** `Mutable<T>` strips `readonly` at the top level of `T`;
+ * nested `ReadonlyArray<…>`, `Readonly<…>`, and inner `readonly` modifiers
+ * declared inside referenced types are preserved. For example,
+ * `Mutable<CanonicalDocument>` does NOT make `draft.content.children`
+ * mutable — `content` is `DocumentRootNode`, whose `children` field is
+ * declared as it is in the source type. If you need to mutate nested
+ * structure, build the nested value first (also as a `Mutable<…>` of the
+ * nested type) and assign it onto the draft as a complete replacement.
+ * Deep-readonly propagation across nested catalogs/stores/nodes is a
+ * deferred D1 follow-up (see `docs/plans/refactor/02-canonical-document-deferred.md`).
+ */
+export type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+
+/**
+ * Draft-only mutable view of `CanonicalDocument`. Equivalent to
+ * `Mutable<CanonicalDocument>`; kept as a named alias for discoverability at
+ * the most common call site. See {@link Mutable} for the general pattern and
+ * usage constraints.
+ */
+export type MutableCanonicalDocument = Mutable<CanonicalDocument>;
+
+/**
+ * Named `Mutable*` aliases for the top-level catalogs, stores, and
+ * registries referenced from `CanonicalDocument`. Same semantics as
+ * `Mutable<T>` — present as named exports so a consumer can write
+ * `const catalog: MutableStylesCatalog = { … }` without reaching for the
+ * generic. For deeply-nested shapes (node types, formatting records, table
+ * cells, chart models) use `Mutable<T>` directly.
+ *
+ * These aliases are the foundation layer for the deferred D1 deep-readonly
+ * propagation (see `docs/plans/refactor/02-canonical-document-deferred.md`
+ * § D1). They are type-only additions with zero runtime cost and zero
+ * consumer impact; they only unlock the migration path for later slices.
+ */
+export type MutableDocumentMetadata = Mutable<DocumentMetadata>;
+export type MutableStylesCatalog = Mutable<StylesCatalog>;
+export type MutableNumberingCatalog = Mutable<NumberingCatalog>;
+export type MutableMediaCatalog = Mutable<MediaCatalog>;
+export type MutableDocumentRootNode = Mutable<DocumentRootNode>;
+export type MutableReviewStore = Mutable<ReviewStore>;
+export type MutablePreservationStore = Mutable<PreservationStore>;
+export type MutableDiagnosticStore = Mutable<DiagnosticStore>;
+export type MutableSubPartsCatalog = Mutable<SubPartsCatalog>;
+export type MutableFieldRegistry = Mutable<FieldRegistry>;
+export type MutableCanonicalFontTable = Mutable<CanonicalFontTable>;
+
 
 export interface DocumentMetadata {
   title?: string;
@@ -382,6 +490,34 @@ export interface ThemeFontScheme {
   minorFont?: string;
 }
 
+/**
+ * ECMA-376 §17.18.94 `<w:rFonts>` theme-slot values. The set is a small
+ * closed enumeration; every attribute value outside this list is dropped
+ * at parse (preserving the "canonical reflects modeled state only"
+ * invariant — unknown values would be data the layer cannot round-trip).
+ *
+ * Slot semantics: `majorAscii` = major-font Latin glyph typeface,
+ * `minorEastAsia` = minor-font East-Asian typeface, etc. Word uses
+ * `majorFont` for headings and `minorFont` for body text; the script
+ * suffix picks the typeface within that major/minor family.
+ *
+ * Canonical `ThemeFontScheme` today captures only a single typeface
+ * per major/minor — all script variants of the same major/minor family
+ * resolve to the same concrete font. Extending the scheme with
+ * per-script (latin / ea / cs) typefaces is L02 territory and is
+ * tracked as a follow-up; the run-side field preserves the full
+ * attribute for byte-identical export regardless.
+ */
+export type ThemeFontSlot =
+  | "majorAscii"
+  | "minorAscii"
+  | "majorHAnsi"
+  | "minorHAnsi"
+  | "majorEastAsia"
+  | "minorEastAsia"
+  | "majorBidi"
+  | "minorBidi";
+
 export interface ThemeDefinition {
   name?: string;
   colorScheme?: ThemeColorScheme;
@@ -664,6 +800,24 @@ export interface CanonicalRunFormatting {
   fontFamilyHAnsi?: string;
   fontFamilyEastAsia?: string;
   fontFamilyCs?: string;
+  /**
+   * ECMA-376 §17.3.2.26 theme-slot bindings on `<w:rFonts>`
+   * (`w:asciiTheme`, `w:hAnsiTheme`, `w:eastAsiaTheme`, `w:cstheme`).
+   * When present, the run asks for the typeface named by the
+   * corresponding slot on the document's `theme.fontScheme` — Word
+   * then resolves the concrete font through the theme. Preserved for
+   * round-trip; resolution lives in
+   * `src/runtime/formatting/font-resolution.ts`.
+   *
+   * Concrete names (`fontFamilyAscii`, etc.) take precedence over
+   * theme slots per ECMA-376 §17.3.2.26; when both are present the
+   * concrete name wins. Keep the theme slot on the canonical so the
+   * export path can re-emit it byte-identically.
+   */
+  asciiTheme?: ThemeFontSlot;
+  hAnsiTheme?: ThemeFontSlot;
+  eastAsiaTheme?: ThemeFontSlot;
+  csTheme?: ThemeFontSlot;
   fontSizeHalfPoints?: number;
   fontSizeCsHalfPoints?: number;
   /**
@@ -1930,6 +2084,151 @@ export function createCanonicalDocument(
   return document;
 }
 
+/**
+ * Layer 02 default-envelope factory. Produces a fully-valid
+ * {@link CanonicalDocument} with a single empty paragraph and empty
+ * catalogs/stores. Used by:
+ * - the session layer's default-new-document path (when a host requests
+ *   an editor without supplying source bytes)
+ * - the persisted-snapshot repair path (as the "base" onto which a
+ *   malformed envelope is merged by {@link repairCanonicalDocumentEnvelope})
+ *
+ * The function is pure: no runtime, io, or session imports. Every field
+ * populated here is a structural constant, so the resulting document
+ * passes {@link assertCanonicalDocument} by construction.
+ */
+export function createEmptyCanonicalDocument(params: {
+  docId: UUID;
+  createdAt: ISO8601DateTime;
+  updatedAt?: ISO8601DateTime;
+}): CanonicalDocument {
+  return createCanonicalDocument({
+    docId: params.docId,
+    createdAt: params.createdAt,
+    updatedAt: params.updatedAt ?? params.createdAt,
+    metadata: { customProperties: {} },
+    styles: { paragraphs: {}, characters: {}, tables: {} },
+    numbering: { abstractDefinitions: {}, instances: {} },
+    media: { items: {} },
+    content: {
+      type: "doc",
+      children: [{ type: "paragraph", children: [] }],
+    },
+    review: { comments: {}, revisions: {} },
+    preservation: { opaqueFragments: {}, packageParts: {} },
+    diagnostics: { warnings: [], errors: [] },
+  });
+}
+
+/**
+ * Layer 02 repair-envelope factory. Coerces an unknown value that claims
+ * to be a persisted {@link CanonicalDocument} into a structurally-valid
+ * envelope by merging the value's recognizable fields onto a freshly
+ * constructed empty envelope (see {@link createEmptyCanonicalDocument}).
+ *
+ * The repair preserves optional fields — `subParts`, `fieldRegistry`,
+ * `fontTable` — unmodified when present as objects. The session layer's
+ * previous copy of this function silently dropped `fieldRegistry` and
+ * `fontTable`, which caused a round-trip of (load → persist → reload)
+ * to lose canonical data. Having the function live on the model layer
+ * ensures every repair path recognises every optional field the model
+ * actually owns.
+ *
+ * Inputs that are not plain objects are treated as completely missing,
+ * producing a document with default content. Inputs whose `docId` is
+ * not a valid UUID are given {@link params.fallbackDocId} instead.
+ *
+ * This function is pure and synchronous. It does not throw; the caller
+ * decides whether to pass the output through {@link assertCanonicalDocument}
+ * for strict validation (the session-layer repair path does; the rehydration
+ * path does too, after merging in the live session's canonicalDocument
+ * snapshot). The output is always structurally valid — the final shape is
+ * `createEmptyCanonicalDocument(fallback) ∪ filtered(input)`.
+ */
+export function repairCanonicalDocumentEnvelope(
+  value: unknown,
+  params: {
+    fallbackDocId: UUID;
+    fallbackCreatedAt: ISO8601DateTime;
+    fallbackUpdatedAt?: ISO8601DateTime;
+  },
+): CanonicalDocument {
+  const base = createEmptyCanonicalDocument({
+    docId: params.fallbackDocId,
+    createdAt: params.fallbackCreatedAt,
+    updatedAt: params.fallbackUpdatedAt ?? params.fallbackCreatedAt,
+  });
+  const record = isPlainRecord(value) ? value : {};
+  const metadata = isPlainRecord(record.metadata) ? record.metadata : {};
+  const customProperties = isPlainRecord(metadata.customProperties)
+    ? (Object.fromEntries(
+        Object.entries(metadata.customProperties).filter(
+          ([, entry]) => typeof entry === "string",
+        ),
+      ) as Record<string, string>)
+    : {};
+
+  const envelope: Mutable<CanonicalDocument> = {
+    ...base,
+    schemaVersion: CDS_SCHEMA_VERSION,
+    docId: isUuid(record.docId) ? record.docId : params.fallbackDocId,
+    createdAt:
+      typeof record.createdAt === "string" && record.createdAt.length > 0
+        ? record.createdAt
+        : base.createdAt,
+    updatedAt:
+      typeof record.updatedAt === "string" && record.updatedAt.length > 0
+        ? record.updatedAt
+        : base.updatedAt,
+    metadata: {
+      ...base.metadata,
+      ...metadata,
+      customProperties,
+    } as CanonicalDocument["metadata"],
+    styles:
+      record.styles === undefined
+        ? base.styles
+        : (record.styles as CanonicalDocument["styles"]),
+    numbering:
+      record.numbering === undefined
+        ? base.numbering
+        : (record.numbering as CanonicalDocument["numbering"]),
+    media:
+      record.media === undefined
+        ? base.media
+        : (record.media as CanonicalDocument["media"]),
+    content: isPlainRecord(record.content)
+      ? (record.content as unknown as CanonicalDocument["content"])
+      : base.content,
+    review:
+      record.review === undefined
+        ? base.review
+        : (record.review as CanonicalDocument["review"]),
+    preservation:
+      record.preservation === undefined
+        ? base.preservation
+        : (record.preservation as CanonicalDocument["preservation"]),
+    diagnostics:
+      record.diagnostics === undefined
+        ? base.diagnostics
+        : (record.diagnostics as CanonicalDocument["diagnostics"]),
+  };
+  if (isPlainRecord(record.subParts)) {
+    envelope.subParts = record.subParts as unknown as CanonicalDocument["subParts"];
+  }
+  if (isPlainRecord(record.fieldRegistry)) {
+    envelope.fieldRegistry = record.fieldRegistry as unknown as CanonicalDocument["fieldRegistry"];
+  }
+  if (isPlainRecord(record.fontTable)) {
+    envelope.fontTable = record.fontTable as unknown as CanonicalDocument["fontTable"];
+  }
+  return envelope;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 export function serializeCanonicalDocument(document: CanonicalDocument): string {
   assertCanonicalDocument(document);
   return stableStringify(document);
@@ -3621,3 +3920,40 @@ function expectDomainString(
 
   return stableId;
 }
+
+/**
+ * Content-addressable canonical document id — a pseudo-UUIDv4
+ * derived deterministically from an opaque `documentId` string
+ * via four 32-bit FNV-1a hashes. Stable across load/export
+ * (same `documentId` → same `docId`), zero I/O, no wall clock.
+ *
+ * Lives here (model) rather than `src/core/state/editor-state.ts`
+ * because `CanonicalDocument.docId` is a model concern — the
+ * editor-state layer consumes it, doesn't define it. The legacy
+ * export at `src/core/state/editor-state.ts::createCanonicalDocumentId`
+ * re-exports this function for back-compat.
+ */
+export function createCanonicalDocumentId(documentId: string): string {
+  const hashWord = (seed: string): string => {
+    let hash = 0x811c9dc5;
+    for (const char of seed) {
+      hash ^= char.charCodeAt(0);
+      hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+  };
+
+  const raw =
+    hashWord(`${documentId}:0`) +
+    hashWord(`${documentId}:1`) +
+    hashWord(`${documentId}:2`) +
+    hashWord(`${documentId}:3`);
+
+  return [
+    raw.slice(0, 8),
+    raw.slice(8, 12),
+    `4${raw.slice(13, 16)}`,
+    `8${raw.slice(17, 20)}`,
+    raw.slice(20, 32),
+  ].join("-");
+}

package/src/model/chart-types.ts

@@ -13,7 +13,7 @@
  * references; consumers of Stage 1 models should treat color resolution as
  * "not yet available."
  *
- * See docs/plans/lane-5-charts.md §3 Task 1.1 for the full specification.
+ * See CLAUDE.md (lane status table) §3 Task 1.1 for the full specification.
  */
 
 // ---------------------------------------------------------------------------

package/src/model/layout/index.ts

@@ -0,0 +1,83 @@
+/**
+ * Layer 02 · shared layout types (barrel).
+ *
+ * Neutral home for *data-only* layout types that multiple layers
+ * consume but nobody else should own — `RuntimePageGraph`,
+ * `RuntimeLayoutFacet`, `RuntimeLineBox`, `RuntimeNoteAllocation`,
+ * `RuntimePageAnchor`, etc. Proposed by Layer 04 at `cross-layer-
+ * coord-04.md §2` and accepted by Layer 02 at `cross-layer-coord-02.md §9`.
+ *
+ * # Acceptance rule (what can land in `src/model/layout/**`)
+ *
+ * This directory is inside `src/model/**` and therefore subject to the
+ * same architecture §D2 (quasi-immutability) and §D3 (no upward
+ * imports) contracts as the rest of Layer 02. The import-purity guard
+ * at `scripts/ci-check-model-import-purity.mjs` already scans this
+ * subdirectory recursively — no guard change needed when types land.
+ *
+ * Accepts:
+ *   ✓ Plain data interfaces / type aliases for layout-graph + geometry
+ *     shapes (e.g. `RuntimePageGraph`, `RuntimeLineBox`,
+ *     `RuntimeNoteAllocation`, `RuntimePageAnchor`).
+ *   ✓ Readonly / discriminated-union shapes.
+ *   ✓ `Mutable<T>` draft aliases (same construction-pattern discipline
+ *     as the rest of `src/model/`).
+ *   ✓ Type-level utility aliases and branded-id types that describe a
+ *     layout shape.
+ *
+ * Rejects (these belong elsewhere — typically `src/runtime/layout/`):
+ *   ✗ Classes with methods, or interfaces that describe a stateful
+ *     object.
+ *   ✗ Factory functions or builders (`createPageGraph()`, etc.).
+ *   ✗ Visitors / walkers / transformers that operate on a layout tree.
+ *   ✗ Imports from any forbidden prefix (see guard).
+ *   ✗ Non-trivial top-level statements (module side-effects).
+ *
+ * # Who edits here
+ *
+ * Layer 04 owns the content. Layer 02 owns the boundary (purity guard
+ * + acceptance rule). A type relocation from `src/runtime/layout/**`
+ * into this tree lands as an L04 commit; L02 reviews and, if the
+ * types pass the acceptance rule, the guard scan stays green on the
+ * next CI run. No L02 commit is needed per relocation.
+ *
+ * # Pass 1 — 2026-04-22
+ *
+ * 6 pure data types relocated from `src/runtime/layout/page-graph.ts`
+ * per `docs/plans/cross-layer-coord-04.md §1.12` (L04 purity audit).
+ *
+ * # Pass 2 — 2026-04-22
+ *
+ * `PageLayoutSnapshot`, `EditorStoryTarget`, and `DocumentPageSnapshot`
+ * relocated out of `src/api/public-types.ts`. They are pure data shapes
+ * derived from `CanonicalDocument` inputs; living in the model tree lets
+ * `RuntimePageGraph` (next step) drop its transitive api dependency.
+ * `src/api/public-types.ts` continues to re-export them as a stability
+ * guarantee for external consumers.
+ */
+
+export type {
+  RuntimePageRegions,
+  RuntimePageRegion,
+  RuntimeBlockFragment,
+  RuntimeLineBox,
+  RuntimeNoteAllocation,
+  RuntimePageAnchor,
+} from "./page-graph-types.ts";
+
+export type {
+  PageLayoutSnapshot,
+  EditorStoryTarget,
+  DocumentPageSnapshot,
+} from "./page-layout-snapshot.ts";
+
+export type {
+  ResolvedPageStories,
+  ResolvedDocumentSection,
+} from "./resolved-layout-types.ts";
+
+export type {
+  RuntimePageGraph,
+  RuntimePageNode,
+  BuildPageGraphInput,
+} from "./runtime-page-graph-types.ts";

package/src/model/layout/page-graph-types.ts

@@ -0,0 +1,181 @@
+/**
+ * Layer 02 · shared layout data types — Pass 1 of the L04/L02
+ * `src/model/layout/` seam (see `docs/plans/cross-layer-coord-04.md
+ * §1.12` and `cross-layer-coord-02.md §9`).
+ *
+ * These six interfaces are the pure-data subset of the layout graph.
+ * They describe how the paginated layout engine exposes region /
+ * fragment / line-box / footnote / anchor state — no methods, no
+ * imports from higher layers, no runtime-scoped types. They live
+ * here so external consumers (Layer 01 `CacheEnvelope`, future debug
+ * runners, stateless services) can import the shapes without pulling
+ * in `src/runtime/layout/`.
+ *
+ * Runtime-scoped companions (`RuntimePageGraph`, `RuntimePageNode`,
+ * `BuildPageGraphInput`) remain in `src/runtime/layout/page-graph.ts`
+ * because they reference `ResolvedPageStories` / `ResolvedDocumentSection`
+ * which carry runtime identity today. Pass 2 will relocate the parent
+ * graph types once those references are narrowed (see L04's coord-04
+ * §1.12 "Pass 2 (full closure)").
+ *
+ * Acceptance rule: see `src/model/layout/index.ts`. Every type here is
+ * plain data (no classes / methods / factories / higher-layer imports).
+ */
+
+// ---------------------------------------------------------------------------
+// Region types
+// ---------------------------------------------------------------------------
+
+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[];
+}
+
+// ---------------------------------------------------------------------------
+// Fragment types
+// ---------------------------------------------------------------------------
+
+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;
+  /**
+   * Refactor/04 Slice 4 — zero-based column index on the page, set only
+   * when the containing section paginated under a multi-column layout.
+   * Absent on single-column pages; absent on footnote-area + header/footer
+   * fragments. `buildRegions` uses this to route fragment ids into
+   * `RuntimePageRegions.columns[i].fragmentIds`.
+   */
+  columnIndex?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Line box + note + anchor types
+// ---------------------------------------------------------------------------
+
+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;
+}