@shbernal/ts-pptx 1.0.0 → 3.0.0

package/dist/{slide-B6mDaM-P.d.ts → slide-YuSCGa45.d.ts}

@@ -1,4 +1,4 @@
-import { _ as TextAnchor, f as SHAPE_NAME, g as TableStyle, h as SlideObjectType, i as CHART_NAME, l as PLACEHOLDER_TYPE, t as AlignH } from "./enums-D3aF4QGb.js";
+import { _ as TextAnchor, f as SHAPE_NAME, g as TableStyle, h as SlideObjectType, i as CHART_NAME, l as PLACEHOLDER_TYPE, t as AlignH } from "./enums-oLLeaSW3.js";
 //#region src/types/text.d.ts
 interface TextBaseProps {
   /**
@@ -1475,6 +1475,72 @@ interface ChartOpts extends ChartPropsAxisCat, ChartPropsAxisSer, ChartPropsAxis
   metadata?: Record<string, string>;
 }
 //#endregion
+//#region src/ooxml/st-enums.d.ts
+/**
+ * `ST_` simple-type enumerations from ECMA-376, declared once as the single source of both the
+ * TypeScript union a caller is checked against and the runtime list a value is validated against.
+ *
+ * **The problem this solves.** Each of these used to exist twice: a hand-written string union in
+ * `src/types/` (what the compiler enforces) and a hand-written array in `src/gen/` or `src/read/`
+ * (what the validator checks at run time). Nothing tied the two together, so adding a member to
+ * one and not the other produced either a value TypeScript accepts and the validator drops, or a
+ * value the validator passes and the type rejects. Two of them had already diverged in *order*,
+ * which is harmless, but nothing would have caught a divergence in *content*.
+ *
+ * **The shape.** Every entry is a `readonly` tuple declared `as const`, with its union derived via
+ * `(typeof X)[number]`. Widening the tuple widens the union in the same edit — they cannot drift.
+ * This is the idiom already used for `EMBEDDED_FONT_SLOTS` and `EXTRA_SHAPE_PRESETS`; this module
+ * brings the stragglers onto it.
+ *
+ * **Why this module is neither `gen/` nor `read/`.** `src/types/` needs the unions for the public
+ * write API, `src/gen/` needs the tuples to vet a value before emitting it, and `src/read/` needs
+ * them to vet a value before writing it into a loaded part. It is a fact about the schema, so it
+ * belongs to none of the three.
+ *
+ * Values are listed in **schema declaration order**, which is the order the diagnostics print
+ * when they tell a caller what is legal.
+ */
+/**
+ * `ST_BevelPresetType` — the bevel profile applied to a 3-D edge.
+ * @see ECMA-376 Part 1 §20.1.10.9
+ */
+declare const BEVEL_PRESETS: readonly ["relaxedInset", "circle", "slope", "cross", "angle", "softRound", "convex", "coolSlant", "divot", "riblet", "hardEdge", "artDeco"];
+type BevelPresetType = (typeof BEVEL_PRESETS)[number];
+/**
+ * `ST_PresetMaterialType` — how a 3-D surface responds to light.
+ * @see ECMA-376 Part 1 §20.1.10.50
+ */
+declare const PRESET_MATERIALS: readonly ["legacyMatte", "legacyPlastic", "legacyMetal", "legacyWireframe", "matte", "plastic", "metal", "warmMatte", "translucentPowder", "powder", "dkEdge", "softEdge", "clear", "flat", "softmetal"];
+type PresetMaterialType = (typeof PRESET_MATERIALS)[number];
+/**
+ * `ST_LightRigType` — the preset lighting scene.
+ * @see ECMA-376 Part 1 §20.1.10.35
+ */
+declare const LIGHT_RIGS: readonly ["legacyFlat1", "legacyFlat2", "legacyFlat3", "legacyFlat4", "legacyNormal1", "legacyNormal2", "legacyNormal3", "legacyNormal4", "legacyHarsh1", "legacyHarsh2", "legacyHarsh3", "legacyHarsh4", "threePt", "balanced", "soft", "harsh", "flood", "contrasting", "morning", "sunrise", "sunset", "chilly", "freezing", "flat", "twoPt", "glow", "brightRoom"];
+type LightRigType = (typeof LIGHT_RIGS)[number];
+/**
+ * `ST_LightRigDirection` — where the light rig sits relative to the scene.
+ * @see ECMA-376 Part 1 §20.1.10.33
+ */
+declare const LIGHT_RIG_DIRECTIONS: readonly ["tl", "t", "tr", "l", "r", "bl", "b", "br"];
+type LightRigDirection = (typeof LIGHT_RIG_DIRECTIONS)[number];
+/**
+ * `ST_TextVerticalType` — `a:bodyPr/@vert` and `a:tcPr/@vert`.
+ * @see ECMA-376 Part 1 §20.1.10.83
+ */
+declare const TEXT_VERTICAL: readonly ["horz", "vert", "vert270", "wordArtVert", "eaVert", "mongolianVert", "wordArtVertRtl"];
+type TextVerticalType = (typeof TEXT_VERTICAL)[number];
+/**
+ * `ST_PresetLineDashVal` — the dash pattern of a line or border (`a:prstDash/@val`).
+ *
+ * The `sys*` members are the "system" dashes whose exact dot/gap ratio the renderer picks; the
+ * rest are defined by the spec. Both `BorderProps.dashType` and `ShapeLineProps.dashType` accept
+ * this whole set, so a caller who knows one knows the other.
+ * @see ECMA-376 Part 1 §20.1.10.49
+ */
+declare const PRESET_LINE_DASHES: readonly ["solid", "dot", "dash", "lgDash", "dashDot", "lgDashDot", "lgDashDotDot", "sysDash", "sysDot", "sysDashDot", "sysDashDotDot"];
+type PresetLineDashVal = (typeof PRESET_LINE_DASHES)[number];
+//#endregion
 //#region src/types/style.d.ts
 interface BorderProps {
   /**
@@ -1482,6 +1548,21 @@ interface BorderProps {
    * @default solid
    */
   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'
@@ -1631,10 +1712,11 @@ interface ShapeLineProps extends ShapeFillProps {
    */
   width?: number;
   /**
-   * Dash type
+   * Dash type — the full `ST_PresetLineDashVal` set, so any dash a source deck can
+   * carry can also be authored and replicated.
    * @default 'solid'
    */
-  dashType?: 'solid' | 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'sysDash' | 'sysDot';
+  dashType?: PresetLineDashVal;
   /**
    * Line end cap style
    * @default 'flat'
@@ -1922,7 +2004,7 @@ type VAlign = 'top' | 'middle' | 'bottom';
  * Text body `vert` attribute — flow/rotation direction of the text within its box.
  * Maps to `<a:bodyPr vert="…">` (ECMA-376 `ST_TextVerticalType`).
  */
-type TextVertType = 'eaVert' | 'horz' | 'mongolianVert' | 'vert' | 'vert270' | 'wordArtVert' | 'wordArtVertRtl';
+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
@@ -2149,9 +2231,15 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
    * - When a `data` (base64) image is supplied and `w`/`h` are omitted, the natural pixel
    *   size is read from the image header (PNG/JPEG/GIF/BMP/WebP) and used at 96 DPI
    *   (natural pixels / 96 = inches).
-   * - When only one of `w`/`h` is given, the other is derived from the natural aspect ratio.
-   * - `path` images and vector (SVG) data cannot be measured synchronously, so an omitted
-   *   dimension falls back to 1 inch.
+   * - 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?")
@@ -2260,31 +2348,38 @@ interface ImageBaseProps extends PositionProps, ObjectNameProps {
   };
   /**
    * 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
    */
   sizing?: {
     /**
      * Sizing type
      * - `cover` / `contain` fit the image into the `w`×`h` box using the image's *natural*
-     *   pixel aspect ratio (read from the embedded PNG/JPEG/GIF/BMP/WebP header). If the
-     *   natural size cannot be determined (e.g. SVG or an unrecognized format) the displayed
-     *   `w`/`h` ratio is used as a fallback and a warning is logged.
+     *   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';
+    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;
+    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;
+    h?: Coord;
     /**
      * Offset from left to crop image
      * - `crop` only
@@ -2592,6 +2687,63 @@ interface TableToSlidesProps extends TableProps {
    */
   slideMargin?: Margin;
 }
+/**
+ * A table cell's corner-to-corner rules (`a:tcPr/a:lnTlToBr` / `a:lnBlToTr`) — the
+ * "Diagonal Down Border" / "Diagonal Up Border" of PowerPoint's border gallery.
+ *
+ * Deliberately its own object rather than two more entries on {@link TableCellProps.border}'s
+ * tuple: widening that tuple to six would break every existing caller for a construct almost
+ * no deck uses, and the two diagonals are not edges — they do not participate in the
+ * perimeter, and they are not inherited by a merged region's covered cells.
+ *
+ * @example diagonal: { tlToBr: { type:'solid', color:'C00000', width:1 } } // strike a cell out
+ * @example diagonal: { tlToBr: { type:'solid' }, blToTr: { type:'solid' } } // an X across the cell
+ */
+interface TableCellDiagonals {
+  /** Top-left to bottom-right (`╲`, `a:lnTlToBr`). */
+  tlToBr?: BorderProps;
+  /** Bottom-left to top-right (`╱`, `a:lnBlToTr`). */
+  blToTr?: BorderProps;
+}
+/**
+ * A cell's 3-D bevel (`a:tcPr/a:cell3D`).
+ *
+ * A minimal surface over `CT_Cell3D`, which is a required `a:bevel` plus an optional
+ * `a:lightRig`. PowerPoint's table UI exposes no control for it — it reaches a deck through a
+ * theme's table style or through another producer — so this exists to author and reproduce
+ * one, not as a general 3-D model.
+ */
+interface TableCell3DProps {
+  /**
+   * The bevel's preset shape (`a:bevel/@prst`).
+   * @default 'circle'
+   */
+  preset?: BevelPresetType;
+  /**
+   * Bevel width in points (`a:bevel/@w`; the attribute is EMU).
+   * @default 6 // 76200 EMU
+   */
+  width?: number;
+  /**
+   * Bevel height in points (`a:bevel/@h`; the attribute is EMU).
+   * @default 6 // 76200 EMU
+   */
+  height?: number;
+  /**
+   * Surface material (`a:cell3D/@prstMaterial`), which decides how the bevel takes light.
+   * @default 'plastic'
+   */
+  material?: PresetMaterialType;
+  /**
+   * Scene lighting (`a:cell3D/a:lightRig`). Both fields are required by the schema, so
+   * either give both or omit the whole object and let the renderer light the bevel.
+   * @example lightRig: { rig: 'threePt', dir: 't' }
+   */
+  lightRig?: {
+    rig: LightRigType;
+    dir: LightRigDirection;
+  };
+}
 interface TableCellProps extends TextBaseProps {
   /**
    * Auto-paging character weight
@@ -2610,9 +2762,44 @@ interface TableCellProps extends TextBaseProps {
    */
   autoPageLineWeight?: number;
   /**
-   * Cell border
+   * 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. For the two corner-to-corner rules see {@link diagonal}; for the
+   * table's outside edge see {@link TableProps.outerBorder}.
    */
   border?: BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps];
+  /**
+   * 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
    */
@@ -2629,6 +2816,24 @@ interface TableCellProps extends TextBaseProps {
    * @example { image:{ data:'image/png;base64,…' } } // picture fill, `type` inferred
    */
   fill?: ShapeFillProps;
+  /**
+   * What happens to a **single glyph** wider than the cell's text width (`a:tcPr/@horzOverflow`).
+   * - `'clip'` (PowerPoint's default) cuts the glyph off at the cell edge
+   * - `'overflow'` lets it draw past the edge, over whatever is beside it
+   *
+   * This is **not** a text-wrap switch, despite the name. Lines always wrap to the column
+   * width; only an individual character too wide to fit on a line by itself is affected, so
+   * it matters for oversized display type, wide CJK/emoji glyphs, and icon fonts in a narrow
+   * column. PowerPoint has no per-cell no-wrap at all — `wrap="none"` on a cell's `a:bodyPr`
+   * is discarded on the next save (probe:
+   * `test/read/fixtures/authoring/probe-table-cell-wrap.ps1`).
+   * `'clip'` is written as asked but is the schema default, so PowerPoint drops the
+   * attribute again the first time it saves the deck — the visible result is the same
+   * either way, and leaving this unset emits nothing at all.
+   * @default (unset — PowerPoint clips)
+   * @example 'overflow' // a 60pt glyph in a 0.5in column draws whole instead of being cut
+   */
+  horzOverflow?: 'clip' | 'overflow';
   hyperlink?: HyperlinkProps;
   /**
    * Cell margin (inches)
@@ -2658,74 +2863,6 @@ interface TableCellProps extends TextBaseProps {
    */
   fit?: 'none' | 'shrink' | 'resize' | TextFitShrinkProps;
 }
-/**
- * Styling for one region of a custom table style (maps to a `CT_TablePartStyle`).
- * A region (e.g. the header row or banded rows) is shown only when the matching
- * `TableProps` flag is set — `firstRow` needs `hasHeader`, `band1H`/`band2H` need
- * `hasBandedRows`, and so on.
- * @see TableStyleProps
- */
-interface TableStyleRegionProps {
-  /**
-   * Solid cell fill color (hex).
-   * - `HexColor` only; theme references are not supported in custom styles
-   * @example '1A2B3C'
-   */
-  fill?: HexColor;
-  /**
-   * Text color (hex).
-   * @example 'FFFFFF'
-   */
-  color?: HexColor;
-  /** Bold text. */
-  bold?: boolean;
-  /** Italic text. */
-  italic?: boolean;
-  /**
-   * Cell border(s).
-   * - single value is applied to all four sides plus the interior grid lines
-   * - array of values in TRBL order styles only the four outer sides
-   */
-  border?: BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps];
-}
-/**
- * A reusable custom table style written to `ppt/tableStyles.xml`.
- * Pass to `pptx.defineTableStyle()`, which registers it and returns a GUID to use
- * as `TableProps.tableStyle`. Unlike the fixed built-in `TableStyle` set, a custom
- * style can use arbitrary brand colors, is editable in PowerPoint's Table Styles
- * gallery, and bands correctly across any row/column count (including auto-paged tables).
- * @example
- * const brand = pptx.defineTableStyle({
- *   name: 'Brand Banded',
- *   wholeTbl: { border: { type:'solid', color:'D9D9D9', width:0.5 } },
- *   firstRow: { fill:'1A2B3C', color:'FFFFFF', bold:true },
- *   band1H:   { fill:'EAF1F8' },
- *   band2H:   { fill:'FFFFFF' },
- * })
- * slide.addTable(rows, { tableStyle: brand, hasHeader:true, hasBandedRows:true })
- */
-interface TableStyleProps {
-  /** Display name shown in PowerPoint's Table Styles gallery. */
-  name: string;
-  /** Base styling applied to every cell. */
-  wholeTbl?: TableStyleRegionProps;
-  /** Header (first) row — activated by `TableProps.hasHeader`. */
-  firstRow?: TableStyleRegionProps;
-  /** Footer (last) row — activated by `TableProps.hasFooter`. */
-  lastRow?: TableStyleRegionProps;
-  /** First column — activated by `TableProps.hasFirstColumn`. */
-  firstCol?: TableStyleRegionProps;
-  /** Last column — activated by `TableProps.hasLastColumn`. */
-  lastCol?: TableStyleRegionProps;
-  /** Odd horizontal band — activated by `TableProps.hasBandedRows`. */
-  band1H?: TableStyleRegionProps;
-  /** Even horizontal band — activated by `TableProps.hasBandedRows`. */
-  band2H?: TableStyleRegionProps;
-  /** Odd vertical band — activated by `TableProps.hasBandedColumns`. */
-  band1V?: TableStyleRegionProps;
-  /** Even vertical band — activated by `TableProps.hasBandedColumns`. */
-  band2V?: TableStyleRegionProps;
-}
 interface TableProps extends PositionProps, TextBaseProps, ObjectNameProps {
   _arrObjTabHeadRows?: TableRow[];
   /**
@@ -2786,11 +2923,41 @@ interface TableProps extends PositionProps, TextBaseProps, ObjectNameProps {
    */
   autoPagePlaceholder?: boolean;
   /**
-   * Table border
-   * - single value is applied to all 4 sides
-   * - array of values in TRBL order for individual sides
+   * 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.
+   *
+   * 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, BorderProps, BorderProps, BorderProps];
+  /**
+   * 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`
@@ -2875,30 +3042,34 @@ interface TableProps extends PositionProps, TextBaseProps, ObjectNameProps {
    */
   rtl?: boolean;
   /**
-   * Table style to apply, either a built-in `TableStyle` member or the GUID
-   * returned by `pptx.defineTableStyle()` for a custom style.
+   * Built-in table style to apply, as a `TableStyle` member.
    * Emits `<a:tableStyleId>` inside `<a:tblPr>` with the corresponding GUID.
    * Style flags (`hasHeader`, `hasFooter`, `hasBandedRows`, etc.) select which
    * regions of the chosen style are activated; they have no visible effect without
    * a `tableStyle` set.
    *
-   * @example tableStyle: pptx.TableStyle.MEDIUM_STYLE_2_ACCENT_1 // built-in
-   * @example const brand = pptx.defineTableStyle({ name:'Brand', firstRow:{ fill:'1A2B3C', color:'FFFFFF', bold:true } }); tableStyle: brand
+   * **Only a built-in GUID renders.** PowerPoint resolves `<a:tableStyleId>` against
+   * its own table-style gallery and never reads a style definition out of the package,
+   * so a GUID it does not recognise leaves the table with PowerPoint's no-style look —
+   * a black hairline grid. For brand colours use direct formatting instead:
+   * `headerRow`, `columns[i]`, the table-level {@link border} / {@link fill}, or per-cell
+   * options. See `docs/tables.md` → "Table styles".
+   *
+   * @example tableStyle: pptx.TableStyle.MEDIUM_STYLE_2_ACCENT_1
    */
-  tableStyle?: TableStyle | string;
+  tableStyle?: TableStyle;
   /**
    * Inline styling for the header (first) row, applied as direct per-cell formatting.
    *
-   * Convenience shortcut for styling a header distinctly from the body **without** first
-   * registering a custom style via `pptx.defineTableStyle({ firstRow })`. Each property is
-   * merged onto every cell of row 0 (`fill`, `color`, `bold`, `align`, `border`, etc.).
+   * 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 any `tableStyle`
-   * 4. `wholeTbl` / defaults
+   * 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`.
@@ -2920,7 +3091,7 @@ interface TableProps extends PositionProps, TextBaseProps, ObjectNameProps {
    * 1. explicit per-cell `options`
    * 2. `headerRow` (row 0 only)
    * 3. this `columns[colIdx]`
-   * 4. `wholeTbl` / `tableStyle` / defaults
+   * 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
@@ -2942,16 +3113,39 @@ interface TableProps extends PositionProps, TextBaseProps, ObjectNameProps {
    */
   columns?: TableCellProps[];
   /**
-   * Default cell background for every cell in the table — a solid color or a
-   * picture fill. Superseded per cell by `options.fill`, `headerRow`, and
-   * `columns[i]`. A picture fill is embedded once and shared by every cell that
-   * inherits it.
+   * Default cell background — **stamped onto every cell**, not painted behind the table.
+   *
+   * Each cell that does not set its own `options.fill` (or take one from `headerRow` /
+   * `columns[i]`) gets this as its own `a:tcPr` fill. A picture fill is embedded once and
+   * shared by every cell that inherits it.
+   *
+   * Visually this is usually what you want, but it is not what a source deck contains, and
+   * it has one real consequence: because every cell ends up explicitly filled, a cell that
+   * later gets its own fill has nothing to fall back to. For a genuine table background —
+   * one `a:tblPr` fill that cells sit on top of — use {@link tableFill}.
    * @example { color:'FF0000' } // hex color (red)
    * @example { color:'0088CC', transparency:50 } // hex color, 50% transparent
    * @example { color:SchemeColor.accent1 } // theme color Accent1
    * @example { type:'image', image:{ path:'watermark.png' } } // picture fill
    */
   fill?: ShapeFillProps;
+  /**
+   * The table's own background (`a:tblPr` fill) — one fill behind the whole table that
+   * every cell sits on top of.
+   *
+   * The counterpart to {@link fill}, and the difference is where the paint lands rather
+   * than how it looks: `fill` copies a colour onto every cell, while this writes a single
+   * fill on the table itself. That matters when a cell is meant to be transparent — with
+   * `tableFill`, an unfilled cell shows the table background through; with `fill` there is
+   * no such thing as an unfilled cell. It is also what a deck read back from PowerPoint
+   * actually carries, so a replica reproduces the source's structure rather than an
+   * equivalent-looking flattening of it.
+   *
+   * Takes the same `ShapeFillProps` a cell does — solid, gradient, pattern or picture.
+   * @example { color:'F2F2F2' } // a light background behind the whole table
+   * @example { type:'image', image:{ path:'watermark.png' } } // one watermark, not one per cell
+   */
+  tableFill?: ShapeFillProps;
   /**
    * Cell margin (inches)
    * - affects all table cells, is superceded by cell options
@@ -3228,6 +3422,108 @@ interface SlideMasterProps {
   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 over it, but every other consumer — and
+   *   PowerPoint's own `mc:Fallback` path, thumbnails, and PDF export — shows exactly what is here
+   * - supply a real render whenever the deck is meant to read correctly outside PowerPoint
+   * @example { path: 'assets/engine-render.png' }
+   */
+  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/slide.d.ts
 /**
  * A child object that can be placed inside a group via `slide.addGroup()`.
@@ -3320,7 +3616,15 @@ interface ObjectOptions extends ImageBaseProps, PositionProps, ShapeProps, Table
   hasFirstColumn?: boolean;
   hasLastColumn?: boolean;
   rtl?: boolean;
-  tableStyle?: TableStyle | string;
+  tableStyle?: TableStyle;
+  /**
+   * Table perimeter border. `addTableDefinition` normalizes it to a 4-tuple (TRBL, sides
+   * left unset as `undefined`) before it reaches the emitter, so the serializer never has
+   * to re-handle the single-`BorderProps` form.
+   */
+  outerBorder?: TableProps['outerBorder'];
+  /** Table background (`a:tblPr` fill), as distinct from `fill`, which is stamped onto each cell. */
+  tableFill?: TableProps['tableFill'];
 }
 interface SlideLayout {
   background?: BackgroundProps;
@@ -3333,6 +3637,8 @@ interface 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;
@@ -3392,5 +3698,5 @@ interface AddSlideProps {
   sectionTitle?: string;
 }
 //#endregion
-export { LinearGradientFillProps as $, CommentProps as $t, ImageBaseProps as A, ChartPropsChartBar as At, ShapeGuide as B, ChartPropsChartWaterfall as Bt, TableRow as C, ChartLineDash as Ct, TableToSlidesDocument as D, ChartPropsAxisSer as Dt, TableStyleRegionProps as E, ChartPropsAxisCat as Et, ShapeAdjustHandle as F, ChartPropsChartPie as Ft, DataOrPathProps as G, ChartPropsTitle as Gt, BackgroundProps as H, ChartPropsDataTable as Ht, ShapeAdjustHandlePolar as I, ChartPropsChartRadar as It, GradientFillProps as J, OptsChartData as Jt, DataOrPathRequiredProps as K, ChartSeriesOpts as Kt, ShapeAdjustHandleXY as L, ChartPropsChartRegionMap as Lt, MediaProps as M, ChartPropsChartDoughnut as Mt, MediaType as N, ChartPropsChartHistogram as Nt, TableToSlidesElement as O, ChartPropsAxisVal as Ot, OleObjectProps as P, ChartPropsChartLine as Pt, ImageFillProps as Q, PlaceholderProps as Qt, ShapeAdjustValue as R, ChartPropsChartStock as Rt, TableProps as S, ChartExStatistics as St, TableStyleProps as T, ChartOpts as Tt, Color as U, ChartPropsFillLine as Ut, ShapeProps as V, ChartPropsDataLabel as Vt, Coord as W, ChartPropsLegend as Wt, HAlign as X, ObjectLockProps as Xt, GradientStopProps as Y, OptsChartGridLine as Yt, HexColor as Z, ObjectNameProps as Zt, TransitionProps as _, ChartAxisTickMark as _t, Slide as a, SlideComment as an, TextVertType as at, TableCell as b, ChartExBinning as bt, MasterTextStyleLevel as c, TextBaseProps as cn, BorderProps as ct, SlideMasterObject as d, TextMeasurement as dn, HyperlinkActionJump as dt, MeasureTextOptions as en, Margin as et, SlideMasterProps as f, TextProps as fn, HyperlinkProps as ft, PresetEffect as g, ChartAreaProps as gt, AnimationTrigger as h, textRuns as hn, ShapeLineProps as ht, ObjectOptions as i, ResolvedCommentAuthor as in, RadialGradientFillProps as it, ImageProps as j, ChartPropsChartBoxWhisker as jt, TableToSlidesProps as k, ChartPropsBase as kt, MasterTextStyleProps as l, TextFitShrinkProps as ln, ConnectorProps as lt, AnimationProps as m, textRun as mn, ShapeFillProps as mt, GroupChildProps as n, NotesTextOptions as nn, PatternPreset as nt, SlideLayout as o, TableCellLayout as on, ThemeColor as ot, SlideNumberProps as p, TextPropsOptions as pn, ShadowProps as pt, GeometryPoint as q, LineCap as qt, GroupProps as r, OverflowBoxOptions as rn, PositionProps as rt, MasterBulletProps as s, TableLayoutResult as sn, VAlign as st, AddSlideProps as t, NotesProps as tn, PatternFillProps as tt, SlideMasterChartProps as u, TextGlowProps as un, ConnectorType as ut, TransitionSoundProps as v, ChartDataPointStyle as vt, TableRowSlide as w, ChartMulti as wt, TableCellProps as x, ChartExGeography as xt, TransitionType as y, ChartErrorBarOptions as yt, ShapeConnectionSite as z, ChartPropsChartSurface as zt };
-//# sourceMappingURL=slide-B6mDaM-P.d.ts.map
+export { HAlign as $, ChartSeriesOpts as $t, TableToSlidesDocument as A, ChartLineDash as At, ShapeAdjustHandleXY as B, ChartPropsChartHistogram as Bt, TableCell as C, ChartAreaProps as Ct, TableProps as D, ChartExBinning as Dt, TableCellProps as E, ChartErrorBarOptions as Et, MediaProps as F, ChartPropsAxisVal as Ft, BackgroundProps as G, ChartPropsChartStock as Gt, ShapeConnectionSite as H, ChartPropsChartPie as Ht, MediaType as I, ChartPropsBase as It, DataOrPathProps as J, ChartPropsDataLabel as Jt, Color as K, ChartPropsChartSurface as Kt, OleObjectProps as L, ChartPropsChartBar as Lt, TableToSlidesProps as M, ChartOpts as Mt, ImageBaseProps as N, ChartPropsAxisCat as Nt, TableRow as O, ChartExGeography as Ot, ImageProps as P, ChartPropsAxisSer as Pt, GradientStopProps as Q, ChartPropsTitle as Qt, ShapeAdjustHandle as R, ChartPropsChartBoxWhisker as Rt, TransitionType as S, textRuns as Sn, PresetMaterialType as St, TableCellDiagonals as T, ChartDataPointStyle as Tt, ShapeGuide as U, ChartPropsChartRadar as Ut, ShapeAdjustValue as V, ChartPropsChartLine as Vt, ShapeProps as W, ChartPropsChartRegionMap as Wt, GeometryPoint as X, ChartPropsFillLine as Xt, DataOrPathRequiredProps as Y, ChartPropsDataTable as Yt, GradientFillProps as Z, ChartPropsLegend as Zt, AnimationProps as _, TextGlowProps as _n, ShapeFillProps as _t, Slide as a, PlaceholderProps as an, PatternPreset as at, TransitionProps as b, TextPropsOptions as bn, LightRigDirection as bt, Model3dPoint as c, NotesProps as cn, TextVertType as ct, MasterTextStyleLevel as d, ResolvedCommentAuthor as dn, BorderProps as dt, LineCap as en, HexColor as et, MasterTextStyleProps as f, SlideComment as fn, ConnectorProps as ft, SlideNumberProps as g, TextFitShrinkProps as gn, ShadowProps as gt, SlideMasterProps as h, TextBaseProps as hn, HyperlinkProps as ht, ObjectOptions as i, ObjectNameProps as in, PatternFillProps as it, TableToSlidesElement as j, ChartMulti as jt, TableRowSlide as k, ChartExStatistics as kt, Model3dProps as l, NotesTextOptions as ln, ThemeColor as lt, SlideMasterObject as m, TableLayoutResult as mn, HyperlinkActionJump as mt, GroupChildProps as n, OptsChartGridLine as nn, LinearGradientFillProps as nt, SlideLayout as o, CommentProps as on, PositionProps as ot, SlideMasterChartProps as p, TableCellLayout as pn, ConnectorType as pt, Coord as q, ChartPropsChartWaterfall as qt, GroupProps as r, ObjectLockProps as rn, Margin as rt, Model3dCameraProps as s, MeasureTextOptions as sn, RadialGradientFillProps as st, AddSlideProps as t, OptsChartData as tn, ImageFillProps as tt, MasterBulletProps as u, OverflowBoxOptions as un, VAlign as ut, AnimationTrigger as v, TextMeasurement as vn, ShapeLineProps as vt, TableCell3DProps as w, ChartAxisTickMark as wt, TransitionSoundProps as x, textRun as xn, LightRigType as xt, PresetEffect as y, TextProps as yn, BevelPresetType as yt, ShapeAdjustHandlePolar as z, ChartPropsChartDoughnut as zt };
+//# sourceMappingURL=slide-YuSCGa45.d.ts.map