pptx-ts 3.7.0 → 4.0.0

package/dist/{slide-ZqAdVvHV.d.ts → pres-C6qgOFAa.d.ts}

@@ -1,4 +1,252 @@
-import { _ as TextAnchor, f as SHAPE_NAME, g as TableStyle, h as SlideObjectType, i as CHART_NAME, l as PLACEHOLDER_TYPE, t as AlignH } from "./enums-CvRYniUA.js";
+import { c as PLACEHOLDER_TYPE, d as SHAPE_NAME, i as CHART_NAME, v as WRITE_OUTPUT_TYPE } from "./enums-BUKTUB6V.js";
+//#region src/ooxml/st-enums.d.ts
+/**
+ * `ST_` simple-type enumerations from ECMA-376, declared once as the single source of both the
+ * TypeScript union a caller is checked against and the runtime list a value is validated against.
+ *
+ * **The problem this solves.** Each of these used to exist twice: a hand-written string union in
+ * `src/types/` (what the compiler enforces) and a hand-written array in `src/gen/` or `src/read/`
+ * (what the validator checks at run time). Nothing tied the two together, so adding a member to
+ * one and not the other produced either a value TypeScript accepts and the validator drops, or a
+ * value the validator passes and the type rejects. Two of them had already diverged in *order*,
+ * which is harmless, but nothing would have caught a divergence in *content*.
+ *
+ * **The shape.** Every entry is a `readonly` tuple declared `as const`, with its union derived via
+ * `(typeof X)[number]`. Widening the tuple widens the union in the same edit — they cannot drift.
+ * This is the idiom `EXTRA_SHAPE_PRESETS` already used; this module brings the stragglers onto it,
+ * and holds a few closed schema lists that are not `ST_` types, such as `EMBEDDED_FONT_SLOTS`.
+ *
+ * **Why this module is neither `gen/` nor `read/`.** `src/types/` needs the unions for the public
+ * write API, `src/gen/` needs the tuples to vet a value before emitting it, and `src/read/` needs
+ * them to vet a value before writing it into a loaded part. It is a fact about the schema, so it
+ * belongs to none of the three.
+ *
+ * Values are listed in **schema declaration order**, which is the order the diagnostics print
+ * when they tell a caller what is legal.
+ *
+ * **The chart option bag reads its enumerations from here**: `BarDirection`, `BarGrouping`,
+ * `Bar3DShape`, `LegendPosition`, `DisplayBlanksAs`, `DataLabelPosition` and `LineDataSymbol`
+ * first, then the axis and error-bar ones. They were the half of this consolidation that went
+ * unfinished for a while. `src/types/chart.ts`
+ * hand-wrote four of those unions beside the option that takes them and typed the other three as
+ * bare `string`, so `barDir` carried no compile-time check at all, and `dataLabelPosition`'s
+ * hand-written union was missing `inBase` — a value the validator accepts on a stacked bar, so
+ * the two spellings had already diverged in content. Both are gone: for every option here, the
+ * type a caller is checked against and the tuple the validator checks are one declaration.
+ */
+/** `ST_TextAutonumberScheme` — the numbering an auto-numbered bullet counts in (`a:buAutoNum/@type`). */
+declare const TEXT_AUTONUM_SCHEMES: readonly ['alphaLcParenBoth', 'alphaUcParenBoth', 'alphaLcParenR', 'alphaUcParenR', 'alphaLcPeriod', 'alphaUcPeriod', 'arabicParenBoth', 'arabicParenR', 'arabicPeriod', 'arabicPlain', 'romanLcParenBoth', 'romanUcParenBoth', 'romanLcParenR', 'romanUcParenR', 'romanLcPeriod', 'romanUcPeriod', 'circleNumDbPlain', 'circleNumWdBlackPlain', 'circleNumWdWhitePlain', 'arabicDbPeriod', 'arabicDbPlain', 'ea1ChsPeriod', 'ea1ChsPlain', 'ea1ChtPeriod', 'ea1ChtPlain', 'ea1JpnChsDbPeriod', 'ea1JpnKorPlain', 'ea1JpnKorPeriod', 'arabic1Minus', 'arabic2Minus', 'hebrew2Minus', 'thaiAlphaPeriod', 'thaiAlphaParenR', 'thaiAlphaParenBoth', 'thaiNumPeriod', 'thaiNumParenR', 'thaiNumParenBoth', 'hindiAlphaPeriod', 'hindiNumPeriod', 'hindiNumParenR', 'hindiAlpha1Period'];
+/** `ST_TextStrikeType` — a run's strikethrough (`a:rPr/@strike`). */
+declare const TEXT_STRIKE_TYPES: readonly ['noStrike', 'sngStrike', 'dblStrike'];
+/** `ST_TextCapsType` — a run's capitalization (`a:rPr/@cap`). */
+declare const TEXT_CAPS_TYPES: readonly ['none', 'small', 'all'];
+/** `ST_TextUnderlineType` — a run's underline (`a:rPr/@u`). */
+declare const TEXT_UNDERLINE_TYPES: readonly ['none', 'words', 'sng', 'dbl', 'heavy', 'dotted', 'dottedHeavy', 'dash', 'dashHeavy', 'dashLong', 'dashLongHeavy', 'dotDash', 'dotDashHeavy', 'dotDotDash', 'dotDotDashHeavy', 'wavy', 'wavyHeavy', 'wavyDbl'];
+/** `ST_TextTabAlignType` — a tab stop's alignment (`a:tab/@algn`). */
+declare const TEXT_TAB_ALIGN_TYPES: readonly ['l', 'ctr', 'r', 'dec'];
+/**
+ * The base slide transitions: the `p:` type elements of `CT_SlideTransition`'s choice, in its
+ * declaration order. The writer emits the type as `<p:TYPE/>`, so this is also the list a type is
+ * checked against before it becomes an element name, and the list the script converter uses to
+ * decide which read transitions the write API can express. PowerPoint's modern transitions live in
+ * other namespaces and are not here.
+ */
+declare const TRANSITION_TYPES: readonly ['blinds', 'checker', 'circle', 'dissolve', 'comb', 'cover', 'cut', 'diamond', 'fade', 'newsflash', 'plus', 'pull', 'push', 'random', 'randomBar', 'split', 'strips', 'wedge', 'wheel', 'wipe', 'zoom'];
+/**
+ * `ST_BevelPresetType` — the bevel profile applied to a 3-D edge.
+ * @see ECMA-376 Part 1 §20.1.10.9
+ */
+declare const BEVEL_PRESETS: readonly ['relaxedInset', 'circle', 'slope', 'cross', 'angle', 'softRound', 'convex', 'coolSlant', 'divot', 'riblet', 'hardEdge', 'artDeco'];
+type BevelPresetType = (typeof BEVEL_PRESETS)[number];
+/**
+ * `ST_PresetMaterialType` — how a 3-D surface responds to light.
+ * @see ECMA-376 Part 1 §20.1.10.50
+ */
+declare const PRESET_MATERIALS: readonly ['legacyMatte', 'legacyPlastic', 'legacyMetal', 'legacyWireframe', 'matte', 'plastic', 'metal', 'warmMatte', 'translucentPowder', 'powder', 'dkEdge', 'softEdge', 'clear', 'flat', 'softmetal'];
+type PresetMaterialType = (typeof PRESET_MATERIALS)[number];
+/**
+ * `ST_LightRigType` — the preset lighting scene.
+ * @see ECMA-376 Part 1 §20.1.10.35
+ */
+declare const LIGHT_RIGS: readonly ['legacyFlat1', 'legacyFlat2', 'legacyFlat3', 'legacyFlat4', 'legacyNormal1', 'legacyNormal2', 'legacyNormal3', 'legacyNormal4', 'legacyHarsh1', 'legacyHarsh2', 'legacyHarsh3', 'legacyHarsh4', 'threePt', 'balanced', 'soft', 'harsh', 'flood', 'contrasting', 'morning', 'sunrise', 'sunset', 'chilly', 'freezing', 'flat', 'twoPt', 'glow', 'brightRoom'];
+type LightRigType = (typeof LIGHT_RIGS)[number];
+/**
+ * `ST_LightRigDirection` — where the light rig sits relative to the scene.
+ * @see ECMA-376 Part 1 §20.1.10.33
+ */
+declare const LIGHT_RIG_DIRECTIONS: readonly ['tl', 't', 'tr', 'l', 'r', 'bl', 'b', 'br'];
+type LightRigDirection = (typeof LIGHT_RIG_DIRECTIONS)[number];
+/**
+ * `ST_TextHorzOverflowType` — `a:bodyPr/@horzOverflow` and `a:tcPr/@horzOverflow`.
+ * @see ECMA-376 Part 1 §20.1.10.68
+ */
+declare const TEXT_HORZ_OVERFLOW: readonly ['clip', 'overflow'];
+type TextHorzOverflowType = (typeof TEXT_HORZ_OVERFLOW)[number];
+/**
+ * `ST_TextVerticalType` — `a:bodyPr/@vert` and `a:tcPr/@vert`.
+ * @see ECMA-376 Part 1 §20.1.10.83
+ */
+declare const TEXT_VERTICAL: readonly ['horz', 'vert', 'vert270', 'wordArtVert', 'eaVert', 'mongolianVert', 'wordArtVertRtl'];
+type TextVerticalType = (typeof TEXT_VERTICAL)[number];
+/**
+ * `ST_LineEndType` — the arrowhead at either end of a stroke (`a:headEnd/@type`,
+ * `a:tailEnd/@type`).
+ * @see ECMA-376 Part 1 §20.1.10.33
+ */
+declare const LINE_END_TYPES: readonly ['none', 'triangle', 'stealth', 'diamond', 'oval', 'arrow'];
+/**
+ * The four face slots of `CT_EmbeddedFontListEntry`, in schema child order (`p:font` first, then
+ * these). Not an `ST_` type, but a closed, ordered set the schema declares, like
+ * {@link THEME_COLOR_SLOTS}. The read and write sides iterate it so their emitters agree on
+ * element order, and `sequence.ts` derives `EMBEDDED_FONT_ENTRY_SEQUENCE` from it, so the order
+ * the serializer writes and the order the insertion points are computed from are one fact.
+ * `embedded-fonts.ts` re-exports it.
+ */
+declare const EMBEDDED_FONT_SLOTS: readonly ['regular', 'bold', 'italic', 'boldItalic'];
+type LineEndType = (typeof LINE_END_TYPES)[number];
+/**
+ * `ST_TextShapeType` — the preset path text is bent along (`a:prstTxWarp/@prst`), which
+ * PowerPoint calls WordArt.
+ *
+ * `textNoShape` is the identity member: it is legal, and it warps nothing. The library does not
+ * narrow this set — every member is a shape PowerPoint draws.
+ * @see ECMA-376 Part 1 §20.1.10.76
+ */
+declare const TEXT_SHAPE_TYPES: readonly ['textNoShape', 'textPlain', 'textStop', 'textTriangle', 'textTriangleInverted', 'textChevron', 'textChevronInverted', 'textRingInside', 'textRingOutside', 'textArchUp', 'textArchDown', 'textCircle', 'textButton', 'textArchUpPour', 'textArchDownPour', 'textCirclePour', 'textButtonPour', 'textCurveUp', 'textCurveDown', 'textCanUp', 'textCanDown', 'textWave1', 'textWave2', 'textDoubleWave1', 'textWave4', 'textInflate', 'textDeflate', 'textInflateBottom', 'textDeflateBottom', 'textInflateTop', 'textDeflateTop', 'textDeflateInflate', 'textDeflateInflateDeflate', 'textFadeRight', 'textFadeLeft', 'textFadeUp', 'textFadeDown', 'textSlantUp', 'textSlantDown', 'textCascadeUp', 'textCascadeDown'];
+type TextShapeType = (typeof TEXT_SHAPE_TYPES)[number];
+/**
+ * `ST_PresetLineDashVal` — the dash pattern of a line or border (`a:prstDash/@val`).
+ *
+ * The `sys*` members are the "system" dashes whose exact dot/gap ratio the renderer picks; the
+ * rest are defined by the spec. Both `BorderProps.dashType` and `ShapeLineProps.dashType` accept
+ * this whole set, so a caller who knows one knows the other.
+ * @see ECMA-376 Part 1 §20.1.10.49
+ */
+declare const PRESET_LINE_DASHES: readonly ['solid', 'dot', 'dash', 'lgDash', 'dashDot', 'lgDashDot', 'lgDashDotDot', 'sysDash', 'sysDot', 'sysDashDot', 'sysDashDotDot'];
+type PresetLineDashVal = (typeof PRESET_LINE_DASHES)[number];
+/**
+ * `ST_BarDir` — whether a bar/column plot runs horizontally or vertically (`c:barDir/@val`).
+ * @see ECMA-376 Part 1 §21.2.3.3
+ */
+declare const BAR_DIRECTIONS: readonly ['bar', 'col'];
+type BarDirection = (typeof BAR_DIRECTIONS)[number];
+/**
+ * `ST_BarGrouping` — how a bar/column plot stacks its series (`c:grouping/@val` inside
+ * `c:barChart`/`c:bar3DChart`).
+ * @see ECMA-376 Part 1 §21.2.3.4
+ */
+declare const BAR_GROUPINGS: readonly ['percentStacked', 'clustered', 'standard', 'stacked'];
+type BarGrouping = (typeof BAR_GROUPINGS)[number];
+/**
+ * `ST_Shape` — the solid a 3-D bar is drawn as (`c:shape/@val`).
+ * @see ECMA-376 Part 1 §21.2.3.35
+ */
+declare const BAR_3D_SHAPES: readonly ['cone', 'coneToMax', 'box', 'cylinder', 'pyramid', 'pyramidToMax'];
+type Bar3DShape = (typeof BAR_3D_SHAPES)[number];
+/**
+ * `ST_RadarStyle` — how a radar plot is drawn (`c:radarStyle/@val`).
+ * @see ECMA-376 Part 1 §21.2.3.33
+ */
+declare const RADAR_STYLES: readonly ['standard', 'marker', 'filled'];
+type RadarStyle = (typeof RADAR_STYLES)[number];
+/**
+ * This library's own names for two of the three radar styles, mapped to the wire spelling each
+ * one means. They are the PowerPoint UI's words ("Radar", "Radar with Markers"), which is why
+ * they were chosen; `filled` needed no rename and is already the schema's own spelling, which is
+ * what made the other two read as typos rather than as a second vocabulary.
+ *
+ * Both spellings are accepted on the public option and normalized to the wire one at definition
+ * time. Before that, `radarStyle: 'marker'` — the schema's word, and the obvious guess for anyone
+ * reading a chart part — failed the enum check and silently fell back to `standard`, so a caller
+ * asking for markers got a plain radar.
+ */
+declare const RADAR_STYLE_ALIASES: {
+  readonly radar: 'standard';
+  readonly markers: 'marker';
+};
+type RadarStyleAlias = keyof typeof RADAR_STYLE_ALIASES;
+/**
+ * `ST_LegendPos` — where the legend sits relative to the plot area (`c:legendPos/@val`).
+ * @see ECMA-376 Part 1 §21.2.3.24
+ */
+declare const LEGEND_POSITIONS: readonly ['b', 'tr', 'l', 'r', 't'];
+type LegendPosition = (typeof LEGEND_POSITIONS)[number];
+/**
+ * `ST_DispBlanksAs` — what a plot draws where a value is missing (`c:dispBlanksAs/@val`).
+ * @see ECMA-376 Part 1 §21.2.3.10
+ */
+declare const DISPLAY_BLANKS_AS: readonly ['span', 'gap', 'zero'];
+type DisplayBlanksAs = (typeof DISPLAY_BLANKS_AS)[number];
+/**
+ * `ST_DLblPos` — where a data label sits relative to its point (`c:dLblPos/@val`).
+ *
+ * The whole set is legal on the attribute, but only a subset of it is legal *per plot type* —
+ * PowerPoint offers a pie chart `bestFit`/`ctr`/`inEnd`/`outEnd` and nothing else. Those subsets
+ * are a fact about the chart types rather than about the attribute, so they live beside the
+ * chart definer that applies them; this is the value space they are drawn from.
+ * @see ECMA-376 Part 1 §21.2.3.13
+ */
+declare const DATA_LABEL_POSITIONS: readonly ['bestFit', 'b', 'ctr', 'inBase', 'inEnd', 'l', 'outEnd', 'r', 't'];
+type DataLabelPosition = (typeof DATA_LABEL_POSITIONS)[number];
+/**
+ * `ST_MarkerStyle`, **narrowed** to what the library authors (`c:symbol/@val`).
+ *
+ * The schema also has `plus`, `star`, `x`, `picture` and `auto`. Neither PowerPoint 2013 nor
+ * PowerPoint Online draws the first three, `picture` needs a `c:spPr` blip this API has no
+ * spelling for, and `auto` is what leaving the option off already means — so the accepted set is
+ * deliberately smaller than the type. Widen it only with evidence that the member renders.
+ * @see ECMA-376 Part 1 §21.2.3.27
+ */
+declare const LINE_DATA_SYMBOLS: readonly ['circle', 'dash', 'diamond', 'dot', 'none', 'square', 'triangle'];
+type LineDataSymbol = (typeof LINE_DATA_SYMBOLS)[number];
+/** `ST_TickLblPos` — where an axis draws its tick labels (`c:tickLblPos/@val`). */
+declare const TICK_LABEL_POSITIONS: readonly ['high', 'low', 'nextTo', 'none'];
+type TickLabelPosition = (typeof TICK_LABEL_POSITIONS)[number];
+/** `ST_Orientation` — which way an axis runs (`c:orientation/@val`). */
+declare const AXIS_ORIENTATIONS: readonly ['maxMin', 'minMax'];
+type AxisOrientation = (typeof AXIS_ORIENTATIONS)[number];
+/** `ST_TickMark` — an axis' major or minor tick marks (`c:majorTickMark/@val`, `c:minorTickMark/@val`). */
+declare const TICK_MARKS: readonly ['cross', 'in', 'none', 'out'];
+type TickMark = (typeof TICK_MARKS)[number];
+/** `ST_CrossBetween` — whether a value axis crosses its category axis between or on categories (`c:crossBetween/@val`). */
+declare const CROSS_BETWEEN: readonly ['between', 'midCat'];
+type CrossBetween = (typeof CROSS_BETWEEN)[number];
+/** `ST_BuiltInUnit` — the unit a value axis displays its labels in (`c:builtInUnit/@val`). */
+declare const BUILT_IN_UNITS: readonly ['hundreds', 'thousands', 'tenThousands', 'hundredThousands', 'millions', 'tenMillions', 'hundredMillions', 'billions', 'trillions'];
+type BuiltInUnit = (typeof BUILT_IN_UNITS)[number];
+/** `ST_TimeUnit` — a date axis' base, major or minor time unit (`c:baseTimeUnit/@val` and its two siblings). */
+declare const TIME_UNITS: readonly ['days', 'months', 'years'];
+type TimeUnit = (typeof TIME_UNITS)[number];
+/** `ST_ErrDir` — the axis an error bar measures along (`c:errDir/@val`). */
+declare const ERROR_BAR_DIRECTIONS: readonly ['x', 'y'];
+type ErrorBarDirection = (typeof ERROR_BAR_DIRECTIONS)[number];
+/** `ST_ErrBarType` — which sides of a point draw an error bar (`c:errBarType/@val`). */
+declare const ERROR_BAR_TYPES: readonly ['both', 'minus', 'plus'];
+type ErrorBarType = (typeof ERROR_BAR_TYPES)[number];
+/** `ST_ErrValType` — how an error bar's amount is read (`c:errValType/@val`). */
+declare const ERROR_BAR_VALUE_TYPES: readonly ['cust', 'fixedVal', 'percentage', 'stdDev', 'stdErr'];
+type ErrorBarValueType = (typeof ERROR_BAR_VALUE_TYPES)[number];
+/**
+ * The twelve theme colour slots (`a:clrScheme` children) a `p:clrMap` token can point at.
+ *
+ * Not an `ST_` type — these are element names inside `a:CT_ColorScheme`, which the schema
+ * declares as a fixed sequence rather than an enumeration. The effect is the same: a closed,
+ * ordered set of twelve names, in the order the scheme declares them.
+ * @see ECMA-376 Part 1 §20.1.6.2
+ */
+declare const THEME_COLOR_SLOTS: readonly ['dk1', 'lt1', 'dk2', 'lt2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
+type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
+/**
+ * The twelve colour-map tokens (`p:clrMap` attributes), in schema attribute order.
+ *
+ * A slide's `schemeClr val="tx1"` names a *token*, not a slot: the master's `p:clrMap` is the
+ * indirection that sends it to a {@link ThemeColorSlot}. Which is why the two lists look alike
+ * and are not the same list — `bg1`/`tx1` are tokens, `lt1`/`dk1` are slots.
+ * @see ECMA-376 Part 1 §19.3.1.6
+ */
+declare const COLOR_MAP_TOKENS: readonly ['bg1', 'tx1', 'bg2', 'tx2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
+type ColorMapToken = (typeof COLOR_MAP_TOKENS)[number];
+//#endregion
 //#region src/types/shape.d.ts
 /**
  * A single preset-geometry adjustment guide (`<a:gd>` inside `<a:avLst>`).
@@ -101,12 +349,14 @@ interface ShapeProps extends PositionProps, ObjectNameProps {
    */
   arcThicknessRatio?: number;
   /**
-   * Shape fill color properties
+   * Shape fill color properties, or a bare {@link Color} as shorthand for a solid fill
+   * ({@link FillOption}).
+   * @example 'FF0000' // hex color (red), shorthand for { color:'FF0000' }
    * @example { color:'FF0000' } // hex color (red)
    * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
    * @example { color:SchemeColor.accent1 } // Theme color Accent1
    */
-  fill?: ShapeFillProps;
+  fill?: FillOption;
   /**
    * Flip shape horizontally?
    * @default false
@@ -156,9 +406,10 @@ interface ShapeProps extends PositionProps, ObjectNameProps {
    */
   adjustHandles?: ShapeAdjustHandle[];
   /**
-   * Rounded rectangle radius (only for ShapeType.roundRect)
-   * - values: 0.0 to 1.0
-   * @default 0
+   * Corner radius (inches), for `'roundRect'` and the other rounded presets
+   * - resolved against the shorter side of the shape and written as the preset's corner guide
+   * - not clamped: a radius past half the shorter side is written as given, and PowerPoint draws the corner at its limit
+   * - omitted, the preset keeps its own radius
    */
   rectRadius?: number;
   /**
@@ -195,6 +446,7 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
   /**
    * Alt Text value ("How would you describe this object and its contents to someone who is blind?")
    * - PowerPoint: [right-click on an image] > "Edit Alt Text..."
+   * - omitted, the picture's `descr` is empty, as PowerPoint writes it; the source path or URL is never used
    */
   altText?: string;
   /**
@@ -256,9 +508,10 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
    */
   points?: GeometryPoint[];
   /**
-   * Rounded rectangle corner radius (inches) when `shape: 'roundRect'`
-   * - values: 0.0 to 1.0
-   * @default 0
+   * Corner radius (inches) of the clip `shape`, for `'roundRect'` and the other rounded presets
+   * - resolved against the shorter side of the box and written as the preset's corner guide
+   * - not clamped: a radius past half the shorter side is written as given, and PowerPoint draws the corner at its limit
+   * - omitted, the preset keeps its own radius
    */
   rectRadius?: number;
   /**
@@ -468,7 +721,7 @@ interface OleObjectBaseProps extends PositionProps, ObjectNameProps {
   /**
    * Payload file extension, used to name the embedded part and to pick the content type,
    * relationship type, and default `progId`.
-   * - inferred from `data`'s MIME, else `path`'s extension, else `progId`
+   * - inferred from the MIME type of a `data:` URI in `data`, else `path`'s extension, else `progId`
    * - anything that is not a known Office package extension (`xlsx`/`xlsm`/`docx`/`docm`/`pptx`/`pptm`)
    *   is embedded as a generic OLE blob part named `.bin`
    * @example 'xlsx'
@@ -528,6 +781,72 @@ type MediaProps = MediaBaseProps & ((DataOrPathRequiredProps & {
 }));
 //#endregion
 //#region src/types/text.d.ts
+/**
+ * A drawn bullet: the object arm of {@link TextPropsOptions.bullet}.
+ *
+ * Named rather than left inline so a caller can build one as a variable and so the two
+ * relationship ids `addText()` stamps on it have somewhere off the public surface to live
+ * (`TextBulletPropsInternal`).
+ */
+interface TextBulletProps {
+  /**
+   * Bullet type
+   * @default bullet
+   */
+  type?: 'bullet' | 'number';
+  /**
+   * Bullet character code (unicode)
+   * @example '25BA' // 'BLACK RIGHT-POINTING POINTER' (U+25BA)
+   */
+  characterCode?: string;
+  /**
+   * Bullet glyph font typeface (`<a:buFont/>`), e.g. for symbol-font bullets
+   * @example 'Wingdings' // render `characterCode` using the Wingdings font
+   */
+  fontFace?: string;
+  /**
+   * Bullet glyph size as a percentage of the run's text size (25–400)
+   * @default 100
+   * @example 80 // bullet glyph is 80% of the text size
+   */
+  size?: number;
+  /**
+   * Indentation (space between bullet and text) (points)
+   * @default 27 // DEF_BULLET_MARGIN
+   * @example 10 // Indents text 10 points from bullet
+   */
+  indent?: number;
+  /**
+   * Number type: any `ST_TextAutonumberScheme` (`a:buAutoNum/@type`)
+   * @example 'romanLcParenR' // roman numerals lower-case with paranthesis right
+   */
+  numberType?: (typeof TEXT_AUTONUM_SCHEMES)[number];
+  /**
+   * Number bullets start at
+   * @default 1
+   * @example 10 // numbered bullets start with 10
+   */
+  numberStartAt?: number;
+  /**
+   * Image to use as the bullet glyph ("picture bullet", `<a:buBlip>`)
+   * - supply an image `path` (filesystem/URL) or base64 `data` (same forms as `addImage()`)
+   * - raster formats (PNG/JPG/GIF) and SVG are supported; use `size` to scale relative to the text height
+   * - SVG bullets embed a PNG preview plus the SVG (the same dual-rel handling as `addImage()`)
+   * - takes precedence over `type`/`characterCode` when set
+   * @example image: { path: 'images/star.png' }
+   * @example image: { data: 'image/png;base64,iVBOR...' }
+   * @example image: { path: 'images/star.svg' }
+   */
+  image?: {
+    path?: string;
+    data?: string;
+  };
+  /**
+   * Bullet glyph color (separate from the text run color)
+   * @example 'FF0000' // red bullet
+   */
+  color?: HexColor;
+}
 interface TextBaseProps {
   /**
    * Horizontal alignment
@@ -553,12 +872,12 @@ interface TextBaseProps {
   breakLine?: boolean;
   /**
    * Preset text warp / WordArt shape (`<a:bodyPr><a:prstTxWarp prst="..">`), which
-   * bends the text along a preset path (arch, circle, wave, …). The value is an
-   * OOXML `ST_TextShapeType` preset name.
+   * bends the text along a preset path (arch, circle, wave, …) — the whole
+   * `ST_TextShapeType` set.
    * @example 'textArchUp' // bend text along an upward arch (e.g. a label following a ring/arc)
    * @example 'textCircle'
    */
-  textWarp?: string;
+  textWarp?: TextShapeType;
   /**
    * Add standard or custom bullet
    * - use `true` for standard bullet
@@ -580,76 +899,7 @@ interface TextBaseProps {
    * paragraphs. A paragraph takes its properties from its first run.
    * @default false
    */
-  bullet?: boolean | 'inherit' | {
-    /**
-     * Bullet type
-     * @default bullet
-     */
-    type?: 'bullet' | 'number';
-    /**
-     * Bullet character code (unicode)
-     * @example '25BA' // 'BLACK RIGHT-POINTING POINTER' (U+25BA)
-     */
-    characterCode?: string;
-    /**
-     * Bullet glyph font typeface (`<a:buFont/>`), e.g. for symbol-font bullets
-     * @example 'Wingdings' // render `characterCode` using the Wingdings font
-     */
-    fontFace?: string;
-    /**
-     * Bullet glyph size as a percentage of the run's text size (25–400)
-     * @default 100
-     * @example 80 // bullet glyph is 80% of the text size
-     */
-    size?: number;
-    /**
-     * Indentation (space between bullet and text) (points)
-     * @default 27 // DEF_BULLET_MARGIN
-     * @example 10 // Indents text 10 points from bullet
-     */
-    indent?: number;
-    /**
-     * Number type
-     * @example 'romanLcParenR' // roman numerals lower-case with paranthesis right
-     */
-    numberType?: 'alphaLcParenBoth' | 'alphaLcParenR' | 'alphaLcPeriod' | 'alphaUcParenBoth' | 'alphaUcParenR' | 'alphaUcPeriod' | 'arabicParenBoth' | 'arabicParenR' | 'arabicPeriod' | 'arabicPlain' | 'romanLcParenBoth' | 'romanLcParenR' | 'romanLcPeriod' | 'romanUcParenBoth' | 'romanUcParenR' | 'romanUcPeriod';
-    /**
-     * Number bullets start at
-     * @default 1
-     * @example 10 // numbered bullets start with 10
-     */
-    numberStartAt?: number;
-    /**
-     * Image to use as the bullet glyph ("picture bullet", `<a:buBlip>`)
-     * - supply an image `path` (filesystem/URL) or base64 `data` (same forms as `addImage()`)
-     * - raster formats (PNG/JPG/GIF) and SVG are supported; use `size` to scale relative to the text height
-     * - SVG bullets embed a PNG preview plus the SVG (the same dual-rel handling as `addImage()`)
-     * - takes precedence over `type`/`characterCode` when set
-     * @example image: { path: 'images/star.png' }
-     * @example image: { data: 'image/png;base64,iVBOR...' }
-     * @example image: { path: 'images/star.svg' }
-     */
-    image?: {
-      path?: string;
-      data?: string;
-    };
-    /**
-     * Relationship id assigned to a picture-bullet image (`<a:blip r:embed>`)
-     * - for SVG bullets this is the PNG-preview rel; the SVG rel is `_rIdSvg`
-     * @internal populated by `addText()`; do not set directly
-     */
-    _rId?: number;
-    /**
-     * Relationship id of the SVG image for an SVG picture bullet (`<asvg:svgBlip r:embed>`)
-     * @internal populated by `addText()`; do not set directly
-     */
-    _rIdSvg?: number;
-    /**
-     * Bullet glyph color (separate from the text run color)
-     * @example 'FF0000' // red bullet
-     */
-    color?: HexColor;
-  };
+  bullet?: boolean | 'inherit' | TextBulletProps;
   /**
    * Text capitalization (`a:rPr/@cap`, `ST_TextCapsType`)
    * - `'all'` = ALL CAPS
@@ -660,7 +910,7 @@ interface TextBaseProps {
    * - PowerPoint: Font > Effects > All Caps / Small Caps
    * @default (unset) inherit
    */
-  caps?: 'none' | 'small' | 'all';
+  caps?: (typeof TEXT_CAPS_TYPES)[number];
   /**
    * Text color
    * - `HexColor` or `ThemeColor`
@@ -757,7 +1007,7 @@ interface TextBaseProps {
    */
   tabStops?: Array<{
     position: number;
-    alignment?: 'l' | 'r' | 'ctr' | 'dec';
+    alignment?: (typeof TEXT_TAB_ALIGN_TYPES)[number];
   }>;
   /**
    * text direction
@@ -767,7 +1017,7 @@ interface TextBaseProps {
    * `wordArtVert` = stacked
    * @default 'horz'
    */
-  textDirection?: 'horz' | 'vert' | 'vert270' | 'wordArtVert';
+  textDirection?: Extract<TextVerticalType, 'horz' | 'vert' | 'vert270' | 'wordArtVert'>;
   /**
    * Transparency (percent)
    * - MS-PPT > Format Shape > Text Options > Text Fill & Outline > Text Fill > Transparency
@@ -786,7 +1036,7 @@ interface TextBaseProps {
    * @default (unset) inherit
    */
   underline?: {
-    style?: 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dbl' | 'dotDash' | 'dotDashHeavy' | 'dotDotDash' | 'dotDotDashHeavy' | 'dotted' | 'dottedHeavy' | 'heavy' | 'none' | 'sng' | 'wavy' | 'wavyDbl' | 'wavyHeavy' | 'words';
+    style?: (typeof TEXT_UNDERLINE_TYPES)[number];
     color?: Color;
   };
   /**
@@ -846,20 +1096,6 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
   points?: GeometryPoint[];
   /** Preset-geometry adjustment guides for text frames. */
   shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
-  _bodyProp?: {
-    align?: AlignH;
-    anchor?: TextAnchor;
-    lIns?: number;
-    rIns?: number;
-    tIns?: number;
-    bIns?: number;
-    numCol?: number;
-    spcCol?: number;
-    vert?: TextVertType;
-    wrap?: boolean;
-    prstTxWarp?: string;
-  };
-  _lineIdx?: number;
   baseline?: number;
   /**
    * Character spacing
@@ -898,8 +1134,11 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
    * - `'resize'` computes the height the text needs and bakes it into the shape's
    *   `a:ext/@cy` (adjusting `a:off/@y` per vertical anchor), the marker being
    *   `<a:spAutoFit/>`.
-   * Without registered metrics they fall back to the bare flag (`<a:normAutofit/>` /
-   * `<a:spAutoFit/>`, which only PowerPoint recomputes on edit) and warn once.
+   * With no metrics registered at all they fall back to the bare flag (`<a:normAutofit/>` /
+   * `<a:spAutoFit/>`, which only PowerPoint recomputes on edit), with no warning. Once any face
+   * is registered, a named face without metrics is measured with a conservative estimate
+   * (`measure/heuristic-metrics`), and a run with no face keeps the bare flag
+   * (`measure/shrink-unmeasured`, `measure/resize-unmeasured`); each code warns once per write.
    *
    * **Note** Bare `'shrink'`/`'resize'` (no metrics) only take effect after editing
    * text / resizing the shape; PowerPoint calculates the result then. The object form
@@ -911,12 +1150,13 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
    */
   fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
   /**
-   * Shape fill
+   * Shape fill, or a bare {@link Color} as shorthand for a solid fill ({@link FillOption}).
+   * @example 'FF0000' // hex color (red), shorthand for { color:'FF0000' }
    * @example { color:'FF0000' } // hex color (red)
    * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
    * @example { color:SchemeColor.accent1 } // theme color Accent1
    */
-  fill?: ShapeFillProps;
+  fill?: FillOption;
   /**
    * Flip shape horizontally?
    * @default false
@@ -929,6 +1169,16 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
   flipV?: boolean;
   glow?: TextGlowProps;
   hyperlink?: HyperlinkProps;
+  /**
+   * Outline level of the paragraph (`a:p/@lvl`) — which of the list style's nine levels the
+   * paragraph takes its bullet, indent and typography from.
+   * - range: 0-8, whole numbers only (`ST_TextIndentLevelType`); anything else is reported
+   *   under `text/invalid-indent-level` and ignored
+   * - `0` is the default and writes no attribute
+   * - this is the discrete level, not a measurement: `paraMarginLeft` and `paraIndent` are the
+   *   points-valued controls
+   * @default 0
+   */
   indentLevel?: number;
   isTextBox?: boolean;
   line?: ShapeLineProps;
@@ -970,14 +1220,26 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
    *   a real `<p:ph type="...">`. Use `placeholder: 'title'` to give a slide an accessible
    *   title (PowerPoint's accessibility checker otherwise reports "Missing Slide Title")
    * - values: 'title' | 'body' | et. al.
+   *
+   * **The placeholder supplies, it does not impose.** Every option this bag states wins; the
+   * layout placeholder fills in the ones it leaves out. So `{ placeholder: 'body' }` alone
+   * takes the placeholder's frame, anchor, margins, bullet and text style, and
+   * `{ placeholder: 'body', valign: 'top' }` takes all of that except the anchor. It matches
+   * PowerPoint, where a slide placeholder's XML carries only the properties it overrides and
+   * inherits the rest.
+   *
+   * The rule is about what the *caller* wrote, not about what the option bag holds by the time
+   * inheritance runs: a value this library defaults on the way past does not count as the
+   * caller stating one, and does not beat the layout.
    * @example 'title'
    * @see https://learn.microsoft.com/en-us/office/vba/api/powerpoint.ppplaceholdertype
    */
   placeholder?: string;
   /**
-   * Rounded rectangle radius (only for ShapeType.roundRect)
-   * - values: 0.0 to 1.0
-   * @default 0
+   * Corner radius (inches) of the text box's `shape`, for `'roundRect'` and the other rounded presets
+   * - resolved against the shorter side of the box and written as the preset's corner guide
+   * - not clamped: a radius past half the shorter side is written as given, and PowerPoint draws the corner at its limit
+   * - omitted, the preset keeps its own radius
    */
   rectRadius?: number;
   /**
@@ -992,6 +1254,21 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
    * @default false
    */
   rtlMode?: boolean;
+  /**
+   * Shadow options. **Which shadow depends on which bag it is on**, and the two are different
+   * effects rather than two spellings of one:
+   *
+   * - on the options passed to `addText` — the *shape's* bag — it is the shape's drop shadow
+   *   (`p:spPr/a:effectLst`), PowerPoint's Shape Effects ▸ Shadow;
+   * - on a run's own `options` inside the text array, it is the *text* shadow
+   *   (`a:rPr/a:effectLst`), PowerPoint's Text Effects ▸ Shadow.
+   *
+   * A run therefore does **not** inherit the shape's shadow: PowerPoint's two gestures are
+   * independent, and applying both is what darkens a shadow twice. State it in both places to
+   * get both, exactly as it takes two actions there.
+   * @example addText('hi', { shadow }) // the box has a shadow; its glyphs do not
+   * @example addText([{ text: 'hi', options: { shadow } }]) // the glyphs do; the box does not
+   */
   shadow?: ShadowProps;
   shape?: SHAPE_NAME;
   /**
@@ -1006,7 +1283,7 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
    *   struck" rather than "unspecified"
    * @default (unset) inherit
    */
-  strike?: boolean | 'noStrike' | 'sngStrike' | 'dblStrike';
+  strike?: boolean | (typeof TEXT_STRIKE_TYPES)[number];
   subscript?: boolean;
   superscript?: boolean;
   /**
@@ -1037,9 +1314,9 @@ interface TextProps {
    * `<m:oMathPara>…</m:oMathPara>`; the `m:` prefix is resolved by the wrapper, so the markup does
    * not need its own namespace declarations.
    * This is the raw-OMML entry point. To author from LaTeX or MathML, convert with
-   * `latexToOmml()` / `mathmlToOmml()` from the `@shbernal/ts-pptx/math` subpath.
+   * `latexToOmml()` / `mathmlToOmml()` from the `pptx-ts/math` subpath.
    * @example { math: '<m:r><m:t>x^2+1=y</m:t></m:r>' } // raw OMML
-   * @example import { latexToOmml } from '@shbernal/ts-pptx/math'; ({ math: latexToOmml('x^2+1=y') })
+   * @example import { latexToOmml } from 'pptx-ts/math'; ({ math: latexToOmml('x^2+1=y') })
    */
   math?: string;
   /**
@@ -1235,7 +1512,12 @@ declare function textRun(text: string | number, options?: TextPropsOptions): Tex
 declare function textRuns(runs: TextProps[]): TextProps[];
 //#endregion
 //#region src/types/object.d.ts
-interface PlaceholderProps extends PositionProps, TextBaseProps, ObjectNameProps {
+/**
+ * A layout placeholder's options. They reach the slide objects that fill the placeholder as text
+ * options, so beside the text formatting a placeholder takes the shape `fill` (an image fill
+ * included) and the `hyperlink` a text box does, and `bullet` through {@link TextBaseProps}.
+ */
+interface PlaceholderProps extends PositionProps, TextBaseProps, ObjectNameProps, Pick<TextPropsOptions, 'fill' | 'hyperlink'> {
   name: string;
   type: PLACEHOLDER_TYPE;
   /**
@@ -1248,17 +1530,19 @@ interface PlaceholderProps extends PositionProps, TextBaseProps, ObjectNameProps
    */
   shape?: SHAPE_NAME;
   /**
-   * Rounded rectangle corner radius (inches) when `shape: 'roundRect'`
-   * - range: 0.0 to slide height/2
+   * Corner radius (inches) of the placeholder's `shape`, for `'roundRect'` and the other rounded presets
+   * - resolved against the shorter side of the placeholder and written as the preset's corner guide
+   * - not clamped: a radius past half the shorter side is written as given, and PowerPoint draws the corner at its limit
+   * - omitted, the preset keeps its own radius
    */
   rectRadius?: number;
 }
 interface ObjectNameProps {
   /**
    * Object name
-   * - used instead of default "Object N" name
+   * - used instead of the default name for the object's kind: `Text 1`, `Shape 2`, `Image 1` and so
+   *   on, numbered per kind (see `docs/reference/object-names.md`)
    * - PowerPoint: Home > Arrange > Selection Pane...
-   * @default 'Object 1'
    * @example 'Antenna Design 9'
    */
   objectName?: string;
@@ -1361,7 +1645,13 @@ type CommonObjectDescriptor = {
 };
 //#endregion
 //#region src/types/chart.d.ts
-type ChartAxisTickMark = 'none' | 'inside' | 'outside' | 'cross';
+/**
+ * An axis' tick marks (`ST_TickMark`): `in` and `out` of the axis line, `cross` through it, or `none`.
+ *
+ * This used to offer `'inside'` and `'outside'`, which are not the schema's words; they reached
+ * the part as written and PowerPoint refused it. Any other value warns and takes the default.
+ */
+type ChartAxisTickMark = TickMark;
 /**
  * Line end cap style. Maps to the OOXML `cap` attribute on `<a:ln>` (`flat`/`sq`/`rnd`).
  */
@@ -1454,18 +1744,18 @@ interface ChartDataPointStyle {
  * Error-bar configuration for a chart series (`<c:errBars>`).
  * Maps onto OOXML `CT_ErrBars` (errDir / errBarType / errValType / noEndCap / plus / minus / val).
  */
-interface ChartErrorBarOptions {
+interface ChartErrorBarOptions extends StrokeProps {
   /**
    * Axis the error bars measure along.
    * - `'y'` (the value axis) for BAR/BAR3D/LINE/AREA; SCATTER may also use `'x'`.
    * @default 'y'
    */
-  direction?: 'x' | 'y';
+  direction?: ErrorBarDirection;
   /**
    * Which sides of each marker draw a bar.
    * @default 'both'
    */
-  barType?: 'both' | 'minus' | 'plus';
+  barType?: ErrorBarType;
   /**
    * How `value` (or `plusValues`/`minusValues`) is interpreted.
    * - `'fixedVal'` — fixed amount in axis units
@@ -1475,9 +1765,10 @@ interface ChartErrorBarOptions {
    * - `'cust'` — explicit per-point amounts via `plusValues`/`minusValues`
    * @default 'fixedVal'
    */
-  valueType?: 'cust' | 'fixedVal' | 'percentage' | 'stdDev' | 'stdErr';
+  valueType?: ErrorBarValueType;
   /**
    * Magnitude for `'fixedVal'`, `'percentage'`, or `'stdDev'`. Ignored for `'stdErr'` and `'cust'`.
+   * - a finite number; `NaN` or `Infinity` throws
    * @default 1
    */
   value?: number;
@@ -1490,31 +1781,36 @@ interface ChartErrorBarOptions {
    * @default false
    */
   noEndCap?: boolean;
-  /** Error-bar line color (hex, e.g. `'FF0000'`). */
-  color?: HexColor;
-  /** Error-bar line width (points). */
-  size?: number;
-}
-interface OptsChartGridLine {
-  /**
-   * MS-PPT > Chart format > Format Major Gridlines > Line > Cap type
-   * - line cap type
-   * @default flat
-   */
-  cap?: LineCap;
   /**
-   * Gridline color
-   * - `HexColor` or `ThemeColor`
-   * @example 'FF3399'
-   * @example SchemeColor.accent1 // theme color Accent1
+   * Error-bar line width (points).
+   * @deprecated Use {@link StrokeProps.width}. `width` wins when both are set.
    */
-  color?: Color;
+  size?: number;
+}
+/**
+ * The stroke a plot draws its gridlines (or a stacked bar its series lines) with.
+ *
+ * A {@link StrokeProps}, so it takes `width`, `dashType`, `type`, `cap`, `color` and
+ * `transparency` under the same names a table border does. `size` and `style` are the
+ * pre-4.0 spellings and still work; see their notes for the exact mapping.
+ *
+ * Defaults where a gridline is drawn: `color: '888888'`, `width: 1`, `cap: 'flat'`, solid.
+ */
+interface OptsChartGridLine extends StrokeProps {
   /**
-   * Gridline size (points)
+   * Gridline size (points).
+   * @deprecated Use {@link StrokeProps.width}. `width` wins when both are set.
    */
   size?: number;
   /**
-   * Gridline style
+   * Gridline style.
+   *
+   * `'none'` omits the gridlines entirely and is the same statement as `type: 'none'`;
+   * `'solid'`, `'dash'` and `'dot'` are `a:prstDash` presets and map onto `dashType`
+   * unchanged — note that this `'dash'` is the literal `dash` preset, where
+   * {@link StrokeProps.type}`: 'dash'` means `sysDash`.
+   * @deprecated Use {@link StrokeProps.dashType} (or `type: 'none'`). `dashType` and an
+   *   explicit `type` both win when set.
    */
   style?: 'solid' | 'dash' | 'dot' | 'none';
 }
@@ -1538,13 +1834,14 @@ interface ChartPropsFillLine {
    *
    * `type: 'image'` is not supported here and falls back to no fill with a warning: a
    * blip fill needs a media relationship on the chart part, which nothing registers.
+   * @example fill: '696969' // hex RGB color value, shorthand for {color: '696969'}
    * @example fill: {color: '696969'} // hex RGB color value
    * @example fill: {color: SchemeColor.background2} // Theme color value
    * @example fill: {color: '696969', transparency: 50} // 50% transparent grey
    * @example fill: {type: 'gradient', gradient: {kind: 'linear', angle: 90, stops: [{position: 0, color: '0088CC'}, {position: 100, color: 'FFFFFF'}]}}
    * @example fill: {type: 'inherit'} // no fill child at all -- take the chart style's fill
    */
-  fill?: ShapeFillProps;
+  fill?: FillOption;
 }
 interface ChartAreaProps extends ChartPropsFillLine {
   /**
@@ -1555,10 +1852,6 @@ interface ChartAreaProps extends ChartPropsFillLine {
   roundedCorners?: boolean;
 }
 interface ChartPropsBase {
-  /**
-   * Axis position
-   */
-  axisPos?: 'b' | 'l' | 'r' | 't';
   /**
    * Series colours, cycled: series (or, on a pie/doughnut, data point) `n` takes
    * `chartColors[n % chartColors.length]`, so a shorter list repeats rather than running out.
@@ -1569,12 +1862,20 @@ interface ChartPropsBase {
    */
   chartColors?: HexColor[];
   /**
-   * opacity (0 - 100)
+   * Series fill opacity, as a percentage from 0 to 100.
+   *
+   * `0` means what it says: a fully transparent fill, so the series is invisible. That is a
+   * deliberate meaning, not a shorthand for "unset"; leave the option out for an opaque fill.
+   * A value outside 0-100 clamps with a warning, and `NaN` throws.
    * @example 50 // 50% opaque
    */
   chartColorsOpacity?: number;
   dataBorder?: BorderProps;
-  displayBlanksAs?: 'gap' | 'span' | 'zero';
+  /**
+   * What a plot draws where a value is missing (`ST_DispBlanksAs`).
+   * @default 'gap'
+   */
+  displayBlanksAs?: DisplayBlanksAs;
   invertedColors?: HexColor[];
   lang?: string;
   layout?: PositionProps;
@@ -1589,7 +1890,9 @@ interface ChartPropsBase {
    * Enable data labels, with a meaning that is **overloaded per plot type** — it is not a
    * plain duplicate of {@link ChartPropsBase.showValue}:
    * - pie / doughnut: shows the **category name** (`c:showCatName`);
-   * - scatter: shows **both** the value and the category name;
+   * - scatter: turns on the labels {@link ChartPropsDataLabel.dataLabelFormatScatter} describes,
+   *   and shows nothing without it: `'XY'` shows both the value and the category name, and
+   *   `'custom'`/`'customXY'` show each point's label text;
    * - chartEx (waterfall/funnel/…): OR-combined with `showValue` to show the **value** label.
    *
    * For the common "show the numeric value" case on standard plots, prefer `showValue`.
@@ -1666,8 +1969,27 @@ interface ChartPropsBase {
   plotArea?: ChartPropsFillLine;
   /**
    * Per-series style overrides.
-   * Element at index N applies to the series at data[N].
-   * Missing indices or unset fields fall back to the chart-level option.
+   *
+   * Element at index N applies to the **Nth series of the chart** — the same number the series
+   * carries in `<c:idx>`/`<c:order>`. For most plots that is its position in `data`; on a combo
+   * it counts across every subchart in order, so a bar(2) + line(1) combo reaches the line at
+   * index 2. A scatter or bubble series counts one lower than its position, because the X row in
+   * front of it is not a series: `seriesOptions[0]` styles `data[1]`. Missing indices or unset
+   * fields fall back to the chart-level option.
+   *
+   * **Not every field reaches every plot**, and a stated field that cannot be resolved warns
+   * (`chart/option-not-supported`) naming itself rather than being dropped in silence:
+   *
+   * - `color` reaches every plot that colours *series*: `bar`, `bar3d`, `area`, `line`, `radar`,
+   *   `scatter`, `bubble`, `bubble3d`, and (as the volume bar and the close marker) `stock`.
+   * - `lineSize` reaches only a series that strokes itself: `line`, `radar`, `scatter`, `bubble`
+   *   and `bubble3d`. A bar or an area takes its outline from `dataBorder`; a stock price series
+   *   draws no line at all.
+   * - the `dataLabel*` fields need a per-series `<c:dLbls>`, which the category-axis family and
+   *   `scatter` emit. A bubble chart's label block is chart-level, and `dataLabelFormatCode` in
+   *   particular has no referent on `scatter`, whose label builders emit no number format.
+   * - `pie`, `doughnut` and `surface` read nothing: a pie colours points and a surface colours
+   *   bands, so a per-*series* override has no referent even in principle.
    */
   seriesOptions?: ChartSeriesOpts[];
 }
@@ -1676,7 +1998,16 @@ interface ChartPropsAxisCat {
    * Multi-Chart prop: array of cat axes
    */
   catAxes?: ChartPropsAxisCat[];
-  catAxisBaseTimeUnit?: string;
+  /**
+   * The unit a date axis counts from in (`c:baseTimeUnit/@val`, `ST_TimeUnit`).
+   *
+   * The canonical spelling is lower-case, and the check forgives case at run time, so `'Days'`
+   * is taken as `days`. The type names the canonical three so the call site offers them; do not
+   * read the narrower type as permission to drop the tolerance, which a JavaScript caller with
+   * no types still relies on. Anything else warns `chart/invalid-axis-time-unit` and leaves the
+   * element off, because a garbage unit makes PowerPoint render nothing at all.
+   */
+  catAxisBaseTimeUnit?: TimeUnit;
   catAxisCrossesAt?: number | 'autoZero';
   catAxisHidden?: boolean;
   catAxisLabelColor?: string;
@@ -1691,23 +2022,89 @@ interface ChartPropsAxisCat {
    * - PowerPoint: Format Axis > Number > Format Code
    */
   catAxisLabelFormatCode?: string;
-  catAxisLabelFrequency?: string;
-  catAxisLabelPos?: 'none' | 'low' | 'high' | 'nextTo';
+  /**
+   * Show every Nth category label (`c:tickLblSkip`, `ST_Skip`), e.g. `2` for every other one.
+   * - a whole number of at least 1; anything else warns and leaves the element off
+   *
+   * Pass a number. The `string` half is a compatibility hangover — this was typed as a
+   * free-form string and emitted verbatim, which both rejected the natural `2` and let
+   * `'every other'` reach the attribute — and is read with `Number()` like any other.
+   */
+  catAxisLabelFrequency?: number | string;
+  catAxisLabelPos?: TickLabelPosition;
   catAxisLabelRotate?: number;
-  catAxisLineColor?: string;
+  /**
+   * The category axis line, as a stroke: `width`, `dashType`, `type`, `color`, `cap` and
+   * `transparency` under the same names a table border and a gridline use.
+   *
+   * `type: 'none'` paints no line (an `<a:noFill/>` on the axis' own `<c:spPr>`), which is
+   * what `catAxisLineShow: false` used to say. Omitted, the line is drawn at 1 pt in
+   * `DEF_GRIDLINE_COLOR`, solid, flat-capped.
+   *
+   * The four flat `catAxisLine*` keys below are the pre-4.0 spellings. Anything set here wins
+   * over its flat counterpart. They cannot express a cap, a transparency, or any
+   * dash outside `solid`/`dash`/`dot`, which is why they are superseded rather than
+   * widened.
+   * @example { width: 1.5, dashType: 'lgDashDot', color: SchemeColor.accent1, transparency: 40 }
+   */
+  catAxisLine?: StrokeProps;
+  /**
+   * Category-axis line colour.
+   * @deprecated Use `catAxisLine.color`.
+   */
+  catAxisLineColor?: Color;
+  /**
+   * Draw the category-axis line at all.
+   * @deprecated Use `catAxisLine.type: 'none'` to suppress it.
+   * @default true
+   */
   catAxisLineShow?: boolean;
+  /**
+   * Category-axis line width in points.
+   * @deprecated Use `catAxisLine.width`.
+   */
   catAxisLineSize?: number;
+  /**
+   * Category-axis line dash.
+   * @deprecated Use `catAxisLine.dashType`, which takes the full `ST_PresetLineDashVal` set.
+   */
   catAxisLineStyle?: 'solid' | 'dash' | 'dot';
   catAxisMajorTickMark?: ChartAxisTickMark;
-  catAxisMajorTimeUnit?: string;
+  /**
+   * The unit a date axis counts major tick marks in (`c:majorTimeUnit/@val`, `ST_TimeUnit`).
+   *
+   * The canonical spelling is lower-case, and the check forgives case at run time, so `'Days'`
+   * is taken as `days`. The type names the canonical three so the call site offers them; do not
+   * read the narrower type as permission to drop the tolerance, which a JavaScript caller with
+   * no types still relies on. Anything else warns `chart/invalid-axis-time-unit` and leaves the
+   * element off, because a garbage unit makes PowerPoint render nothing at all.
+   */
+  catAxisMajorTimeUnit?: TimeUnit;
+  /**
+   * Spacing between major tick marks on a date axis or a scatter's X axis (`c:majorUnit`,
+   * `ST_AxisUnit`).
+   * - above 0; anything else warns and leaves the element off
+   */
   catAxisMajorUnit?: number;
+  /** Axis maximum (`c:max`). A value that is not a finite number throws. */
   catAxisMaxVal?: number;
   catAxisMinorTickMark?: ChartAxisTickMark;
-  catAxisMinorTimeUnit?: string;
+  /**
+   * The unit a date axis counts minor tick marks in (`c:minorTimeUnit/@val`, `ST_TimeUnit`).
+   *
+   * The canonical spelling is lower-case, and the check forgives case at run time, so `'Days'`
+   * is taken as `days`. The type names the canonical three so the call site offers them; do not
+   * read the narrower type as permission to drop the tolerance, which a JavaScript caller with
+   * no types still relies on. Anything else warns `chart/invalid-axis-time-unit` and leaves the
+   * element off, because a garbage unit makes PowerPoint render nothing at all.
+   */
+  catAxisMinorTimeUnit?: TimeUnit;
+  /** Spacing between minor tick marks; the same rule as {@link ChartPropsAxisCat.catAxisMajorUnit}. */
   catAxisMinorUnit?: number;
+  /** Axis minimum (`c:min`). A value that is not a finite number throws. */
   catAxisMinVal?: number;
   catAxisMultiLevelLabels?: boolean;
-  catAxisOrientation?: 'minMax' | 'maxMin';
+  catAxisOrientation?: AxisOrientation;
   catAxisTitle?: string;
   catAxisTitleColor?: string;
   catAxisTitleFontFace?: string;
@@ -1717,40 +2114,79 @@ interface ChartPropsAxisCat {
   catLabelFormatCode?: string;
   /**
    * Whether data should use secondary category axis (instead of primary)
+   *
+   * A combo subchart plots on the secondary category and value axes together, because a plot's
+   * two axes have to cross each other. When no subchart sets `secondaryValAxis`, the secondary
+   * value axis is written hidden; `valAxes[1]` can show it.
    * @default false
    */
   secondaryCatAxis?: boolean;
   showCatAxisTitle?: boolean;
 }
 interface ChartPropsAxisSer {
-  serAxisBaseTimeUnit?: string;
   serAxisHidden?: boolean;
   serAxisLabelColor?: string;
   serAxisLabelFontBold?: boolean;
   serAxisLabelFontFace?: string;
   serAxisLabelFontItalic?: boolean;
   serAxisLabelFontSize?: number;
-  serAxisLabelFrequency?: string;
-  serAxisLabelPos?: 'none' | 'low' | 'high' | 'nextTo';
-  serAxisLineColor?: string;
-  serAxisLineShow?: boolean;
-  serAxisMajorTimeUnit?: string;
-  serAxisMajorUnit?: number;
-  serAxisMinorTimeUnit?: string;
-  serAxisMinorUnit?: number;
-  serAxisOrientation?: string;
-  serAxisTitle?: string;
-  serAxisTitleColor?: string;
-  serAxisTitleFontFace?: string;
-  serAxisTitleFontSize?: number;
-  serAxisTitleRotate?: number;
-  serGridLine?: OptsChartGridLine;
-  serLabelFormatCode?: string;
-  showSerAxisTitle?: boolean;
-}
+  /**
+   * Show every Nth series-axis label (`c:tickLblSkip`, `ST_Skip`) on a 3-D chart.
+   * - a whole number of at least 1; anything else warns and leaves the element off
+   *
+   * Pass a number; see {@link ChartPropsAxisCat.catAxisLabelFrequency} for the `string` half.
+   */
+  serAxisLabelFrequency?: number | string;
+  serAxisLabelPos?: TickLabelPosition;
+  /**
+   * The series axis line, as a stroke — the same {@link StrokeProps} the other two axes and
+   * every gridline take. See {@link ChartPropsAxisCat.catAxisLine}.
+   *
+   * The series axis is the third axis of a 3-D chart, and it was the one axis whose line
+   * could be shown and coloured but not sized or dashed: the emitter hardcoded one point and
+   * `solid` where the other two read the caller. Comparing the three axes' option spellings
+   * side by side is how that was found.
+   */
+  serAxisLine?: StrokeProps;
+  /**
+   * Series-axis line colour.
+   * @deprecated Use `serAxisLine.color`.
+   */
+  serAxisLineColor?: Color;
+  /**
+   * Draw the series-axis line at all.
+   * @deprecated Use `serAxisLine.type: 'none'` to suppress it.
+   * @default true
+   */
+  serAxisLineShow?: boolean;
+  /**
+   * Series-axis line width in points.
+   * @deprecated Use `serAxisLine.width`.
+   */
+  serAxisLineSize?: number;
+  /**
+   * Series-axis line dash.
+   * @deprecated Use `serAxisLine.dashType`, which takes the full `ST_PresetLineDashVal` set.
+   */
+  serAxisLineStyle?: 'solid' | 'dash' | 'dot';
+  serAxisOrientation?: AxisOrientation;
+  serAxisTitle?: string;
+  serAxisTitleColor?: string;
+  serAxisTitleFontFace?: string;
+  serAxisTitleFontSize?: number;
+  serAxisTitleRotate?: number;
+  serGridLine?: OptsChartGridLine;
+  serLabelFormatCode?: string;
+  showSerAxisTitle?: boolean;
+}
 interface ChartPropsAxisVal {
   /**
    * Whether data should use secondary value axis (instead of primary)
+   *
+   * A combo subchart plots on the secondary category and value axes together, because a plot's
+   * two axes have to cross each other. When no subchart sets `secondaryCatAxis`, the secondary
+   * category axis is written hidden, as PowerPoint does for a series moved to its secondary axis;
+   * `catAxes[1]` can show it.
    * @default false
    */
   secondaryValAxis?: boolean;
@@ -1766,8 +2202,8 @@ interface ChartPropsAxisVal {
    * - `'midCat'` = values plotted on tick marks (default for scatter/area)
    * - PowerPoint: Format Axis > Axis Options > Axis crosses > On tick marks / Between tick marks
    */
-  valAxisCrossBetween?: 'between' | 'midCat';
-  valAxisDisplayUnit?: 'billions' | 'hundredMillions' | 'hundreds' | 'hundredThousands' | 'millions' | 'tenMillions' | 'tenThousands' | 'thousands' | 'trillions';
+  valAxisCrossBetween?: CrossBetween;
+  valAxisDisplayUnit?: BuiltInUnit;
   valAxisDisplayUnitLabel?: boolean;
   valAxisHidden?: boolean;
   valAxisLabelColor?: string;
@@ -1776,23 +2212,58 @@ interface ChartPropsAxisVal {
   valAxisLabelFontItalic?: boolean;
   valAxisLabelFontSize?: number;
   valAxisLabelFormatCode?: string;
-  valAxisLabelPos?: 'none' | 'low' | 'high' | 'nextTo';
+  valAxisLabelPos?: TickLabelPosition;
   valAxisLabelRotate?: number;
-  valAxisLineColor?: string;
+  /**
+   * The value axis line, as a stroke — the same {@link StrokeProps} the other two axes and
+   * every gridline take. See {@link ChartPropsAxisCat.catAxisLine}.
+   */
+  valAxisLine?: StrokeProps;
+  /**
+   * Value-axis line colour.
+   * @deprecated Use `valAxisLine.color`.
+   */
+  valAxisLineColor?: Color;
+  /**
+   * Draw the value-axis line at all.
+   * @deprecated Use `valAxisLine.type: 'none'` to suppress it.
+   * @default true
+   */
   valAxisLineShow?: boolean;
+  /**
+   * Value-axis line width in points.
+   * @deprecated Use `valAxisLine.width`.
+   */
   valAxisLineSize?: number;
+  /**
+   * Value-axis line dash.
+   * @deprecated Use `valAxisLine.dashType`, which takes the full `ST_PresetLineDashVal` set.
+   */
   valAxisLineStyle?: 'solid' | 'dash' | 'dot';
   /**
    * PowerPoint: Format Axis > Axis Options > Logarithmic scale - Base
-   * - range: 2-99
+   * - range: 2-1000 (`ST_LogBase`); a value outside it clamps with a warning, and `NaN` throws
    */
   valAxisLogScaleBase?: number;
   valAxisMajorTickMark?: ChartAxisTickMark;
+  /**
+   * Spacing between major tick marks on the value axis (`c:majorUnit`, `ST_AxisUnit`).
+   * - above 0; anything else warns and leaves the element off
+   * - PowerPoint: Format Axis > Axis Options > Units > Major
+   */
   valAxisMajorUnit?: number;
+  /** Axis maximum (`c:max`). A value that is not a finite number throws. */
   valAxisMaxVal?: number;
   valAxisMinorTickMark?: ChartAxisTickMark;
+  /**
+   * Spacing between minor tick marks on the value axis (`c:minorUnit`) — the sibling
+   * `valAxisMajorUnit` had had for years, while the category and series axes carried both.
+   * - PowerPoint: Format Axis > Axis Options > Units > Minor
+   */
+  valAxisMinorUnit?: number;
+  /** Axis minimum (`c:min`). A value that is not a finite number throws. */
   valAxisMinVal?: number;
-  valAxisOrientation?: 'minMax' | 'maxMin';
+  valAxisOrientation?: AxisOrientation;
   valAxisTitle?: string;
   valAxisTitleColor?: string;
   valAxisTitleFontFace?: string;
@@ -1809,8 +2280,16 @@ interface ChartPropsAxisVal {
   valLabelFormatCode?: string;
 }
 interface ChartPropsChartBar {
-  bar3DShape?: string;
-  barDir?: string;
+  /**
+   * The solid a 3-D bar is drawn as (`ST_Shape`).
+   * @default 'box'
+   */
+  bar3DShape?: Bar3DShape;
+  /**
+   * Whether bars run horizontally (`bar`) or vertically (`col`) (`ST_BarDir`).
+   * @default 'col'
+   */
+  barDir?: BarDirection;
   barGapDepthPct?: number;
   /**
    * MS-PPT > Format chart > Format Data Point > Series Options >  "Gap Width"
@@ -1819,7 +2298,13 @@ interface ChartPropsChartBar {
    * @default 150
    */
   barGapWidthPct?: number;
-  barGrouping?: string;
+  /**
+   * How the plot stacks its series (`ST_BarGrouping`). A 2-D bar plot takes every member but
+   * `standard`, which is the 3-D form's own default; an out-of-range value falls back to the
+   * default for the plot with a warning.
+   * @default 'clustered' (2-D), 'standard' (3-D)
+   */
+  barGrouping?: BarGrouping;
   /**
    * MS-PPT > Format chart > Format Data Point > Series Options >  "Series Overlap"
    * - overlap (percent)
@@ -1860,7 +2345,8 @@ interface ChartPropsChartLine {
    */
   lineDash?: ChartLineDash;
   /**
-   * Per-series dash type overrides; index matches the series order in the `data` array.
+   * Per-series dash type overrides; index matches the series order in the `data` array — and on a
+   * combo, the order across every subchart, the same index `seriesOptions` uses.
    * - entries shorter than the series count fall back to `lineDash`
    * - example: `['solid', 'dash', 'lgDash']` gives each series its own dash pattern
    */
@@ -1870,7 +2356,7 @@ interface ChartPropsChartLine {
    * - marker type
    * @default circle
    */
-  lineDataSymbol?: 'circle' | 'dash' | 'diamond' | 'dot' | 'none' | 'square' | 'triangle';
+  lineDataSymbol?: LineDataSymbol;
   /**
    * MS-PPT > Chart format > Format Data Series > [Marker Options] > Border > Color
    * - border color
@@ -1916,11 +2402,13 @@ interface ChartPropsChartPie {
 }
 interface ChartPropsChartRadar {
   /**
-   * Radar chart sub-type, named to match the PowerPoint UI ("Radar", "Radar with
-   * Markers", "Filled Radar").
+   * Radar chart sub-type. Two vocabularies are accepted and mean the same three things:
+   * this library's PowerPoint-UI names (`radar`, `markers`, `filled`) and `ST_RadarStyle`'s
+   * own wire spellings (`standard`, `marker`, `filled`), which is what the chart part shows.
+   * `filled` is spelled the same in both.
    * @default radar
    */
-  radarStyle?: 'radar' | 'markers' | 'filled';
+  radarStyle?: RadarStyle | RadarStyleAlias;
 }
 /**
  * Options for the modern (Office 2016) chartEx chart types.
@@ -2083,8 +2571,24 @@ interface ChartPropsDataLabel {
    * @example '$0.00' // shows values as '$0.00'
    */
   dataLabelFormatCode?: string;
+  /**
+   * What a scatter's data labels show when {@link ChartPropsBase.showLabel} is set. A scatter
+   * writes series labels only for one of these, so `showLabel` alone shows nothing.
+   * - `'XY'`: each point's value and category name, composed by PowerPoint;
+   * - `'custom'`: each point's label text;
+   * - `'customXY'`: each point's label text followed by its X and Y values, for a label that is
+   *   not blank.
+   */
   dataLabelFormatScatter?: 'custom' | 'customXY' | 'XY';
-  dataLabelPosition?: 'b' | 'bestFit' | 'ctr' | 'l' | 'r' | 't' | 'inEnd' | 'outEnd';
+  /**
+   * Where a data label sits relative to its point (`ST_DLblPos`).
+   *
+   * The whole set is legal on the attribute, but only a subset of it is legal *per plot type*
+   * -- a pie takes `bestFit`/`ctr`/`inEnd`/`outEnd` and nothing else, a stacked bar takes
+   * `inBase` and not `outEnd`. A value outside this plot's subset is dropped with a warning
+   * rather than emitted, because PowerPoint reports the file as needing repair.
+   */
+  dataLabelPosition?: DataLabelPosition;
 }
 interface ChartPropsDataTable {
   dataTableFontSize?: number;
@@ -2118,12 +2622,21 @@ interface ChartPropsLegend {
    * legend horizontally while leaving vertical placement and size automatic.
    * Setting this overrides the automatic placement implied by `legendPos`.
    *
+   * Held to the plot area's {@link ChartPropsBase.layout} rule: `x` and `y` from 0 to 1, `w` and
+   * `h` above 0 and at most 1. A value outside that, or one that is not a number, warns and is
+   * dropped, so that axis stays automatic. `ST_Double` itself is unbounded; whether PowerPoint
+   * places a legend reaching past the chart edge has not been checked, so the narrower rule stands.
+   *
    * Has no effect unless `showLegend` is `true`.
    *
    * @example { x: 0.7, y: 0.3, w: 0.25, h: 0.4 }
    */
   legendLayout?: PositionProps;
-  legendPos?: 'b' | 'l' | 'r' | 't' | 'tr';
+  /**
+   * Where the legend sits (`ST_LegendPos`).
+   * @default 'r'
+   */
+  legendPos?: LegendPosition;
 }
 interface ChartPropsTitle extends TextBaseProps {
   title?: string;
@@ -2145,7 +2658,7 @@ interface ChartPropsTitle extends TextBaseProps {
   };
   titleRotate?: number;
 }
-interface ChartOpts extends ChartPropsAxisCat, ChartPropsAxisSer, ChartPropsAxisVal, ChartPropsBase, ChartPropsChartBar, ChartPropsChartDoughnut, ChartPropsChartLine, ChartPropsChartPie, ChartPropsChartRadar, ChartPropsChartWaterfall, ChartPropsChartHistogram, ChartPropsChartBoxWhisker, ChartPropsChartRegionMap, ChartPropsChartStock, ChartPropsChartSurface, ChartPropsDataLabel, ChartPropsDataTable, ChartPropsLegend, ChartPropsTitle, ObjectNameProps, OptsChartGridLine, PositionProps {
+interface ChartOpts extends ChartPropsAxisCat, ChartPropsAxisSer, ChartPropsAxisVal, ChartPropsBase, ChartPropsChartBar, ChartPropsChartDoughnut, ChartPropsChartLine, ChartPropsChartPie, ChartPropsChartRadar, ChartPropsChartWaterfall, ChartPropsChartHistogram, ChartPropsChartBoxWhisker, ChartPropsChartRegionMap, ChartPropsChartStock, ChartPropsChartSurface, ChartPropsDataLabel, ChartPropsDataTable, ChartPropsLegend, ChartPropsTitle, ObjectNameProps, PositionProps {
   /**
    * Chart type — required when using the canonical `addChart(data, options)` signature.
    * - Omit only for multi-type (combo) charts, where each `ChartMulti` entry carries its own `type`.
@@ -2169,130 +2682,59 @@ interface ChartOpts extends ChartPropsAxisCat, ChartPropsAxisSer, ChartPropsAxis
   metadata?: Record<string, string>;
 }
 //#endregion
-//#region src/ooxml/st-enums.d.ts
+//#region src/types/style.d.ts
 /**
- * `ST_` simple-type enumerations from ECMA-376, declared once as the single source of both the
- * TypeScript union a caller is checked against and the runtime list a value is validated against.
+ * A stroke, stated once.
  *
- * **The problem this solves.** Each of these used to exist twice: a hand-written string union in
- * `src/types/` (what the compiler enforces) and a hand-written array in `src/gen/` or `src/read/`
- * (what the validator checks at run time). Nothing tied the two together, so adding a member to
- * one and not the other produced either a value TypeScript accepts and the validator drops, or a
- * value the validator passes and the type rejects. Two of them had already diverged in *order*,
- * which is harmless, but nothing would have caught a divergence in *content*.
+ * Width, dash, colour, transparency and cap are one concept, and the library used to spell
+ * them five ways: `width`/`size`/`catAxisLineSize` for the measure, `type` + `dashType` /
+ * `style` / `catAxisLineStyle` for the dash, `HexColor` / `Color` / bare `string` for the
+ * paint. This is that vocabulary; {@link BorderProps} is an alias of it, and the chart
+ * option bag now takes it wherever it used to spell a stroke by hand.
  *
- * **The shape.** Every entry is a `readonly` tuple declared `as const`, with its union derived via
- * `(typeof X)[number]`. Widening the tuple widens the union in the same edit — they cannot drift.
- * This is the idiom already used for `EMBEDDED_FONT_SLOTS` and `EXTRA_SHAPE_PRESETS`; this module
- * brings the stragglers onto it.
- *
- * **Why this module is neither `gen/` nor `read/`.** `src/types/` needs the unions for the public
- * write API, `src/gen/` needs the tuples to vet a value before emitting it, and `src/read/` needs
- * them to vet a value before writing it into a loaded part. It is a fact about the schema, so it
- * belongs to none of the three.
- *
- * Values are listed in **schema declaration order**, which is the order the diagnostics print
- * when they tell a caller what is legal.
- */
-/**
- * `ST_BevelPresetType` — the bevel profile applied to a 3-D edge.
- * @see ECMA-376 Part 1 §20.1.10.9
- */
-declare const BEVEL_PRESETS: readonly ['relaxedInset', 'circle', 'slope', 'cross', 'angle', 'softRound', 'convex', 'coolSlant', 'divot', 'riblet', 'hardEdge', 'artDeco'];
-type BevelPresetType = (typeof BEVEL_PRESETS)[number];
-/**
- * `ST_PresetMaterialType` — how a 3-D surface responds to light.
- * @see ECMA-376 Part 1 §20.1.10.50
- */
-declare const PRESET_MATERIALS: readonly ['legacyMatte', 'legacyPlastic', 'legacyMetal', 'legacyWireframe', 'matte', 'plastic', 'metal', 'warmMatte', 'translucentPowder', 'powder', 'dkEdge', 'softEdge', 'clear', 'flat', 'softmetal'];
-type PresetMaterialType = (typeof PRESET_MATERIALS)[number];
-/**
- * `ST_LightRigType` — the preset lighting scene.
- * @see ECMA-376 Part 1 §20.1.10.35
- */
-declare const LIGHT_RIGS: readonly ['legacyFlat1', 'legacyFlat2', 'legacyFlat3', 'legacyFlat4', 'legacyNormal1', 'legacyNormal2', 'legacyNormal3', 'legacyNormal4', 'legacyHarsh1', 'legacyHarsh2', 'legacyHarsh3', 'legacyHarsh4', 'threePt', 'balanced', 'soft', 'harsh', 'flood', 'contrasting', 'morning', 'sunrise', 'sunset', 'chilly', 'freezing', 'flat', 'twoPt', 'glow', 'brightRoom'];
-type LightRigType = (typeof LIGHT_RIGS)[number];
-/**
- * `ST_LightRigDirection` — where the light rig sits relative to the scene.
- * @see ECMA-376 Part 1 §20.1.10.33
- */
-declare const LIGHT_RIG_DIRECTIONS: readonly ['tl', 't', 'tr', 'l', 'r', 'bl', 'b', 'br'];
-type LightRigDirection = (typeof LIGHT_RIG_DIRECTIONS)[number];
-/**
- * `ST_TextVerticalType` — `a:bodyPr/@vert` and `a:tcPr/@vert`.
- * @see ECMA-376 Part 1 §20.1.10.83
- */
-declare const TEXT_VERTICAL: readonly ['horz', 'vert', 'vert270', 'wordArtVert', 'eaVert', 'mongolianVert', 'wordArtVertRtl'];
-type TextVerticalType = (typeof TEXT_VERTICAL)[number];
-/**
- * `ST_PresetLineDashVal` — the dash pattern of a line or border (`a:prstDash/@val`).
+ * Defaults are **per site**, not per interface — a table border's absent `width` is 1 pt, a
+ * chart gridline's is whatever `DEF_CHART_GRIDLINE` says — so each consumer documents its own
+ * rather than this type claiming one for all of them.
  *
- * The `sys*` members are the "system" dashes whose exact dot/gap ratio the renderer picks; the
- * rest are defined by the spec. Both `BorderProps.dashType` and `ShapeLineProps.dashType` accept
- * this whole set, so a caller who knows one knows the other.
- * @see ECMA-376 Part 1 §20.1.10.49
+ * {@link ShapeLineProps} is deliberately *not* an alias: a shape stroke is a **paint**, so its
+ * `type` names a fill kind (`gradient`, `pattern`, …) rather than the three-way dash switch
+ * below. The keys the two share (`width`, `dashType`, `cap`, `transparency`) already agree.
  */
-declare const PRESET_LINE_DASHES: readonly ['solid', 'dot', 'dash', 'lgDash', 'dashDot', 'lgDashDot', 'lgDashDotDot', 'sysDash', 'sysDot', 'sysDashDot', 'sysDashDotDot'];
-type PresetLineDashVal = (typeof PRESET_LINE_DASHES)[number];
-/**
- * The twelve theme colour slots (`a:clrScheme` children) a `p:clrMap` token can point at.
- *
- * Not an `ST_` type — these are element names inside `a:CT_ColorScheme`, which the schema
- * declares as a fixed sequence rather than an enumeration. The effect is the same: a closed,
- * ordered set of twelve names, in the order the scheme declares them.
- * @see ECMA-376 Part 1 §20.1.6.2
- */
-declare const THEME_COLOR_SLOTS: readonly ['dk1', 'lt1', 'dk2', 'lt2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
-type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
-/**
- * The twelve colour-map tokens (`p:clrMap` attributes), in schema attribute order.
- *
- * A slide's `schemeClr val="tx1"` names a *token*, not a slot: the master's `p:clrMap` is the
- * indirection that sends it to a {@link ThemeColorSlot}. Which is why the two lists look alike
- * and are not the same list — `bg1`/`tx1` are tokens, `lt1`/`dk1` are slots.
- * @see ECMA-376 Part 1 §19.3.1.6
- */
-declare const COLOR_MAP_TOKENS: readonly ['bg1', 'tx1', 'bg2', 'tx2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
-type ColorMapToken = (typeof COLOR_MAP_TOKENS)[number];
-//#endregion
-//#region src/types/style.d.ts
-interface BorderProps {
+interface StrokeProps {
   /**
-   * Border type
-   * @default solid
+   * Coarse three-way switch: `'none'` suppresses the stroke, `'dash'` asks for a dashed one,
+   * `'solid'` for an unbroken one.
    */
   type?: 'none' | 'dash' | 'solid';
   /**
-   * Dash pattern, using the same vocabulary as {@link ShapeLineProps.dashType}.
+   * Dash pattern, over the full `ST_PresetLineDashVal` set, so any dash a source deck can
+   * carry can also be authored.
    *
-   * `type` is only a coarse three-way switch, so every dashed border it can express
-   * collapses onto `sysDash`. Set this to pick the exact `a:prstDash` preset instead:
+   * `type` is only a coarse three-way switch, so every dashed stroke it can express collapses
+   * onto `sysDash`. Set this to pick the exact `a:prstDash` preset instead:
    * `dashType: 'lgDashDot'` emits `<a:prstDash val="lgDashDot"/>`.
    *
    * **Precedence.** When both are set, `dashType` wins over `type` for the dash pattern —
    * `{ type: 'solid', dashType: 'sysDot' }` draws a dotted rule. The one exception is
-   * `type: 'none'`, which suppresses the border entirely and is decided before any dash
+   * `type: 'none'`, which suppresses the stroke entirely and is decided before any dash
    * pattern is chosen. An unrecognized value warns and falls back to what `type` implies.
-   * @default (derived from `type`: `sysDash` for `'dash'`, else `solid`)
    * @example { type: 'solid', color: '999999', dashType: 'lgDash' }
    */
-  dashType?: ShapeLineProps['dashType'];
+  dashType?: PresetLineDashVal;
   /**
-   * Border color (hex)
+   * Stroke colour — a 6-digit hex RGB or a `SchemeColor` token.
    * @example 'FF3399'
-   * @default '666666'
+   * @example SchemeColor.accent1
    */
-  color?: HexColor;
+  color?: Color;
   /**
-   * Border width (points)
+   * Stroke width, in points.
    * - MS-PPT > Format Shape > Fill & Line > Line > Width
-   * @default 1
    */
   width?: number;
   /**
-   * Border transparency (percent)
+   * Stroke transparency (percent, 0-100).
    * - MS-PPT > Format Shape > Fill & Line > Line > Transparency
-   * - range: 0-100
    * @default 0
    */
   transparency?: number;
@@ -2302,6 +2744,13 @@ interface BorderProps {
    */
   cap?: LineCap;
 }
+/**
+ * A border is a {@link StrokeProps} under its older name, kept because it reads better on the
+ * four sides of a table cell and on a chart area's outline than "stroke" would.
+ *
+ * Defaults where a table border is drawn: `type: 'solid'`, `color: '666666'`, `width: 1`.
+ */
+type BorderProps = StrokeProps;
 /**
  * Slide-show navigation action for action-button shapes. Each value maps 1:1 onto
  * `ppaction://hlinkshowjump?jump=<value>`. A specific numbered slide is reached via
@@ -2309,9 +2758,8 @@ interface BorderProps {
  */
 type HyperlinkActionJump = 'firstslide' | 'previousslide' | 'nextslide' | 'lastslide' | 'lastslideviewed' | 'endshow';
 interface HyperlinkProps {
-  _rId?: number;
   /**
-   * Slide number to link to
+   * The 1-based number of the slide to link to. The deck has to have that slide when it is written.
    */
   slide?: number;
   /**
@@ -2344,7 +2792,10 @@ interface ShadowProps {
   transparency?: number;
   /**
    * blur (points)
-   * - range: 0-100
+   * - MS-PPT > Format Shape > Effects > Shadow > Blur
+   * - PowerPoint's own spinner stops at 100, but a larger blur is unusual rather than
+   *   invalid: it loads and paints. Only a *negative* blur is rejected (clamped to `0` with
+   *   a `shadow/blur-out-of-range` diagnostic), because the `blurRad` attribute is unsigned.
    * @default 0
    */
   blur?: number;
@@ -2356,7 +2807,10 @@ interface ShadowProps {
   angle?: number;
   /**
    * shadow offset (points)
-   * - range: 0-200
+   * - MS-PPT > Format Shape > Effects > Shadow > Distance
+   * - PowerPoint's own spinner stops at 200, but a larger distance is unusual rather than
+   *   invalid: it loads and paints. Only a *negative* offset is rejected (clamped to `0` with
+   *   a `shadow/offset-out-of-range` diagnostic), because the `dist` attribute is unsigned.
    * @default 0
    */
   offset?: number;
@@ -2371,6 +2825,24 @@ interface ShadowProps {
    */
   rotateWithShape?: boolean;
 }
+/**
+ * What a fill option accepts: a {@link ShapeFillProps} object, or a bare {@link Color} as
+ * shorthand for a solid fill in that colour.
+ *
+ * `'FF0000'` and `{ color: 'FF0000' }` are the same statement and emit the same
+ * `<a:solidFill>` — the shorthand is lossless, not a lesser spelling, and every other key on
+ * the object (`transparency`, `gradient`, `pattern`, `image`) is simply one the shorthand has
+ * no way to say. Reach for the object as soon as you need any of them.
+ *
+ * The shorthand is deliberately **not** offered on {@link ShapeLineProps}. A stroke carries
+ * width and dash alongside its paint, and those defaults are applied by rebuilding the line
+ * object at definition time; a bare string arrives with nothing to rebuild, so it would paint
+ * the colour and silently drop `w` and `prstDash`. A stroke says more than a colour, so it is
+ * spelled as an object.
+ * @example fill: 'FF0000' // solid red
+ * @example fill: { color: 'FF0000', transparency: 50 } // the same red, half transparent
+ */
+type FillOption = Color | ShapeFillProps;
 interface ShapeFillProps {
   /**
    * Fill color
@@ -2400,15 +2872,24 @@ interface ShapeFillProps {
    * On a table cell (`TableCellProps.fill`) and a slide background the two spellings
    * differ the same way, except that *omitting* the option there already means
    * inherit, so `'inherit'` is merely the explicit form of the default.
+   *
+   * **Omitting `type` is not the same as omitting the fill.** Setting `gradient`,
+   * `pattern` or `image` selects that kind on its own — the sub-object is the statement,
+   * and `type` is how you say something the sub-objects cannot. Where both are given and
+   * they disagree, **the explicit `type` wins** and the sub-object is ignored, because
+   * that is the only rule under which `{ type: 'none', gradient }` can still mean
+   * transparent.
    * @default 'solid'
    */
   type?: 'none' | 'inherit' | 'solid' | 'gradient' | 'pattern' | 'image';
   /**
-   * Native PPTX gradient fill options.
+   * Native PPTX gradient fill options. Setting this (or `type: 'gradient'`) paints the
+   * shape interior with a gradient instead of a color.
    */
   gradient?: GradientFillProps;
   /**
-   * Native PPTX pattern fill options.
+   * Native PPTX pattern fill options. Setting this (or `type: 'pattern'`) paints the
+   * shape interior with a two-color preset pattern instead of a color.
    */
   pattern?: PatternFillProps;
   /**
@@ -2416,22 +2897,36 @@ interface ShapeFillProps {
    * shape interior with a stretched bitmap instead of a color.
    */
   image?: ImageFillProps;
-  /**
-   * Resolved media relationship id for an image fill, assigned at add-time.
-   * @internal
-   */
-  _imgRid?: number;
 }
 /**
  * Line (stroke) options.
  *
- * A stroke is painted like a fill: in addition to a solid `color`, it accepts the
- * inherited `gradient`/`pattern`/`image` fill options (DrawingML allows the same
- * fill group inside `<a:ln>`). Setting `gradient` (or `type: 'gradient'`) paints a
- * gradient stroke, e.g. `line: { width: 1, gradient: { kind: 'linear', angle: 0,
- * stops: [{ position: 0, color: 'accent3' }, { position: 100, color: 'accent4' }] } }`.
+ * A stroke is painted much like a fill: in addition to a solid `color`, it accepts the
+ * inherited `gradient` and `pattern` fill options. Setting `gradient` (or
+ * `type: 'gradient'`) paints a gradient stroke, e.g. `line: { width: 1, gradient: {
+ * kind: 'linear', angle: 0, stops: [{ position: 0, color: 'accent3' }, { position: 100,
+ * color: 'accent4' }] } }`.
+ *
+ * **A picture stroke is not one of them**, which is why `image` and `type: 'image'` are
+ * subtracted from the inherited fill props rather than carried. `<a:ln>`'s paint child is
+ * `EG_LineFillProperties` — `a:noFill`, `a:solidFill`, `a:gradFill`, `a:pattFill` and
+ * nothing else — so unlike a shape interior a stroke has no `a:blipFill` slot to put a
+ * bitmap in, and a package that emitted one is what PowerPoint answers with a repair
+ * prompt. The interface carried `image` from `ShapeFillProps` regardless, and no call site
+ * ever registered the media for it, so a picture stroke reached the emitter with no rel and
+ * painted nothing. It is now spelled out as unsupported: a JS caller who sets it anyway
+ * gets `line/image-fill-unsupported`.
+ *
+ * A stroke also does not take the bare-colour shorthand a fill does — see {@link FillOption}
+ * for why. Spell it `line: { color: 'FF0000' }`.
  */
-interface ShapeLineProps extends ShapeFillProps {
+interface ShapeLineProps extends Omit<ShapeFillProps, 'type' | 'image'> {
+  /**
+   * Stroke paint kind. The same vocabulary as {@link ShapeFillProps.type} minus
+   * `'image'`, which `<a:ln>` cannot express (see the note on this interface).
+   * @default 'solid'
+   */
+  type?: 'none' | 'inherit' | 'solid' | 'gradient' | 'pattern';
   /**
    * Line width (pt)
    * @default 1
@@ -2449,13 +2944,13 @@ interface ShapeLineProps extends ShapeFillProps {
    */
   cap?: LineCap;
   /**
-   * Begin arrow type
+   * Begin arrow type — the `ST_LineEndType` set (`a:headEnd/@type`).
    */
-  beginArrowType?: 'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle';
+  beginArrowType?: LineEndType;
   /**
-   * End arrow type
+   * End arrow type — the `ST_LineEndType` set (`a:tailEnd/@type`).
    */
-  endArrowType?: 'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle';
+  endArrowType?: LineEndType;
 }
 /**
  * Connector routing style. Maps to a connector preset geometry. The exact preset
@@ -2503,8 +2998,9 @@ interface ConnectorProps {
    * The shape's `objectName` must be set and unique on the slide. `x1`/`y1` remain the static
    * fallback geometry (and are used if the name can't be resolved).
    *
-   * A shape inside a group is a valid target — group children are named on the same slide — though
-   * the connector itself cannot be a group child (see {@link Slide.addGroup}).
+   * A shape inside a group is a valid target — group children are named on the same slide. The
+   * connector itself is not an {@link Slide.addGroup} child, but {@link Slide.groupObjects} can
+   * group one that is already on the slide.
    */
   startShape?: string;
   /**
@@ -2530,7 +3026,7 @@ interface ConnectorProps {
   y2: Coord;
   /**
    * Line color (6-digit hex, no `#`)
-   * @default '000000'
+   * @default '333333'
    */
   color?: HexColor;
   /**
@@ -2625,6 +3121,13 @@ type DataOrPathRequiredProps = (DataOrPathProps & {
   path: string;
 });
 interface BackgroundProps extends DataOrPathProps, ShapeFillProps {}
+/**
+ * What a `background` option accepts: a {@link BackgroundProps} object, or a bare
+ * {@link Color} as shorthand for a solid background in that colour — the same shorthand
+ * every other fill site takes (see `FillOption`).
+ * @example background: 'FF3399' // shorthand for { color: 'FF3399' }
+ */
+type BackgroundOption = BackgroundProps | Color;
 /**
  * Color in Hex format
  * @example 'FF3399'
@@ -2722,6 +3225,27 @@ interface ImageFillProps {
   path?: string;
   /** Pre-encoded base64 data URI, e.g. `'image/png;base64,iVBOR...'`. */
   data?: string;
+  /**
+   * Crop the source image to a sub-region by percentage edge insets, emitted as
+   * DrawingML `<a:srcRect>`.
+   * - each value is the percent (0–100) trimmed from that edge of the source image
+   * - `l` + `r` and `t` + `b` must each be less than 100
+   * - omitted edges default to 0
+   *
+   * This is the source-image crop used by native Shape picture fills. The
+   * remaining region is stretched to fill the shape's bounding box and then
+   * clipped by the shape geometry.
+   */
+  crop?: {
+    /** Percent trimmed from the left edge of the source image. @default 0 */
+    l?: number;
+    /** Percent trimmed from the top edge of the source image. @default 0 */
+    t?: number;
+    /** Percent trimmed from the right edge of the source image. @default 0 */
+    r?: number;
+    /** Percent trimmed from the bottom edge of the source image. @default 0 */
+    b?: number;
+  };
 }
 type Margin = number | [number, number, number, number];
 type HAlign = 'left' | 'center' | 'right' | 'justify';
@@ -2774,1153 +3298,227 @@ type GeometryPoint = {
   close: true;
 };
 //#endregion
-//#region src/types/table.d.ts
+//#region src/types/theme.d.ts
 /**
- * A `<table>` element, from whatever DOM implementation the caller has.
+ * Theme color scheme overrides. Each slot maps to one `<a:clrScheme>` entry in `theme1.xml`;
+ * any slot left unset keeps the default Office value. Provide 6-digit hex (no `#`).
  *
- * Deliberately *not* `lib.dom`'s `Element`. `lib.dom`'s types are built for a browser, and a
- * non-browser DOM's element type — happy-dom's, jsdom's — declares its own members and does
- * not satisfy them, so demanding `Element` would reject from TypeScript exactly the
- * implementations `ts-pptx/html` exists to accept. Requiring the three members the conversion
- * actually calls keeps a mistyped argument an error while letting every real DOM through.
+ * Slot names use the OOXML scheme names. The PowerPoint UI labels them as:
+ * `dk1`=Text/Dark 1, `lt1`=Background/Light 1, `dk2`=Text/Dark 2, `lt2`=Background/Light 2,
+ * `accent1`-`accent6`=Accent 1-6, `hlink`=Hyperlink, `folHlink`=Followed Hyperlink.
+ * @example { accent1: 'C00000', dk2: '1F3864', hlink: '0070C0' }
  */
-interface TableToSlidesElement {
-  getAttribute: (name: string) => string | null;
-  querySelector: (selectors: string) => unknown;
-  querySelectorAll: (selectors: string) => unknown;
+interface ThemeColorScheme {
+  /** Text/Dark 1 (default Office: black via `windowText`) */
+  dk1?: HexColor;
+  /** Background/Light 1 (default Office: white via `window`) */
+  lt1?: HexColor;
+  /** Text/Dark 2 (default Office: `44546A`) */
+  dk2?: HexColor;
+  /** Background/Light 2 (default Office: `E7E6E6`) */
+  lt2?: HexColor;
+  /** Accent 1 (default Office: `4472C4`) */
+  accent1?: HexColor;
+  /** Accent 2 (default Office: `ED7D31`) */
+  accent2?: HexColor;
+  /** Accent 3 (default Office: `A5A5A5`) */
+  accent3?: HexColor;
+  /** Accent 4 (default Office: `FFC000`) */
+  accent4?: HexColor;
+  /** Accent 5 (default Office: `5B9BD5`) */
+  accent5?: HexColor;
+  /** Accent 6 (default Office: `70AD47`) */
+  accent6?: HexColor;
+  /** Hyperlink (default Office: `0563C1`) */
+  hlink?: HexColor;
+  /** Followed Hyperlink (default Office: `954F72`) */
+  folHlink?: HexColor;
+}
+interface ThemeProps {
+  /**
+   * Headings font face name
+   * @example 'Arial Narrow'
+   * @default 'Calibri Light'
+   */
+  headFontFace?: string;
+  /**
+   * Body font face name
+   * @example 'Arial'
+   * @default 'Calibri'
+   */
+  bodyFontFace?: string;
+  /**
+   * Headings East Asian font face — theme `<a:ea>` slot of the major font.
+   * Used for CJK (Chinese/Japanese/Korean) runs that fall back to the theme font.
+   * - leave unset to keep PowerPoint's empty default (auto-resolved per script)
+   * @example 'Yu Gothic'
+   */
+  headFontFaceEA?: string;
+  /**
+   * Body East Asian font face — theme `<a:ea>` slot of the minor font.
+   * Used for CJK (Chinese/Japanese/Korean) runs that fall back to the theme font.
+   * - leave unset to keep PowerPoint's empty default (auto-resolved per script)
+   * @example 'Yu Gothic'
+   */
+  bodyFontFaceEA?: string;
+  /**
+   * Headings complex-script font face — theme `<a:cs>` slot of the major font.
+   * Used for complex scripts such as Arabic, Hebrew, Thai, and Devanagari.
+   * - leave unset to keep PowerPoint's empty default (auto-resolved per script)
+   * @example 'Arial'
+   */
+  headFontFaceCS?: string;
+  /**
+   * Body complex-script font face — theme `<a:cs>` slot of the minor font.
+   * Used for complex scripts such as Arabic, Hebrew, Thai, and Devanagari.
+   * - leave unset to keep PowerPoint's empty default (auto-resolved per script)
+   * @example 'Arial'
+   */
+  bodyFontFaceCS?: string;
+  /**
+   * Theme color scheme overrides written to `ppt/theme/theme1.xml`.
+   * - any unset slot keeps its default Office value
+   * - references such as `SchemeColor.accent1` resolve against these values
+   * @example { accent1: 'C00000', accent2: '00B050', hlink: '0070C0' }
+   */
+  colorScheme?: ThemeColorScheme;
 }
-/**
- * The one thing `tableToSlides` asks a document for. Structural for the same reason
- * {@link TableToSlidesElement} is.
- */
-interface TableToSlidesDocument {
-  getElementById: (elementId: string) => TableToSlidesElement | null;
-}
-interface TableToSlidesProps extends TableProps {
-  _arrObjTabHeadRows?: TableRow[];
-  /**
-   * Add an image to slide(s) created during autopaging
-   * - `image` prop requires either `path` or `data`
-   * - see `DataOrPathProps` for details on `image` props
-   * - see `PositionProps` for details on `options` props
-   */
-  addImage?: {
-    image: DataOrPathProps;
-    options: PositionProps;
-  };
-  /**
-   * Add a shape to slide(s) created during autopaging
-   */
-  addShape?: {
-    shapeName: SHAPE_NAME;
-    options: ShapeProps;
-  };
-  /**
-   * Add a table to slide(s) created during autopaging
-   */
-  addTable?: {
-    rows: TableRow[];
-    options: TableProps;
-  };
-  /**
-   * Add a text object to slide(s) created during autopaging
-   */
-  addText?: {
-    text: TextProps[];
-    options: TextPropsOptions;
-  };
+//#endregion
+//#region src/types/pres.d.ts
+interface WriteBaseProps {
   /**
-   * Whether to enable auto-paging
-   * - auto-paging creates new slides as content overflows a slide
+   * Whether to DEFLATE-compress the package (PowerPoint itself always compresses;
+   * set `false` only if export time matters more than file size)
    * @default true
    */
-  autoPage?: boolean;
-  /**
-   * Auto-paging character weight
-   * - adjusts how many characters are used before lines wrap
-   * - range: -1.0 to 1.0
-   * @default 0.0
-   * @example 0.5 // lines are longer (increases the number of characters that can fit on a given line)
-   */
-  autoPageCharWeight?: number;
-  /**
-   * Auto-paging line weight
-   * - adjusts how many lines are used before slides wrap
-   * - range: -1.0 to 1.0
-   * @default 0.0
-   * @example 0.5 // tables are taller (increases the number of lines that can fit on a given slide)
-   */
-  autoPageLineWeight?: number;
-  /**
-   * Whether to repeat head row(s) on new tables created by autopaging
-   * @default false
-   */
-  autoPageRepeatHeader?: boolean;
-  /**
-   * The `y` location to use on subsequent slides created by autopaging
-   * @default (top margin of Slide)
-   */
-  autoPageSlideStartY?: number;
-  /**
-   * Column widths (inches)
-   */
-  colW?: number | number[];
-  /**
-   * Document to resolve a table *id* against.
-   * - only consulted when the table is identified by string id; passing the element itself
-   *   needs no document, since one is reached through the element's `ownerDocument`
-   * - defaults to the global `document`, which is what a browser caller gets
-   * - supply this to convert a table outside a browser (any DOM implementation will do)
-   */
-  document?: TableToSlidesDocument;
-  /**
-   * Title of the slide master to use for the auto-paged slides (the `title` passed to
-   * `defineSlideMaster`). Matches the `masterTitle` option of `addSlide`.
-   * - define a master slide to have your auto-paged slides carry a corporate design, etc.
-   */
-  masterTitle?: string;
-  /**
-   * Slide margin
-   * - this margin will be across all slides created by auto-paging
-   */
-  slideMargin?: Margin;
-}
-/**
- * A table cell's corner-to-corner rules (`a:tcPr/a:lnTlToBr` / `a:lnBlToTr`) — the
- * "Diagonal Down Border" / "Diagonal Up Border" of PowerPoint's border gallery.
- *
- * Deliberately its own object rather than two more entries on {@link TableCellProps.border}'s
- * tuple: widening that tuple to six would break every existing caller for a construct almost
- * no deck uses, and the two diagonals are not edges — they do not participate in the
- * perimeter, and they are not inherited by a merged region's covered cells.
- *
- * @example diagonal: { tlToBr: { type:'solid', color:'C00000', width:1 } } // strike a cell out
- * @example diagonal: { tlToBr: { type:'solid' }, blToTr: { type:'solid' } } // an X across the cell
- */
-interface TableCellDiagonals {
-  /** Top-left to bottom-right (`╲`, `a:lnTlToBr`). */
-  tlToBr?: BorderProps;
-  /** Bottom-left to top-right (`╱`, `a:lnBlToTr`). */
-  blToTr?: BorderProps;
-}
-/**
- * A cell's 3-D bevel (`a:tcPr/a:cell3D`).
- *
- * A minimal surface over `CT_Cell3D`, which is a required `a:bevel` plus an optional
- * `a:lightRig`. PowerPoint's table UI exposes no control for it — it reaches a deck through a
- * theme's table style or through another producer — so this exists to author and reproduce
- * one, not as a general 3-D model.
- */
-interface TableCell3DProps {
-  /**
-   * The bevel's preset shape (`a:bevel/@prst`).
-   * @default 'circle'
-   */
-  preset?: BevelPresetType;
-  /**
-   * Bevel width in points (`a:bevel/@w`; the attribute is EMU).
-   * @default 6 // 76200 EMU
-   */
-  width?: number;
-  /**
-   * Bevel height in points (`a:bevel/@h`; the attribute is EMU).
-   * @default 6 // 76200 EMU
-   */
-  height?: number;
-  /**
-   * Surface material (`a:cell3D/@prstMaterial`), which decides how the bevel takes light.
-   * @default 'plastic'
-   */
-  material?: PresetMaterialType;
-  /**
-   * Scene lighting (`a:cell3D/a:lightRig`). Both fields are required by the schema, so
-   * either give both or omit the whole object and let the renderer light the bevel.
-   * @example lightRig: { rig: 'threePt', dir: 't' }
-   */
-  lightRig?: {
-    rig: LightRigType;
-    dir: LightRigDirection;
-  };
-}
-interface TableCellProps extends TextBaseProps {
-  /**
-   * Auto-paging character weight
-   * - adjusts how many characters are used before lines wrap
-   * - range: -1.0 to 1.0
-   * @default 0.0
-   * @example 0.5 // lines are longer (increases the number of characters that can fit on a given line)
-   */
-  autoPageCharWeight?: number;
-  /**
-   * Auto-paging line weight
-   * - adjusts how many lines are used before slides wrap
-   * - range: -1.0 to 1.0
-   * @default 0.0
-   * @example 0.5 // tables are taller (increases the number of lines that can fit on a given slide)
-   */
-  autoPageLineWeight?: number;
-  /**
-   * The cell's four edge borders (`a:tcPr/a:lnT|lnR|lnB|lnL`).
-   * - a single `BorderProps` is broadcast to all four sides
-   * - an array is read in **TRBL** order (`[top, right, bottom, left]`)
-   *
-   * Overrides the table-level {@link TableProps.border} default entirely — the two do not
-   * merge per side. A `null` entry is a hole: that edge is left out of `a:tcPr` and keeps
-   * inheriting from the table style, while `{ type: 'none' }` writes an explicit no-line
-   * that overrides it. For the two corner-to-corner rules see {@link diagonal}; for the
-   * table's outside edge see {@link TableProps.outerBorder}.
-   */
-  border?: BorderProps | [BorderProps | null, BorderProps | null, BorderProps | null, BorderProps | null];
-  /**
-   * The cell's corner-to-corner rules — PowerPoint's "Diagonal Down/Up Border".
+  compression?: boolean;
+  /**
+   * How to handle a media asset (image/audio/video) that fails to load during export.
+   * - `'throw'` (default): reject the export with an error naming the failing asset. A deck
+   *   that silently embeds a broken-image placeholder is a degenerate result, so failing
+   *   loudly is the safe default.
+   * - `'placeholder'`: substitute a broken-image placeholder, emit a `media/load-failed`
+   *   diagnostic (see `setDiagnosticHandler`), and
+   *   continue. Useful for best-effort/batch jobs where one missing asset should not abort
+   *   the whole deck. An OLE object's or a 3D model's payload still rejects the export: the
+   *   placeholder is a picture, and written into a `.xlsx` or `.glb` part it is a part
+   *   PowerPoint cannot open.
    *
-   * Kept off {@link border}'s tuple on purpose: see {@link TableCellDiagonals}. A diagonal
-   * on a merged cell is one stroke across the whole region, so only the span origin carries
-   * it — the covered cells inherit the origin's *edges* but never its diagonals.
-   * @example diagonal: { tlToBr: { type:'solid', color:'C00000' } } // strike the cell out
+   * An SVG that loads but cannot be rasterized into the PNG fallback written beside it (in a
+   * browser, one that does not decode or has no intrinsic size) is reported as
+   * `media/svg-preview-failed` instead, whether it was given by `path` or inline: the export
+   * rejects with it under `'throw'`, and under `'placeholder'` it is warned, the SVG part keeps
+   * its bytes and only the PNG fallback is a placeholder. A runtime with no rasterizer (Node,
+   * the neutral entry) always writes that placeholder, and reports nothing.
+   * @default 'throw'
    */
-  diagonal?: TableCellDiagonals;
-  /**
-   * Centre the cell's whole text **block** horizontally within the cell
-   * (`a:tcPr/@anchorCtr`), independent of each paragraph's own `align`.
-   *
-   * The two do different things and compose: `align` decides where each line sits inside
-   * the text block, `anchorCtr` decides where that block sits inside the cell. With
-   * left-aligned text in a wide cell, `anchorCtr: true` centres the ragged-right column of
-   * lines as a unit while keeping their left edges flush with each other.
-   *
-   * `false` is the schema default, so it emits nothing — the same reasoning as
-   * `horzOverflow: 'clip'`.
-   * @default false
-   */
-  anchorCtr?: boolean;
-  /**
-   * A 3-D bevel on the cell (`a:tcPr/a:cell3D`). Niche: PowerPoint's table UI has no
-   * control for it, so it reaches a deck from a theme or another producer, and this exists
-   * to author and reproduce one. See {@link TableCell3DProps}.
-   */
-  cell3D?: TableCell3DProps;
-  /**
-   * Cell colspan
-   */
-  colspan?: number;
-  /**
-   * Cell fill — a solid color, or a picture that fills the cell (`a:blipFill` in
-   * the cell's `a:tcPr`, stretched to the cell box). A picture fill embeds the
-   * image as slide media; identical sources are embedded once. Raster only —
-   * an SVG source warns and is ignored, matching shape fills.
-   * @example { color:'FF0000' } // hex color (red)
-   * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
-   * @example { color:SchemeColor.accent1 } // theme color Accent1
-   * @example { type:'image', image:{ path:'logo.png' } } // picture fill
-   * @example { image:{ data:'image/png;base64,…' } } // picture fill, `type` inferred
-   */
-  fill?: ShapeFillProps;
-  /**
-   * What happens to a **single glyph** wider than the cell's text width (`a:tcPr/@horzOverflow`).
-   * - `'clip'` (PowerPoint's default) cuts the glyph off at the cell edge
-   * - `'overflow'` lets it draw past the edge, over whatever is beside it
-   *
-   * This is **not** a text-wrap switch, despite the name. Lines always wrap to the column
-   * width; only an individual character too wide to fit on a line by itself is affected, so
-   * it matters for oversized display type, wide CJK/emoji glyphs, and icon fonts in a narrow
-   * column. PowerPoint has no per-cell no-wrap at all — `wrap="none"` on a cell's `a:bodyPr`
-   * is discarded on the next save (probe:
-   * `test/read/fixtures/authoring/probe-table-cell-wrap.ps1`).
-   * `'clip'` is written as asked but is the schema default, so PowerPoint drops the
-   * attribute again the first time it saves the deck — the visible result is the same
-   * either way, and leaving this unset emits nothing at all.
-   * @default (unset — PowerPoint clips)
-   * @example 'overflow' // a 60pt glyph in a 0.5in column draws whole instead of being cut
-   */
-  horzOverflow?: 'clip' | 'overflow';
-  hyperlink?: HyperlinkProps;
-  /**
-   * Cell margin (inches)
-   * @default 0
-   */
-  margin?: Margin;
-  /**
-   * Cell rowspan
-   */
-  rowspan?: number;
-  /**
-   * Shrink cell text to fit when it would overflow the cell's fixed height.
-   * - `'shrink'` measures the wrapped text and bakes a **reduced literal font size**
-   *   onto the cell's runs so the text fits — PowerPoint does not support text
-   *   autofit (`normAutofit`) inside table cells, so there is no font-scale flag to
-   *   set; the size itself is lowered, which both PowerPoint and LibreOffice render
-   *   identically with no edit/resize.
-   * - Requires the cell font registered via {@link TsPptx.registerFontMetrics};
-   *   without metrics it is a no-op (the cell keeps its authored size) and warns once.
-   * - Only triggers when the cell's row has a **fixed** height that the text exceeds.
-   *   With auto-height rows (no `rowH`/`h`), the row simply grows, so nothing shrinks.
-   * - Only `'shrink'` is acted on for cells. `'resize'` and the object form are ignored
-   *   here: a table row already auto-grows to fit its tallest cell (the cell equivalent
-   *   of `spAutoFit`), so there is nothing to bake. (The wider union is shared with
-   *   {@link TextPropsOptions.fit} so table-level `fit` can cascade to cells.)
-   * @example 'shrink' // measured when the cell font is registered; else no-op
-   */
-  fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
-}
-interface TableProps extends PositionProps, TextBaseProps, ObjectNameProps {
-  _arrObjTabHeadRows?: TableRow[];
-  /**
-   * Name of a table/content placeholder defined on the slide layout/master to bind this table to.
-   * - when it matches a layout/master placeholder, the table's `<p:graphicFrame>` emits that
-   *   placeholder's `<p:ph>` (idx/type) so PowerPoint treats the table as filling the placeholder
-   *   (e.g. a "Title and Content" content placeholder)
-   * - the table also inherits the placeholder's position/size for any of x/y/w/h left unset
-   * @example 'body' // bind to the layout placeholder named 'body'
-   */
-  placeholder?: string;
-  /**
-   * Whether to enable auto-paging
-   * - auto-paging creates new slides as content overflows a slide
-   * @default false
-   */
-  autoPage?: boolean;
-  /**
-   * Auto-paging character weight
-   * - adjusts how many characters are used before lines wrap
-   * - range: -1.0 to 1.0
-   * @default 0.0
-   * @example 0.5 // lines are longer (increases the number of characters that can fit on a given line)
-   */
-  autoPageCharWeight?: number;
-  /**
-   * Auto-paging line weight
-   * - adjusts how many lines are used before slides wrap
-   * - range: -1.0 to 1.0
-   * @default 0.0
-   * @example 0.5 // tables are taller (increases the number of lines that can fit on a given slide)
-   */
-  autoPageLineWeight?: number;
-  /**
-   * Whether table header row(s) should be repeated on each new slide creating by autoPage.
-   * Use `autoPageHeaderRows` to designate how many rows comprise the table header (1+).
-   * @default false
-   */
-  autoPageRepeatHeader?: boolean;
-  /**
-   * Number of rows that comprise table headers
-   * - required when `autoPageRepeatHeader` is set to true.
-   * @example 2 - repeats the first two table rows on each new slide created
-   * @default 1
-   */
-  autoPageHeaderRows?: number;
-  /**
-   * The `y` location to use on subsequent slides created by autopaging
-   * @default (top margin of Slide)
-   */
-  autoPageSlideStartY?: number;
-  /**
-   * Whether populated placeholders on the source slide (e.g. a title set via
-   * `addText(text, { placeholder })`) are copied onto each overflow slide created by autoPage.
-   * - new slides otherwise inherit only the layout's empty placeholders, so a title set on the
-   *   first slide would not appear on continuation slides.
-   * @default false
-   */
-  autoPagePlaceholder?: boolean;
-  /**
-   * Default border for **every cell** in the table — not the table's outer perimeter.
-   *
-   * A single `BorderProps` is broadcast to all four sides of each cell; an array is read
-   * in TRBL order and applied to each cell's own four sides. So
-   * `border: [{type:'solid'}, {type:'none'}, {type:'solid'}, {type:'none'}]` gives *every*
-   * cell a top and bottom rule — a full set of horizontal grid lines, not a rule at the
-   * top and bottom of the table. A cell's own `options.border` overrides this entirely.
-   *
-   * A `null` entry is a hole — that edge inherits from the table style — where
-   * `{ type: 'none' }` writes an explicit no-line that overrides it. Authoring nothing at
-   * all depends on {@link tableStyle}: a styled table leaves every edge absent so the style
-   * paints its grid, and a table with no style takes four no-fill sides, which is what keeps
-   * it clear of PowerPoint's no-style black hairline grid.
-   *
-   * For the perimeter, use {@link outerBorder}, which applies only to the cells on the
-   * table's outside edge. The two compose: `border` draws the interior grid and
-   * `outerBorder` overrides the edges it reaches.
-   * @example border: { type:'solid', color:'D9D9D9', width:0.5 } // full grid
-   * @example border: [{type:'solid'}, {type:'none'}, {type:'solid'}, {type:'none'}] // horizontal rules only
-   */
-  border?: BorderProps | [BorderProps | null, BorderProps | null, BorderProps | null, BorderProps | null];
-  /**
-   * Border for the table's outer perimeter only — the top edge of the first row, the
-   * bottom edge of the last row, the left edge of the first column and the right edge of
-   * the last column.
-   *
-   * A single `BorderProps` is used for all four perimeter sides; an array is read in TRBL
-   * order, so `outerBorder: [box, box, box, box]` boxes the table and
-   * `outerBorder: [rule, undefined, rule, undefined]` rules only above and below it.
-   * An `undefined`/omitted entry leaves that side to whatever {@link border} (or the cell's
-   * own `options.border`) already put there.
-   *
-   * Applied **after** every other border source, so it wins on the sides it touches and
-   * leaves the interior alone — the "outline the table, no interior grid" case is
-   * `outerBorder` with no `border` at all. Merged cells are handled: a span's covered cells
-   * inherit the origin's borders, so a colspan straddling the last column still gets the
-   * right-hand rule.
-   * @example outerBorder: { type:'solid', color:'1A2B3C', width:1 } // box the table
-   * @example outerBorder: [{type:'solid'}, undefined, {type:'solid'}, undefined] // rules above and below
-   */
-  outerBorder?: BorderProps | [BorderProps?, BorderProps?, BorderProps?, BorderProps?];
-  /**
-   * Width of table columns (inches)
-   * - single value is applied to every column equally based upon `w`
-   * - array of values in applied to each column in order
-   * @default columns of equal width based upon `w`
-   */
-  colW?: number | number[];
-  /**
-   * Shrink columns proportionally so a too-wide table fits the slide.
-   * - `'shrink'`: if the total column width exceeds the space available between
-   *   the table's `x` and the right slide margin, scale every column down by the
-   *   same factor so the whole table fits. Columns that already fit are untouched.
-   * - applies to an explicit `colW` array (the common "too many columns" case) and
-   *   to a `w` wider than the slide; never grows columns and never enforces a
-   *   minimum width, so a very high column count can still become thin.
-   * - opt-in: explicit widths are otherwise emitted as-is and may run off the slide.
-   * @default undefined (no scaling)
-   */
-  fitColumns?: 'shrink';
-  /**
-   * Table-level text-fit policy, cascaded to every cell that does not set its own
-   * {@link TableCellProps.fit}.
-   * - `'shrink'`: each cell whose row has a **fixed** height that its wrapped text
-   *   would exceed gets a reduced literal font size baked onto its runs so the text
-   *   fits (see {@link TableCellProps.fit} for the full semantics and the font-metrics
-   *   requirement). Cells that set their own `fit` win over this table default.
-   * - `'none'` / `'resize'` / the object form are accepted for parity with
-   *   {@link TextPropsOptions.fit} but only `'shrink'` is acted on for table cells.
-   * @default undefined (cells keep their authored size)
-   * @example 'shrink'
-   */
-  fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
-  /**
-   * Mark the first row as a header row.
-   * Emits `firstRow="1"` on `<a:tblPr>`, activating the first-row style region of
-   * the table style and satisfying the PowerPoint accessibility checker's "table header" rule.
-   * @default false
-   */
-  hasHeader?: boolean;
-  /**
-   * Mark the last row as a footer row.
-   * Emits `lastRow="1"` on `<a:tblPr>`, activating the last-row style region.
-   * Requires `tableStyle` to have a visible effect.
-   * @default false
-   */
-  hasFooter?: boolean;
-  /**
-   * Enable alternating row (band) shading.
-   * Emits `bandRow="1"` on `<a:tblPr>`, activating band1H/band2H style regions.
-   * Requires `tableStyle` to have a visible effect.
-   * @default false
-   */
-  hasBandedRows?: boolean;
-  /**
-   * Enable alternating column (band) shading.
-   * Emits `bandCol="1"` on `<a:tblPr>`, activating band1V/band2V style regions.
-   * Requires `tableStyle` to have a visible effect.
-   * @default false
-   */
-  hasBandedColumns?: boolean;
-  /**
-   * Apply special styling to the first column.
-   * Emits `firstCol="1"` on `<a:tblPr>`, activating the firstCol style region.
-   * Requires `tableStyle` to have a visible effect.
-   * @default false
-   */
-  hasFirstColumn?: boolean;
-  /**
-   * Apply special styling to the last column.
-   * Emits `lastCol="1"` on `<a:tblPr>`, activating the lastCol style region.
-   * Requires `tableStyle` to have a visible effect.
-   * @default false
-   */
-  hasLastColumn?: boolean;
-  /**
-   * Lay the table out right-to-left.
-   * Emits `rtl="1"` on `<a:tblPr>`, which mirrors the column order so the first
-   * column renders on the right — the correct layout for RTL scripts (Arabic, Hebrew).
-   * This controls only the table/column direction; per-cell text direction is set
-   * with each cell's `rtlMode` option.
-   * @default false
-   */
-  rtl?: boolean;
-  /**
-   * Built-in table style to apply, as a `TableStyle` member.
-   * Emits `<a:tableStyleId>` inside `<a:tblPr>` with the corresponding GUID.
-   * Style flags (`hasHeader`, `hasFooter`, `hasBandedRows`, etc.) select which
-   * regions of the chosen style are activated; they have no visible effect without
-   * a `tableStyle` set.
-   *
-   * **Only a built-in GUID renders.** PowerPoint resolves `<a:tableStyleId>` against
-   * its own table-style gallery and never reads a style definition out of the package,
-   * so a GUID it does not recognise leaves the table with PowerPoint's no-style look —
-   * a black hairline grid. For brand colours use direct formatting instead:
-   * `headerRow`, `columns[i]`, the table-level {@link border} / {@link fill}, or per-cell
-   * options. See `docs/tables.md` → "Table styles".
-   *
-   * @example tableStyle: pptx.TableStyle.MEDIUM_STYLE_2_ACCENT_1
-   */
-  tableStyle?: TableStyle;
-  /**
-   * Inline styling for the header (first) row, applied as direct per-cell formatting.
-   *
-   * This is how a header is styled distinctly from the body: each property is merged
-   * onto every cell of row 0 (`fill`, `color`, `bold`, `align`, `border`, etc.).
-   *
-   * Precedence (highest wins), matching how PowerPoint resolves styling — direct cell
-   * formatting overrides a table-style region:
-   * 1. explicit per-cell `options` on a row-0 cell
-   * 2. this `headerRow`
-   * 3. the `firstRow` region of a built-in `tableStyle`
-   * 4. the library's per-cell defaults
-   *
-   * Setting `headerRow` also implies `hasHeader: true` (emits `firstRow="1"` for the
-   * accessibility "table header" marker) unless `hasHeader` is explicitly set to `false`.
-   * @example headerRow: { fill: { color:'1A2B3C' }, color:'FFFFFF', bold:true, align:'center' }
-   */
-  headerRow?: TableCellProps;
-  /**
-   * Per-column default cell styling, applied as direct per-cell formatting.
-   *
-   * `columns[i]` is merged onto every cell that starts in column `i` (`fill`, `color`,
-   * `bold`, `align`, `valign`, `border`, `margin`, …), so a wide **colored** matrix —
-   * per-column fills, maturity-gradient headers — does not require hand-writing a fill
-   * onto every cell. Entries may be sparse (`columns[2]` alone styles only column 2);
-   * an `undefined`/omitted entry leaves that column untouched. The whole option is
-   * optional and degrades cleanly to today's text-on-white when not given.
-   *
-   * Precedence (highest wins), matching how PowerPoint resolves styling — direct cell
-   * formatting overrides a table-style region:
-   * 1. explicit per-cell `options`
-   * 2. `headerRow` (row 0 only)
-   * 3. this `columns[colIdx]`
-   * 4. a built-in `tableStyle` / the library's per-cell defaults
-   *
-   * The merge is property-level, so a header cell keeps `headerRow`'s typography **and**
-   * takes its column's `fill` when they set different properties. For a graduated header
-   * band, put shared header typography (bold/white/centered, **no fill**) in `headerRow`
-   * and let each `columns[i].fill` supply that column's fill.
-   *
-   * Column index counts each cell's `colspan` (default 1) within a row, so merged cells
-   * map to the correct column; it does not track `rowspan`s inherited from earlier rows.
-   *
-   * There is deliberately no built-in "group bracket" annotation. Label a span of columns
-   * by composing existing primitives: `addShape('rightBrace', …)` (or `'bracePair'`) plus
-   * `addText`, positioned from the table's `x` and `colW` (a span's `x`/`w` is the running
-   * sum of the preceding/covered column widths).
-   *
-   * @example columns: [{}, { fill: { color:'E8F0FE' } }, { fill: { color:'C6DAFC' } }] // per-column solid fills
-   * @example // gradient header: shared typography on headerRow, graduated fills per column
-   * headerRow: { color:'FFFFFF', bold:true, align:'center' },
-   * columns: [{}, { fill:{color:'BBD3FB'} }, { fill:{color:'89AEF6'} }, { fill:{color:'4B7BE5'} }]
-   */
-  columns?: TableCellProps[];
-  /**
-   * Default cell background — **stamped onto every cell**, not painted behind the table.
-   *
-   * Each cell that does not set its own `options.fill` (or take one from `headerRow` /
-   * `columns[i]`) gets this as its own `a:tcPr` fill. A picture fill is embedded once and
-   * shared by every cell that inherits it.
-   *
-   * Visually this is usually what you want, but it is not what a source deck contains, and
-   * it has one real consequence: because every cell ends up explicitly filled, a cell that
-   * later gets its own fill has nothing to fall back to. For a genuine table background —
-   * one `a:tblPr` fill that cells sit on top of — use {@link tableFill}.
-   * @example { color:'FF0000' } // hex color (red)
-   * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
-   * @example { color:SchemeColor.accent1 } // theme color Accent1
-   * @example { type:'image', image:{ path:'watermark.png' } } // picture fill
-   */
-  fill?: ShapeFillProps;
-  /**
-   * The table's own background (`a:tblPr` fill) — one fill behind the whole table that
-   * every cell sits on top of.
-   *
-   * The counterpart to {@link fill}, and the difference is where the paint lands rather
-   * than how it looks: `fill` copies a colour onto every cell, while this writes a single
-   * fill on the table itself. That matters when a cell is meant to be transparent — with
-   * `tableFill`, an unfilled cell shows the table background through; with `fill` there is
-   * no such thing as an unfilled cell. It is also what a deck read back from PowerPoint
-   * actually carries, so a replica reproduces the source's structure rather than an
-   * equivalent-looking flattening of it.
-   *
-   * Takes the same `ShapeFillProps` a cell does — solid, gradient, pattern or picture.
-   * @example { color:'F2F2F2' } // a light background behind the whole table
-   * @example { type:'image', image:{ path:'watermark.png' } } // one watermark, not one per cell
-   */
-  tableFill?: ShapeFillProps;
-  /**
-   * Cell margin (inches)
-   * - affects all table cells, is superceded by cell options
-   */
-  margin?: Margin;
-  /**
-   * Height of table rows (inches)
-   * - single value is applied to every row equally based upon `h`
-   * - array of values in applied to each row in order
-   * @default rows of equal height based upon `h`
-   */
-  rowH?: number | number[];
-  /**
-   * DEV-ONLY diagnostic flag: when `true`, logs a verbose trace of the auto-paging
-   * calculations to the console. Intended for debugging table layout only; leave unset
-   * in production. Inherited by {@link TableToSlidesProps}.
-   * @default false
-   */
-  verbose?: boolean;
-}
-interface TableCell {
-  _type?: SlideObjectType.tablecell;
-  /** lines in this cell (autoPage) */
-  _lines?: TableCell[][];
-  /** `text` prop but guaranteed to hold "TableCell[]" */
-  _tableCells?: TableCell[];
-  /** height in EMU */
-  _lineHeight?: number;
-  _hmerge?: boolean;
-  _vmerge?: boolean;
-  _rowContinue?: number;
-  /** origin cell of a colspan/rowspan span, set on the dummy `_hmerge`/`_vmerge` cells so they can
-   * inherit the origin's border/fill and render the merged region's outer edges */
-  _spanOrigin?: TableCell;
-  /**
-   * Cell content: a plain string, or an array of `TableCell` runs for mixed formatting.
-   * (A `number` is still coerced to a string at runtime for plain-JS callers, but is no
-   * longer part of the type — pass `String(n)` from TypeScript.)
-   */
-  text?: string | TableCell[];
-  options?: TableCellProps;
-}
-interface TableRowSlide {
-  rows: TableRow[];
-  /**
-   * Per-row height (inches) aligned 1:1 with `rows`, derived from the original `rowH` array.
-   * Auto-paging splits/reorders rows across slides and inserts repeated headers, so the caller's
-   * `rowH[i]` (keyed by *original* row index) can no longer be applied by physical row index on
-   * each generated slide. This carries each output row's resolved height so a configured height
-   * follows its source row instead of being re-applied to whatever lands at that index.
-   * Entries are `undefined` where no explicit height was configured (auto-distributed height).
-   */
-  rowH?: Array<number | undefined>;
-}
-type TableRow = TableCell[];
-//#endregion
-//#region src/types/animation.d.ts
-/**
- * Slide transition and animation types.
- *
- * Re-exported by `./index.js`, which is the import site for the rest of `src/`.
- */
-/**
- * Base ECMA-376 slide-transition type (`p:transition`'s single type child). Each
- * maps to a `<p:TYPE/>` element; type-specific variants (e.g. direction) go in
- * {@link TransitionProps.variant}. Modern PowerPoint-only transitions (Morph,
- * Vortex, …) live in the `p14`/`p15`/`p159` namespaces and are out of authoring
- * scope for now. See `docs/animations-and-transitions.md`.
- */
-type TransitionType = 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'cut' | 'diamond' | 'dissolve' | 'fade' | 'newsflash' | 'plus' | 'pull' | 'push' | 'random' | 'randomBar' | 'split' | 'strips' | 'wedge' | 'wheel' | 'wipe' | 'zoom';
-/**
- * Slide-show transition applied between slides (`p:transition`). Assign to
- * {@link Slide.transition}. Setting `durationMs` emits PowerPoint's
- * `mc:AlternateContent` form (a `p14` Choice carrying `p14:dur` plus a base
- * `mc:Fallback`); otherwise only the coarse `speed` bucket is written.
- * @example slide.transition = { type: 'push', durationMs: 1250, variant: { dir: 'd' } }
- */
-interface TransitionProps {
-  /** Transition type (the `<p:TYPE/>` element), e.g. `fade`, `push`, `wipe`, `cut`, `dissolve`. */
-  type: TransitionType;
-  /** Exact duration in milliseconds (`p14:dur`); emits the `mc:AlternateContent` form. */
-  durationMs?: number;
-  /** Coarse speed bucket (`spd`); derived from `durationMs` when omitted, else defaults to `fast`. */
-  speed?: 'slow' | 'med' | 'fast';
-  /** Advance on mouse click (`advClick`). @default true */
-  advanceOnClick?: boolean;
-  /** Auto-advance after this many milliseconds (`advTm`). */
-  advanceAfterMs?: number;
-  /** Type-specific variant attributes, e.g. `{ dir: 'd' }` for push, `{ spokes: '2' }` for wheel. */
-  variant?: Record<string, string>;
-  /** Sound played with the transition (`p:sndAc`): a start sound (embedded WAV) or the stop-previous form. */
-  sound?: TransitionSoundProps;
-  /**
-   * Internal: the slide relationship id assigned to the embedded sound part, stamped
-   * by the export-time registration pass. Not part of the authoring surface.
-   */
-  _sndRId?: number;
-}
-/**
- * A transition sound (`p:sndAc`). Either a **start sound** — an embedded WAV played
- * when the transition runs (`p:stSnd` → `p:snd`), optionally looped — or the
- * **stop-previous** form (`p:endSnd`) that silences a still-playing transition
- * sound. Built-in PowerPoint sounds embed identically to a custom file, so there is
- * no separate built-in path: supply the WAV bytes via `data` or `path`.
- * See `docs/animations-and-transitions.md`.
- */
-interface TransitionSoundProps {
-  /** Embedded sound bytes as a base64 data URI (e.g. `data:audio/wav;base64,…`) or raw base64. */
-  data?: string;
-  /** Path to a sound file, read at export time (alternative to `data`). */
-  path?: string;
-  /** Display name emitted on `<p:snd @name>` (e.g. `ding.wav`); defaults to the file name. */
-  name?: string;
-  /** Loop the sound until the next sound starts (`<p:stSnd loop="1">`). @default false */
-  loop?: boolean;
-  /** Emit the stop-previous form (`<p:endSnd/>`) instead of a start sound. Mutually exclusive with `data`/`path`. */
-  stopPrevious?: boolean;
+  onMediaError?: 'throw' | 'placeholder';
 }
-/**
- * A preset build-animation effect. The supported set is fixed (each is a verbatim
- * template captured from PowerPoint); adding one means adding a fixture + template,
- * not a new code path. See `docs/animations-and-transitions.md`.
- */
-type PresetEffect = 'fadeIn' | 'flyIn' | 'appear' | 'wipe' | 'grow' | 'spin' | 'fadeOut' | 'flyOut';
-/** When a build-animation effect starts relative to the preceding one. */
-type AnimationTrigger = 'onClick' | 'withPrevious' | 'afterPrevious';
-/**
- * A preset build animation on a shape (entrance/emphasis/exit), added via
- * {@link Slide.addAnimation}. Target the shape by its 0-based add order
- * (`shapeIndex`, mapping to the generated `spid = shapeIndex + 2`) or by
- * `objectName`. Effects play in the order added, grouped into click steps by
- * `trigger`.
- */
-interface AnimationProps {
-  /** The preset effect to play. */
-  preset: PresetEffect;
+interface WriteProps extends WriteBaseProps {
   /**
-   * 0-based add order of the target shape on the slide (`spid = shapeIndex + 2`).
-   * Counts top-level objects only; use `objectName` to target a shape inside a group.
+   * Output type
+   * - values: 'arraybuffer' | 'base64' | 'binarystring' | 'blob' | 'nodebuffer' | 'uint8array'
+   * @default 'blob'
    */
-  shapeIndex?: number;
-  /**
-   * Target shape by its `objectName` (alternative to `shapeIndex`). Any shape on the slide,
-   * including one inside a group; an unresolved name warns and drops the effect.
-   */
-  objectName?: string;
-  /** Trigger relative to the previous effect. @default 'onClick' */
-  trigger?: AnimationTrigger;
-  /** Effect duration in milliseconds; preset-specific default when omitted. */
-  durationMs?: number;
+  outputType?: WRITE_OUTPUT_TYPE;
 }
-//#endregion
-//#region src/types/master.d.ts
-interface SlideNumberProps extends PositionProps, TextBaseProps {
+interface WriteFileProps extends WriteBaseProps {
   /**
-   * margin (inches) — text-frame internal margin; a value `>= 1` warns as a likely legacy points value
+   * Export file name
+   * @default 'Presentation.pptx'
    */
-  margin?: Margin;
-}
-interface SlideMasterChartProps {
-  type: CHART_NAME | ChartMulti[];
-  data: OptsChartData[];
-  options?: ChartOpts;
-  opts?: ChartOpts;
-}
-/**
- * One object on a slide master, as a key-tagged descriptor.
- *
- * The six descriptors it shares with a group child are {@link CommonObjectDescriptor}; the two
- * below are the master's own — a chart, which a group cannot hold, and a placeholder, which is
- * the whole point of a master.
- */
-type SlideMasterObject = CommonObjectDescriptor | {
-  chart: SlideMasterChartProps;
-} | {
-  placeholder: {
-    options: PlaceholderProps;
-    /**
-     * Text to be shown in placeholder (shown until user focuses textbox or adds text)
-     * - Leave blank to have powerpoint show default phrase (ex: "Click to add title")
-     */
-    text?: string;
-  };
-};
-/**
- * Bullet configuration for one slide-master text-style level (`a:buChar`/`a:buAutoNum`/`a:buNone`).
- * A focused subset of the run-level bullet model — picture bullets and per-glyph sizing are not
- * supported in master defaults (those require slide rels). Set `bullet: false` to suppress the
- * level's bullet entirely.
- */
-interface MasterBulletProps {
-  /** `'bullet'` emits a character bullet (`a:buChar`); `'number'` emits an auto-number (`a:buAutoNum`). @default 'bullet' */
-  type?: 'bullet' | 'number';
-  /** Bullet character (unicode code point hex), e.g. `'2022'` for •. Used when `type` is `'bullet'`. */
-  characterCode?: string;
-  /** Glyph font typeface for the bullet character (`a:buFont`), e.g. `'Arial'` or `'Wingdings'`. */
-  fontFace?: string;
-  /** Auto-number scheme (`a:buAutoNum@type`) when `type` is `'number'`, e.g. `'arabicPeriod'`. @default 'arabicPeriod' */
-  numberType?: string;
-  /** Starting value for auto-numbered bullets (`a:buAutoNum@startAt`). @default 1 */
-  numberStartAt?: number;
+  fileName?: string;
 }
 /**
- * Styling for one paragraph level (`a:lvlNpPr`) of a slide-master text style. Every field is
- * optional; an unset field keeps PowerPoint's built-in default for that level. Configure via
- * {@link SlideMasterProps.textStyles}.
+ * One emitted OOXML package part: its full slash-path and already-encoded bytes. Returned by
+ * {@link TsPptx.toParts} for callers that want the raw parts of the `.pptx` OPC package without
+ * zipping (custom containers, streaming, part-level inspection). The bytes are byte-identical to
+ * what `write()` would compress for the same part;
+ * XML parts are UTF-8 (decode with `new TextDecoder().decode(part.data)`), media/font parts are
+ * their raw binary.
  */
-interface MasterTextStyleLevel {
-  /** Font size in points (`a:defRPr@sz`), e.g. `24`. */
-  fontSize?: number;
-  /** Font face (`a:defRPr/a:latin@typeface`). Unset keeps the theme font (`+mn-lt`/`+mj-lt`). */
-  fontFace?: string;
-  /** Text color — hex (`'C00000'`) or theme slot (`'tx1'`) — emitted as `a:defRPr/a:solidFill`. */
-  color?: Color;
-  /** Bold text (`a:defRPr@b`). */
-  bold?: boolean;
-  /** Italic text (`a:defRPr@i`). */
-  italic?: boolean;
-  /** Horizontal alignment (`a:lvlNpPr@algn`). */
-  align?: HAlign;
-  /** Left margin in inches (`a:lvlNpPr@marL`); for a hanging bullet this is the text indent. */
-  marginLeft?: number;
-  /** First-line indent in inches (`a:lvlNpPr@indent`); negative produces a hanging bullet. */
-  indent?: number;
-  /** Bullet config: `false` emits `a:buNone`; an object configures a char/number bullet. Unset keeps the level default. */
-  bullet?: boolean | MasterBulletProps;
+interface PackagePart {
+  /** Full OOXML package part path, e.g. `ppt/slides/slide1.xml`. */
+  readonly path: string;
+  /** The part's already-encoded bytes: a fresh view per call, safe to keep or transfer. */
+  readonly data: Uint8Array;
 }
 /**
- * Per-level slide-master text styles, written to `slideMaster1.xml`'s `<p:txStyles>`.
- * Because a deck has a single shared slide master, these styles are **deck-wide**: when set on more
- * than one `defineSlideMaster()` call the last value for each group (`title`/`body`/`other`) wins.
+ * Options for {@link TsPptx.toParts}. A deliberately narrow subset of {@link WriteProps}:
+ * `compression` and `outputType` are zip concerns and do not apply when parts are returned
+ * unzipped, so only media-error handling is exposed.
  */
-interface MasterTextStyleProps {
-  /** Title placeholder style (`p:titleStyle`, single level). */
-  title?: MasterTextStyleLevel;
-  /** Body placeholder per-level styles (`p:bodyStyle`, levels 1–9; index 0 is `lvl1`). */
-  body?: MasterTextStyleLevel[];
-  /** Other/default placeholder per-level styles (`p:otherStyle`, levels 1–9). */
-  other?: MasterTextStyleLevel[];
-}
-interface SlideMasterProps {
-  /**
-   * Unique name for this master
-   */
-  title: string;
-  background?: BackgroundProps;
-  margin?: Margin;
-  slideNumber?: SlideNumberProps;
-  objects?: SlideMasterObject[];
-  /**
-   * Per-level master text styles (title / body / other) written to the shared slide master's
-   * `<p:txStyles>`. Configure nested bullet character, font size, color, alignment, and indent
-   * for each of the nine list levels. Deck-wide (see {@link MasterTextStyleProps}).
-   * @example textStyles: { body: [{ fontSize: 24, color: 'C00000', bullet: { characterCode: '25AA' } }] }
-   */
-  textStyles?: MasterTextStyleProps;
-}
-//#endregion
-//#region src/types/model3d.d.ts
-/** A point or direction in the model's 3D scene, in metres. */
-interface Model3dPoint {
-  x: number;
-  y: number;
-  z: number;
-}
-/**
- * Camera override for `addModel3d()`, mapping onto `am3d:camera`.
- *
- * The defaults are what PowerPoint itself wrote for a 2×2×2 cube, and they are correct for any
- * model whose bounding box is roughly cubic **once `meterPerModelUnit` is right** — the camera is
- * expressed in metres, so the scale is what actually decides framing.
- *
- * PowerPoint's own rule, measured against three models: it normalizes the model's largest
- * bounding-box extent to 1 metre and then places the camera at
- *
- * ```
- * pos.z = |halfExtents / maxExtent| / sin(fov / 2)
- * ```
- *
- * looking at the origin. A caller who knows their model's bounding box can reproduce that
- * exactly; a caller who does not should at least set `meterPerModelUnit` to `1 / maxExtent`.
- */
-interface Model3dCameraProps {
-  /**
-   * Camera position in metres (`am3d:camera/am3d:pos`).
-   * @default { x: 0, y: 0, z: 2.2630334 }
-   */
-  pos?: Model3dPoint;
+interface PartsProps {
   /**
-   * Point the camera aims at, in metres (`am3d:camera/am3d:lookAt`).
-   * @default { x: 0, y: 0, z: 0 }
+   * How to handle a media asset (image/audio/video) that fails to load. Same semantics as
+   * {@link WriteBaseProps.onMediaError}.
+   * @default 'throw'
    */
-  lookAt?: Model3dPoint;
-  /**
-   * Camera "up" direction (`am3d:camera/am3d:up`). Need not be normalized.
-   * @default { x: 0, y: 1, z: 0 }
-   */
-  up?: Model3dPoint;
-  /**
-   * Vertical field of view in **degrees** (`am3d:perspective@fov`).
-   * - range: greater than 0 and less than 180
-   * @default 45
-   */
-  fov?: number;
+  onMediaError?: 'throw' | 'placeholder';
 }
-/**
- * Add an embedded 3D model (PowerPoint's Insert ▸ 3D Models) to a slide.
- *
- * The `.glb` bytes travel inside the `.pptx` (in `ppt/media/`), so PowerPoint 2019+ renders and
- * lets the viewer orbit the model. Requires either `data` or `path`. Linked (non-embedded)
- * models are not supported.
- */
-interface Model3dBaseProps extends PositionProps, ObjectNameProps {
+interface SectionProps {
   /**
-   * Picture of the model shown wherever the live 3D view is unavailable — a raster image `path`
-   * (Node/local) or base64 `data:` URI.
-   * - the library cannot render a 3D scene, so when this is omitted a neutral gray placeholder is
-   *   embedded; PowerPoint 2019+ draws the live model over it, but every other consumer — and
-   *   PowerPoint's own `mc:Fallback` path, thumbnails, and PDF export — shows exactly what is here
-   * - supply a real render whenever the deck is meant to read correctly outside PowerPoint
-   * @example { path: 'assets/engine-render.png' }
+   * Section title
    */
-  preview?: {
-    path?: string;
-    data?: string;
-  };
-  /**
-   * Camera override. Omitted, ts-pptx emits the camera PowerPoint wrote for a 2×2×2 cube.
-   * @see {@link Model3dCameraProps} for the framing formula and when this matters.
-   */
-  camera?: Model3dCameraProps;
+  title: string;
   /**
-   * Metres per model unit (`am3d:trans/am3d:meterPerModelUnit`) — the scale that decides how
-   * large the model is in the scene the {@link camera} looks at.
+   * Where to insert the section, counting from **1**: `order: 1` puts it first, `order: 2`
+   * second. Omit it to append.
    *
-   * This is the single override most models need. PowerPoint sets it to `1 / maxExtent`, where
-   * `maxExtent` is the model's largest bounding-box dimension in model units, which normalizes
-   * every model to 1 metre across. ts-pptx does not parse the `.glb`, so it cannot measure that
-   * — it defaults to `0.5`, correct for a model 2 units across. A model 100 units across left at
-   * the default is a 50-metre object with the camera 2.26 metres from its centre, i.e. the
-   * viewer is inside it.
-   * - range: greater than 0
-   * @default 0.5
-   * @example 1 / 100 // a model whose largest bounding-box dimension is 100 units
+   * An order past the end appends, which is the only sensible reading of "put it at
+   * position 12" in a deck with four sections. Anything that is not a whole number of at
+   * least 1 -- `0`, a negative, a fraction -- warns and appends: it named no position, and
+   * silently treating it as one is how `order: 1` came to insert *second* and `order: 0` to
+   * append with no word said.
+   * - values: 1-n
    */
-  meterPerModelUnit?: number;
-  /**
-   * Alt text (`p:cNvPr@descr`) — what a screen reader announces for the model.
-   */
-  altText?: string;
-}
-/**
- * Options for `slide.addModel3d()`. Requires either `data` (base64, with or without a
- * `data:...;base64,` header) or `path` (a local/remote `.glb` read at export time).
- *
- * Sizing note: `w`/`h` default to 4 × 3 inches rather than being measured. A 3D model has no
- * intrinsic aspect ratio, and the library never opens the payload.
- */
-type Model3dProps = Model3dBaseProps & DataOrPathRequiredProps;
-//#endregion
-//#region src/types/slide.d.ts
-/**
- * A child object that can be placed inside a group via `slide.addGroup()`.
- *
- * The six descriptors it shares with `SlideMasterObject` are {@link CommonObjectDescriptor};
- * `group` is the group's own, and the master's `chart` and `placeholder` are deliberately not
- * here. A `group` child nests another group (an identity child
- * coordinate space is kept at every depth, so descendants keep their slide-absolute
- * coordinates). Charts, media, tables, and placeholders are intentionally excluded (see
- * `addGroup`); passing one logs a warning and skips it.
- */
-type GroupChildProps = CommonObjectDescriptor | {
-  group: {
-    children: GroupChildProps[];
-    options?: GroupProps;
-  };
-};
-/**
- * Options for `slide.addGroup()`.
- *
- * The group keeps an identity child coordinate space (`chOff/chExt == off/ext`) at every depth:
- * children — including nested groups — keep their slide-absolute `x/y/w/h`. A consequence worth
- * knowing: a group's own frame never moves or scales its children, it only places the selection
- * handle and the rotate pivot.
- *
- * The frame is all-or-nothing. Pass all four of `x/y/w/h` to set it explicitly, or none to have it
- * auto-computed as the bounding box of the children. A partial frame is ambiguous, so it warns and
- * falls back to auto-bounds on every axis.
- */
-interface GroupProps extends PositionProps, ObjectNameProps {
-  /** Rotation in degrees (applied to the whole group) */
-  rotate?: number;
-  /** Flip the group horizontally */
-  flipH?: boolean;
-  /** Flip the group vertically */
-  flipV?: boolean;
+  order?: number;
 }
-interface ObjectOptions extends ImageBaseProps, PositionProps, ShapeProps, TableCellProps, TextPropsOptions {
-  _placeholderIdx?: number;
-  _placeholderType?: PLACEHOLDER_TYPE;
-  /** Connector adjust-guide values (OOXML 1000ths-of-a-percent), one per bend; emitted as `<a:gd name="adjN">` */
-  _connectorAdj?: number[];
-  /** Connector start-point binding: target shape `objectName` (raw, as the caller spelled it) + connection-site index; resolved to `<a:stCxn>` at serialize time */
-  _startCxn?: {
-    name: string;
-    idx: number;
-  };
-  /** Connector end-point binding: target shape `objectName` (raw, as the caller spelled it) + connection-site index; resolved to `<a:endCxn>` at serialize time */
-  _endCxn?: {
-    name: string;
-    idx: number;
-  };
-  /**
-   * Image: which dimensions were omitted by the user and should be derived from the image's
-   * natural pixel size at serialize time. Path-based images can't be measured synchronously in
-   * `addImage()` (bytes are loaded async during export), so the missing extent is backfilled
-   * once `_relsMedia[].data` is populated. `{ w, h }` true means "derive this side from the
-   * natural ratio". Base64 `data` images are measured eagerly in `addImage()` and never set this.
-   */
-  _szAuto?: {
-    w: boolean;
-    h: boolean;
-  };
-  cx?: Coord;
-  cy?: Coord;
-  margin?: Margin;
-  colW?: number | number[];
-  rowH?: number | number[];
-  hasHeader?: boolean;
-  hasFooter?: boolean;
-  hasBandedRows?: boolean;
-  hasBandedColumns?: boolean;
-  hasFirstColumn?: boolean;
-  hasLastColumn?: boolean;
-  rtl?: boolean;
-  tableStyle?: TableStyle;
-  /**
-   * Table perimeter border. `addTableDefinition` normalizes it to a 4-tuple (TRBL, sides
-   * left unset as `undefined`) before it reaches the emitter, so the serializer never has
-   * to re-handle the single-`BorderProps` form.
-   */
-  outerBorder?: TableProps['outerBorder'];
-  /** Table background (`a:tblPr` fill), as distinct from `fill`, which is stamped onto each cell. */
-  tableFill?: TableProps['tableFill'];
-}
-interface SlideLayout {
-  background?: BackgroundProps;
-}
-/**
- * One authored object on a slide, as {@link Slide.objects} reports it: what it is and how it is
- * addressed, not how it is drawn. It is a snapshot taken when the getter ran, not a live handle —
- * nothing on it writes back, and a later `addShape`/`groupObjects` leaves it describing the slide
- * as it was.
- *
- * The point of it is composition. A slide assembled by independent renderers arrives with objects
- * whose descriptors nobody kept, and the only durable handle on them is the `objectName` each one
- * was authored with; without a way to enumerate those, a consumer that wants to act on what is
- * already there has to either make every renderer surrender its internals or keep a parallel
- * ledger of what it added — and a ledger is wrong the moment a renderer adds an object it did not
- * announce.
- */
-interface SlideObjectInfo {
-  /** What kind of object this is — the same value the object was authored as. */
-  readonly type: SlideObjectType;
-  /**
-   * Selection Pane name, in the spelling the caller passed to `objectName`, so it can be handed
-   * straight back to `groupObjects()` or to an animation or connector reference.
-   *
-   * Always a string: an object authored without a name still gets the generated `Shape 3` /
-   * `Text 1` / `Group 2` identity PowerPoint shows in the Selection Pane, and that name addresses
-   * it just as well. The two are indistinguishable here on purpose — nothing downstream of
-   * authoring records which is which, and a consumer that cares can tell them apart by the
-   * naming convention it chose for its own objects.
-   */
-  readonly objectName: string;
-  /** True when the object occupies a layout placeholder, which grouping refuses on top of kind. */
-  readonly isPlaceholder: boolean;
-  /**
-   * Whether `groupObjects()` would accept this object on kind alone. It cannot speak for the
-   * *selection* — an unresolved, duplicated or ambiguous name still throws — so it answers "is
-   * this object groupable", never "will this call succeed".
-   */
-  readonly canGroup: boolean;
-  /**
-   * Children, when `type` is `group`; empty otherwise. Ordered bottom-to-top like
-   * {@link Slide.objects} itself, and nested to whatever depth the groups nest.
-   */
-  readonly children: readonly SlideObjectInfo[];
-}
-interface Slide {
-  addChart(data: OptsChartData[], options: ChartOpts & {
-    type: CHART_NAME;
-  }): Slide;
-  addChart(charts: ChartMulti[], options?: ChartOpts): Slide;
-  addConnector: (options: ConnectorProps) => Slide;
-  addImage: (options: ImageProps) => Slide;
-  addMedia: (options: MediaProps) => Slide;
-  /** Embed a 3D model (Insert ▸ 3D Models) — a `.glb` PowerPoint 2019+ renders live. */
-  addModel3d: (options: Model3dProps) => Slide;
-  /** Embed an OLE object (Insert ▸ Object) whose bytes travel inside the `.pptx`. */
-  addOleObject: (options: OleObjectProps) => Slide;
-  addComment: (options: CommentProps) => Slide;
-  addNotes: (notes: string | NotesProps | NotesProps[]) => Slide;
-  addShape: (shapeName: SHAPE_NAME, options?: ShapeProps) => Slide;
-  addTable: (tableRows: TableRow[], options?: TableProps) => Slide;
-  addText: (text: string | number | TextProps[], options?: TextPropsOptions) => Slide;
-  addAnimation: (options: AnimationProps) => Slide;
-  /** Group child object descriptors into a single PowerPoint group (`<p:grpSp>`). */
-  addGroup: (children: GroupChildProps[], options?: GroupProps) => Slide;
-  /** Group objects already on this slide, addressed by their `objectName`, into a single group. */
-  groupObjects: (objectNames: string[], options?: GroupProps) => Slide;
-  /**
-   * The objects authored on this slide so far, bottom-to-top in z-order — the read-back half of
-   * `groupObjects()`, which addresses those same objects by name but until now gave no way to
-   * learn the names.
-   *
-   * A fresh snapshot on every access, and inert: it describes the slide, and writing to it does
-   * nothing. To act on what it reports, call the authoring API with the names it hands you.
-   * @example
-   * const cards = slide.objects.filter((o) => o.canGroup && o.objectName?.startsWith('card:'))
-   * slide.groupObjects(cards.map((o) => o.objectName), { objectName: 'Cards' })
-   */
-  readonly objects: readonly SlideObjectInfo[];
-  readonly newAutoPagedSlides?: Slide[];
+interface PresLayout {
   /**
-   * Slide-show transition played when advancing to this slide (`p:transition`).
-   * @example slide.transition = { type: 'fade', durationMs: 1500 }
+   * Layout Name
+   * @example 'LAYOUT_WIDE'
    */
-  transition?: TransitionProps;
-  /**
-   * Slide width in inches, resolved from the active presentation layout.
-   * Use for coordinate math instead of hard-coding layout dimensions.
-   * @example slide.addText('Centered', { x: 0, w: slide.width, align: 'center' })
-   */
-  readonly width?: number;
+  name: string;
   /**
-   * Slide height in inches, resolved from the active presentation layout.
-   */
-  readonly height?: number;
+   * Slide width.
+   *
+   * **The unit depends on which direction this shape is travelling.** `defineLayout` reads it
+   * as INCHES -- that is what its own example passes -- while `pptx.presLayout` returns it in
+   * EMU. So `defineLayout({ ...pptx.presLayout, name: 'Copy' })`, the obvious way to derive a
+   * layout from the current one, states a width of nine million inches; `defineLayout` now
+   * clamps it to the 56in maximum and says so rather than emitting a `sldSz` PowerPoint
+   * refuses.
+   */
+  width: number;
+  /** Slide height; the same two units as {@link width}, in the same two directions. */
+  height: number;
+}
+type CustomPropertyValue = string | number | boolean | Date;
+interface PresentationProps {
+  author: string;
+  company: string;
+  layout: string;
   /**
-   * Background color or image (`color` | `path` | `data`)
-   * @example { color: 'FF3399' } - hex color
-   * @example { color: 'FF3399', transparency:50 } - hex color with 50% transparency
-   * @example { path: 'https://onedrives.com/myimg.png` } - retrieve image via URL
-   * @example { path: '/home/user/images/myimg.png` } - retrieve image via local path
-   * @example { data: 'image/png;base64,iVtDaDrF[...]=' } - base64 string
+   * Presentation's layout
+   * read-only
    */
-  background?: BackgroundProps;
+  presLayout: PresLayout;
+  revision: string;
   /**
-   * Default text color (hex format)
-   * @example 'FF3399'
-   * @default '000000' (DEF_FONT_COLOR)
+   * Slide number to assign to the first slide (affects the slide-number field displayed in placeholders).
+   * @default 1
    */
-  color?: HexColor;
+  firstSlideNum: number;
   /**
-   * Whether slide is hidden
+   * Whether to enable right-to-left mode
    * @default false
    */
-  hidden?: boolean;
-  /**
-   * Slide number options
-   */
-  slideNumber?: SlideNumberProps;
-}
-interface AddSlideProps {
-  /** Title of the slide master to use for the new slide (the `title` passed to {@link SlideMasterProps} via `defineSlideMaster`). */
-  masterTitle?: string;
-  sectionTitle?: string;
+  rtlMode: boolean;
+  subject: string;
+  theme: ThemeProps;
+  title: string;
 }
 //#endregion
-export { VAlign as $, MeasureTextOptions as $t, TableRowSlide as A, ChartPropsChartDoughnut as At, GradientFillProps as B, ChartPropsDataTable as Bt, TransitionType as C, ShapeAdjustValue as Cn, ChartOpts as Ct, TableCellProps as D, ChartPropsBase as Dt, TableCellDiagonals as E, ShapeProps as En, ChartPropsAxisVal as Et, Color as F, ChartPropsChartRegionMap as Ft, LinearGradientFillProps as G, LineCap as Gt, HAlign as H, ChartPropsLegend as Ht, Coord as I, ChartPropsChartStock as It, PatternPreset as J, CommonObjectDescriptor as Jt, Margin as K, OptsChartData as Kt, DataOrPathProps as L, ChartPropsChartSurface as Lt, TableToSlidesElement as M, ChartPropsChartLine as Mt, TableToSlidesProps as N, ChartPropsChartPie as Nt, TableProps as O, ChartPropsChartBar as Ot, BackgroundProps as P, ChartPropsChartRadar as Pt, ThemeColor as Q, CommentProps as Qt, DataOrPathRequiredProps as R, ChartPropsChartWaterfall as Rt, TransitionSoundProps as S, ShapeAdjustHandleXY as Sn, ChartMulti as St, TableCell3DProps as T, ShapeGuide as Tn, ChartPropsAxisSer as Tt, HexColor as U, ChartPropsTitle as Ut, GradientStopProps as V, ChartPropsFillLine as Vt, ImageFillProps as W, ChartSeriesOpts as Wt, RadialGradientFillProps as X, ObjectNameProps as Xt, PositionProps as Y, ObjectLockProps as Yt, TextVertType as Z, PlaceholderProps as Zt, SlideNumberProps as _, MediaProps as _n, ChartErrorBarOptions as _t, Slide as a, TableCellLayout as an, ShadowProps as at, PresetEffect as b, ShapeAdjustHandle as bn, ChartExStatistics as bt, Model3dCameraProps as c, TextFitShrinkProps as cn, BevelPresetType as ct, MasterBulletProps as d, TextProps as dn, LightRigType as dt, NotesProps as en, BorderProps as et, MasterTextStyleLevel as f, TextPropsOptions as fn, PresetMaterialType as ft, SlideMasterProps as g, ImageProps as gn, ChartDataPointStyle as gt, SlideMasterObject as h, ImageBaseProps as hn, ChartAxisTickMark as ht, ObjectOptions as i, SlideComment as in, HyperlinkProps as it, TableToSlidesDocument as j, ChartPropsChartHistogram as jt, TableRow as k, ChartPropsChartBoxWhisker as kt, Model3dPoint as l, TextGlowProps as ln, ColorMapToken as lt, SlideMasterChartProps as m, textRuns as mn, ChartAreaProps as mt, GroupChildProps as n, OverflowBoxOptions as nn, ConnectorType as nt, SlideLayout as o, TableLayoutResult as on, ShapeFillProps as ot, MasterTextStyleProps as p, textRun as pn, ThemeColorSlot as pt, PatternFillProps as q, OptsChartGridLine as qt, GroupProps as r, ResolvedCommentAuthor as rn, HyperlinkActionJump as rt, SlideObjectInfo as s, TextBaseProps as sn, ShapeLineProps as st, AddSlideProps as t, NotesTextOptions as tn, ConnectorProps as tt, Model3dProps as u, TextMeasurement as un, LightRigDirection as ut, AnimationProps as v, MediaType as vn, ChartExBinning as vt, TableCell as w, ShapeConnectionSite as wn, ChartPropsAxisCat as wt, TransitionProps as x, ShapeAdjustHandlePolar as xn, ChartLineDash as xt, AnimationTrigger as y, OleObjectProps as yn, ChartExGeography as yt, GeometryPoint as z, ChartPropsDataLabel as zt };
-//# sourceMappingURL=slide-ZqAdVvHV.d.ts.map
+export { ChartPropsAxisCat as $, ShapeAdjustValue as $t, TextVertType as A, NotesTextOptions as At, ShapeFillProps as B, TextMeasurement as Bt, ImageFillProps as C, TimeUnit as Cn, CommonObjectDescriptor as Ct, PatternPreset as D, CommentProps as Dt, PatternFillProps as E, PlaceholderProps as Et, ConnectorType as F, TableLayoutResult as Ft, ChartDataPointStyle as G, ImageBaseProps as Gt, StrokeProps as H, TextPropsOptions as Ht, FillOption as I, TextBaseProps as It, ChartExGeography as J, MediaType as Jt, ChartErrorBarOptions as K, ImageProps as Kt, HyperlinkActionJump as L, TextBulletProps as Lt, VAlign as M, ResolvedCommentAuthor as Mt, BorderProps as N, SlideComment as Nt, PositionProps as O, MeasureTextOptions as Ot, ConnectorProps as P, TableCellLayout as Pt, ChartOpts as Q, ShapeAdjustHandleXY as Qt, HyperlinkProps as R, TextFitShrinkProps as Rt, HexColor as S, ThemeColorSlot as Sn, OptsChartGridLine as St, Margin as T, ObjectNameProps as Tt, ChartAreaProps as U, textRun as Ut, ShapeLineProps as V, TextProps as Vt, ChartAxisTickMark as W, textRuns as Wt, ChartLineDash as X, ShapeAdjustHandle as Xt, ChartExStatistics as Y, OleObjectProps as Yt, ChartMulti as Z, ShapeAdjustHandlePolar as Zt, DataOrPathRequiredProps as _, RadarStyleAlias as _n, ChartPropsLegend as _t, PresentationProps as a, BarGrouping as an, ChartPropsChartDoughnut as at, GradientStopProps as b, TextHorzOverflowType as bn, LineCap as bt, WriteFileProps as c, DataLabelPosition as cn, ChartPropsChartPie as ct, ThemeProps as d, LegendPosition as dn, ChartPropsChartStock as dt, ShapeConnectionSite as en, ChartPropsAxisSer as et, BackgroundOption as f, LightRigDirection as fn, ChartPropsChartSurface as ft, DataOrPathProps as g, RadarStyle as gn, ChartPropsFillLine as gt, Coord as h, PresetMaterialType as hn, ChartPropsDataTable as ht, PresLayout as i, BarDirection as in, ChartPropsChartBoxWhisker as it, ThemeColor as j, OverflowBoxOptions as jt, RadialGradientFillProps as k, NotesProps as kt, WriteProps as l, DisplayBlanksAs as ln, ChartPropsChartRadar as lt, Color as m, LineDataSymbol as mn, ChartPropsDataLabel as mt, PackagePart as n, ShapeProps as nn, ChartPropsBase as nt, SectionProps as o, BevelPresetType as on, ChartPropsChartHistogram as ot, BackgroundProps as p, LightRigType as pn, ChartPropsChartWaterfall as pt, ChartExBinning as q, MediaProps as qt, PartsProps as r, Bar3DShape as rn, ChartPropsChartBar as rt, WriteBaseProps as s, ColorMapToken as sn, ChartPropsChartLine as st, CustomPropertyValue as t, ShapeGuide as tn, ChartPropsAxisVal as tt, ThemeColorScheme as u, EMBEDDED_FONT_SLOTS as un, ChartPropsChartRegionMap as ut, GeometryPoint as v, TEXT_AUTONUM_SCHEMES as vn, ChartPropsTitle as vt, LinearGradientFillProps as w, ObjectLockProps as wt, HAlign as x, TextShapeType as xn, OptsChartData as xt, GradientFillProps as y, TRANSITION_TYPES as yn, ChartSeriesOpts as yt, ShadowProps as z, TextGlowProps as zt };
+//# sourceMappingURL=pres-C6qgOFAa.d.ts.map