pptx-ts 3.7.0 → 4.0.0

package/dist/slide-Dx2ZeVZ6.d.ts

@@ -0,0 +1,1256 @@
+import { d as SHAPE_NAME, h as TableStyle, i as CHART_NAME, m as SlideObjectType } from "./enums-BUKTUB6V.js";
+import { Ct as CommonObjectDescriptor, Dt as CommentProps, Et as PlaceholderProps, Gt as ImageBaseProps, Ht as TextPropsOptions, I as FillOption, It as TextBaseProps, Kt as ImageProps, N as BorderProps, O as PositionProps, P as ConnectorProps, Q as ChartOpts, R as HyperlinkProps, Rt as TextFitShrinkProps, S as HexColor, T as Margin, Tt as ObjectNameProps, Vt as TextProps, Yt as OleObjectProps, Z as ChartMulti, _ as DataOrPathRequiredProps, bn as TextHorzOverflowType, f as BackgroundOption, fn as LightRigDirection, g as DataOrPathProps, h as Coord, hn as PresetMaterialType, kt as NotesProps, m as Color, nn as ShapeProps, on as BevelPresetType, pn as LightRigType, qt as MediaProps, vn as TEXT_AUTONUM_SCHEMES, wt as ObjectLockProps, x as HAlign, xt as OptsChartData, yn as TRANSITION_TYPES } from "./pres-C6qgOFAa.js";
+//#region src/types/table.d.ts
+/**
+ * A `<table>` element, from whatever DOM implementation the caller has.
+ *
+ * Deliberately *not* `lib.dom`'s `Element`. `lib.dom`'s types are built for a browser, and a
+ * non-browser DOM's element type — happy-dom's, jsdom's — declares its own members and does
+ * not satisfy them, so demanding `Element` would reject from TypeScript exactly the
+ * implementations `pptx-ts/html` exists to accept. Requiring the three members the conversion
+ * actually calls keeps a mistyped argument an error while letting every real DOM through.
+ */
+interface TableToSlidesElement {
+  getAttribute: (name: string) => string | null;
+  querySelector: (selectors: string) => unknown;
+  querySelectorAll: (selectors: string) => unknown;
+}
+/**
+ * The one thing `tableToSlides` asks a document for. Structural for the same reason
+ * {@link TableToSlidesElement} is.
+ */
+interface TableToSlidesDocument {
+  getElementById: (elementId: string) => TableToSlidesElement | null;
+}
+/**
+ * Options for `tableToSlides`. The conversion computes its own column widths, always pages, and
+ * repeats every `<thead>` row, so `colW`, `autoPage` and `autoPageHeaderRows` are not options here.
+ */
+interface TableToSlidesProps extends Omit<TableProps, 'autoPage' | 'colW' | 'autoPageHeaderRows'> {
+  /**
+   * Add an image to slide(s) created during autopaging
+   * - `image` prop requires either `path` or `data`
+   * - see `DataOrPathProps` for details on `image` props
+   * - see `PositionProps` for details on `options` props
+   */
+  addImage?: {
+    image: DataOrPathProps;
+    options: PositionProps;
+  };
+  /**
+   * Add a shape to slide(s) created during autopaging
+   */
+  addShape?: {
+    shapeName: SHAPE_NAME;
+    options: ShapeProps;
+  };
+  /**
+   * Add a table to slide(s) created during autopaging
+   */
+  addTable?: {
+    rows: TableRow[];
+    options: TableProps;
+  };
+  /**
+   * Add a text object to slide(s) created during autopaging
+   */
+  addText?: {
+    text: TextProps[];
+    options: TextPropsOptions;
+  };
+  /**
+   * Auto-paging character weight
+   * - adjusts how many characters are used before lines wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // lines are longer (increases the number of characters that can fit on a given line)
+   */
+  autoPageCharWeight?: number;
+  /**
+   * Auto-paging line weight
+   * - adjusts how many lines are used before slides wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // each line is priced taller, so fewer lines fit on a slide before the table pages
+   */
+  autoPageLineWeight?: number;
+  /**
+   * Whether to repeat head row(s) on new tables created by autopaging
+   * @default false
+   */
+  autoPageRepeatHeader?: boolean;
+  /**
+   * The `y` location to use on subsequent slides created by autopaging
+   * @default (top margin of Slide)
+   */
+  autoPageSlideStartY?: number;
+  /**
+   * Document to resolve a table *id* against.
+   * - only consulted when the table is identified by string id; passing the element itself
+   *   needs no document, since one is reached through the element's `ownerDocument`
+   * - defaults to the global `document`, which is what a browser caller gets
+   * - supply this to convert a table outside a browser (any DOM implementation will do)
+   */
+  document?: TableToSlidesDocument;
+  /**
+   * Title of the slide master to use for the auto-paged slides (the `title` passed to
+   * `defineSlideMaster`). Matches the `masterTitle` option of `addSlide`.
+   * - define a master slide to have your auto-paged slides carry a corporate design, etc.
+   */
+  masterTitle?: string;
+  /**
+   * Slide margin
+   * - this margin will be across all slides created by auto-paging
+   */
+  slideMargin?: Margin;
+}
+/**
+ * A table cell's corner-to-corner rules (`a:tcPr/a:lnTlToBr` / `a:lnBlToTr`) — the
+ * "Diagonal Down Border" / "Diagonal Up Border" of PowerPoint's border gallery.
+ *
+ * Deliberately its own object rather than two more entries on {@link TableCellProps.border}'s
+ * tuple: widening that tuple to six would break every existing caller for a construct almost
+ * no deck uses, and the two diagonals are not edges — they do not participate in the
+ * perimeter, and they are not inherited by a merged region's covered cells.
+ *
+ * @example diagonal: { tlToBr: { type:'solid', color:'C00000', width:1 } } // strike a cell out
+ * @example diagonal: { tlToBr: { type:'solid' }, blToTr: { type:'solid' } } // an X across the cell
+ */
+interface TableCellDiagonals {
+  /** Top-left to bottom-right (`╲`, `a:lnTlToBr`). */
+  tlToBr?: BorderProps;
+  /** Bottom-left to top-right (`╱`, `a:lnBlToTr`). */
+  blToTr?: BorderProps;
+}
+/**
+ * A cell's 3-D bevel (`a:tcPr/a:cell3D`).
+ *
+ * A minimal surface over `CT_Cell3D`, which is a required `a:bevel` plus an optional
+ * `a:lightRig`. PowerPoint's table UI exposes no control for it — it reaches a deck through a
+ * theme's table style or through another producer — so this exists to author and reproduce
+ * one, not as a general 3-D model.
+ */
+interface TableCell3DProps {
+  /**
+   * The bevel's preset shape (`a:bevel/@prst`).
+   * @default 'circle'
+   */
+  preset?: BevelPresetType;
+  /**
+   * Bevel width in points (`a:bevel/@w`; the attribute is EMU).
+   * @default 6 // 76200 EMU
+   */
+  width?: number;
+  /**
+   * Bevel height in points (`a:bevel/@h`; the attribute is EMU).
+   * @default 6 // 76200 EMU
+   */
+  height?: number;
+  /**
+   * Surface material (`a:cell3D/@prstMaterial`), which decides how the bevel takes light.
+   * @default 'plastic'
+   */
+  material?: PresetMaterialType;
+  /**
+   * Scene lighting (`a:cell3D/a:lightRig`). Both fields are required by the schema, so
+   * either give both or omit the whole object and let the renderer light the bevel.
+   * @example lightRig: { rig: 'threePt', dir: 't' }
+   */
+  lightRig?: {
+    rig: LightRigType;
+    dir: LightRigDirection;
+  };
+}
+interface TableCellProps extends TextBaseProps {
+  /**
+   * Strikethrough, as {@link TextPropsOptions.strike} takes it on a text run. On a cell it applies
+   * to every run that states none; on a run inside a cell's `text`, to that run.
+   */
+  strike?: NonNullable<TextPropsOptions['strike']>;
+  /**
+   * Baseline shift, as {@link TextPropsOptions.baseline} takes it on a text run: above zero raises
+   * the text, below zero lowers it. On a cell it applies to every run that states none.
+   */
+  baseline?: NonNullable<TextPropsOptions['baseline']>;
+  /** Outline level of the paragraph a run starts, as {@link TextPropsOptions.indentLevel}. */
+  indentLevel?: NonNullable<TextPropsOptions['indentLevel']>;
+  /** Line spacing in points, as {@link TextPropsOptions.lineSpacing}. */
+  lineSpacing?: NonNullable<TextPropsOptions['lineSpacing']>;
+  /** Line spacing as a multiple of single spacing, as {@link TextPropsOptions.lineSpacingMultiple}. */
+  lineSpacingMultiple?: NonNullable<TextPropsOptions['lineSpacingMultiple']>;
+  /** Space before the paragraph in points, as {@link TextPropsOptions.paraSpaceBefore}. */
+  paraSpaceBefore?: NonNullable<TextPropsOptions['paraSpaceBefore']>;
+  /** Space after the paragraph in points, as {@link TextPropsOptions.paraSpaceAfter}. */
+  paraSpaceAfter?: NonNullable<TextPropsOptions['paraSpaceAfter']>;
+  /**
+   * Auto-paging character weight
+   * - adjusts how many characters are used before lines wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // lines are longer (increases the number of characters that can fit on a given line)
+   */
+  autoPageCharWeight?: number;
+  /**
+   * The cell's four edge borders (`a:tcPr/a:lnT|lnR|lnB|lnL`).
+   * - a single `BorderProps` is broadcast to all four sides
+   * - an array is read in **TRBL** order (`[top, right, bottom, left]`)
+   *
+   * Overrides the table-level {@link TableProps.border} default entirely — the two do not
+   * merge per side. A `null` entry is a hole: that edge is left out of `a:tcPr` and keeps
+   * inheriting from the table style, while `{ type: 'none' }` writes an explicit no-line
+   * that overrides it. For the two corner-to-corner rules see {@link diagonal}; for the
+   * table's outside edge see {@link TableProps.outerBorder}.
+   */
+  border?: BorderProps | [BorderProps | null, BorderProps | null, BorderProps | null, BorderProps | null];
+  /**
+   * The cell's corner-to-corner rules — PowerPoint's "Diagonal Down/Up Border".
+   *
+   * Kept off {@link border}'s tuple on purpose: see {@link TableCellDiagonals}. A diagonal
+   * on a merged cell is one stroke across the whole region, so only the span origin carries
+   * it — the covered cells inherit the origin's *edges* but never its diagonals.
+   * @example diagonal: { tlToBr: { type:'solid', color:'C00000' } } // strike the cell out
+   */
+  diagonal?: TableCellDiagonals;
+  /**
+   * Centre the cell's whole text **block** horizontally within the cell
+   * (`a:tcPr/@anchorCtr`), independent of each paragraph's own `align`.
+   *
+   * The two do different things and compose: `align` decides where each line sits inside
+   * the text block, `anchorCtr` decides where that block sits inside the cell. With
+   * left-aligned text in a wide cell, `anchorCtr: true` centres the ragged-right column of
+   * lines as a unit while keeping their left edges flush with each other.
+   *
+   * `false` is the schema default, so it emits nothing — the same reasoning as
+   * `horzOverflow: 'clip'`.
+   * @default false
+   */
+  anchorCtr?: boolean;
+  /**
+   * A 3-D bevel on the cell (`a:tcPr/a:cell3D`). Niche: PowerPoint's table UI has no
+   * control for it, so it reaches a deck from a theme or another producer, and this exists
+   * to author and reproduce one. See {@link TableCell3DProps}.
+   */
+  cell3D?: TableCell3DProps;
+  /**
+   * Cell colspan
+   */
+  colspan?: number;
+  /**
+   * Cell fill — a solid color, or a picture that fills the cell (`a:blipFill` in
+   * the cell's `a:tcPr`, stretched to the cell box). A picture fill embeds the
+   * image as slide media; identical sources are embedded once. Raster only —
+   * an SVG source warns and is ignored, matching shape fills. A bare {@link Color} is
+   * shorthand for a solid fill ({@link FillOption}).
+   * @example 'FF0000' // hex color (red), shorthand for { color:'FF0000' }
+   * @example { color:'FF0000' } // hex color (red)
+   * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
+   * @example { color:SchemeColor.accent1 } // theme color Accent1
+   * @example { type:'image', image:{ path:'logo.png' } } // picture fill
+   * @example { image:{ data:'image/png;base64,…' } } // picture fill, `type` inferred
+   */
+  fill?: FillOption;
+  /**
+   * What happens to a **single glyph** wider than the cell's text width (`a:tcPr/@horzOverflow`).
+   * - `'clip'` (PowerPoint's default) cuts the glyph off at the cell edge
+   * - `'overflow'` lets it draw past the edge, over whatever is beside it
+   *
+   * This is **not** a text-wrap switch, despite the name. Lines always wrap to the column
+   * width; only an individual character too wide to fit on a line by itself is affected, so
+   * it matters for oversized display type, wide CJK/emoji glyphs, and icon fonts in a narrow
+   * column. PowerPoint has no per-cell no-wrap at all — `wrap="none"` on a cell's `a:bodyPr`
+   * is discarded on the next save (probe:
+   * `test/read/fixtures/authoring/probe-table-cell-wrap.ps1`).
+   * `'clip'` is written as asked but is the schema default, so PowerPoint drops the
+   * attribute again the first time it saves the deck — the visible result is the same
+   * either way, and leaving this unset emits nothing at all.
+   * @default (unset — PowerPoint clips)
+   * @example 'overflow' // a 60pt glyph in a 0.5in column draws whole instead of being cut
+   */
+  horzOverflow?: TextHorzOverflowType;
+  hyperlink?: HyperlinkProps;
+  /**
+   * Cell margin (inches), in `[top, right, bottom, left]` order
+   * @default [0.05, 0.1, 0.05, 0.1]
+   */
+  margin?: Margin;
+  /**
+   * Cell rowspan
+   */
+  rowspan?: number;
+  /**
+   * Shrink cell text to fit when it would overflow the cell's fixed height.
+   * - `'shrink'` measures the wrapped text and bakes a **reduced literal font size**
+   *   onto the cell's runs so the text fits — PowerPoint does not support text
+   *   autofit (`normAutofit`) inside table cells, so there is no font-scale flag to
+   *   set; the size itself is lowered, which both PowerPoint and LibreOffice render
+   *   identically with no edit/resize.
+   * - Requires the cell font registered via {@link TsPptx.registerFontMetrics}. With no
+   *   metrics registered at all it is a silent no-op (the cell keeps its authored size); once
+   *   any face is registered, an unregistered face is estimated and warns once per write.
+   * - Only triggers when the cell's row has a **fixed** height that the text exceeds.
+   *   With auto-height rows (no `rowH`/`h`), the row simply grows, so nothing shrinks.
+   * - Only `'shrink'` is acted on for cells. `'resize'` and the object form are ignored
+   *   here: a table row already auto-grows to fit its tallest cell (the cell equivalent
+   *   of `spAutoFit`), so there is nothing to bake. (The wider union is shared with
+   *   {@link TextPropsOptions.fit} so table-level `fit` can cascade to cells.)
+   * @example 'shrink' // measured when the cell font is registered; else no-op
+   */
+  fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
+}
+interface TableProps extends PositionProps, TextBaseProps, ObjectNameProps {
+  /**
+   * Name of a table/content placeholder defined on the slide layout/master to bind this table to.
+   * - when it matches a layout/master placeholder, the table's `<p:graphicFrame>` emits that
+   *   placeholder's `<p:ph>` (idx/type) so PowerPoint treats the table as filling the placeholder
+   *   (e.g. a "Title and Content" content placeholder)
+   * - the table also inherits the placeholder's position/size for any of x/y/w/h left unset
+   * @example 'body' // bind to the layout placeholder named 'body'
+   */
+  placeholder?: string;
+  /**
+   * Whether to enable auto-paging
+   * - auto-paging creates new slides as content overflows a slide
+   * @default false
+   */
+  autoPage?: boolean;
+  /**
+   * Auto-paging character weight
+   * - adjusts how many characters are used before lines wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // lines are longer (increases the number of characters that can fit on a given line)
+   */
+  autoPageCharWeight?: number;
+  /**
+   * Auto-paging line weight
+   * - adjusts how many lines are used before slides wrap
+   * - range: -1.0 to 1.0
+   * @default 0.0
+   * @example 0.5 // each line is priced taller, so fewer lines fit on a slide before the table pages
+   */
+  autoPageLineWeight?: number;
+  /**
+   * Whether table header row(s) should be repeated on each new slide creating by autoPage.
+   * Use `autoPageHeaderRows` to designate how many rows comprise the table header (1+).
+   * @default false
+   */
+  autoPageRepeatHeader?: boolean;
+  /**
+   * Number of rows that comprise table headers
+   * - required when `autoPageRepeatHeader` is set to true.
+   * - a whole number from 1 to the table's own row count; anything else is reported under
+   *   `table/invalid-header-row-count` and falls back to `1`
+   * @example 2 - repeats the first two table rows on each new slide created
+   * @default 1
+   */
+  autoPageHeaderRows?: number;
+  /**
+   * The `y` location to use on subsequent slides created by autopaging
+   * @default (top margin of Slide)
+   */
+  autoPageSlideStartY?: number;
+  /**
+   * Slide margins (inches) this table is laid out against, overriding the master's.
+   *
+   * Steers the default table width, `fitColumns: 'shrink'`, and every page the auto-pager
+   * creates. It was declared on {@link TableToSlidesProps} only, while the pager read it on
+   * both paths — so from `addTable` it worked at run time and the type rejected it, and the
+   * table definer ignored it either way, which made "does my table respect `slideMargin`"
+   * depend on whether `autoPage` was on.
+   */
+  slideMargin?: Margin;
+  /**
+   * Whether populated placeholders on the source slide (e.g. a title set via
+   * `addText(text, { placeholder })`) are copied onto each overflow slide created by autoPage.
+   * - new slides otherwise inherit only the layout's empty placeholders, so a title set on the
+   *   first slide would not appear on continuation slides.
+   * @default false
+   */
+  autoPagePlaceholder?: boolean;
+  /**
+   * Default border for **every cell** in the table — not the table's outer perimeter.
+   *
+   * A single `BorderProps` is broadcast to all four sides of each cell; an array is read
+   * in TRBL order and applied to each cell's own four sides. So
+   * `border: [{type:'solid'}, {type:'none'}, {type:'solid'}, {type:'none'}]` gives *every*
+   * cell a top and bottom rule — a full set of horizontal grid lines, not a rule at the
+   * top and bottom of the table. A cell's own `options.border` overrides this entirely.
+   *
+   * A `null` entry is a hole — that edge inherits from the table style — where
+   * `{ type: 'none' }` writes an explicit no-line that overrides it. Authoring nothing at
+   * all depends on {@link tableStyle}: a styled table leaves every edge absent so the style
+   * paints its grid, and a table with no style takes four no-fill sides, which is what keeps
+   * it clear of PowerPoint's no-style black hairline grid.
+   *
+   * For the perimeter, use {@link outerBorder}, which applies only to the cells on the
+   * table's outside edge. The two compose: `border` draws the interior grid and
+   * `outerBorder` overrides the edges it reaches.
+   * @example border: { type:'solid', color:'D9D9D9', width:0.5 } // full grid
+   * @example border: [{type:'solid'}, {type:'none'}, {type:'solid'}, {type:'none'}] // horizontal rules only
+   */
+  border?: BorderProps | [BorderProps | null, BorderProps | null, BorderProps | null, BorderProps | null];
+  /**
+   * Border for the table's outer perimeter only — the top edge of the first row, the
+   * bottom edge of the last row, the left edge of the first column and the right edge of
+   * the last column.
+   *
+   * A single `BorderProps` is used for all four perimeter sides; an array is read in TRBL
+   * order, so `outerBorder: [box, box, box, box]` boxes the table and
+   * `outerBorder: [rule, undefined, rule, undefined]` rules only above and below it.
+   * An `undefined`/omitted entry leaves that side to whatever {@link border} (or the cell's
+   * own `options.border`) already put there.
+   *
+   * Applied **after** every other border source, so it wins on the sides it touches and
+   * leaves the interior alone — the "outline the table, no interior grid" case is
+   * `outerBorder` with no `border` at all. Merged cells are handled: a span's covered cells
+   * inherit the origin's borders, so a colspan straddling the last column still gets the
+   * right-hand rule.
+   * @example outerBorder: { type:'solid', color:'1A2B3C', width:1 } // box the table
+   * @example outerBorder: [{type:'solid'}, undefined, {type:'solid'}, undefined] // rules above and below
+   */
+  outerBorder?: BorderProps | [BorderProps?, BorderProps?, BorderProps?, BorderProps?];
+  /**
+   * Width of table columns (inches)
+   * - single value is applied to every column equally based upon `w`
+   * - array of values in applied to each column in order
+   * @default columns of equal width based upon `w`
+   */
+  colW?: number | number[];
+  /**
+   * Shrink columns proportionally so a too-wide table fits the slide.
+   * - `'shrink'`: if the total column width exceeds the space available between
+   *   the table's `x` and the right slide margin, scale every column down by the
+   *   same factor so the whole table fits. Columns that already fit are untouched.
+   * - applies to an explicit `colW` array (the common "too many columns" case) and
+   *   to a `w` wider than the slide; never grows columns and never enforces a
+   *   minimum width, so a very high column count can still become thin.
+   * - opt-in: explicit widths are otherwise emitted as-is and may run off the slide.
+   * @default undefined (no scaling)
+   */
+  fitColumns?: 'shrink';
+  /**
+   * Table-level text-fit policy, cascaded to every cell that does not set its own
+   * {@link TableCellProps.fit}.
+   * - `'shrink'`: each cell whose row has a **fixed** height that its wrapped text
+   *   would exceed gets a reduced literal font size baked onto its runs so the text
+   *   fits (see {@link TableCellProps.fit} for the full semantics and the font-metrics
+   *   requirement). Cells that set their own `fit` win over this table default.
+   * - `'none'` / `'resize'` / the object form are accepted for parity with
+   *   {@link TextPropsOptions.fit} but only `'shrink'` is acted on for table cells.
+   * @default undefined (cells keep their authored size)
+   * @example 'shrink'
+   */
+  fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
+  /**
+   * Mark the first row as a header row.
+   * Emits `firstRow="1"` on `<a:tblPr>`, activating the first-row style region of
+   * the table style and satisfying the PowerPoint accessibility checker's "table header" rule.
+   * @default false
+   */
+  hasHeader?: boolean;
+  /**
+   * Mark the last row as a footer row.
+   * Emits `lastRow="1"` on `<a:tblPr>`, activating the last-row style region.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasFooter?: boolean;
+  /**
+   * Enable alternating row (band) shading.
+   * Emits `bandRow="1"` on `<a:tblPr>`, activating band1H/band2H style regions.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasBandedRows?: boolean;
+  /**
+   * Enable alternating column (band) shading.
+   * Emits `bandCol="1"` on `<a:tblPr>`, activating band1V/band2V style regions.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasBandedColumns?: boolean;
+  /**
+   * Apply special styling to the first column.
+   * Emits `firstCol="1"` on `<a:tblPr>`, activating the firstCol style region.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasFirstColumn?: boolean;
+  /**
+   * Apply special styling to the last column.
+   * Emits `lastCol="1"` on `<a:tblPr>`, activating the lastCol style region.
+   * Requires `tableStyle` to have a visible effect.
+   * @default false
+   */
+  hasLastColumn?: boolean;
+  /**
+   * Lay the table out right-to-left.
+   * Emits `rtl="1"` on `<a:tblPr>`, which mirrors the column order so the first
+   * column renders on the right — the correct layout for RTL scripts (Arabic, Hebrew).
+   * This controls only the table/column direction; per-cell text direction is set
+   * with each cell's `rtlMode` option.
+   * @default false
+   */
+  rtl?: boolean;
+  /**
+   * Table style to apply: a built-in style as a `TableStyle` member, or any other style GUID in
+   * braces, such as the id a table read back from a deck names.
+   * Emits `<a:tableStyleId>` inside `<a:tblPr>` with that GUID.
+   * Style flags (`hasHeader`, `hasFooter`, `hasBandedRows`, etc.) select which
+   * regions of the chosen style are activated; they have no visible effect without
+   * a `tableStyle` set.
+   *
+   * **Only a built-in GUID renders.** PowerPoint resolves `<a:tableStyleId>` against
+   * its own table-style gallery and never reads a style definition out of the package,
+   * so a GUID it does not recognise leaves the table with PowerPoint's no-style look —
+   * a black hairline grid. For brand colours use direct formatting instead:
+   * `headerRow`, `columns[i]`, the table-level {@link border} / {@link fill}, or per-cell
+   * options. See `docs/tables.md` → "Apply a built-in table style".
+   *
+   * @example tableStyle: TableStyle.MEDIUM_STYLE_2_ACCENT_1 // import { TableStyle } from 'pptx-ts'
+   */
+  tableStyle?: TableStyle | `{${string}}`;
+  /**
+   * Inline styling for the header (first) row, applied as direct per-cell formatting.
+   *
+   * This is how a header is styled distinctly from the body: each property is merged
+   * onto every cell of row 0 (`fill`, `color`, `bold`, `align`, `border`, etc.).
+   *
+   * Precedence (highest wins), matching how PowerPoint resolves styling — direct cell
+   * formatting overrides a table-style region:
+   * 1. explicit per-cell `options` on a row-0 cell
+   * 2. this `headerRow`
+   * 3. the `firstRow` region of a built-in `tableStyle`
+   * 4. the library's per-cell defaults
+   *
+   * Setting `headerRow` also implies `hasHeader: true` (emits `firstRow="1"` for the
+   * accessibility "table header" marker) unless `hasHeader` is explicitly set to `false`.
+   * @example headerRow: { fill: { color:'1A2B3C' }, color:'FFFFFF', bold:true, align:'center' }
+   */
+  headerRow?: TableCellProps;
+  /**
+   * Per-column default cell styling, applied as direct per-cell formatting.
+   *
+   * `columns[i]` is merged onto every cell that starts in column `i` (`fill`, `color`,
+   * `bold`, `align`, `valign`, `border`, `margin`, …), so a wide **colored** matrix —
+   * per-column fills, maturity-gradient headers — does not require hand-writing a fill
+   * onto every cell. Entries may be sparse (`columns[2]` alone styles only column 2);
+   * an `undefined`/omitted entry leaves that column untouched. The whole option is
+   * optional and degrades cleanly to today's text-on-white when not given.
+   *
+   * Precedence (highest wins), matching how PowerPoint resolves styling — direct cell
+   * formatting overrides a table-style region:
+   * 1. explicit per-cell `options`
+   * 2. `headerRow` (row 0 only)
+   * 3. this `columns[colIdx]`
+   * 4. a built-in `tableStyle` / the library's per-cell defaults
+   *
+   * The merge is property-level, so a header cell keeps `headerRow`'s typography **and**
+   * takes its column's `fill` when they set different properties. For a graduated header
+   * band, put shared header typography (bold/white/centered, **no fill**) in `headerRow`
+   * and let each `columns[i].fill` supply that column's fill.
+   *
+   * Column index is the grid column a cell starts in, counting each cell's `colspan`
+   * (default 1) and the `rowspan`s carried down from earlier rows, so merged cells map to
+   * the correct column.
+   *
+   * There is deliberately no built-in "group bracket" annotation. Label a span of columns
+   * by composing existing primitives: `addShape('rightBrace', …)` (or `'bracePair'`) plus
+   * `addText`, positioned from the table's `x` and `colW` (a span's `x`/`w` is the running
+   * sum of the preceding/covered column widths).
+   *
+   * @example columns: [{}, { fill: { color:'E8F0FE' } }, { fill: { color:'C6DAFC' } }] // per-column solid fills
+   * @example // gradient header: shared typography on headerRow, graduated fills per column
+   * headerRow: { color:'FFFFFF', bold:true, align:'center' },
+   * columns: [{}, { fill:{color:'BBD3FB'} }, { fill:{color:'89AEF6'} }, { fill:{color:'4B7BE5'} }]
+   */
+  columns?: TableCellProps[];
+  /**
+   * Default cell background — **stamped onto every cell**, not painted behind the table.
+   *
+   * Each cell that does not set its own `options.fill` (or take one from `headerRow` /
+   * `columns[i]`) gets this as its own `a:tcPr` fill. A picture fill is embedded once and
+   * shared by every cell that inherits it.
+   *
+   * Visually this is usually what you want, but it is not what a source deck contains, and
+   * it has one real consequence: because every cell ends up explicitly filled, a cell that
+   * later gets its own fill has nothing to fall back to. For a genuine table background —
+   * one `a:tblPr` fill that cells sit on top of — use {@link tableFill}. A bare
+   * {@link Color} is shorthand for a solid fill ({@link FillOption}).
+   * @example 'FF0000' // hex color (red), shorthand for { color:'FF0000' }
+   * @example { color:'FF0000' } // hex color (red)
+   * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
+   * @example { color:SchemeColor.accent1 } // theme color Accent1
+   * @example { type:'image', image:{ path:'watermark.png' } } // picture fill
+   */
+  fill?: FillOption;
+  /**
+   * The table's own background (`a:tblPr` fill) — one fill behind the whole table that
+   * every cell sits on top of.
+   *
+   * The counterpart to {@link fill}, and the difference is where the paint lands rather
+   * than how it looks: `fill` copies a colour onto every cell, while this writes a single
+   * fill on the table itself. That matters when a cell is meant to be transparent — with
+   * `tableFill`, an unfilled cell shows the table background through; with `fill` there is
+   * no such thing as an unfilled cell. It is also what a deck read back from PowerPoint
+   * actually carries, so a replica reproduces the source's structure rather than an
+   * equivalent-looking flattening of it.
+   *
+   * Takes the same {@link FillOption} a cell does — solid, gradient, pattern or picture,
+   * or a bare {@link Color} as shorthand for a solid fill.
+   * @example 'F2F2F2' // shorthand for { color:'F2F2F2' }
+   * @example { color:'F2F2F2' } // a light background behind the whole table
+   * @example { type:'image', image:{ path:'watermark.png' } } // one watermark, not one per cell
+   */
+  tableFill?: FillOption;
+  /**
+   * Cell margin (inches)
+   * - affects all table cells, is superceded by cell options
+   */
+  margin?: Margin;
+  /**
+   * Height of table rows (inches)
+   * - single value is applied to every row equally based upon `h`
+   * - array of values in applied to each row in order
+   *
+   * An entry pins its row only when it is a **number greater than zero**. `0`, a negative
+   * value and anything that does not read as a finite number are not heights, so they do
+   * not pin: the row is sized from the table's `h` instead, or grows to fit if there is
+   * none, and a `table/invalid-row-height` diagnostic says so. A *missing* array slot, or
+   * `null` in it, is different and is silent — that is how an auto-height row is spelled.
+   *
+   * The reading is shared by everything that answers a question about row height: the
+   * emitted `<a:tr h>`, the export-time measured-fit pass, the auto-pager, and
+   * `pptx.tableLayout()`. A prediction that disagreed with what the export bakes would be
+   * worse than no prediction (`docs/contributing/design/text-fit.md`).
+   * @default rows of equal height based upon `h`
+   */
+  rowH?: number | Array<number | null>;
+  /**
+   * DEV-ONLY diagnostic flag: when `true`, logs a verbose trace of the auto-paging
+   * calculations to the console. Intended for debugging table layout only; leave unset
+   * in production. Inherited by {@link TableToSlidesProps}.
+   * @default false
+   */
+  verbose?: boolean;
+}
+interface TableCell {
+  /**
+   * Cell content: a plain string, or an array of `TableCell` runs for mixed formatting.
+   * (A `number` is still coerced to a string at runtime for plain-JS callers, but is no
+   * longer part of the type — pass `String(n)` from TypeScript.)
+   */
+  text?: string | TableCell[];
+  options?: TableCellProps;
+}
+interface TableRowSlide {
+  rows: TableRow[];
+  /**
+   * Per-row height (inches) aligned 1:1 with `rows`, derived from the original `rowH` array.
+   * Auto-paging splits/reorders rows across slides and inserts repeated headers, so the caller's
+   * `rowH[i]` (keyed by *original* row index) can no longer be applied by physical row index on
+   * each generated slide. This carries each output row's resolved height so a configured height
+   * follows its source row instead of being re-applied to whatever lands at that index.
+   * Entries are `undefined` where no explicit height was configured (auto-distributed height).
+   */
+  rowH?: Array<number | undefined>;
+  /**
+   * Where this page's table starts, in inches from the top of the slide: the top the pager budgeted
+   * the page's height from.
+   *
+   * A continuation page starts at `autoPageSlideStartY` when stated, else at the top margin, or at
+   * the table's own `y` when that is higher. Placing the table anywhere else puts it where it was
+   * not measured, so the callers place every page after the first here rather than re-deriving
+   * the rule.
+   */
+  y?: number;
+  /**
+   * The column grid (inches) the pager measured this page against, one entry per grid column.
+   *
+   * The pager resolves `colW` — normalizing a short array, and distributing the usable width
+   * when the caller gave none — and the emitted table has to use the same grid, or the widths
+   * the text was wrapped to are not the widths it is drawn in. This carried it by writing
+   * back onto the options bag it was handed, which made a reused bag change the next call's
+   * output; it rides out here instead.
+   */
+  colW?: number[];
+}
+type TableRow = TableCell[];
+//#endregion
+//#region src/types/animation.d.ts
+/**
+ * Base ECMA-376 slide-transition type (`p:transition`'s single type child). Each
+ * maps to a `<p:TYPE/>` element; type-specific variants (e.g. direction) go in
+ * {@link TransitionProps.variant}. Modern PowerPoint-only transitions (Morph,
+ * Vortex, …) live in the `p14`/`p15`/`p159` namespaces and are out of authoring
+ * scope for now. See `docs/animations-and-transitions.md`.
+ */
+type TransitionType = (typeof TRANSITION_TYPES)[number];
+/**
+ * Slide-show transition applied between slides (`p:transition`). Assign to
+ * {@link Slide.transition}. Setting `durationMs` emits PowerPoint's
+ * `mc:AlternateContent` form (a `p14` Choice carrying `p14:dur` plus a base
+ * `mc:Fallback`); otherwise only the coarse `speed` bucket is written.
+ * @example slide.transition = { type: 'push', durationMs: 1250, variant: { dir: 'd' } }
+ */
+interface TransitionProps {
+  /** Transition type (the `<p:TYPE/>` element), e.g. `fade`, `push`, `wipe`, `cut`, `dissolve`. */
+  type: TransitionType;
+  /** Exact duration in milliseconds (`p14:dur`); emits the `mc:AlternateContent` form. */
+  durationMs?: number;
+  /** Coarse speed bucket (`spd`); derived from `durationMs` when omitted, else defaults to `fast`. */
+  speed?: 'slow' | 'med' | 'fast';
+  /** Advance on mouse click (`advClick`). @default true */
+  advanceOnClick?: boolean;
+  /** Auto-advance after this many milliseconds (`advTm`). */
+  advanceAfterMs?: number;
+  /** Type-specific variant attributes, e.g. `{ dir: 'd' }` for push, `{ spokes: '2' }` for wheel. */
+  variant?: Record<string, string>;
+  /** Sound played with the transition (`p:sndAc`): a start sound (embedded WAV) or the stop-previous form. */
+  sound?: TransitionSoundProps;
+}
+/**
+ * A transition sound (`p:sndAc`). Either a **start sound** — an embedded WAV played
+ * when the transition runs (`p:stSnd` → `p:snd`), optionally looped — or the
+ * **stop-previous** form (`p:endSnd`) that silences a still-playing transition
+ * sound. Built-in PowerPoint sounds embed identically to a custom file, so there is
+ * no separate built-in path: supply the WAV bytes via `data` or `path`.
+ * See `docs/animations-and-transitions.md`.
+ */
+interface TransitionSoundProps {
+  /** Embedded sound bytes as a base64 data URI (e.g. `data:audio/wav;base64,…`) or raw base64. */
+  data?: string;
+  /** Path to a sound file, read at export time (alternative to `data`). */
+  path?: string;
+  /** Display name emitted on `<p:snd @name>` (e.g. `ding.wav`); defaults to the file name. */
+  name?: string;
+  /** Loop the sound until the next sound starts (`<p:stSnd loop="1">`). @default false */
+  loop?: boolean;
+  /** Emit the stop-previous form (`<p:endSnd/>`) instead of a start sound. Mutually exclusive with `data`/`path`. */
+  stopPrevious?: boolean;
+}
+/**
+ * A preset build-animation effect. The supported set is fixed (each is a verbatim
+ * template captured from PowerPoint); adding one means adding a fixture + template,
+ * not a new code path. See `docs/contributing/design/animations.md`.
+ */
+type PresetEffect = 'fadeIn' | 'flyIn' | 'appear' | 'wipe' | 'grow' | 'spin' | 'fadeOut' | 'flyOut';
+/** When a build-animation effect starts relative to the preceding one. */
+type AnimationTrigger = 'onClick' | 'withPrevious' | 'afterPrevious';
+/**
+ * A preset build animation on a shape (entrance/emphasis/exit), added via
+ * {@link Slide.addAnimation}. Target the shape by its 0-based add order
+ * (`shapeIndex`) or by `objectName`. Effects play in the order added, grouped
+ * into click steps by `trigger`.
+ */
+interface AnimationProps {
+  /** The preset effect to play. */
+  preset: PresetEffect;
+  /**
+   * 0-based add order of the target SHAPE on the slide.
+   *
+   * Counts the top-level objects that draw something, so an `addNotes` (or a hyperlink
+   * definition) between two shapes does not shift the shapes after it. Use `objectName` to
+   * target a shape inside a group; an index past the last shape warns and drops the effect.
+   */
+  shapeIndex?: number;
+  /**
+   * Target shape by its `objectName` (alternative to `shapeIndex`). Any shape on the slide,
+   * including one inside a group; an unresolved name warns and drops the effect.
+   */
+  objectName?: string;
+  /** Trigger relative to the previous effect. @default 'onClick' */
+  trigger?: AnimationTrigger;
+  /** Effect duration in milliseconds; preset-specific default when omitted. */
+  durationMs?: number;
+}
+//#endregion
+//#region src/types/master.d.ts
+interface SlideNumberProps extends PositionProps, TextBaseProps {
+  /**
+   * margin (inches) — text-frame internal margin; a value `>= 1` warns as a likely legacy points value
+   */
+  margin?: Margin;
+}
+/**
+ * A chart on a slide master, as a key-tagged descriptor.
+ *
+ * `options` is the spelling every sibling descriptor uses (`shape.options`, `text.options`).
+ * A second, undocumented `opts` alias used to sit beside it and *win* when both were given,
+ * so a caller who set the documented one and left a stray `opts` behind got the stray.
+ */
+interface SlideMasterChartProps {
+  type: CHART_NAME | ChartMulti[];
+  data: OptsChartData[];
+  options?: ChartOpts;
+}
+/**
+ * One object on a slide master, as a key-tagged descriptor.
+ *
+ * The six descriptors it shares with a group child are {@link CommonObjectDescriptor}; the two
+ * below are the master's own — a chart, which a group cannot hold, and a placeholder, which is
+ * the whole point of a master.
+ */
+type SlideMasterObject = CommonObjectDescriptor | {
+  chart: SlideMasterChartProps;
+} | {
+  placeholder: {
+    options: PlaceholderProps;
+    /**
+     * Text to be shown in placeholder (shown until user focuses textbox or adds text)
+     * - Leave blank to have powerpoint show default phrase (ex: "Click to add title")
+     */
+    text?: string;
+  };
+};
+/**
+ * Bullet configuration for one slide-master text-style level (`a:buChar`/`a:buAutoNum`/`a:buNone`).
+ * A focused subset of the run-level bullet model — picture bullets and per-glyph sizing are not
+ * supported in master defaults (those require slide rels). Set `bullet: false` to suppress the
+ * level's bullet entirely.
+ */
+interface MasterBulletProps {
+  /** `'bullet'` emits a character bullet (`a:buChar`); `'number'` emits an auto-number (`a:buAutoNum`). @default 'bullet' */
+  type?: 'bullet' | 'number';
+  /** Bullet character (unicode code point hex), e.g. `'2022'` for •. Used when `type` is `'bullet'`. */
+  characterCode?: string;
+  /** Glyph font typeface for the bullet character (`a:buFont`), e.g. `'Arial'` or `'Wingdings'`. */
+  fontFace?: string;
+  /** Auto-number scheme (`a:buAutoNum@type`) when `type` is `'number'`, e.g. `'arabicPeriod'`. @default 'arabicPeriod' */
+  numberType?: (typeof TEXT_AUTONUM_SCHEMES)[number];
+  /** Starting value for auto-numbered bullets (`a:buAutoNum@startAt`). @default 1 */
+  numberStartAt?: number;
+}
+/**
+ * Styling for one paragraph level (`a:lvlNpPr`) of a slide-master text style. Every field is
+ * optional; an unset field keeps PowerPoint's built-in default for that level. Configure via
+ * {@link SlideMasterProps.textStyles}.
+ */
+interface MasterTextStyleLevel {
+  /** Font size in points (`a:defRPr@sz`), e.g. `24`. */
+  fontSize?: number;
+  /** Font face (`a:defRPr/a:latin@typeface`). Unset keeps the theme font (`+mn-lt`/`+mj-lt`). */
+  fontFace?: string;
+  /** Text color — hex (`'C00000'`) or theme slot (`'tx1'`) — emitted as `a:defRPr/a:solidFill`. */
+  color?: Color;
+  /** Bold text (`a:defRPr@b`). */
+  bold?: boolean;
+  /** Italic text (`a:defRPr@i`). */
+  italic?: boolean;
+  /** Horizontal alignment (`a:lvlNpPr@algn`). */
+  align?: HAlign;
+  /** Left margin in inches (`a:lvlNpPr@marL`); for a hanging bullet this is the text indent. */
+  marginLeft?: number;
+  /** First-line indent in inches (`a:lvlNpPr@indent`); negative produces a hanging bullet. */
+  indent?: number;
+  /** Bullet config: `false` emits `a:buNone`; an object configures a char/number bullet. Unset keeps the level default. */
+  bullet?: boolean | MasterBulletProps;
+}
+/**
+ * Per-level slide-master text styles, written to `slideMaster1.xml`'s `<p:txStyles>`.
+ * Because a deck has a single shared slide master, these styles are **deck-wide**: when set on more
+ * than one `defineSlideMaster()` call the last value for each group (`title`/`body`/`other`) wins.
+ */
+interface MasterTextStyleProps {
+  /** Title placeholder style (`p:titleStyle`, single level). */
+  title?: MasterTextStyleLevel;
+  /** Body placeholder per-level styles (`p:bodyStyle`, levels 1–9; index 0 is `lvl1`). */
+  body?: MasterTextStyleLevel[];
+  /** Other/default placeholder per-level styles (`p:otherStyle`, levels 1–9). */
+  other?: MasterTextStyleLevel[];
+}
+interface SlideMasterProps {
+  /**
+   * Unique name for this master
+   */
+  title: string;
+  background?: BackgroundOption;
+  margin?: Margin;
+  slideNumber?: SlideNumberProps;
+  objects?: SlideMasterObject[];
+  /**
+   * Per-level master text styles (title / body / other) written to the shared slide master's
+   * `<p:txStyles>`. Configure nested bullet character, font size, color, alignment, and indent
+   * for each of the nine list levels. Deck-wide (see {@link MasterTextStyleProps}).
+   * @example textStyles: { body: [{ fontSize: 24, color: 'C00000', bullet: { characterCode: '25AA' } }] }
+   */
+  textStyles?: MasterTextStyleProps;
+}
+//#endregion
+//#region src/types/model3d.d.ts
+/** A point or direction in the model's 3D scene, in metres. */
+interface Model3dPoint {
+  x: number;
+  y: number;
+  z: number;
+}
+/**
+ * Camera override for `addModel3d()`, mapping onto `am3d:camera`.
+ *
+ * The defaults are what PowerPoint itself wrote for a 2×2×2 cube, and they are correct for any
+ * model whose bounding box is roughly cubic **once `meterPerModelUnit` is right** — the camera is
+ * expressed in metres, so the scale is what actually decides framing.
+ *
+ * PowerPoint's own rule, measured against three models: it normalizes the model's largest
+ * bounding-box extent to 1 metre and then places the camera at
+ *
+ * ```
+ * pos.z = |halfExtents / maxExtent| / sin(fov / 2)
+ * ```
+ *
+ * looking at the origin. A caller who knows their model's bounding box can reproduce that
+ * exactly; a caller who does not should at least set `meterPerModelUnit` to `1 / maxExtent`.
+ */
+interface Model3dCameraProps {
+  /**
+   * Camera position in metres (`am3d:camera/am3d:pos`).
+   * @default { x: 0, y: 0, z: 2.2630334 }
+   */
+  pos?: Model3dPoint;
+  /**
+   * Point the camera aims at, in metres (`am3d:camera/am3d:lookAt`).
+   * @default { x: 0, y: 0, z: 0 }
+   */
+  lookAt?: Model3dPoint;
+  /**
+   * Camera "up" direction (`am3d:camera/am3d:up`). Need not be normalized.
+   * @default { x: 0, y: 1, z: 0 }
+   */
+  up?: Model3dPoint;
+  /**
+   * Vertical field of view in **degrees** (`am3d:perspective@fov`).
+   * - range: greater than 0 and less than 180
+   * @default 45
+   */
+  fov?: number;
+}
+/**
+ * Add an embedded 3D model (PowerPoint's Insert ▸ 3D Models) to a slide.
+ *
+ * The `.glb` bytes travel inside the `.pptx` (in `ppt/media/`), so PowerPoint 2019+ renders and
+ * lets the viewer orbit the model. Requires either `data` or `path`. Linked (non-embedded)
+ * models are not supported.
+ */
+interface Model3dBaseProps extends PositionProps, ObjectNameProps {
+  /**
+   * Picture of the model shown wherever the live 3D view is unavailable — a raster image `path`
+   * (Node/local) or base64 `data:` URI.
+   * - the library cannot render a 3D scene, so when this is omitted a neutral gray placeholder is
+   *   embedded; PowerPoint 2019+ draws the live model on screen, in exports and in print, but older
+   *   PowerPoint and applications without a 3D renderer show exactly what is here
+   * - supply a real render whenever the deck is meant to read correctly outside PowerPoint
+   * @example { path: 'assets/engine-render.png' }
+   */
+  preview?: {
+    path?: string;
+    data?: string;
+  };
+  /**
+   * Camera override. Omitted, ts-pptx emits the camera PowerPoint wrote for a 2×2×2 cube.
+   * @see {@link Model3dCameraProps} for the framing formula and when this matters.
+   */
+  camera?: Model3dCameraProps;
+  /**
+   * Metres per model unit (`am3d:trans/am3d:meterPerModelUnit`) — the scale that decides how
+   * large the model is in the scene the {@link camera} looks at.
+   *
+   * This is the single override most models need. PowerPoint sets it to `1 / maxExtent`, where
+   * `maxExtent` is the model's largest bounding-box dimension in model units, which normalizes
+   * every model to 1 metre across. ts-pptx does not parse the `.glb`, so it cannot measure that
+   * — it defaults to `0.5`, correct for a model 2 units across. A model 100 units across left at
+   * the default is a 50-metre object with the camera 2.26 metres from its centre, i.e. the
+   * viewer is inside it.
+   * - range: greater than 0
+   * @default 0.5
+   * @example 1 / 100 // a model whose largest bounding-box dimension is 100 units
+   */
+  meterPerModelUnit?: number;
+  /**
+   * Alt text (`p:cNvPr@descr`) — what a screen reader announces for the model.
+   */
+  altText?: string;
+}
+/**
+ * Options for `slide.addModel3d()`. Requires either `data` (base64, with or without a
+ * `data:...;base64,` header) or `path` (a local/remote `.glb` read at export time).
+ *
+ * Sizing note: `w`/`h` default to 4 × 3 inches rather than being measured. A 3D model has no
+ * intrinsic aspect ratio, and the library never opens the payload.
+ */
+type Model3dProps = Model3dBaseProps & DataOrPathRequiredProps;
+//#endregion
+//#region src/types/zoom.d.ts
+/** Options shared by all three zoom kinds. */
+interface ZoomBaseProps extends PositionProps {
+  /** Object name (PowerPoint selection-pane label). Auto-named (e.g. `Slide Zoom 3`) when omitted. */
+  objectName?: string;
+  /**
+   * Ship a caller-supplied thumbnail instead of the gray placeholder — a raster image `path`
+   * (Node/local) or base64 `data:` URI. Shown as-authored (not auto-refreshed by PowerPoint).
+   */
+  coverImage?: {
+    path?: string;
+    data?: string;
+  };
+  /**
+   * After the zoom animates to its target, return to this (parent) slide when the target's
+   * content finishes. Maps to `zmPr@returnToParent`. Default `false`.
+   */
+  returnToParent?: boolean;
+  /** Zoom transition duration in milliseconds (`zmPr@transitionDur`). Default `1000`. */
+  transitionDur?: number;
+  /**
+   * Object lock flags ({@link ObjectLockProps}), as `objectLock` on every other object type.
+   *
+   * A zoom is a `p:graphicFrame`, so these land on its `a:graphicFrameLocks` and the flags that
+   * apply are the graphic-frame ones (`noGrp`, `noDrilldown`, `noSelect`, `noChangeAspect`,
+   * `noMove`, `noResize`); a picture-only flag warns and is dropped, as everywhere else. The
+   * `mc:Fallback` picture keeps its own fixed lock set — it is what pre-2016 consumers draw, and
+   * folding a graphic-frame flag set onto a `a:picLocks` element would warn about every flag the
+   * two element types do not share.
+   *
+   * `noChangeAspect` is on by default (a zoom tile mirrors its target slide's aspect); pass it
+   * `false` to lift it.
+   * @example { noMove: true, noResize: true } // pin the tile in place
+   */
+  objectLock?: ObjectLockProps;
+}
+/** Slide Zoom: a tile that zooms to a single target slide. */
+interface SlideZoomProps extends ZoomBaseProps {
+  /** Target slide — a `Slide` returned by `addSlide()`, or its 1-based slide number. */
+  target: Slide | number;
+}
+/** Section Zoom: a tile that zooms to the start of a named section. */
+interface SectionZoomProps extends ZoomBaseProps {
+  /** Title of the target section (as passed to `addSection({ title })`). */
+  sectionTitle: string;
+}
+/**
+ * Summary Zoom: a grid of tiles, one per section, that navigates to each section's start.
+ * The section containing the host slide is excluded (a summary does not link to itself).
+ */
+type SummaryZoomProps = ZoomBaseProps;
+//#endregion
+//#region src/types/slide.d.ts
+/**
+ * A child object that can be placed inside a group via `slide.addGroup()`.
+ *
+ * The six descriptors it shares with `SlideMasterObject` are {@link CommonObjectDescriptor};
+ * `group` is the group's own, and the master's `chart` and `placeholder` are deliberately not
+ * here. A `group` child nests another group (an identity child
+ * coordinate space is kept at every depth, so descendants keep their slide-absolute
+ * coordinates). Charts, media, tables, and placeholders are intentionally excluded (see
+ * `addGroup`); passing one logs a warning and skips it.
+ */
+type GroupChildProps = CommonObjectDescriptor | {
+  group: {
+    children: GroupChildProps[];
+    options?: GroupProps;
+  };
+};
+/**
+ * Options for `slide.addGroup()`.
+ *
+ * The group keeps an identity child coordinate space (`chOff/chExt == off/ext`) at every depth:
+ * children — including nested groups — keep their slide-absolute `x/y/w/h`. A consequence worth
+ * knowing: a group's own frame never moves or scales its children, it only places the selection
+ * handle and the rotate pivot.
+ *
+ * The frame is all-or-nothing. Pass all four of `x/y/w/h` to set it explicitly, or none to have it
+ * auto-computed as the bounding box of the children. A partial frame is ambiguous, so it warns and
+ * falls back to auto-bounds on every axis.
+ */
+interface GroupProps extends PositionProps, ObjectNameProps {
+  /** Rotation in degrees (applied to the whole group) */
+  rotate?: number;
+  /** Flip the group horizontally */
+  flipH?: boolean;
+  /** Flip the group vertically */
+  flipV?: boolean;
+}
+interface ObjectOptions extends ImageBaseProps, PositionProps, ShapeProps, TableCellProps, TextPropsOptions {
+  cx?: Coord;
+  cy?: Coord;
+  margin?: Margin;
+  colW?: number | number[];
+  rowH?: number | Array<number | null>;
+  hasHeader?: boolean;
+  hasFooter?: boolean;
+  hasBandedRows?: boolean;
+  hasBandedColumns?: boolean;
+  hasFirstColumn?: boolean;
+  hasLastColumn?: boolean;
+  rtl?: boolean;
+  tableStyle?: TableStyle | `{${string}}`;
+  /**
+   * Table perimeter border. `addTableDefinition` normalizes it to a 4-tuple (TRBL, sides
+   * left unset as `undefined`) before it reaches the emitter, so the serializer never has
+   * to re-handle the single-`BorderProps` form.
+   */
+  outerBorder?: TableProps['outerBorder'];
+  /** Table background (`a:tblPr` fill), as distinct from `fill`, which is stamped onto each cell. */
+  tableFill?: TableProps['tableFill'];
+}
+interface SlideLayout {
+  background?: BackgroundOption | undefined;
+}
+/**
+ * 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[];
+}
+/**
+ * A slide as the authoring API presents it.
+ *
+ * The four settable properties (`transition`, `background`, `color`, `slideNumber`) admit an
+ * explicit `undefined`, which is not the loophole it looks like under
+ * `exactOptionalPropertyTypes`: `SlideBuilder` implements them as accessor pairs, so the property
+ * is *always* present on a real slide and its getter answers `undefined` when nothing is set.
+ * There is no absent state for the declaration to describe. Writing one is also how the setters
+ * are cleared — `slide.transition = undefined` removes the `p:transition` — and an interface that
+ * could not express the value its own setter takes would be describing a different type.
+ */
+interface Slide {
+  addChart(data: OptsChartData[], options: ChartOpts & {
+    type: CHART_NAME;
+  }): Slide;
+  addChart(charts: ChartMulti[], options?: ChartOpts): Slide;
+  addConnector: (options: ConnectorProps) => Slide;
+  addImage: (options: ImageProps) => Slide;
+  addMedia: (options: MediaProps) => Slide;
+  /** Embed a 3D model (Insert ▸ 3D Models) — a `.glb` PowerPoint 2019+ renders live. */
+  addModel3d: (options: Model3dProps) => Slide;
+  /** Embed an OLE object (Insert ▸ Object) whose bytes travel inside the `.pptx`. */
+  addOleObject: (options: OleObjectProps) => Slide;
+  addComment: (options: CommentProps) => Slide;
+  addNotes: (notes: string | NotesProps | NotesProps[]) => Slide;
+  addShape: (shapeName: SHAPE_NAME, options?: ShapeProps) => Slide;
+  addTable: (tableRows: TableRow[], options?: TableProps) => Slide;
+  addText: (text: string | number | TextProps[], options?: TextPropsOptions) => Slide;
+  addAnimation: (options: AnimationProps) => Slide;
+  /** Group child object descriptors into a single PowerPoint group (`<p:grpSp>`). */
+  addGroup: (children: GroupChildProps[], options?: GroupProps) => Slide;
+  /** Group objects already on this slide, addressed by their `objectName`, into a single group. */
+  groupObjects: (objectNames: string[], options?: GroupProps) => Slide;
+  /**
+   * Add a Slide Zoom — a clickable tile that zooms to a single target slide (Insert ▸ Zoom).
+   * @example slide.addSlideZoom({ target: intro, x: 1, y: 1, w: 3, h: 1.7 })
+   */
+  addSlideZoom: (options: SlideZoomProps) => Slide;
+  /**
+   * Add a Section Zoom — a clickable tile that zooms to the start of a named section.
+   * @example slide.addSectionZoom({ sectionTitle: 'Results', x: 1, y: 1, w: 3, h: 1.7 })
+   */
+  addSectionZoom: (options: SectionZoomProps) => Slide;
+  /**
+   * Add a Summary Zoom — a grid of tiles, one per section (excluding this slide's own section).
+   * @example slide.addSummaryZoom({ x: 0.5, y: 1.5, w: 11, h: 4.5 })
+   */
+  addSummaryZoom: (options: SummaryZoomProps) => 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[];
+  /**
+   * Every continuation slide this slide's auto-paging tables have spilled onto, in call order.
+   *
+   * Across calls, and each slide once: a slide can carry several `addTable`s, each appends what
+   * it spilled onto, and a later table lands on an earlier one's continuations rather than making
+   * its own. So this names all of them rather than only the most recent table's.
+   * @example
+   * slide.addTable(rows, { autoPage: true })
+   * for (const made of slide.newAutoPagedSlides) made.addText('continued', { x: 0.5, y: 0.2 })
+   */
+  readonly newAutoPagedSlides?: Slide[];
+  /**
+   * Slide-show transition played when advancing to this slide (`p:transition`).
+   * @example slide.transition = { type: 'fade', durationMs: 1500 }
+   */
+  transition?: TransitionProps | undefined;
+  /**
+   * Slide width in inches, resolved from the active presentation layout.
+   * Use for coordinate math instead of hard-coding layout dimensions.
+   * @example slide.addText('Centered', { x: 0, w: slide.width, align: 'center' })
+   */
+  readonly width?: number;
+  /**
+   * Slide height in inches, resolved from the active presentation layout.
+   */
+  readonly height?: number;
+  /**
+   * Background color or image (`color` | `path` | `data`)
+   * @example { color: 'FF3399' } - hex color
+   * @example { color: 'FF3399', transparency:50 } - hex color with 50% transparency
+   * @example { path: 'https://onedrives.com/myimg.png` } - retrieve image via URL
+   * @example { path: '/home/user/images/myimg.png` } - retrieve image via local path
+   * @example { data: 'image/png;base64,iVtDaDrF[...]=' } - base64 string
+   */
+  background?: BackgroundOption | undefined;
+  /**
+   * Default text color (hex format)
+   * @example 'FF3399'
+   * @default '000000' (DEF_FONT_COLOR)
+   */
+  color?: HexColor | undefined;
+  /**
+   * Whether slide is hidden
+   * @default false
+   */
+  hidden?: boolean;
+  /**
+   * Slide number options
+   */
+  slideNumber?: SlideNumberProps | undefined;
+}
+interface AddSlideProps {
+  /** Title of the slide master to use for the new slide (the `title` passed to {@link SlideMasterProps} via `defineSlideMaster`). */
+  masterTitle?: string;
+  sectionTitle?: string;
+}
+//#endregion
+export { TableCellDiagonals as A, AnimationTrigger as C, TransitionType as D, TransitionSoundProps as E, TableToSlidesDocument as F, TableToSlidesElement as I, TableToSlidesProps as L, TableProps as M, TableRow as N, TableCell as O, TableRowSlide as P, AnimationProps as S, TransitionProps as T, MasterTextStyleProps as _, Slide as a, SlideMasterProps as b, SectionZoomProps as c, ZoomBaseProps as d, Model3dCameraProps as f, MasterTextStyleLevel as g, MasterBulletProps as h, ObjectOptions as i, TableCellProps as j, TableCell3DProps as k, SlideZoomProps as l, Model3dProps as m, GroupChildProps as n, SlideLayout as o, Model3dPoint as p, GroupProps as r, SlideObjectInfo as s, AddSlideProps as t, SummaryZoomProps as u, SlideMasterChartProps as v, PresetEffect as w, SlideNumberProps as x, SlideMasterObject as y };
+//# sourceMappingURL=slide-Dx2ZeVZ6.d.ts.map