@shbernal/ts-pptx 4.0.1 → 4.2.0

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

@@ -1,5 +1,4 @@
-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
+import { c as PLACEHOLDER_TYPE, d as SHAPE_NAME, i as CHART_NAME, v as WRITE_OUTPUT_TYPE } from "./enums-PcXr3o3J.js";
 /**
  * `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.
@@ -12,7 +11,7 @@ import { c as PLACEHOLDER_TYPE, d as SHAPE_NAME, i as CHART_NAME, v as WRITE_OUT
  * 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.
+ * `(typeof X)[number]`. Widening the tuple widens the union in the same edit, so 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`.
  *
@@ -30,19 +29,19 @@ import { c as PLACEHOLDER_TYPE, d as SHAPE_NAME, i as CHART_NAME, v as WRITE_OUT
  * 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
+ * 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`). */
+/** `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`). */
+/** `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`). */
+/** `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`). */
+/** `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`). */
+/** `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
@@ -53,43 +52,47 @@ declare const TEXT_TAB_ALIGN_TYPES: readonly ['l', 'ctr', 'r', 'dec'];
  */
 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.
+ * `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.
+ * `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.
+ * `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.
+ * `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`.
+ * `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`.
+ * `ST_PresetPatternVal`: `a:pattFill/@prst`, the hatch a pattern fill draws.
+ */
+declare const PATTERN_PRESETS: readonly ['pct5', 'pct10', 'pct20', 'pct25', 'pct30', 'pct40', 'pct50', 'pct60', 'pct70', 'pct75', 'pct80', 'pct90', 'horz', 'vert', 'ltHorz', 'ltVert', 'dkHorz', 'dkVert', 'narHorz', 'narVert', 'dashHorz', 'dashVert', 'cross', 'dnDiag', 'upDiag', 'ltDnDiag', 'ltUpDiag', 'dkDnDiag', 'dkUpDiag', 'wdDnDiag', 'wdUpDiag', 'dashDnDiag', 'dashUpDiag', 'diagCross', 'smCheck', 'lgCheck', 'smGrid', 'lgGrid', 'dotGrid', 'smConfetti', 'lgConfetti', 'horzBrick', 'diagBrick', 'solidDmnd', 'openDmnd', 'dotDmnd', 'plaid', 'sphere', 'weave', 'divot', 'shingle', 'wave', 'trellis', 'zigZag'];
+/**
+ * `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`,
+ * `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
  */
@@ -105,17 +108,24 @@ declare const LINE_END_TYPES: readonly ['none', 'triangle', 'stealth', 'diamond'
 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
+ * `ST_PlaceholderType`: the kind of placeholder a `p:ph` fills (`p:ph/@type`). Absent, it means
+ * `obj`.
+ * @see ECMA-376 Part 1 §19.7.10
+ */
+declare const PLACEHOLDER_TYPES: readonly ['title', 'body', 'ctrTitle', 'subTitle', 'dt', 'sldNum', 'ftr', 'hdr', 'obj', 'chart', 'tbl', 'clipArt', 'dgm', 'media', 'sldImg', 'pic'];
+type PlaceholderXmlType = (typeof PLACEHOLDER_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.
+ * 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`).
+ * `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
@@ -125,26 +135,26 @@ type TextShapeType = (typeof TEXT_SHAPE_TYPES)[number];
 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`).
+ * `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
+ * `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`).
+ * `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`).
+ * `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'];
@@ -156,8 +166,8 @@ type RadarStyle = (typeof RADAR_STYLES)[number];
  * 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
+ * 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: {
@@ -166,21 +176,21 @@ declare const RADAR_STYLE_ALIASES: {
 };
 type RadarStyleAlias = keyof typeof RADAR_STYLE_ALIASES;
 /**
- * `ST_LegendPos` — where the legend sits relative to the plot area (`c:legendPos/@val`).
+ * `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`).
+ * `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`).
+ * `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* —
+ * 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.
@@ -193,43 +203,43 @@ type DataLabelPosition = (typeof DATA_LABEL_POSITIONS)[number];
  *
  * 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
+ * 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`). */
+/** `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`). */
+/** `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`). */
+/** `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`). */
+/** `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`). */
+/** `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). */
+/** `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`). */
+/** `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`). */
+/** `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`). */
+/** `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
+ * 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
@@ -241,13 +251,11 @@ type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
  *
  * 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.
+ * 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>`).
  * - `name` is the guide name the preset defines, e.g. `'adj'`, `'adj1'`, `'adj2'`.
@@ -266,12 +274,12 @@ interface ShapeAdjustValue {
  * A geometry guide (`<a:gd>` inside a `custGeom`'s `<a:gdLst>`): a named construction formula
  * that connection sites, adjust handles, and the text rect can reference by name.
  * - `name` is a `ST_GeomGuideName` token, e.g. `'w2'`.
- * - `formula` is a `ST_GeomGuideFormula` — a space-delimited op + args string emitted verbatim,
+ * - `formula` is a `ST_GeomGuideFormula`: a space-delimited op + args string emitted verbatim,
  *   e.g. the multiply-divide op `"* / w 1 2"` written without the inner space (w × 1 ÷ 2), or
  *   `'val 10800'`. This is an advanced escape hatch: the arguments are not interpreted, only
  *   escaped. The leading operation *is* checked against the 17 ECMA-376 §20.1.9.11 operations
  *   (multiply-divide, add-subtract, add-divide, if-else, `abs`, `at2`, `cat2`, `cos`, `max`,
- *   `min`, `mod`, `pin`, `sat2`, `sin`, `sqrt`, `tan`, `val` — see `GEOM_GUIDE_OPS` in
+ *   `min`, `mod`, `pin`, `sat2`, `sin`, `sqrt`, `tan`, `val`; see `GEOM_GUIDE_OPS` in
  *   `src/gen/drawingml/geometry.ts` for the literal tokens), because an unknown one emits
  *   schema-shaped but semantically dead geometry that PowerPoint answers with a repair prompt;
  *   such a guide is warned about and skipped.
@@ -293,7 +301,7 @@ interface ShapeConnectionSite {
   /** Y in the object's own space (like `points`), or a guide-name string emitted verbatim. */
   y: Coord | string;
 }
-/** An XY adjust handle (`<a:ahXY>`) — a draggable handle, optionally bound to guides. */
+/** An XY adjust handle (`<a:ahXY>`): a draggable handle, optionally bound to guides. */
 interface ShapeAdjustHandleXY {
   x: Coord | string;
   y: Coord | string;
@@ -304,7 +312,7 @@ interface ShapeAdjustHandleXY {
   minY?: Coord | string;
   maxY?: Coord | string;
 }
-/** A polar adjust handle (`<a:ahPolar>`) — radius/angle rather than XY. */
+/** A polar adjust handle (`<a:ahPolar>`): radius/angle rather than XY. */
 interface ShapeAdjustHandlePolar {
   x: Coord | string;
   y: Coord | string;
@@ -378,7 +386,7 @@ interface ShapeProps extends PositionProps, ObjectNameProps {
   line?: ShapeLineProps;
   /**
    * Points (only for ShapeType.custGeom)
-   * - type: 'arc' (no end point — it is computed from the pen position, radii and sweep)
+   * - type: 'arc' (no end point; it is computed from the pen position, radii and sweep)
    * - `hR` Shape Arc Height Radius
    * - `wR` Shape Arc Width Radius
    * - `stAng` Shape Arc Start Angle (degrees, not wrapped into 0..360)
@@ -388,20 +396,20 @@ interface ShapeProps extends PositionProps, ObjectNameProps {
    */
   points?: GeometryPoint[];
   /**
-   * Geometry guides (`<a:gdLst>`) for a `custGeom` shape — named construction formulas that
+   * Geometry guides (`<a:gdLst>`) for a `custGeom` shape: named construction formulas that
    * connection sites / adjust handles can reference. Advanced: each `formula` is emitted verbatim.
    * @example [{ name: 'w2', formula: 'val 10800' }]
    */
   guides?: ShapeGuide[];
   /**
-   * Connection sites (`<a:cxnLst>`) for a `custGeom` shape — the points a connector can attach to.
+   * Connection sites (`<a:cxnLst>`) for a `custGeom` shape: the points a connector can attach to.
    * Positions are absolute in the object's own space (like `points`); a `startShapeIdx`/`endShapeIdx`
    * on an `addConnector` indexes into this list.
    * @example [{ ang: 0, x: 1, y: 0 }, { ang: 180, x: 0, y: 1 }]
    */
   connectionSites?: ShapeConnectionSite[];
   /**
-   * Adjust handles (`<a:ahLst>`) for a `custGeom` shape — draggable handles (XY or polar),
+   * Adjust handles (`<a:ahLst>`) for a `custGeom` shape: draggable handles (XY or polar),
    * optionally bound to guides via `gdRef*`.
    */
   adjustHandles?: ShapeAdjustHandle[];
@@ -424,16 +432,14 @@ interface ShapeProps extends PositionProps, ObjectNameProps {
    */
   shadow?: ShadowProps;
 }
-//#endregion
-//#region src/types/media.d.ts
 type MediaType = 'audio' | 'online' | 'video';
-interface ImageBaseProps extends PositionProps, ObjectNameProps {
+interface ImageBaseProps extends PlaceholderPositionProps, ObjectNameProps {
   /**
-   * Sizing note (`w`/`h` inherited from {@link PositionProps}):
+   * Sizing note (`w`/`h` inherited from {@link PlaceholderPositionProps}):
    * - When a `data` (base64) image is supplied and `w`/`h` are omitted, the natural pixel
    *   size is read from the image header (PNG/JPEG/GIF/BMP/WebP) and used at 96 DPI
    *   (natural pixels / 96 = inches).
-   * - When only one of `w`/`h` is given, the other is derived from the natural aspect ratio —
+   * - When only one of `w`/`h` is given, the other is derived from the natural aspect ratio,
    *   for an SVG too, from its `width`/`height` or `viewBox`.
    * - A `path` image is measured at export time (its bytes are not available synchronously);
    *   an omitted dimension falls back to 1 inch if it stays unmeasurable.
@@ -469,14 +475,17 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
    */
   line?: ShapeLineProps;
   /**
-   * Name of a picture placeholder defined on the slide layout/master to populate
+   * Name of a picture placeholder defined on the slide layout/master to populate, or a
+   * {@link PlaceholderBinding} that states the `p:ph` to write
    * - when it matches a layout/master placeholder, the image inherits that placeholder's
    *   position and size for any of `x`/`y`/`w`/`h` not supplied explicitly;
    *   explicit values always win
+   * - a name that matches none writes no `p:ph`; a binding's `idx` or `type` writes one regardless
    * @example 'picph'
+   * @example { type: 'pic', idx: 13 }
    * @see https://docs.microsoft.com/en-us/office/vba/api/powerpoint.ppplaceholdertype
    */
-  placeholder?: string;
+  placeholder?: PlaceholderOption;
   /**
    * Image rotation (degrees)
    * - range: -360 to 360
@@ -531,8 +540,10 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
   /**
    * Crop the source image to a sub-region by percentage edge insets, emitted verbatim
    * as OOXML `<a:srcRect>`.
-   * - each value is the percent (0–100) trimmed off that edge of the *source* image, the
+   * - each value is the percent (at most 100) trimmed off that edge of the *source* image, the
    *   same model PowerPoint's Picture Format > Crop uses; `l`+`r` and `t`+`b` must each be < 100
+   * - a negative value pads that edge with empty space instead, as PowerPoint's Fit crop and
+   *   `sizing: 'contain'` do
    * - the remaining sub-region is stretched to fill the picture's displayed `w`×`h` box, so this
    *   is the faithful way to reproduce a deck that maps several icons out of one composite raster
    * - operates on the source image directly (independent of natural-pixel measurement), so unlike
@@ -541,13 +552,13 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
    * @example { l: 0, t: 0, r: 50, b: 50 } // keep the top-left quadrant of the source image
    */
   crop?: {
-    /** Percent (0–100) trimmed from the left edge of the source image. @default 0 */
+    /** Percent trimmed from the left edge of the source image; negative pads it. @default 0 */
     l?: number;
-    /** Percent (0–100) trimmed from the top edge of the source image. @default 0 */
+    /** Percent trimmed from the top edge of the source image; negative pads it. @default 0 */
     t?: number;
-    /** Percent (0–100) trimmed from the right edge of the source image. @default 0 */
+    /** Percent trimmed from the right edge of the source image; negative pads it. @default 0 */
     r?: number;
-    /** Percent (0–100) trimmed from the bottom edge of the source image. @default 0 */
+    /** Percent trimmed from the bottom edge of the source image; negative pads it. @default 0 */
     b?: number;
   };
   /**
@@ -559,7 +570,7 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
     /**
      * Sizing type
      * - `cover` / `contain` fit the image into the `w`×`h` box using the image's *natural*
-     *   aspect ratio — read from the embedded PNG/JPEG/GIF/BMP/WebP header, or from an SVG's
+     *   aspect ratio, read from the embedded PNG/JPEG/GIF/BMP/WebP header, or from an SVG's
      *   `width`/`height` or `viewBox`. If the natural size cannot be determined (an
      *   unrecognized format, or an SVG carrying neither) the displayed `w`/`h` ratio is used
      *   as a fallback and a warning is logged.
@@ -645,7 +656,7 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
   };
   /**
    * Recolor the image by mapping one source color to another (`<a:clrChange>`)
-   * - every pixel matching `from` is repainted `to` — the classic "swap the flat background out" recolour
+   * - every pixel matching `from` is repainted `to`: the classic "swap the flat background out" recolour
    *   (MS-PPT > Format Picture > Picture Color > Set Transparent Color is the single-colour sibling)
    * - colors accept `HexColor` or `ThemeColor`, same as fills / `duotone`
    * @example { from: '000000', to: 'FF0000' } // turn black pixels red
@@ -658,7 +669,7 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
   };
   /**
    * Raw SVG markup to embed as the image source
-   * - convenience for `data: 'data:image/svg+xml;base64,...'`; ts-pptx encodes it for you
+   * - convenience for `data: 'data:image/svg+xml;base64,...'`; pptx-ts encodes it for you
    * - ignored when `data` or `path` is also provided
    * @example '<svg viewBox="0 0 24 24">...</svg>'
    */
@@ -706,7 +717,7 @@ interface MediaBaseProps extends PositionProps, ObjectNameProps {
  */
 interface OleObjectBaseProps extends PositionProps, ObjectNameProps {
   /**
-   * Picture of the embedded document shown on the slide — a raster image `path` (Node/local)
+   * Picture of the embedded document shown on the slide: a raster image `path` (Node/local)
    * or base64 `data:` URI.
    * - the library is Node-first and cannot render an Office document, so when this is omitted a
    *   neutral gray placeholder is embedded; PowerPoint draws the live object over it, but every
@@ -728,7 +739,7 @@ interface OleObjectBaseProps extends PositionProps, ObjectNameProps {
    */
   extn?: string;
   /**
-   * OLE server ProgID — what PowerPoint launches on double-click.
+   * OLE server ProgID: what PowerPoint launches on double-click.
    * - defaults from the resolved extension (`xlsx` → `Excel.Sheet.12`, `docx` → `Word.Document.12`,
    *   `pptx` → `PowerPoint.Show.12`, anything else → `Package`)
    * @example 'Excel.Sheet.12'
@@ -763,7 +774,9 @@ type MediaProps = MediaBaseProps & ((DataOrPathRequiredProps & {
    */
   type: Exclude<MediaType, 'online'>;
   /**
-   * Optional video embed link metadata.
+   * Not written for embedded media: only `type: 'online'` reads `link`. An embedded
+   * clip links its own media part, so an outside link has nowhere to go, and setting
+   * it warns `media/option-not-supported`.
    */
   link?: string;
 }) | (DataOrPathProps & {
@@ -779,8 +792,6 @@ type MediaProps = MediaBaseProps & ((DataOrPathRequiredProps & {
    */
   link: string;
 }));
-//#endregion
-//#region src/types/text.d.ts
 /**
  * A drawn bullet: the object arm of {@link TextPropsOptions.bullet}.
  *
@@ -855,7 +866,7 @@ interface TextBaseProps {
    * {@link breakLine} is not the only paragraph boundary: two adjacent runs whose `align`
    * differs start a new one, so stating it on the opening run alone splits the paragraph in
    * two. That is the mirror of {@link bullet}, {@link paraMarginLeft} and {@link paraIndent},
-   * which are read from the opening run only. Neither mistake changes the run count — the
+   * which are read from the opening run only. Neither mistake changes the run count: the
    * only symptom is a differently shaped paragraph, with no error.
    * @default 'left'
    */
@@ -872,7 +883,7 @@ 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 whole
+   * 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'
@@ -882,22 +893,23 @@ interface TextBaseProps {
    * Add standard or custom bullet
    * - use `true` for standard bullet
    * - pass object options for custom bullet
-   * - `false` (and omitting the option) is the *explicit off*: it writes `<a:buNone/>`
-   *   plus `marL="0" indent="0"`, which overrides whatever bullet the layout's or
-   *   master's list style sets for this level
-   * - `'inherit'` states nothing at all — no bullet child and no margin attributes — so
-   *   the list style keeps reaching the paragraph. This is the one state omission
-   *   cannot spell, because omitting the option means `false` here for compatibility
+   * - `false` is the *explicit off*: it writes `<a:buNone/>` plus `marL="0" indent="0"`,
+   *   which overrides whatever bullet the layout's or master's list style sets for this level
+   * - `'inherit'` states nothing at all (no bullet child and no margin attributes), so
+   *   the list style keeps reaching the paragraph
+   * - omitting the option means `'inherit'` on a placeholder definition
+   *   (`defineSlideMaster({ objects })`), and on text filling a placeholder the layout
+   *   defines, which takes the definition's bullet. Anywhere else it means `false`
    *
    * The margins are only a *default* of the bullet state: {@link paraMarginLeft} and
    * {@link paraIndent} state `@marL`/`@indent` independently in any of the three, including
    * an inherited margin under a drawn bullet.
    *
    * When a shape's text is an array of runs, state this on the **opening run only**. A run
-   * that draws a bullet starts a new paragraph by itself, so repeating it — the placement
-   * that {@link align} requires — turns one three-run paragraph into three one-run
+   * that draws a bullet starts a new paragraph by itself, so repeating it (the placement
+   * that {@link align} requires) turns one three-run paragraph into three one-run
    * paragraphs. A paragraph takes its properties from its first run.
-   * @default false
+   * @default false, or `'inherit'` on a placeholder
    */
   bullet?: boolean | 'inherit' | TextBulletProps;
   /**
@@ -924,7 +936,7 @@ interface TextBaseProps {
    *
    * Applied to the Latin (`<a:latin>`) and complex-script (`<a:cs>`) font slots, matching
    * how PowerPoint writes a font picked from the UI. The East Asian slot (`<a:ea>`) is left
-   * to inherit from the theme unless `fontFaceEA` is set — forcing a Latin-only face into the
+   * to inherit from the theme unless `fontFaceEA` is set. Forcing a Latin-only face into the
    * East Asian slot duplicates/ghosts text in Office 365.
    * @example 'Arial' // Arial font
    */
@@ -932,8 +944,9 @@ interface TextBaseProps {
   /**
    * East Asian font face name (`<a:ea>` slot), used to render CJK (Chinese/Japanese/Korean) glyphs
    *
-   * Set this when the East Asian font differs from `fontFace`. When omitted, `<a:ea>` inherits the
-   * theme East Asian font, which is what PowerPoint does for Latin fonts.
+   * Independent of `fontFace`: set alone, it writes only `<a:ea>` and the Latin and complex-script
+   * slots keep inheriting. When omitted, `<a:ea>` inherits the theme East Asian font, which is what
+   * PowerPoint does for Latin fonts.
    * @example '微軟正黑體' // render East Asian glyphs with Microsoft JhengHei
    */
   fontFaceEA?: string;
@@ -960,12 +973,12 @@ interface TextBaseProps {
    */
   lang?: string;
   /**
-   * First-line indent (points) — `a:pPr/@indent`, the offset of the paragraph's FIRST line
+   * First-line indent (points): `a:pPr/@indent`, the offset of the paragraph's FIRST line
    * from {@link paraMarginLeft}. Negative hangs the first line to the left of the body, which
    * is what a bulleted paragraph does; positive indents it to the right, the "first line
    * indented" prose form. PowerPoint: Paragraph > Indentation > Special.
    * - `'inherit'` writes no `@indent` at all, so the paragraph takes whatever its list style
-   *   (`a:lstStyle` → placeholder → layout → master) sets — the same third state
+   *   (`a:lstStyle` → placeholder → layout → master) sets: the same third state
    *   {@link bullet} spells, on the attribute beside it
    * - omitting the option keeps the bullet-derived default: a drawn bullet hangs the first
    *   line by its margin, `bullet: false` writes `indent="0"`, `bullet: 'inherit'` writes
@@ -979,12 +992,12 @@ interface TextBaseProps {
    */
   paraIndent?: number | 'inherit';
   /**
-   * Left margin of the paragraph (points) — `a:pPr/@marL`, where the paragraph's body text
+   * Left margin of the paragraph (points): `a:pPr/@marL`, where the paragraph's body text
    * starts. This is the paragraph's own margin, not the text frame's internal padding
    * (`margin`) and not the discrete outline level (`indentLevel`, which writes `a:p/@lvl`).
    * PowerPoint: Paragraph > Indentation > Before text.
    * - `'inherit'` writes no `@marL` at all, so the paragraph takes whatever its list style
-   *   (`a:lstStyle` → placeholder → layout → master) sets — the third state that omission
+   *   (`a:lstStyle` → placeholder → layout → master) sets, the third state that omission
    *   cannot spell, since omitting it writes the bullet-derived default
    * - omitting the option keeps that default: a drawn bullet writes its own margin (see
    *   `bullet.indent`), `bullet: false` writes `marL="0"`, `bullet: 'inherit'` writes nothing
@@ -1031,11 +1044,15 @@ interface TextBaseProps {
    * - `style` is the full `ST_TextUnderlineType` enumeration (ECMA-376 §20.1.10.81)
    * - `'none'` is the *explicit off*: it writes `a:rPr/@u="none"`, which overrides an
    *   underline the run would otherwise inherit from its list style, placeholder, layout or
-   *   master. Omitting the option instead states nothing and lets that inheritance stand —
-   *   the two are different facts, not two spellings of one.
+   *   master. Omitting the option instead states nothing and lets that inheritance stand.
+   *   The two are different facts, not two spellings of one.
+   * - `true` is shorthand for `{ style: 'sng' }`, a single line. `false` states nothing, as omitting
+   *   the option does, so an inherited underline stands; `{ style: 'none' }` is the explicit off.
    * @default (unset) inherit
+   * @example underline: true // single underline
+   * @example underline: { style: 'dbl', color: 'FF0000' } // red double underline
    */
-  underline?: {
+  underline?: boolean | {
     style?: (typeof TEXT_UNDERLINE_TYPES)[number];
     color?: Color;
   };
@@ -1083,10 +1100,10 @@ interface TextFitShrinkProps {
    */
   lnSpcReduction?: number;
 }
-interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps, ObjectNameProps {
+interface TextPropsOptions extends PlaceholderPositionProps, DataOrPathProps, TextBaseProps, ObjectNameProps {
   /**
    * Preset-geometry start/end angles for text frames (`shape` + these build `<a:prstGeom>`
-   * adjustment guides through the shared emitter — `genXmlPresetGeom` reads them whether
+   * adjustment guides through the shared emitter, and `genXmlPresetGeom` reads them whether
    * the object is a shape or a styled text frame).
    */
   angleRange?: [number, number];
@@ -1096,11 +1113,28 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
   points?: GeometryPoint[];
   /** Preset-geometry adjustment guides for text frames. */
   shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
+  /**
+   * Baseline shift (`a:rPr/@baseline`): above zero raises the text, below zero lowers it.
+   *
+   * A percent of the font size, so `30` raises the text by 30% (what `superscript` writes) and
+   * `-40` lowers it by 40% (what `subscript` writes). It is written in thousandths of a percent,
+   * rounded. `0`, like leaving the option out, states no shift. Wins over `superscript` and
+   * `subscript` when both are set.
+   */
   baseline?: number;
   /**
    * Character spacing
    */
   charSpacing?: number;
+  /**
+   * Kerning (`a:rPr/@kern`): the smallest font size, in points, that gets pair kerning. Text at
+   * this size or larger is kerned, smaller text is not, and `0` turns kerning off.
+   * - PowerPoint: Font > Character Spacing > "Kerning for fonts: _ Points and above"
+   * - range: 0-4000
+   * @example 12 // kern text set at 12pt or larger, PowerPoint's own default
+   * @default undefined // no `kern`, except that a non-zero `charSpacing` writes `kern="0"`
+   */
+  kerning?: number;
   /**
    * Number of text columns in the text body
    * - PowerPoint: Format Shape > Shape Options > Size & Properties > Text Box > Columns > "Number"
@@ -1126,7 +1160,7 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
    * - 'resize' = Resize shape to fit text
    *
    * **Measured fit:** if you register the box's font with
-   * {@link TsPptx.registerFontMetrics}, both `'shrink'` and `'resize'` are
+   * {@link PptxTs.registerFontMetrics}, both `'shrink'` and `'resize'` are
    * **measured at export time**, so the text renders correctly in headless renderers
    * and on plain file-open (no edit/resize needed):
    * - `'shrink'` computes the largest `fontScale` at which the wrapped text fits and
@@ -1170,7 +1204,7 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
   glow?: TextGlowProps;
   hyperlink?: HyperlinkProps;
   /**
-   * Outline level of the paragraph (`a:p/@lvl`) — which of the list style's nine levels the
+   * 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
@@ -1196,7 +1230,7 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
    */
   lineSpacingMultiple?: number;
   /**
-   * Margin (inches) — the text-frame internal margin/padding
+   * Margin (inches): the text-frame internal margin/padding
    * - PowerPoint: Format Shape > Shape Options > Size & Properties > Text Box > Left/Right/Top/Bottom margin (shown in inches)
    * - array order is `[top, right, bottom, left]`
    * - a value `>= 1` is honored as inches but warns once (it is likely a legacy points value; divide by 72)
@@ -1220,6 +1254,9 @@ 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.
+   * - a {@link PlaceholderBinding} states the `p:ph` in full: its `name` binds as the string
+   *   does, and its `type` and `idx` are written whether or not a layout placeholder matches,
+   *   which is how text fills a placeholder of a layout this deck does not define
    *
    * **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
@@ -1232,9 +1269,10 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
    * 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'
+   * @example { type: 'body', idx: 1 }
    * @see https://learn.microsoft.com/en-us/office/vba/api/powerpoint.ppplaceholdertype
    */
-  placeholder?: string;
+  placeholder?: PlaceholderOption;
   /**
    * 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
@@ -1258,7 +1296,7 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
    * 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
+   * - 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.
@@ -1272,13 +1310,13 @@ interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps
   shadow?: ShadowProps;
   shape?: SHAPE_NAME;
   /**
-   * Strikethrough (`a:rPr/@strike`, `ST_TextStrikeType` — ECMA-376 §20.1.10.78)
+   * Strikethrough (`a:rPr/@strike`, `ST_TextStrikeType`, ECMA-376 §20.1.10.78)
    * - `true` is `'sngStrike'`; `'dblStrike'` is the double rule
    * - `'noStrike'` is the *explicit off*: it writes `strike="noStrike"`, which overrides a
    *   strikethrough the run would otherwise inherit from its list style, placeholder, layout
    *   or master
    * - `false`, like leaving the option out, writes no attribute at all and so states
-   *   *nothing* — the run keeps whatever it inherits. This matches `bold`/`italic`, whose
+   *   *nothing*: the run keeps whatever it inherits. This matches `bold`/`italic`, whose
    *   falsy arm is likewise an omission; reach for `'noStrike'` when the intent is "not
    *   struck" rather than "unspecified"
    * @default (unset) inherit
@@ -1320,8 +1358,8 @@ interface TextProps {
    */
   math?: string;
   /**
-   * Emit this item's `math` equation *inline* — an `<a14:m><m:oMath>` run flowing mid-paragraph
-   * between the surrounding plain text runs — instead of as its own centered display-math
+   * Emit this item's `math` equation *inline* (an `<a14:m><m:oMath>` run flowing mid-paragraph
+   * between the surrounding plain text runs) instead of as its own centered display-math
    * paragraph. Has no effect unless `math` is set. Pair with the bare-`<m:oMath>` inline form of
    * the equation: `latexToOmml(tex, { display: false })` or `mathmlToOmml(mathml)`.
    * @example addText([{ text: 'where ' }, { math: latexToOmml('x^2+1=y', { display: false }), inline: true }, { text: ' holds' }])
@@ -1329,9 +1367,9 @@ interface TextProps {
   inline?: boolean;
 }
 /**
- * Options for layout-time text measurement ({@link TsPptx.measureText}).
- * Inches for width, points for type/spacing — the consumer-facing units. The
- * measured face must have metrics registered via {@link TsPptx.registerFontMetrics}
+ * Options for layout-time text measurement ({@link PptxTs.measureText}).
+ * Inches for width, points for type/spacing: the consumer-facing units. The
+ * measured face must have metrics registered via {@link PptxTs.registerFontMetrics}
  * (a named face without exact metrics uses a conservative heuristic; an unnamed
  * theme-default face is unmeasurable).
  */
@@ -1358,7 +1396,7 @@ interface MeasureTextOptions {
   insetIn?: number;
 }
 /**
- * Result of {@link TsPptx.measureText}. Heights err **tall** (conservative) —
+ * Result of {@link PptxTs.measureText}. Heights err **tall** (conservative):
  * they match the value the export-time autofit bake uses, so the laid-out height is
  * ≥ what PowerPoint/LibreOffice render. Use it to grow a container; for an overflow
  * check it may slightly over-report (good for a warning, not a hard gate).
@@ -1366,10 +1404,10 @@ interface MeasureTextOptions {
 interface TextMeasurement {
   /** Laid-out height in inches at the given `fontSize` (conservative/tall). */
   heightIn: number;
-  /** Number of wrapped lines (conservative — the model wraps marginally early). */
+  /** Number of wrapped lines (conservative: the model wraps marginally early). */
   lineCount: number;
   /**
-   * Width in inches of the widest laid-out line (conservative — the model wraps
+   * Width in inches of the widest laid-out line (conservative: the model wraps
    * marginally early, so this errs slightly wide). With an unconstrained `wIn` it
    * is the natural single-line width; constrained, it is the widest wrapped line.
    * A box set to this width will not re-wrap the text.
@@ -1379,15 +1417,15 @@ interface TextMeasurement {
   measurable: boolean;
   /**
    * The **named** faces laid out with the conservative average-advance heuristic
-   * instead of their real metrics — i.e. faces with no registered metrics. Empty
+   * instead of their real metrics, i.e. faces with no registered metrics. Empty
    * when every run was measured exactly (and for an unmeasurable result, which
    * guessed nothing). The numbers stay conservative (they err tall/wide), but a
    * non-empty list means they are an approximation, not a measurement; register
-   * the face via {@link TsPptx.registerFontMetrics} for an exact result.
+   * the face via {@link PptxTs.registerFontMetrics} for an exact result.
    */
   approximatedFaces: string[];
   /**
-   * Code points in the measured text — sorted, deduplicated — whose run resolved to a
+   * Code points in the measured text (sorted, deduplicated) whose run resolved to a
    * **registered** face that has no glyph for them. Empty for fully covered text.
    *
    * Unlike everything else here, a non-empty list means the numbers are **not reliably
@@ -1399,7 +1437,7 @@ interface TextMeasurement {
    * and the text overflow. Register a face that covers them (or set an explicit
    * `fontFace` on those runs) before trusting the height.
    *
-   * Faces with no registered metrics are not audited — they measure through the
+   * Faces with no registered metrics are not audited: they measure through the
    * cmap-less heuristic and are reported in {@link approximatedFaces} instead.
    * `String.fromCodePoint(...uncoveredCodepoints)` renders the list.
    */
@@ -1409,13 +1447,13 @@ interface TextMeasurement {
   /** The `fontScale` (percent) that fits inner height `hIn`; `100` if it already fits, never below the shrink floor. */
   shrinkScaleFor: (hIn: number) => number;
 }
-/** Options for {@link TsPptx.overflowsBox}: a measure plus the box inner height to test against. */
+/** Options for {@link PptxTs.overflowsBox}: a measure plus the box inner height to test against. */
 interface OverflowBoxOptions extends MeasureTextOptions {
   /** Box inner height in inches to test for overflow. */
   hIn: number;
 }
 /**
- * One cell's computed rectangle from {@link TsPptx.tableLayout}. All values are
+ * One cell's computed rectangle from {@link PptxTs.tableLayout}. All values are
  * inches; `x`/`y` are absolute (offset from the table's `x`/`y`). For a merged cell,
  * `row`/`col` are the top-left origin and `wIn`/`hIn` cover the whole span; the
  * cells it covers are not emitted separately.
@@ -1440,12 +1478,12 @@ interface TableCellLayout {
   /**
    * `true` when `hIn`/`yIn` are pinned by an explicit `rowH` (array or scalar) or
    * table `h`; `false` when the row is auto-height and the value is a conservative
-   * (tall) estimate from the same text model as {@link TsPptx.measureText}.
+   * (tall) estimate from the same text model as {@link PptxTs.measureText}.
    */
   heightExact: boolean;
 }
 /**
- * Result of {@link TsPptx.tableLayout}: per-cell geometry plus overall table
+ * Result of {@link PptxTs.tableLayout}: per-cell geometry plus overall table
  * bounds, for placing images/shapes over a table without rendering it. Geometry is
  * for a single, un-paginated table laid out at `opts.x`/`y`/`w`; `autoPage` paging
  * is not modeled. Widths are exact; auto-height row heights are conservative
@@ -1463,8 +1501,8 @@ interface TableLayoutResult {
 }
 /**
  * Per-run options for a speaker-notes text run.
- * A focused subset of `TextPropsOptions`: inline formatting plus an (external URL) hyperlink.
- * Notes hyperlinks support `url` only; `slide` targets are not yet supported.
+ * A focused subset of `TextPropsOptions`: inline formatting plus a hyperlink, which takes a
+ * `url`, a `slide` or an `action` as on a slide.
  */
 type NotesTextOptions = Pick<TextPropsOptions, 'hyperlink' | 'bold' | 'italic' | 'underline' | 'color' | 'fontSize' | 'fontFace'>;
 /** A single speaker-notes text run: text plus optional inline formatting / hyperlink. */
@@ -1510,18 +1548,29 @@ interface ResolvedCommentAuthor {
 declare function textRun(text: string | number, options?: TextPropsOptions): TextProps;
 /** Wraps a run array so TypeScript accepts it as `TextProps[]` without a cast. */
 declare function textRuns(runs: TextProps[]): TextProps[];
-//#endregion
-//#region src/types/object.d.ts
 /**
  * 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}.
+ *
+ * A definition states no bullet, left margin or first-line indent unless given one, so the
+ * master's `textStyles` reach its slides; `bullet: false` turns the bullet off on this layout.
  */
 interface PlaceholderProps extends PositionProps, TextBaseProps, ObjectNameProps, Pick<TextPropsOptions, 'fill' | 'hyperlink'> {
   name: string;
-  type: PLACEHOLDER_TYPE;
   /**
-   * margin (inches) — text-frame internal margin; a value `>= 1` warns as a likely legacy points value
+   * `p:ph/@type`: one of the six friendly types, or any `ST_PlaceholderType` value (`ctrTitle`,
+   * `subTitle`, `obj`, `dt`, `ftr`, `sldNum`, …).
+   */
+  type: PLACEHOLDER_TYPE | PlaceholderXmlType;
+  /**
+   * `p:ph/@idx`, a non-negative integer a slide object binds to by stating the same `idx`.
+   * Omitted, it is 100 plus the object's position in `objects`. `0` writes none, as PowerPoint
+   * writes for a title.
+   */
+  idx?: number;
+  /**
+   * margin (inches): text-frame internal margin; a value `>= 1` warns as a likely legacy points value
    */
   margin?: Margin;
   /**
@@ -1537,6 +1586,36 @@ interface PlaceholderProps extends PositionProps, TextBaseProps, ObjectNameProps
    */
   rectRadius?: number;
 }
+/**
+ * A slide object's placeholder binding stated in full: the `p:ph` it writes, with or without a
+ * layout placeholder of that name in the same deck.
+ *
+ * The string form of `placeholder` binds only to a placeholder the deck's own layout defines by
+ * name, and takes its `idx` from there. A slide that fills a placeholder of a layout the deck does
+ * not define, such as one from a template it is appended to, needs the `idx` stated, because
+ * PowerPoint matches a slide placeholder to its layout's by `idx`.
+ * @example { idx: 1 } // the content placeholder of PowerPoint's "Title and Content" layout
+ * @example { type: 'ctrTitle' } // the title of a title slide
+ */
+interface PlaceholderBinding {
+  /**
+   * Name of a layout placeholder defined in this deck, as the string form takes it. The object
+   * inherits its options and frame, and its `type` and `idx` unless they are stated here too.
+   */
+  name?: string;
+  /**
+   * `p:ph/@type`. Omitted, it is the named layout placeholder's type, else none, which
+   * PowerPoint reads as `obj`.
+   */
+  type?: PlaceholderXmlType;
+  /**
+   * `p:ph/@idx`, a non-negative integer. Omitted, it is the named layout placeholder's index,
+   * else none, which PowerPoint reads as `0`.
+   */
+  idx?: number;
+}
+/** A slide object's `placeholder`: a layout placeholder's name, or a {@link PlaceholderBinding}. */
+type PlaceholderOption = string | PlaceholderBinding;
 interface ObjectNameProps {
   /**
    * Object name
@@ -1577,6 +1656,8 @@ interface ObjectNameProps {
 interface ObjectLockProps {
   /** Disallow grouping/ungrouping with other objects. (shapes, images, tables) */
   noGrp?: boolean;
+  /** Disallow ungrouping the group (`a:grpSpLocks/@noUngrp`). (groups only) */
+  noUngrp?: boolean;
   /** Disallow selecting the object. (shapes, images, tables) */
   noSelect?: boolean;
   /** Disallow moving the object. (shapes, images, tables) */
@@ -1605,14 +1686,14 @@ interface ObjectLockProps {
 /**
  * The object descriptors a slide master and a group child both accept.
  *
- * Both surfaces take a key-tagged descriptor — one key naming the object kind, its value the
- * options for that kind — and both accepted the same six. They were written out twice, and the
+ * Both surfaces take a key-tagged descriptor (one key naming the object kind, its value the
+ * options for that kind), and both accepted the same six. They were written out twice, and the
  * doc on `GroupChildProps` said as much in as many words: "Uses the same key-tagged descriptor
  * shape as `SlideMasterObject`". That coupling was real and maintained by hand, which meant a
  * seventh descriptor added to one was silently missing from the other.
  *
- * Each union is now this plus what is genuinely its own — a master adds `chart` and
- * `placeholder`, a group child adds `group` — so the difference between them is the part you
+ * Each union is now this plus what is genuinely its own (a master adds `chart` and
+ * `placeholder`, a group child adds `group`), so the difference between them is the part you
  * read, and the shared vocabulary is stated once.
  */
 type CommonObjectDescriptor = {
@@ -1643,8 +1724,6 @@ type CommonObjectDescriptor = {
     options?: TextPropsOptions;
   };
 };
-//#endregion
-//#region src/types/chart.d.ts
 /**
  * An axis' tick marks (`ST_TickMark`): `in` and `out` of the axis line, `cross` through it, or `none`.
  *
@@ -1675,10 +1754,13 @@ interface OptsChartData {
    */
   sizes?: number[];
   /**
-   * category values
+   * category values. A `null` is a gap: the point has no value, and the embedded workbook
+   * holds an empty cell for it. How a line or area chart draws across one is
+   * `displayBlanksAs`.
    * @example [2000, 2010, 2020]
+   * @example [5, null, 7] // no value for the second category
    */
-  values?: number[];
+  values?: Array<number | null>;
   /**
    * Custom text label per data point, replacing the auto-generated value label.
    * Index aligns with `values[]`. Empty string or missing entries fall back to the chart-level label settings.
@@ -1758,11 +1840,11 @@ interface ChartErrorBarOptions extends StrokeProps {
   barType?: ErrorBarType;
   /**
    * How `value` (or `plusValues`/`minusValues`) is interpreted.
-   * - `'fixedVal'` — fixed amount in axis units
-   * - `'percentage'` — percent of each value (e.g. `value: 5` → ±5%)
-   * - `'stdDev'` — `value` standard deviations
-   * - `'stdErr'` — standard error (ignores `value`)
-   * - `'cust'` — explicit per-point amounts via `plusValues`/`minusValues`
+   * - `'fixedVal'`: fixed amount in axis units
+   * - `'percentage'`: percent of each value (e.g. `value: 5` → ±5%)
+   * - `'stdDev'`: `value` standard deviations
+   * - `'stdErr'`: standard error (ignores `value`)
+   * - `'cust'`: explicit per-point amounts via `plusValues`/`minusValues`
    * @default 'fixedVal'
    */
   valueType?: ErrorBarValueType;
@@ -1807,7 +1889,7 @@ interface OptsChartGridLine extends StrokeProps {
    *
    * `'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
+   * 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.
@@ -1817,7 +1899,11 @@ interface OptsChartGridLine extends StrokeProps {
 interface ChartMulti {
   type: CHART_NAME;
   data: OptsChartData[];
-  options: ChartOpts;
+  /**
+   * This subchart's options, merged over the combo chart's own. Omitted, the subchart takes the
+   * chart's options as they are.
+   */
+  options?: ChartOpts;
 }
 interface ChartPropsFillLine {
   /**
@@ -1829,16 +1915,17 @@ interface ChartPropsFillLine {
    * PowerPoint: Format Chart Area/Plot Area > Fill
    *
    * Omitting `fill` leaves the area transparent (`<a:noFill/>`), as does a `fill` that
-   * states neither a `color` nor a `type` — `transparency` alone is not a fill, since
+   * states neither a `color` nor a `type`: `transparency` alone is not a fill, since
    * there is no colour for the alpha to apply to.
    *
-   * `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.
+   * `type: 'image'` paints a picture, which the chart part references through a relationship of
+   * its own. A chartEx chart (waterfall, funnel, …) writes no area fill at all.
    * @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: 'image', image: {path: 'paper.png'}} // a picture, stretched over the area
    * @example fill: {type: 'inherit'} // no fill child at all -- take the chart style's fill
    */
   fill?: FillOption;
@@ -1856,7 +1943,7 @@ interface ChartPropsBase {
    * 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.
    *
-   * Omitting it, or passing an empty array, both mean the same thing — the built-in default
+   * Omitting it, or passing an empty array, both mean the same thing: the built-in default
    * palette for the chart type. Two spellings of "I named no colours"; there is no third state
    * that suppresses the fills.
    */
@@ -1887,7 +1974,7 @@ interface ChartPropsBase {
    */
   showBubbleSize?: boolean;
   /**
-   * Enable data labels, with a meaning that is **overloaded per plot type** — it is not a
+   * 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: turns on the labels {@link ChartPropsDataLabel.dataLabelFormatScatter} describes,
@@ -1970,7 +2057,7 @@ interface ChartPropsBase {
   /**
    * Per-series style overrides.
    *
-   * Element at index N applies to the **Nth series of the chart** — the same number the series
+   * 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
@@ -2026,9 +2113,9 @@ interface ChartPropsAxisCat {
    * 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
+   * 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.
+   * `'every other'` reach the attribute), and is read with `Number()` like any other.
    */
   catAxisLabelFrequency?: number | string;
   catAxisLabelPos?: TickLabelPosition;
@@ -2111,6 +2198,13 @@ interface ChartPropsAxisCat {
   catAxisTitleFontSize?: number;
   catAxisTitleRotate?: number;
   catGridLine?: OptsChartGridLine;
+  /**
+   * Date format for the category labels, which makes the category axis a date axis (`c:dateAx`).
+   * - Example: `'yyyy-mm-dd'`, `'mmm yyyy'`
+   * - labels: ISO dates or date-times (`'2026-01-01'`, `'2026-01-01T12:00'`) or date serial numbers;
+   *   ISO ones are written as their serials. A label that is neither warns and the categories stay text.
+   * - PowerPoint: Format Axis > Number > Format Code
+   */
   catLabelFormatCode?: string;
   /**
    * Whether data should use secondary category axis (instead of primary)
@@ -2139,7 +2233,7 @@ interface ChartPropsAxisSer {
   serAxisLabelFrequency?: number | string;
   serAxisLabelPos?: TickLabelPosition;
   /**
-   * The series axis line, as a stroke — the same {@link StrokeProps} the other two axes and
+   * 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
@@ -2215,7 +2309,7 @@ interface ChartPropsAxisVal {
   valAxisLabelPos?: TickLabelPosition;
   valAxisLabelRotate?: number;
   /**
-   * The value axis line, as a stroke — the same {@link StrokeProps} the other two axes and
+   * 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;
@@ -2256,7 +2350,7 @@ interface ChartPropsAxisVal {
   valAxisMaxVal?: number;
   valAxisMinorTickMark?: ChartAxisTickMark;
   /**
-   * Spacing between minor tick marks on the value axis (`c:minorUnit`) — the sibling
+   * 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
    */
@@ -2345,7 +2439,7 @@ interface ChartPropsChartLine {
    */
   lineDash?: ChartLineDash;
   /**
-   * Per-series dash type overrides; index matches the series order in the `data` array — and on a
+   * 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
@@ -2431,7 +2525,7 @@ interface ChartPropsChartWaterfall {
  * today is which side of each bin interval is closed.
  *
  * NOTE: explicit bin geometry (fixed bin width / bin count / overflow / underflow) is not yet
- * supported — PowerPoint desktop rejects the decks those settings produce, so they are deferred.
+ * supported: PowerPoint desktop rejects the decks those settings produce, so they are deferred.
  */
 interface ChartExBinning {
   /** Which side of each bin interval is closed: `'r'` (right, the default) or `'l'` (left). */
@@ -2452,7 +2546,7 @@ interface ChartPropsChartHistogram {
  */
 interface ChartExStatistics {
   /**
-   * How the first/third quartiles are computed: `'exclusive'` (PowerPoint's default — the median
+   * How the first/third quartiles are computed: `'exclusive'` (PowerPoint's default: the median
    * is excluded when splitting the halves) or `'inclusive'`.
    */
   quartileMethod?: 'inclusive' | 'exclusive';
@@ -2479,7 +2573,7 @@ interface ChartPropsChartBoxWhisker {
  * PowerPoint resolves against its Bing-backed geography database when the deck is opened.
  *
  * These fields tell PowerPoint how to interpret ambiguous region names (e.g. "Georgia" the country
- * vs. the US state). They do NOT change what ts-pptx writes beyond the `<cx:geography>` hint —
+ * vs. the US state). They do NOT change what pptx-ts writes beyond the `<cx:geography>` hint:
  * the actual map is resolved and rendered by PowerPoint 2016+/Microsoft 365 at open time, so the
  * region names must match PowerPoint's geography database or the map renders blank.
  */
@@ -2499,12 +2593,12 @@ interface ChartPropsChartRegionMap {
 }
 interface ChartPropsChartStock {
   /**
-   * Stock (high-low-close) chart style — selects how many value series the chart expects and how
+   * Stock (high-low-close) chart style: selects how many value series the chart expects and how
    * they are drawn. The data series must be supplied in the exact order implied by the style:
-   * - `'hlc'` — High, Low, Close (3 series). The close is marked with a dot.
-   * - `'ohlc'` — Open, High, Low, Close (4 series). Open→close is drawn as up/down bars.
-   * - `'vhlc'` — Volume, High, Low, Close (4 series). Volume is a column on its own axis.
-   * - `'vohlc'` — Volume, Open, High, Low, Close (5 series). Volume column + up/down bars.
+   * - `'hlc'`: High, Low, Close (3 series). The close is marked with a dot.
+   * - `'ohlc'`: Open, High, Low, Close (4 series). Open→close is drawn as up/down bars.
+   * - `'vhlc'`: Volume, High, Low, Close (4 series). Volume is a column on its own axis.
+   * - `'vohlc'`: Volume, Open, High, Low, Close (5 series). Volume column + up/down bars.
    *
    * `<c:hiLowLines>` connect the high/low of each category in every style.
    * @default 'hlc'
@@ -2658,9 +2752,9 @@ 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, PositionProps {
+interface ChartOpts extends ChartPropsAxisCat, ChartPropsAxisSer, ChartPropsAxisVal, ChartPropsBase, ChartPropsChartBar, ChartPropsChartDoughnut, ChartPropsChartLine, ChartPropsChartPie, ChartPropsChartRadar, ChartPropsChartWaterfall, ChartPropsChartHistogram, ChartPropsChartBoxWhisker, ChartPropsChartRegionMap, ChartPropsChartStock, ChartPropsChartSurface, ChartPropsDataLabel, ChartPropsDataTable, ChartPropsLegend, ChartPropsTitle, ObjectNameProps, PlaceholderPositionProps {
   /**
-   * Chart type — required when using the canonical `addChart(data, options)` signature.
+   * 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`.
    */
   type?: CHART_NAME;
@@ -2669,9 +2763,19 @@ interface ChartOpts extends ChartPropsAxisCat, ChartPropsAxisSer, ChartPropsAxis
    * - PowerPoint: [right-click on a chart] > "Edit Alt Text..."
    */
   altText?: string;
+  /**
+   * Name of a placeholder defined on the slide layout/master to fill, or a
+   * {@link PlaceholderBinding} that states the `p:ph` to write
+   * - when it matches a layout/master placeholder, the chart takes that placeholder's position
+   *   and size for any of `x`/`y`/`w`/`h` not supplied explicitly; explicit values always win
+   * - a name that matches none writes no `p:ph`; a binding's `idx` or `type` writes one regardless
+   * @example 'chartph'
+   * @example { type: 'chart', idx: 13 }
+   */
+  placeholder?: PlaceholderOption;
   /**
    * Custom chart-level metadata, emitted as a schema-valid extension on the chart space
-   * (`c:chartSpace/c:extLst`) under a stable ts-pptx vendor GUID.
+   * (`c:chartSpace/c:extLst`) under a stable pptx-ts vendor GUID.
    * - Use for round-trippable, machine-readable annotations a consumer wants to travel with the
    *   chart (e.g. a source-data id, a generator tag, a semantic role). PowerPoint preserves the
    *   extension untouched and ignores it for rendering.
@@ -2681,8 +2785,6 @@ interface ChartOpts extends ChartPropsAxisCat, ChartPropsAxisSer, ChartPropsAxis
    */
   metadata?: Record<string, string>;
 }
-//#endregion
-//#region src/types/style.d.ts
 /**
  * A stroke, stated once.
  *
@@ -2692,8 +2794,8 @@ interface ChartOpts extends ChartPropsAxisCat, ChartPropsAxisSer, ChartPropsAxis
  * 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.
  *
- * 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
+ * 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.
  *
  * {@link ShapeLineProps} is deliberately *not* an alias: a shape stroke is a **paint**, so its
@@ -2714,7 +2816,7 @@ interface StrokeProps {
    * 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 —
+   * **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 stroke entirely and is decided before any dash
    * pattern is chosen. An unrecognized value warns and falls back to what `type` implies.
@@ -2722,7 +2824,7 @@ interface StrokeProps {
    */
   dashType?: PresetLineDashVal;
   /**
-   * Stroke colour — a 6-digit hex RGB or a `SchemeColor` token.
+   * Stroke colour: a 6-digit hex RGB or a `SchemeColor` token.
    * @example 'FF3399'
    * @example SchemeColor.accent1
    */
@@ -2757,26 +2859,50 @@ type BorderProps = StrokeProps;
  * `HyperlinkProps.slide` instead (which emits `ppaction://hlinksldjump`).
  */
 type HyperlinkActionJump = 'firstslide' | 'previousslide' | 'nextslide' | 'lastslide' | 'lastslideviewed' | 'endshow';
-interface HyperlinkProps {
+/** What every {@link HyperlinkProps} takes beside its one destination. */
+interface HyperlinkBaseProps {
   /**
-   * The 1-based number of the slide to link to. The deck has to have that slide when it is written.
+   * Hyperlink Tooltip
    */
-  slide?: number;
+  tooltip?: string;
+}
+/** A hyperlink to a URL. */
+interface UrlHyperlinkProps extends HyperlinkBaseProps {
   /**
    * Url to link to
    */
-  url?: string;
+  url: string;
+  slide?: never;
+  action?: never;
+}
+/** A hyperlink to another slide of the deck. */
+interface SlideHyperlinkProps extends HyperlinkBaseProps {
   /**
-   * Hyperlink Tooltip
+   * The 1-based number of the slide to link to. The deck has to have that slide when it is written.
    */
-  tooltip?: string;
+  slide: number;
+  url?: never;
+  action?: never;
+}
+/** A slide-show navigation action, such as "next slide". */
+interface ActionHyperlinkProps extends HyperlinkBaseProps {
   /**
-   * Slide-show navigation action for action-button shapes. Emits a relationship-less
-   * `<a:hlinkClick action="ppaction://hlinkshowjump?jump=…"/>` on the shape.
+   * Slide-show navigation action. Emits a relationship-less
+   * `<a:hlinkClick action="ppaction://hlinkshowjump?jump=…"/>` on the shape when the shape states
+   * it (an action button), or on the run when a text run states it, as PowerPoint writes a jump
+   * set on selected text. A shape's action is not repeated on its runs.
    * @example hyperlink: { action: 'nextslide' }
    */
-  action?: HyperlinkActionJump;
+  action: HyperlinkActionJump;
+  url?: never;
+  slide?: never;
 }
+/**
+ * A click hyperlink, which names exactly one destination: a `url`, a `slide` or an `action`.
+ * @example hyperlink: { url: 'https://github.com', tooltip: 'GitHub' }
+ * @example hyperlink: { slide: 3 }
+ */
+type HyperlinkProps = UrlHyperlinkProps | SlideHyperlinkProps | ActionHyperlinkProps;
 interface ShadowProps {
   /**
    * shadow type
@@ -2830,7 +2956,7 @@ interface ShadowProps {
  * 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
+ * `<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.
  *
@@ -2864,7 +2990,7 @@ interface ShapeFillProps {
    * `'none'` and `'inherit'` are different states, and both have to be spelled out
    * because omitting `fill` is not one of them: the shape/text-box emitter defaults a
    * missing `fill` to `<a:noFill/>`.
-   * - `'none'` emits `<a:noFill/>` — an explicit transparent interior.
+   * - `'none'` emits `<a:noFill/>`, an explicit transparent interior.
    * - `'inherit'` emits no fill child at all, leaving the interior to
    *   `p:style/a:fillRef` or the placeholder. This is the only way to author that
    *   state from `addShape`/`addText`.
@@ -2874,7 +3000,7 @@ interface ShapeFillProps {
    * 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,
+   * `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
@@ -2909,33 +3035,38 @@ interface ShapeFillProps {
  *
  * **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
+ * `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' }`.
+ * 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 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).
+   *
+   * `'inherit'` leaves the whole outline to `p:style/a:lnRef` or the placeholder: no paint,
+   * and no 1pt or solid defaults for `width` and `dashType`. A width, dash, cap or arrowhead
+   * you state is still written over what is inherited.
+   * @example { type: 'inherit' } // an empty <a:ln>: paint, width and dash all inherited
    * @default 'solid'
    */
   type?: 'none' | 'inherit' | 'solid' | 'gradient' | 'pattern';
   /**
    * Line width (pt)
-   * @default 1
+   * @default 1, or inherited when `type` is `'inherit'`
    */
   width?: number;
   /**
-   * Dash type — the full `ST_PresetLineDashVal` set, so any dash a source deck can
+   * Dash type: the full `ST_PresetLineDashVal` set, so any dash a source deck can
    * carry can also be authored and replicated.
-   * @default 'solid'
+   * @default 'solid', or inherited when `type` is `'inherit'`
    */
   dashType?: PresetLineDashVal;
   /**
@@ -2944,11 +3075,11 @@ interface ShapeLineProps extends Omit<ShapeFillProps, 'type' | 'image'> {
    */
   cap?: LineCap;
   /**
-   * Begin arrow type — the `ST_LineEndType` set (`a:headEnd/@type`).
+   * Begin arrow type: the `ST_LineEndType` set (`a:headEnd/@type`).
    */
   beginArrowType?: LineEndType;
   /**
-   * End arrow type — the `ST_LineEndType` set (`a:tailEnd/@type`).
+   * End arrow type: the `ST_LineEndType` set (`a:tailEnd/@type`).
    */
   endArrowType?: LineEndType;
 }
@@ -2973,7 +3104,7 @@ interface ConnectorProps {
   /**
    * Number of adjustable bends (jogs) for an `elbow` / `curved` connector. Selects the
    * preset variant and how many `adj` values it accepts:
-   * - `1` → `bentConnector3` / `curvedConnector3` (one jog) — the default
+   * - `1` → `bentConnector3` / `curvedConnector3` (one jog), the default
    * - `2` → `bentConnector4` / `curvedConnector4` (two jogs)
    * - `3` → `bentConnector5` / `curvedConnector5` (three jogs)
    *
@@ -2998,13 +3129,13 @@ 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. The
+   * 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;
   /**
-   * Connection-site index on `startShape` (0-based; the valid range is preset-dependent — a
+   * Connection-site index on `startShape` (0-based; the valid range is preset-dependent: a
    * shape's `<a:cxnLst>` enumerates its sites). Ignored without `startShape`.
    * @default 0
    */
@@ -3016,7 +3147,7 @@ interface ConnectorProps {
    * @default 0
    */
   endShapeIdx?: number;
-  /** Start point X — inches, or a `Coord` such as `'50%'` / `'2in'` */
+  /** Start point X: inches, or a `Coord` such as `'50%'` / `'2in'` */
   x1: Coord;
   /** Start point Y */
   y1: Coord;
@@ -3045,10 +3176,8 @@ interface ConnectorProps {
   /** Accessibility alt text */
   altText?: string;
 }
-//#endregion
-//#region src/types/core.d.ts
 /**
- * Coordinate value. A bare `number` is **always inches** — there is no magnitude-based unit
+ * Coordinate value. A bare `number` is **always inches**; there is no magnitude-based unit
  * guessing. For other units use an explicit string suffix:
  * - `number` → inches (e.g. `10.25`)
  * - `"<n>%"` → percentage of the slide axis (e.g. `"75%"`)
@@ -3095,6 +3224,36 @@ interface PositionProps {
    */
   w?: Coord;
 }
+/**
+ * {@link PositionProps} for an object that can fill a layout placeholder: text, an image, a table
+ * or a chart. Each axis also takes `null`, which leaves it unstated, as omitting it does. With
+ * `placeholder`, an unstated axis comes from the layout placeholder; without one, it takes the
+ * object's default. `null` is how a computed value says "unset" where `exactOptionalPropertyTypes`
+ * refuses `undefined`.
+ * @example { placeholder: 'body', x: indent ?? null } // the placeholder's left edge unless indented
+ */
+interface PlaceholderPositionProps {
+  /**
+   * Horizontal position, as {@link PositionProps.x}. `null` leaves it unstated: the layout
+   * placeholder's, with `placeholder`.
+   */
+  x?: Coord | null;
+  /**
+   * Vertical position, as {@link PositionProps.y}. `null` leaves it unstated: the layout
+   * placeholder's, with `placeholder`.
+   */
+  y?: Coord | null;
+  /**
+   * Height, as {@link PositionProps.h}. `null` leaves it unstated: the layout placeholder's, with
+   * `placeholder`.
+   */
+  h?: Coord | null;
+  /**
+   * Width, as {@link PositionProps.w}. `null` leaves it unstated: the layout placeholder's, with
+   * `placeholder`.
+   */
+  w?: Coord | null;
+}
 /**
  * Reusable optional data/path fields.
  * Use `DataOrPathRequiredProps` for APIs that require at least one source.
@@ -3123,7 +3282,7 @@ type DataOrPathRequiredProps = (DataOrPathProps & {
 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
+ * {@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' }
  */
@@ -3205,8 +3364,8 @@ interface RadialGradientFillProps {
   stops: GradientStopProps[];
 }
 type GradientFillProps = LinearGradientFillProps | RadialGradientFillProps;
-/** OOXML ST_PresetPatternVal — preset pattern names for `<a:pattFill prst="...">` */
-type PatternPreset = 'pct5' | 'pct10' | 'pct20' | 'pct25' | 'pct30' | 'pct40' | 'pct50' | 'pct60' | 'pct70' | 'pct75' | 'pct80' | 'pct90' | 'horz' | 'vert' | 'ltHorz' | 'ltVert' | 'dkHorz' | 'dkVert' | 'narHorz' | 'narVert' | 'dashHorz' | 'dashVert' | 'cross' | 'dnDiag' | 'upDiag' | 'ltDnDiag' | 'ltUpDiag' | 'dkDnDiag' | 'dkUpDiag' | 'wdDnDiag' | 'wdUpDiag' | 'dashDnDiag' | 'dashUpDiag' | 'diagCross' | 'smCheck' | 'lgCheck' | 'smGrid' | 'lgGrid' | 'dotGrid' | 'smConfetti' | 'lgConfetti' | 'horzBrick' | 'diagBrick' | 'solidDmnd' | 'openDmnd' | 'dotDmnd' | 'plaid' | 'sphere' | 'weave' | 'divot' | 'shingle' | 'wave' | 'trellis' | 'zigZag';
+/** OOXML ST_PresetPatternVal: preset pattern names for `<a:pattFill prst="...">` */
+type PatternPreset = (typeof PATTERN_PRESETS)[number];
 interface PatternFillProps {
   /** OOXML preset pattern (`prst` attribute on `<a:pattFill>`). */
   preset: PatternPreset;
@@ -3216,7 +3375,7 @@ interface PatternFillProps {
   bgColor?: Color;
 }
 /**
- * Native PPTX picture (image) fill — fills a shape's interior with a bitmap
+ * Native PPTX picture (image) fill: fills a shape's interior with a bitmap
  * (`<a:blipFill>`). Provide exactly one of `path` or `data`; raster formats only
  * (PNG/JPEG/GIF/BMP/WebP). SVG is not yet supported as a fill source.
  */
@@ -3228,7 +3387,8 @@ interface ImageFillProps {
   /**
    * 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
+   * - each value is the percent (at most 100) trimmed from that edge of the source image;
+   *   a negative value pads that edge with empty space instead
    * - `l` + `r` and `t` + `b` must each be less than 100
    * - omitted edges default to 0
    *
@@ -3237,13 +3397,13 @@ interface ImageFillProps {
    * clipped by the shape geometry.
    */
   crop?: {
-    /** Percent trimmed from the left edge of the source image. @default 0 */
+    /** Percent trimmed from the left edge of the source image; negative pads it. @default 0 */
     l?: number;
-    /** Percent trimmed from the top edge of the source image. @default 0 */
+    /** Percent trimmed from the top edge of the source image; negative pads it. @default 0 */
     t?: number;
-    /** Percent trimmed from the right edge of the source image. @default 0 */
+    /** Percent trimmed from the right edge of the source image; negative pads it. @default 0 */
     r?: number;
-    /** Percent trimmed from the bottom edge of the source image. @default 0 */
+    /** Percent trimmed from the bottom edge of the source image; negative pads it. @default 0 */
     b?: number;
   };
 }
@@ -3251,7 +3411,7 @@ type Margin = number | [number, number, number, number];
 type HAlign = 'left' | 'center' | 'right' | 'justify';
 type VAlign = 'top' | 'middle' | 'bottom';
 /**
- * Text body `vert` attribute — flow/rotation direction of the text within its box.
+ * Text body `vert` attribute: flow/rotation direction of the text within its box.
  * Maps to `<a:bodyPr vert="…">` (ECMA-376 `ST_TextVerticalType`).
  */
 type TextVertType = TextVerticalType;
@@ -3263,42 +3423,45 @@ type TextVertType = TextVerticalType;
  * The `arc` node carries no `x`/`y`: an `<a:arcTo>` has no explicit end point. The renderer
  * derives it from the current pen position, the radii and the swept angle, so an end point
  * authored here would be discarded (a warning is emitted if one is supplied).
+ *
+ * Any coordinate, radius or angle may instead name a guide, which is written verbatim (the
+ * `ST_AdjCoordinate` / `ST_AdjAngle` string form): one declared in the shape's `guides`, or a
+ * built-in such as `'w'`, `'hc'` or `'cd4'`. A coordinate counts as a name when it starts with a
+ * letter or `_`; an angle, when it is a string at all.
  */
 type GeometryPoint = {
-  x: Coord;
-  y: Coord;
+  x: Coord | string;
+  y: Coord | string;
   moveTo?: boolean;
 } | {
   curve: {
     type: 'arc';
-    hR: Coord;
-    wR: Coord;
-    stAng: number;
-    swAng: number;
+    hR: Coord | string;
+    wR: Coord | string;
+    stAng: number | string;
+    swAng: number | string;
   };
 } | {
-  x: Coord;
-  y: Coord;
+  x: Coord | string;
+  y: Coord | string;
   curve: {
     type: 'cubic';
-    x1: Coord;
-    y1: Coord;
-    x2: Coord;
-    y2: Coord;
+    x1: Coord | string;
+    y1: Coord | string;
+    x2: Coord | string;
+    y2: Coord | string;
   };
 } | {
-  x: Coord;
-  y: Coord;
+  x: Coord | string;
+  y: Coord | string;
   curve: {
     type: 'quadratic';
-    x1: Coord;
-    y1: Coord;
+    x1: Coord | string;
+    y1: Coord | string;
   };
 } | {
   close: true;
 };
-//#endregion
-//#region src/types/theme.d.ts
 /**
  * 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 `#`).
@@ -3348,28 +3511,28 @@ interface ThemeProps {
    */
   bodyFontFace?: string;
   /**
-   * Headings East Asian font face — theme `<a:ea>` slot of the major font.
+   * 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.
+   * 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.
+   * 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.
+   * 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'
@@ -3383,8 +3546,6 @@ interface ThemeProps {
    */
   colorScheme?: ThemeColorScheme;
 }
-//#endregion
-//#region src/types/pres.d.ts
 interface WriteBaseProps {
   /**
    * Whether to DEFLATE-compress the package (PowerPoint itself always compresses;
@@ -3414,13 +3575,26 @@ interface WriteBaseProps {
    */
   onMediaError?: 'throw' | 'placeholder';
 }
-interface WriteProps extends WriteBaseProps {
+interface WriteProps<T extends WRITE_OUTPUT_TYPE = WRITE_OUTPUT_TYPE> extends WriteBaseProps {
   /**
-   * Output type
+   * Output type. `write()` resolves to the matching {@link WriteOutputMap} entry.
    * - values: 'arraybuffer' | 'base64' | 'binarystring' | 'blob' | 'nodebuffer' | 'uint8array'
    * @default 'blob'
    */
-  outputType?: WRITE_OUTPUT_TYPE;
+  outputType?: T;
+}
+/**
+ * What `write()` resolves to for each {@link WriteProps.outputType}. `'nodebuffer'` is a Node
+ * `Buffer` at run time, typed as the `Uint8Array` it extends so the declaration does not need
+ * Node's types.
+ */
+interface WriteOutputMap {
+  arraybuffer: ArrayBuffer;
+  base64: string;
+  binarystring: string;
+  blob: Blob;
+  nodebuffer: Uint8Array;
+  uint8array: Uint8Array;
 }
 interface WriteFileProps extends WriteBaseProps {
   /**
@@ -3431,7 +3605,7 @@ interface WriteFileProps extends WriteBaseProps {
 }
 /**
  * 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
+ * {@link PptxTs.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
@@ -3444,7 +3618,7 @@ interface PackagePart {
   readonly data: Uint8Array;
 }
 /**
- * Options for {@link TsPptx.toParts}. A deliberately narrow subset of {@link WriteProps}:
+ * Options for {@link PptxTs.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.
  */
@@ -3519,6 +3693,5 @@ interface PresentationProps {
   theme: ThemeProps;
   title: string;
 }
-//#endregion
-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
+export { ChartExBinning as $, ImageBaseProps as $t, PositionProps as A, TextShapeType as An, ObjectLockProps as At, HyperlinkActionJump as B, ResolvedCommentAuthor as Bt, HexColor as C, PlaceholderXmlType as Cn, ChartPropsLegend as Ct, PatternFillProps as D, TEXT_AUTONUM_SCHEMES as Dn, OptsChartData as Dt, Margin as E, RadarStyleAlias as En, LineCap as Et, ActionHyperlinkProps as F, CommentProps as Ft, ShapeLineProps as G, TextBulletProps as Gt, HyperlinkProps as H, TableCellLayout as Ht, BorderProps as I, MeasureTextOptions as It, UrlHyperlinkProps as J, TextMeasurement as Jt, SlideHyperlinkProps as K, TextFitShrinkProps as Kt, ConnectorProps as L, NotesProps as Lt, TextVertType as M, TimeUnit as Mn, PlaceholderBinding as Mt, ThemeColor as N, PlaceholderOption as Nt, PatternPreset as O, TRANSITION_TYPES as On, OptsChartGridLine as Ot, VAlign as P, PlaceholderProps as Pt, ChartErrorBarOptions as Q, textRuns as Qt, ConnectorType as R, NotesTextOptions as Rt, HAlign as S, LineDataSymbol as Sn, ChartPropsFillLine as St, LinearGradientFillProps as T, RadarStyle as Tn, ChartSeriesOpts as Tt, ShadowProps as U, TableLayoutResult as Ut, HyperlinkBaseProps as V, SlideComment as Vt, ShapeFillProps as W, TextBaseProps as Wt, ChartAxisTickMark as X, TextPropsOptions as Xt, ChartAreaProps as Y, TextProps as Yt, ChartDataPointStyle as Z, textRun as Zt, DataOrPathProps as _, DisplayBlanksAs as _n, ChartPropsChartStock as _t, PresentationProps as a, ShapeAdjustHandlePolar as an, ChartPropsAxisCat as at, GradientFillProps as b, LightRigDirection as bn, ChartPropsDataLabel as bt, WriteFileProps as c, ShapeConnectionSite as cn, ChartPropsBase as ct, ThemeColorScheme as d, Bar3DShape as dn, ChartPropsChartDoughnut as dt, ImageProps as en, ChartExGeography as et, ThemeProps as f, BarDirection as fn, ChartPropsChartHistogram as ft, Coord as g, DataLabelPosition as gn, ChartPropsChartRegionMap as gt, Color as h, ColorMapToken as hn, ChartPropsChartRadar as ht, PresLayout as i, ShapeAdjustHandle as in, ChartOpts as it, RadialGradientFillProps as j, ThemeColorSlot as jn, ObjectNameProps as jt, PlaceholderPositionProps as k, TextHorzOverflowType as kn, CommonObjectDescriptor as kt, WriteOutputMap as l, ShapeGuide as ln, ChartPropsChartBar as lt, BackgroundProps as m, BevelPresetType as mn, ChartPropsChartPie as mt, PackagePart as n, MediaType as nn, ChartLineDash as nt, SectionProps as o, ShapeAdjustHandleXY as on, ChartPropsAxisSer as ot, BackgroundOption as p, BarGrouping as pn, ChartPropsChartLine as pt, StrokeProps as q, TextGlowProps as qt, PartsProps as r, OleObjectProps as rn, ChartMulti as rt, WriteBaseProps as s, ShapeAdjustValue as sn, ChartPropsAxisVal as st, CustomPropertyValue as t, MediaProps as tn, ChartExStatistics as tt, WriteProps as u, ShapeProps as un, ChartPropsChartBoxWhisker as ut, DataOrPathRequiredProps as v, EMBEDDED_FONT_SLOTS as vn, ChartPropsChartSurface as vt, ImageFillProps as w, PresetMaterialType as wn, ChartPropsTitle as wt, GradientStopProps as x, LightRigType as xn, ChartPropsDataTable as xt, GeometryPoint as y, LegendPosition as yn, ChartPropsChartWaterfall as yt, FillOption as z, OverflowBoxOptions as zt };
+//# sourceMappingURL=pres-BkEkUAEM.d.ts.map