@docx-editor.dev/core 2.12.0 → 2.13.0

package/dist/{semantic-records-CRG1r6-a.d.cts → semantic-records-Btw3Ao4v.d.cts}

@@ -1,6 +1,6 @@
-import { a as OoxmlNode, s as OoxmlProperty, x as ImageResourceState, G as DrawingAccessibility, S as SourceCrop, H as DrawingTransform, J as VectorShapeProjection, z as DrawingHorizontalReferenceFrame, A as DrawingVerticalReferenceFrame, u as ImageWrapTarget, K as DrawingProjection, L as OoxmlDrawingNode, M as TableBorderStyle, g as OoxmlElement, O as OoxmlPart } from './tree-op-types-CA7qgAUF.cjs';
-import { a as RevisionAttribution } from './revision-projection-6u8lae9J.cjs';
-import { O as OmmlEquationProjection } from './omml-equation-BmV51rim.cjs';
+import { a as OoxmlNode, s as OoxmlProperty, g as OoxmlElement, O as OoxmlPart, x as ImageResourceState, U as DrawingAccessibility, S as SourceCrop, W as DrawingTransform, X as VectorShapeProjection, z as DrawingHorizontalReferenceFrame, A as DrawingVerticalReferenceFrame, u as ImageWrapTarget, Y as DrawingProjection, Z as OoxmlDrawingNode, _ as TableBorderStyle } from './tree-op-types-BUulYD5y.cjs';
+import { a as RevisionAttribution } from './revision-projection-Dknlar93.cjs';
+import { O as OmmlEquationProjection } from './omml-equation-DB8d-jCq.cjs';
 
 /**
  * Whether a paragraph must start a new page (`w:pageBreakBefore`).
@@ -454,6 +454,164 @@ interface StoryPageFieldNeeds {
     readonly hasSectionPages: boolean;
 }
 
+/** One recognized REF instruction: the target name and the supported switches, nothing else. */
+interface RefFieldSpec {
+    readonly bookmark: string;
+    /** `r` / `w` paint the target's number; `n` the same without context; null the range text. */
+    readonly numberSwitch: 'r' | 'w' | 'n' | null;
+    /** `\h` parsed and inert — the reference paints; navigation is a follow-up. */
+    readonly hyperlink: boolean;
+}
+/**
+ * Recognize `REF <bookmark> [\r|\w|\n] [\t] [\h] [\* MERGEFORMAT]` or
+ * `NOTEREF <bookmark> [\h] [\* MERGEFORMAT]`, or null for anything else.
+ *
+ * The keyword matches case-insensitively; the bookmark name keeps its authored case (it is a
+ * lookup key into a Map, never an object property, so hostile names like `__proto__` are just
+ * names that resolve to nothing). Any unrecognized switch fails the parse so the field falls
+ * back to its cached result — never the raw instruction, never a guess. NOTEREF's `\p`
+ * (above/below position text) and `\f` (note-style formatting) are unrecognized on purpose.
+ */
+declare function parseRefInstruction(raw: string): RefFieldSpec | null;
+
+/** Soft ceiling on abstractNum / num entries read from one part. */
+declare const MAX_NUMBERING_DEFINITIONS = 512;
+/** Soft ceiling on override entries per `w:num`. */
+declare const MAX_LVL_OVERRIDES = 9;
+/** `w:suff` — what separates a list marker from the text after it. */
+type ListSuffix = 'tab' | 'space' | 'nothing';
+/** `w:lvlJc` — how a list marker aligns within its own indent. */
+type ListMarkerAlign = 'left' | 'center' | 'right';
+/**
+ * One level's indent, plus which parts the level actually AUTHORED.
+ *
+ * The provenance matters: `w:ind` cascades per-attribute, so a level that authored only `left`
+ * must not overwrite an inherited `hanging` with a synthesized zero.
+ */
+interface NumberingLevelIndent {
+    readonly left: number;
+    readonly right: number;
+    readonly hanging: number;
+    readonly firstLine: number;
+    /**
+     * Which of these the LEVEL actually authored.
+     *
+     * A level's `w:pPr/w:ind` sits between the paragraph style and direct formatting, so the
+     * merge has to tell "the level says left = 0" from "the level says nothing about left and
+     * the style's value stands". Absent (the default) reads as "says nothing", which is what a
+     * hand-built level in a test means.
+     */
+    readonly stated?: {
+        readonly left: boolean;
+        readonly right: boolean;
+        /** `w:hanging`/`w:firstLine` are one mutually exclusive slot (§17.3.1.10, §17.3.1.12). */
+        readonly firstLineOffset: boolean;
+    };
+}
+/** One `w:lvl`: how this depth numbers, what its marker looks like, and how it indents. */
+interface NumberingLevel {
+    readonly ilvl: number;
+    readonly start: number;
+    readonly numFmt: string;
+    readonly lvlText: string;
+    readonly lvlJc: ListMarkerAlign;
+    readonly suff: ListSuffix;
+    readonly indent: NumberingLevelIndent;
+    /**
+     * `w:lvlRestart` one-based trigger level, or `0` when the level never restarts.
+     * Omitted in XML → restart when the previous level (or any earlier level) is used.
+     */
+    readonly lvlRestart?: number;
+    /**
+     * `w:isLgl` (§17.9.9): render EVERY level referenced by this level's `w:lvlText` in
+     * decimal, whatever number format those levels declare for themselves.
+     */
+    readonly isLgl: boolean;
+    /** Level `w:rPr` as flat properties (for marker face / vanish). */
+    readonly runProperties: readonly OoxmlProperty[];
+    /** True when level run props request vanish — marker must not paint. */
+    readonly vanish: boolean;
+}
+/**
+ * One `w:lvlOverride` on a `w:num`: a restart value, a replacement level, or both.
+ *
+ * How two lists share an abstract definition while numbering independently.
+ */
+interface LevelOverride {
+    readonly startOverride?: number;
+    /** Full level replacement when `w:lvl` is present under the override. */
+    readonly level?: NumberingLevel;
+}
+/**
+ * One `w:abstractNum` — the shape of a list, without being a list.
+ *
+ * Never referenced by a paragraph directly. Paragraphs name a {@link NumDefinition}, which names
+ * one of these, so several lists can share a definition and still count separately.
+ */
+interface AbstractNumDefinition {
+    readonly abstractNumId: string;
+    readonly levels: ReadonlyMap<number, NumberingLevel>;
+    /**
+     * `w:numStyleLink` (§17.9.21): this definition carries no levels of its own — the numbering
+     * lives on the named style. Word follows the link; resolve it with
+     * {@link resolveNumberingStyleLinks} before reading levels, or every paragraph on this
+     * abstract renders with NO marker at all.
+     */
+    readonly numStyleLink?: string;
+    /**
+     * `w:styleLink` (§17.9.23): the definition side of the same pair — this abstract IS the
+     * numbering of the named style. Kept so a link can be verified rather than assumed.
+     */
+    readonly styleLink?: string;
+}
+/**
+ * One `w:num` — the thing a paragraph's `w:numId` actually names.
+ *
+ * Points at an {@link AbstractNumDefinition} and may override any of its levels.
+ */
+interface NumDefinition {
+    readonly numId: string;
+    readonly abstractNumId: string;
+    readonly overrides: ReadonlyMap<number, LevelOverride>;
+}
+/**
+ * The bounded projection of `numbering.xml` that list layout resolves against.
+ *
+ * Projection ONLY — never a mutation or serialization authority. Hostile values are dropped or
+ * clamped, and a missing definition resolves to "no list" rather than a guess.
+ */
+interface NumberingIndex {
+    readonly abstractNums: ReadonlyMap<string, AbstractNumDefinition>;
+    readonly nums: ReadonlyMap<string, NumDefinition>;
+}
+/**
+ * Build a numbering index from the root of a numbering part (`w:numbering`).
+ *
+ * Empty / missing roots yield an empty index. Duplicate ids keep the first definition.
+ */
+/**
+ * Project `numbering.xml` into the bounded index.
+ *
+ * Every ceiling here exists because the input is file-derived: definition counts, override
+ * counts, indent magnitudes and style-link hop depth are all capped, and nothing from the file
+ * becomes a loop bound or an allocation size.
+ */
+declare function buildNumberingIndex(root: OoxmlElement | null | undefined): NumberingIndex;
+/** Resolve the effective level for a `numId` + `ilvl`, applying overrides. */
+/**
+ * The effective level for one paragraph's numbering reference, after overrides and style links.
+ *
+ * Answers null for a reference the index cannot resolve — a paragraph naming a definition the
+ * file never declared is an unnumbered paragraph, not an error.
+ */
+declare function resolveNumberingLevel(index: NumberingIndex, numId: string, ilvl: number): {
+    readonly abstractNumId: string;
+    readonly level: NumberingLevel;
+    readonly startOverride?: number;
+} | null;
+/** Empty index for tests / documents without numbering. */
+declare const EMPTY_NUMBERING_INDEX: NumberingIndex;
+
 interface DrawingPoint {
     readonly x: number;
     readonly y: number;
@@ -475,6 +633,432 @@ interface DrawingGeometry {
     readonly effectInsets: DrawingInsets;
 }
 
+/** Horizontal alignment of a paragraph (`w:jc`, ECMA-376 §17.3.1.13). */
+type Alignment = 'left' | 'center' | 'right' | 'both';
+
+/** Soft ceiling on `basedOn` chain length — enough for real templates, refuses hostile graphs. */
+declare const MAX_STYLE_BASED_ON_DEPTH = 32;
+/** Soft ceiling on style definitions read from one styles part. */
+declare const MAX_STYLE_DEFINITIONS = 4096;
+/** One `w:style` as the cascade reads it: its properties, and the style it is based on. */
+interface StyleDefinition {
+    readonly styleId: string;
+    readonly type: string;
+    readonly basedOn: string | null;
+    /**
+     * `w:next` — the style Word gives the paragraph that FOLLOWS one in this style.
+     *
+     * Nothing in layout reads it: it is a rule about authoring, not about painting. It is
+     * read here because this is the one place `styles.xml` is parsed, and a second reader
+     * would be a second answer to what a style id means.
+     */
+    readonly next: string | null;
+    readonly paragraphProperties: readonly OoxmlProperty[];
+    readonly runProperties: readonly OoxmlProperty[];
+    /** The style's `w:pPr` node, when present — needed for nested `w:pBdr`. */
+    readonly paragraphPropertiesNode: OoxmlElement | undefined;
+    /** The style's `w:tblPr`, for a `w:type="table"` style. */
+    readonly tablePropertiesNode: OoxmlElement | undefined;
+    /**
+     * `w:tblStylePr` conditional formats by `w:type` (`firstRow`, `band1Horz`, …).
+     *
+     * Word puts a table's real appearance here: `Table Grid` carries its grid in the style's
+     * `w:tblBorders`, and the banded/​header looks live in these. A document states only
+     * `<w:tblStyle w:val="TableGrid"/>`.
+     */
+    readonly conditionalTableFormats: ReadonlyMap<string, OoxmlElement>;
+}
+/**
+ * The whole styles part, indexed and ready to resolve against.
+ *
+ * `cacheToken` is load-bearing: it folds into layout cache producers so breaks measured under one
+ * styles part are never reused under another.
+ */
+interface StyleCascadeTable {
+    /**
+     * Bounded fingerprint folded into layout cache producers so a different styles part cannot
+     * reuse breaks measured under another cascade. Computed once per table (FNV-1a hex).
+     */
+    readonly cacheToken: string;
+    readonly docDefaultsRun: readonly OoxmlProperty[];
+    readonly docDefaultsParagraph: readonly OoxmlProperty[];
+    readonly docDefaultsParagraphNode: OoxmlElement | undefined;
+    /** `w:style[@w:default='1'][@w:type='paragraph']` — last wins among defaults of that type. */
+    readonly defaultParagraphStyleId: string | null;
+    /** `w:style[@w:default='1'][@w:type='character']` — last wins among defaults of that type. */
+    readonly defaultCharacterStyleId: string | null;
+    /**
+     * `w:style[@w:default='1'][@w:type='table']` — last wins among defaults of that type.
+     *
+     * A `w:tbl` with no `w:tblStyle` still resolves against this one. Word's own
+     * `TableNormal` is where the 0/108/0/108 twip cell margins live, so skipping it gives
+     * every unstyled table padding the document says it does not have.
+     */
+    readonly defaultTableStyleId: string | null;
+    /**
+     * The theme part's Latin typefaces, for `w:rFonts` theme references.
+     *
+     * Lives on the cascade because it is document-level style material with the same
+     * lifetime, and because every site that resolves run properties already holds this table.
+     */
+    readonly themeFonts: ThemeFonts;
+    readonly styles: ReadonlyMap<string, StyleDefinition>;
+}
+/**
+ * A paragraph's properties after the cascade, plus the same list WITHOUT its own `w:pPr`.
+ *
+ * Both, because a writer needs to know what a paragraph INHERITS to decide whether setting a
+ * value is a change or a no-op — and writing back an inherited value freezes it into the
+ * paragraph as though the author had chosen it.
+ */
+interface CascadedParagraphFormatting {
+    /** Flat paragraph properties in cascade order (defaults → bases → style → direct). */
+    readonly paragraphProperties: readonly OoxmlProperty[];
+    /**
+     * The same list WITHOUT the paragraph's own `w:pPr` — everything it inherits.
+     *
+     * Numbering needs the two tiers apart: a level's `w:pPr/w:ind` outranks the style's and is
+     * outranked by the paragraph's own, and a flattened list cannot say which is which.
+     */
+    readonly inheritedParagraphProperties: readonly OoxmlProperty[];
+    /** Matching `w:pPr` nodes for nested border resolution. */
+    readonly paragraphPropertyNodes: readonly OoxmlNode[];
+    /**
+     * Inherited run properties for CONTENT runs (before direct run `rPr`).
+     *
+     * Does NOT include direct `w:pPr/w:rPr` — that formats the paragraph MARK only
+     * (ECMA-376 §17.3.1.36). Folding mark `w:sz` into content made BodyText runs with no
+     * direct size paint at the mark's size (Selection Notice "or" alternative → 6.5pt).
+     */
+    readonly runProperties: readonly OoxmlProperty[];
+    /**
+     * Content cascade plus direct `w:pPr/w:rPr` — empty-line metrics and last-line mark height.
+     */
+    readonly markRunProperties: readonly OoxmlProperty[];
+    /**
+     * The style this paragraph resolved to, or null when it names none and there is no
+     * document default. `w:contextualSpacing` compares neighbours by exactly this.
+     */
+    readonly styleId: string | null;
+}
+/** Accepted style ids only — over-long, control-bearing, or dangerous keys are dropped. */
+declare function isValidStyleId(raw: string | undefined): raw is string;
+/**
+ * What a table style contributes to the paragraphs of ONE cell: the style's whole-table
+ * `w:pPr`/`w:rPr` followed by every `w:tblStylePr` the cell is under (17.7.6.6), weakest
+ * first in the caller's condition order (banding, column, row, corner).
+ *
+ * This is how Word makes a header row bold and centred while the document states nothing
+ * but `<w:tblStyle w:val="…"/>` on the table and plain runs in the cells.
+ */
+interface TableCellStyleFormatting {
+    readonly paragraphProperties: readonly OoxmlProperty[];
+    /** Matching `w:pPr` nodes, for nested `w:pBdr` / `w:tabs` resolution. */
+    readonly paragraphPropertyNodes: readonly OoxmlElement[];
+    /** Inherited run properties for every run in the cell, before the paragraph style. */
+    readonly runProperties: readonly OoxmlProperty[];
+}
+/**
+ * Build a cascade table from a styles part root.
+ *
+ * Only direct `w:style` children of the root participate (bounded count). Duplicate
+ * `styleId` values keep the last definition, matching Word's reader for this fixture class.
+ * Default paragraph/character style ids track `w:default="1"` with the same last-wins rule.
+ */
+declare function buildStyleCascadeTable(stylesRoot: OoxmlElement | null, themeFonts?: ThemeFonts): StyleCascadeTable;
+/**
+ * Cascade paragraph + inherited run properties for one paragraph's direct `w:pPr`.
+ *
+ * Order: `docDefaults` → table style → `basedOn` ancestors → paragraph style → direct
+ * formatting, which is the style hierarchy of 17.7.2: a table style sits above the document
+ * defaults and below the paragraph style a cell paragraph names for itself.
+ * When `w:pStyle` is absent, the document's default paragraph style (`w:default="1"`) is used.
+ * Direct formatting is last so it overrides inherited values inside the existing resolvers.
+ */
+declare function cascadeParagraphFormatting(table: StyleCascadeTable, directPPr: OoxmlNode | undefined, tableCellStyle?: TableCellStyleFormatting): CascadedParagraphFormatting;
+/**
+ * Bottom border after cascade: a later `w:pBdr` replaces an earlier one; absence inherits.
+ * `nil`/`none` clear the edge via `paragraphBorders`.
+ */
+declare function cascadedBottomBorder(paragraphPropertyNodes: readonly OoxmlNode[]): ParagraphBorderEdge | undefined;
+/**
+ * Merge inherited paragraph-style run props with a run's direct `rPr` (direct last).
+ *
+ * When a cascade table is supplied, also resolves `w:rStyle` character styles (basedOn chain,
+ * cycle/depth capped). Runs without an explicit `rStyle` pick up the default character style
+ * (`w:default="1"`). Precedence: inherited → character style chain → direct formatting.
+ *
+ * PASS `inheritedRunProperties` BY IDENTITY. It must be an array
+ * {@link cascadeParagraphFormatting} returned — `runProperties` or `markRunProperties` — and
+ * not a copy of one. A toggle property (ECMA-376 §17.7.3) resolves per level of the style
+ * hierarchy, and the levels below the character style resolve to more than a true or a false:
+ * whether the document defaults' short circuit is still standing decides what the character
+ * style's own toggle does next, and no single `w:b` element can spell that. The paragraph
+ * cascade attaches that state to the array it returns, so spreading, filtering or sorting the
+ * list drops it. (`Object.freeze` returns the same object, so that one is safe.) A list
+ * without it is read as one ordinary level, which is the most a bare property list can say
+ * and is what a caller assembling its own list gets.
+ */
+declare function cascadeRunProperties(inheritedRunProperties: readonly OoxmlProperty[], directRunProperties: readonly OoxmlProperty[], table?: StyleCascadeTable): readonly OoxmlProperty[];
+/** Everything the line breaker needs about one paragraph, already cascaded and converted. */
+interface ParagraphLayoutInputs {
+    readonly props: OoxmlProperty[];
+    readonly indent: {
+        left: number;
+        right: number;
+        hanging: number;
+        firstLine: number;
+    };
+    readonly available: number;
+    readonly alignment: Alignment;
+    readonly spacing: ParagraphSpacing;
+    /** Resolved `w:line` / `w:lineRule`; single spacing where the cascade says nothing. */
+    readonly lineSpacing: ParagraphLineSpacing;
+    /** `w:contextualSpacing`: drop before/after between same-style neighbours. */
+    readonly contextualSpacing: boolean;
+    /** Resolved paragraph style id, for the `w:contextualSpacing` neighbour comparison. */
+    readonly styleId: string | null;
+    readonly bottomBorder: ParagraphBorderEdge | undefined;
+    /**
+     * Every `CT_PBdr` edge after cascade, not just the bottom one.
+     *
+     * `bottomBorder` stays alongside it because the fragment signature and the table flow
+     * read that field by name; this is the whole box, so a cell paragraph gets the same
+     * frame a body paragraph does.
+     */
+    readonly borders: ParagraphBorders;
+    /** Validated 6-hex paragraph shading fill from cascaded `w:pPr/w:shd`, absent for none. */
+    readonly shading: string | undefined;
+    readonly inheritedRunProperties: readonly OoxmlProperty[];
+    /**
+     * Paragraph-mark cascade (`inheritedRunProperties` + direct `w:pPr/w:rPr`).
+     * Empty-line sizing and last-line mark height — never content-run face.
+     */
+    readonly markRunProperties: readonly OoxmlProperty[];
+    /** Cascaded custom tab stops + default interval for paragraph-flow breaking. */
+    readonly tabStops: ResolvedTabStops;
+    /**
+     * Fingerprint folded into the paragraph layout cache key — nested `w:tabs` are absent
+     * from flat property bags, so style-inherited stops must be named explicitly.
+     */
+    readonly tabStopsCacheToken: string;
+    /** Resolved list marker inputs when the paragraph participates in numbering. */
+    readonly listItem?: ResolvedListItem;
+}
+/**
+ * Resolve every paragraph input semantic layout / table cells share: cascaded props when a
+ * style table is present, otherwise direct formatting only.
+ *
+ * When `listItem` is provided, its merged level indent becomes the paragraph indent (list
+ * hanging / left from `numbering.xml`), which is what Word uses for fixture list paragraphs
+ * that author no direct `w:ind`.
+ *
+ * `tableCellStyle` carries what the enclosing table's style says about this cell's
+ * paragraphs; body paragraphs pass nothing.
+ *
+ * `inTableCell` is asked for separately because a cell paragraph may have no table style to
+ * inherit at all, and `w:beforeAutospacing` still needs to know it is in a cell.
+ */
+declare function resolveParagraphLayoutInputs(paragraph: OoxmlElement, contentWidth: number, styleCascade: StyleCascadeTable | undefined, listItem?: ResolvedListItem, tableCellStyle?: TableCellStyleFormatting, inTableCell?: boolean): ParagraphLayoutInputs;
+
+/**
+ * A paragraph's list membership fully resolved: definition, level, marker text and geometry.
+ *
+ * `markerText` is already expanded through the counter state, so it is the string a reader sees
+ * rather than the `w:lvlText` template.
+ */
+interface ResolvedListItem {
+    readonly numId: string;
+    readonly ilvl: number;
+    readonly abstractNumId: string;
+    /** `w:numFmt` of the resolved level — `bullet` or a numbering format. */
+    readonly numFmt: string;
+    readonly markerText: string;
+    readonly markerAlign: ListMarkerAlign;
+    readonly suffix: ListSuffix;
+    /** Effective indent after merging level + paragraph indents, in points. */
+    readonly indent: NumberingLevelIndent;
+    readonly markerStyle: ResolvedRunStyle;
+    /** Fingerprint for layout cache keys (indent, marker text, marker face). */
+    readonly cacheToken: string;
+}
+/**
+ * Read `w:numPr` from cascaded paragraph-property nodes (lowest precedence first).
+ *
+ * Flat `OoxmlProperty[]` bags drop nested `ilvl`/`numId`, so this walks the tree nodes
+ * the same way borders and tabs do.
+ *
+ * `w:ilvl` and `w:numId` inherit INDEPENDENTLY through the style chain and the direct
+ * `w:pPr` (§17.3.1.19): a tier stating only the level keeps the id it inherits — Word's
+ * standard Heading2–Heading9 shape, where only Heading1 names the `w:num` — and a tier
+ * stating only the id keeps the inherited level. Treating each `w:numPr` node as a full
+ * replacement dropped the id at every level-only tier and unnumbered the paragraph. A
+ * stated `w:numId w:val="0"` (or an invalid value) still switches numbering off at that
+ * tier even when a lower tier set one; a higher tier stating a valid id re-enables. A
+ * level-only tier with no id inherited from below resolves to no numbering.
+ */
+declare function readNumPr(paragraphPropertyNodes: readonly OoxmlNode[]): {
+    numId: string;
+    ilvl: number;
+} | null;
+/**
+ * Resolve `w:numStyleLink` delegation using the document's styles (§17.9.21).
+ *
+ * Without a style table there is nothing to follow, so the index is returned unchanged —
+ * and so it is when nothing delegates, which keeps layout cache identity.
+ */
+declare function withNumberingStyleLinks(index: NumberingIndex, styleCascade: StyleCascadeTable | undefined): NumberingIndex;
+/**
+ * The effective indent of a list paragraph: STYLE, then the numbering LEVEL, then DIRECT.
+ *
+ * Word applies a level's `w:pPr/w:ind` between the paragraph style and the paragraph's own
+ * formatting, per attribute — and the ordering matters on real documents. A converted
+ * agreement numbers its `(a)` items with a level stating `left=1512 hanging=738` under a
+ * `ListParagraph` style stating `left=775 hanging=624`, and states only `hanging="737"` on
+ * the paragraph itself. Reading the flattened cascade as "the paragraph's indent" gave the
+ * STYLE's 775 to a level that had overridden it, so every lettered sub-item hung a full
+ * indent step to the left of where Word puts it.
+ *
+ * `inherited` is the cascade WITHOUT the paragraph's own `w:pPr` (defaults, table cell style,
+ * style chain); `direct` is that `w:pPr` alone.
+ */
+declare function mergeListIndent(levelIndent: NumberingLevelIndent, inherited: readonly OoxmlProperty[], direct?: readonly OoxmlProperty[]): NumberingLevelIndent;
+/**
+ * Collect paragraphs of a block list in document order, descending into tables.
+ *
+ * Caps nesting so a hostile nested-table document cannot recurse without bound.
+ */
+declare function walkStoryParagraphs(blocks: readonly OoxmlElement[], maxTableDepth?: number): OoxmlElement[];
+/**
+ * Resolve every list paragraph in a story to a {@link ResolvedListItem}, keyed by node id.
+ *
+ * Non-list paragraphs are absent from the map. Hostile / missing numbering resolves inertly
+ * (paragraph omitted — laid out as ordinary text).
+ */
+declare function resolveStoryListItems(blocks: readonly OoxmlElement[], index: NumberingIndex, styleCascade: StyleCascadeTable | undefined, isFontAvailable?: (family: string) => boolean): ReadonlyMap<string, ResolvedListItem>;
+/**
+ * Attach a full-story list-item map to layout options.
+ *
+ * Resolves once over `blocks` (body story including table cells) so counters continue across
+ * section boundaries. No-ops when numbering is absent.
+ */
+declare function withResolvedListItems<T extends {
+    readonly numberingIndex?: NumberingIndex;
+    readonly listItems?: ReadonlyMap<string, ResolvedListItem>;
+    readonly styleCascade?: StyleCascadeTable;
+    readonly isFontAvailable?: (family: string) => boolean;
+}>(options: T, blocks: readonly OoxmlElement[]): T & {
+    readonly numberingIndex: NumberingIndex;
+    readonly listItems?: ReadonlyMap<string, ResolvedListItem>;
+};
+/**
+ * Horizontal marker box inside the first-line indent slot.
+ *
+ * Coordinates are relative to the same origin as paragraph content (`indent.left` is the
+ * text start). Returns null when there is nothing to paint.
+ *
+ * `w:hanging` and a positive `w:firstLine` are one mutually exclusive slot
+ * (§17.3.1.10, §17.3.1.12), so the marker has two placements, not an interaction:
+ * a hanging level puts the marker BEFORE the text start (`left - hanging`); a
+ * positive-firstLine level puts it AFTER (`left + firstLine`) — the standard legal
+ * shape `w:ind w:left="0" w:firstLine="720"` numbers at 0.5" while continuation
+ * lines return to the margin. Reading only the hanging model painted every such
+ * marker at the left margin.
+ */
+declare function listMarkerBox(item: ResolvedListItem, markerWidth: number, lineY: number, lineHeight: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+
+/**
+ * The story's resolved REF inputs for one layout pass.
+ *
+ * Threaded as a runtime rider on the layout options (see `layoutSemanticDocument`) rather
+ * than a `SemanticLayoutOptions` member, so the public options surface stays put. Absent
+ * means every REF field paints its cached result — the pre-existing degradation, and the one
+ * header/footer and text-box stories still take. Note stories receive the body's context
+ * through `NotesLayoutInput.refFields`.
+ */
+interface RefFieldContext {
+    /**
+     * Content token over every PAINTED REF output in the story, for the section prepass memo.
+     * A renumbering edit can move a REF value in a section whose own blocks and list map are
+     * identity-unchanged, and this token is the only validator that sees it. A field that
+     * failed calibration contributes its (session-constant) cached text, so the token still
+     * moves exactly when painted output moves.
+     */
+    readonly valuesToken: string;
+    /** The paragraph's REF outputs folded for its block cache key; `''` when it holds none. */
+    tokenForParagraph(paragraphId: string): string;
+    /**
+     * The live value ONE field paints, keyed by its begin / `w:fldSimple` node id, or null to
+     * keep the cached result (failed calibration, unresolvable, or an anchor this scan never
+     * saw). Anchor-keyed so the projection's paint and this context's token fold read the SAME
+     * calibration verdict, however each walk collected the field's cached text.
+     */
+    liveValueOf(anchorId: string, spec: RefFieldSpec): string | null;
+    /**
+     * The synthesized display of ONE AUTONUM-family field, keyed by its begin / `w:fldSimple`
+     * node id, or null to paint nothing (unsupported switches, or an anchor this scan never
+     * saw — both the field's historical rendering). These fields carry no cached result at
+     * all, so there is no calibration: the sequential value is the only display they have.
+     * Optional so hand-built contexts predating it stay valid.
+     */
+    autonumValueOf?(anchorId: string): string | null;
+    /**
+     * The deferred projection of ONE `PAGEREF` field, or null to keep the cached result
+     * (missing bookmark, unsupported switches, or an anchor this scan never saw).
+     *
+     * A `PAGEREF` value is a property of pagination, so the scan cannot compute it — it hands
+     * the projection the resolved TARGET and the calibration inputs instead, and document
+     * finalize (`finalizePageFieldProjection`) substitutes the page number the target's first
+     * fragment lands on. Optional so hand-built contexts predating it stay valid.
+     */
+    pageRefProjectionOf?(anchorId: string, spec: RefFieldSpec): PageRefFieldProjection | null;
+}
+/**
+ * Sticky calibration identity for one `PAGEREF` field.
+ *
+ * An opaque frozen object rather than a mutable verdict holder because span markers are
+ * serialized into fragment signatures — a verdict written into the marker would move a
+ * signature that no painted output moved. The verdict itself lives beside the finalize pass
+ * (`field-page-furniture.ts`), keyed weakly on this object; the registry below carries the
+ * object across passes the same way REF verdicts are carried.
+ */
+type PageRefCalibrationCell = Readonly<Record<never, never>>;
+/**
+ * What a `PAGEREF` span carries to document finalize: the resolved target, the normalized
+ * authored cache (the calibration oracle), and the sticky calibration identity.
+ */
+interface PageRefFieldProjection {
+    /** Canonical id of the paragraph the bookmark names — first declaration wins. */
+    readonly targetParagraphId: string;
+    /** The authored cached result, whitespace-collapsed — what the computed number must reproduce. */
+    readonly cached: string;
+    readonly calibration: PageRefCalibrationCell;
+}
+/**
+ * Note parts whose stories join the context: their REF fields resolve against the body's
+ * bookmarks and numbering (a footnote citing "Section 1.2(c)" targets a body paragraph),
+ * and their bookmark declarations become plain-REF targets. Number switches aimed AT a
+ * note paragraph still fall back to the cached result — the list map is the body's.
+ */
+interface RefNoteParts {
+    readonly footnotesPart: OoxmlPart | null;
+    readonly endnotesPart: OoxmlPart | null;
+}
+/**
+ * Resolve the document's REF fields for one layout pass, or null when it has none.
+ *
+ * Bookmarks and REF fields resolve across the body story and (when `notes` is given) the
+ * footnote/endnote stories, against ONE shared target index — a footnote REF finds the
+ * body bookmark it cites. Header/footer and text-box stories are not given a context and
+ * keep painting cached results.
+ */
+declare function resolveStoryRefFields(blocks: readonly OoxmlElement[], listItems: ReadonlyMap<string, ResolvedListItem> | undefined, notes?: RefNoteParts): RefFieldContext | null;
+
 /**
  * Why textbox story layout stopped short.
  *
@@ -647,6 +1231,15 @@ interface FieldAtomMarker {
         /** The field's `\#` numeric picture, applied when finalize substitutes the value. */
         readonly picture?: string;
     };
+    /**
+     * A BODY `PAGEREF` atom whose value is the page number its bookmark target lands on.
+     *
+     * Deferred exactly like {@link pageField}: the paragraph walk paints the field's cached
+     * result (or the placeholder digit when the file cached none) and records the resolved
+     * target here; document finalize substitutes the number of the page hosting the target's
+     * first fragment, gated per field on the calibration verdict.
+     */
+    readonly pageRef?: PageRefFieldProjection;
 }
 /** A half-open model-offset range, in the paragraph's own UTF-16 offset space. */
 interface ModelRange {
@@ -982,10 +1575,12 @@ interface StyleSpanRecord {
     /**
      * Cumulative advances from {@link box}.x to each UTF-16 caret boundary in {@link text}.
      *
-     * Length is `text.length + 1` (both endpoints). Layout publishes these so hit-testing and
-     * the caret read the same per-cluster edges the span was measured with, rather than
-     * re-measuring a prefix at interaction time or interpolating across {@link box}.width —
-     * OpenSpec task 13.5. Absent on older records; consumers fall back to the measurer.
+     * Length is `text.length + 1` (both endpoints). When PRESENT, these are the interaction
+     * authority: hit-testing and the caret read them instead of re-measuring. Layout does not
+     * publish them eagerly — measuring every character of every laid span dominated page
+     * repagination — so interactions measure prefixes on demand through the same measurer the
+     * span was laid with (memoized per span; see `prefixWidth` in semantic-hit-test.ts), and
+     * only interpolate across {@link box}.width when no measurer is supplied.
      */
     readonly caretEdges?: readonly number[];
     /**
@@ -1682,4 +2277,4 @@ interface TextMeasurer {
     };
 }
 
-export { type LineSpacingRule as $, type AnchoredDrawingRecord as A, type BlockFragmentRecord as B, type ContentControlBoundaryRecord as C, type DrawingPoint as D, DEFAULT_TAB_INTERVAL_PT as E, type FieldLinkProjector as F, DEFAULT_TAB_INTERVAL_TWIPS as G, type HyperlinkProjector as H, type InlineDrawingRecord as I, EMPTY_TAB_STOPS as J, type EquationFractionGeometry as K, type LineRecord as L, type ModelRange as M, type EquationGeometry as N, type EquationNaryGeometry as O, type PageGeometry as P, type EquationRadicalGeometry as Q, type ResolvedRunStyle as R, type SemanticLayout as S, type TextMeasurer as T, type EquationRowGeometry as U, type EquationScriptGeometry as V, type EquationSpanRecord as W, type EquationTextGeometry as X, type FieldAtomMarker as Y, type HeaderFooterStoryRecord as Z, type HyperlinkFieldSpec as _, type StyleSpanRecord as a, type ListMarkerRecord as a0, MAX_BORDER_SPACE_PT as a1, MAX_BORDER_WIDTH_PT as a2, MAX_PARAGRAPH_SPACING_PT as a3, MAX_TABLE_BORDER_STROKES as a4, MAX_TAB_POSITION_TWIPS as a5, MAX_TAB_STOPS as a6, PARAGRAPH_BORDER_SIDES as a7, type ParagraphAutoSpacingContext as a8, type ParagraphBorderSide as a9, cascadedTabStops as aA, collapsedSpaceBefore as aB, defaultTabIntervalFromSettings as aC, displayText as aD, layoutEquation as aE, measureDisplayText as aF, nextTabDestination as aG, paragraphBorderExtentPt as aH, paragraphBorderStrokeWidthPt as aI, paragraphBorders as aJ, paragraphBordersFingerprint as aK, paragraphBreaksBefore as aL, paragraphContextualSpacing as aM, paragraphLineSpacing as aN, paragraphSpacing as aO, paragraphTabStops as aP, readBorderSide as aQ, readCellBorders as aR, readTableBorders as aS, resolveBorderConflict as aT, resolveRunStyle as aU, resolveTableCellBorderGrid as aV, runStylesEqual as aW, tabAdvanceWidth as aX, tabStopsFingerprint as aY, withDefaultTabInterval as aZ, type ParagraphBorderStrokeRecord as aa, type ParagraphBottomBorderRecord as ab, type ParagraphIndent as ac, type ResolvedCellBorders as ad, type ResolvedTableBorderEdge as ae, type ResolvedTableBorderEdgeSegment as af, type ResolvedUnderline as ag, SINGLE_LINE_SPACING as ah, type SourceRange as ai, type SpanLinkRecord as aj, TAB_LEADER_GLYPH as ak, type TabAlignment as al, type TabDestination as am, type TabLeader as an, type TabStop as ao, type TableBorderSideName as ap, type TableBorderStrokeRecord as aq, type TableFragmentRecord as ar, type VerticalAlign as as, appliedSpaceBefore as at, applyLineSpacing as au, baselineShiftPtOf as av, borderExtentPt as aw, borderWeight as ax, bottomBorderExtentPt as ay, cascadedParagraphBorders as az, type TableRowFragmentRecord as b, type TableCellFragmentRecord as c, type LayoutBox as d, type DrawingInsets as e, type ThemeFonts as f, type ParagraphSpacing as g, type ParagraphLineSpacing as h, type ParagraphBorderEdge as i, type ParagraphBorders as j, type ResolvedTabStops as k, type PageRecord as l, type TableBorderSide as m, type ContentControlLock as n, type ParagraphFragmentRecord as o, type InlineDrawingLayoutContext as p, type StoryPageFieldNeeds as q, type CellBorderBox as r, type TableBorderBox as s, AUTO_PARAGRAPH_SPACING_PT as t, type BorderGridGeometry as u, type ContentControlGeometryFragment as v, type ContentControlLevel as w, type ContentControlMappedType as x, DEFAULT_PAGE_GEOMETRY as y, DEFAULT_RUN_STYLE as z };
+export { type FieldAtomMarker as $, type AnchoredDrawingRecord as A, type BlockFragmentRecord as B, type ContentControlBoundaryRecord as C, type DrawingPoint as D, DEFAULT_RUN_STYLE as E, type FieldLinkProjector as F, DEFAULT_TAB_INTERVAL_PT as G, type HyperlinkProjector as H, type InlineDrawingRecord as I, DEFAULT_TAB_INTERVAL_TWIPS as J, EMPTY_NUMBERING_INDEX as K, type LineRecord as L, type ModelRange as M, type NumberingLevel as N, EMPTY_TAB_STOPS as O, type PageGeometry as P, type EquationFractionGeometry as Q, type ResolvedRunStyle as R, type SemanticLayout as S, type TextMeasurer as T, type EquationGeometry as U, type EquationNaryGeometry as V, type EquationRadicalGeometry as W, type EquationRowGeometry as X, type EquationScriptGeometry as Y, type EquationSpanRecord as Z, type EquationTextGeometry as _, type StyleSpanRecord as a, cascadedParagraphBorders as a$, type HeaderFooterStoryRecord as a0, type HyperlinkFieldSpec as a1, type LevelOverride as a2, type LineSpacingRule as a3, type ListMarkerAlign as a4, type ListMarkerRecord as a5, type ListSuffix as a6, MAX_BORDER_SPACE_PT as a7, MAX_BORDER_WIDTH_PT as a8, MAX_LVL_OVERRIDES as a9, type ResolvedTableBorderEdge as aA, type ResolvedTableBorderEdgeSegment as aB, type ResolvedUnderline as aC, SINGLE_LINE_SPACING as aD, type SourceRange as aE, type SpanLinkRecord as aF, type StyleDefinition as aG, TAB_LEADER_GLYPH as aH, type TabAlignment as aI, type TabDestination as aJ, type TabLeader as aK, type TabStop as aL, type TableBorderSideName as aM, type TableBorderStrokeRecord as aN, type TableFragmentRecord as aO, type VerticalAlign as aP, appliedSpaceBefore as aQ, applyLineSpacing as aR, baselineShiftPtOf as aS, borderExtentPt as aT, borderWeight as aU, bottomBorderExtentPt as aV, buildNumberingIndex as aW, buildStyleCascadeTable as aX, cascadeParagraphFormatting as aY, cascadeRunProperties as aZ, cascadedBottomBorder as a_, MAX_NUMBERING_DEFINITIONS as aa, MAX_PARAGRAPH_SPACING_PT as ab, MAX_STYLE_BASED_ON_DEPTH as ac, MAX_STYLE_DEFINITIONS as ad, MAX_TABLE_BORDER_STROKES as ae, MAX_TAB_POSITION_TWIPS as af, MAX_TAB_STOPS as ag, type NumDefinition as ah, type NumberingLevelIndent as ai, PARAGRAPH_BORDER_SIDES as aj, type PageRefCalibrationCell as ak, type PageRefFieldProjection as al, type ParagraphAutoSpacingContext as am, type ParagraphBorderEdge as an, type ParagraphBorderSide as ao, type ParagraphBorderStrokeRecord as ap, type ParagraphBorders as aq, type ParagraphBottomBorderRecord as ar, type ParagraphIndent as as, type ParagraphLayoutInputs as at, type ParagraphLineSpacing as au, type ParagraphSpacing as av, type RefFieldSpec as aw, type RefNoteParts as ax, type ResolvedCellBorders as ay, type ResolvedTabStops as az, type TableRowFragmentRecord as b, cascadedTabStops as b0, collapsedSpaceBefore as b1, defaultTabIntervalFromSettings as b2, displayText as b3, isValidStyleId as b4, layoutEquation as b5, listMarkerBox as b6, measureDisplayText as b7, mergeListIndent as b8, nextTabDestination as b9, withNumberingStyleLinks as bA, withResolvedListItems as bB, paragraphBorderExtentPt as ba, paragraphBorderStrokeWidthPt as bb, paragraphBorders as bc, paragraphBordersFingerprint as bd, paragraphBreaksBefore as be, paragraphContextualSpacing as bf, paragraphLineSpacing as bg, paragraphSpacing as bh, paragraphTabStops as bi, parseRefInstruction as bj, readBorderSide as bk, readCellBorders as bl, readNumPr as bm, readTableBorders as bn, resolveBorderConflict as bo, resolveNumberingLevel as bp, resolveParagraphLayoutInputs as bq, resolveRunStyle as br, resolveStoryListItems as bs, resolveStoryRefFields as bt, resolveTableCellBorderGrid as bu, runStylesEqual as bv, tabAdvanceWidth as bw, tabStopsFingerprint as bx, walkStoryParagraphs as by, withDefaultTabInterval as bz, type TableCellFragmentRecord as c, type NumberingIndex as d, type LayoutBox as e, type DrawingInsets as f, type PageRecord as g, type TableBorderSide as h, type ContentControlLock as i, type ParagraphFragmentRecord as j, type InlineDrawingLayoutContext as k, type StyleCascadeTable as l, type RefFieldContext as m, type StoryPageFieldNeeds as n, type ResolvedListItem as o, type CellBorderBox as p, type TableCellStyleFormatting as q, type TableBorderBox as r, AUTO_PARAGRAPH_SPACING_PT as s, type AbstractNumDefinition as t, type BorderGridGeometry as u, type CascadedParagraphFormatting as v, type ContentControlGeometryFragment as w, type ContentControlLevel as x, type ContentControlMappedType as y, DEFAULT_PAGE_GEOMETRY as z };