@shbernal/ts-pptx 3.5.0 → 3.7.0

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

@@ -174,342 +174,695 @@ interface ShapeProps extends PositionProps, ObjectNameProps {
   shadow?: ShadowProps;
 }
 //#endregion
-//#region src/types/text.d.ts
-interface TextBaseProps {
+//#region src/types/media.d.ts
+type MediaType = 'audio' | 'online' | 'video';
+interface ImageBaseProps extends PositionProps, ObjectNameProps {
   /**
-   * Horizontal alignment
-   *
-   * When a shape's text is an array of runs, set this on **every run** of a paragraph.
-   * {@link breakLine} is not the only paragraph boundary: two adjacent runs whose `align`
-   * differs start a new one, so stating it on the opening run alone splits the paragraph in
-   * two. That is the mirror of {@link bullet}, {@link paraMarginLeft} and {@link paraIndent},
-   * which are read from the opening run only. Neither mistake changes the run count — the
-   * only symptom is a differently shaped paragraph, with no error.
-   * @default 'left'
+   * 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 —
+   *   for an SVG too, from its `width`/`height` or `viewBox`.
+   * - A `path` image is measured at export time (its bytes are not available synchronously);
+   *   an omitted dimension falls back to 1 inch if it stays unmeasurable.
+   * - An SVG with *neither* dimension given also falls back to 1 inch: its user units carry a
+   *   dependable aspect ratio but only a conventional magnitude, so a 24-unit icon is not
+   *   treated as a quarter-inch object.
+   * - A vector source placed in a box whose ratio differs from its own is letterboxed, not
+   *   stretched; see {@link sizing} to override.
    */
-  align?: HAlign;
   /**
-   * Bold style
-   * @default false
+   * 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..."
    */
-  bold?: boolean;
+  altText?: string;
   /**
-   * Add a line-break
+   * Flip horizontally?
    * @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;
+  flipH?: boolean;
   /**
-   * Add standard or custom bullet
-   * - use `true` for standard bullet
-   * - pass object options for custom bullet
-   * - `false` (and omitting the option) is the *explicit off*: it writes `<a:buNone/>`
-   *   plus `marL="0" indent="0"`, which overrides whatever bullet the layout's or
-   *   master's list style sets for this level
-   * - `'inherit'` states nothing at all — no bullet child and no margin attributes — so
-   *   the list style keeps reaching the paragraph. This is the one state omission
-   *   cannot spell, because omitting the option means `false` here for compatibility
-   *
-   * The margins are only a *default* of the bullet state: {@link paraMarginLeft} and
-   * {@link paraIndent} state `@marL`/`@indent` independently in any of the three, including
-   * an inherited margin under a drawn bullet.
-   *
-   * When a shape's text is an array of runs, state this on the **opening run only**. A run
-   * that draws a bullet starts a new paragraph by itself, so repeating it — the placement
-   * that {@link align} requires — turns one three-run paragraph into three one-run
-   * paragraphs. A paragraph takes its properties from its first run.
+   * Flip vertical?
    * @default false
    */
-  bullet?: boolean | 'inherit' | {
-    /**
-     * Bullet type
-     * @default bullet
-     */
-    type?: 'bullet' | 'number';
-    /**
-     * Bullet character code (unicode)
-     * @example '25BA' // 'BLACK RIGHT-POINTING POINTER' (U+25BA)
-     */
-    characterCode?: string;
-    /**
-     * Bullet glyph font typeface (`<a:buFont/>`), e.g. for symbol-font bullets
-     * @example 'Wingdings' // render `characterCode` using the Wingdings font
-     */
-    fontFace?: string;
-    /**
-     * Bullet glyph size as a percentage of the run's text size (25–400)
-     * @default 100
-     * @example 80 // bullet glyph is 80% of the text size
-     */
-    size?: number;
-    /**
-     * Indentation (space between bullet and text) (points)
-     * @default 27 // DEF_BULLET_MARGIN
-     * @example 10 // Indents text 10 points from bullet
-     */
-    indent?: number;
-    /**
-     * Number type
-     * @example 'romanLcParenR' // roman numerals lower-case with paranthesis right
-     */
-    numberType?: 'alphaLcParenBoth' | 'alphaLcParenR' | 'alphaLcPeriod' | 'alphaUcParenBoth' | 'alphaUcParenR' | 'alphaUcPeriod' | 'arabicParenBoth' | 'arabicParenR' | 'arabicPeriod' | 'arabicPlain' | 'romanLcParenBoth' | 'romanLcParenR' | 'romanLcPeriod' | 'romanUcParenBoth' | 'romanUcParenR' | 'romanUcPeriod';
-    /**
-     * Number bullets start at
-     * @default 1
-     * @example 10 // numbered bullets start with 10
-     */
-    numberStartAt?: number;
-    /**
-     * Image to use as the bullet glyph ("picture bullet", `<a:buBlip>`)
-     * - supply an image `path` (filesystem/URL) or base64 `data` (same forms as `addImage()`)
-     * - raster formats (PNG/JPG/GIF) and SVG are supported; use `size` to scale relative to the text height
-     * - SVG bullets embed a PNG preview plus the SVG (the same dual-rel handling as `addImage()`)
-     * - takes precedence over `type`/`characterCode` when set
-     * @example image: { path: 'images/star.png' }
-     * @example image: { data: 'image/png;base64,iVBOR...' }
-     * @example image: { path: 'images/star.svg' }
-     */
-    image?: {
-      path?: string;
-      data?: string;
-    };
-    /**
-     * Relationship id assigned to a picture-bullet image (`<a:blip r:embed>`)
-     * - for SVG bullets this is the PNG-preview rel; the SVG rel is `_rIdSvg`
-     * @internal populated by `addText()`; do not set directly
-     */
-    _rId?: number;
-    /**
-     * Relationship id of the SVG image for an SVG picture bullet (`<asvg:svgBlip r:embed>`)
-     * @internal populated by `addText()`; do not set directly
-     */
-    _rIdSvg?: number;
-    /**
-     * Bullet glyph color (separate from the text run color)
-     * @example 'FF0000' // red bullet
-     */
-    color?: HexColor;
-  };
+  flipV?: boolean;
+  hyperlink?: HyperlinkProps;
   /**
-   * Text capitalization (`a:rPr/@cap`, `ST_TextCapsType`)
-   * - `'all'` = ALL CAPS
-   * - `'small'` = Small Caps
-   * - `'none'` = the *explicit off*: it writes `cap="none"`, which overrides a capitalization
-   *   the run would otherwise inherit. Omitting the option states nothing and lets that
-   *   inheritance stand
-   * - PowerPoint: Font > Effects > All Caps / Small Caps
-   * @default (unset) inherit
+   * 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
    */
-  caps?: 'none' | 'small' | 'all';
+  line?: ShapeLineProps;
   /**
-   * 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)
+   * 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
    */
-  color?: Color;
+  placeholder?: string;
   /**
-   * 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
+   * Image rotation (degrees)
+   * - range: -360 to 360
+   * @default 0
+   * @example 180 // rotate image 180 degrees
    */
-  fontFace?: string;
+  rotate?: number;
   /**
-   * 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
+   * Enable image rounding (clips the image to a circle/ellipse)
+   * - shorthand for `shape: 'ellipse'`; `shape` takes precedence when both are set
+   * @default false
    */
-  fontFaceEA?: string;
+  rounding?: boolean;
   /**
-   * Font size
-   * @example 12 // Font size 12
+   * 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
    */
-  fontSize?: number;
+  shape?: SHAPE_NAME;
   /**
-   * Text highlight color (hex format)
-   * @example 'FFFF00' // yellow
+   * 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
    */
-  highlight?: HexColor;
+  points?: GeometryPoint[];
   /**
-   * italic style
-   * @default false
+   * Rounded rectangle corner radius (inches) when `shape: 'roundRect'`
+   * - values: 0.0 to 1.0
+   * @default 0
    */
-  italic?: boolean;
+  rectRadius?: number;
   /**
-   * language
-   * - ISO 639-1 standard language code
-   * @default 'en-US' // english US
-   * @example 'fr-CA' // french Canadian
+   * 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 }
    */
-  lang?: string;
+  shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
   /**
-   * First-line indent (points) — `a:pPr/@indent`, the offset of the paragraph's FIRST line
-   * from {@link paraMarginLeft}. Negative hangs the first line to the left of the body, which
-   * is what a bulleted paragraph does; positive indents it to the right, the "first line
-   * indented" prose form. PowerPoint: Paragraph > Indentation > Special.
-   * - `'inherit'` writes no `@indent` at all, so the paragraph takes whatever its list style
-   *   (`a:lstStyle` → placeholder → layout → master) sets — the same third state
-   *   {@link bullet} spells, on the attribute beside it
-   * - omitting the option keeps the bullet-derived default: a drawn bullet hangs the first
-   *   line by its margin, `bullet: false` writes `indent="0"`, `bullet: 'inherit'` writes
-   *   nothing
-   * - a value here overrides all of those, in every bullet state
-   * @example -18 // hang the first line 18pt left of the body text
-   * @example 18 // indent the first line 18pt, prose style
-   * @example 'inherit' // keep the list style's indent, even on a bulleted paragraph
-   * @remarks Read from the **opening run** of a paragraph, like {@link bullet} and unlike
-   * {@link align}; a value on a continuation run is ignored.
+   * Shadow Props
+   * - MS-PPT > Format Picture > Shadow
+   * @example
+   * { type: 'outer', color: '000000', transparency: 50, blur: 20,  offset: 20, angle: 270 }
    */
-  paraIndent?: number | 'inherit';
+  shadow?: ShadowProps;
   /**
-   * Left margin of the paragraph (points) — `a:pPr/@marL`, where the paragraph's body text
-   * starts. This is the paragraph's own margin, not the text frame's internal padding
-   * (`margin`) and not the discrete outline level (`indentLevel`, which writes `a:p/@lvl`).
-   * PowerPoint: Paragraph > Indentation > Before text.
-   * - `'inherit'` writes no `@marL` at all, so the paragraph takes whatever its list style
-   *   (`a:lstStyle` → placeholder → layout → master) sets — the third state that omission
-   *   cannot spell, since omitting it writes the bullet-derived default
-   * - omitting the option keeps that default: a drawn bullet writes its own margin (see
-   *   `bullet.indent`), `bullet: false` writes `marL="0"`, `bullet: 'inherit'` writes nothing
-   * - a value here overrides all of those, in every bullet state
-   * @example 36 // body text starts 36pt (0.5in) from the frame's text edge
-   * @example 'inherit' // keep the list style's margin, even on a bulleted paragraph
-   * @remarks Read from the **opening run** of a paragraph, like {@link bullet} and unlike
-   * {@link align}; a value on a continuation run is ignored.
-   */
-  paraMarginLeft?: number | 'inherit';
-  /**
-   * 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
+   * 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
    */
-  tabStops?: Array<{
-    position: number;
-    alignment?: 'l' | 'r' | 'ctr' | 'dec';
-  }>;
+  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;
+  };
   /**
-   * text direction
-   * `horz` = horizontal
-   * `vert` = rotate 90^
-   * `vert270` = rotate 270^
-   * `wordArtVert` = stacked
-   * @default 'horz'
+   * Image sizing options
+   * - omit entirely for the default: a raster fills the `w`×`h` box, a vector (SVG) source is
+   *   letterboxed to its own aspect ratio inside that box
    */
-  textDirection?: 'horz' | 'vert' | 'vert270' | 'wordArtVert';
+  sizing?: {
+    /**
+     * Sizing type
+     * - `cover` / `contain` fit the image into the `w`×`h` box using the image's *natural*
+     *   aspect ratio — read from the embedded PNG/JPEG/GIF/BMP/WebP header, or from an SVG's
+     *   `width`/`height` or `viewBox`. If the natural size cannot be determined (an
+     *   unrecognized format, or an SVG carrying neither) the displayed `w`/`h` ratio is used
+     *   as a fallback and a warning is logged.
+     * - `crop` cuts a window out of the displayed image using the `x`/`y`/`w`/`h` offsets.
+     * - `stretch` fills the box regardless of aspect ratio. This is what a raster does
+     *   anyway; name it explicitly to opt a vector source out of its aspect-correct default.
+     */
+    type: 'contain' | 'cover' | 'crop' | 'stretch';
+    /**
+     * Image width
+     * - inches or percentage
+     * - defaults to the picture's own `w`, which is what `cover`/`contain` almost always want
+     * @example 10.25 // position in inches
+     * @example '75%' // position as percentage of slide size
+     */
+    w?: Coord;
+    /**
+     * Image height
+     * - inches or percentage
+     * - defaults to the picture's own `h`
+     * @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 Shape > Text Options > Text Fill & Outline > Text Fill > Transparency
+   * - MS-PPT > Format Picture > Picture > Picture Transparency > Transparency
    * - range: 0-100
    * @default 0
+   * @example 25 // 25% transparent
    */
   transparency?: number;
   /**
-   * underline properties
-   * - PowerPoint: Font > Color & Underline > Underline Style/Underline Color
-   * - `style` is the full `ST_TextUnderlineType` enumeration (ECMA-376 §20.1.10.81)
-   * - `'none'` is the *explicit off*: it writes `a:rPr/@u="none"`, which overrides an
-   *   underline the run would otherwise inherit from its list style, placeholder, layout or
-   *   master. Omitting the option instead states nothing and lets that inheritance stand —
-   *   the two are different facts, not two spellings of one.
-   * @default (unset) inherit
+   * 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
    */
-  underline?: {
-    style?: 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dbl' | 'dotDash' | 'dotDashHeavy' | 'dotDotDash' | 'dotDotDashHeavy' | 'dotted' | 'dottedHeavy' | 'heavy' | 'none' | 'sng' | 'wavy' | 'wavyDbl' | 'wavyHeavy' | 'words';
-    color?: Color;
+  duotone?: {
+    /** Color mapped to the image's dark/shadow tones. */
+    shadow: Color;
+    /** Color mapped to the image's light/highlight tones. */
+    highlight: Color;
   };
   /**
-   * vertical alignment
-   * @default 'top'
+   * 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
    */
-  valign?: VAlign;
-}
-interface TextGlowProps {
+  grayscale?: boolean;
   /**
-   * Border color (hex format)
-   * @example 'FF3399'
+   * 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
    */
-  color?: HexColor;
+  biLevel?: {
+    /** Luminance split point as a `0.0–1.0` fraction (serialized to `thresh`, the 0–1 fraction ×100000). */
+    threshold: number;
+  };
   /**
-   * opacity (0.0 - 1.0)
-   * @example 0.5
-   * 50% opaque
+   * 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
    */
-  opacity?: number;
+  clrChange?: {
+    /** Source color to replace (`<a:clrFrom>`). */
+    from: Color;
+    /** Replacement color (`<a:clrTo>`). */
+    to: Color;
+  };
   /**
-   * size (points)
+   * 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>'
    */
-  size: number;
+  svg?: string;
 }
-interface TextFitShrinkProps {
+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 {
   /**
-   * Shrink text on overflow (`<a:normAutofit>`)
+   * Cover image
+   * @default "play button" image, gray background
    */
-  type: 'shrink';
+  cover?: string;
   /**
-   * 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%)
+   * media file extension
+   * - use when the media file path does not already have an extension, ex: "/folder/SomeSong"
+   * @default extension from file provided
    */
-  fontScale?: number;
+  extn?: string;
   /**
-   * 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%)
+   * 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
    */
-  lnSpcReduction?: number;
+  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;
 }
-interface TextPropsOptions extends PositionProps, DataOrPathProps, TextBaseProps, ObjectNameProps {
+/**
+ * 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 {
   /**
-   * Preset-geometry start/end angles for text frames (`shape` + these build `<a:prstGeom>`
-   * adjustment guides through the shared emitter — `genXmlPresetGeom` reads them whether
-   * the object is a shape or a styled text frame).
+   * 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' }
    */
-  angleRange?: [number, number];
-  /** Preset-geometry block-arc thickness for text frames. */
-  arcThicknessRatio?: number;
-  /** Custom geometry points when a text frame uses a custom geometry shape. */
-  points?: GeometryPoint[];
-  /** Preset-geometry adjustment guides for text frames. */
-  shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
-  _bodyProp?: {
-    align?: AlignH;
-    anchor?: TextAnchor;
-    lIns?: number;
-    rIns?: number;
-    tIns?: number;
-    bIns?: number;
-    numCol?: number;
-    spcCol?: number;
-    vert?: TextVertType;
-    wrap?: boolean;
-    prstTxWarp?: string;
+  cover?: {
+    path?: string;
+    data?: string;
   };
-  _lineIdx?: number;
-  baseline?: number;
   /**
-   * Character spacing
+   * 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/text.d.ts
+interface TextBaseProps {
+  /**
+   * Horizontal alignment
+   *
+   * When a shape's text is an array of runs, set this on **every run** of a paragraph.
+   * {@link breakLine} is not the only paragraph boundary: two adjacent runs whose `align`
+   * differs start a new one, so stating it on the opening run alone splits the paragraph in
+   * two. That is the mirror of {@link bullet}, {@link paraMarginLeft} and {@link paraIndent},
+   * which are read from the opening run only. Neither mistake changes the run count — the
+   * only symptom is a differently shaped paragraph, with no error.
+   * @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
+   * - `false` (and omitting the option) is the *explicit off*: it writes `<a:buNone/>`
+   *   plus `marL="0" indent="0"`, which overrides whatever bullet the layout's or
+   *   master's list style sets for this level
+   * - `'inherit'` states nothing at all — no bullet child and no margin attributes — so
+   *   the list style keeps reaching the paragraph. This is the one state omission
+   *   cannot spell, because omitting the option means `false` here for compatibility
+   *
+   * The margins are only a *default* of the bullet state: {@link paraMarginLeft} and
+   * {@link paraIndent} state `@marL`/`@indent` independently in any of the three, including
+   * an inherited margin under a drawn bullet.
+   *
+   * When a shape's text is an array of runs, state this on the **opening run only**. A run
+   * that draws a bullet starts a new paragraph by itself, so repeating it — the placement
+   * that {@link align} requires — turns one three-run paragraph into three one-run
+   * paragraphs. A paragraph takes its properties from its first run.
+   * @default false
+   */
+  bullet?: boolean | 'inherit' | {
+    /**
+     * Bullet type
+     * @default bullet
+     */
+    type?: 'bullet' | 'number';
+    /**
+     * Bullet character code (unicode)
+     * @example '25BA' // 'BLACK RIGHT-POINTING POINTER' (U+25BA)
+     */
+    characterCode?: string;
+    /**
+     * Bullet glyph font typeface (`<a:buFont/>`), e.g. for symbol-font bullets
+     * @example 'Wingdings' // render `characterCode` using the Wingdings font
+     */
+    fontFace?: string;
+    /**
+     * Bullet glyph size as a percentage of the run's text size (25–400)
+     * @default 100
+     * @example 80 // bullet glyph is 80% of the text size
+     */
+    size?: number;
+    /**
+     * Indentation (space between bullet and text) (points)
+     * @default 27 // DEF_BULLET_MARGIN
+     * @example 10 // Indents text 10 points from bullet
+     */
+    indent?: number;
+    /**
+     * Number type
+     * @example 'romanLcParenR' // roman numerals lower-case with paranthesis right
+     */
+    numberType?: 'alphaLcParenBoth' | 'alphaLcParenR' | 'alphaLcPeriod' | 'alphaUcParenBoth' | 'alphaUcParenR' | 'alphaUcPeriod' | 'arabicParenBoth' | 'arabicParenR' | 'arabicPeriod' | 'arabicPlain' | 'romanLcParenBoth' | 'romanLcParenR' | 'romanLcPeriod' | 'romanUcParenBoth' | 'romanUcParenR' | 'romanUcPeriod';
+    /**
+     * Number bullets start at
+     * @default 1
+     * @example 10 // numbered bullets start with 10
+     */
+    numberStartAt?: number;
+    /**
+     * Image to use as the bullet glyph ("picture bullet", `<a:buBlip>`)
+     * - supply an image `path` (filesystem/URL) or base64 `data` (same forms as `addImage()`)
+     * - raster formats (PNG/JPG/GIF) and SVG are supported; use `size` to scale relative to the text height
+     * - SVG bullets embed a PNG preview plus the SVG (the same dual-rel handling as `addImage()`)
+     * - takes precedence over `type`/`characterCode` when set
+     * @example image: { path: 'images/star.png' }
+     * @example image: { data: 'image/png;base64,iVBOR...' }
+     * @example image: { path: 'images/star.svg' }
+     */
+    image?: {
+      path?: string;
+      data?: string;
+    };
+    /**
+     * Relationship id assigned to a picture-bullet image (`<a:blip r:embed>`)
+     * - for SVG bullets this is the PNG-preview rel; the SVG rel is `_rIdSvg`
+     * @internal populated by `addText()`; do not set directly
+     */
+    _rId?: number;
+    /**
+     * Relationship id of the SVG image for an SVG picture bullet (`<asvg:svgBlip r:embed>`)
+     * @internal populated by `addText()`; do not set directly
+     */
+    _rIdSvg?: number;
+    /**
+     * Bullet glyph color (separate from the text run color)
+     * @example 'FF0000' // red bullet
+     */
+    color?: HexColor;
+  };
+  /**
+   * Text capitalization (`a:rPr/@cap`, `ST_TextCapsType`)
+   * - `'all'` = ALL CAPS
+   * - `'small'` = Small Caps
+   * - `'none'` = the *explicit off*: it writes `cap="none"`, which overrides a capitalization
+   *   the run would otherwise inherit. Omitting the option states nothing and lets that
+   *   inheritance stand
+   * - PowerPoint: Font > Effects > All Caps / Small Caps
+   * @default (unset) inherit
+   */
+  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;
+  /**
+   * First-line indent (points) — `a:pPr/@indent`, the offset of the paragraph's FIRST line
+   * from {@link paraMarginLeft}. Negative hangs the first line to the left of the body, which
+   * is what a bulleted paragraph does; positive indents it to the right, the "first line
+   * indented" prose form. PowerPoint: Paragraph > Indentation > Special.
+   * - `'inherit'` writes no `@indent` at all, so the paragraph takes whatever its list style
+   *   (`a:lstStyle` → placeholder → layout → master) sets — the same third state
+   *   {@link bullet} spells, on the attribute beside it
+   * - omitting the option keeps the bullet-derived default: a drawn bullet hangs the first
+   *   line by its margin, `bullet: false` writes `indent="0"`, `bullet: 'inherit'` writes
+   *   nothing
+   * - a value here overrides all of those, in every bullet state
+   * @example -18 // hang the first line 18pt left of the body text
+   * @example 18 // indent the first line 18pt, prose style
+   * @example 'inherit' // keep the list style's indent, even on a bulleted paragraph
+   * @remarks Read from the **opening run** of a paragraph, like {@link bullet} and unlike
+   * {@link align}; a value on a continuation run is ignored.
+   */
+  paraIndent?: number | 'inherit';
+  /**
+   * Left margin of the paragraph (points) — `a:pPr/@marL`, where the paragraph's body text
+   * starts. This is the paragraph's own margin, not the text frame's internal padding
+   * (`margin`) and not the discrete outline level (`indentLevel`, which writes `a:p/@lvl`).
+   * PowerPoint: Paragraph > Indentation > Before text.
+   * - `'inherit'` writes no `@marL` at all, so the paragraph takes whatever its list style
+   *   (`a:lstStyle` → placeholder → layout → master) sets — the third state that omission
+   *   cannot spell, since omitting it writes the bullet-derived default
+   * - omitting the option keeps that default: a drawn bullet writes its own margin (see
+   *   `bullet.indent`), `bullet: false` writes `marL="0"`, `bullet: 'inherit'` writes nothing
+   * - a value here overrides all of those, in every bullet state
+   * @example 36 // body text starts 36pt (0.5in) from the frame's text edge
+   * @example 'inherit' // keep the list style's margin, even on a bulleted paragraph
+   * @remarks Read from the **opening run** of a paragraph, like {@link bullet} and unlike
+   * {@link align}; a value on a continuation run is ignored.
+   */
+  paraMarginLeft?: number | 'inherit';
+  /**
+   * 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
+   * - `style` is the full `ST_TextUnderlineType` enumeration (ECMA-376 §20.1.10.81)
+   * - `'none'` is the *explicit off*: it writes `a:rPr/@u="none"`, which overrides an
+   *   underline the run would otherwise inherit from its list style, placeholder, layout or
+   *   master. Omitting the option instead states nothing and lets that inheritance stand —
+   *   the two are different facts, not two spellings of one.
+   * @default (unset) inherit
+   */
+  underline?: {
+    style?: 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dbl' | 'dotDash' | 'dotDashHeavy' | 'dotDotDash' | 'dotDotDashHeavy' | 'dotted' | 'dottedHeavy' | 'heavy' | 'none' | 'sng' | 'wavy' | 'wavyDbl' | 'wavyHeavy' | 'words';
+    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 {
+  /**
+   * Preset-geometry start/end angles for text frames (`shape` + these build `<a:prstGeom>`
+   * adjustment guides through the shared emitter — `genXmlPresetGeom` reads them whether
+   * the object is a shape or a styled text frame).
+   */
+  angleRange?: [number, number];
+  /** Preset-geometry block-arc thickness for text frames. */
+  arcThicknessRatio?: number;
+  /** Custom geometry points when a text frame uses a custom geometry shape. */
+  points?: GeometryPoint[];
+  /** Preset-geometry adjustment guides for text frames. */
+  shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
+  _bodyProp?: {
+    align?: AlignH;
+    anchor?: TextAnchor;
+    lIns?: number;
+    rIns?: number;
+    tIns?: number;
+    bIns?: number;
+    numCol?: number;
+    spcCol?: number;
+    vert?: TextVertType;
+    wrap?: boolean;
+    prstTxWarp?: string;
+  };
+  _lineIdx?: number;
+  baseline?: number;
+  /**
+   * Character spacing
    */
   charSpacing?: number;
   /**
@@ -965,6 +1318,47 @@ interface ObjectLockProps {
   /** Disallow drilling down into the graphical object (e.g. chart data). (tables) */
   noDrilldown?: boolean;
 }
+/**
+ * The object descriptors a slide master and a group child both accept.
+ *
+ * Both surfaces take a key-tagged descriptor — one key naming the object kind, its value the
+ * options for that kind — and both accepted the same six. They were written out twice, and the
+ * doc on `GroupChildProps` said as much in as many words: "Uses the same key-tagged descriptor
+ * shape as `SlideMasterObject`". That coupling was real and maintained by hand, which meant a
+ * seventh descriptor added to one was silently missing from the other.
+ *
+ * Each union is now this plus what is genuinely its own — a master adds `chart` and
+ * `placeholder`, a group child adds `group` — so the difference between them is the part you
+ * read, and the shared vocabulary is stated once.
+ */
+type CommonObjectDescriptor = {
+  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, …).
+ *
+ * A union member's comment cannot carry block tags, so this stands in for `@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;
+  };
+};
 //#endregion
 //#region src/types/chart.d.ts
 type ChartAxisTickMark = 'none' | 'inside' | 'outside' | 'cross';
@@ -1840,6 +2234,26 @@ type TextVerticalType = (typeof TEXT_VERTICAL)[number];
  */
 declare const PRESET_LINE_DASHES: readonly ['solid', 'dot', 'dash', 'lgDash', 'dashDot', 'lgDashDot', 'lgDashDotDot', 'sysDash', 'sysDot', 'sysDashDot', 'sysDashDotDot'];
 type PresetLineDashVal = (typeof PRESET_LINE_DASHES)[number];
+/**
+ * The twelve theme colour slots (`a:clrScheme` children) a `p:clrMap` token can point at.
+ *
+ * Not an `ST_` type — these are element names inside `a:CT_ColorScheme`, which the schema
+ * declares as a fixed sequence rather than an enumeration. The effect is the same: a closed,
+ * ordered set of twelve names, in the order the scheme declares them.
+ * @see ECMA-376 Part 1 §20.1.6.2
+ */
+declare const THEME_COLOR_SLOTS: readonly ['dk1', 'lt1', 'dk2', 'lt2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
+type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
+/**
+ * The twelve colour-map tokens (`p:clrMap` attributes), in schema attribute order.
+ *
+ * A slide's `schemeClr val="tx1"` names a *token*, not a slot: the master's `p:clrMap` is the
+ * indirection that sends it to a {@link ThemeColorSlot}. Which is why the two lists look alike
+ * and are not the same list — `bg1`/`tx1` are tokens, `lt1`/`dk1` are slots.
+ * @see ECMA-376 Part 1 §19.3.1.6
+ */
+declare const COLOR_MAP_TOKENS: readonly ['bg1', 'tx1', 'bg2', 'tx2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
+type ColorMapToken = (typeof COLOR_MAP_TOKENS)[number];
 //#endregion
 //#region src/types/style.d.ts
 interface BorderProps {
@@ -1850,868 +2264,515 @@ interface BorderProps {
   type?: 'none' | 'dash' | 'solid';
   /**
    * Dash pattern, using the same vocabulary as {@link ShapeLineProps.dashType}.
-   *
-   * `type` is only a coarse three-way switch, so every dashed border it can express
-   * collapses onto `sysDash`. Set this to pick the exact `a:prstDash` preset instead:
-   * `dashType: 'lgDashDot'` emits `<a:prstDash val="lgDashDot"/>`.
-   *
-   * **Precedence.** When both are set, `dashType` wins over `type` for the dash pattern —
-   * `{ type: 'solid', dashType: 'sysDot' }` draws a dotted rule. The one exception is
-   * `type: 'none'`, which suppresses the border entirely and is decided before any dash
-   * pattern is chosen. An unrecognized value warns and falls back to what `type` implies.
-   * @default (derived from `type`: `sysDash` for `'dash'`, else `solid`)
-   * @example { type: 'solid', color: '999999', dashType: 'lgDash' }
-   */
-  dashType?: ShapeLineProps['dashType'];
-  /**
-   * 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
-   *
-   * `'none'` and `'inherit'` are different states, and both have to be spelled out
-   * because omitting `fill` is not one of them: the shape/text-box emitter defaults a
-   * missing `fill` to `<a:noFill/>`.
-   * - `'none'` emits `<a:noFill/>` — an explicit transparent interior.
-   * - `'inherit'` emits no fill child at all, leaving the interior to
-   *   `p:style/a:fillRef` or the placeholder. This is the only way to author that
-   *   state from `addShape`/`addText`.
-   *
-   * On a table cell (`TableCellProps.fill`) and a slide background the two spellings
-   * differ the same way, except that *omitting* the option there already means
-   * inherit, so `'inherit'` is merely the explicit form of the default.
-   * @default 'solid'
-   */
-  type?: 'none' | 'inherit' | '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.
+   *
+   * `type` is only a coarse three-way switch, so every dashed border it can express
+   * collapses onto `sysDash`. Set this to pick the exact `a:prstDash` preset instead:
+   * `dashType: 'lgDashDot'` emits `<a:prstDash val="lgDashDot"/>`.
+   *
+   * **Precedence.** When both are set, `dashType` wins over `type` for the dash pattern —
+   * `{ type: 'solid', dashType: 'sysDot' }` draws a dotted rule. The one exception is
+   * `type: 'none'`, which suppresses the border entirely and is decided before any dash
+   * pattern is chosen. An unrecognized value warns and falls back to what `type` implies.
+   * @default (derived from `type`: `sysDash` for `'dash'`, else `solid`)
+   * @example { type: 'solid', color: '999999', dashType: 'lgDash' }
    */
-  image?: ImageFillProps;
+  dashType?: ShapeLineProps['dashType'];
   /**
-   * Resolved media relationship id for an image fill, assigned at add-time.
-   * @internal
+   * Border color (hex)
+   * @example 'FF3399'
+   * @default '666666'
    */
-  _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 {
+  color?: HexColor;
   /**
-   * Line width (pt)
+   * Border width (points)
+   * - MS-PPT > Format Shape > Fill & Line > Line > Width
    * @default 1
    */
   width?: number;
   /**
-   * Dash type — the full `ST_PresetLineDashVal` set, so any dash a source deck can
-   * carry can also be authored and replicated.
-   * @default 'solid'
+   * Border transparency (percent)
+   * - MS-PPT > Format Shape > Fill & Line > Line > Transparency
+   * - range: 0-100
+   * @default 0
    */
-  dashType?: PresetLineDashVal;
+  transparency?: number;
   /**
    * 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.
+ * 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`).
  */
-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;
+type HyperlinkActionJump = 'firstslide' | 'previousslide' | 'nextslide' | 'lastslide' | 'lastslideviewed' | 'endshow';
+interface HyperlinkProps {
+  _rId?: number;
   /**
-   * 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
+   * Slide number to link to
    */
-  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;
+  slide?: number;
   /**
-   * Connection-site index on `endShape`. Ignored without `endShape`.
-   * @default 0
+   * Url to link to
    */
-  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;
+  url?: string;
   /**
-   * Line color (6-digit hex, no `#`)
-   * @default '000000'
+   * Hyperlink Tooltip
    */
-  color?: HexColor;
+  tooltip?: string;
   /**
-   * Line width (pt)
-   * @default 1
+   * 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' }
    */
-  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;
+  action?: HyperlinkActionJump;
 }
-//#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 {
+interface ShadowProps {
   /**
-   * Horizontal position
-   * - inches or percentage
-   * @example 10.25 // position in inches
-   * @example '75%' // position as percentage of slide size
+   * shadow type
+   * @default 'none'
    */
-  x?: Coord;
+  type: 'outer' | 'inner' | 'none';
   /**
-   * Vertical position
-   * - inches or percentage
-   * @example 10.25 // position in inches
-   * @example '75%' // position as percentage of slide size
+   * shadow transparency (percent)
+   * - MS-PPT > Format Shape > Effects > Shadow > Transparency
+   * - range: 0-100 (0 = fully opaque, 100 = fully transparent)
+   * @example 25 // 25% transparent
    */
-  y?: Coord;
+  transparency?: number;
   /**
-   * Height
-   * - inches or percentage
-   * @example 10.25 // height in inches
-   * @example '75%' // height as percentage of slide size
+   * blur (points)
+   * - range: 0-100
+   * @default 0
    */
-  h?: Coord;
+  blur?: number;
   /**
-   * Width
-   * - inches or percentage
-   * @example 10.25 // width in inches
-   * @example '75%' // width as percentage of slide size
+   * angle (degrees)
+   * - range: 0-359
+   * @default 0
    */
-  w?: Coord;
-}
-/**
- * Reusable optional data/path fields.
- * Use `DataOrPathRequiredProps` for APIs that require at least one source.
- */
-interface DataOrPathProps {
+  angle?: number;
   /**
-   * 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
+   * shadow offset (points)
+   * - range: 0-200
+   * @default 0
    */
-  path?: string;
+  offset?: number;
   /**
-   * base64-encoded string
-   * - Useful for avoiding potential path/server issues
-   *
-   * @example 'image/png;base64,iVtDafDrBF[...]=' // pre-encoded image in base-64
+   * shadow color (hex format)
+   * @example 'FF3399'
    */
-  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 {
+  color?: HexColor;
   /**
-   * Stop position as a percentage.
-   * - range: 0-100
+   * whether to rotate shadow with shape
+   * @default false
    */
-  position: number;
+  rotateWithShape?: boolean;
+}
+interface ShapeFillProps {
   /**
-   * Stop color.
+   * Fill color
    * - `HexColor` or `ThemeColor`
+   * @example 'FF0000' // hex color (red)
+   * @example SchemeColor.text1 // Theme color (Text1)
    */
-  color: Color;
+  color?: Color;
   /**
    * Transparency (percent)
+   * - MS-PPT > Format Shape > Fill & Line > Fill > Transparency
    * - 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.
+   * Fill type
+   *
+   * `'none'` and `'inherit'` are different states, and both have to be spelled out
+   * because omitting `fill` is not one of them: the shape/text-box emitter defaults a
+   * missing `fill` to `<a:noFill/>`.
+   * - `'none'` emits `<a:noFill/>` — an explicit transparent interior.
+   * - `'inherit'` emits no fill child at all, leaving the interior to
+   *   `p:style/a:fillRef` or the placeholder. This is the only way to author that
+   *   state from `addShape`/`addText`.
+   *
+   * On a table cell (`TableCellProps.fill`) and a slide background the two spellings
+   * differ the same way, except that *omitting* the option there already means
+   * inherit, so `'inherit'` is merely the explicit form of the default.
+   * @default 'solid'
    */
-  stops: GradientStopProps[];
-}
-interface RadialGradientFillProps {
+  type?: 'none' | 'inherit' | 'solid' | 'gradient' | 'pattern' | 'image';
   /**
-   * 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.
+   * Native PPTX gradient fill options.
    */
-  kind: 'radial';
+  gradient?: GradientFillProps;
   /**
-   * 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 }
+   * Native PPTX pattern fill options.
    */
-  center?: {
-    x: number;
-    y: number;
-  };
+  pattern?: PatternFillProps;
   /**
-   * Whether the fill rotates with the shape.
-   * @default true
+   * Native PPTX picture fill options. Setting this (or `type: 'image'`) fills the
+   * shape interior with a stretched bitmap instead of a color.
    */
-  rotateWithShape?: boolean;
+  image?: ImageFillProps;
   /**
-   * Gradient stops. Stops are serialized in ascending `position` order; the
-   * first (`position: 0`) is the center color.
+   * Resolved media relationship id for an image fill, assigned at add-time.
+   * @internal
    */
-  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;
+  _imgRid?: number;
 }
-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 = TextVerticalType;
 /**
- * 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)
+ * Line (stroke) options.
  *
- * 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).
+ * 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' }] } }`.
  */
-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/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 —
-   *   for an SVG too, from its `width`/`height` or `viewBox`.
-   * - A `path` image is measured at export time (its bytes are not available synchronously);
-   *   an omitted dimension falls back to 1 inch if it stays unmeasurable.
-   * - An SVG with *neither* dimension given also falls back to 1 inch: its user units carry a
-   *   dependable aspect ratio but only a conventional magnitude, so a 24-unit icon is not
-   *   treated as a quarter-inch object.
-   * - A vector source placed in a box whose ratio differs from its own is letterboxed, not
-   *   stretched; see {@link sizing} to override.
-   */
-  /**
-   * 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;
+interface ShapeLineProps extends ShapeFillProps {
   /**
-   * 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 width (pt)
+   * @default 1
    */
-  line?: ShapeLineProps;
+  width?: number;
   /**
-   * 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
+   * Dash type — the full `ST_PresetLineDashVal` set, so any dash a source deck can
+   * carry can also be authored and replicated.
+   * @default 'solid'
    */
-  placeholder?: string;
+  dashType?: PresetLineDashVal;
   /**
-   * Image rotation (degrees)
-   * - range: -360 to 360
-   * @default 0
-   * @example 180 // rotate image 180 degrees
+   * Line end cap style
+   * @default 'flat'
    */
-  rotate?: number;
+  cap?: LineCap;
   /**
-   * Enable image rounding (clips the image to a circle/ellipse)
-   * - shorthand for `shape: 'ellipse'`; `shape` takes precedence when both are set
-   * @default false
+   * Begin arrow type
    */
-  rounding?: boolean;
+  beginArrowType?: 'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle';
   /**
-   * 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
+   * End arrow type
    */
-  shape?: SHAPE_NAME;
+  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 {
   /**
-   * 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
+   * Routing style
+   * @default 'straight'
    */
-  points?: GeometryPoint[];
+  type?: ConnectorType;
   /**
-   * Rounded rectangle corner radius (inches) when `shape: 'roundRect'`
-   * - values: 0.0 to 1.0
-   * @default 0
+   * 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
    */
-  rectRadius?: number;
+  bends?: 1 | 2 | 3;
   /**
-   * 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 }
+   * 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).
    */
-  shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[];
+  adj?: number | number[];
   /**
-   * Shadow Props
-   * - MS-PPT > Format Picture > Shadow
-   * @example
-   * { type: 'outer', color: '000000', transparency: 50, blur: 20,  offset: 20, angle: 270 }
+   * 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}).
    */
-  shadow?: ShadowProps;
+  startShape?: string;
   /**
-   * 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
+   * 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
    */
-  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;
-  };
+  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;
   /**
-   * Image sizing options
-   * - omit entirely for the default: a raster fills the `w`×`h` box, a vector (SVG) source is
-   *   letterboxed to its own aspect ratio inside that box
+   * Connection-site index on `endShape`. Ignored without `endShape`.
+   * @default 0
    */
-  sizing?: {
-    /**
-     * Sizing type
-     * - `cover` / `contain` fit the image into the `w`×`h` box using the image's *natural*
-     *   aspect ratio — read from the embedded PNG/JPEG/GIF/BMP/WebP header, or from an SVG's
-     *   `width`/`height` or `viewBox`. If the natural size cannot be determined (an
-     *   unrecognized format, or an SVG carrying neither) the displayed `w`/`h` ratio is used
-     *   as a fallback and a warning is logged.
-     * - `crop` cuts a window out of the displayed image using the `x`/`y`/`w`/`h` offsets.
-     * - `stretch` fills the box regardless of aspect ratio. This is what a raster does
-     *   anyway; name it explicitly to opt a vector source out of its aspect-correct default.
-     */
-    type: 'contain' | 'cover' | 'crop' | 'stretch';
-    /**
-     * Image width
-     * - inches or percentage
-     * - defaults to the picture's own `w`, which is what `cover`/`contain` almost always want
-     * @example 10.25 // position in inches
-     * @example '75%' // position as percentage of slide size
-     */
-    w?: Coord;
-    /**
-     * Image height
-     * - inches or percentage
-     * - defaults to the picture's own `h`
-     * @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;
-  };
+  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;
   /**
-   * Transparency (percent)
-   * - MS-PPT > Format Picture > Picture > Picture Transparency > Transparency
-   * - range: 0-100
-   * @default 0
-   * @example 25 // 25% transparent
+   * Line color (6-digit hex, no `#`)
+   * @default '000000'
    */
-  transparency?: number;
+  color?: HexColor;
   /**
-   * 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
+   * Line width (pt)
+   * @default 1
    */
-  duotone?: {
-    /** Color mapped to the image's dark/shadow tones. */
-    shadow: Color;
-    /** Color mapped to the image's light/highlight tones. */
-    highlight: Color;
-  };
+  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 {
   /**
-   * 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
+   * Horizontal position
+   * - inches or percentage
+   * @example 10.25 // position in inches
+   * @example '75%' // position as percentage of slide size
    */
-  grayscale?: boolean;
+  x?: Coord;
   /**
-   * 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
+   * Vertical position
+   * - inches or percentage
+   * @example 10.25 // position in inches
+   * @example '75%' // position as percentage of slide size
    */
-  biLevel?: {
-    /** Luminance split point as a `0.0–1.0` fraction (serialized to `thresh`, the 0–1 fraction ×100000). */
-    threshold: number;
-  };
+  y?: Coord;
   /**
-   * 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
+   * Height
+   * - inches or percentage
+   * @example 10.25 // height in inches
+   * @example '75%' // height as percentage of slide size
    */
-  clrChange?: {
-    /** Source color to replace (`<a:clrFrom>`). */
-    from: Color;
-    /** Replacement color (`<a:clrTo>`). */
-    to: Color;
-  };
+  h?: Coord;
   /**
-   * 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>'
+   * Width
+   * - inches or percentage
+   * @example 10.25 // width in inches
+   * @example '75%' // width as percentage of slide size
    */
-  svg?: string;
+  w?: Coord;
 }
-type ImageProps = ImageBaseProps & (DataOrPathRequiredProps | (DataOrPathProps & {
-  svg: string;
-}));
 /**
- * Add media (audio/video) to slide
- * Requires either `data` or `path`; online media requires `link`.
+ * Reusable optional data/path fields.
+ * Use `DataOrPathRequiredProps` for APIs that require at least one source.
  */
-interface MediaBaseProps extends PositionProps, ObjectNameProps {
+interface DataOrPathProps {
   /**
-   * Cover image
-   * @default "play button" image, gray background
+   * 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
    */
-  cover?: string;
+  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 {
   /**
-   * media file extension
-   * - use when the media file path does not already have an extension, ex: "/folder/SomeSong"
-   * @default extension from file provided
+   * Stop position as a percentage.
+   * - range: 0-100
    */
-  extn?: string;
+  position: number;
   /**
-   * 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
+   * Stop color.
+   * - `HexColor` or `ThemeColor`
    */
-  loop?: boolean;
+  color: Color;
   /**
-   * 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
+   * Transparency (percent)
+   * - range: 0-100
+   * @default 0
    */
-  loopCount?: number;
+  transparency?: 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 {
+interface LinearGradientFillProps {
   /**
-   * 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' }
+   * Gradient type.
    */
-  cover?: {
-    path?: string;
-    data?: string;
-  };
+  kind: 'linear';
   /**
-   * 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'
+   * Gradient angle in degrees. Values are normalized into 0-359.999...
+   * @default 0
    */
-  extn?: string;
+  angle?: number;
   /**
-   * 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'
+   * Whether the gradient angle scales with the fill region.
    */
-  progId?: string;
+  scaled?: boolean;
   /**
-   * 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
+   * Whether the fill rotates with the shape.
+   * @default true
    */
-  showAsIcon?: boolean;
+  rotateWithShape?: 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
+   * Gradient stops. Stops are serialized in ascending `position` order.
    */
-  imgW?: number;
-  /** @see {@link imgW} */
-  imgH?: number;
+  stops: GradientStopProps[];
 }
-/**
- * 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 & {
+interface RadialGradientFillProps {
   /**
-   * Media type
+   * 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.
    */
-  type: Exclude<MediaType, 'online'>;
+  kind: 'radial';
   /**
-   * Optional video embed link metadata.
+   * 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 }
    */
-  link?: string;
-}) | (DataOrPathProps & {
+  center?: {
+    x: number;
+    y: number;
+  };
   /**
-   * Use 'online' to embed a YouTube video (only supported in recent versions of PowerPoint)
+   * Whether the fill rotates with the shape.
+   * @default true
    */
-  type: 'online';
+  rotateWithShape?: boolean;
   /**
-   * 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
+   * Gradient stops. Stops are serialized in ascending `position` order; the
+   * first (`position: 0`) is the center color.
    */
-  link: string;
-}));
+  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 = TextVerticalType;
+/**
+ * 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/table.d.ts
 /**
@@ -3456,35 +3517,15 @@ interface SlideMasterChartProps {
   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, …).
+ * One object on a slide master, as a key-tagged descriptor.
  *
- * A union member's comment cannot carry block tags, so this stands in for `@example`:
- * `{ shape: { type: 'ellipse', options: { x: 1, y: 1, w: 2, h: 2, fill: { color: 'FF0000' } } } }`
+ * The six descriptors it shares with a group child are {@link CommonObjectDescriptor}; the two
+ * below are the master's own — a chart, which a group cannot hold, and a placeholder, which is
+ * the whole point of a master.
  */
-{
-  shape: {
-    type: SHAPE_NAME;
-    options?: ShapeProps;
-  };
-} | {
-  text: {
-    text: string | number | TextProps[];
-    options?: TextPropsOptions;
-  };
+type SlideMasterObject = CommonObjectDescriptor | {
+  chart: SlideMasterChartProps;
 } | {
   placeholder: {
     options: PlaceholderProps;
@@ -3675,31 +3716,14 @@ type Model3dProps = Model3dBaseProps & DataOrPathRequiredProps;
 /**
  * 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
+ * The six descriptors it shares with `SlideMasterObject` are {@link CommonObjectDescriptor};
+ * `group` is the group's own, and the master's `chart` and `placeholder` are deliberately not
+ * here. A `group` child nests another group (an identity child
  * coordinate space is kept at every depth, so descendants keep their slide-absolute
  * coordinates). Charts, media, tables, and placeholders are intentionally excluded (see
  * `addGroup`); passing one logs a warning and skips it.
  */
-type GroupChildProps = {
-  image: ImageProps;
-} | {
-  line: ShapeProps;
-} | {
-  rect: ShapeProps;
-} | {
-  roundRect: ShapeProps;
-} | {
-  shape: {
-    type: SHAPE_NAME;
-    options?: ShapeProps;
-  };
-} | {
-  text: {
-    text: string | number | TextProps[];
-    options?: TextPropsOptions;
-  };
-} | {
+type GroupChildProps = CommonObjectDescriptor | {
   group: {
     children: GroupChildProps[];
     options?: GroupProps;
@@ -3776,6 +3800,47 @@ interface ObjectOptions extends ImageBaseProps, PositionProps, ShapeProps, Table
 interface SlideLayout {
   background?: BackgroundProps;
 }
+/**
+ * One authored object on a slide, as {@link Slide.objects} reports it: what it is and how it is
+ * addressed, not how it is drawn. It is a snapshot taken when the getter ran, not a live handle —
+ * nothing on it writes back, and a later `addShape`/`groupObjects` leaves it describing the slide
+ * as it was.
+ *
+ * The point of it is composition. A slide assembled by independent renderers arrives with objects
+ * whose descriptors nobody kept, and the only durable handle on them is the `objectName` each one
+ * was authored with; without a way to enumerate those, a consumer that wants to act on what is
+ * already there has to either make every renderer surrender its internals or keep a parallel
+ * ledger of what it added — and a ledger is wrong the moment a renderer adds an object it did not
+ * announce.
+ */
+interface SlideObjectInfo {
+  /** What kind of object this is — the same value the object was authored as. */
+  readonly type: SlideObjectType;
+  /**
+   * Selection Pane name, in the spelling the caller passed to `objectName`, so it can be handed
+   * straight back to `groupObjects()` or to an animation or connector reference.
+   *
+   * Always a string: an object authored without a name still gets the generated `Shape 3` /
+   * `Text 1` / `Group 2` identity PowerPoint shows in the Selection Pane, and that name addresses
+   * it just as well. The two are indistinguishable here on purpose — nothing downstream of
+   * authoring records which is which, and a consumer that cares can tell them apart by the
+   * naming convention it chose for its own objects.
+   */
+  readonly objectName: string;
+  /** True when the object occupies a layout placeholder, which grouping refuses on top of kind. */
+  readonly isPlaceholder: boolean;
+  /**
+   * Whether `groupObjects()` would accept this object on kind alone. It cannot speak for the
+   * *selection* — an unresolved, duplicated or ambiguous name still throws — so it answers "is
+   * this object groupable", never "will this call succeed".
+   */
+  readonly canGroup: boolean;
+  /**
+   * Children, when `type` is `group`; empty otherwise. Ordered bottom-to-top like
+   * {@link Slide.objects} itself, and nested to whatever depth the groups nest.
+   */
+  readonly children: readonly SlideObjectInfo[];
+}
 interface Slide {
   addChart(data: OptsChartData[], options: ChartOpts & {
     type: CHART_NAME;
@@ -3798,6 +3863,18 @@ interface Slide {
   addGroup: (children: GroupChildProps[], options?: GroupProps) => Slide;
   /** Group objects already on this slide, addressed by their `objectName`, into a single group. */
   groupObjects: (objectNames: string[], options?: GroupProps) => Slide;
+  /**
+   * The objects authored on this slide so far, bottom-to-top in z-order — the read-back half of
+   * `groupObjects()`, which addresses those same objects by name but until now gave no way to
+   * learn the names.
+   *
+   * A fresh snapshot on every access, and inert: it describes the slide, and writing to it does
+   * nothing. To act on what it reports, call the authoring API with the names it hands you.
+   * @example
+   * const cards = slide.objects.filter((o) => o.canGroup && o.objectName?.startsWith('card:'))
+   * slide.groupObjects(cards.map((o) => o.objectName), { objectName: 'Cards' })
+   */
+  readonly objects: readonly SlideObjectInfo[];
   readonly newAutoPagedSlides?: Slide[];
   /**
    * Slide-show transition played when advancing to this slide (`p:transition`).
@@ -3845,5 +3922,5 @@ interface AddSlideProps {
   sectionTitle?: string;
 }
 //#endregion
-export { PositionProps as $, CommentProps as $t, TableToSlidesDocument as A, ChartPropsChartBar as At, Coord as B, ChartPropsChartWaterfall as Bt, TableCell as C, ChartLineDash as Ct, TableProps as D, ChartPropsAxisSer as Dt, TableCellProps as E, ChartPropsAxisCat as Et, MediaProps as F, ChartPropsChartPie as Ft, GradientStopProps as G, ChartPropsTitle as Gt, DataOrPathRequiredProps as H, ChartPropsDataTable as Ht, MediaType as I, ChartPropsChartRadar as It, ImageFillProps as J, OptsChartData as Jt, HAlign as K, ChartSeriesOpts as Kt, OleObjectProps as L, ChartPropsChartRegionMap as Lt, TableToSlidesProps as M, ChartPropsChartDoughnut as Mt, ImageBaseProps as N, ChartPropsChartHistogram as Nt, TableRow as O, ChartPropsAxisVal as Ot, ImageProps as P, ChartPropsChartLine as Pt, PatternPreset as Q, PlaceholderProps as Qt, BackgroundProps as R, ChartPropsChartStock as Rt, TransitionType as S, ShapeProps as Sn, ChartExStatistics as St, TableCellDiagonals as T, ChartOpts as Tt, GeometryPoint as U, ChartPropsFillLine as Ut, DataOrPathProps as V, ChartPropsDataLabel as Vt, GradientFillProps as W, ChartPropsLegend as Wt, Margin as X, ObjectLockProps as Xt, LinearGradientFillProps as Y, OptsChartGridLine as Yt, PatternFillProps as Z, ObjectNameProps as Zt, AnimationProps as _, ShapeAdjustHandlePolar as _n, ChartAxisTickMark as _t, Slide as a, SlideComment as an, ConnectorProps as at, TransitionProps as b, ShapeConnectionSite as bn, ChartExBinning as bt, Model3dPoint as c, TextBaseProps as cn, HyperlinkProps as ct, MasterTextStyleLevel as d, TextMeasurement as dn, ShapeLineProps as dt, MeasureTextOptions as en, RadialGradientFillProps as et, MasterTextStyleProps as f, TextProps as fn, BevelPresetType as ft, SlideNumberProps as g, ShapeAdjustHandle as gn, ChartAreaProps as gt, SlideMasterProps as h, textRuns as hn, PresetMaterialType as ht, ObjectOptions as i, ResolvedCommentAuthor as in, BorderProps as it, TableToSlidesElement as j, ChartPropsChartBoxWhisker as jt, TableRowSlide as k, ChartPropsBase as kt, Model3dProps as l, TextFitShrinkProps as ln, ShadowProps as lt, SlideMasterObject as m, textRun as mn, LightRigType as mt, GroupChildProps as n, NotesTextOptions as nn, ThemeColor as nt, SlideLayout as o, TableCellLayout as on, ConnectorType as ot, SlideMasterChartProps as p, TextPropsOptions as pn, LightRigDirection as pt, HexColor as q, LineCap as qt, GroupProps as r, OverflowBoxOptions as rn, VAlign as rt, Model3dCameraProps as s, TableLayoutResult as sn, HyperlinkActionJump as st, AddSlideProps as t, NotesProps as tn, TextVertType as tt, MasterBulletProps as u, TextGlowProps as un, ShapeFillProps as ut, AnimationTrigger as v, ShapeAdjustHandleXY as vn, ChartDataPointStyle as vt, TableCell3DProps as w, ChartMulti as wt, TransitionSoundProps as x, ShapeGuide as xn, ChartExGeography as xt, PresetEffect as y, ShapeAdjustValue as yn, ChartErrorBarOptions as yt, Color as z, ChartPropsChartSurface as zt };
-//# sourceMappingURL=slide-B_aInw3N.d.ts.map
+export { VAlign as $, MeasureTextOptions as $t, TableRowSlide as A, ChartPropsChartDoughnut as At, GradientFillProps as B, ChartPropsDataTable as Bt, TransitionType as C, ShapeAdjustValue as Cn, ChartOpts as Ct, TableCellProps as D, ChartPropsBase as Dt, TableCellDiagonals as E, ShapeProps as En, ChartPropsAxisVal as Et, Color as F, ChartPropsChartRegionMap as Ft, LinearGradientFillProps as G, LineCap as Gt, HAlign as H, ChartPropsLegend as Ht, Coord as I, ChartPropsChartStock as It, PatternPreset as J, CommonObjectDescriptor as Jt, Margin as K, OptsChartData as Kt, DataOrPathProps as L, ChartPropsChartSurface as Lt, TableToSlidesElement as M, ChartPropsChartLine as Mt, TableToSlidesProps as N, ChartPropsChartPie as Nt, TableProps as O, ChartPropsChartBar as Ot, BackgroundProps as P, ChartPropsChartRadar as Pt, ThemeColor as Q, CommentProps as Qt, DataOrPathRequiredProps as R, ChartPropsChartWaterfall as Rt, TransitionSoundProps as S, ShapeAdjustHandleXY as Sn, ChartMulti as St, TableCell3DProps as T, ShapeGuide as Tn, ChartPropsAxisSer as Tt, HexColor as U, ChartPropsTitle as Ut, GradientStopProps as V, ChartPropsFillLine as Vt, ImageFillProps as W, ChartSeriesOpts as Wt, RadialGradientFillProps as X, ObjectNameProps as Xt, PositionProps as Y, ObjectLockProps as Yt, TextVertType as Z, PlaceholderProps as Zt, SlideNumberProps as _, MediaProps as _n, ChartErrorBarOptions as _t, Slide as a, TableCellLayout as an, ShadowProps as at, PresetEffect as b, ShapeAdjustHandle as bn, ChartExStatistics as bt, Model3dCameraProps as c, TextFitShrinkProps as cn, BevelPresetType as ct, MasterBulletProps as d, TextProps as dn, LightRigType as dt, NotesProps as en, BorderProps as et, MasterTextStyleLevel as f, TextPropsOptions as fn, PresetMaterialType as ft, SlideMasterProps as g, ImageProps as gn, ChartDataPointStyle as gt, SlideMasterObject as h, ImageBaseProps as hn, ChartAxisTickMark as ht, ObjectOptions as i, SlideComment as in, HyperlinkProps as it, TableToSlidesDocument as j, ChartPropsChartHistogram as jt, TableRow as k, ChartPropsChartBoxWhisker as kt, Model3dPoint as l, TextGlowProps as ln, ColorMapToken as lt, SlideMasterChartProps as m, textRuns as mn, ChartAreaProps as mt, GroupChildProps as n, OverflowBoxOptions as nn, ConnectorType as nt, SlideLayout as o, TableLayoutResult as on, ShapeFillProps as ot, MasterTextStyleProps as p, textRun as pn, ThemeColorSlot as pt, PatternFillProps as q, OptsChartGridLine as qt, GroupProps as r, ResolvedCommentAuthor as rn, HyperlinkActionJump as rt, SlideObjectInfo as s, TextBaseProps as sn, ShapeLineProps as st, AddSlideProps as t, NotesTextOptions as tn, ConnectorProps as tt, Model3dProps as u, TextMeasurement as un, LightRigDirection as ut, AnimationProps as v, MediaType as vn, ChartExBinning as vt, TableCell as w, ShapeConnectionSite as wn, ChartPropsAxisCat as wt, TransitionProps as x, ShapeAdjustHandlePolar as xn, ChartLineDash as xt, AnimationTrigger as y, OleObjectProps as yn, ChartExGeography as yt, GeometryPoint as z, ChartPropsDataLabel as zt };
+//# sourceMappingURL=slide-ZqAdVvHV.d.ts.map