@pptx-studio/model 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1340 @@
+import { COLOR_TRANSFORM_OPS, ClrMap, ClrScheme, Color, ColorContext, Effect, Fill, Line, Rgba } from "@pptx-studio/paint";
+import { XElement } from "@pptx-studio/xml";
+import { Geometry, PresetGuide } from "@pptx-studio/geometry";
+import { PartStore } from "@pptx-studio/opc";
+//#region src/errors.d.ts
+/**
+ * Typed failures, as everywhere else in this repository.
+ *
+ * Two kinds of thing go wrong here and they want different treatment.
+ *
+ * A **broken package** - a slide that names no layout, a layout whose master is
+ * missing, a master with no theme - is not a programming mistake. PowerPoint
+ * repairs all three rather than refusing them (measured in 2.9, and after the
+ * repair the binding is simply gone), and a viewer that throws on a file
+ * PowerPoint opens is a viewer nobody can use. So those are *not* errors here:
+ * the chain records what it found and `parent` is `null`. There is a code for
+ * each all the same, because `validate` refuses to *write* one, and because a
+ * caller that asks for the theme of a master that has none needs an answer with
+ * a name.
+ *
+ * A **caller mistake** - resolving `phClr` outside a style invocation, asking
+ * for a sheet that is not in the document - is an error and throws.
+ */
+type ModelErrorCode =
+/** A part the chain needs is not in the package. */
+'MODEL_PART_MISSING' |
+/** A part is present but its root element is not the one its rel promised. */
+'MODEL_PART_KIND' |
+/** `ppt/presentation.xml` is missing, or the root rels do not name it. */
+'MODEL_NO_PRESENTATION' |
+/** A slide has no `slideLayout` relationship, or a layout no `slideMaster`. */
+'MODEL_NO_PARENT' |
+/** A master has no `theme` relationship. */
+'MODEL_NO_THEME' |
+/** A `p:clrMap` or `a:overrideClrMapping` missing one of its twelve attributes. */
+'MODEL_CLRMAP_INCOMPLETE' |
+/** A `p:clrMap` attribute naming something that is not one of the twelve slots. */
+'MODEL_CLRMAP_SLOT' |
+/** A `p:ph/@idx` that is not a non-negative integer below 2^32. */
+'MODEL_PLACEHOLDER_IDX' |
+/** An `a:off`/`a:ext`/`@rot` attribute that is not an integer. */
+'MODEL_XFRM_NUMBER' |
+/** A style-matrix reference whose `@idx` does not parse. */
+'MODEL_STYLE_IDX' |
+/** An `a:fontRef/@idx` outside `major`, `minor` and `none`. */
+'MODEL_FONT_COLLECTION' |
+/** A theme with no `a:fmtScheme`, asked for a style-matrix entry. */
+'MODEL_NO_STYLE_MATRIX' |
+/** A `a:fillStyleLst`/`a:lnStyleLst`/`a:bgFillStyleLst` with no entries at all. */
+'MODEL_STYLE_LIST_EMPTY' |
+/** A sheet chain that returns to a sheet it has already visited. */
+'MODEL_SHEET_CYCLE' |
+/** A sheet that does not belong to the document it was asked about. */
+'MODEL_FOREIGN_SHEET' |
+/** `a:prstGeom` with no `@prst`, or an `a:custGeom` command missing a point. */
+'MODEL_GEOMETRY' |
+/** A text attribute whose value is not of the type its schema names. */
+'MODEL_TEXT_ATTR' |
+/** An `a:fld` with no `@id`, which is a required `ST_Guid`. */
+'MODEL_TEXT_FIELD' |
+/**
+ * A bullet that contradicts itself or omits what the schema requires.
+ *
+ * The four kinds are an exclusive group, `a:buAutoNum` must carry a @type and
+ * `a:buBlip` must resolve to a relationship. A file that breaks one of those is
+ * one PowerPoint would repair, and repairing it here quietly would hide which.
+ */
+'MODEL_TEXT_BULLET' |
+/** A paragraph level that is not an integer. */
+'MODEL_TEXT_LEVEL' | 'MODEL_TEXT_TYPEFACE' | 'BLIP_NO_EMBED' | 'BLIP_DUOTONE' | 'BLIP_CLR_CHANGE' | 'BLIP_TILE_ALIGN' | 'BLIP_TILE_FLIP';
+declare class ModelError extends Error {
+  readonly name = "ModelError";
+  readonly code: ModelErrorCode;
+  /** The part the failure is about, when there is one. */
+  readonly partName: string | null;
+  /** Whatever detail names the failure: an attribute value, a rel id, a slot. */
+  readonly detail: string | null;
+  constructor(code: ModelErrorCode, message: string, partName?: string | null, detail?: string | null);
+}
+declare function isModelError(value: unknown): value is ModelError;
+declare const MODEL_ERROR_CODES: readonly ModelErrorCode[];
+//#endregion
+//#region src/parse/geometry.d.ts
+/**
+ * What a shape says it is.
+ *
+ * `preset` keeps the adjust values as guides rather than numbers, because
+ * `a:avLst` is a `CT_GeomGuideList` and a guide may in principle carry any
+ * formula - `evaluateGuides` takes either form and the file's form is the one
+ * that round-trips.
+ */
+type ShapeGeometry = {
+  readonly kind: 'preset';
+  readonly prst: string;
+  readonly adjust: readonly PresetGuide[];
+} | {
+  readonly kind: 'custom';
+  readonly geometry: Geometry;
+};
+/**
+ * The geometry a shape declares, or `undefined` when it declares none.
+ *
+ * `undefined` is the whole point: a slide placeholder with no `a:prstGeom` has
+ * not chosen to be a rectangle, it has said nothing, and `resolve` is what turns
+ * that into the layout's answer.
+ */
+declare function parseGeometry(spPr: XElement | undefined, partName: string): ShapeGeometry | undefined;
+//#endregion
+//#region src/text.d.ts
+/** `ST_TextAlignType`. */
+type TextAlign = 'l' | 'ctr' | 'r' | 'just' | 'justLow' | 'dist' | 'thaiDist';
+/** `ST_TextFontAlignType`. */
+type FontAlign = 'auto' | 't' | 'ctr' | 'base' | 'b';
+/** `ST_TextUnderlineType`, all seventeen, as written. */
+type Underline = 'none' | 'words' | 'sng' | 'dbl' | 'heavy' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dotDashHeavy' | 'dotDotDash' | 'dotDotDashHeavy' | 'wavy' | 'wavyHeavy' | 'wavyDbl';
+/** `ST_TextStrikeType`. */
+type Strike = 'noStrike' | 'sngStrike' | 'dblStrike';
+/** `ST_TextCapsType`. */
+type Caps = 'none' | 'small' | 'all';
+/**
+ * `a:lnSpc`, `a:spcBef` and `a:spcAft`, which are one of two quite different
+ * things and say which in their child element's name.
+ *
+ * `a:spcPct` is hundred-thousandths of the line height - 150000 is 150%.
+ * `a:spcPts` is hundredths of a point - 3000 is 30pt. Conflating them collapses
+ * every slide that uses the second, and `ST_Percentage` accepts *both* the
+ * `150000` and the `150%` spellings, so the parse is not `parseInt` either:
+ * `parseInt("150%")` is 150, which is 0.15% line spacing. Measured in 3.1, and
+ * in 2.6 for the colour transforms that share the type.
+ */
+type Spacing = {
+  readonly kind: 'percent';
+  readonly value: number;
+} | {
+  readonly kind: 'points';
+  readonly value: number;
+};
+/**
+ * One of the four typeface slots on a run.
+ *
+ * `@typeface` may be a real face name or a theme reference - `+mj-lt`,
+ * `+mn-lt`, `+mj-ea`, `+mn-ea`, `+mj-cs`, `+mn-cs` - and the reference is kept
+ * as written rather than resolved here, because which theme it resolves against
+ * is a property of the sheet and not of the run.
+ */
+interface Typeface {
+  readonly typeface: string;
+  /** `@panose`, twenty hex characters. */
+  readonly panose: string | undefined;
+  /** `@pitchFamily`, `(family << 4) | pitch`. */
+  readonly pitchFamily: number | undefined;
+  /** `@charset`, **signed**: Shift-JIS is -128, not 128. */
+  readonly charset: number | undefined;
+}
+/**
+ * Which of a theme's two font collections a `+mj-`/`+mn-` reference names.
+ *
+ * `script` is spelled the way `FontCollection` spells it rather than the way the
+ * reference does - `lt` in the markup is the `a:latin` element, and a resolver
+ * that carried the reference's spelling would need a second map between two
+ * three-member sets to index the thing it just parsed.
+ */
+type ThemeFontRef = {
+  readonly collection: 'major' | 'minor';
+  readonly script: 'latin' | 'ea' | 'cs';
+};
+/** `+mn-lt` and its five siblings, or `null` for a real typeface name. */
+declare function themeFontRef(typeface: string): ThemeFontRef | null;
+/**
+ * `CT_TextCharacterProperties` - `a:rPr`, `a:defRPr` and `a:endParaRPr`.
+ *
+ * Every field is optional in the file and optional here. The cascade merges
+ * these **per property**: measured in 3.1 with five levels declaring one
+ * property each, which produced a 24-point bold italic underlined struck run
+ * where a nearest-level-takes-all reading gives an 18-point struck one.
+ */
+interface RunProps {
+  /** `@sz`, hundredths of a point. 2400 is 24pt. */
+  readonly sz: number | undefined;
+  readonly b: boolean | undefined;
+  readonly i: boolean | undefined;
+  readonly u: Underline | undefined;
+  readonly strike: Strike | undefined;
+  readonly cap: Caps | undefined;
+  /** `@spc`, hundredths of a point. May be negative. */
+  readonly spc: number | undefined;
+  /** `@kern`, hundredths of a point: the size at or above which to kern. */
+  readonly kern: number | undefined;
+  /** `@baseline`, hundred-thousandths. 30000 is superscript. */
+  readonly baseline: number | undefined;
+  readonly noProof: boolean | undefined;
+  readonly lang: string | undefined;
+  readonly altLang: string | undefined;
+  readonly latin: Typeface | undefined;
+  readonly ea: Typeface | undefined;
+  readonly cs: Typeface | undefined;
+  readonly sym: Typeface | undefined;
+  /** The text's own fill: `a:solidFill` and its siblings inside `a:rPr`. */
+  readonly fill: Fill | undefined;
+  /** `a:ln` inside `a:rPr`: the outline of the glyphs. */
+  readonly line: Line | undefined;
+  readonly effects: readonly Effect[] | undefined;
+  /** `a:highlight`, which is a colour and not a fill. */
+  readonly highlight: Color | undefined;
+  /** The element this was read from. Edits go here, never to the fields above. */
+  readonly node: XElement;
+}
+/**
+ * The exclusive group in `CT_TextParagraphProperties`: one of four, or nothing.
+ *
+ * `undefined` on `ParaProps` is the fifth case and the one that matters -
+ * a level that declares no bullet element at all **inherits** one, where
+ * `'none'` suppresses it.
+ */
+type BulletKind = 'none' | 'char' | 'autonum' | 'blip';
+/** `a:buFont` / `a:buFontTx`, which are exclusive of each other. */
+type BulletFont = {
+  readonly kind: 'typeface';
+  readonly value: Typeface;
+} |
+/** `a:buFontTx`: follow the text, and cancel anything inherited. */
+{
+  readonly kind: 'text';
+};
+/** `a:buSzPct` / `a:buSzPts` / `a:buSzTx`. */
+type BulletSize =
+/** `a:buSzPct/@val`, thousandths of a percent of the first run's size. */
+{
+  readonly kind: 'percent';
+  readonly value: number;
+} |
+/** `a:buSzPts/@val`, hundredths of a point, absolute. */
+{
+  readonly kind: 'points';
+  readonly value: number;
+} | {
+  readonly kind: 'text';
+};
+/** `a:buClr` / `a:buClrTx`. */
+type BulletColor = {
+  readonly kind: 'color';
+  readonly value: Color;
+} | {
+  readonly kind: 'text';
+};
+/** `a:buAutoNum`. */
+interface BulletAutoNum {
+  /** `@type`, one of the 41 `ST_TextAutonumberScheme` values. */
+  readonly type: string;
+  /**
+   * `@startAt`. Absent is measured to behave exactly as `1` - but the two are
+   * kept apart, because a paragraph whose `startAt` differs from its
+   * predecessor's begins a new run, and "absent" has to compare equal to "1"
+   * for that rule rather than to nothing.
+   */
+  readonly startAt: number | undefined;
+}
+/**
+ * `CT_TextParagraphProperties` - `a:pPr` and every `a:lvlNpPr`.
+ *
+ * `@lvl` is deliberately absent. It is the level a paragraph *is at*, not a
+ * property that inherits: an `a:lvl3pPr` carrying `lvl="7"` would be nonsense,
+ * and a cascade that inherited it would change which level the next lookup used
+ * halfway through resolving one paragraph.
+ */
+interface ParaProps {
+  /** `@marL`, EMU. Measured to default to **0**, not to the schema's 347663. */
+  readonly marL: number | undefined;
+  readonly marR: number | undefined;
+  /** `@indent`, EMU, usually negative. Defaults to 0, not to -342900. */
+  readonly indent: number | undefined;
+  readonly algn: TextAlign | undefined;
+  /** `@defTabSz`, EMU. */
+  readonly defTabSz: number | undefined;
+  readonly rtl: boolean | undefined;
+  readonly eaLnBrk: boolean | undefined;
+  readonly fontAlgn: FontAlign | undefined;
+  /** `@latinLnBrk`. ECMA says the default is true; PowerPoint behaves as false. */
+  readonly latinLnBrk: boolean | undefined;
+  readonly hangingPunct: boolean | undefined;
+  readonly lnSpc: Spacing | undefined;
+  readonly spcBef: Spacing | undefined;
+  readonly spcAft: Spacing | undefined;
+  /** `a:defRPr`: the run properties every run in this paragraph starts from. */
+  readonly defRPr: RunProps | undefined;
+  /**
+   * Which of `a:buNone`, `a:buChar`, `a:buAutoNum` and `a:buBlip` this level
+   * states, or `undefined` where it states none and inherits instead.
+   */
+  readonly buKind: BulletKind | undefined;
+  /** `a:buChar/@char`, exactly as written. The symbol mapping happens at draw time. */
+  readonly buChar: string | undefined;
+  readonly buAutoNum: BulletAutoNum | undefined;
+  /** `a:buBlip/a:blip/@r:embed`. */
+  readonly buBlip: string | undefined;
+  /**
+   * The three decorations, each its own slot.
+   *
+   * They merge independently of the kind and of each other, which is measured
+   * rather than assumed: a level declaring only `a:buFont` re-faces the
+   * character it inherits and keeps its size and colour, and a level declaring
+   * only `a:buSzTx` cancels an inherited `a:buSzPct` and keeps the rest.
+   * Measured on eleven cases twice - once through a shape's own `a:lstStyle`
+   * and once through three hops of the master chain.
+   */
+  readonly buFont: BulletFont | undefined;
+  readonly buSize: BulletSize | undefined;
+  readonly buColor: BulletColor | undefined;
+  readonly node: XElement;
+}
+/**
+ * `CT_TextListStyle`: nine levels, and an `a:defPPr` nothing reads.
+ *
+ * `levels[0]` is `a:lvl1pPr`, which a paragraph at `lvl="0"` uses. Measured in
+ * 3.1: the levels are independent all the way up the chain - a layout
+ * placeholder declaring only `a:lvl2pPr` changes the second level and leaves the
+ * first and third to the master - so this is nine slots and not one object.
+ *
+ * `a:defPPr` is parsed and kept because it is in the file, and it is **not** a
+ * source: measured on a shape's own `a:lstStyle` and on `p:defaultTextStyle`,
+ * declaring only an `a:defPPr` changed nothing either time.
+ */
+interface ListStyle {
+  /** Nine entries, `a:lvl1pPr` through `a:lvl9pPr`, absent ones `undefined`. */
+  readonly levels: readonly (ParaProps | undefined)[];
+  /** `a:defPPr`. Preserved, never resolved against. */
+  readonly defPPr: ParaProps | undefined;
+  readonly node: XElement;
+}
+/** The number of levels a `CT_TextListStyle` holds, and `@lvl`'s range plus one. */
+declare const LEVELS = 9;
+/** `a:r`: a run of text with its own properties. */
+interface TextRun {
+  readonly kind: 'run';
+  readonly props: RunProps | undefined;
+  readonly text: string;
+  readonly node: XElement;
+}
+/**
+ * `a:br`: a hard line break.
+ *
+ * Not a paragraph break. It starts no new bullet, resets no first-line indent
+ * and applies neither `spcBef` nor `spcAft` - which is 3.6's problem, and is
+ * recorded here so that nothing later mistakes it for an `a:p`.
+ */
+interface TextBreak {
+  readonly kind: 'br';
+  readonly props: RunProps | undefined;
+  readonly node: XElement;
+}
+/** `a:fld`: a field, with the text PowerPoint last cached for it. */
+interface TextField {
+  readonly kind: 'field';
+  /** `@id`, a required `ST_Guid`. Regenerating it is a repair risk. */
+  readonly id: string;
+  /** `@type`, one of the fourteen reserved names or a custom one. */
+  readonly fieldType: string | undefined;
+  readonly props: RunProps | undefined;
+  readonly text: string;
+  readonly node: XElement;
+}
+type TextContent = TextRun | TextBreak | TextField;
+/** `a:p`. */
+interface Paragraph {
+  readonly props: ParaProps | undefined;
+  /**
+   * `a:pPr/@lvl`, 0 through 8, defaulting to 0.
+   *
+   * Read off the paragraph rather than inherited, and clamped rather than
+   * thrown on: `ST_TextIndentLevelType` bounds it at 8, and a file outside the
+   * bound is one PowerPoint still opens.
+   */
+  readonly level: number;
+  readonly content: readonly TextContent[];
+  /** `a:endParaRPr`: the properties of the (empty) run after the last one. */
+  readonly endParaRPr: RunProps | undefined;
+  readonly node: XElement;
+}
+/** `ST_TextAnchoringType`. PowerPoint lays `just` and `dist` out as `b`. */
+type TextAnchor = 't' | 'ctr' | 'b' | 'just' | 'dist';
+/** `ST_TextVerticalType`. */
+type VerticalText = 'horz' | 'vert' | 'vert270' | 'wordArtVert' | 'eaVert' | 'mongolianVert' | 'wordArtVertRtl';
+/** `ST_TextWrappingType`. */
+type TextWrap = 'none' | 'square';
+/** `ST_TextVertOverflowType`. */
+type VertOverflow = 'overflow' | 'ellipsis' | 'clip';
+/** `ST_TextHorzOverflowType`. */
+type HorzOverflow = 'overflow' | 'clip';
+/** The one autofit child an `a:bodyPr` may carry. */
+type Autofit = {
+  readonly kind: 'none';
+} | {
+  readonly kind: 'shape';
+} | {
+  readonly kind: 'normal';
+  /** `@fontScale`, thousandths of a percent. */
+  readonly fontScale: number | undefined;
+  /** `@lnSpcReduction`, thousandths of a percent. */
+  readonly lnSpcReduction: number | undefined;
+};
+/**
+ * `a:bodyPr`, as the file states it.
+ *
+ * Lengths are EMU and `rot` is 60000ths of a degree, both as written. Every
+ * attribute inherits through the placeholder chain on its own - measured in 3.6
+ * at all three levels - so absence has to survive parsing.
+ */
+interface BodyProps {
+  readonly anchor: TextAnchor | undefined;
+  readonly anchorCtr: boolean | undefined;
+  readonly lIns: number | undefined;
+  readonly tIns: number | undefined;
+  readonly rIns: number | undefined;
+  readonly bIns: number | undefined;
+  readonly vert: VerticalText | undefined;
+  readonly wrap: TextWrap | undefined;
+  readonly vertOverflow: VertOverflow | undefined;
+  readonly horzOverflow: HorzOverflow | undefined;
+  readonly rot: number | undefined;
+  readonly upright: boolean | undefined;
+  readonly numCol: number | undefined;
+  readonly spcCol: number | undefined;
+  readonly rtlCol: boolean | undefined;
+  readonly spcFirstLastPara: boolean | undefined;
+  readonly compatLnSpc: boolean | undefined;
+  readonly fromWordArt: boolean | undefined;
+  readonly forceAA: boolean | undefined;
+  readonly autofit: Autofit | undefined;
+  readonly node: XElement;
+}
+/** `p:txBody` / `a:txBody`. */
+interface TextBody {
+  readonly bodyPr: BodyProps | undefined;
+  readonly lstStyle: ListStyle | undefined;
+  readonly paragraphs: readonly Paragraph[];
+  readonly node: XElement;
+}
+/**
+ * The bucket of `p:txStyles` a shape reads, or `null` for one that reads none.
+ *
+ * `other` is in the union because the element exists, not because anything
+ * reaches it - see the module comment.
+ */
+type TextStyleBucket = 'title' | 'body' | 'other';
+/** `p:txStyles` on a master. */
+interface TextStyles {
+  readonly title: ListStyle | undefined;
+  readonly body: ListStyle | undefined;
+  readonly other: ListStyle | undefined;
+  readonly node: XElement;
+}
+//#endregion
+//#region src/types.d.ts
+/** `a:off` and `a:ext` together, in EMU, plus the three transform attributes. */
+interface Xfrm {
+  readonly x: number;
+  readonly y: number;
+  readonly cx: number;
+  readonly cy: number;
+  /** `@rot`, sixtieths of a degree. Zero when the attribute was absent. */
+  readonly rot: number;
+  readonly flipH: boolean;
+  readonly flipV: boolean;
+  /** `a:chOff`/`a:chExt`, present only on a group's `a:xfrm`. */
+  readonly child: {
+    readonly x: number;
+    readonly y: number;
+    readonly cx: number;
+    readonly cy: number;
+  } | null;
+}
+/**
+ * `ST_PlaceholderType`. All nineteen, as written.
+ *
+ * Not all nineteen are legal everywhere. A slide **master** accepts only
+ * `title`, `body`, `dt`, `ftr`, `sldNum` and `hdr`: a master carrying
+ * `ctrTitle`, `subTitle`, `obj` or `pic` is repaired on open, measured in 2.9.
+ * That is not a curiosity - it is the reason the layout-to-master hop has to
+ * fold `ctrTitle` into `title` and every content type into `body`, because
+ * otherwise the stock "Title and Content" layout could inherit nothing from the
+ * stock master.
+ */
+type PlaceholderType = 'title' | 'body' | 'ctrTitle' | 'subTitle' | 'obj' | 'chart' | 'tbl' | 'clipArt' | 'dgm' | 'media' | 'sldImg' | 'pic' | 'sldNum' | 'hdr' | 'ftr' | 'dt';
+declare const PLACEHOLDER_TYPES: readonly PlaceholderType[];
+/** The six a slide master may carry. Measured; see `PlaceholderType`. */
+declare const MASTER_PLACEHOLDER_TYPES: readonly PlaceholderType[];
+/** `@sz`, a sizing hint. Recorded, and not part of matching - measured. */
+type PlaceholderSize = 'full' | 'half' | 'quarter';
+interface Placeholder {
+  /**
+   * `@type` as written, or `null` when the attribute was absent.
+   *
+   * `null` is kept rather than defaulted, because "the file said `obj`" and
+   * "the file said nothing" are different facts and only the second one is safe
+   * to rewrite. `normalizePlaceholder` supplies the default when a comparison
+   * needs one.
+   */
+  readonly type: PlaceholderType | null;
+  /** `@idx` as written, or `null` when absent. Defaults to 0 when compared. */
+  readonly idx: number | null;
+  readonly size: PlaceholderSize | null;
+  /** `@orient`. Recorded, and not part of matching. */
+  readonly orient: 'horz' | 'vert' | null;
+  readonly hasCustomPrompt: boolean;
+}
+/** A placeholder with its defaults supplied: what the matcher compares. */
+interface NormalPlaceholder {
+  readonly type: PlaceholderType;
+  readonly idx: number;
+}
+/** One of the six things a `p:spTree` may contain. */
+type ShapeKind = 'sp' | 'pic' | 'grpSp' | 'graphicFrame' | 'cxnSp' | 'contentPart';
+/** `a:lnRef`, `a:fillRef` and `a:effectRef`: an index into the style matrix. */
+interface StyleRef {
+  /**
+   * `@idx`. Zero means none; 1..999 index the main list; 1001 and up index the
+   * background list, offset by 1000. Measured on both `a:fillRef` and
+   * `p:bgRef`, which turn out to be the same rule over the same six entries.
+   */
+  readonly idx: number;
+  /** The colour `phClr` takes inside the entry this reference names. */
+  readonly color: Color | null;
+}
+/** `a:fontRef`. `@idx` is a collection name, never a number. */
+interface FontRef {
+  readonly idx: 'major' | 'minor' | 'none';
+  readonly color: Color | null;
+}
+/** `p:style`: four references into the theme's `a:fmtScheme` and `a:fontScheme`. */
+interface ShapeStyle {
+  readonly lnRef: StyleRef;
+  readonly fillRef: StyleRef;
+  readonly effectRef: StyleRef;
+  readonly fontRef: FontRef;
+}
+/**
+ * A shape, exactly as its part wrote it.
+ *
+ * Everything optional here is optional *in the file*, and the resolver is the
+ * only thing entitled to fill any of it in.
+ */
+interface Shape {
+  readonly kind: ShapeKind;
+  /** `p:cNvPr/@id`. Unique within a part, and may repeat across parts. */
+  readonly cNvPrId: number;
+  readonly name: string;
+  /** `p:cNvPr/@descr`, the alt text. */
+  readonly descr: string | null;
+  readonly hidden: boolean;
+  readonly placeholder: Placeholder | null;
+  readonly xfrm: Xfrm | undefined;
+  readonly fill: Fill | undefined;
+  readonly line: Line | undefined;
+  readonly effects: readonly Effect[] | undefined;
+  readonly style: ShapeStyle | undefined;
+  /** `a:prstGeom/@prst`, or `null` for a `custGeom` or no geometry at all. */
+  readonly prstGeom: string | undefined;
+  /**
+   * `a:prstGeom` or `a:custGeom`, parsed far enough to draw.
+   *
+   * `undefined` when the shape declares neither, which is the ordinary state of
+   * a slide placeholder: it inherits its outline from its layout exactly as it
+   * inherits its rectangle, and `resolve` is what asks.
+   */
+  readonly geometry: ShapeGeometry | undefined;
+  /**
+   * `p:txBody`, when the shape has one.
+   *
+   * Present on every `p:sp` PowerPoint writes, including the ones with no text
+   * in them, and absent from a `p:pic` or a `p:graphicFrame`. Its `a:lstStyle`
+   * is one level of the text cascade; the paragraphs are the text itself.
+   */
+  readonly text: TextBody | undefined;
+  /** Children, for a `grpSp`. Empty for everything else. */
+  readonly children: readonly Shape[];
+  /** The element this was read from. Edits go here, never to the fields above. */
+  readonly node: XElement;
+}
+/**
+ * `p:bg`, which is one of two quite different things.
+ *
+ * `p:bgPr` states a fill. `p:bgRef` names an entry of the theme's style matrix
+ * and the colour to invoke it with - the same mechanism as `a:fillRef` on a
+ * shape, over the same table, with the same 1000-offset. Both were measured
+ * against the same six theme entries in 2.9 and agreed on all six.
+ */
+type Background = {
+  readonly kind: 'fill';
+  readonly fill: Fill;
+  readonly effects: readonly Effect[] | undefined;
+} | {
+  readonly kind: 'ref';
+  readonly ref: StyleRef;
+};
+/** `a:fmtScheme`: four lists of style entries, held as the elements they were. */
+interface FormatScheme {
+  readonly name: string | null;
+  /** `a:fillStyleLst`. Each entry is a whole `EG_FillProperties` element. */
+  readonly fillStyles: readonly Fill[];
+  /** `a:lnStyleLst`. Each entry is a whole `a:ln`. */
+  readonly lineStyles: readonly Line[];
+  /** `a:effectStyleLst`. Each entry's `a:effectLst`, flattened. */
+  readonly effectStyles: readonly (readonly Effect[])[];
+  /** `a:bgFillStyleLst`, which `@idx` 1001 and up reach. */
+  readonly bgFillStyles: readonly Fill[];
+}
+/**
+ * `a:fontScheme`: the two collections `+mj-` and `+mn-` name.
+ *
+ * Three scripts each, because `a:rPr` has four typeface slots and three of them
+ * take a theme reference - `+mn-ea` on an `a:ea` is how a CJK run follows the
+ * theme. The `a:font` script-tag list under each collection is 3.7's business
+ * and is not modelled here.
+ */
+interface FontCollection {
+  /** `a:latin/@typeface`. An empty string means the theme states none. */
+  readonly latin: string | null;
+  readonly ea: string | null;
+  readonly cs: string | null;
+}
+interface FontScheme {
+  readonly name: string | null;
+  readonly major: FontCollection;
+  readonly minor: FontCollection;
+}
+interface Theme {
+  readonly partName: string;
+  readonly name: string | null;
+  readonly scheme: ClrScheme;
+  readonly fonts: FontScheme;
+  readonly format: FormatScheme | null;
+  readonly node: XElement;
+}
+type SheetKind = 'slide' | 'layout' | 'master';
+/**
+ * `p:clrMapOvr`, which has exactly two forms and one surprise.
+ *
+ * `a:masterClrMapping` means "use the map already in force". The surprise,
+ * measured in 2.9, is what "already in force" means for a slide: it is the
+ * **layout's** map, not the master's. A layout carrying an
+ * `a:overrideClrMapping` changes the colours of every slide bound to it that
+ * says `masterClrMapping`, and a slide's own override beats its layout's. The
+ * element's name says master and it means parent.
+ */
+type ColorMapOverride = {
+  readonly kind: 'inherit';
+} | {
+  readonly kind: 'override';
+  readonly map: ClrMap;
+};
+/**
+ * A slide, a layout or a master, with its parent already resolved.
+ *
+ * The parent link comes from **this part's own `.rels`** and from nowhere else.
+ * Not from `p:sldLayoutIdLst`, not from `p:sldMasterIdLst`, and not from the
+ * part's number in its folder: a two-master deck saved by PowerPoint numbers its
+ * layouts `slideLayout1..22` in one flat folder, and which master owns which is
+ * recorded only in the masters' relationship parts. The list elements exist to
+ * give each sheet an id and an order in the UI, not to bind anything.
+ */
+interface Sheet {
+  readonly kind: SheetKind;
+  readonly partName: string;
+  /** `p:cSld/@name`. */
+  readonly name: string | null;
+  /** `p:sldLayout/@type`, one of `ST_SlideLayoutType`. Layouts only. */
+  readonly layoutType: string | null;
+  /** `p:sldLayout/@matchingName`. Layouts only, and only when written. */
+  readonly matchingName: string | null;
+  readonly shapes: readonly Shape[];
+  readonly background: Background | undefined;
+  /** `p:clrMap`, on a master. `undefined` everywhere else. */
+  readonly clrMap: ClrMap | undefined;
+  /**
+   * `p:txStyles`, on a master. `undefined` everywhere else, and meaningfully so.
+   *
+   * A master that declares none does not get a partial one: PowerPoint
+   * substitutes its whole built-in set, measured in 3.1. So the difference
+   * between `undefined` and a `p:txStyles` whose buckets say nothing is the
+   * difference between a 28-point body placeholder and an 18-point one.
+   */
+  readonly txStyles: TextStyles | undefined;
+  /** `p:clrMapOvr`, on a layout or a slide. */
+  readonly clrMapOvr: ColorMapOverride | undefined;
+  /** `@showMasterSp`, defaulting to true. Slides and layouts. */
+  readonly showMasterShapes: boolean;
+  /** The layout of a slide, the master of a layout, `null` for a master and for
+   *  a sheet whose binding is missing - which PowerPoint repairs rather than
+   *  refuses, so it has to be representable. */
+  readonly parent: Sheet | null;
+  /** The theme, on a master. Every other sheet reaches it through `parent`. */
+  readonly theme: Theme | null;
+  readonly node: XElement;
+}
+/**
+ * Where a resolved value came from.
+ *
+ * 2.9 declared this union in advance, guessing at the members the text cascade
+ * would need. 3.1 measured them, and the guess was wrong in one place:
+ * `themeObjDefaults` is gone, because `a:objectDefaults/a:spDef/a:lstStyle` is
+ * not a source. A package declaring a size there and nowhere else resolves to
+ * the built-in default, so the member named a level that never fires - see
+ * `corpus/ground-truth/text-cascade.json`.
+ */
+type Origin =
+/** The run's own `a:rPr`. */
+'run' |
+/** The paragraph's `a:pPr`, or its `a:defRPr`. */
+'paragraph' |
+/** The shape itself: its `p:spPr`, or its own `a:lstStyle`. */
+'shape' | 'layoutPh' | 'masterPh' |
+/** The master's `p:txStyles`, in the bucket the chain's last type selects. */
+'txStyles' |
+/** `p:defaultTextStyle`, which only a shape with no bucket reaches. */
+'defaultTextStyle' |
+/** PowerPoint's own text styles, substituted for a master that declares none. */
+'builtin' | 'theme' | 'schemaDefault';
+/**
+ * A value, where it came from, and whether the thing that owns it said so.
+ *
+ * `explicit` is not the same as `origin === 'shape'`: a layout placeholder that
+ * declares a fill is explicit *about that fill*, and the slide that inherits it
+ * is not. The inspector's hollow-versus-filled dot is exactly this bit.
+ */
+interface Resolved<T> {
+  readonly value: T;
+  readonly origin: Origin;
+  readonly explicit: boolean;
+  /** The sheet the value was found on, when one was involved. */
+  readonly sheet: Sheet | null;
+  /** The shape the value was found on, when one was involved. */
+  readonly shape: Shape | null;
+}
+//#endregion
+//#region src/parse/paint.d.ts
+/** One of the six `EG_ColorChoice` members. */
+declare function parseColorElement(element: XElement): Color;
+/** The first colour child of a wrapper such as `a:solidFill` or `a:fillRef`. */
+declare function parseColorChild(parent: XElement | undefined): Color | null;
+/** One member of `EG_FillProperties`. */
+declare function parseFillElement(element: XElement, partName: string): Fill;
+/** The fill a container declares, or `undefined` when it declares none. */
+declare function parseFill(parent: XElement, partName: string): Fill | undefined;
+/** `a:ln`, lazily: every field is `null` when the attribute was absent. */
+declare function parseLineElement(element: XElement, partName: string): Line;
+declare function parseLine(parent: XElement, partName: string): Line | undefined;
+/**
+ * `a:effectLst`, in the order the file wrote it.
+ *
+ * Which is not the order it is painted in: 2.8 measured a glow painting *over*
+ * an outer shadow, the reverse of the schema's sequence. `effectFilter` in
+ * `paint` owns that, and this owns only the reading.
+ *
+ * `a:effectDag` is not modelled, so the shape is re-emitted byte for byte
+ * rather than approximated. PowerPoint writes none but does render one:
+ * measured on `a04-effects-03`, where it composites a glow over the fill.
+ */
+declare function parseEffects(parent: XElement): readonly Effect[] | undefined;
+//#endregion
+//#region src/parse/sheet.d.ts
+/**
+ * `p:clrMap` or `a:overrideClrMapping`: all twelve attributes, every time.
+ *
+ * Eleven is a repair prompt, so a map that is missing one is a broken file
+ * rather than a partial opinion, and there is nothing sensible to default the
+ * missing one to.
+ */
+declare function parseClrMap(element: XElement, partName: string): ClrMap;
+declare function parseTheme(root: XElement, partName: string): Theme;
+/**
+ * One part into one sheet. The parent and the theme are filled in by
+ * `document.ts`, which is the only thing that can follow a relationship.
+ */
+declare function parseSheet(root: XElement, partName: string): Omit<Sheet, 'parent' | 'theme'>;
+//#endregion
+//#region src/resolve/placeholder.d.ts
+/**
+ * The type of a `p:ph` that has none.
+ *
+ * `obj`, measured: a bare `<p:ph/>` on a slide reads back through PowerPoint's
+ * object model as `ppPlaceholderObject`. ECMA's own default for the attribute
+ * is `body`, and the two behave identically at the first hop because that hop
+ * ignores the type - but they differ at the second, where `obj` folds to `body`
+ * and `body` is already there. They agree, and it is worth knowing why rather
+ * than by luck.
+ */
+declare const DEFAULT_PLACEHOLDER_TYPE: PlaceholderType;
+/** The `@idx` of a `p:ph` that has none. */
+declare const DEFAULT_PLACEHOLDER_IDX = 0;
+/** Supply the two defaults, so a comparison has something to compare. */
+declare function normalizePlaceholder(ph: Placeholder): NormalPlaceholder;
+/**
+ * The type a placeholder presents when it asks a master for its parent.
+ *
+ * `ctrTitle` becomes `title`; everything a master may not carry - `subTitle`,
+ * `obj`, `pic`, `chart`, `tbl`, `clipArt`, `dgm`, `media`, `sldImg` - becomes
+ * `body`. Measured on `pic`, `obj`, `subTitle` and `ctrTitle`; the rest follow
+ * because a master cannot hold them either and `body` is the only remaining
+ * content type.
+ */
+declare function masterPlaceholderType(type: PlaceholderType): PlaceholderType;
+/** Every placeholder in a sheet's top-level shape tree, in document order. */
+declare function placeholders(sheet: Sheet): readonly Shape[];
+/**
+ * Slide to layout: the first placeholder whose `@idx` agrees.
+ *
+ * "First" matters only for a layout that has two placeholders at one index,
+ * which PowerPoint accepts without repairing; the first in the shape tree is
+ * the one that wins.
+ */
+declare function matchInLayout(ph: Placeholder, layout: Sheet): Shape | null;
+/** Layout to master: the first placeholder of the folded type. */
+declare function matchInMaster(ph: Placeholder, master: Sheet): Shape | null;
+/** One link of the chain: a shape, the sheet it is on, and how it was reached. */
+interface ChainLink {
+  readonly shape: Shape;
+  readonly sheet: Sheet;
+  /** `shape` for the first link, then `layoutPh`, then `masterPh`. */
+  readonly origin: 'shape' | 'layoutPh' | 'masterPh';
+}
+/**
+ * The chain a shape inherits along, nearest first.
+ *
+ * One entry for a non-placeholder, and for a placeholder that matched nothing.
+ * Up to three for a slide placeholder that reached the master. Each hop asks
+ * with the placeholder of the sheet it is leaving, which is why the layout's
+ * `@type` and not the slide's decides the second hop.
+ */
+declare function inheritanceChain(shape: Shape, sheet: Sheet): readonly ChainLink[];
+/**
+ * A placeholder that reached no parent and states no geometry of its own.
+ *
+ * PowerPoint renders one at the origin with zero width and height - it does not
+ * refuse the file, does not drop the shape, and does not invent a rectangle.
+ * Measured on four probes: a title where the layout has none, a body at an index
+ * nobody has, and both against a layout with no placeholders at all.
+ */
+declare const ORPHAN_RECT: {
+  readonly x: 0;
+  readonly y: 0;
+  readonly cx: 0;
+  readonly cy: 0;
+};
+//#endregion
+//#region src/resolve/resolve.d.ts
+/**
+ * The first level of the chain that declared something.
+ *
+ * `pick` must return `undefined` for "this level did not say" and anything else
+ * for a value, including `null` - a shape may legitimately declare a `null`, and
+ * conflating that with silence is how an explicit `a:noFill` gets overwritten by
+ * an inherited colour.
+ */
+declare function resolve<T>(shape: Shape, sheet: Sheet, pick: (shape: Shape) => T | undefined): Resolved<T> | undefined;
+/**
+ * The rectangle a shape occupies, and which sheet stated it.
+ *
+ * The single most consequential call in the package. A slide placeholder that
+ * PowerPoint wrote has **no** `a:xfrm` - not when it was created, not when text
+ * was typed into it, only when the user moved or resized it, at which point the
+ * whole resolved rectangle is baked in at once. So an absent `xfrm` is the
+ * statement "still bound to my layout", and it is what Change Layout reads.
+ */
+declare function resolveXfrm(shape: Shape, sheet: Sheet): Resolved<Xfrm> | undefined;
+/** Every sheet from this one up to its master, nearest first. */
+declare function sheetChain(sheet: Sheet): readonly Sheet[];
+/** The master at the top of a sheet's chain, or `null` if the chain is broken. */
+declare function masterOf(sheet: Sheet): Sheet | null;
+/**
+ * The theme a sheet resolves against.
+ *
+ * The master's, reached through this sheet's own chain. **Not** the one
+ * `ppt/presentation.xml.rels` names: PowerPoint writes a `theme` relationship
+ * there too, it always points at `theme1.xml`, and on a two-master deck every
+ * slide on the second master would take the first master's palette. Measured -
+ * the two masters resolved `accent1` to two different colours, and each
+ * master's background used its own theme's `bgFillStyleLst`.
+ *
+ * A master must own its theme part outright: two masters pointing at the same
+ * one is repaired on open, so a shared theme is a broken file rather than an
+ * economy.
+ */
+declare function themeOf(sheet: Sheet): Theme | null;
+declare function schemeOf(sheet: Sheet): ClrScheme | undefined;
+/**
+ * The colour map in force on a sheet.
+ *
+ * `a:masterClrMapping` says "the map already in force", and the surprise is what
+ * that means: for a slide it is the **layout's** map, not the master's. Measured
+ * - a layout carrying an `a:overrideClrMapping` changed `accent1` on a slide
+ * that declared `masterClrMapping`, and a slide with an override of its own beat
+ * its layout's. The element is named for the sheet it usually ends at rather
+ * than for the one it asks.
+ */
+declare function colorMapOf(sheet: Sheet): ClrMap | undefined;
+/**
+ * Everything `resolveColor` needs, for a colour written on this sheet.
+ *
+ * `phClr` is supplied by whatever style invocation the colour sits inside, and
+ * there is nothing sensible to default it to: `style.ts` passes it in, and a
+ * `schemeClr val="phClr"` reached any other way throws rather than painting
+ * black.
+ */
+declare function colorContextOf(sheet: Sheet, phClr?: Rgba): ColorContext;
+//#endregion
+//#region src/style.d.ts
+/**
+ * The offset that separates the two style lists.
+ *
+ * `0` and `1000` mean *nothing at all*; `1..999` index the main list; `1001` and
+ * up index the background list. Measured on both `a:fillRef` and `p:bgRef`
+ * against a theme whose six entries paint six distinguishable colours - all six
+ * agreed between the two elements, and `idx="0"` and `idx="1000"` both painted
+ * nothing.
+ */
+declare const STYLE_MATRIX_OFFSET = 1000;
+/** Which of the two lists an index reaches, and where in it. */
+type StyleMatrixTarget = {
+  readonly list: 'none';
+} | {
+  readonly list: 'main';
+  readonly at: number;
+} | {
+  readonly list: 'background';
+  readonly at: number;
+};
+/**
+ * Where an index points, before anything is fetched.
+ *
+ * Out of range is not an error. A `fillRef idx="4"` against a three-entry list
+ * paints the third entry, and a `bgRef idx="9999"` paints the last background
+ * entry: PowerPoint clamps, opens the file without repairing it, and a renderer
+ * that throws here refuses a deck PowerPoint shows.
+ */
+declare function styleMatrixTarget(idx: number): StyleMatrixTarget;
+/** The fill a `fillRef`/`bgRef` index names, or `null` for none. */
+declare function styleMatrixFill(ref: StyleRef, theme: Theme): Fill | null;
+/**
+ * The line an `lnRef` index names, or `null` for none.
+ *
+ * `a:lnStyleLst` has no background counterpart, so an index above 1000 clamps
+ * into the same list rather than reaching a second one.
+ */
+declare function styleMatrixLine(ref: StyleRef, theme: Theme): Line | null;
+/** The effects an `effectRef` index names. Empty for none. */
+declare function styleMatrixEffects(ref: StyleRef, theme: Theme): readonly Effect[];
+/**
+ * The colour a style reference invokes its entry with.
+ *
+ * The reference's own colour child, resolved against the sheet - and it may
+ * carry transforms of its own. PowerPoint's shape-style gallery writes
+ * `<a:schemeClr val="accent1"><a:shade val="15000"/></a:schemeClr>` on seven of
+ * its forty-two entries, so `phClr` is a fully transformed colour and not a
+ * theme slot name.
+ */
+declare function phClrOf(ref: StyleRef, sheet: Sheet): Rgba | null;
+/** What a shape paints, and where each half of the answer came from. */
+interface ResolvedAppearance {
+  /** `null` means nothing is painted: no fill was declared and no style names one. */
+  readonly fill: Fill | null;
+  readonly fillOrigin: Origin | null;
+  /** The colour `phClr` resolves to inside `fill`, when it came from the theme. */
+  readonly fillPhClr: Rgba | null;
+  readonly line: Line | null;
+  readonly lineOrigin: Origin | null;
+  readonly linePhClr: Rgba | null;
+  readonly effects: readonly Effect[] | null;
+}
+/**
+ * What a shape paints, following both routes and in the right order.
+ *
+ * An explicit `spPr` fill beats the `fillRef`, and an explicit `a:noFill` beats
+ * it too - both measured. A shape with neither paints nothing rather than black.
+ *
+ * The two routes are searched independently: the `spPr` fill is looked for down
+ * the whole inheritance chain first, and only if no level declared one does the
+ * `p:style` - itself inherited down the same chain - get consulted.
+ */
+declare function resolveAppearance(shape: Shape, sheet: Sheet): ResolvedAppearance;
+/**
+ * A shape's fill as a single colour, when it is one.
+ *
+ * A convenience over `resolveAppearance` for the common case, and the shape the
+ * ground-truth fixture is in: PowerPoint's object model reports one RGB per
+ * shape, so this is what a measurement can be compared against.
+ */
+declare function resolveSolidFill(shape: Shape, sheet: Sheet): Rgba | null;
+/** Resolve any colour written on a sheet, with an optional `phClr` in scope. */
+declare function resolveOnSheet(color: Color, sheet: Sheet, phClr?: Rgba): Rgba;
+//#endregion
+//#region src/resolve/background.d.ts
+/** A background, with the sheet that declared it and how it was expressed. */
+interface ResolvedBackground {
+  readonly fill: Fill;
+  /** The sheet whose `p:bg` this is. */
+  readonly sheet: Sheet;
+  /** True when the sheet asked for it is the one that declared it. */
+  readonly explicit: boolean;
+  /** `bgPr` or `bgRef`, because they round-trip differently. */
+  readonly form: 'bgPr' | 'bgRef';
+  /** The colour `phClr` takes inside `fill`, for a `bgRef`. */
+  readonly phClr: Rgba | null;
+}
+/** Which sheet's `p:bg` applies, without unpacking it. */
+declare function backgroundSheet(sheet: Sheet): {
+  sheet: Sheet;
+  background: Background;
+} | null;
+/**
+ * The background of a slide, layout or master.
+ *
+ * `null` when no sheet in the chain declares one, which is a legal file: a deck
+ * whose master has no `p:bg` paints nothing behind its slides.
+ */
+declare function resolveBackground(sheet: Sheet): ResolvedBackground | null;
+/** The background as one colour, when it is a solid. `null` otherwise. */
+declare function resolveBackgroundColor(sheet: Sheet): Rgba | null;
+//#endregion
+//#region src/document.d.ts
+/** One thing wrong with the package that did not stop the load. */
+interface DocumentProblem {
+  readonly code: 'MODEL_NO_PARENT' | 'MODEL_NO_THEME' | 'MODEL_PART_MISSING' | 'MODEL_PART_KIND';
+  readonly partName: string;
+  readonly message: string;
+}
+/**
+ * A loaded presentation: its slides, in `p:sldIdLst` order, each with its chain.
+ *
+ * Nothing here is a class with behaviour. It is the result of a load, and every
+ * question about it is a free function in `resolve.ts`, `style.ts` or
+ * `background.ts` - so a caller can hold a `Sheet` from anywhere and still ask
+ * everything, and so the whole surface stays tree-shakable.
+ */
+interface Document {
+  /** The presentation part, for the parts of it 2.9 does not model. */
+  readonly presentation: XElement;
+  readonly presentationPartName: string;
+  /** In `p:sldIdLst` order, which *is* the deck's order. */
+  readonly slides: readonly Sheet[];
+  /** In `p:sldMasterIdLst` order. */
+  readonly masters: readonly Sheet[];
+  /** Every layout reachable from a master, in the order its master lists it. */
+  readonly layouts: readonly Sheet[];
+  readonly themes: readonly Theme[];
+  readonly problems: readonly DocumentProblem[];
+  /**
+   * `p:defaultTextStyle`, the terminus of the text cascade for every shape that
+   * reaches no `p:txStyles` bucket - which is every shape that is not a
+   * placeholder, and the `dt`, `ftr`, `sldNum` and `hdr` placeholders besides.
+   *
+   * It lives on the presentation part, so it belongs to the package rather than
+   * to any sheet, and `undefined` means the package declared none.
+   */
+  readonly defaultTextStyle: ListStyle | undefined;
+  /** Slide size in EMU, from `p:sldSz`. */
+  readonly slideSize: {
+    readonly cx: number;
+    readonly cy: number;
+  };
+  sheet(partName: string): Sheet | undefined;
+}
+declare function loadDocument(store: PartStore): Document;
+//#endregion
+//#region src/parse/text.d.ts
+/** `a:rPr`, `a:defRPr` or `a:endParaRPr` - one type under three names. */
+declare function parseRunProps(element: XElement, partName: string): RunProps;
+/** `a:pPr`, `a:defPPr` or any `a:lvlNpPr` - one type under eleven names. */
+declare function parseParaProps(element: XElement, partName: string): ParaProps;
+/**
+ * `a:lstStyle`, or a `p:txStyles` bucket, which is the same type unwrapped.
+ *
+ * The nine levels are independent: measured in 3.1, a layout placeholder
+ * declaring only `a:lvl2pPr` changes the second level and leaves the first and
+ * third to the master. So a level nobody declared stays `undefined` rather than
+ * falling back to level one, and the resolver asks per level.
+ */
+declare function parseListStyle(element: XElement, partName: string): ListStyle;
+/** `p:txStyles` on a master. */
+declare function parseTextStyles(element: XElement, partName: string): TextStyles;
+/** `p:defaultTextStyle` on `ppt/presentation.xml`, which is a `CT_TextListStyle`. */
+declare function parseDefaultTextStyle(presentation: XElement, partName: string): ListStyle | undefined;
+/** A `p:txBody` or an `a:txBody`. */
+declare function parseTextBody(element: XElement, partName: string): TextBody;
+/** The `p:txBody` of a shape, when it has one. */
+declare function parseTextBodyChild(parent: XElement, partName: string): TextBody | undefined;
+//#endregion
+//#region src/builtin-text-styles.d.ts
+/**
+ * PowerPoint's own `p:txStyles`, substituted when a master declares none.
+ *
+ * GENERATED by tools/ground-truth/text/cascade/write-tables.ts from
+ * corpus/ground-truth/text-cascade.json. Do not edit by hand.
+ *
+ * Measured, not transcribed. Nine paragraphs at `lvl="0"` through `lvl="8"` in a
+ * title placeholder, a body placeholder and a shape that is not a placeholder,
+ * in a package whose master carries no `p:txStyles` at all, read back through
+ * PowerPoint's own object model. The body ladder - 28, 24, 20 and then 18 for
+ * the rest - is not a number anything in the file declares, which is how the
+ * ladder experiment discovered there was a source below every source the plan
+ * names.
+ *
+ * A PowerPoint-authored master always writes `p:txStyles`, so this table only
+ * ever applies to a hand-written or damaged one. It exists because the
+ * alternative is a placeholder resolving to no size at all, and because a
+ * measured answer costs one deck.
+ *
+ * `bullet` says whether PowerPoint drew one, which is what 3.5 reproduces; the
+ * glyph and its font belong to that sub-phase and are in the fixture, not here.
+ */
+/** One level of a built-in list style. */
+interface BuiltinLevel {
+  /** Hundredths of a point, as `a:defRPr/@sz` holds it. */
+  readonly sz: number;
+  /** EMU, as `a:lvlNpPr/@marL` holds it. */
+  readonly marL: number;
+  /** EMU, as `a:lvlNpPr/@indent` holds it. Negative is a hanging indent. */
+  readonly indent: number;
+  readonly bullet: boolean;
+  /**
+   * The theme reference this level names, or `null` where it names none.
+   *
+   * A reference and not a face, because the built-in styles are the same
+   * whatever theme a package carries: `+mj-lt` measured as the theme's major
+   * face and `+mn-lt` as its minor.
+   */
+  readonly typeface: string | null;
+}
+/** The three buckets, nine levels each, level 1 first. */
+declare const BUILTIN_TEXT_STYLES: {
+  readonly title: readonly BuiltinLevel[];
+  readonly body: readonly BuiltinLevel[];
+  readonly other: readonly BuiltinLevel[];
+};
+/**
+ * What is left when every source is silent and the master *does* declare
+ * `p:txStyles`.
+ *
+ * Distinct from the table above, and measured separately: a body placeholder
+ * whose `p:bodyStyle/a:lvl1pPr` declares only a `marL` came back at
+ * 18 points rather than the built-in body style's
+ * 28, and with no indent rather than the built-in's
+ * hanging one. So the built-in styles are substituted wholesale for an absent
+ * `p:txStyles` and are not a per-property backstop underneath a present one.
+ *
+ * `marL` and `indent` are **0**, not the ECMA-376 schema defaults of 347663 and
+ * -342900. Materialising those at parse time gives every paragraph a
+ * 27-point hanging indent nothing asked for, and blocks the inherited value on
+ * top of it, because a default that has been written down cannot be told from a
+ * declaration.
+ *
+ * The typeface is the minor face on all 6 probes that reach a silent cascade.
+ */
+declare const TEXT_FLOOR: BuiltinLevel;
+//#endregion
+//#region src/resolve/text.d.ts
+/** Which `p:txStyles` bucket a placeholder type reads, or `null` for none. */
+declare function bucketOf(type: string): 'title' | 'body' | null;
+/**
+ * Everything the cascade needs that is not on the shape.
+ *
+ * `defaultTextStyle` comes from `ppt/presentation.xml` and is therefore a
+ * property of the package rather than of any sheet, which is why it is passed
+ * in rather than walked to. A caller that has a `Document` has it already;
+ * `undefined` means the package declared none, which is a state PowerPoint
+ * distinguishes and this must too.
+ */
+interface TextContext {
+  readonly sheet: Sheet;
+  readonly shape: Shape;
+  readonly defaultTextStyle: ListStyle | undefined;
+}
+/** One level of the walk: a list style, and what to call it if it answers. */
+interface Level {
+  readonly style: ListStyle | undefined;
+  readonly origin: Origin;
+  readonly sheet: Sheet | null;
+  readonly shape: Shape | null;
+}
+/**
+ * The list styles a shape reads, nearest first, ending at whichever terminus it
+ * reaches.
+ *
+ * Exported because it *is* the finding: a caller that wants to show the user
+ * where a value could have come from - the inspector's Overrides panel, layout
+ * compatibility scoring - needs the same list the resolver walks, not a second
+ * opinion about it.
+ */
+declare function textLevels(context: TextContext): readonly Level[];
+/**
+ * The values left when every level has been asked and none of them said.
+ *
+ * Two quite different things, and which applies turns on one question: does the
+ * master declare `p:txStyles` at all? If it does not, PowerPoint substitutes its
+ * whole built-in set, and a body placeholder is 28 points with a hanging bullet
+ * indent. If it does, there is no per-property backstop underneath it and what
+ * remains is the floor - 18 points, no margin, no indent. Measured as two
+ * separate probes precisely because the two are easy to conflate and differ on
+ * every partially-specified master.
+ */
+declare function floorOf(context: TextContext, level: number): BuiltinLevel;
+/**
+ * A paragraph property, from the paragraph's own `a:pPr` or up the walk.
+ *
+ * `pick` returns `undefined` for "this level did not say" and anything else for
+ * a value, including `null` - the same contract `resolve` uses, and for the same
+ * reason: a level may legitimately declare a `null`, and conflating that with
+ * silence is how an explicit value gets overwritten by an inherited one.
+ */
+declare function resolveParagraph<T>(context: TextContext, paragraph: Paragraph, pick: (props: ParaProps) => T | undefined): Resolved<T> | undefined;
+/**
+ * A run property, from the run's own `a:rPr` and then every `a:defRPr` above it.
+ *
+ * The paragraph's `a:pPr/a:defRPr` is one level, not a special case: it sits
+ * between the run and the shape's `a:lstStyle`, which the ladder pinned by
+ * declaring a different size at each and reading back which one won.
+ */
+declare function resolveRun<T>(context: TextContext, paragraph: Paragraph, run: TextContent | undefined, pick: (props: RunProps) => T | undefined): Resolved<T> | undefined;
+/**
+ * The font size of a run, in hundredths of a point, always.
+ *
+ * The only resolver here that cannot return `undefined`: text has to be drawn at
+ * some size, and the size when nothing declared one is measured rather than
+ * chosen. `origin` is `builtin` when the master declares no `p:txStyles` and
+ * `schemaDefault` when it does and the bucket said nothing - two different
+ * numbers on the same slide, and the field says which was used.
+ */
+declare function resolveSize(context: TextContext, paragraph: Paragraph, run: TextContent | undefined): Resolved<number>;
+/**
+ * The Latin typeface of a run, with any theme reference followed.
+ *
+ * The second resolver that cannot return `undefined`: a run has to be drawn in
+ * some face, and the face when nothing named one is measured rather than
+ * chosen - the theme's minor, on all six probes reaching a silent cascade.
+ */
+declare function resolveLatinTypeface(context: TextContext, paragraph: Paragraph, run: TextContent | undefined): Resolved<string>;
+/** `@marL` in EMU. Measured to be 0 when nothing declares it, not 347663. */
+declare function resolveMarginLeft(context: TextContext, paragraph: Paragraph): Resolved<number>;
+/** `@indent` in EMU. Measured to be 0 when nothing declares it, not -342900. */
+declare function resolveIndent(context: TextContext, paragraph: Paragraph): Resolved<number>;
+/**
+ * The bullet, merged the way T5 measured it: five slots, each on its own.
+ *
+ * The kind is one slot because the schema makes the four elements exclusive, and
+ * the three decorations are three more because PowerPoint merges them
+ * separately - a level declaring only `a:buFont` re-faces the character it
+ * inherits and keeps its size and colour. Measured on eleven cases twice over,
+ * once through a shape's own `a:lstStyle` and once through three hops of the
+ * master chain, and the two agree.
+ *
+ * Every one of these returns `undefined` when nothing in the chain declares the
+ * slot, which for the kind is the difference between "no bullet" and "nobody
+ * said" - `a:buNone` resolves to `'none'` and an empty chain to `undefined`.
+ * Nothing here supplies a default, because a paragraph with no bullet anywhere
+ * in its chain genuinely has none.
+ */
+declare function resolveBulletKind(context: TextContext, paragraph: Paragraph): Resolved<BulletKind> | undefined;
+/** `a:buChar/@char`, as written. The symbol mapping belongs to the renderer. */
+declare function resolveBulletChar(context: TextContext, paragraph: Paragraph): Resolved<string> | undefined;
+/** `a:buAutoNum`, type and start value together, since one is meaningless alone. */
+declare function resolveBulletAutoNum(context: TextContext, paragraph: Paragraph): Resolved<BulletAutoNum> | undefined;
+/** `a:buBlip/a:blip/@r:embed`, which the caller resolves against the part's rels. */
+declare function resolveBulletBlip(context: TextContext, paragraph: Paragraph): Resolved<string> | undefined;
+/**
+ * `a:buFont` or `a:buFontTx`.
+ *
+ * Worth knowing before using it: this is **inert for an autonumber**. PowerPoint
+ * draws a number in the first run's face whatever `a:buFont` says - measured on
+ * twenty probes, including one where `buFont` named Wingdings and the run named
+ * Courier New - and its own UI writes `buFont="+mj-lt"` on every list it
+ * numbers. The resolver still reports it, because the file says it and 1.3 has
+ * to write it back; the renderer is where it is ignored.
+ */
+declare function resolveBulletFont(context: TextContext, paragraph: Paragraph): Resolved<BulletFont> | undefined;
+/** `a:buSzPct`, `a:buSzPts` or `a:buSzTx`; a percentage is of the first run's size. */
+declare function resolveBulletSize(context: TextContext, paragraph: Paragraph): Resolved<BulletSize> | undefined;
+/** `a:buClr` or `a:buClrTx`. Unlike the font, this one *does* reach an autonumber. */
+declare function resolveBulletColor(context: TextContext, paragraph: Paragraph): Resolved<BulletColor> | undefined;
+//#endregion
+//#region src/resolve/body.d.ts
+/**
+ * The four insets in points, per attribute.
+ *
+ * Restated here rather than imported from `@pptx-studio/text`, which is a layer
+ * below and which this package does not depend on - the same posture
+ * `line-model.ts` takes towards `Spacing`.
+ */
+interface ResolvedInsets {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+/**
+ * One property of the text frame, from the shape's own `a:bodyPr` or above it.
+ *
+ * `pick` returns `undefined` for "this level did not say", the same contract the
+ * text cascade uses.
+ */
+declare function resolveBody<T>(shape: Shape, sheet: Sheet, pick: (props: BodyProps) => T | undefined): Resolved<T> | undefined;
+declare function resolveAnchor(shape: Shape, sheet: Sheet): Resolved<TextAnchor> | undefined;
+declare function resolveAnchorCtr(shape: Shape, sheet: Sheet): Resolved<boolean> | undefined;
+declare function resolveVertical(shape: Shape, sheet: Sheet): Resolved<VerticalText> | undefined;
+declare function resolveWrap(shape: Shape, sheet: Sheet): Resolved<TextWrap> | undefined;
+declare function resolveColumns(shape: Shape, sheet: Sheet): Resolved<number> | undefined;
+/**
+ * The four insets, in points, each falling back on its own.
+ *
+ * A frame stating only `lIns` still gets 3.6 above and below, so this resolves
+ * four times rather than once.
+ */
+declare function resolveInsets(shape: Shape, sheet: Sheet): ResolvedInsets;
+//#endregion
+//#region src/parse/body.d.ts
+/** Parse an `a:bodyPr`. Lengths stay in EMU and angles in 60000ths of a degree. */
+declare function parseBodyProps(element: XElement, partName: string): BodyProps;
+/** The `a:bodyPr` of a `p:txBody`, when it has one. */
+declare function parseBodyPropsChild(parent: XElement, partName: string): BodyProps | undefined;
+//#endregion
+//#region src/resolve/typeface.d.ts
+/** The four slots a `CT_TextCharacterProperties` can name. */
+type ScriptSlot = 'latin' | 'ea' | 'cs' | 'sym';
+/**
+ * The typeface a slot asks for, with any theme reference followed.
+ *
+ * `undefined` means the reference resolved to a collection entry the theme
+ * leaves empty, which is not the same as the theme naming nothing.
+ */
+declare function resolveTypeface(typeface: string, scheme: FontScheme): string | undefined;
+/** The same, for a whole `CT_TextFont`. */
+declare function resolveTypefaceOf(font: Typeface, scheme: FontScheme): string | undefined;
+/**
+ * Every distinct typeface a set of runs asks for, theme references followed.
+ *
+ * This is what `fontReport` is given: a report keyed on `+mn-lt` would name a
+ * token no user recognises and would collapse two themes into one row.
+ */
+declare function requestedTypefaces(fonts: Iterable<Typeface | undefined>, scheme: FontScheme): readonly string[];
+//#endregion
+export { BUILTIN_TEXT_STYLES, type Background, type BuiltinLevel, type BulletAutoNum, type BulletColor, type BulletFont, type BulletKind, type BulletSize, COLOR_TRANSFORM_OPS, type Caps, type ChainLink, type ColorMapOverride, DEFAULT_PLACEHOLDER_IDX, DEFAULT_PLACEHOLDER_TYPE, type Document, type DocumentProblem, type FontAlign, type FontCollection, type FontRef, type FontScheme, type FormatScheme, LEVELS, type ListStyle, MASTER_PLACEHOLDER_TYPES, MODEL_ERROR_CODES, ModelError, type ModelErrorCode, type NormalPlaceholder, ORPHAN_RECT, type Origin, PLACEHOLDER_TYPES, type ParaProps, type Paragraph, type Placeholder, type PlaceholderSize, type PlaceholderType, type Resolved, type ResolvedAppearance, type ResolvedBackground, type ResolvedInsets, type RunProps, STYLE_MATRIX_OFFSET, type ScriptSlot, type Shape, type ShapeGeometry, type ShapeKind, type ShapeStyle, type Sheet, type SheetKind, type Spacing, type Strike, type StyleMatrixTarget, type StyleRef, TEXT_FLOOR, type TextAlign, type TextAnchor, type TextBody, type TextBreak, type TextContent, type TextContext, type TextField, type TextRun, type TextStyleBucket, type TextStyles, type Theme, type ThemeFontRef, type Typeface, type Underline, type VerticalText, type Xfrm, backgroundSheet, bucketOf, colorContextOf, colorMapOf, floorOf, inheritanceChain, isModelError, loadDocument, masterOf, masterPlaceholderType, matchInLayout, matchInMaster, normalizePlaceholder, parseBodyProps, parseBodyPropsChild, parseClrMap, parseColorChild, parseColorElement, parseDefaultTextStyle, parseEffects, parseFill, parseFillElement, parseGeometry, parseLine, parseLineElement, parseListStyle, parseParaProps, parseRunProps, parseSheet, parseTextBody, parseTextBodyChild, parseTextStyles, parseTheme, phClrOf, placeholders, requestedTypefaces, resolve, resolveAnchor, resolveAnchorCtr, resolveAppearance, resolveBackground, resolveBackgroundColor, resolveBody, resolveBulletAutoNum, resolveBulletBlip, resolveBulletChar, resolveBulletColor, resolveBulletFont, resolveBulletKind, resolveBulletSize, resolveColumns, resolveIndent, resolveInsets, resolveLatinTypeface, resolveMarginLeft, resolveOnSheet, resolveParagraph, resolveRun, resolveSize, resolveSolidFill, resolveTypeface, resolveTypefaceOf, resolveVertical, resolveWrap, resolveXfrm, schemeOf, sheetChain, styleMatrixEffects, styleMatrixFill, styleMatrixLine, styleMatrixTarget, textLevels, themeFontRef, themeOf };
+//# sourceMappingURL=index.d.ts.map