@docx-editor.dev/core 2.13.0 → 2.14.0

package/dist/{semantic-records-Btw3Ao4v.d.cts → semantic-records-BpozY7-j.d.cts}

@@ -1,5 +1,5 @@
 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 { b as RevisionAttribution } from './revision-projection-DXbrfNGD.cjs';
 import { O as OmmlEquationProjection } from './omml-equation-DB8d-jCq.cjs';
 
 /**
@@ -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.
@@ -696,7 +1229,7 @@ interface StyleCascadeTable {
      */
     readonly defaultTableStyleId: string | null;
     /**
-     * The theme part's Latin typefaces, for `w:rFonts` theme references.
+     * 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.
@@ -1571,6 +2104,14 @@ 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}.
@@ -2277,4 +2818,4 @@ interface TextMeasurer {
     };
 }
 
-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 };
+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 };