@docx-editor.dev/core 2.12.0 → 2.14.0

package/dist/{semantic-records-CRG1r6-a.d.cts → semantic-records-92UnKeU_.d.ts}

@@ -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-D6HzlPR4.js';
+import { b as RevisionAttribution } from './revision-projection-BeXVrSSV.js';
+import { O as OmmlEquationProjection } from './omml-equation-BY49UOIF.js';
 
 /**
  * Whether a paragraph must start a new page (`w:pageBreakBefore`).
@@ -339,6 +339,473 @@ declare function tabAdvanceWidth(alignment: TabAlignment, currentX: number, dest
  */
 declare function tabStopsFingerprint(tabs: ResolvedTabStops): string;
 
+/**
+ * UAX #9 embedding levels, one per UTF-16 code unit, plus the paragraph ranges they were resolved
+ * within.
+ *
+ * The level is EXACT, not a direction: its parity gives direction, but the numeric value is what
+ * reordering needs, and collapsing it early loses nested isolates.
+ */
+interface BidiEmbeddingLevels {
+    readonly levels: Uint8Array;
+    readonly paragraphs: readonly {
+        readonly start: number;
+        readonly end: number;
+        readonly level: number;
+    }[];
+}
+
+/**
+ * A face, as something asks for it: family plus the two axes this engine admits.
+ *
+ * Only static weights and slants. Variable-font axes are deliberately outside this vocabulary —
+ * the shaper refuses variation axes, and a variable file admitted here would render bold at
+ * regular weight.
+ */
+interface FontRequest {
+    readonly family: string;
+    readonly weight: number;
+    readonly style: 'normal' | 'italic';
+}
+/**
+ * A request that was answered by a DIFFERENT face than the one asked for.
+ *
+ * Recorded rather than silently applied, because a substitution changes measurement: it is part
+ * of the shaping fingerprint, so a cached run shaped against a substitute is never reused for the
+ * real face.
+ */
+interface FontSubstitution {
+    readonly requested: FontRequest;
+    readonly resolved: FontRequest;
+    readonly lineMetrics?: {
+        readonly heightEm: number;
+        readonly baselineEm: number;
+    };
+}
+declare const RESOLVED_FONT_BRAND: unique symbol;
+/**
+ * A face that passed admission: the bytes are present, within limits, hash-verified, and parse as
+ * a font.
+ *
+ * Branded, so a `ResolvedFont` cannot be constructed by an object literal. Holding one is proof
+ * the checks ran — which is what lets shaping skip re-validating on every call.
+ */
+interface ResolvedFont {
+    readonly [RESOLVED_FONT_BRAND]: true;
+    readonly id: string;
+    readonly identity: string;
+    readonly request: FontRequest;
+    readonly family: string;
+    /** Owned byte length, available without creating a defensive byte copy. */
+    readonly byteLength: number;
+    readonly bytes: Uint8Array;
+    readonly hash: string;
+    readonly faceIndex: number;
+    readonly substitution: FontSubstitution | null;
+}
+/**
+ * Largest single face this engine will ever admit, whatever a caller configures.
+ *
+ * A CEILING, not a default: a host may set a smaller `maxFontBytes`, but nothing can raise it
+ * past this. Font bytes come from files, and an unbounded face is a memory-exhaustion vector.
+ */
+declare const HARD_MAX_FONT_BYTES: number;
+/** Most faces one snapshot may hold, whatever a caller configures. */
+declare const HARD_MAX_FONT_SOURCES = 256;
+/** Most bytes all admitted faces may total, whatever a caller configures. */
+declare const HARD_MAX_AGGREGATE_FONT_BYTES: number;
+/**
+ * Why a face was not admitted.
+ *
+ * `forbidden` and `hashMismatch` are adversarial signals rather than ordinary failures: the first
+ * is a face the host declared off-limits, the second is bytes that are not what their source
+ * claimed.
+ */
+type FontResolutionErrorCode = 'missing' | 'forbidden' | 'overLimit' | 'malformed' | 'hashMismatch';
+/**
+ * A face that could not be admitted, carrying whatever evidence the refusal produced.
+ *
+ * RETURNED rather than thrown by `FontResourceSnapshot.resolve`, because a missing face is an
+ * ordinary condition — layout falls back and carries on. It extends `Error` so a caller that
+ * would rather throw can.
+ */
+declare class FontResolutionError extends Error {
+    readonly name = "FontResolutionError";
+    readonly request: FontRequest;
+    readonly code: FontResolutionErrorCode;
+    readonly limit?: number;
+    readonly actual?: number;
+    readonly diagnostic?: string;
+    readonly expectedHash?: string;
+    readonly actualHash?: string;
+    constructor(code: FontResolutionErrorCode, request: FontRequest, details?: {
+        readonly limit?: number;
+        readonly actual?: number;
+        readonly diagnostic?: string;
+        readonly expectedHash?: string;
+        readonly actualHash?: string;
+    });
+}
+/**
+ * One face offered to a snapshot, before admission.
+ *
+ * `hash` is checked against the bytes, so a source cannot claim a face it did not supply. Setting
+ * `availability` to `forbidden` declares a face that exists but must not be used, which resolves
+ * as a typed refusal rather than as "missing".
+ */
+interface FontResourceDefinition {
+    readonly request: FontRequest;
+    readonly id: string;
+    readonly bytes: Uint8Array;
+    readonly hash: string;
+    readonly faceIndex: number;
+    readonly availability?: 'available' | 'forbidden';
+}
+/**
+ * A host-declared redirect: requests for `from` resolve to `to`.
+ *
+ * How a metric-compatible substitute is wired in — a document naming Calibri resolves to Carlito
+ * without the document being rewritten.
+ */
+interface DeclaredFontSubstitution {
+    readonly from: FontRequest;
+    readonly to: FontRequest;
+    readonly lineMetrics?: {
+        readonly heightEm: number;
+        readonly baselineEm: number;
+    };
+}
+/** Whether bytes parse as a usable font, with a diagnostic when they do not. */
+type FontValidationResult = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly diagnostic: string;
+};
+/**
+ * The injected check that bytes really are a font.
+ *
+ * Injected because it is the shaper that knows — HarfBuzz can open a face and read its tables,
+ * and this layer must not duplicate that judgement. Every byte reaching it is file input.
+ */
+type FontByteValidator = (bytes: Uint8Array, faceIndex: number) => FontValidationResult;
+/**
+ * An immutable set of admitted faces, and the only way to reach one.
+ *
+ * `epoch` identifies the snapshot: fonts change by REPLACING it, never by mutation, so a layout
+ * pass holds one snapshot for its whole run and cannot observe a face appearing or vanishing
+ * midway.
+ */
+interface FontResourceSnapshot {
+    readonly epoch: number;
+    /** The admitted face, or a typed refusal. Never throws. */
+    resolve(request: FontRequest): ResolvedFont | FontResolutionError;
+}
+/**
+ * How a snapshot is built: which faces, under what limits, validated how.
+ *
+ * `maxFontBytes` is clamped to {@link HARD_MAX_FONT_BYTES} — a caller may tighten the budget but
+ * never widen it past the engine's own ceiling.
+ */
+interface FontResourceSnapshotOptions {
+    readonly epoch: number;
+    readonly maxFontBytes: number;
+    readonly resources: readonly FontResourceDefinition[];
+    readonly substitutions?: readonly DeclaredFontSubstitution[];
+    readonly validateFont: FontByteValidator;
+    readonly instrumentation?: FontResourceInstrumentation;
+}
+/**
+ * Optional counters for the operations font admission is expected to do RARELY.
+ *
+ * Exists so tests can assert the absence of work: hashing and byte-copying a 64 MB face on every
+ * resolve would not be visible in output, only in a stalled document, so the checks assert these
+ * fire once rather than per call.
+ */
+interface FontResourceInstrumentation {
+    readonly onOwnedByteCopy?: () => void;
+    readonly onHash?: () => void;
+    readonly onTableScan?: () => void;
+    readonly onAdmission?: () => void;
+}
+/**
+ * The canonical string identifying one face request.
+ *
+ * Case- and whitespace-normalized, so `"Times New Roman"` and `"times new roman"` are one key —
+ * a document may name a family either way and both must reach the same face.
+ */
+declare const fontRequestKey: (request: FontRequest) => string;
+/** Bounded minimum sfnt/TTC check; Task 4 supplies full parser-backed validation. */
+declare const boundedStructuralFontValidator: FontByteValidator;
+/**
+ * Admit a set of faces and return the immutable snapshot layout resolves against.
+ *
+ * Admission is the trust boundary for font bytes: counts and sizes are checked against the hard
+ * ceilings, each face's hash is re-derived and compared, and the bytes are handed to the injected
+ * validator. A face failing any of these is recorded as a typed refusal rather than dropped, so
+ * `resolve` can explain itself instead of answering "missing".
+ */
+declare const createFontResourceSnapshot: (options: FontResourceSnapshotOptions) => FontResourceSnapshot;
+
+declare const FIXED_POINT: unique symbol;
+/** Fixed-point coordinates are safe integers in units declared by ShapingEnvironment.fixedPointScale. */
+type FixedPoint = number & {
+    readonly [FIXED_POINT]: true;
+};
+/**
+ * Brand a safe integer as a {@link FixedPoint} coordinate.
+ *
+ * Fixed point rather than float throughout shaping so that two runs shaped identically compare
+ * EQUAL — float accumulation would make the same text measure differently depending on how it was
+ * split, and pagination is decided on those measurements.
+ *
+ * @throws RangeError when the value is not a safe integer.
+ */
+declare const fixedPoint: (value: number) => FixedPoint;
+/** Which way a run reads. The parity projection of its bidi embedding level. */
+type TextDirection = 'ltr' | 'rtl';
+/** How fixed-point conversion breaks ties. Part of the shaping fingerprint. */
+type FixedPointRoundingMode = 'halfAwayFromZero' | 'halfToEven' | 'towardZero';
+/** Which Unicode normalization is applied before shaping, if any. */
+type NormalizationPolicy = 'none' | 'NFC' | 'NFD' | 'NFKC' | 'NFKD';
+/**
+ * The shaping library and its exact version.
+ *
+ * Versioned because a library upgrade can change glyph positioning, and a cached measurement
+ * taken under the old one must not be reused under the new one.
+ */
+interface VersionedShapingLibrary {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Everything that determines how text shapes — the complete input to a
+ * {@link ShapingEnvironment}.
+ *
+ * Exhaustive on purpose. Any field that could change a glyph's position belongs here, because the
+ * environment's fingerprint is what decides whether a cached shaped run may be reused.
+ */
+interface ShapingEnvironmentInput {
+    readonly font: ResolvedFont;
+    readonly variationAxes: Readonly<Record<string, number>>;
+    readonly shapingLibrary: VersionedShapingLibrary;
+    readonly unicodeDataVersion: string;
+    readonly normalization: NormalizationPolicy;
+    readonly script: string;
+    readonly language: string;
+    readonly direction: TextDirection;
+    readonly features: Readonly<Record<string, number>>;
+    readonly fallbackOrder: readonly ResolvedFont[];
+    readonly fixedPointScale: number;
+    readonly roundingMode: FixedPointRoundingMode;
+}
+/**
+ * A validated {@link ShapingEnvironmentInput} — build one with `createShapingEnvironment`.
+ *
+ * Structurally identical to its input, but the nominal distinction is the point: holding one
+ * means the tags, axes and fonts inside it have already been checked.
+ */
+interface ShapingEnvironment extends ShapingEnvironmentInput {
+}
+/** One shaping call: the text, its size, its bidi level, and the environment to shape it in. */
+interface ShapeInput {
+    readonly text: string;
+    readonly fontSizeHalfPoints: number;
+    /** Exact UAX #9 embedding/isolate level; direction is its parity projection. */
+    readonly bidiLevel: number;
+    readonly environment: ShapingEnvironment;
+}
+/**
+ * One positioned glyph.
+ *
+ * `id` is a glyph index in its FACE, not a character — a ligature is one glyph spanning several
+ * characters, and a single character may produce several glyphs. Use `cluster` to get back to
+ * text.
+ */
+interface ShapedGlyph {
+    readonly id: number;
+    /** UTF-16 text offset identifying the cluster that produced this glyph. */
+    readonly cluster: number;
+    /** Pen origin before this glyph's shaping offsets, in fixed-point run coordinates. */
+    readonly originX: FixedPoint;
+    readonly originY: FixedPoint;
+    readonly advanceX: FixedPoint;
+    readonly advanceY: FixedPoint;
+    readonly offsetX: FixedPoint;
+    readonly offsetY: FixedPoint;
+    /** Exact monochrome outline returned by the admitted HarfBuzz face. */
+    readonly outline: GlyphOutline;
+}
+/** A glyph's outline as SVG path data, in font design units. */
+interface GlyphOutline {
+    readonly path: string;
+    /** Design units per em — divide by this to scale the path to a point size. */
+    readonly unitsPerEm: number;
+}
+/**
+ * One cluster: the smallest indivisible text-to-glyph correspondence.
+ *
+ * The unit the CARET moves by. A cluster may be several characters (a ligature) or several glyphs
+ * (a decomposed mark), so neither a character index nor a glyph index is a valid caret position —
+ * `caretEdges` is, and it includes both endpoints.
+ */
+interface ShapedCluster {
+    /** Half-open logical UTF-16 range in ShapedRun.text. */
+    readonly textStart: number;
+    readonly textEnd: number;
+    /** Half-open visual glyph range in ShapedRun.glyphs. */
+    readonly glyphStart: number;
+    readonly glyphEnd: number;
+    readonly advance: FixedPoint;
+    /** Fixed-point edges from this cluster's visual origin, including both endpoints. */
+    readonly caretEdges: readonly FixedPoint[];
+    /** Index into ShapedRun.fontSpans, preserving the exact fallback choice. */
+    readonly fontSpan: number;
+}
+/** A run's vertical metrics, from the face that shaped it. Drives line height and baseline. */
+interface ShapedVerticalMetrics {
+    readonly ascent: FixedPoint;
+    readonly descent: FixedPoint;
+    readonly lineGap: FixedPoint;
+}
+/**
+ * A stretch of glyphs that came from ONE face.
+ *
+ * A run whose text needed fallback has several of these. Recording the exact face per span is
+ * what lets a re-shape reproduce the same result rather than re-running fallback selection and
+ * possibly choosing differently.
+ */
+interface ShapedFontSpan {
+    readonly glyphStart: number;
+    readonly glyphEnd: number;
+    readonly font: ResolvedFont;
+    /** null denotes the primary font; otherwise this is the environment fallback-order index. */
+    readonly fallbackIndex: number | null;
+}
+/**
+ * One shaped run: text turned into positioned glyphs, with everything needed to measure it, paint
+ * it, and put a caret in it.
+ *
+ * The engine's measurement unit. Layout never measures characters — it measures these.
+ */
+interface ShapedRun {
+    readonly text: string;
+    readonly direction: TextDirection;
+    readonly bidiLevel: number;
+    readonly glyphs: readonly ShapedGlyph[];
+    readonly clusters: readonly ShapedCluster[];
+    readonly fontSpans: readonly ShapedFontSpan[];
+    readonly metrics: ShapedVerticalMetrics;
+}
+/**
+ * A {@link ShapedRun} reduced to the fields two shaping results must agree on to be considered
+ * identical.
+ *
+ * Fonts appear as {@link FontFingerprintInputs} rather than whole `ResolvedFont` objects, so the
+ * comparison is over VALUES and does not depend on object identity — which is what makes it work
+ * across a reload or a worker boundary.
+ */
+interface ShapedRunComparatorInputs {
+    readonly text: string;
+    readonly direction: TextDirection;
+    readonly script: string;
+    readonly language: string;
+    readonly bidiLevel: number;
+    readonly glyphs: readonly ShapedGlyph[];
+    readonly clusters: readonly ShapedCluster[];
+    readonly fontSpans: readonly {
+        readonly glyphStart: number;
+        readonly glyphEnd: number;
+        readonly fallbackIndex: number | null;
+        readonly font: FontFingerprintInputs;
+    }[];
+    readonly metrics: ShapedVerticalMetrics;
+}
+/**
+ * The one thing layout needs from a shaping backend.
+ *
+ * Injected rather than imported, which is what keeps layout DOM-free and testable: a fixed-metric
+ * shaper measures deterministically in a test, HarfBuzz measures for real in a browser, and
+ * layout cannot tell the difference.
+ */
+interface TextShaper {
+    shape(input: ShapeInput): ShapedRun;
+}
+/**
+ * A font reduced to the values that identify it for fingerprinting.
+ *
+ * Includes the content `hash` and `faceIndex`, so two faces with the same family name but
+ * different bytes fingerprint differently — which is what stops a cached measurement being reused
+ * against a substituted face.
+ */
+interface FontFingerprintInputs {
+    readonly identity: string;
+    readonly id: string;
+    readonly family: string;
+    readonly request: FontRequest;
+    readonly hash: string;
+    readonly faceIndex: number;
+    readonly byteLength: number;
+    readonly substitution: FontSubstitution | null;
+}
+/**
+ * A {@link ShapingEnvironment} reduced to comparable values.
+ *
+ * Records and axis maps become SORTED entry arrays, because two environments differing only in
+ * key insertion order must fingerprint the same — otherwise a cache would miss on a difference
+ * that changes no glyph.
+ */
+interface ShapingEnvironmentFingerprintInputs {
+    readonly font: FontFingerprintInputs;
+    readonly variationAxes: readonly (readonly [string, number])[];
+    readonly shapingLibrary: VersionedShapingLibrary;
+    readonly unicodeDataVersion: string;
+    readonly normalization: NormalizationPolicy;
+    readonly script: string;
+    readonly language: string;
+    readonly direction: TextDirection;
+    readonly features: readonly (readonly [string, number])[];
+    readonly fallbackOrder: readonly FontFingerprintInputs[];
+    readonly fixedPointScale: number;
+    readonly roundingMode: FixedPointRoundingMode;
+}
+/**
+ * Validate and freeze a shaping environment.
+ *
+ * Checks every field that could silently corrupt a measurement: OpenType tags must be four ASCII
+ * bytes, script and language must be non-blank and control-character free, fonts must already be
+ * validated. Throws rather than coercing — a bad tag that shapes anyway produces a document that
+ * measures wrong everywhere and looks fine.
+ *
+ * @throws TypeError on a malformed tag, name, or axis value.
+ */
+declare const createShapingEnvironment: (input: ShapingEnvironmentInput) => ShapingEnvironment;
+/**
+ * Reduce an environment to its comparable form, with records sorted so key order cannot affect
+ * the result.
+ */
+declare const shapingEnvironmentFingerprintInputs: (input: ShapingEnvironmentInput) => ShapingEnvironmentFingerprintInputs;
+/** Canonical serialization of every shaping variable, including byte hash and provenance. */
+declare const shapingEnvironmentFingerprint: (environment: ShapingEnvironmentInput) => string;
+/**
+ * Validate and freeze a shaped run against the environment that produced it.
+ *
+ * Checks the internal consistency a shaper must satisfy: direction matches the environment,
+ * cluster ranges tile the text without gaps or overlap, glyph ranges stay in bounds, font spans
+ * cover every glyph, and caret edges are monotonic. A shaper that violates any of these produces
+ * a caret that lands in the wrong place, which is far harder to diagnose downstream than here.
+ *
+ * @throws TypeError when the run and environment disagree, or the run is internally inconsistent.
+ */
+declare const createShapedRun: (input: ShapedRun, environmentInput: ShapingEnvironmentInput) => ShapedRun;
+/**
+ * Reduce a shaped run to its comparable form, validating it on the way through.
+ *
+ * What the D9 determinism oracles compare: two shaping runs of the same text in the same
+ * environment must produce byte-identical structures here.
+ */
+declare const shapedRunComparatorInputs: (input: ShapedRun, environment: ShapingEnvironmentInput) => ShapedRunComparatorInputs;
+
 /** `w:vertAlign` — script position, which also scales the run's effective size. */
 type VerticalAlign = 'baseline' | 'superscript' | 'subscript';
 /** A resolved underline: its variant, and its colour when it does not follow the text. */
@@ -356,6 +823,16 @@ interface ResolvedUnderline {
  */
 interface ResolvedRunStyle {
     readonly fontFamily: string | null;
+    /**
+     * The `eastAsia` slot's typeface (`w:rFonts w:eastAsia`/`w:eastAsiaTheme`), or null when
+     * no level authors one.
+     *
+     * OOXML picks a run's face per SCRIPT: `fontFamily` covers the ascii/hAnsi slots, and
+     * ideographic/kana/hangul text resolves through this one instead. Kept beside — not
+     * folded into — `fontFamily`, because a mixed run needs both at once and the split into
+     * slot-homogeneous pieces happens downstream (`piecesOfParagraph`).
+     */
+    readonly fontFamilyEastAsia: string | null;
     /** Points. `w:sz` is half-points, so 22 becomes 11. */
     readonly fontSizePt: number;
     /** RRGGBB, or null for the inherited/automatic colour. */
@@ -401,16 +878,20 @@ interface ResolvedRunStyle {
 /** The style a run inherits when it authors nothing. */
 declare const DEFAULT_RUN_STYLE: ResolvedRunStyle;
 /**
- * The theme part's two Latin typefaces, for resolving `w:rFonts` theme attributes.
+ * The theme part's typefaces, for resolving `w:rFonts` theme attributes.
  *
  * Structurally identical to the binding lane's `DocumentThemeFonts` and assignable from it.
- * Declared here so this lane reads two validated strings rather than the theme tree.
+ * Declared here so this lane reads validated strings rather than the theme tree.
  */
 interface ThemeFonts {
     /** `a:majorFont` latin typeface — headings. */
     readonly major: string | null;
     /** `a:minorFont` latin typeface — body text. */
     readonly minor: string | null;
+    /** `a:majorFont` east asian typeface (`a:ea`) — headings. Optional for back-compat. */
+    readonly majorEastAsia?: string | null;
+    /** `a:minorFont` east asian typeface (`a:ea`) — body text. Optional for back-compat. */
+    readonly minorEastAsia?: string | null;
 }
 /**
  * Resolve one run's direct formatting.
@@ -439,6 +920,58 @@ declare function runStylesEqual(a: ResolvedRunStyle, b: ResolvedRunStyle): boole
  */
 declare function baselineShiftPtOf(style: ResolvedRunStyle): number;
 
+/**
+ * Which `w:rFonts` slot a character resolves its face through.
+ *
+ * OOXML gives a run up to four faces and picks between them by SCRIPT, so one run of mixed Latin
+ * and CJK text uses two different fonts without saying so anywhere in its properties.
+ */
+type FontSlot = 'ascii' | 'hAnsi' | 'eastAsia' | 'cs';
+/**
+ * A run of text sharing one script, direction and font slot — the unit handed to the shaper.
+ *
+ * Shaping cannot span a script change: Arabic and Latin in one call would produce wrong joining
+ * behaviour, so a run is itemized into these first.
+ */
+interface ScriptItem {
+    readonly from: number;
+    readonly to: number;
+    readonly direction: TextDirection;
+    readonly bidiLevel: number;
+    readonly script: 'Zyyy' | 'Latn' | 'Grek' | 'Cyrl' | 'Hani' | 'Hebr' | 'Arab' | 'Deva' | 'Beng' | 'Thai' | 'Khmr';
+    readonly slot: FontSlot;
+}
+/**
+ * A code point whose script this engine does not itemize.
+ *
+ * Carries the offending `codePoint` so the caller can report which character stopped it, rather
+ * than failing anonymously somewhere in the middle of a paragraph.
+ */
+declare class UnsupportedScriptError extends Error {
+    readonly name = "UnsupportedScriptError";
+    readonly code = "unsupportedScript";
+    readonly codePoint: number;
+    constructor(codePoint: number);
+}
+/**
+ * Split text into shapeable runs by script, bidi level and font slot.
+ *
+ * Consumes the bidi levels rather than re-deriving direction, so itemization and reordering agree
+ * by construction instead of by two implementations happening to match.
+ */
+declare function itemizeScriptFontSlots(text: string, paragraphOffset: number, embedding: BidiEmbeddingLevels): readonly ScriptItem[];
+/**
+ * The style a piece's text is MEASURED AND PAINTED in, given the font slot it carries.
+ *
+ * This is the measurer-boundary resolution: pieces and spans keep the run's real resolved
+ * style — with `fontFamily` and `fontFamilyEastAsia` both intact, so formatting readback
+ * and the format painter see the run as authored — and every consumer that turns text into
+ * geometry or ink resolves the face through here. The derived object is memoized per
+ * (style, family) by {@link withFontFamily}, so measurers amortizing over style identity
+ * keep their caches.
+ */
+declare function styleForFontSlot(style: ResolvedRunStyle, slot: FontSlot | undefined): ResolvedRunStyle;
+
 type AllowlistedPageField = 'PAGE' | 'NUMPAGES' | 'SECTIONPAGES';
 /**
  * Which allowlisted page fields a header/footer story actually contains.
@@ -454,6 +987,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 +1166,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 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 +1764,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 {
@@ -978,14 +2104,24 @@ interface StyleSpanRecord {
      * point put the caret where no glyph is.
      */
     readonly style: ResolvedRunStyle;
+    /**
+     * The `w:rFonts` slot this span's text resolves its face through; absent means the base
+     * (ascii/hAnsi) slots. {@link style} stays the run's full resolution — with both
+     * `fontFamily` and `fontFamilyEastAsia` — so formatting readback and the format painter
+     * see the run as authored; measurement, paint and hit-testing resolve the effective face
+     * with `styleForFontSlot(span.style, span.fontSlot)`.
+     */
+    readonly fontSlot?: FontSlot;
     readonly box: LayoutBox;
     /**
      * 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 +2818,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 DeclaredFontSubstitution as $, type AnchoredDrawingRecord as A, type BlockFragmentRecord as B, type ContentControlBoundaryRecord as C, type DrawingPoint as D, AUTO_PARAGRAPH_SPACING_PT as E, type FontResourceSnapshot as F, type AbstractNumDefinition as G, type HyperlinkProjector as H, type InlineDrawingRecord as I, type BidiEmbeddingLevels as J, type BorderGridGeometry as K, type LineRecord as L, type ModelRange as M, type NormalizationPolicy as N, type CascadedParagraphFormatting as O, type PageGeometry as P, type ContentControlGeometryFragment as Q, type ResolvedRunStyle as R, type SemanticLayout as S, type TextMeasurer as T, type ContentControlLevel as U, type VersionedShapingLibrary as V, type ContentControlMappedType as W, DEFAULT_PAGE_GEOMETRY as X, DEFAULT_RUN_STYLE as Y, DEFAULT_TAB_INTERVAL_PT as Z, DEFAULT_TAB_INTERVAL_TWIPS as _, type StyleSpanRecord as a, type ResolvedUnderline as a$, EMPTY_NUMBERING_INDEX as a0, EMPTY_TAB_STOPS as a1, type EquationFractionGeometry as a2, type EquationGeometry as a3, type EquationNaryGeometry as a4, type EquationRadicalGeometry as a5, type EquationRowGeometry as a6, type EquationScriptGeometry as a7, type EquationSpanRecord as a8, type EquationTextGeometry as a9, MAX_PARAGRAPH_SPACING_PT as aA, MAX_STYLE_BASED_ON_DEPTH as aB, MAX_STYLE_DEFINITIONS as aC, MAX_TABLE_BORDER_STROKES as aD, MAX_TAB_POSITION_TWIPS as aE, MAX_TAB_STOPS as aF, type NumDefinition as aG, type NumberingLevelIndent as aH, PARAGRAPH_BORDER_SIDES as aI, type PageRefCalibrationCell as aJ, type PageRefFieldProjection as aK, type ParagraphAutoSpacingContext as aL, type ParagraphBorderEdge as aM, type ParagraphBorderSide as aN, type ParagraphBorderStrokeRecord as aO, type ParagraphBorders as aP, type ParagraphBottomBorderRecord as aQ, type ParagraphIndent as aR, type ParagraphLayoutInputs as aS, type ParagraphLineSpacing as aT, type ParagraphSpacing as aU, type RefFieldSpec as aV, type RefNoteParts as aW, type ResolvedCellBorders as aX, type ResolvedTabStops as aY, type ResolvedTableBorderEdge as aZ, type ResolvedTableBorderEdgeSegment as a_, type FieldAtomMarker as aa, type FontFingerprintInputs as ab, type FontRequest as ac, FontResolutionError as ad, type FontResolutionErrorCode as ae, type FontResourceDefinition as af, type FontResourceInstrumentation as ag, type FontResourceSnapshotOptions as ah, type FontSlot as ai, type FontSubstitution as aj, type FontValidationResult as ak, type GlyphOutline as al, HARD_MAX_AGGREGATE_FONT_BYTES as am, HARD_MAX_FONT_BYTES as an, HARD_MAX_FONT_SOURCES as ao, type HeaderFooterStoryRecord as ap, type HyperlinkFieldSpec as aq, type LevelOverride as ar, type LineSpacingRule as as, type ListMarkerAlign as at, type ListMarkerRecord as au, type ListSuffix as av, MAX_BORDER_SPACE_PT as aw, MAX_BORDER_WIDTH_PT as ax, MAX_LVL_OVERRIDES as ay, MAX_NUMBERING_DEFINITIONS as az, type TextShaper as b, parseRefInstruction as b$, SINGLE_LINE_SPACING as b0, type ScriptItem as b1, type ShapeInput as b2, type ShapedCluster as b3, type ShapedFontSpan as b4, type ShapedGlyph as b5, type ShapedRunComparatorInputs as b6, type ShapedVerticalMetrics as b7, type ShapingEnvironment as b8, type ShapingEnvironmentFingerprintInputs as b9, cascadedBottomBorder as bA, cascadedParagraphBorders as bB, cascadedTabStops as bC, collapsedSpaceBefore as bD, createFontResourceSnapshot as bE, createShapedRun as bF, createShapingEnvironment as bG, defaultTabIntervalFromSettings as bH, displayText as bI, fixedPoint as bJ, fontRequestKey as bK, isValidStyleId as bL, itemizeScriptFontSlots as bM, layoutEquation as bN, listMarkerBox as bO, measureDisplayText as bP, mergeListIndent as bQ, nextTabDestination as bR, paragraphBorderExtentPt as bS, paragraphBorderStrokeWidthPt as bT, paragraphBorders as bU, paragraphBordersFingerprint as bV, paragraphBreaksBefore as bW, paragraphContextualSpacing as bX, paragraphLineSpacing as bY, paragraphSpacing as bZ, paragraphTabStops as b_, type ShapingEnvironmentInput as ba, type SourceRange as bb, type SpanLinkRecord as bc, type StyleDefinition as bd, TAB_LEADER_GLYPH as be, type TabAlignment as bf, type TabDestination as bg, type TabLeader as bh, type TabStop as bi, type TableBorderSideName as bj, type TableBorderStrokeRecord as bk, type TableFragmentRecord as bl, type TextDirection as bm, UnsupportedScriptError as bn, type VerticalAlign as bo, appliedSpaceBefore as bp, applyLineSpacing as bq, baselineShiftPtOf as br, borderExtentPt as bs, borderWeight as bt, bottomBorderExtentPt as bu, boundedStructuralFontValidator as bv, buildNumberingIndex as bw, buildStyleCascadeTable as bx, cascadeParagraphFormatting as by, cascadeRunProperties as bz, type FixedPointRoundingMode as c, readBorderSide as c0, readCellBorders as c1, readNumPr as c2, readTableBorders as c3, resolveBorderConflict as c4, resolveNumberingLevel as c5, resolveParagraphLayoutInputs as c6, resolveRunStyle as c7, resolveStoryListItems as c8, resolveStoryRefFields as c9, resolveTableCellBorderGrid as ca, runStylesEqual as cb, shapedRunComparatorInputs as cc, shapingEnvironmentFingerprint as cd, shapingEnvironmentFingerprintInputs as ce, styleForFontSlot as cf, tabAdvanceWidth as cg, tabStopsFingerprint as ch, walkStoryParagraphs as ci, withDefaultTabInterval as cj, withNumberingStyleLinks as ck, withResolvedListItems as cl, type ResolvedFont as d, type TableRowFragmentRecord as e, type TableCellFragmentRecord as f, type NumberingLevel as g, type NumberingIndex as h, type LayoutBox as i, type DrawingInsets as j, type PageRecord as k, type TableBorderSide as l, type ContentControlLock as m, type ParagraphFragmentRecord as n, type FontByteValidator as o, type FixedPoint as p, type ShapedRun as q, type InlineDrawingLayoutContext as r, type StyleCascadeTable as s, type FieldLinkProjector as t, type RefFieldContext as u, type StoryPageFieldNeeds as v, type ResolvedListItem as w, type CellBorderBox as x, type TableCellStyleFormatting as y, type TableBorderBox as z };