@shbernal/ts-pptx 0.0.1

package/dist/slide-B6mDaM-P.d.ts

@@ -0,0 +1,3396 @@
+import { _ as TextAnchor, f as SHAPE_NAME, g as TableStyle, h as SlideObjectType, i as CHART_NAME, l as PLACEHOLDER_TYPE, t as AlignH } from "./enums-D3aF4QGb.js";
+//#region src/types/text.d.ts
+interface TextBaseProps {
+  /**
+   * Horizontal alignment
+   * @default 'left'
+   */
+  align?: HAlign;
+  /**
+   * Bold style
+   * @default false
+   */
+  bold?: boolean;
+  /**
+   * Add a line-break
+   * @default false
+   */
+  breakLine?: boolean;
+  /**
+   * Preset text warp / WordArt shape (`<a:bodyPr><a:prstTxWarp prst="..">`), which
+   * bends the text along a preset path (arch, circle, wave, …). The value is an
+   * OOXML `ST_TextShapeType` preset name.
+   * @example 'textArchUp' // bend text along an upward arch (e.g. a label following a ring/arc)
+   * @example 'textCircle'
+   */
+  textWarp?: string;
+  /**
+   * Add standard or custom bullet
+   * - use `true` for standard bullet
+   * - pass object options for custom bullet
+   * @default false
+   */
+  bullet?: boolean | {
+    /**
+     * Bullet type
+     * @default bullet
+     */
+    type?: 'bullet' | 'number';
+    /**
+     * Bullet character code (unicode)
+     * @example '25BA' // 'BLACK RIGHT-POINTING POINTER' (U+25BA)
+     */
+    characterCode?: string;
+    /**
+     * Bullet glyph font typeface (`<a:buFont/>`), e.g. for symbol-font bullets
+     * @example 'Wingdings' // render `characterCode` using the Wingdings font
+     */
+    fontFace?: string;
+    /**
+     * Bullet glyph size as a percentage of the run's text size (25–400)
+     * @default 100
+     * @example 80 // bullet glyph is 80% of the text size
+     */
+    size?: number;
+    /**
+     * Indentation (space between bullet and text) (points)
+     * @default 27 // DEF_BULLET_MARGIN
+     * @example 10 // Indents text 10 points from bullet
+     */
+    indent?: number;
+    /**
+     * Number type
+     * @example 'romanLcParenR' // roman numerals lower-case with paranthesis right
+     */
+    numberType?: 'alphaLcParenBoth' | 'alphaLcParenR' | 'alphaLcPeriod' | 'alphaUcParenBoth' | 'alphaUcParenR' | 'alphaUcPeriod' | 'arabicParenBoth' | 'arabicParenR' | 'arabicPeriod' | 'arabicPlain' | 'romanLcParenBoth' | 'romanLcParenR' | 'romanLcPeriod' | 'romanUcParenBoth' | 'romanUcParenR' | 'romanUcPeriod';
+    /**
+     * Number bullets start at
+     * @default 1
+     * @example 10 // numbered bullets start with 10
+     */
+    numberStartAt?: number;
+    /**
+     * Image to use as the bullet glyph ("picture bullet", `<a:buBlip>`)
+     * - supply an image `path` (filesystem/URL) or base64 `data` (same forms as `addImage()`)
+     * - raster formats (PNG/JPG/GIF) and SVG are supported; use `size` to scale relative to the text height
+     * - SVG bullets embed a PNG preview plus the SVG (the same dual-rel handling as `addImage()`)
+     * - takes precedence over `type`/`characterCode` when set
+     * @example image: { path: 'images/star.png' }
+     * @example image: { data: 'image/png;base64,iVBOR...' }
+     * @example image: { path: 'images/star.svg' }
+     */
+    image?: {
+      path?: string;
+      data?: string;
+    };
+    /**
+     * Relationship id assigned to a picture-bullet image (`<a:blip r:embed>`)
+     * - for SVG bullets this is the PNG-preview rel; the SVG rel is `_rIdSvg`
+     * @internal populated by `addText()`; do not set directly
+     */
+    _rId?: number;
+    /**
+     * Relationship id of the SVG image for an SVG picture bullet (`<asvg:svgBlip r:embed>`)
+     * @internal populated by `addText()`; do not set directly
+     */
+    _rIdSvg?: number;
+    /**
+     * Bullet glyph color (separate from the text run color)
+     * @example 'FF0000' // red bullet
+     */
+    color?: HexColor;
+  };
+  /**
+   * Text capitalization
+   * - `'all'` = ALL CAPS
+   * - `'small'` = Small Caps
+   * - `'none'` = no override (default)
+   * - PowerPoint: Font > Effects > All Caps / Small Caps
+   */
+  caps?: 'none' | 'small' | 'all';
+  /**
+   * Text color
+   * - `HexColor` or `ThemeColor`
+   * - MS-PPT > Format Shape > Text Options > Text Fill & Outline > Text Fill > Color
+   * @example 'FF0000' // hex color (red)
+   * @example SchemeColor.text1 // Theme color (Text1)
+   */
+  color?: Color;
+  /**
+   * Font face name
+   *
+   * 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
+   * East Asian slot duplicates/ghosts text in Office 365.
+   * @example 'Arial' // Arial font
+   */
+  fontFace?: string;
+  /**
+   * 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.
+   * @example '微軟正黑體' // render East Asian glyphs with Microsoft JhengHei
+   */
+  fontFaceEA?: string;
+  /**
+   * Font size
+   * @example 12 // Font size 12
+   */
+  fontSize?: number;
+  /**
+   * Text highlight color (hex format)
+   * @example 'FFFF00' // yellow
+   */
+  highlight?: HexColor;
+  /**
+   * italic style
+   * @default false
+   */
+  italic?: boolean;
+  /**
+   * language
+   * - ISO 639-1 standard language code
+   * @default 'en-US' // english US
+   * @example 'fr-CA' // french Canadian
+   */
+  lang?: string;
+  /**
+   * Add a soft line-break (shift+enter) before line text content
+   * @default false
+   */
+  softBreakBefore?: boolean;
+  /**
+   * tab stops
+   * - PowerPoint: Paragraph > Tabs > Tab stop position
+   * @example [{ position:1 }, { position:3 }] // Set first tab stop to 1 inch, set second tab stop to 3 inches
+   */
+  tabStops?: Array<{
+    position: number;
+    alignment?: 'l' | 'r' | 'ctr' | 'dec';
+  }>;
+  /**
+   * text direction
+   * `horz` = horizontal
+   * `vert` = rotate 90^
+   * `vert270` = rotate 270^
+   * `wordArtVert` = stacked
+   * @default 'horz'
+   */
+  textDirection?: 'horz' | 'vert' | 'vert270' | 'wordArtVert';
+  /**
+   * Transparency (percent)
+   * - MS-PPT > Format Shape > Text Options > Text Fill & Outline > Text Fill > Transparency
+   * - range: 0-100
+   * @default 0
+   */
+  transparency?: number;
+  /**
+   * underline properties
+   * - PowerPoint: Font > Color & Underline > Underline Style/Underline Color
+   * @default (none)
+   */
+  underline?: {
+    style?: 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dbl' | 'dotDash' | 'dotDashHeave' | 'dotDotDash' | 'dotDotDashHeavy' | 'dotted' | 'dottedHeavy' | 'heavy' | 'none' | 'sng' | 'wavy' | 'wavyDbl' | 'wavyHeavy';
+    color?: Color;
+  };
+  /**
+   * vertical alignment
+   * @default 'top'
+   */
+  valign?: VAlign;
+}
+interface TextGlowProps {
+  /**
+   * Border color (hex format)
+   * @example 'FF3399'
+   */
+  color?: HexColor;
+  /**
+   * opacity (0.0 - 1.0)
+   * @example 0.5
+   * 50% opaque
+   */
+  opacity?: number;
+  /**
+   * size (points)
+   */
+  size: number;
+}
+interface TextFitShrinkProps {
+  /**
+   * Shrink text on overflow (`<a:normAutofit>`)
+   */
+  type: 'shrink';
+  /**
+   * Font scale as a percent (0-100), mapped to `<a:normAutofit fontScale="..">`.
+   *
+   * PowerPoint normally calculates this dynamically when text overflows; set it
+   * explicitly to bake the scale into the generated file.
+   * @example 85 // render text at 85% of its nominal size
+   * @default undefined // attribute omitted (PowerPoint defaults to 100%)
+   */
+  fontScale?: number;
+  /**
+   * Line-space reduction as a percent (0-100), mapped to `<a:normAutofit lnSpcReduction="..">`.
+   * @example 20 // reduce line spacing by 20%
+   * @default undefined // attribute omitted (PowerPoint defaults to 0%)
+   */
+  lnSpcReduction?: number;
+}
+interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps, ObjectNameProps {
+  _bodyProp?: {
+    align?: AlignH;
+    anchor?: TextAnchor;
+    lIns?: number;
+    rIns?: number;
+    tIns?: number;
+    bIns?: number;
+    numCol?: number;
+    spcCol?: number;
+    vert?: TextVertType;
+    wrap?: boolean;
+    prstTxWarp?: string;
+  };
+  _lineIdx?: number;
+  baseline?: number;
+  /**
+   * Character spacing
+   */
+  charSpacing?: number;
+  /**
+   * Number of text columns in the text body
+   * - PowerPoint: Format Shape > Shape Options > Size & Properties > Text Box > Columns > "Number"
+   * - range: 1-16
+   * @default 1
+   * @example 2 // flow text into two columns
+   */
+  columns?: number;
+  /**
+   * Spacing between text columns (points)
+   * - PowerPoint: Format Shape > Shape Options > Size & Properties > Text Box > Columns > "Spacing"
+   * - only applies when `columns` > 1
+   * @default 0
+   * @example 10 // 10pt gap between columns
+   */
+  columnSpacing?: number;
+  /**
+   * Text fit options
+   *
+   * MS-PPT > Format Shape > Shape Options > Text Box > "[unlabeled group]": [3 options below]
+   * - 'none' = Do not Autofit
+   * - 'shrink' = Shrink text on overflow
+   * - 'resize' = Resize shape to fit text
+   *
+   * **Measured fit:** if you register the box's font with
+   * {@link TsPptx.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
+   *   bakes `<a:normAutofit fontScale=…/>`.
+   * - `'resize'` computes the height the text needs and bakes it into the shape's
+   *   `a:ext/@cy` (adjusting `a:off/@y` per vertical anchor), the marker being
+   *   `<a:spAutoFit/>`.
+   * Without registered metrics they fall back to the bare flag (`<a:normAutofit/>` /
+   * `<a:spAutoFit/>`, which only PowerPoint recomputes on edit) and warn once.
+   *
+   * **Note** Bare `'shrink'`/`'resize'` (no metrics) only take effect after editing
+   * text / resizing the shape; PowerPoint calculates the result then. The object form
+   * of `'shrink'` always bakes the explicit values you pass.
+   * @example 'shrink' // measured when metrics are registered; else bare <a:normAutofit/>
+   * @example 'resize' // measured when metrics are registered; else bare <a:spAutoFit/>
+   * @example { type: 'shrink', fontScale: 85, lnSpcReduction: 20 } // pre-shrink with explicit values
+   * @default "none"
+   */
+  fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
+  /**
+   * Shape fill
+   * @example { color:'FF0000' } // hex color (red)
+   * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
+   * @example { color:SchemeColor.accent1 } // theme color Accent1
+   */
+  fill?: ShapeFillProps;
+  /**
+   * Flip shape horizontally?
+   * @default false
+   */
+  flipH?: boolean;
+  /**
+   * Flip shape vertical?
+   * @default false
+   */
+  flipV?: boolean;
+  glow?: TextGlowProps;
+  hyperlink?: HyperlinkProps;
+  indentLevel?: number;
+  isTextBox?: boolean;
+  line?: ShapeLineProps;
+  /**
+   * Line spacing (pt)
+   * - PowerPoint: Paragraph > Indents and Spacing > Line Spacing: > "Exactly"
+   * @example 28 // 28pt
+   */
+  lineSpacing?: number;
+  /**
+   * line spacing multiple (percent)
+   * - range: 0.0-9.99
+   * - PowerPoint: Paragraph > Indents and Spacing > Line Spacing: > "Multiple"
+   * @example 1.5 // 1.5X line spacing
+   */
+  lineSpacingMultiple?: number;
+  /**
+   * 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)
+   * @default (unset) PowerPoint's "Normal" internal margin [0.05", 0.1", 0.05", 0.1"]
+   * @example 0 // Top/Right/Bottom/Left margin 0
+   * @example 0.1 // Top/Right/Bottom/Left margin 0.1 inch
+   * @example [0.05, 0.1, 0.05, 0.1] // top 0.05", right 0.1", bottom 0.05", left 0.1"
+   */
+  margin?: Margin;
+  outline?: {
+    color: Color;
+    size: number;
+  };
+  paraSpaceAfter?: number;
+  paraSpaceBefore?: number;
+  /**
+   * Placeholder type
+   * - when the value matches a placeholder defined on the slide layout/master, this text
+   *   inherits that placeholder's position and formatting
+   * - otherwise the text shape is promoted to a standalone placeholder of this type, emitting
+   *   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.
+   * @example 'title'
+   * @see https://learn.microsoft.com/en-us/office/vba/api/powerpoint.ppplaceholdertype
+   */
+  placeholder?: string;
+  /**
+   * Rounded rectangle radius (only for ShapeType.roundRect)
+   * - values: 0.0 to 1.0
+   * @default 0
+   */
+  rectRadius?: number;
+  /**
+   * Rotation (degrees)
+   * - range: -360 to 360
+   * @default 0
+   * @example 180 // rotate 180 degrees
+   */
+  rotate?: number;
+  /**
+   * Whether to enable right-to-left mode
+   * @default false
+   */
+  rtlMode?: boolean;
+  shadow?: ShadowProps;
+  shape?: SHAPE_NAME;
+  strike?: boolean | 'dblStrike' | 'sngStrike';
+  subscript?: boolean;
+  superscript?: boolean;
+  /**
+   * Vertical alignment
+   * @default middle
+   */
+  valign?: VAlign;
+  /**
+   * Advanced/legacy escape hatch for the full `ST_TextVerticalType` range (e.g. `eaVert`,
+   * `mongolianVert`, `wordArtVert`). Prefer {@link TextBaseProps.textDirection} for the common
+   * cases; both map to `a:bodyPr@vert`.
+   */
+  vert?: TextVertType;
+  /**
+   * Text wrap
+   * @default true
+   */
+  wrap?: boolean;
+}
+interface TextProps {
+  text?: string | number;
+  options?: TextPropsOptions;
+  /**
+   * Raw OMML (Office MathML) for a native, editable PowerPoint equation. By default it is emitted
+   * as its own centered display-math paragraph (`<a14:m><m:oMathPara><m:oMath>…`) and `text` is
+   * ignored; set `inline` to instead flow it as an equation run mid-paragraph. Accepts either the
+   * inner OMML (children of `<m:oMath>`), a full `<m:oMath>…</m:oMath>`, or a full
+   * `<m:oMathPara>…</m:oMathPara>`; the `m:` prefix is resolved by the wrapper, so the markup does
+   * not need its own namespace declarations.
+   * This is the raw-OMML entry point. To author from LaTeX or MathML, convert with
+   * `latexToOmml()` / `mathmlToOmml()` from the `@shbernal/ts-pptx/math` subpath.
+   * @example { math: '<m:r><m:t>x^2+1=y</m:t></m:r>' } // raw OMML
+   * @example import { latexToOmml } from '@shbernal/ts-pptx/math'; ({ math: latexToOmml('x^2+1=y') })
+   */
+  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
+   * 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' }])
+   */
+  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}
+ * (a named face without exact metrics uses a conservative heuristic; an unnamed
+ * theme-default face is unmeasurable).
+ */
+interface MeasureTextOptions {
+  /** Available text width in inches (the box width minus L/R inset, unless `insetIn` is given). */
+  wIn: number;
+  /** Font size in points. */
+  fontSize: number;
+  /** Font family name, as used in `fontFace`. Required for an exact measure; an unnamed face is unmeasurable. */
+  fontFace?: string;
+  bold?: boolean;
+  italic?: boolean;
+  /** Character spacing in points. */
+  charSpacing?: number;
+  /** Exact line spacing in points (overrides `lineSpacingMultiple`). */
+  lineSpacing?: number;
+  /** Line spacing as a multiple of single (e.g. `1.5`). */
+  lineSpacingMultiple?: number;
+  /** Space before each paragraph, in points. */
+  paraSpaceBefore?: number;
+  /** Space after each paragraph, in points. */
+  paraSpaceAfter?: number;
+  /** L/R text inset in inches; when set, subtracted from `wIn` on both sides (pass a raw box width). */
+  insetIn?: number;
+}
+/**
+ * Result of {@link TsPptx.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).
+ */
+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). */
+  lineCount: number;
+  /**
+   * 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.
+   */
+  widestLineIn: number;
+  /** `false` only for an unnamed theme-default face that could not be measured. */
+  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
+   * 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.
+   */
+  approximatedFaces: string[];
+  /** True if the text fits a box of inner height `hIn` (inches) at full size. */
+  fitsBox: (hIn: number) => boolean;
+  /** 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. */
+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
+ * 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.
+ */
+interface TableCellLayout {
+  /** Zero-based grid row of the cell's top-left origin. */
+  row: number;
+  /** Zero-based grid column of the cell's top-left origin. */
+  col: number;
+  /** Number of rows the cell spans (1 if not merged). */
+  rowSpan: number;
+  /** Number of columns the cell spans (1 if not merged). */
+  colSpan: number;
+  /** Left edge in inches (absolute). */
+  xIn: number;
+  /** Top edge in inches (absolute). */
+  yIn: number;
+  /** Outer cell width in inches (sum of spanned column widths). */
+  wIn: number;
+  /** Outer cell height in inches (sum of spanned row heights). */
+  hIn: number;
+  /**
+   * `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}.
+   */
+  heightExact: boolean;
+}
+/**
+ * Result of {@link TsPptx.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
+ * estimates (see {@link TableCellLayout.heightExact}).
+ */
+interface TableLayoutResult {
+  /** One entry per non-merged origin cell, in row-major order. */
+  cells: TableCellLayout[];
+  /** Overall table width in inches (sum of column widths). */
+  widthIn: number;
+  /** Overall table height in inches (sum of row heights; may include estimates). */
+  heightIn: number;
+  /** `false` if any row height was estimated (the total errs tall, like `measureText`). */
+  heightExact: boolean;
+}
+/**
+ * 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.
+ */
+type NotesTextOptions = Pick<TextPropsOptions, 'hyperlink' | 'bold' | 'italic' | 'underline' | 'color' | 'fontSize' | 'fontFace'>;
+/** A single speaker-notes text run: text plus optional inline formatting / hyperlink. */
+interface NotesProps {
+  text: string;
+  options?: NotesTextOptions;
+}
+/**
+ * A review comment attached to a slide (legacy ISO/IEC 29500 §13 comment).
+ */
+interface CommentProps {
+  /** Author display name (required). Comments sharing the same `author`+`initials` are grouped under one author entry. */
+  author: string;
+  /** Author initials shown in the comment marker. Defaults to letters derived from `author`. */
+  initials?: string;
+  /** Comment body text (required). */
+  text: string;
+  /** Comment marker X position in inches. @default 0.5 */
+  x?: number;
+  /** Comment marker Y position in inches. @default 0.5 */
+  y?: number;
+  /** Authored date/time as a `Date` or ISO-8601 string. Omitted from the XML when not provided. */
+  date?: Date | string;
+}
+/** Internal normalized comment stored on a slide (`_comments`). x/y are inches; `date` is ISO-8601 when present. */
+interface SlideComment {
+  author: string;
+  initials: string;
+  text: string;
+  x: number;
+  y: number;
+  date?: string;
+}
+/** Resolved presentation-level comment author, emitted to `commentAuthors.xml`. */
+interface ResolvedCommentAuthor {
+  id: number;
+  name: string;
+  initials: string;
+  lastIdx: number;
+  clrIdx: number;
+}
+/** Factory for a single inline text run. Prevents `as never` casts when building mixed-style run arrays. */
+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
+interface PlaceholderProps extends PositionProps, TextBaseProps, ObjectNameProps {
+  name: string;
+  type: PLACEHOLDER_TYPE;
+  /**
+   * margin (inches) — text-frame internal margin; a value `>= 1` warns as a likely legacy points value
+   */
+  margin?: Margin;
+  /**
+   * Preset shape geometry for this placeholder (e.g. `'roundRect'`)
+   * @default 'rect'
+   */
+  shape?: SHAPE_NAME;
+  /**
+   * Rounded rectangle corner radius (inches) when `shape: 'roundRect'`
+   * - range: 0.0 to slide height/2
+   */
+  rectRadius?: number;
+}
+interface ObjectNameProps {
+  /**
+   * Object name
+   * - used instead of default "Object N" name
+   * - PowerPoint: Home > Arrange > Selection Pane...
+   * @default 'Object 1'
+   * @example 'Antenna Design 9'
+   */
+  objectName?: string;
+  /**
+   * Alt Text value ("How would you describe this object and its contents to someone who is blind?")
+   * - serialized to the generated object's `p:cNvPr` `descr` attribute
+   * - PowerPoint: [right-click on the object] > "Edit Alt Text..."
+   * @example 'Quarterly revenue bar chart'
+   */
+  altText?: string;
+  /**
+   * Object lock flags (DrawingML `a:spLocks` / `a:picLocks` / `a:graphicFrameLocks`)
+   * - restrict how the object can be manipulated in PowerPoint (e.g. prevent moving, resizing, or grouping)
+   * - each flag maps 1:1 to the OOXML attribute of the same name; only flags set to `true` are emitted
+   * - PowerPoint UI: Selection Pane / right-click protections (most locks are honored at edit time, not as a password)
+   * - flags only apply to the object types that support them (see each flag); flags set on an unsupported
+   *   object type are ignored with a console warning
+   * @example { noMove: true, noResize: true } // pin an object in place
+   * @example { noGrp: true } // exclude from grouping
+   */
+  objectLock?: ObjectLockProps;
+}
+/**
+ * Object lock flags. Maps to DrawingML locking elements:
+ * - shapes / text boxes / placeholders → `a:spLocks`
+ * - images / media → `a:picLocks`
+ * - tables → `a:graphicFrameLocks`
+ *
+ * Each property mirrors the OOXML attribute name. A flag is only serialized for object types whose
+ * locking element defines it (noted per-flag); setting an unsupported flag logs a warning and is ignored.
+ */
+interface ObjectLockProps {
+  /** Disallow grouping/ungrouping with other objects. (shapes, images, tables) */
+  noGrp?: boolean;
+  /** Disallow selecting the object. (shapes, images, tables) */
+  noSelect?: boolean;
+  /** Disallow moving the object. (shapes, images, tables) */
+  noMove?: boolean;
+  /** Disallow resizing the object. (shapes, images, tables) */
+  noResize?: boolean;
+  /** Disallow changing the aspect ratio. (shapes, images, tables) */
+  noChangeAspect?: boolean;
+  /** Disallow rotating the object. (shapes, images) */
+  noRot?: boolean;
+  /** Disallow editing the freeform/custom-geometry points. (shapes, images) */
+  noEditPoints?: boolean;
+  /** Disallow moving the shape's adjustment handles. (shapes, images) */
+  noAdjustHandles?: boolean;
+  /** Disallow changing arrowheads. (shapes, images) */
+  noChangeArrowheads?: boolean;
+  /** Disallow changing the shape type (preset geometry). (shapes, images) */
+  noChangeShapeType?: boolean;
+  /** Disallow editing the text body. (shapes / text boxes) */
+  noTextEdit?: boolean;
+  /** Disallow cropping the picture. (images) */
+  noCrop?: boolean;
+  /** Disallow drilling down into the graphical object (e.g. chart data). (tables) */
+  noDrilldown?: boolean;
+}
+//#endregion
+//#region src/types/chart.d.ts
+type ChartAxisTickMark = 'none' | 'inside' | 'outside' | 'cross';
+/**
+ * Line end cap style. Maps to the OOXML `cap` attribute on `<a:ln>` (`flat`/`sq`/`rnd`).
+ */
+type LineCap = 'flat' | 'round' | 'square';
+type ChartLineDash = 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'solid' | 'sysDash' | 'sysDot';
+interface OptsChartData {
+  /**
+   * category labels
+   * @example ['Year 2000', 'Year 2010', 'Year 2020'] // single-level category axes labels
+   * @example [['Year 2000', 'Year 2010', 'Year 2020'], ['Decades', '', '']] // multi-level category axes labels
+   */
+  labels?: string[] | string[][];
+  /**
+   * series name
+   * @example 'Locations'
+   */
+  name?: string;
+  /**
+   * bubble sizes
+   * @example [5, 1, 5, 1]
+   */
+  sizes?: number[];
+  /**
+   * category values
+   * @example [2000, 2010, 2020]
+   */
+  values?: number[];
+  /**
+   * 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.
+   * Supported for BAR, LINE, AREA, RADAR, PIE, and DOUGHNUT chart types.
+   * @example ['Low', '', 'High']  // only points 0 and 2 get custom labels
+   */
+  customLabels?: string[];
+  /**
+   * Per-data-point visual overrides (border / fill), index-aligned with `values[]`.
+   * Empty (`{}`) or missing entries fall back to series/chart styling.
+   * Supported for BAR, LINE, AREA, SCATTER, PIE, and DOUGHNUT chart types.
+   * @example
+   * pointStyles: [
+   *   { border: { width: 2, color: 'FF0000' } }, // point 0: red 2pt border
+   *   {},                                     // point 1: default
+   *   { fill: '00B050', border: { type: 'dash', color: '404040' } }, // point 2
+   * ]
+   */
+  pointStyles?: ChartDataPointStyle[];
+  /**
+   * Error bars for this series (`<c:errBars>`).
+   * - Supported for BAR, BAR3D, LINE, AREA, and SCATTER chart types (RADAR has no error bars in the schema).
+   * - Pass a single config, or an array to draw both X and Y error bars (SCATTER/AREA only; BAR/LINE use the first entry).
+   * @example { valueType: 'percentage', value: 5 } // ±5% error bars
+   * @example { valueType: 'fixedVal', value: 2, barType: 'plus', noEndCap: true }
+   * @example { valueType: 'cust', plusValues: [1, 2, 1], minusValues: [0.5, 1, 0.5] }
+   */
+  errorBars?: ChartErrorBarOptions | ChartErrorBarOptions[];
+}
+/**
+ * Per-data-point style override for a chart series.
+ * Each entry applies to the data point at the same index in `values[]`.
+ * Unset fields fall back to the series/chart-level styling.
+ */
+interface ChartDataPointStyle {
+  /**
+   * Data-point border (line). Reuses {@link BorderProps}.
+   * - `type: 'none'` hides the border; `'dash'` draws a dashed border.
+   * @example { width: 2, color: 'FF0000' }
+   */
+  border?: BorderProps;
+  /**
+   * Data-point fill color (hex), overriding `chartColors[idx]`.
+   * Most meaningful on fill-based charts (BAR, AREA, PIE, DOUGHNUT).
+   * @example '00B050'
+   */
+  fill?: HexColor;
+  /**
+   * Data-point pattern fill (`<a:pattFill>`), e.g. diagonal hatching, for the
+   * BAR/BAR3D and SCATTER charts that emit per-point `c:dPt`. Takes precedence
+   * over `fill` (OOXML allows only one fill per data point).
+   *
+   * When `pattern.fgColor` is omitted it defaults to this point's resolved fill
+   * color (`fill` or the varied `chartColors[idx]`), giving a hatched version of
+   * the bar color; if no point color is resolvable it falls back to black.
+   * `pattern.bgColor` defaults to white.
+   * @example { preset: 'ltUpDiag' }
+   * @example { preset: 'diagCross', fgColor: 'C00000', bgColor: 'FFFFFF' }
+   */
+  pattern?: PatternFillProps;
+}
+/**
+ * Error-bar configuration for a chart series (`<c:errBars>`).
+ * Maps onto OOXML `CT_ErrBars` (errDir / errBarType / errValType / noEndCap / plus / minus / val).
+ */
+interface ChartErrorBarOptions {
+  /**
+   * Axis the error bars measure along.
+   * - `'y'` (the value axis) for BAR/BAR3D/LINE/AREA; SCATTER may also use `'x'`.
+   * @default 'y'
+   */
+  direction?: 'x' | 'y';
+  /**
+   * Which sides of each marker draw a bar.
+   * @default 'both'
+   */
+  barType?: 'both' | 'minus' | 'plus';
+  /**
+   * 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`
+   * @default 'fixedVal'
+   */
+  valueType?: 'cust' | 'fixedVal' | 'percentage' | 'stdDev' | 'stdErr';
+  /**
+   * Magnitude for `'fixedVal'`, `'percentage'`, or `'stdDev'`. Ignored for `'stdErr'` and `'cust'`.
+   * @default 1
+   */
+  value?: number;
+  /** Per-point positive magnitudes; required when `valueType === 'cust'` (unless `barType: 'minus'`). Index-aligned with `values[]`. */
+  plusValues?: number[];
+  /** Per-point negative magnitudes; required when `valueType === 'cust'` (unless `barType: 'plus'`). Index-aligned with `values[]`. */
+  minusValues?: number[];
+  /**
+   * Hide the perpendicular end caps.
+   * @default false
+   */
+  noEndCap?: boolean;
+  /** Error-bar line color (hex, e.g. `'FF0000'`). */
+  color?: HexColor;
+  /** Error-bar line width (points). */
+  size?: number;
+}
+interface OptsChartGridLine {
+  /**
+   * MS-PPT > Chart format > Format Major Gridlines > Line > Cap type
+   * - line cap type
+   * @default flat
+   */
+  cap?: LineCap;
+  /**
+   * Gridline color
+   * - `HexColor` or `ThemeColor`
+   * @example 'FF3399'
+   * @example SchemeColor.accent1 // theme color Accent1
+   */
+  color?: Color;
+  /**
+   * Gridline size (points)
+   */
+  size?: number;
+  /**
+   * Gridline style
+   */
+  style?: 'solid' | 'dash' | 'dot' | 'none';
+}
+interface ChartMulti {
+  type: CHART_NAME;
+  data: OptsChartData[];
+  options: ChartOpts;
+}
+interface ChartPropsFillLine {
+  /**
+   * PowerPoint: Format Chart Area/Plot > Border ["Line"]
+   * @example border: {color: 'FF0000', width: 1} // hex RGB color, 1 pt line
+   */
+  border?: BorderProps;
+  /**
+   * PowerPoint: Format Chart Area/Plot Area > Fill
+   * @example fill: {color: '696969'} // hex RGB color value
+   * @example fill: {color: SchemeColor.background2} // Theme color value
+   * @example fill: {transparency: 50} // 50% transparency
+   */
+  fill?: ShapeFillProps;
+}
+interface ChartAreaProps extends ChartPropsFillLine {
+  /**
+   * Whether the chart area has rounded corners
+   * - only applies when either `fill` or `border` is used
+   * @default true
+   */
+  roundedCorners?: boolean;
+}
+interface ChartPropsBase {
+  /**
+   * Axis position
+   */
+  axisPos?: 'b' | 'l' | 'r' | 't';
+  chartColors?: HexColor[];
+  /**
+   * opacity (0 - 100)
+   * @example 50 // 50% opaque
+   */
+  chartColorsOpacity?: number;
+  dataBorder?: BorderProps;
+  displayBlanksAs?: 'gap' | 'span' | 'zero';
+  invertedColors?: HexColor[];
+  lang?: string;
+  layout?: PositionProps;
+  shadow?: ShadowProps;
+  /**
+   * Show each bubble's size value as a data label (bubble / bubble3D charts only).
+   * Has no effect on other chart types.
+   * @default false
+   */
+  showBubbleSize?: boolean;
+  /**
+   * Enable data labels, with a meaning that is **overloaded per plot type** — it is not a
+   * plain duplicate of {@link ChartPropsBase.showValue}:
+   * - pie / doughnut: shows the **category name** (`c:showCatName`);
+   * - scatter: shows **both** the value and the category name;
+   * - chartEx (waterfall/funnel/…): OR-combined with `showValue` to show the **value** label.
+   *
+   * For the common "show the numeric value" case on standard plots, prefer `showValue`.
+   * @default false
+   */
+  showLabel?: boolean;
+  showLeaderLines?: boolean;
+  /**
+   * Leader line color (pie/doughnut data labels). Requires `showLeaderLines: true`.
+   * When omitted, PowerPoint applies its automatic leader-line color.
+   * @example 'FF0000' // red leader lines
+   */
+  leaderLineColor?: HexColor;
+  /**
+   * Leader line width, in points (pie/doughnut data labels). Requires `showLeaderLines: true`.
+   * @default 0.75
+   * @example 1.5
+   */
+  leaderLineSize?: number;
+  /**
+   * @default false
+   */
+  showLegend?: boolean;
+  /**
+   * @default false
+   */
+  showPercent?: boolean;
+  /**
+   * @default false
+   */
+  showSerName?: boolean;
+  /**
+   * @default false
+   */
+  showTitle?: boolean;
+  /**
+   * @default false
+   */
+  showValue?: boolean;
+  /**
+   * 3D Perspecitve
+   * - range: 0-120
+   * @default 30
+   */
+  v3DPerspective?: number;
+  /**
+   * Right Angle Axes
+   * - Shows chart from first-person perspective
+   * - Overrides `v3DPerspective` when true
+   * - PowerPoint: Chart Options > 3-D Rotation
+   * @default false
+   */
+  v3DRAngAx?: boolean;
+  /**
+   * X Rotation
+   * - PowerPoint: Chart Options > 3-D Rotation
+   * - range: 0-359.9
+   * @default 30
+   */
+  v3DRotX?: number;
+  /**
+   * Y Rotation
+   * - range: 0-359.9
+   * @default 30
+   */
+  v3DRotY?: number;
+  /**
+   * PowerPoint: Format Chart Area (Fill & Border/Line)
+   */
+  chartArea?: ChartAreaProps;
+  /**
+   * PowerPoint: Format Plot Area (Fill & Border/Line)
+   */
+  plotArea?: ChartPropsFillLine;
+  /**
+   * Per-series style overrides.
+   * Element at index N applies to the series at data[N].
+   * Missing indices or unset fields fall back to the chart-level option.
+   */
+  seriesOptions?: ChartSeriesOpts[];
+}
+interface ChartPropsAxisCat {
+  /**
+   * Multi-Chart prop: array of cat axes
+   */
+  catAxes?: ChartPropsAxisCat[];
+  catAxisBaseTimeUnit?: string;
+  catAxisCrossesAt?: number | 'autoZero';
+  catAxisHidden?: boolean;
+  catAxisLabelColor?: string;
+  catAxisLabelFontBold?: boolean;
+  catAxisLabelFontFace?: string;
+  catAxisLabelFontItalic?: boolean;
+  catAxisLabelFontSize?: number;
+  /**
+   * Number format code for the category (X) axis labels on scatter and bubble charts.
+   * Falls back to `valAxisLabelFormatCode` when not set.
+   * - Example: `'0.00'`, `'#,##0'`, `'mmm yyyy'`
+   * - PowerPoint: Format Axis > Number > Format Code
+   */
+  catAxisLabelFormatCode?: string;
+  catAxisLabelFrequency?: string;
+  catAxisLabelPos?: 'none' | 'low' | 'high' | 'nextTo';
+  catAxisLabelRotate?: number;
+  catAxisLineColor?: string;
+  catAxisLineShow?: boolean;
+  catAxisLineSize?: number;
+  catAxisLineStyle?: 'solid' | 'dash' | 'dot';
+  catAxisMajorTickMark?: ChartAxisTickMark;
+  catAxisMajorTimeUnit?: string;
+  catAxisMajorUnit?: number;
+  catAxisMaxVal?: number;
+  catAxisMinorTickMark?: ChartAxisTickMark;
+  catAxisMinorTimeUnit?: string;
+  catAxisMinorUnit?: number;
+  catAxisMinVal?: number;
+  catAxisMultiLevelLabels?: boolean;
+  catAxisOrientation?: 'minMax' | 'maxMin';
+  catAxisTitle?: string;
+  catAxisTitleColor?: string;
+  catAxisTitleFontFace?: string;
+  catAxisTitleFontSize?: number;
+  catAxisTitleRotate?: number;
+  catGridLine?: OptsChartGridLine;
+  catLabelFormatCode?: string;
+  /**
+   * Whether data should use secondary category axis (instead of primary)
+   * @default false
+   */
+  secondaryCatAxis?: boolean;
+  showCatAxisTitle?: boolean;
+}
+interface ChartPropsAxisSer {
+  serAxisBaseTimeUnit?: string;
+  serAxisHidden?: boolean;
+  serAxisLabelColor?: string;
+  serAxisLabelFontBold?: boolean;
+  serAxisLabelFontFace?: string;
+  serAxisLabelFontItalic?: boolean;
+  serAxisLabelFontSize?: number;
+  serAxisLabelFrequency?: string;
+  serAxisLabelPos?: 'none' | 'low' | 'high' | 'nextTo';
+  serAxisLineColor?: string;
+  serAxisLineShow?: boolean;
+  serAxisMajorTimeUnit?: string;
+  serAxisMajorUnit?: number;
+  serAxisMinorTimeUnit?: string;
+  serAxisMinorUnit?: number;
+  serAxisOrientation?: string;
+  serAxisTitle?: string;
+  serAxisTitleColor?: string;
+  serAxisTitleFontFace?: string;
+  serAxisTitleFontSize?: number;
+  serAxisTitleRotate?: number;
+  serGridLine?: OptsChartGridLine;
+  serLabelFormatCode?: string;
+  showSerAxisTitle?: boolean;
+}
+interface ChartPropsAxisVal {
+  /**
+   * Whether data should use secondary value axis (instead of primary)
+   * @default false
+   */
+  secondaryValAxis?: boolean;
+  showValAxisTitle?: boolean;
+  /**
+   * Multi-Chart prop: array of val axes
+   */
+  valAxes?: ChartPropsAxisVal[];
+  valAxisCrossesAt?: number | 'autoZero';
+  /**
+   * Controls where axis values are plotted relative to tick marks
+   * - `'between'` = values plotted between tick marks (default for bar/column/line)
+   * - `'midCat'` = values plotted on tick marks (default for scatter/area)
+   * - PowerPoint: Format Axis > Axis Options > Axis crosses > On tick marks / Between tick marks
+   */
+  valAxisCrossBetween?: 'between' | 'midCat';
+  valAxisDisplayUnit?: 'billions' | 'hundredMillions' | 'hundreds' | 'hundredThousands' | 'millions' | 'tenMillions' | 'tenThousands' | 'thousands' | 'trillions';
+  valAxisDisplayUnitLabel?: boolean;
+  valAxisHidden?: boolean;
+  valAxisLabelColor?: string;
+  valAxisLabelFontBold?: boolean;
+  valAxisLabelFontFace?: string;
+  valAxisLabelFontItalic?: boolean;
+  valAxisLabelFontSize?: number;
+  valAxisLabelFormatCode?: string;
+  valAxisLabelPos?: 'none' | 'low' | 'high' | 'nextTo';
+  valAxisLabelRotate?: number;
+  valAxisLineColor?: string;
+  valAxisLineShow?: boolean;
+  valAxisLineSize?: number;
+  valAxisLineStyle?: 'solid' | 'dash' | 'dot';
+  /**
+   * PowerPoint: Format Axis > Axis Options > Logarithmic scale - Base
+   * - range: 2-99
+   */
+  valAxisLogScaleBase?: number;
+  valAxisMajorTickMark?: ChartAxisTickMark;
+  valAxisMajorUnit?: number;
+  valAxisMaxVal?: number;
+  valAxisMinorTickMark?: ChartAxisTickMark;
+  valAxisMinVal?: number;
+  valAxisOrientation?: 'minMax' | 'maxMin';
+  valAxisTitle?: string;
+  valAxisTitleColor?: string;
+  valAxisTitleFontFace?: string;
+  valAxisTitleFontSize?: number;
+  valAxisTitleRotate?: number;
+  valGridLine?: OptsChartGridLine;
+  /**
+   * Value label format code
+   * - this also directs Data Table formatting
+   * @example '#%' // round percent
+   * @example '0.00%' // shows values as '0.00%'
+   * @example '$0.00' // shows values as '$0.00'
+   */
+  valLabelFormatCode?: string;
+}
+interface ChartPropsChartBar {
+  bar3DShape?: string;
+  barDir?: string;
+  barGapDepthPct?: number;
+  /**
+   * MS-PPT > Format chart > Format Data Point > Series Options >  "Gap Width"
+   * - width (percent)
+   * - range: `0`-`500`
+   * @default 150
+   */
+  barGapWidthPct?: number;
+  barGrouping?: string;
+  /**
+   * MS-PPT > Format chart > Format Data Point > Series Options >  "Series Overlap"
+   * - overlap (percent)
+   * - range: `-100`-`100`
+   * @default 0
+   */
+  barOverlapPct?: number;
+  /**
+   * Draw connector lines between data points across stacked bar/column series
+   * ("Series Lines" in PowerPoint). Emits `<c:serLines>` in the bar chart.
+   *
+   * - `true` uses PowerPoint's automatic line styling.
+   * - An {@link OptsChartGridLine} object customizes color/size/style/cap.
+   * - Omit (or pass an object with `style: 'none'`) to disable.
+   *
+   * Bar (`bar`) charts only; ignored for 3D bar charts.
+   * @default undefined
+   * @example true
+   * @example { color: '777777', size: 1, style: 'dash' }
+   */
+  barSeriesLine?: boolean | OptsChartGridLine;
+}
+interface ChartPropsChartDoughnut {
+  dataNoEffects?: boolean;
+  holeSize?: number;
+}
+interface ChartPropsChartLine {
+  /**
+   * MS-PPT > Chart format > Format Data Series > Line > Cap type
+   * - line cap type
+   * @default flat
+   */
+  lineCap?: LineCap;
+  /**
+   * MS-PPT > Chart format > Format Data Series > Line > Dash type (chart-level default)
+   * - applies to every series that has no entry in `lineDashValues`
+   * @default solid
+   */
+  lineDash?: ChartLineDash;
+  /**
+   * Per-series dash type overrides; index matches the series order in the `data` array.
+   * - entries shorter than the series count fall back to `lineDash`
+   * - example: `['solid', 'dash', 'lgDash']` gives each series its own dash pattern
+   */
+  lineDashValues?: ChartLineDash[];
+  /**
+   * MS-PPT > Chart format > Format Data Series > Marker Options > Built-in > Type
+   * - marker type
+   * @default circle
+   */
+  lineDataSymbol?: 'circle' | 'dash' | 'diamond' | 'dot' | 'none' | 'square' | 'triangle';
+  /**
+   * MS-PPT > Chart format > Format Data Series > [Marker Options] > Border > Color
+   * - border color
+   * @default circle
+   */
+  lineDataSymbolLineColor?: string;
+  /**
+   * MS-PPT > Chart format > Format Data Series > [Marker Options] > Border > Width
+   * - border width (points)
+   * @default 0.75
+   */
+  lineDataSymbolLineSize?: number;
+  /**
+   * MS-PPT > Chart format > Format Data Series > Marker Options > Built-in > Size
+   * - marker size
+   * - range: 2-72
+   * @default 6
+   */
+  lineDataSymbolSize?: number;
+  /**
+   * MS-PPT > Chart format > Format Data Series > Line > Width
+   * - line width (points)
+   * - range: 0-1584
+   * @default 2
+   */
+  lineSize?: number;
+  /**
+   * MS-PPT > Chart format > Format Data Series > Line > Smoothed line
+   * - "Smoothed line"
+   * @default false
+   */
+  lineSmooth?: boolean;
+}
+interface ChartPropsChartPie {
+  dataNoEffects?: boolean;
+  /**
+   * MS-PPT > Format chart > Format Data Series > Series Options >  "Angle of first slice"
+   * - angle (degrees)
+   * - range: 0-359
+   * @default 0
+   */
+  firstSliceAng?: number;
+}
+interface ChartPropsChartRadar {
+  /**
+   * Radar chart sub-type, named to match the PowerPoint UI ("Radar", "Radar with
+   * Markers", "Filled Radar").
+   * @default radar
+   */
+  radarStyle?: 'radar' | 'markers' | 'filled';
+}
+/**
+ * Options for the modern (Office 2016) chartEx chart types.
+ *
+ * NOTE: chartEx charts (currently `waterfall`) render only in PowerPoint 2016+/Microsoft 365.
+ * In older Office, Google Slides, Keynote and LibreOffice a fallback placeholder shows instead.
+ */
+interface ChartPropsChartWaterfall {
+  /**
+   * Zero-based category indices to render as **subtotal/total** columns in a `waterfall` chart
+   * (columns anchored to the axis baseline rather than floating from the running cumulative
+   * value). Out-of-range or non-integer entries are dropped with a console warning.
+   * @example [0, 4] // first and fifth categories are totals
+   */
+  subtotals?: number[];
+}
+/**
+ * Bin configuration for a `histogram` chart. A histogram is fed **raw observations** (one series of
+ * `values`, no `labels`); PowerPoint groups them into bins automatically. The only control wired
+ * 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.
+ */
+interface ChartExBinning {
+  /** Which side of each bin interval is closed: `'r'` (right, the default) or `'l'` (left). */
+  intervalClosed?: 'l' | 'r';
+}
+interface ChartPropsChartHistogram {
+  /**
+   * Bin configuration for a `histogram` chart. Omit for PowerPoint's automatic binning.
+   * @example { intervalClosed: 'l' }
+   */
+  binning?: ChartExBinning;
+}
+/**
+ * Statistics configuration for a `boxWhisker` (box-and-whisker) chart. Each value series is
+ * summarized into a box (quartiles + median) with whiskers; these flags mirror the toggles
+ * PowerPoint exposes in the *Format Data Series* pane. All fields are optional and default to
+ * PowerPoint's own defaults (inclusive of the outlier points and the mean marker).
+ */
+interface ChartExStatistics {
+  /**
+   * How the first/third quartiles are computed: `'exclusive'` (PowerPoint's default — the median
+   * is excluded when splitting the halves) or `'inclusive'`.
+   */
+  quartileMethod?: 'inclusive' | 'exclusive';
+  /** Draw a line connecting the mean of each box across categories. Default `false`. */
+  meanLine?: boolean;
+  /** Mark the mean of each box with a marker. Default `true`. */
+  meanMarker?: boolean;
+  /** Plot outlier points (values beyond the whiskers) individually. Default `true`. */
+  outliers?: boolean;
+  /** Plot every non-outlier point alongside the box, not just the box itself. Default `false`. */
+  nonoutliers?: boolean;
+}
+interface ChartPropsChartBoxWhisker {
+  /**
+   * Statistics configuration for a `boxWhisker` chart. Omit for PowerPoint's defaults
+   * (exclusive quartiles, mean marker shown, outliers shown).
+   * @example { quartileMethod: 'inclusive', meanLine: true }
+   */
+  statistics?: ChartExStatistics;
+}
+/**
+ * Geography configuration for a `regionMap` (filled-map) chart. A region map colors each geographic
+ * area by its value; the category labels are region names (countries, states, provinces, …) that
+ * 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 —
+ * 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.
+ */
+interface ChartExGeography {
+  /** BCP-47 language used to interpret the region names, e.g. `'en-US'` (the default). */
+  cultureLanguage?: string;
+  /** ISO region the names are scoped to, e.g. `'US'` (the default) or `'FR'`. */
+  cultureRegion?: string;
+}
+interface ChartPropsChartRegionMap {
+  /**
+   * Geography configuration for a `regionMap` chart. Omit for PowerPoint's defaults
+   * (`cultureLanguage: 'en-US'`, `cultureRegion: 'US'`).
+   * @example { cultureLanguage: 'en-US', cultureRegion: 'FR' }
+   */
+  geography?: ChartExGeography;
+}
+interface ChartPropsChartStock {
+  /**
+   * 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.
+   *
+   * `<c:hiLowLines>` connect the high/low of each category in every style.
+   * @default 'hlc'
+   */
+  stockStyle?: 'hlc' | 'ohlc' | 'vhlc' | 'vohlc';
+}
+interface ChartPropsChartSurface {
+  /**
+   * Draw a 3-D surface (`<c:surface3DChart>`) rather than a 2-D contour / top view
+   * (`<c:surfaceChart>`). The 3-D surface tilts the scene; the contour looks straight down.
+   * @default true
+   */
+  surface3D?: boolean;
+  /**
+   * Draw the surface as a wireframe mesh (`<c:wireframe val="1"/>`) instead of a filled sheet.
+   * Applies to both the 3-D surface and the 2-D contour.
+   * @default false
+   */
+  surfaceWireframe?: boolean;
+}
+/**
+ * Per-series style overrides for a chart.
+ * Each entry applies to the series at the same index in the data array.
+ * Unset fields fall back to the chart-level option.
+ */
+interface ChartSeriesOpts {
+  /** Series fill / line color (hex, e.g. `'FF0000'`) */
+  color?: HexColor;
+  /** Data-label font color */
+  dataLabelColor?: string;
+  /** Data-label font bold */
+  dataLabelFontBold?: boolean;
+  /** Data-label typeface */
+  dataLabelFontFace?: string;
+  /** Data-label font italic */
+  dataLabelFontItalic?: boolean;
+  /** Data-label font size (points) */
+  dataLabelFontSize?: number;
+  /**
+   * Data-label number format code for this series.
+   * Overrides the chart-level `dataLabelFormatCode` for this series only.
+   * @example '#,##0' // thousands separator
+   * @example '0.00%' // shows values as '0.00%'
+   * @example '$0.00' // shows values as '$0.00'
+   */
+  dataLabelFormatCode?: string;
+  /**
+   * Line/radar series line width (points).
+   * Pass `0` to hide the line.
+   */
+  lineSize?: number;
+}
+interface ChartPropsDataLabel {
+  dataLabelBkgrdColors?: boolean;
+  dataLabelColor?: string;
+  dataLabelFontBold?: boolean;
+  dataLabelFontFace?: string;
+  dataLabelFontItalic?: boolean;
+  dataLabelFontSize?: number;
+  /**
+   * Data label format code
+   * @example '#%' // round percent
+   * @example '0.00%' // shows values as '0.00%'
+   * @example '$0.00' // shows values as '$0.00'
+   */
+  dataLabelFormatCode?: string;
+  dataLabelFormatScatter?: 'custom' | 'customXY' | 'XY';
+  dataLabelPosition?: 'b' | 'bestFit' | 'ctr' | 'l' | 'r' | 't' | 'inEnd' | 'outEnd';
+}
+interface ChartPropsDataTable {
+  dataTableFontSize?: number;
+  /**
+   * Data table format code
+   * @example '#%' // round percent
+   * @example '0.00%' // shows values as '0.00%'
+   * @example '$0.00' // shows values as '$0.00'
+   */
+  dataTableFormatCode?: string;
+  /**
+   * Whether to show a data table adjacent to the chart
+   * @default false
+   */
+  showDataTable?: boolean;
+  showDataTableHorzBorder?: boolean;
+  showDataTableKeys?: boolean;
+  showDataTableOutline?: boolean;
+  showDataTableVertBorder?: boolean;
+}
+interface ChartPropsLegend {
+  legendColor?: string;
+  legendFontFace?: string;
+  legendFontSize?: number;
+  /**
+   * Manual legend placement within the chart area.
+   *
+   * Each of `x`/`y`/`w`/`h` is a fraction (0-1) of the chart's width/height.
+   * `x`/`y` position the legend's top-left corner relative to the chart edge;
+   * `w`/`h` set its size. Each axis is independent: provide only `x` to move the
+   * legend horizontally while leaving vertical placement and size automatic.
+   * Setting this overrides the automatic placement implied by `legendPos`.
+   *
+   * Has no effect unless `showLegend` is `true`.
+   *
+   * @example { x: 0.7, y: 0.3, w: 0.25, h: 0.4 }
+   */
+  legendLayout?: PositionProps;
+  legendPos?: 'b' | 'l' | 'r' | 't' | 'tr';
+}
+interface ChartPropsTitle extends TextBaseProps {
+  title?: string;
+  titleAlign?: string;
+  titleBold?: boolean;
+  titleColor?: string;
+  titleFontFace?: string;
+  titleFontSize?: number;
+  titleItalic?: boolean;
+  titleUnderline?: boolean;
+  /**
+   * Manual title position (inches), relative to the chart.
+   * Each axis is independent: omit `x` to keep automatic horizontal centering,
+   * or omit `y` to keep automatic vertical placement. Provide at least one.
+   */
+  titlePos?: {
+    x?: number;
+    y?: number;
+  };
+  titleRotate?: number;
+}
+interface ChartOpts extends ChartPropsAxisCat, ChartPropsAxisSer, ChartPropsAxisVal, ChartPropsBase, ChartPropsChartBar, ChartPropsChartDoughnut, ChartPropsChartLine, ChartPropsChartPie, ChartPropsChartRadar, ChartPropsChartWaterfall, ChartPropsChartHistogram, ChartPropsChartBoxWhisker, ChartPropsChartRegionMap, ChartPropsChartStock, ChartPropsChartSurface, ChartPropsDataLabel, ChartPropsDataTable, ChartPropsLegend, ChartPropsTitle, ObjectNameProps, OptsChartGridLine, PositionProps {
+  /**
+   * 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;
+  /**
+   * Alt Text value ("How would you describe this object and its contents to someone who is blind?")
+   * - PowerPoint: [right-click on a chart] > "Edit Alt Text..."
+   */
+  altText?: string;
+  /**
+   * 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.
+   * - 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.
+   * - Keys must be non-empty strings; values must be strings. Invalid entries are dropped with a
+   *   console warning rather than emitting degenerate XML.
+   * @example { sourceId: 'q3-revenue', generator: 'my-deck-tool' }
+   */
+  metadata?: Record<string, string>;
+}
+//#endregion
+//#region src/types/style.d.ts
+interface BorderProps {
+  /**
+   * Border type
+   * @default solid
+   */
+  type?: 'none' | 'dash' | 'solid';
+  /**
+   * Border color (hex)
+   * @example 'FF3399'
+   * @default '666666'
+   */
+  color?: HexColor;
+  /**
+   * Border width (points)
+   * - MS-PPT > Format Shape > Fill & Line > Line > Width
+   * @default 1
+   */
+  width?: number;
+  /**
+   * Border transparency (percent)
+   * - MS-PPT > Format Shape > Fill & Line > Line > Transparency
+   * - range: 0-100
+   * @default 0
+   */
+  transparency?: number;
+  /**
+   * Line end cap style
+   * @default 'flat'
+   */
+  cap?: LineCap;
+}
+/**
+ * Slide-show navigation action for action-button shapes. Each value maps 1:1 onto
+ * `ppaction://hlinkshowjump?jump=<value>`. A specific numbered slide is reached via
+ * `HyperlinkProps.slide` instead (which emits `ppaction://hlinksldjump`).
+ */
+type HyperlinkActionJump = 'firstslide' | 'previousslide' | 'nextslide' | 'lastslide' | 'lastslideviewed' | 'endshow';
+interface HyperlinkProps {
+  _rId?: number;
+  /**
+   * Slide number to link to
+   */
+  slide?: number;
+  /**
+   * Url to link to
+   */
+  url?: string;
+  /**
+   * Hyperlink Tooltip
+   */
+  tooltip?: string;
+  /**
+   * Slide-show navigation action for action-button shapes. Emits a relationship-less
+   * `<a:hlinkClick action="ppaction://hlinkshowjump?jump=…"/>` on the shape.
+   * @example hyperlink: { action: 'nextslide' }
+   */
+  action?: HyperlinkActionJump;
+}
+interface ShadowProps {
+  /**
+   * shadow type
+   * @default 'none'
+   */
+  type: 'outer' | 'inner' | 'none';
+  /**
+   * shadow transparency (percent)
+   * - MS-PPT > Format Shape > Effects > Shadow > Transparency
+   * - range: 0-100 (0 = fully opaque, 100 = fully transparent)
+   * @example 25 // 25% transparent
+   */
+  transparency?: number;
+  /**
+   * blur (points)
+   * - range: 0-100
+   * @default 0
+   */
+  blur?: number;
+  /**
+   * angle (degrees)
+   * - range: 0-359
+   * @default 0
+   */
+  angle?: number;
+  /**
+   * shadow offset (points)
+   * - range: 0-200
+   * @default 0
+   */
+  offset?: number;
+  /**
+   * shadow color (hex format)
+   * @example 'FF3399'
+   */
+  color?: HexColor;
+  /**
+   * whether to rotate shadow with shape
+   * @default false
+   */
+  rotateWithShape?: boolean;
+}
+interface ShapeFillProps {
+  /**
+   * Fill color
+   * - `HexColor` or `ThemeColor`
+   * @example 'FF0000' // hex color (red)
+   * @example SchemeColor.text1 // Theme color (Text1)
+   */
+  color?: Color;
+  /**
+   * Transparency (percent)
+   * - MS-PPT > Format Shape > Fill & Line > Fill > Transparency
+   * - range: 0-100
+   * @default 0
+   */
+  transparency?: number;
+  /**
+   * Fill type
+   * @default 'solid'
+   */
+  type?: 'none' | 'solid' | 'gradient' | 'pattern' | 'image';
+  /**
+   * Native PPTX gradient fill options.
+   */
+  gradient?: GradientFillProps;
+  /**
+   * Native PPTX pattern fill options.
+   */
+  pattern?: PatternFillProps;
+  /**
+   * Native PPTX picture fill options. Setting this (or `type: 'image'`) fills the
+   * shape interior with a stretched bitmap instead of a color.
+   */
+  image?: ImageFillProps;
+  /**
+   * Resolved media relationship id for an image fill, assigned at add-time.
+   * @internal
+   */
+  _imgRid?: number;
+}
+/**
+ * Line (stroke) options.
+ *
+ * A stroke is painted like a fill: in addition to a solid `color`, it accepts the
+ * inherited `gradient`/`pattern`/`image` fill options (DrawingML allows the same
+ * fill group inside `<a:ln>`). Setting `gradient` (or `type: 'gradient'`) paints a
+ * gradient stroke, e.g. `line: { width: 1, gradient: { kind: 'linear', angle: 0,
+ * stops: [{ position: 0, color: 'accent3' }, { position: 100, color: 'accent4' }] } }`.
+ */
+interface ShapeLineProps extends ShapeFillProps {
+  /**
+   * Line width (pt)
+   * @default 1
+   */
+  width?: number;
+  /**
+   * Dash type
+   * @default 'solid'
+   */
+  dashType?: 'solid' | 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'sysDash' | 'sysDot';
+  /**
+   * Line end cap style
+   * @default 'flat'
+   */
+  cap?: LineCap;
+  /**
+   * Begin arrow type
+   */
+  beginArrowType?: 'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle';
+  /**
+   * End arrow type
+   */
+  endArrowType?: 'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle';
+}
+/**
+ * Connector routing style. Maps to a connector preset geometry. The exact preset
+ * also depends on `bends` (number of jogs):
+ * `straight`→`straightConnector1`; `elbow`→`bentConnector{3,4,5}`;
+ * `curved`→`curvedConnector{3,4,5}`.
+ */
+type ConnectorType = 'straight' | 'elbow' | 'curved';
+/**
+ * A connector is a line drawn between two points, emitted as a PowerPoint connector
+ * (`<p:cxnSp>`) so the app treats it as a connector (selectable/reroutable) rather than a
+ * plain line shape. Endpoints are given directly; the bounding box and flip flags are derived.
+ */
+interface ConnectorProps {
+  /**
+   * Routing style
+   * @default 'straight'
+   */
+  type?: ConnectorType;
+  /**
+   * 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
+   * - `2` → `bentConnector4` / `curvedConnector4` (two jogs)
+   * - `3` → `bentConnector5` / `curvedConnector5` (three jogs)
+   *
+   * Ignored for `type: 'straight'` (a straight connector has no bends).
+   * @default 1
+   */
+  bends?: 1 | 2 | 3;
+  /**
+   * Bend position(s) as a percent of the connector box (`0`–`100`), one value per bend.
+   * A single number sets the sole jog of a one-bend `elbow` / `curved`; an array sets each
+   * jog of a multi-bend connector and its length must equal `bends`. Values outside `0`–`100`
+   * are allowed (they place the bend beyond the endpoint box, as PowerPoint itself does when
+   * endpoints flip). When omitted, PowerPoint uses the preset default (50%).
+   *
+   * Emitted as `<a:gd name="adj1…" fmla="val …"/>` adjust guides (OOXML 1000ths-of-a-percent).
+   */
+  adj?: number | number[];
+  /**
+   * Bind the connector's start point to a shape on the **same slide**, referenced by that
+   * shape's `objectName`. Emits `<a:stCxn id=… idx=…>`, so PowerPoint treats the endpoint as
+   * attached: it reroutes when the shape moves and its elbow auto-router can engage.
+   * The shape's `objectName` must be set and unique on the slide. `x1`/`y1` remain the static
+   * fallback geometry (and are used if the name can't be resolved).
+   *
+   * A shape inside a group is a valid target — group children are named on the same slide — though
+   * the connector itself cannot be a group child (see {@link Slide.addGroup}).
+   */
+  startShape?: string;
+  /**
+   * 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
+   */
+  startShapeIdx?: number;
+  /** Bind the connector's end point to a shape on the same slide (by `objectName`). Emits `<a:endCxn>`. See {@link startShape}. */
+  endShape?: string;
+  /**
+   * Connection-site index on `endShape`. Ignored without `endShape`.
+   * @default 0
+   */
+  endShapeIdx?: number;
+  /** Start point X — inches, or a `Coord` such as `'50%'` / `'2in'` */
+  x1: Coord;
+  /** Start point Y */
+  y1: Coord;
+  /** End point X */
+  x2: Coord;
+  /** End point Y */
+  y2: Coord;
+  /**
+   * Line color (6-digit hex, no `#`)
+   * @default '000000'
+   */
+  color?: HexColor;
+  /**
+   * Line width (pt)
+   * @default 1
+   */
+  width?: number;
+  /** Dash style */
+  dashType?: ShapeLineProps['dashType'];
+  /** Arrowhead at the start point */
+  beginArrowType?: ShapeLineProps['beginArrowType'];
+  /** Arrowhead at the end point */
+  endArrowType?: ShapeLineProps['endArrowType'];
+  /** Selection Pane object name */
+  objectName?: string;
+  /** 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
+ * guessing. For other units use an explicit string suffix:
+ * - `number` → inches (e.g. `10.25`)
+ * - `"<n>%"` → percentage of the slide axis (e.g. `"75%"`)
+ * - `"<n>in"` → inches (e.g. `"10.25in"`)
+ * - `"<n>pt"` → points (e.g. `"72pt"` = 1 inch)
+ * - `"<n>px"` → CSS reference pixels at 96 px/inch (e.g. `"96px"` = 1 inch), for authoring against
+ *   a known web/source canvas size
+ * - `"<n>emu"` → raw EMU, the escape hatch for exact OOXML units (e.g. `"914400emu"` = 1 inch)
+ *
+ * @example 10.25 // inches
+ * @example '75%' // percentage of slide size
+ * @example '72pt' // points
+ * @example '960px' // pixels at 96 DPI = 10 inches
+ * @example '914400emu' // raw EMU
+ */
+type Coord = number | `${number}%` | `${number}in` | `${number}pt` | `${number}px` | `${number}emu`;
+interface PositionProps {
+  /**
+   * Horizontal position
+   * - inches or percentage
+   * @example 10.25 // position in inches
+   * @example '75%' // position as percentage of slide size
+   */
+  x?: Coord;
+  /**
+   * Vertical position
+   * - inches or percentage
+   * @example 10.25 // position in inches
+   * @example '75%' // position as percentage of slide size
+   */
+  y?: Coord;
+  /**
+   * Height
+   * - inches or percentage
+   * @example 10.25 // height in inches
+   * @example '75%' // height as percentage of slide size
+   */
+  h?: Coord;
+  /**
+   * Width
+   * - inches or percentage
+   * @example 10.25 // width in inches
+   * @example '75%' // width as percentage of slide size
+   */
+  w?: Coord;
+}
+/**
+ * Reusable optional data/path fields.
+ * Use `DataOrPathRequiredProps` for APIs that require at least one source.
+ */
+interface DataOrPathProps {
+  /**
+   * URL or relative path
+   *
+   * @example 'https://onedrives.com/myimg.png` // retrieve image via URL
+   * @example '/home/user/images/myimg.png` // retrieve image via local path
+   */
+  path?: string;
+  /**
+   * base64-encoded string
+   * - Useful for avoiding potential path/server issues
+   *
+   * @example 'image/png;base64,iVtDafDrBF[...]=' // pre-encoded image in base-64
+   */
+  data?: string;
+}
+type DataOrPathRequiredProps = (DataOrPathProps & {
+  data: string;
+}) | (DataOrPathProps & {
+  path: string;
+});
+interface BackgroundProps extends DataOrPathProps, ShapeFillProps {}
+/**
+ * Color in Hex format
+ * @example 'FF3399'
+ */
+type HexColor = string;
+type ThemeColor = 'tx1' | 'tx2' | 'bg1' | 'bg2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6';
+type Color = HexColor | ThemeColor;
+interface GradientStopProps {
+  /**
+   * Stop position as a percentage.
+   * - range: 0-100
+   */
+  position: number;
+  /**
+   * Stop color.
+   * - `HexColor` or `ThemeColor`
+   */
+  color: Color;
+  /**
+   * Transparency (percent)
+   * - range: 0-100
+   * @default 0
+   */
+  transparency?: number;
+}
+interface LinearGradientFillProps {
+  /**
+   * Gradient type.
+   */
+  kind: 'linear';
+  /**
+   * Gradient angle in degrees. Values are normalized into 0-359.999...
+   * @default 0
+   */
+  angle?: number;
+  /**
+   * Whether the gradient angle scales with the fill region.
+   */
+  scaled?: boolean;
+  /**
+   * Whether the fill rotates with the shape.
+   * @default true
+   */
+  rotateWithShape?: boolean;
+  /**
+   * Gradient stops. Stops are serialized in ascending `position` order.
+   */
+  stops: GradientStopProps[];
+}
+interface RadialGradientFillProps {
+  /**
+   * Gradient type. A circular gradient radiating from a focus point: the stop at
+   * `position: 0` sits at the center and later stops fan outward to the edges.
+   */
+  kind: 'radial';
+  /**
+   * Focus point of the radial gradient as percentages of the fill box, where
+   * `{ x: 50, y: 50 }` (the default) centers it. Lower/higher values push the
+   * bright center toward an edge.
+   * @default { x: 50, y: 50 }
+   */
+  center?: {
+    x: number;
+    y: number;
+  };
+  /**
+   * Whether the fill rotates with the shape.
+   * @default true
+   */
+  rotateWithShape?: boolean;
+  /**
+   * Gradient stops. Stops are serialized in ascending `position` order; the
+   * first (`position: 0`) is the center color.
+   */
+  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';
+interface PatternFillProps {
+  /** OOXML preset pattern (`prst` attribute on `<a:pattFill>`). */
+  preset: PatternPreset;
+  /** Foreground color. Defaults to black (`000000`) if omitted. */
+  fgColor?: Color;
+  /** Background color. Defaults to white (`FFFFFF`) if omitted. */
+  bgColor?: Color;
+}
+/**
+ * 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.
+ */
+interface ImageFillProps {
+  /** Image file path (Node filesystem path or URL). */
+  path?: string;
+  /** Pre-encoded base64 data URI, e.g. `'image/png;base64,iVBOR...'`. */
+  data?: string;
+}
+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.
+ * Maps to `<a:bodyPr vert="…">` (ECMA-376 `ST_TextVerticalType`).
+ */
+type TextVertType = 'eaVert' | 'horz' | 'mongolianVert' | 'vert' | 'vert270' | 'wordArtVert' | 'wordArtVertRtl';
+/**
+ * A single node of a freeform (`custGeom`) path.
+ * - coordinates are authored in the object's own inch/EMU space (0..width, 0..height), not slide-relative and not normalized
+ * - used by shapes (`ShapeType.custGeom`) and by images (clips the picture to the path)
+ *
+ * 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).
+ */
+type GeometryPoint = {
+  x: Coord;
+  y: Coord;
+  moveTo?: boolean;
+} | {
+  curve: {
+    type: 'arc';
+    hR: Coord;
+    wR: Coord;
+    stAng: number;
+    swAng: number;
+  };
+} | {
+  x: Coord;
+  y: Coord;
+  curve: {
+    type: 'cubic';
+    x1: Coord;
+    y1: Coord;
+    x2: Coord;
+    y2: Coord;
+  };
+} | {
+  x: Coord;
+  y: Coord;
+  curve: {
+    type: 'quadratic';
+    x1: Coord;
+    y1: Coord;
+  };
+} | {
+  close: true;
+};
+//#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'`.
+ *   PowerPoint shows these handles as the yellow drag dots on a selected shape.
+ * - `value` is a fraction `0.0–1.0` of the handle's range, emitted as a percentage
+ *   guide formula (`val`, in 1/100000 units, so `0.25` → `fmla="val 25000"`).
+ *   Most adjustment handles (corner radius, chevron point, callout depth, bevel
+ *   width, …) are percentage-based and map directly; some shapes accept values
+ *   beyond `1.0`. For angle-based handles, prefer the `angleRange` shortcut.
+ */
+interface ShapeAdjustValue {
+  name: string;
+  value: number;
+}
+/**
+ * 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,
+ *   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
+ *   `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.
+ * @see http://www.datypic.com/sc/ooxml/e-a_gd-1.html
+ */
+interface ShapeGuide {
+  name: string;
+  formula: string;
+}
+/**
+ * A connection site (`<a:cxn>` inside a `custGeom`'s `<a:cxnLst>`): a point a connector can attach
+ * to. A connector's `startShapeIdx`/`endShapeIdx` index into the target shape's connection sites.
+ */
+interface ShapeConnectionSite {
+  /** Incoming-connector angle in degrees (emitted to `ang`, `ST_AdjAngle` 60000ths). */
+  ang: number;
+  /** X in the object's own space (like `points`), or a guide-name string emitted verbatim. */
+  x: Coord | string;
+  /** 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. */
+interface ShapeAdjustHandleXY {
+  x: Coord | string;
+  y: Coord | string;
+  gdRefX?: string;
+  minX?: Coord | string;
+  maxX?: Coord | string;
+  gdRefY?: string;
+  minY?: Coord | string;
+  maxY?: Coord | string;
+}
+/** A polar adjust handle (`<a:ahPolar>`) — radius/angle rather than XY. */
+interface ShapeAdjustHandlePolar {
+  x: Coord | string;
+  y: Coord | string;
+  gdRefR?: string;
+  minR?: Coord | string;
+  maxR?: Coord | string;
+  gdRefAng?: string;
+  minAng?: number;
+  maxAng?: number;
+}
+type ShapeAdjustHandle = ShapeAdjustHandleXY | ShapeAdjustHandlePolar;
+interface ShapeProps extends PositionProps, ObjectNameProps {
+  /**
+   * Horizontal alignment
+   * @default 'left'
+   */
+  align?: HAlign;
+  /**
+   * Radius (only for ShapeType.pie, ShapeType.arc, ShapeType.blockArc)
+   * - In the case of ShapeType.blockArc you have to setup the arcThicknessRatio
+   * - values: [0-359, 0-359]
+   * @default [270, 0]
+   */
+  angleRange?: [number, number];
+  /**
+   * Preset-geometry adjustment handles (`<a:avLst>` guides) for any preset shape.
+   * - Use this to tune adjustment handles that lack a dedicated shortcut option,
+   *   e.g. chevron/arrow point depth, callout pointer, bevel/frame thickness.
+   * - Accepts a single guide or an array; each `value` is a `0.0–1.0` fraction of
+   *   the handle's range (see {@link ShapeAdjustValue}).
+   * - `rectRadius` / `angleRange` remain friendly shortcuts; any `shapeAdjust`
+   *   guide that does not collide with a shortcut name is emitted in addition.
+   * @example { name: 'adj', value: 0.25 } // set the single adjust handle to 25%
+   * @example [{ name: 'adj1', value: 0.5 }, { name: 'adj2', value: 0.25 }] // two handles
+   */
+  shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
+  /**
+   * Radius (only for ShapeType.blockArc)
+   * - You have to setup the angleRange values too
+   * - values: 0.0-1.0
+   * @default 0.5
+   */
+  arcThicknessRatio?: number;
+  /**
+   * Shape fill color properties
+   * @example { color:'FF0000' } // hex color (red)
+   * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
+   * @example { color:SchemeColor.accent1 } // Theme color Accent1
+   */
+  fill?: ShapeFillProps;
+  /**
+   * Flip shape horizontally?
+   * @default false
+   */
+  flipH?: boolean;
+  /**
+   * Flip shape vertical?
+   * @default false
+   */
+  flipV?: boolean;
+  /**
+   * Add hyperlink to shape
+   * @example hyperlink: { url: "https://example.com", tooltip: "Visit Homepage" },
+   */
+  hyperlink?: HyperlinkProps;
+  /**
+   * Line options
+   */
+  line?: ShapeLineProps;
+  /**
+   * Points (only for ShapeType.custGeom)
+   * - 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)
+   * - `swAng` Shape Arc Swing Angle (degrees, not wrapped into 0..360)
+   * @see http://www.datypic.com/sc/ooxml/e-a_arcTo-1.html
+   * @example [{ x: 0, y: 0 }, { x: 10, y: 10 }] // draw a line between those two points
+   */
+  points?: GeometryPoint[];
+  /**
+   * 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.
+   * 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),
+   * optionally bound to guides via `gdRef*`.
+   */
+  adjustHandles?: ShapeAdjustHandle[];
+  /**
+   * Rounded rectangle radius (only for ShapeType.roundRect)
+   * - values: 0.0 to 1.0
+   * @default 0
+   */
+  rectRadius?: number;
+  /**
+   * Rotation (degrees)
+   * - range: -360 to 360
+   * @default 0
+   * @example 180 // rotate 180 degrees
+   */
+  rotate?: number;
+  /**
+   * Shadow options
+   */
+  shadow?: ShadowProps;
+}
+//#endregion
+//#region src/types/media.d.ts
+type MediaType = 'audio' | 'online' | 'video';
+interface ImageBaseProps extends PositionProps, ObjectNameProps {
+  /**
+   * Sizing note (`w`/`h` inherited from {@link PositionProps}):
+   * - 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.
+   * - `path` images and vector (SVG) data cannot be measured synchronously, so an omitted
+   *   dimension falls back to 1 inch.
+   */
+  /**
+   * Alt Text value ("How would you describe this object and its contents to someone who is blind?")
+   * - PowerPoint: [right-click on an image] > "Edit Alt Text..."
+   */
+  altText?: string;
+  /**
+   * Flip horizontally?
+   * @default false
+   */
+  flipH?: boolean;
+  /**
+   * Flip vertical?
+   * @default false
+   */
+  flipV?: boolean;
+  hyperlink?: HyperlinkProps;
+  /**
+   * Border line (`<a:ln>` outline) drawn around the image
+   * - same options as a shape outline; a picture supports a single outline, not per-side borders
+   * - MS-PPT: Format Picture > Line
+   * @example { color: '0088CC', width: 2 }                   // 2pt blue border
+   * @example { color: '666666', width: 1, dashType: 'dash' } // dashed gray border
+   */
+  line?: ShapeLineProps;
+  /**
+   * Name of a picture placeholder defined on the slide layout/master to populate
+   * - 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
+   * @example 'picph'
+   * @see https://docs.microsoft.com/en-us/office/vba/api/powerpoint.ppplaceholdertype
+   */
+  placeholder?: string;
+  /**
+   * Image rotation (degrees)
+   * - range: -360 to 360
+   * @default 0
+   * @example 180 // rotate image 180 degrees
+   */
+  rotate?: number;
+  /**
+   * Enable image rounding (clips the image to a circle/ellipse)
+   * - shorthand for `shape: 'ellipse'`; `shape` takes precedence when both are set
+   * @default false
+   */
+  rounding?: boolean;
+  /**
+   * Clip the image to a preset shape geometry ("fit image into shape")
+   * - accepts any PowerPoint preset geometry name, e.g. `'roundRect'`, `'hexagon'`, `'ellipse'`
+   * - combine with `sizing: { type: 'cover', ... }` for an aspect-correct fill of the shape box
+   * - use `rectRadius` to set the corner radius for `'roundRect'`
+   * @example 'roundRect' // rounded-rectangle avatar
+   * @example 'hexagon'   // hexagonal photo
+   */
+  shape?: SHAPE_NAME;
+  /**
+   * Clip the image to an arbitrary freeform path (`custGeom`)
+   * - takes precedence over `shape` / `rounding` when present
+   * - coordinates are authored in the image's own inch/EMU space (0..w, 0..h), not slide-relative and not normalized
+   * - supports the same path DSL as freeform shapes: `moveTo` / `lnTo` / `cubicBezTo` / `quadBezTo` / `arcTo` / `close`
+   * @example [{ x: 1, y: 0 }, { x: 2, y: 2 }, { x: 0, y: 2 }, { close: true }] // triangular photo clip
+   */
+  points?: GeometryPoint[];
+  /**
+   * Rounded rectangle corner radius (inches) when `shape: 'roundRect'`
+   * - values: 0.0 to 1.0
+   * @default 0
+   */
+  rectRadius?: number;
+  /**
+   * Preset-geometry adjustment handles (`<a:avLst>` guides) for the clip `shape`.
+   * - tune adjustment handles that lack a dedicated option, e.g. chevron point depth
+   * - accepts a single guide or an array; each `value` is a `0.0–1.0` fraction (see {@link ShapeAdjustValue})
+   * @example { name: 'adj', value: 0.25 }
+   */
+  shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
+  /**
+   * Shadow Props
+   * - MS-PPT > Format Picture > Shadow
+   * @example
+   * { type: 'outer', color: '000000', transparency: 50, blur: 20,  offset: 20, angle: 270 }
+   */
+  shadow?: ShadowProps;
+  /**
+   * 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
+   *   same model PowerPoint's Picture Format > Crop uses; `l`+`r` and `t`+`b` must each be < 100
+   * - 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
+   *   `sizing: 'crop'` (which crops in *displayed inches*) it works for SVG and unmeasurable formats
+   * - mutually exclusive with {@link sizing}; if both are set `crop` wins and `sizing` is ignored
+   * @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 */
+    l?: number;
+    /** Percent (0–100) trimmed from the top edge of the source image. @default 0 */
+    t?: number;
+    /** Percent (0–100) trimmed from the right edge of the source image. @default 0 */
+    r?: number;
+    /** Percent (0–100) trimmed from the bottom edge of the source image. @default 0 */
+    b?: number;
+  };
+  /**
+   * Image sizing options
+   */
+  sizing?: {
+    /**
+     * Sizing type
+     * - `cover` / `contain` fit the image into the `w`×`h` box using the image's *natural*
+     *   pixel aspect ratio (read from the embedded PNG/JPEG/GIF/BMP/WebP header). If the
+     *   natural size cannot be determined (e.g. SVG or an unrecognized format) the displayed
+     *   `w`/`h` ratio is used as a fallback and a warning is logged.
+     * - `crop` cuts a window out of the displayed image using the `x`/`y`/`w`/`h` offsets.
+     */
+    type: 'contain' | 'cover' | 'crop';
+    /**
+     * Image width
+     * - inches or percentage
+     * @example 10.25 // position in inches
+     * @example '75%' // position as percentage of slide size
+     */
+    w: Coord;
+    /**
+     * Image height
+     * - inches or percentage
+     * @example 10.25 // position in inches
+     * @example '75%' // position as percentage of slide size
+     */
+    h: Coord;
+    /**
+     * Offset from left to crop image
+     * - `crop` only
+     * - inches or percentage
+     * @example 10.25 // position in inches
+     * @example '75%' // position as percentage of slide size
+     */
+    x?: Coord;
+    /**
+     * Offset from top to crop image
+     * - `crop` only
+     * - inches or percentage
+     * @example 10.25 // position in inches
+     * @example '75%' // position as percentage of slide size
+     */
+    y?: Coord;
+  };
+  /**
+   * Transparency (percent)
+   * - MS-PPT > Format Picture > Picture > Picture Transparency > Transparency
+   * - range: 0-100
+   * @default 0
+   * @example 25 // 25% transparent
+   */
+  transparency?: number;
+  /**
+   * Recolor the image as a two-tone (duotone) effect
+   * - maps the image's shadows to `shadow` and its highlights to `highlight`
+   * - serializes `<a:duotone>` inside the picture's `<a:blip>` (MS-PPT > Format Picture > Picture Color > Recolor)
+   * - colors accept `HexColor` or `ThemeColor`, same as fills
+   * - the classic brand treatment: tint stock photography into a single brand hue
+   * @example { shadow: '250F6B', highlight: 'FFFFFF' } // deep-blue duotone
+   */
+  duotone?: {
+    /** Color mapped to the image's dark/shadow tones. */
+    shadow: Color;
+    /** Color mapped to the image's light/highlight tones. */
+    highlight: Color;
+  };
+  /**
+   * Recolor the image to grayscale (`<a:grayscl/>`)
+   * - maps every pixel to its luminance grey (MS-PPT > Format Picture > Picture Color > Recolor > Grayscale)
+   * - the cheapest recolour: no payload
+   * - mutually exclusive with the other recolour modes (`duotone`/`biLevel`/`clrChange`); if several are set,
+   *   the first present in document order wins on read-back
+   * @default false
+   * @example true // desaturate the image
+   */
+  grayscale?: boolean;
+  /**
+   * Recolor the image to two-level black & white (`<a:biLevel thresh="…"/>`)
+   * - every pixel at/above the luminance threshold becomes white, everything below it black
+   *   (MS-PPT > Format Picture > Picture Color > Recolor > Black and White …%)
+   * @example { threshold: 0.5 } // split at 50% luminance
+   */
+  biLevel?: {
+    /** Luminance split point as a `0.0–1.0` fraction (serialized to `thresh`, the 0–1 fraction ×100000). */
+    threshold: number;
+  };
+  /**
+   * 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
+   *   (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
+   */
+  clrChange?: {
+    /** Source color to replace (`<a:clrFrom>`). */
+    from: Color;
+    /** Replacement color (`<a:clrTo>`). */
+    to: Color;
+  };
+  /**
+   * Raw SVG markup to embed as the image source
+   * - convenience for `data: 'data:image/svg+xml;base64,...'`; ts-pptx encodes it for you
+   * - ignored when `data` or `path` is also provided
+   * @example '<svg viewBox="0 0 24 24">...</svg>'
+   */
+  svg?: string;
+}
+type ImageProps = ImageBaseProps & (DataOrPathRequiredProps | (DataOrPathProps & {
+  svg: string;
+}));
+/**
+ * Add media (audio/video) to slide
+ * Requires either `data` or `path`; online media requires `link`.
+ */
+interface MediaBaseProps extends PositionProps, ObjectNameProps {
+  /**
+   * Cover image
+   * @default "play button" image, gray background
+   */
+  cover?: string;
+  /**
+   * media file extension
+   * - use when the media file path does not already have an extension, ex: "/folder/SomeSong"
+   * @default extension from file provided
+   */
+  extn?: string;
+  /**
+   * Loop playback indefinitely (PowerPoint "Playback > Loop until Stopped")
+   * - emits a slide timing tree so the embedded audio/video repeats when played
+   * - not supported for `type: 'online'` (e.g. YouTube) embeds
+   * @default false
+   */
+  loop?: boolean;
+  /**
+   * Total number of times to play the media (a finite loop), ex: `3` plays it three times
+   * - ignored when `loop` is `true` (which repeats forever)
+   * - not supported for `type: 'online'` (e.g. YouTube) embeds
+   */
+  loopCount?: number;
+}
+/**
+ * Add an embedded OLE object (PowerPoint's Insert ▸ Object ▸ Create from File) to a slide.
+ *
+ * The payload's bytes travel inside the `.pptx` (in `ppt/embeddings/`), so double-clicking the
+ * object in PowerPoint opens the source document in place. Requires either `data` or `path`.
+ * Linked objects (`<p:link>` to a file outside the package) are not supported.
+ */
+interface OleObjectBaseProps extends PositionProps, ObjectNameProps {
+  /**
+   * 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
+   *   other consumer (and PowerPoint's own `mc:Fallback` path) shows exactly what is supplied here
+   * - supply a real screenshot whenever the deck is meant to read correctly outside PowerPoint
+   * @example { path: 'assets/budget-preview.png' }
+   */
+  cover?: {
+    path?: string;
+    data?: string;
+  };
+  /**
+   * Payload file extension, used to name the embedded part and to pick the content type,
+   * relationship type, and default `progId`.
+   * - inferred from `data`'s MIME, else `path`'s extension, else `progId`
+   * - anything that is not a known Office package extension (`xlsx`/`xlsm`/`docx`/`docm`/`pptx`/`pptm`)
+   *   is embedded as a generic OLE blob part named `.bin`
+   * @example 'xlsx'
+   */
+  extn?: string;
+  /**
+   * 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'
+   */
+  progId?: string;
+  /**
+   * Display the object as its application icon instead of a document preview (`showAsIcon`).
+   * - the `cover` image is still what gets drawn, so supply an icon-looking preview to match
+   * @default false
+   */
+  showAsIcon?: boolean;
+  /**
+   * Native size of the preview image in EMU (`imgW`/`imgH`), which PowerPoint uses to keep the
+   * object's aspect ratio when it re-renders the embedded document.
+   * - defaults to the object's own `w`/`h` converted to EMU
+   */
+  imgW?: number;
+  /** @see {@link imgW} */
+  imgH?: number;
+}
+/**
+ * Options for `slide.addOleObject()`. Requires either `data` (base64, with or without a
+ * `data:...;base64,` header) or `path` (a local/remote file read at export time).
+ *
+ * Sizing note: `w`/`h` default to 4 × 3 inches rather than being measured, since the library
+ * does not open the embedded document.
+ */
+type OleObjectProps = OleObjectBaseProps & DataOrPathRequiredProps;
+type MediaProps = MediaBaseProps & ((DataOrPathRequiredProps & {
+  /**
+   * Media type
+   */
+  type: Exclude<MediaType, 'online'>;
+  /**
+   * Optional video embed link metadata.
+   */
+  link?: string;
+}) | (DataOrPathProps & {
+  /**
+   * Use 'online' to embed a YouTube video (only supported in recent versions of PowerPoint)
+   */
+  type: 'online';
+  /**
+   * video embed link
+   * - works with YouTube
+   * - other sites may not show correctly in PowerPoint
+   * @example 'https://www.youtube.com/embed/Dph6ynRVyUc' // embed a youtube video
+   */
+  link: string;
+}));
+//#endregion
+//#region src/types/table.d.ts
+/**
+ * A `<table>` element, from whatever DOM implementation the caller has.
+ *
+ * Deliberately *not* `lib.dom`'s `Element`. `lib.dom`'s types are built for a browser, and a
+ * non-browser DOM's element type — happy-dom's, jsdom's — declares its own members and does
+ * not satisfy them, so demanding `Element` would reject from TypeScript exactly the
+ * implementations `ts-pptx/html` exists to accept. Requiring the three members the conversion
+ * actually calls keeps a mistyped argument an error while letting every real DOM through.
+ */
+interface TableToSlidesElement {
+  getAttribute: (name: string) => string | null;
+  querySelector: (selectors: string) => unknown;
+  querySelectorAll: (selectors: string) => unknown;
+}
+/**
+ * The one thing `tableToSlides` asks a document for. Structural for the same reason
+ * {@link TableToSlidesElement} is.
+ */
+interface TableToSlidesDocument {
+  getElementById: (elementId: string) => TableToSlidesElement | null;
+}
+interface TableToSlidesProps extends TableProps {
+  _arrObjTabHeadRows?: TableRow[];
+  /**
+   * Add an image to slide(s) created during autopaging
+   * - `image` prop requires either `path` or `data`
+   * - see `DataOrPathProps` for details on `image` props
+   * - see `PositionProps` for details on `options` props
+   */
+  addImage?: {
+    image: DataOrPathProps;
+    options: PositionProps;
+  };
+  /**
+   * Add a shape to slide(s) created during autopaging
+   */
+  addShape?: {
+    shapeName: SHAPE_NAME;
+    options: ShapeProps;
+  };
+  /**
+   * Add a table to slide(s) created during autopaging
+   */
+  addTable?: {
+    rows: TableRow[];
+    options: TableProps;
+  };
+  /**
+   * Add a text object to slide(s) created during autopaging
+   */
+  addText?: {
+    text: TextProps[];
+    options: TextPropsOptions;
+  };
+  /**
+   * Whether to enable auto-paging
+   * - auto-paging creates new slides as content overflows a slide
+   * @default true
+   */
+  autoPage?: boolean;
+  /**
+   * Auto-paging character weight
+   * - adjusts how many characters are used before lines wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // lines are longer (increases the number of characters that can fit on a given line)
+   */
+  autoPageCharWeight?: number;
+  /**
+   * Auto-paging line weight
+   * - adjusts how many lines are used before slides wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // tables are taller (increases the number of lines that can fit on a given slide)
+   */
+  autoPageLineWeight?: number;
+  /**
+   * Whether to repeat head row(s) on new tables created by autopaging
+   * @default false
+   */
+  autoPageRepeatHeader?: boolean;
+  /**
+   * The `y` location to use on subsequent slides created by autopaging
+   * @default (top margin of Slide)
+   */
+  autoPageSlideStartY?: number;
+  /**
+   * Column widths (inches)
+   */
+  colW?: number | number[];
+  /**
+   * Document to resolve a table *id* against.
+   * - only consulted when the table is identified by string id; passing the element itself
+   *   needs no document, since one is reached through the element's `ownerDocument`
+   * - defaults to the global `document`, which is what a browser caller gets
+   * - supply this to convert a table outside a browser (any DOM implementation will do)
+   */
+  document?: TableToSlidesDocument;
+  /**
+   * Title of the slide master to use for the auto-paged slides (the `title` passed to
+   * `defineSlideMaster`). Matches the `masterTitle` option of `addSlide`.
+   * - define a master slide to have your auto-paged slides carry a corporate design, etc.
+   */
+  masterTitle?: string;
+  /**
+   * Slide margin
+   * - this margin will be across all slides created by auto-paging
+   */
+  slideMargin?: Margin;
+}
+interface TableCellProps extends TextBaseProps {
+  /**
+   * Auto-paging character weight
+   * - adjusts how many characters are used before lines wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // lines are longer (increases the number of characters that can fit on a given line)
+   */
+  autoPageCharWeight?: number;
+  /**
+   * Auto-paging line weight
+   * - adjusts how many lines are used before slides wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // tables are taller (increases the number of lines that can fit on a given slide)
+   */
+  autoPageLineWeight?: number;
+  /**
+   * Cell border
+   */
+  border?: BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps];
+  /**
+   * Cell colspan
+   */
+  colspan?: number;
+  /**
+   * Cell fill — a solid color, or a picture that fills the cell (`a:blipFill` in
+   * the cell's `a:tcPr`, stretched to the cell box). A picture fill embeds the
+   * image as slide media; identical sources are embedded once. Raster only —
+   * an SVG source warns and is ignored, matching shape fills.
+   * @example { color:'FF0000' } // hex color (red)
+   * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
+   * @example { color:SchemeColor.accent1 } // theme color Accent1
+   * @example { type:'image', image:{ path:'logo.png' } } // picture fill
+   * @example { image:{ data:'image/png;base64,…' } } // picture fill, `type` inferred
+   */
+  fill?: ShapeFillProps;
+  hyperlink?: HyperlinkProps;
+  /**
+   * Cell margin (inches)
+   * @default 0
+   */
+  margin?: Margin;
+  /**
+   * Cell rowspan
+   */
+  rowspan?: number;
+  /**
+   * Shrink cell text to fit when it would overflow the cell's fixed height.
+   * - `'shrink'` measures the wrapped text and bakes a **reduced literal font size**
+   *   onto the cell's runs so the text fits — PowerPoint does not support text
+   *   autofit (`normAutofit`) inside table cells, so there is no font-scale flag to
+   *   set; the size itself is lowered, which both PowerPoint and LibreOffice render
+   *   identically with no edit/resize.
+   * - Requires the cell font registered via {@link TsPptx.registerFontMetrics};
+   *   without metrics it is a no-op (the cell keeps its authored size) and warns once.
+   * - Only triggers when the cell's row has a **fixed** height that the text exceeds.
+   *   With auto-height rows (no `rowH`/`h`), the row simply grows, so nothing shrinks.
+   * - Only `'shrink'` is acted on for cells. `'resize'` and the object form are ignored
+   *   here: a table row already auto-grows to fit its tallest cell (the cell equivalent
+   *   of `spAutoFit`), so there is nothing to bake. (The wider union is shared with
+   *   {@link TextPropsOptions.fit} so table-level `fit` can cascade to cells.)
+   * @example 'shrink' // measured when the cell font is registered; else no-op
+   */
+  fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
+}
+/**
+ * Styling for one region of a custom table style (maps to a `CT_TablePartStyle`).
+ * A region (e.g. the header row or banded rows) is shown only when the matching
+ * `TableProps` flag is set — `firstRow` needs `hasHeader`, `band1H`/`band2H` need
+ * `hasBandedRows`, and so on.
+ * @see TableStyleProps
+ */
+interface TableStyleRegionProps {
+  /**
+   * Solid cell fill color (hex).
+   * - `HexColor` only; theme references are not supported in custom styles
+   * @example '1A2B3C'
+   */
+  fill?: HexColor;
+  /**
+   * Text color (hex).
+   * @example 'FFFFFF'
+   */
+  color?: HexColor;
+  /** Bold text. */
+  bold?: boolean;
+  /** Italic text. */
+  italic?: boolean;
+  /**
+   * Cell border(s).
+   * - single value is applied to all four sides plus the interior grid lines
+   * - array of values in TRBL order styles only the four outer sides
+   */
+  border?: BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps];
+}
+/**
+ * A reusable custom table style written to `ppt/tableStyles.xml`.
+ * Pass to `pptx.defineTableStyle()`, which registers it and returns a GUID to use
+ * as `TableProps.tableStyle`. Unlike the fixed built-in `TableStyle` set, a custom
+ * style can use arbitrary brand colors, is editable in PowerPoint's Table Styles
+ * gallery, and bands correctly across any row/column count (including auto-paged tables).
+ * @example
+ * const brand = pptx.defineTableStyle({
+ *   name: 'Brand Banded',
+ *   wholeTbl: { border: { type:'solid', color:'D9D9D9', width:0.5 } },
+ *   firstRow: { fill:'1A2B3C', color:'FFFFFF', bold:true },
+ *   band1H:   { fill:'EAF1F8' },
+ *   band2H:   { fill:'FFFFFF' },
+ * })
+ * slide.addTable(rows, { tableStyle: brand, hasHeader:true, hasBandedRows:true })
+ */
+interface TableStyleProps {
+  /** Display name shown in PowerPoint's Table Styles gallery. */
+  name: string;
+  /** Base styling applied to every cell. */
+  wholeTbl?: TableStyleRegionProps;
+  /** Header (first) row — activated by `TableProps.hasHeader`. */
+  firstRow?: TableStyleRegionProps;
+  /** Footer (last) row — activated by `TableProps.hasFooter`. */
+  lastRow?: TableStyleRegionProps;
+  /** First column — activated by `TableProps.hasFirstColumn`. */
+  firstCol?: TableStyleRegionProps;
+  /** Last column — activated by `TableProps.hasLastColumn`. */
+  lastCol?: TableStyleRegionProps;
+  /** Odd horizontal band — activated by `TableProps.hasBandedRows`. */
+  band1H?: TableStyleRegionProps;
+  /** Even horizontal band — activated by `TableProps.hasBandedRows`. */
+  band2H?: TableStyleRegionProps;
+  /** Odd vertical band — activated by `TableProps.hasBandedColumns`. */
+  band1V?: TableStyleRegionProps;
+  /** Even vertical band — activated by `TableProps.hasBandedColumns`. */
+  band2V?: TableStyleRegionProps;
+}
+interface TableProps extends PositionProps, TextBaseProps, ObjectNameProps {
+  _arrObjTabHeadRows?: TableRow[];
+  /**
+   * Name of a table/content placeholder defined on the slide layout/master to bind this table to.
+   * - when it matches a layout/master placeholder, the table's `<p:graphicFrame>` emits that
+   *   placeholder's `<p:ph>` (idx/type) so PowerPoint treats the table as filling the placeholder
+   *   (e.g. a "Title and Content" content placeholder)
+   * - the table also inherits the placeholder's position/size for any of x/y/w/h left unset
+   * @example 'body' // bind to the layout placeholder named 'body'
+   */
+  placeholder?: string;
+  /**
+   * Whether to enable auto-paging
+   * - auto-paging creates new slides as content overflows a slide
+   * @default false
+   */
+  autoPage?: boolean;
+  /**
+   * Auto-paging character weight
+   * - adjusts how many characters are used before lines wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // lines are longer (increases the number of characters that can fit on a given line)
+   */
+  autoPageCharWeight?: number;
+  /**
+   * Auto-paging line weight
+   * - adjusts how many lines are used before slides wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // tables are taller (increases the number of lines that can fit on a given slide)
+   */
+  autoPageLineWeight?: number;
+  /**
+   * Whether table header row(s) should be repeated on each new slide creating by autoPage.
+   * Use `autoPageHeaderRows` to designate how many rows comprise the table header (1+).
+   * @default false
+   */
+  autoPageRepeatHeader?: boolean;
+  /**
+   * Number of rows that comprise table headers
+   * - required when `autoPageRepeatHeader` is set to true.
+   * @example 2 - repeats the first two table rows on each new slide created
+   * @default 1
+   */
+  autoPageHeaderRows?: number;
+  /**
+   * The `y` location to use on subsequent slides created by autopaging
+   * @default (top margin of Slide)
+   */
+  autoPageSlideStartY?: number;
+  /**
+   * Whether populated placeholders on the source slide (e.g. a title set via
+   * `addText(text, { placeholder })`) are copied onto each overflow slide created by autoPage.
+   * - new slides otherwise inherit only the layout's empty placeholders, so a title set on the
+   *   first slide would not appear on continuation slides.
+   * @default false
+   */
+  autoPagePlaceholder?: boolean;
+  /**
+   * Table border
+   * - single value is applied to all 4 sides
+   * - array of values in TRBL order for individual sides
+   */
+  border?: BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps];
+  /**
+   * Width of table columns (inches)
+   * - single value is applied to every column equally based upon `w`
+   * - array of values in applied to each column in order
+   * @default columns of equal width based upon `w`
+   */
+  colW?: number | number[];
+  /**
+   * Shrink columns proportionally so a too-wide table fits the slide.
+   * - `'shrink'`: if the total column width exceeds the space available between
+   *   the table's `x` and the right slide margin, scale every column down by the
+   *   same factor so the whole table fits. Columns that already fit are untouched.
+   * - applies to an explicit `colW` array (the common "too many columns" case) and
+   *   to a `w` wider than the slide; never grows columns and never enforces a
+   *   minimum width, so a very high column count can still become thin.
+   * - opt-in: explicit widths are otherwise emitted as-is and may run off the slide.
+   * @default undefined (no scaling)
+   */
+  fitColumns?: 'shrink';
+  /**
+   * Table-level text-fit policy, cascaded to every cell that does not set its own
+   * {@link TableCellProps.fit}.
+   * - `'shrink'`: each cell whose row has a **fixed** height that its wrapped text
+   *   would exceed gets a reduced literal font size baked onto its runs so the text
+   *   fits (see {@link TableCellProps.fit} for the full semantics and the font-metrics
+   *   requirement). Cells that set their own `fit` win over this table default.
+   * - `'none'` / `'resize'` / the object form are accepted for parity with
+   *   {@link TextPropsOptions.fit} but only `'shrink'` is acted on for table cells.
+   * @default undefined (cells keep their authored size)
+   * @example 'shrink'
+   */
+  fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
+  /**
+   * Mark the first row as a header row.
+   * Emits `firstRow="1"` on `<a:tblPr>`, activating the first-row style region of
+   * the table style and satisfying the PowerPoint accessibility checker's "table header" rule.
+   * @default false
+   */
+  hasHeader?: boolean;
+  /**
+   * Mark the last row as a footer row.
+   * Emits `lastRow="1"` on `<a:tblPr>`, activating the last-row style region.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasFooter?: boolean;
+  /**
+   * Enable alternating row (band) shading.
+   * Emits `bandRow="1"` on `<a:tblPr>`, activating band1H/band2H style regions.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasBandedRows?: boolean;
+  /**
+   * Enable alternating column (band) shading.
+   * Emits `bandCol="1"` on `<a:tblPr>`, activating band1V/band2V style regions.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasBandedColumns?: boolean;
+  /**
+   * Apply special styling to the first column.
+   * Emits `firstCol="1"` on `<a:tblPr>`, activating the firstCol style region.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasFirstColumn?: boolean;
+  /**
+   * Apply special styling to the last column.
+   * Emits `lastCol="1"` on `<a:tblPr>`, activating the lastCol style region.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasLastColumn?: boolean;
+  /**
+   * Lay the table out right-to-left.
+   * Emits `rtl="1"` on `<a:tblPr>`, which mirrors the column order so the first
+   * column renders on the right — the correct layout for RTL scripts (Arabic, Hebrew).
+   * This controls only the table/column direction; per-cell text direction is set
+   * with each cell's `rtlMode` option.
+   * @default false
+   */
+  rtl?: boolean;
+  /**
+   * Table style to apply, either a built-in `TableStyle` member or the GUID
+   * returned by `pptx.defineTableStyle()` for a custom style.
+   * Emits `<a:tableStyleId>` inside `<a:tblPr>` with the corresponding GUID.
+   * Style flags (`hasHeader`, `hasFooter`, `hasBandedRows`, etc.) select which
+   * regions of the chosen style are activated; they have no visible effect without
+   * a `tableStyle` set.
+   *
+   * @example tableStyle: pptx.TableStyle.MEDIUM_STYLE_2_ACCENT_1 // built-in
+   * @example const brand = pptx.defineTableStyle({ name:'Brand', firstRow:{ fill:'1A2B3C', color:'FFFFFF', bold:true } }); tableStyle: brand
+   */
+  tableStyle?: TableStyle | string;
+  /**
+   * Inline styling for the header (first) row, applied as direct per-cell formatting.
+   *
+   * Convenience shortcut for styling a header distinctly from the body **without** first
+   * registering a custom style via `pptx.defineTableStyle({ firstRow })`. Each property is
+   * merged onto every cell of row 0 (`fill`, `color`, `bold`, `align`, `border`, etc.).
+   *
+   * Precedence (highest wins), matching how PowerPoint resolves styling — direct cell
+   * formatting overrides a table-style region:
+   * 1. explicit per-cell `options` on a row-0 cell
+   * 2. this `headerRow`
+   * 3. the `firstRow` region of any `tableStyle`
+   * 4. `wholeTbl` / defaults
+   *
+   * Setting `headerRow` also implies `hasHeader: true` (emits `firstRow="1"` for the
+   * accessibility "table header" marker) unless `hasHeader` is explicitly set to `false`.
+   * @example headerRow: { fill: { color:'1A2B3C' }, color:'FFFFFF', bold:true, align:'center' }
+   */
+  headerRow?: TableCellProps;
+  /**
+   * Per-column default cell styling, applied as direct per-cell formatting.
+   *
+   * `columns[i]` is merged onto every cell that starts in column `i` (`fill`, `color`,
+   * `bold`, `align`, `valign`, `border`, `margin`, …), so a wide **colored** matrix —
+   * per-column fills, maturity-gradient headers — does not require hand-writing a fill
+   * onto every cell. Entries may be sparse (`columns[2]` alone styles only column 2);
+   * an `undefined`/omitted entry leaves that column untouched. The whole option is
+   * optional and degrades cleanly to today's text-on-white when not given.
+   *
+   * Precedence (highest wins), matching how PowerPoint resolves styling — direct cell
+   * formatting overrides a table-style region:
+   * 1. explicit per-cell `options`
+   * 2. `headerRow` (row 0 only)
+   * 3. this `columns[colIdx]`
+   * 4. `wholeTbl` / `tableStyle` / defaults
+   *
+   * The merge is property-level, so a header cell keeps `headerRow`'s typography **and**
+   * takes its column's `fill` when they set different properties. For a graduated header
+   * band, put shared header typography (bold/white/centered, **no fill**) in `headerRow`
+   * and let each `columns[i].fill` supply that column's fill.
+   *
+   * Column index counts each cell's `colspan` (default 1) within a row, so merged cells
+   * map to the correct column; it does not track `rowspan`s inherited from earlier rows.
+   *
+   * There is deliberately no built-in "group bracket" annotation. Label a span of columns
+   * by composing existing primitives: `addShape('rightBrace', …)` (or `'bracePair'`) plus
+   * `addText`, positioned from the table's `x` and `colW` (a span's `x`/`w` is the running
+   * sum of the preceding/covered column widths).
+   *
+   * @example columns: [{}, { fill: { color:'E8F0FE' } }, { fill: { color:'C6DAFC' } }] // per-column solid fills
+   * @example // gradient header: shared typography on headerRow, graduated fills per column
+   * headerRow: { color:'FFFFFF', bold:true, align:'center' },
+   * columns: [{}, { fill:{color:'BBD3FB'} }, { fill:{color:'89AEF6'} }, { fill:{color:'4B7BE5'} }]
+   */
+  columns?: TableCellProps[];
+  /**
+   * Default cell background for every cell in the table — a solid color or a
+   * picture fill. Superseded per cell by `options.fill`, `headerRow`, and
+   * `columns[i]`. A picture fill is embedded once and shared by every cell that
+   * inherits it.
+   * @example { color:'FF0000' } // hex color (red)
+   * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
+   * @example { color:SchemeColor.accent1 } // theme color Accent1
+   * @example { type:'image', image:{ path:'watermark.png' } } // picture fill
+   */
+  fill?: ShapeFillProps;
+  /**
+   * Cell margin (inches)
+   * - affects all table cells, is superceded by cell options
+   */
+  margin?: Margin;
+  /**
+   * Height of table rows (inches)
+   * - single value is applied to every row equally based upon `h`
+   * - array of values in applied to each row in order
+   * @default rows of equal height based upon `h`
+   */
+  rowH?: number | number[];
+  /**
+   * DEV-ONLY diagnostic flag: when `true`, logs a verbose trace of the auto-paging
+   * calculations to the console. Intended for debugging table layout only; leave unset
+   * in production. Inherited by {@link TableToSlidesProps}.
+   * @default false
+   */
+  verbose?: boolean;
+}
+interface TableCell {
+  _type?: SlideObjectType.tablecell;
+  /** lines in this cell (autoPage) */
+  _lines?: TableCell[][];
+  /** `text` prop but guaranteed to hold "TableCell[]" */
+  _tableCells?: TableCell[];
+  /** height in EMU */
+  _lineHeight?: number;
+  _hmerge?: boolean;
+  _vmerge?: boolean;
+  _rowContinue?: number;
+  /** origin cell of a colspan/rowspan span, set on the dummy `_hmerge`/`_vmerge` cells so they can
+   * inherit the origin's border/fill and render the merged region's outer edges */
+  _spanOrigin?: TableCell;
+  /**
+   * Cell content: a plain string, or an array of `TableCell` runs for mixed formatting.
+   * (A `number` is still coerced to a string at runtime for plain-JS callers, but is no
+   * longer part of the type — pass `String(n)` from TypeScript.)
+   */
+  text?: string | TableCell[];
+  options?: TableCellProps;
+}
+interface TableRowSlide {
+  rows: TableRow[];
+  /**
+   * Per-row height (inches) aligned 1:1 with `rows`, derived from the original `rowH` array.
+   * Auto-paging splits/reorders rows across slides and inserts repeated headers, so the caller's
+   * `rowH[i]` (keyed by *original* row index) can no longer be applied by physical row index on
+   * each generated slide. This carries each output row's resolved height so a configured height
+   * follows its source row instead of being re-applied to whatever lands at that index.
+   * Entries are `undefined` where no explicit height was configured (auto-distributed height).
+   */
+  rowH?: Array<number | undefined>;
+}
+type TableRow = TableCell[];
+//#endregion
+//#region src/types/animation.d.ts
+/**
+ * Slide transition and animation types.
+ *
+ * Re-exported by `./index.js`, which is the import site for the rest of `src/`.
+ */
+/**
+ * Base ECMA-376 slide-transition type (`p:transition`'s single type child). Each
+ * maps to a `<p:TYPE/>` element; type-specific variants (e.g. direction) go in
+ * {@link TransitionProps.variant}. Modern PowerPoint-only transitions (Morph,
+ * Vortex, …) live in the `p14`/`p15`/`p159` namespaces and are out of authoring
+ * scope for now. See `docs/animations-and-transitions.md`.
+ */
+type TransitionType = 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'cut' | 'diamond' | 'dissolve' | 'fade' | 'newsflash' | 'plus' | 'pull' | 'push' | 'random' | 'randomBar' | 'split' | 'strips' | 'wedge' | 'wheel' | 'wipe' | 'zoom';
+/**
+ * Slide-show transition applied between slides (`p:transition`). Assign to
+ * {@link Slide.transition}. Setting `durationMs` emits PowerPoint's
+ * `mc:AlternateContent` form (a `p14` Choice carrying `p14:dur` plus a base
+ * `mc:Fallback`); otherwise only the coarse `speed` bucket is written.
+ * @example slide.transition = { type: 'push', durationMs: 1250, variant: { dir: 'd' } }
+ */
+interface TransitionProps {
+  /** Transition type (the `<p:TYPE/>` element), e.g. `fade`, `push`, `wipe`, `cut`, `dissolve`. */
+  type: TransitionType;
+  /** Exact duration in milliseconds (`p14:dur`); emits the `mc:AlternateContent` form. */
+  durationMs?: number;
+  /** Coarse speed bucket (`spd`); derived from `durationMs` when omitted, else defaults to `fast`. */
+  speed?: 'slow' | 'med' | 'fast';
+  /** Advance on mouse click (`advClick`). @default true */
+  advanceOnClick?: boolean;
+  /** Auto-advance after this many milliseconds (`advTm`). */
+  advanceAfterMs?: number;
+  /** Type-specific variant attributes, e.g. `{ dir: 'd' }` for push, `{ spokes: '2' }` for wheel. */
+  variant?: Record<string, string>;
+  /** Sound played with the transition (`p:sndAc`): a start sound (embedded WAV) or the stop-previous form. */
+  sound?: TransitionSoundProps;
+  /**
+   * Internal: the slide relationship id assigned to the embedded sound part, stamped
+   * by the export-time registration pass. Not part of the authoring surface.
+   */
+  _sndRId?: number;
+}
+/**
+ * A transition sound (`p:sndAc`). Either a **start sound** — an embedded WAV played
+ * when the transition runs (`p:stSnd` → `p:snd`), optionally looped — or the
+ * **stop-previous** form (`p:endSnd`) that silences a still-playing transition
+ * sound. Built-in PowerPoint sounds embed identically to a custom file, so there is
+ * no separate built-in path: supply the WAV bytes via `data` or `path`.
+ * See `docs/animations-and-transitions.md`.
+ */
+interface TransitionSoundProps {
+  /** Embedded sound bytes as a base64 data URI (e.g. `data:audio/wav;base64,…`) or raw base64. */
+  data?: string;
+  /** Path to a sound file, read at export time (alternative to `data`). */
+  path?: string;
+  /** Display name emitted on `<p:snd @name>` (e.g. `ding.wav`); defaults to the file name. */
+  name?: string;
+  /** Loop the sound until the next sound starts (`<p:stSnd loop="1">`). @default false */
+  loop?: boolean;
+  /** Emit the stop-previous form (`<p:endSnd/>`) instead of a start sound. Mutually exclusive with `data`/`path`. */
+  stopPrevious?: boolean;
+}
+/**
+ * A preset build-animation effect. The supported set is fixed (each is a verbatim
+ * template captured from PowerPoint); adding one means adding a fixture + template,
+ * not a new code path. See `docs/animations-and-transitions.md`.
+ */
+type PresetEffect = 'fadeIn' | 'flyIn' | 'appear' | 'wipe' | 'grow' | 'spin' | 'fadeOut' | 'flyOut';
+/** When a build-animation effect starts relative to the preceding one. */
+type AnimationTrigger = 'onClick' | 'withPrevious' | 'afterPrevious';
+/**
+ * A preset build animation on a shape (entrance/emphasis/exit), added via
+ * {@link Slide.addAnimation}. Target the shape by its 0-based add order
+ * (`shapeIndex`, mapping to the generated `spid = shapeIndex + 2`) or by
+ * `objectName`. Effects play in the order added, grouped into click steps by
+ * `trigger`.
+ */
+interface AnimationProps {
+  /** The preset effect to play. */
+  preset: PresetEffect;
+  /**
+   * 0-based add order of the target shape on the slide (`spid = shapeIndex + 2`).
+   * Counts top-level objects only; use `objectName` to target a shape inside a group.
+   */
+  shapeIndex?: number;
+  /**
+   * Target shape by its `objectName` (alternative to `shapeIndex`). Any shape on the slide,
+   * including one inside a group; an unresolved name warns and drops the effect.
+   */
+  objectName?: string;
+  /** Trigger relative to the previous effect. @default 'onClick' */
+  trigger?: AnimationTrigger;
+  /** Effect duration in milliseconds; preset-specific default when omitted. */
+  durationMs?: number;
+}
+//#endregion
+//#region src/types/master.d.ts
+interface SlideNumberProps extends PositionProps, TextBaseProps {
+  /**
+   * margin (inches) — text-frame internal margin; a value `>= 1` warns as a likely legacy points value
+   */
+  margin?: Margin;
+}
+interface SlideMasterChartProps {
+  type: CHART_NAME | ChartMulti[];
+  data: OptsChartData[];
+  options?: ChartOpts;
+  opts?: ChartOpts;
+}
+type SlideMasterObject = {
+  chart: SlideMasterChartProps;
+} | {
+  image: ImageProps;
+} | {
+  line: ShapeProps;
+} | {
+  rect: ShapeProps;
+} | {
+  roundRect: ShapeProps;
+} |
+/**
+ * Any preset shape, addressed by `SHAPE_NAME` (e.g. `ShapeType.ellipse`).
+ * Generalizes the `line`/`rect`/`roundRect` shortcuts to every preset the
+ * `addShape()` serializer supports (ellipse, triangle, chevron, …).
+ * @example { shape: { type: 'ellipse', options: { x: 1, y: 1, w: 2, h: 2, fill: { color: 'FF0000' } } } }
+ */
+{
+  shape: {
+    type: SHAPE_NAME;
+    options?: ShapeProps;
+  };
+} | {
+  text: {
+    text: string | number | TextProps[];
+    options?: TextPropsOptions;
+  };
+} | {
+  placeholder: {
+    options: PlaceholderProps;
+    /**
+     * Text to be shown in placeholder (shown until user focuses textbox or adds text)
+     * - Leave blank to have powerpoint show default phrase (ex: "Click to add title")
+     */
+    text?: string;
+  };
+};
+/**
+ * Bullet configuration for one slide-master text-style level (`a:buChar`/`a:buAutoNum`/`a:buNone`).
+ * A focused subset of the run-level bullet model — picture bullets and per-glyph sizing are not
+ * supported in master defaults (those require slide rels). Set `bullet: false` to suppress the
+ * level's bullet entirely.
+ */
+interface MasterBulletProps {
+  /** `'bullet'` emits a character bullet (`a:buChar`); `'number'` emits an auto-number (`a:buAutoNum`). @default 'bullet' */
+  type?: 'bullet' | 'number';
+  /** Bullet character (unicode code point hex), e.g. `'2022'` for •. Used when `type` is `'bullet'`. */
+  characterCode?: string;
+  /** Glyph font typeface for the bullet character (`a:buFont`), e.g. `'Arial'` or `'Wingdings'`. */
+  fontFace?: string;
+  /** Auto-number scheme (`a:buAutoNum@type`) when `type` is `'number'`, e.g. `'arabicPeriod'`. @default 'arabicPeriod' */
+  numberType?: string;
+  /** Starting value for auto-numbered bullets (`a:buAutoNum@startAt`). @default 1 */
+  numberStartAt?: number;
+}
+/**
+ * Styling for one paragraph level (`a:lvlNpPr`) of a slide-master text style. Every field is
+ * optional; an unset field keeps PowerPoint's built-in default for that level. Configure via
+ * {@link SlideMasterProps.textStyles}.
+ */
+interface MasterTextStyleLevel {
+  /** Font size in points (`a:defRPr@sz`), e.g. `24`. */
+  fontSize?: number;
+  /** Font face (`a:defRPr/a:latin@typeface`). Unset keeps the theme font (`+mn-lt`/`+mj-lt`). */
+  fontFace?: string;
+  /** Text color — hex (`'C00000'`) or theme slot (`'tx1'`) — emitted as `a:defRPr/a:solidFill`. */
+  color?: Color;
+  /** Bold text (`a:defRPr@b`). */
+  bold?: boolean;
+  /** Italic text (`a:defRPr@i`). */
+  italic?: boolean;
+  /** Horizontal alignment (`a:lvlNpPr@algn`). */
+  align?: HAlign;
+  /** Left margin in inches (`a:lvlNpPr@marL`); for a hanging bullet this is the text indent. */
+  marginLeft?: number;
+  /** First-line indent in inches (`a:lvlNpPr@indent`); negative produces a hanging bullet. */
+  indent?: number;
+  /** Bullet config: `false` emits `a:buNone`; an object configures a char/number bullet. Unset keeps the level default. */
+  bullet?: boolean | MasterBulletProps;
+}
+/**
+ * Per-level slide-master text styles, written to `slideMaster1.xml`'s `<p:txStyles>`.
+ * Because a deck has a single shared slide master, these styles are **deck-wide**: when set on more
+ * than one `defineSlideMaster()` call the last value for each group (`title`/`body`/`other`) wins.
+ */
+interface MasterTextStyleProps {
+  /** Title placeholder style (`p:titleStyle`, single level). */
+  title?: MasterTextStyleLevel;
+  /** Body placeholder per-level styles (`p:bodyStyle`, levels 1–9; index 0 is `lvl1`). */
+  body?: MasterTextStyleLevel[];
+  /** Other/default placeholder per-level styles (`p:otherStyle`, levels 1–9). */
+  other?: MasterTextStyleLevel[];
+}
+interface SlideMasterProps {
+  /**
+   * Unique name for this master
+   */
+  title: string;
+  background?: BackgroundProps;
+  margin?: Margin;
+  slideNumber?: SlideNumberProps;
+  objects?: SlideMasterObject[];
+  /**
+   * Per-level master text styles (title / body / other) written to the shared slide master's
+   * `<p:txStyles>`. Configure nested bullet character, font size, color, alignment, and indent
+   * for each of the nine list levels. Deck-wide (see {@link MasterTextStyleProps}).
+   * @example textStyles: { body: [{ fontSize: 24, color: 'C00000', bullet: { characterCode: '25AA' } }] }
+   */
+  textStyles?: MasterTextStyleProps;
+}
+//#endregion
+//#region src/types/slide.d.ts
+/**
+ * A child object that can be placed inside a group via `slide.addGroup()`.
+ *
+ * Uses the same key-tagged descriptor shape as `SlideMasterObject`, but limited to the
+ * object types `addGroup` supports. A `group` child nests another group (an identity child
+ * coordinate space is kept at every depth, so descendants keep their slide-absolute
+ * coordinates). Charts, media, tables, and placeholders are intentionally excluded (see
+ * `addGroup`); passing one logs a warning and skips it.
+ */
+type GroupChildProps = {
+  image: ImageProps;
+} | {
+  line: ShapeProps;
+} | {
+  rect: ShapeProps;
+} | {
+  roundRect: ShapeProps;
+} | {
+  shape: {
+    type: SHAPE_NAME;
+    options?: ShapeProps;
+  };
+} | {
+  text: {
+    text: string | number | TextProps[];
+    options?: TextPropsOptions;
+  };
+} | {
+  group: {
+    children: GroupChildProps[];
+    options?: GroupProps;
+  };
+};
+/**
+ * Options for `slide.addGroup()`.
+ *
+ * The group keeps an identity child coordinate space (`chOff/chExt == off/ext`) at every depth:
+ * children — including nested groups — keep their slide-absolute `x/y/w/h`. A consequence worth
+ * knowing: a group's own frame never moves or scales its children, it only places the selection
+ * handle and the rotate pivot.
+ *
+ * The frame is all-or-nothing. Pass all four of `x/y/w/h` to set it explicitly, or none to have it
+ * auto-computed as the bounding box of the children. A partial frame is ambiguous, so it warns and
+ * falls back to auto-bounds on every axis.
+ */
+interface GroupProps extends PositionProps, ObjectNameProps {
+  /** Rotation in degrees (applied to the whole group) */
+  rotate?: number;
+  /** Flip the group horizontally */
+  flipH?: boolean;
+  /** Flip the group vertically */
+  flipV?: boolean;
+}
+interface ObjectOptions extends ImageBaseProps, PositionProps, ShapeProps, TableCellProps, TextPropsOptions {
+  _placeholderIdx?: number;
+  _placeholderType?: PLACEHOLDER_TYPE;
+  /** Connector adjust-guide values (OOXML 1000ths-of-a-percent), one per bend; emitted as `<a:gd name="adjN">` */
+  _connectorAdj?: number[];
+  /** Connector start-point binding: target shape `objectName` (raw, as the caller spelled it) + connection-site index; resolved to `<a:stCxn>` at serialize time */
+  _startCxn?: {
+    name: string;
+    idx: number;
+  };
+  /** Connector end-point binding: target shape `objectName` (raw, as the caller spelled it) + connection-site index; resolved to `<a:endCxn>` at serialize time */
+  _endCxn?: {
+    name: string;
+    idx: number;
+  };
+  /**
+   * Image: which dimensions were omitted by the user and should be derived from the image's
+   * natural pixel size at serialize time. Path-based images can't be measured synchronously in
+   * `addImage()` (bytes are loaded async during export), so the missing extent is backfilled
+   * once `_relsMedia[].data` is populated. `{ w, h }` true means "derive this side from the
+   * natural ratio". Base64 `data` images are measured eagerly in `addImage()` and never set this.
+   */
+  _szAuto?: {
+    w: boolean;
+    h: boolean;
+  };
+  cx?: Coord;
+  cy?: Coord;
+  margin?: Margin;
+  colW?: number | number[];
+  rowH?: number | number[];
+  hasHeader?: boolean;
+  hasFooter?: boolean;
+  hasBandedRows?: boolean;
+  hasBandedColumns?: boolean;
+  hasFirstColumn?: boolean;
+  hasLastColumn?: boolean;
+  rtl?: boolean;
+  tableStyle?: TableStyle | string;
+}
+interface SlideLayout {
+  background?: BackgroundProps;
+}
+interface Slide {
+  addChart(data: OptsChartData[], options: ChartOpts & {
+    type: CHART_NAME;
+  }): Slide;
+  addChart(charts: ChartMulti[], options?: ChartOpts): Slide;
+  addConnector: (options: ConnectorProps) => Slide;
+  addImage: (options: ImageProps) => Slide;
+  addMedia: (options: MediaProps) => Slide;
+  /** Embed an OLE object (Insert ▸ Object) whose bytes travel inside the `.pptx`. */
+  addOleObject: (options: OleObjectProps) => Slide;
+  addComment: (options: CommentProps) => Slide;
+  addNotes: (notes: string | NotesProps | NotesProps[]) => Slide;
+  addShape: (shapeName: SHAPE_NAME, options?: ShapeProps) => Slide;
+  addTable: (tableRows: TableRow[], options?: TableProps) => Slide;
+  addText: (text: string | number | TextProps[], options?: TextPropsOptions) => Slide;
+  addAnimation: (options: AnimationProps) => Slide;
+  /** Group child object descriptors into a single PowerPoint group (`<p:grpSp>`). */
+  addGroup: (children: GroupChildProps[], options?: GroupProps) => Slide;
+  /** Group objects already on this slide, addressed by their `objectName`, into a single group. */
+  groupObjects: (objectNames: string[], options?: GroupProps) => Slide;
+  readonly newAutoPagedSlides?: Slide[];
+  /**
+   * Slide-show transition played when advancing to this slide (`p:transition`).
+   * @example slide.transition = { type: 'fade', durationMs: 1500 }
+   */
+  transition?: TransitionProps;
+  /**
+   * Slide width in inches, resolved from the active presentation layout.
+   * Use for coordinate math instead of hard-coding layout dimensions.
+   * @example slide.addText('Centered', { x: 0, w: slide.width, align: 'center' })
+   */
+  readonly width?: number;
+  /**
+   * Slide height in inches, resolved from the active presentation layout.
+   */
+  readonly height?: number;
+  /**
+   * Background color or image (`color` | `path` | `data`)
+   * @example { color: 'FF3399' } - hex color
+   * @example { color: 'FF3399', transparency:50 } - hex color with 50% transparency
+   * @example { path: 'https://onedrives.com/myimg.png` } - retrieve image via URL
+   * @example { path: '/home/user/images/myimg.png` } - retrieve image via local path
+   * @example { data: 'image/png;base64,iVtDaDrF[...]=' } - base64 string
+   */
+  background?: BackgroundProps;
+  /**
+   * Default text color (hex format)
+   * @example 'FF3399'
+   * @default '000000' (DEF_FONT_COLOR)
+   */
+  color?: HexColor;
+  /**
+   * Whether slide is hidden
+   * @default false
+   */
+  hidden?: boolean;
+  /**
+   * Slide number options
+   */
+  slideNumber?: SlideNumberProps;
+}
+interface AddSlideProps {
+  /** Title of the slide master to use for the new slide (the `title` passed to {@link SlideMasterProps} via `defineSlideMaster`). */
+  masterTitle?: string;
+  sectionTitle?: string;
+}
+//#endregion
+export { LinearGradientFillProps as $, CommentProps as $t, ImageBaseProps as A, ChartPropsChartBar as At, ShapeGuide as B, ChartPropsChartWaterfall as Bt, TableRow as C, ChartLineDash as Ct, TableToSlidesDocument as D, ChartPropsAxisSer as Dt, TableStyleRegionProps as E, ChartPropsAxisCat as Et, ShapeAdjustHandle as F, ChartPropsChartPie as Ft, DataOrPathProps as G, ChartPropsTitle as Gt, BackgroundProps as H, ChartPropsDataTable as Ht, ShapeAdjustHandlePolar as I, ChartPropsChartRadar as It, GradientFillProps as J, OptsChartData as Jt, DataOrPathRequiredProps as K, ChartSeriesOpts as Kt, ShapeAdjustHandleXY as L, ChartPropsChartRegionMap as Lt, MediaProps as M, ChartPropsChartDoughnut as Mt, MediaType as N, ChartPropsChartHistogram as Nt, TableToSlidesElement as O, ChartPropsAxisVal as Ot, OleObjectProps as P, ChartPropsChartLine as Pt, ImageFillProps as Q, PlaceholderProps as Qt, ShapeAdjustValue as R, ChartPropsChartStock as Rt, TableProps as S, ChartExStatistics as St, TableStyleProps as T, ChartOpts as Tt, Color as U, ChartPropsFillLine as Ut, ShapeProps as V, ChartPropsDataLabel as Vt, Coord as W, ChartPropsLegend as Wt, HAlign as X, ObjectLockProps as Xt, GradientStopProps as Y, OptsChartGridLine as Yt, HexColor as Z, ObjectNameProps as Zt, TransitionProps as _, ChartAxisTickMark as _t, Slide as a, SlideComment as an, TextVertType as at, TableCell as b, ChartExBinning as bt, MasterTextStyleLevel as c, TextBaseProps as cn, BorderProps as ct, SlideMasterObject as d, TextMeasurement as dn, HyperlinkActionJump as dt, MeasureTextOptions as en, Margin as et, SlideMasterProps as f, TextProps as fn, HyperlinkProps as ft, PresetEffect as g, ChartAreaProps as gt, AnimationTrigger as h, textRuns as hn, ShapeLineProps as ht, ObjectOptions as i, ResolvedCommentAuthor as in, RadialGradientFillProps as it, ImageProps as j, ChartPropsChartBoxWhisker as jt, TableToSlidesProps as k, ChartPropsBase as kt, MasterTextStyleProps as l, TextFitShrinkProps as ln, ConnectorProps as lt, AnimationProps as m, textRun as mn, ShapeFillProps as mt, GroupChildProps as n, NotesTextOptions as nn, PatternPreset as nt, SlideLayout as o, TableCellLayout as on, ThemeColor as ot, SlideNumberProps as p, TextPropsOptions as pn, ShadowProps as pt, GeometryPoint as q, LineCap as qt, GroupProps as r, OverflowBoxOptions as rn, PositionProps as rt, MasterBulletProps as s, TableLayoutResult as sn, VAlign as st, AddSlideProps as t, NotesProps as tn, PatternFillProps as tt, SlideMasterChartProps as u, TextGlowProps as un, ConnectorType as ut, TransitionSoundProps as v, ChartDataPointStyle as vt, TableRowSlide as w, ChartMulti as wt, TableCellProps as x, ChartExGeography as xt, TransitionType as y, ChartErrorBarOptions as yt, ShapeConnectionSite as z, ChartPropsChartSurface as zt };
+//# sourceMappingURL=slide-B6mDaM-P.d.ts.map