pptx-svelte-viewer 3.7.0 → 3.9.0

package/dist/index.d.ts

@@ -571,6 +571,44 @@ interface PptxCustomPathProperties {
   customGeometryTextRect?: CustomGeometryTextRect;
 }
 //#endregion
+//#region src/core/types/color-ref.d.ts
+/**
+ * Theme colour references: the typed counterpart of `<a:schemeClr>`.
+ *
+ * A colour picked from the theme palette is remembered as a scheme slot plus
+ * PowerPoint's luminance variants rather than as the sRGB it currently
+ * resolves to, so a later theme change re-colours the shape (and a saved file
+ * keeps `<a:schemeClr>` instead of a canonical `<a:srgbClr>`).
+ *
+ * @module types/color-ref
+ */
+/**
+ * The scheme slot names `a:schemeClr/@val` accepts (ECMA-376 `ST_SchemeColorIndex`).
+ * `bg1`/`tx1`/`bg2`/`tx2` are the colour-map aliases a slide resolves through
+ * `p:clrMap`; `phClr` is the placeholder colour used inside a theme's style
+ * matrix and is never chosen from a picker.
+ */
+type PptxThemeColorSchemeName = 'dk1' | 'lt1' | 'dk2' | 'lt2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink' | 'bg1' | 'tx1' | 'bg2' | 'tx2' | 'phClr';
+/**
+ * A theme colour choice. Every transform is a 0..1 fraction of the OOXML
+ * percentage (`lumMod val="20000"` is `lumMod: 0.2`), matching how the parser
+ * reads them, and is applied in the order `a:schemeClr` children are written:
+ * `tint`, `shade`, `lumMod`, `lumOff`, `alpha`.
+ */
+interface PptxThemeColorRef {
+  scheme: PptxThemeColorSchemeName;
+  /** `a:lumMod`: multiply HSL luminance (PowerPoint's "Lighter/Darker" rows). */
+  lumMod?: number;
+  /** `a:lumOff`: add to HSL luminance after `lumMod` ("Lighter N%" rows). */
+  lumOff?: number;
+  /** `a:tint`: blend towards white. */
+  tint?: number;
+  /** `a:shade`: blend towards black. */
+  shade?: number;
+  /** `a:alpha`: opacity fraction (1 = opaque). */
+  alpha?: number;
+}
+//#endregion
 //#region src/core/types/effect-dag.d.ts
 type EffectDagBlendMode = 'darken' | 'lighten' | 'mult' | 'over' | 'screen';
 type EffectDagContainerType = 'sib' | 'tree';
@@ -860,6 +898,15 @@ interface ShapeStyle {
    * back to canonical `<a:srgbClr>`.
    */
   fillColorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the fill, set when {@link fillColorXml}
+   * is a plain `a:schemeClr` (see `themeColorRefFromColorChoice`). When
+   * present it WINS on save: the writer emits `<a:schemeClr>` from this ref
+   * instead of the resolved {@link fillColor}, so the fill keeps following
+   * the theme palette after a later theme change. `undefined` means the fill
+   * is a plain hex (or a colour kind a ref cannot express).
+   */
+  fillColorRef?: PptxThemeColorRef;
   fillGradient?: string;
   /** Original `gradFill` XML retained for unknown-child and extension round-tripping. */
   fillGradientXml?: XmlObject;
@@ -894,6 +941,12 @@ interface ShapeStyle {
     opacity?: number;
     /** Raw XML colour node preserved for round-trip (e.g. a:schemeClr with transforms). */
     originalColorXml?: XmlObject;
+    /**
+     * Typed theme colour reference for this stop, set when
+     * {@link originalColorXml} is a plain `a:schemeClr`. Wins on save, same
+     * as {@link ShapeStyle.fillColorRef}.
+     */
+    colorRef?: PptxThemeColorRef;
   }>;
   fillGradientAngle?: number;
   fillGradientType?: 'linear' | 'radial';
@@ -940,6 +993,12 @@ interface ShapeStyle {
    * round-trip serialisation. See {@link fillColorXml} for the rationale.
    */
   strokeColorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the outline, mirroring
+   * {@link fillColorRef}: set when {@link strokeColorXml} is a plain
+   * `a:schemeClr`, and wins on save.
+   */
+  strokeColorRef?: PptxThemeColorRef;
   /**
    * Kind of fill painted on the outline (`a:ln` child). Distinguishes a solid
    * outline from a gradient/pattern/none outline so save can emit the correct
@@ -1443,6 +1502,15 @@ interface TextStyle {
    * verbatim when the resolved {@link color} still matches this node.
    */
   colorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the run's text colour, set when
+   * {@link colorXml} is a plain `a:schemeClr` (see
+   * `themeColorRefFromColorChoice`). When present it WINS on save: the
+   * writer emits `<a:schemeClr>` from this ref instead of the resolved
+   * {@link color}, so the text keeps following the theme palette after a
+   * later theme change.
+   */
+  colorRef?: PptxThemeColorRef;
   align?: 'left' | 'center' | 'right' | 'justify' | 'justLow' | 'dist' | 'thaiDist';
   /**
    * Vertical text-box anchor (`a:bodyPr/@anchor`, `ST_TextAnchoringType`).
@@ -1868,6 +1936,12 @@ interface BulletInfo {
    * identity rather than being flattened to `<a:srgbClr/>` on save.
    */
   colorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the bullet colour, set when
+   * {@link colorXml} is a plain `a:schemeClr`. Wins on save, same as
+   * {@link TextStyle.colorRef}.
+   */
+  colorRef?: PptxThemeColorRef;
   /** True when `a:buNone` explicitly suppresses bullets. */
   none?: boolean;
   /** Picture bullet: relationship ID from `a:buBlip` → `a:blip[@r:embed]`. */
@@ -2320,7 +2394,38 @@ interface PptxChartDataPointPicture {
 //#region src/core/types/chart-pivot-format.d.ts
 interface PptxChartPivotFormat {
   index: number;
+  /**
+   * Typed projection of `spPr` (fill/stroke colour, stroke width, dash
+   * style). When the parser is given a colour resolver (the normal case: the
+   * runtime always supplies one), both a literal `a:srgbClr` and an
+   * `a:schemeClr` theme reference (with its `lumMod`/`lumOff`/`tint`/`shade`
+   * modifiers) resolve to a hex colour here, the same theme +
+   * `c:clrMapOvr` chain the rest of chart parsing uses. Without a resolver
+   * (e.g. a hand-built `PptxChartPivotFormat` with no theme to resolve
+   * against), only the literal case resolves. Either way the authored node
+   * is byte-preserved through {@link shapePropertiesXml} until this field is
+   * set to something that no longer matches what re-parses off the current
+   * XML; setting it then re-derives `shapePropertiesXml` on save (merged
+   * onto whatever was already authored, keeping an unrelated schemeClr
+   * reference alive when the colour itself is unchanged) unless
+   * `shapePropertiesXml` is set explicitly, which wins.
+   */
+  shapeProperties?: PptxChartShapeProps;
+  /**
+   * Typed projection of `txPr`'s `a:p/a:pPr/a:defRPr` (size/bold/italic/
+   * colour/family), the same shape a legend entry or data-table's text
+   * override models. Colour resolution mirrors {@link shapeProperties}
+   * (theme-resolved `schemeClr` when a colour resolver is supplied, literal
+   * `srgbClr` otherwise). See {@link txPrXml} for the raw fallback.
+   */
+  textStyle?: PptxChartLegendTextStyle;
+  /**
+   * Typed projection of `marker` (symbol/size/spPr). See {@link markerXml}
+   * for the raw fallback.
+   */
+  marker?: PptxChartMarker;
   shapePropertiesXml?: XmlObject | null;
+  txPrXml?: XmlObject | null;
   markerXml?: XmlObject | null;
   dataLabelXml?: XmlObject | null;
   extensionListXml?: XmlObject | null;
@@ -2479,21 +2584,40 @@ interface PptxChartStyleDefinition {
   plotArea?: PptxChartStylePartEntry;
 }
 //#endregion
-//#region src/core/types/chart-user-shapes.d.ts
+//#region src/core/types/chart-title.d.ts
 /**
- * Types for chart drawing-overlay shapes (`c:userShapes`).
+ * Chart title rich-text run type, split out of `types/chart.ts` (already at
+ * the repo's file-size limit) to keep that module from growing further.
  *
- * A chart's `c:userShapes` element carries an `r:id` that references a
- * separate drawing part (`ppt/drawings/drawingN.xml`) whose root is a
- * `c:userShapes` element populated with `cdr:relSizeAnchor` /
- * `cdr:absSizeAnchor` wrappers around `sp` / `pic` / `cxnSp` shapes drawn on
- * top of the chart plot. These interfaces describe the parsed, renderable
- * overlay model. The raw reference is preserved separately on
- * {@link PptxChartData.userShapesXml} for verbatim round-trip save; this model
- * is render-only.
+ * @module pptx-types/chart-title
+ */
+/**
+ * One run of a chart title's rich text (`c:title/c:tx/c:rich/a:p/a:r`).
  *
- * @module pptx-types/chart-user-shapes
+ * The flat `PptxChartData.title` field only ever captured the FIRST run's
+ * text with no per-run formatting; `titleRuns` (when present) is the
+ * lossless, multi-run replacement parsed from the same `c:rich` body. Absent
+ * when the title has no rich text at all (an empty/auto title, or one
+ * authored as a linked-cell reference).
  */
+interface PptxChartTitleRun {
+  /** This run's text (`a:t`). */
+  text: string;
+  /** `a:rPr/@_b`. */
+  bold?: boolean;
+  /** `a:rPr/@_i`. */
+  italic?: boolean;
+  /**
+   * Font size in POINTS (`a:rPr/@_sz`, hundredths of a point / 100), matching
+   * `PptxChartLegendTextStyle.fontSize`'s convention rather than the pixel
+   * convention `TextStyle.fontSize` uses for slide text.
+   */
+  fontSize?: number;
+  /** Resolved hex colour (e.g. `"#FF0000"`) from `a:rPr/a:solidFill`. */
+  color?: string;
+}
+//#endregion
+//#region src/core/types/chart-user-shapes.d.ts
 /** A single paragraph of overlay-shape text with light formatting. */
 interface PptxChartUserShapeParagraph {
   /** Joined run text of the paragraph. */
@@ -2509,6 +2633,80 @@ interface PptxChartUserShapeParagraph {
   /** Paragraph alignment (`a:pPr/@algn`): left / centre / right. */
   align?: 'l' | 'ctr' | 'r';
 }
+/**
+ * The DrawingML 2D group transform (`a:xfrm` inside `cdr:grpSpPr`) that
+ * anchors a `grpSp`'s own box ({@link off}/{@link ext}) and establishes the
+ * coordinate space its children are expressed in ({@link chOff}/{@link
+ * chExt}), all in EMU. A child's position within the group is mapped into
+ * the group's own box via
+ * `frac = (child.off - chOff) / chExt`, then applied to the enclosing
+ * anchor's box; see `flattenChartUserShapes` in
+ * `chart-user-shapes-parser.ts`.
+ */
+interface PptxChartUserShapeGroupTransform {
+  /** The group's own position in its parent's coordinate space, in EMU. */
+  off: {
+    x: number;
+    y: number;
+  };
+  /** The group's own size in its parent's coordinate space, in EMU. */
+  ext: {
+    cx: number;
+    cy: number;
+  };
+  /** Origin of the child coordinate space (`a:chOff`), in EMU. */
+  chOff: {
+    x: number;
+    y: number;
+  };
+  /** Size of the child coordinate space (`a:chExt`), in EMU. */
+  chExt: {
+    cx: number;
+    cy: number;
+  };
+}
+/**
+ * One shape grouped inside a `cdr:grpSp` (or a nested `cdr:grpSp` itself).
+ * Unlike a top-level {@link PptxChartUserShape}, a group child has no
+ * drawing anchor of its own: its position is expressed in its parent
+ * group's child coordinate space via {@link off}/{@link ext} (EMU, read
+ * from the child's own `a:xfrm`), not as a chart-relative fraction.
+ */
+interface PptxChartUserShapeGroupChild {
+  /** Shape kind, same vocabulary as {@link PptxChartUserShape.kind}. */
+  kind: 'sp' | 'cxnSp' | 'pic' | 'grpSp' | 'graphicFrame';
+  /** Position within the parent group's child coordinate space, in EMU. */
+  off: {
+    x: number;
+    y: number;
+  };
+  /** Size within the parent group's child coordinate space, in EMU. */
+  ext: {
+    cx: number;
+    cy: number;
+  };
+  /** Preset geometry name (`a:prstGeom/@prst`), defaulting to `"rect"`. */
+  prst?: string;
+  /** Resolved solid-fill hex colour, when present. */
+  fill?: string;
+  /** Resolved line/stroke hex colour, when present. */
+  stroke?: string;
+  /** Line width in points (`a:ln/@w` divided by 12700), when present. */
+  strokeWidth?: number;
+  /** Text paragraphs of the shape's `txBody`, when present. */
+  paragraphs?: PptxChartUserShapeParagraph[];
+  /**
+   * Verbatim source XML of a `pic`/`graphicFrame` child, or of this node
+   * itself when `kind === 'grpSp'` and the nested group is untouched since
+   * parse. See {@link PptxChartUserShape.rawXml}'s doc for the same
+   * contract one level up.
+   */
+  rawXml?: XmlObject;
+  /** Present when `kind === 'grpSp'`: this nested group's own transform. */
+  transform?: PptxChartUserShapeGroupTransform;
+  /** Present when `kind === 'grpSp'`: this nested group's own children. */
+  children?: PptxChartUserShapeGroupChild[];
+}
 /**
  * A parsed chart-overlay shape positioned by a drawing anchor.
  *
@@ -2519,12 +2717,13 @@ interface PptxChartUserShapeParagraph {
 interface PptxChartUserShape {
   /**
    * Shape kind: text/preset shape, connector, picture, a group of the
-   * above (`grpSp`, flattened: each grouped child becomes its own entry
-   * reusing the anchor's own bounding box, an approximation since the
-   * group's internal chOff/chExt transform is not applied), or a bare
-   * placeholder for a `graphicFrame` anchor child (deep content such as a
-   * nested chart or table is out of scope; it only keeps the anchor's
-   * space accounted for instead of the whole overlay disappearing).
+   * above (`grpSp`, with its own {@link transform} and {@link children},
+   * nested arbitrarily; use `flattenChartUserShapes` from
+   * `chart-user-shapes-parser.ts` to get a flat, render-ready leaf list
+   * with the group transform already applied), or a bare placeholder for
+   * a `graphicFrame` anchor child (deep content such as a nested chart or
+   * table is out of scope; it only keeps the anchor's space accounted for
+   * instead of the whole overlay disappearing).
    */
   kind: 'sp' | 'cxnSp' | 'pic' | 'grpSp' | 'graphicFrame';
   /** Anchor kind that positioned the shape. */
@@ -2554,6 +2753,26 @@ interface PptxChartUserShape {
   strokeWidth?: number;
   /** Text paragraphs of the shape's `txBody`, when present. */
   paragraphs?: PptxChartUserShapeParagraph[];
+  /**
+   * Verbatim source XML of a `pic` or `graphicFrame` anchor child (the
+   * `cdr:pic` / `cdr:graphicFrame` node itself, not the enclosing anchor),
+   * or of the `cdr:grpSp` node itself when `kind === 'grpSp'` and the
+   * group is untouched since parse (byte-identical passthrough). None of
+   * these three kinds have a reconstructable typed representation that is
+   * guaranteed lossless (a picture's blip reference, a nested chart/table's
+   * graphic content, or a group's exact child ordering/ids), so the
+   * serializer re-emits this verbatim when present instead of a lossy
+   * rebuild. Editing a shape inside a group (via the SDK's path-based
+   * overlay operations) clears the group's `rawXml` so the serializer
+   * regenerates it from {@link transform}/{@link children} instead. Absent
+   * for `sp`/`cxnSp`, which round-trip losslessly through their typed
+   * fields above.
+   */
+  rawXml?: XmlObject;
+  /** Present when `kind === 'grpSp'`: the group's own transform. */
+  transform?: PptxChartUserShapeGroupTransform;
+  /** Present when `kind === 'grpSp'`: the grouped children, nested arbitrarily. */
+  children?: PptxChartUserShapeGroupChild[];
 }
 //#endregion
 //#region src/core/types/chart.d.ts
@@ -2627,6 +2846,10 @@ interface PptxChartTrendline {
   displayRSq?: boolean;
   displayEq?: boolean;
   color?: string;
+  /** Trendline width in points (`c:trendline/c:spPr/a:ln/@w`, EMU / 12700). */
+  lineWidth?: number;
+  /** Trendline dash style (`c:trendline/c:spPr/a:ln/a:prstDash/@val`). */
+  lineDashStyle?: string;
   label?: PptxChartTrendlineLabel | null;
 }
 /** Typed, commonly edited properties of `c:trendlineLbl`. */
@@ -2672,6 +2895,10 @@ interface PptxChartErrBars {
   customMinus?: number[];
   noEndCap?: boolean;
   color?: string;
+  /** Error-bar line width in points (`c:errBars/c:spPr/a:ln/@w`, EMU / 12700). */
+  width?: number;
+  /** Error-bar line dash style (`c:errBars/c:spPr/a:ln/a:prstDash/@val`). */
+  dashStyle?: string;
 }
 /**
  * Visibility flags for the chart data table (axes + legend keys).
@@ -2798,6 +3025,12 @@ interface PptxChartDataLabel {
    * `.../a:p/a:pPr/a:defRPr` default-run-property style.
    */
   txPr?: PptxChartLegendTextStyle;
+  /**
+   * This label's own shape formatting (`c:dLbl/c:spPr`): fill/line colour,
+   * width, and dash style for the label's callout box, taking precedence
+   * over any chart/series-level default when set.
+   */
+  spPr?: PptxChartShapeProps;
 }
 /** Axis number format. */
 interface PptxChartAxisNumFmt {
@@ -3361,6 +3594,16 @@ interface PptxChartDateCategories {
  */
 interface PptxChartData {
   title?: string;
+  /**
+   * Rich-text runs of the title, parsed from `c:title/c:tx/c:rich` (issue:
+   * chart title rich text). Lossless multi-run alternative to the flat
+   * {@link title}: when present, the writer serialises every run's own
+   * bold/italic/size/color; when absent, save falls back to the flat
+   * `title` path as before. Only populated for a classic (`c:`) chart's
+   * rich (typed) title, not a ChartEx (`cx:`) title or one authored as a
+   * linked-cell reference.
+   */
+  titleRuns?: PptxChartTitleRun[];
   chartType: PptxChartType;
   categories: string[];
   /**
@@ -3452,8 +3695,10 @@ interface PptxChartData {
   chartRelationshipId?: string;
   /** `null` explicitly removes an existing ChartML data table. */
   dataTable?: PptxChartDataTable | null;
-  dropLines?: PptxChartLineStyle;
-  hiLowLines?: PptxChartLineStyle;
+  /** `null` explicitly removes an existing `c:dropLines` element. */
+  dropLines?: PptxChartLineStyle | null;
+  /** `null` explicitly removes an existing `c:hiLowLines` element. */
+  hiLowLines?: PptxChartLineStyle | null;
   /** `null` explicitly removes an existing up/down-bars container. */
   upDownBars?: PptxChartUpDownBars | null;
   axes?: PptxChartAxisFormatting[];
@@ -3568,10 +3813,13 @@ interface PptxChartData {
   pivotFormats?: PptxChartPivotFormats | null;
   /**
    * Color-map override (`c:clrMapOvr`) carrying 12 attributes that
-   * remap theme colour roles for this chart only. Preserved as a flat
-   * `attribute → value` map for round-trip fidelity.
+   * remap theme colour roles for this chart only. Modeled as a flat
+   * `attribute -> value` map (e.g. `{ bg1: 'lt1', accent1: 'accent2' }`)
+   * so unknown/future attributes round-trip without code changes.
+   * `null` explicitly removes an existing `c:clrMapOvr`; an empty object
+   * is treated the same as `null` on save.
    */
-  clrMapOvr?: Record<string, string>;
+  clrMapOvr?: Record<string, string> | null;
   /**
    * Whether the chart's own cached numeric values use the 1904 date epoch
    * (`c:chartSpace/c:date1904/@val`). Independent of, and authoritative over,
@@ -4948,13 +5196,55 @@ interface PptxSmartArtData {
   drawingDirty?: boolean;
 }
 //#endregion
-//#region src/core/types/table.d.ts
+//#region src/core/types/table-style-edit.d.ts
+/**
+ * A `a:fillRef`/`a:lnRef`/`a:effectRef`-style style-matrix reference: an
+ * index into the theme's format scheme (`a:fmtScheme/a:fillStyleLst`, 1-based
+ * per ECMA-376 §20.1.4.1.12) plus an optional colour transform child.
+ *
+ * Distinct from an already-resolved {@link ParsedTableStyleFill}: a fill ref
+ * points AT a theme style-matrix entry rather than carrying a colour choice
+ * directly, though the two commonly appear together (`<a:fillRef idx="2">
+ * <a:schemeClr val="accent1"/></a:fillRef>`).
+ *
+ * @example
+ * ```ts
+ * const ref: ParsedTableFillRef = { idx: 2, color: { schemeColor: 'accent1' } };
+ * // => satisfies ParsedTableFillRef
+ * ```
+ */
+interface ParsedTableFillRef {
+  /** 1-based index into the theme format scheme's fill style list. */
+  idx: number;
+  /** Colour transform child (`a:schemeClr`/`a:srgbClr`) applied to the referenced style. */
+  color?: ParsedTableStyleFill;
+}
 /**
- * Table types: cell styling, cell data, rows, table data, and the parsed
- * table style map from `ppt/tableStyles.xml`.
+ * One leaf (or `effectDag`-wrapped) node of an `a:effectLst`/`a:effectDag`
+ * effect chain, kept mostly opaque: {@link kind} names the OOXML element so a
+ * consumer can recognise common effects (`outerShdw`, `glow`, `softEdge`,
+ * `reflection`, `blur`, `innerShdw`, `prstShdw`, `fillOverlay`, `alphaModFix`,
+ * `alphaInv`, `grayscl`, `biLevel`, `duotone`, `hsl`, `lum`, `tint`) without
+ * this module re-deriving the full shape-effect taxonomy already modelled on
+ * `ShapeStyle`; {@link xml} preserves the node verbatim for lossless re-emit.
  *
- * @module pptx-types/table
+ * @example
+ * ```ts
+ * const effect: ParsedTableStyleEffect = {
+ *   kind: 'outerShdw',
+ *   xml: { '@_blurRad': '40000', '@_dist': '20000', '@_dir': '5400000' },
+ * };
+ * // => satisfies ParsedTableStyleEffect
+ * ```
  */
+interface ParsedTableStyleEffect {
+  /** The OOXML element's local name, e.g. `outerShdw`, `glow`, `softEdge`. */
+  kind: string;
+  /** Verbatim XML node (attributes + children) for lossless round-trip. */
+  xml: XmlObject;
+}
+//#endregion
+//#region src/core/types/table.d.ts
 /**
  * Per-cell visual style for a table cell.
  *
@@ -4991,6 +5281,14 @@ interface PptxTableCellStyle {
    * future expansion alongside the run-properties round-trip path.
    */
   colorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the cell text colour, set when
+   * {@link colorXml} is a plain `a:schemeClr`. Wins on save, mirroring
+   * `TextStyle.colorRef`. Distinct from {@link ParsedTableStyleFill.schemeColor},
+   * which describes a `ppt/tableStyles.xml` section fill rather than an
+   * individual cell override.
+   */
+  colorRef?: PptxThemeColorRef;
   backgroundColor?: string;
   /**
    * Raw XML colour-choice node preserved from cell `a:tcPr/a:solidFill` for
@@ -4998,6 +5296,12 @@ interface PptxTableCellStyle {
    * {@link backgroundColor} still matches the original colour.
    */
   backgroundColorXml?: XmlObject;
+  /**
+   * Typed theme colour reference for the cell fill, set when
+   * {@link backgroundColorXml} is a plain `a:schemeClr`. Wins on save,
+   * mirroring `ShapeStyle.fillColorRef`.
+   */
+  backgroundColorRef?: PptxThemeColorRef;
   borderColor?: string;
   /** Top border width in px. */
   borderTopWidth?: number;
@@ -5311,12 +5615,14 @@ interface PptxTableData {
    */
   tableFill?: ParsedTableStyleFill;
   /**
-   * Whether `a:tblPr` carries its own `a:effectLst`/`a:effectDag`,
-   * independent of the referenced table style. Presence-only: the concrete
-   * effect is not yet rendered, and the raw XML round-trips separately via
-   * whatever preserves `a:tblPr`'s unrecognised children (issue G6).
+   * `a:tblPr`'s own `a:effectLst` (or `a:effectDag`) effect chain,
+   * independent of the referenced table style, decomposed into a typed
+   * sequence of {@link ParsedTableStyleEffect} nodes (issue G6). Each node
+   * keeps its own XML verbatim for lossless round-trip; empty array is
+   * normalised to `undefined` by the parser so `tableEffects` is only ever
+   * present when there is at least one effect.
    */
-  tableEffects?: boolean;
+  tableEffects?: ParsedTableStyleEffect[];
 }
 /**
  * A single fill reference within a table style section.
@@ -5492,13 +5798,20 @@ interface ParsedTableStyleBorders {
 /**
  * Table background style (CT_TableBackgroundStyle, ECMA-376 §21.1.3.7).
  *
- * Corresponds to the `<a:tblBg>` child of `<a:tblStyle>`. Currently
- * captures only the resolved scheme-fill colour (verbatim XML for fill
- * / effect references is preserved separately by the save path).
+ * Corresponds to the `<a:tblBg>` child of `<a:tblStyle>`. Captures the
+ * resolved scheme-fill colour, an unresolved style-matrix `a:fillRef`, and a
+ * presence flag for effects (verbatim XML for the effect list is preserved
+ * separately by the save path).
  */
 interface ParsedTableBackground {
   /** Solid fill (resolved from `a:fill > a:solidFill > a:schemeClr`). */
   fill?: ParsedTableStyleFill;
+  /**
+   * Style-matrix fill reference (`<a:fillRef idx="N">...</a:fillRef>`),
+   * mutually exclusive with {@link fill} (`a:fill` is the choice sibling of
+   * `a:fillRef` in `CT_TableBackgroundStyle`).
+   */
+  fillRef?: ParsedTableFillRef;
   /** Has an `a:effectLst` child that should be round-tripped. */
   hasEffectLst?: boolean;
 }
@@ -5612,6 +5925,21 @@ interface PptxAccessibilityProperties {
    */
   isDecorative?: boolean;
 }
+/**
+ * Accessibility description/title from `p:cNvPr/@descr` / `@title` on a
+ * plain shape, text box or connector (`p:sp` / `p:cxnSp`). The same pair of
+ * attributes already round-trips for a graphic frame (see
+ * {@link TablePptxElement.altText}) and, `descr` only, for a picture
+ * ({@link PptxImageProperties.altText}); this mixin extends it to the three
+ * element kinds whose PowerPoint Alt Text pane data was previously dropped
+ * on load because neither field existed on the model.
+ */
+interface PptxNonVisualDescription {
+  /** `p:cNvPr/@descr`. */
+  altText?: string;
+  /** `p:cNvPr/@title`. */
+  title?: string;
+}
 /**
  * `a:cNvPicPr/@preferRelativeResize` (issue G13), a picture-only non-visual
  * property distinct from `a:picLocks`.
@@ -5644,7 +5972,7 @@ interface PptxPictureNonVisualProperties {
  * // => satisfies TextPptxElement
  * ```
  */
-interface TextPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties {
+interface TextPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxNonVisualDescription {
   type: 'text';
 }
 /**
@@ -5662,7 +5990,7 @@ interface TextPptxElement extends PptxElementBase, PptxTextProperties, PptxShape
  * // => satisfies ShapePptxElement
  * ```
  */
-interface ShapePptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxCustomPathProperties, PptxAccessibilityProperties {
+interface ShapePptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxCustomPathProperties, PptxAccessibilityProperties, PptxNonVisualDescription {
   type: 'shape';
 }
 /**
@@ -5684,7 +6012,7 @@ interface ShapePptxElement extends PptxElementBase, PptxTextProperties, PptxShap
  * // => satisfies ConnectorPptxElement
  * ```
  */
-interface ConnectorPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties {
+interface ConnectorPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxNonVisualDescription {
   type: 'connector';
 }
 /**
@@ -5750,6 +6078,13 @@ interface TablePptxElement extends PptxElementBase {
   type: 'table';
   /** Parsed table cell data for editing. */
   tableData?: PptxTableData;
+  /**
+   * Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`, the
+   * same non-visual-properties attribute a picture's alt text comes from.
+   */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
+  title?: string;
   /**
    * Unrecognised extensions captured from `a:graphicData/a:extLst` so they
    * round-trip losslessly. See {@link PptxGraphicFrameExtension}.
@@ -5765,6 +6100,10 @@ interface TablePptxElement extends PptxElementBase {
 interface ChartPptxElement extends PptxElementBase {
   type: 'chart';
   chartData?: PptxChartData;
+  /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
+  title?: string;
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -5782,6 +6121,10 @@ interface ChartPptxElement extends PptxElementBase {
 interface SmartArtPptxElement extends PptxElementBase {
   type: 'smartArt';
   smartArtData?: PptxSmartArtData;
+  /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
+  title?: string;
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -5868,6 +6211,10 @@ interface OlePptxElement extends PptxElementBase {
    * `false`; `undefined` means the source authored no explicit value.
    */
   oleUpdateAutomatic?: boolean;
+  /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
+  title?: string;
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -5959,6 +6306,15 @@ interface MediaPptxElement extends PptxElementBase {
    * (`r:embed`). Defaults to embedded when undefined.
    */
   isLinked?: boolean;
+  /**
+   * Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`.
+   * Only populated for the `p:graphicFrame`-shaped (SDK-created) media
+   * form; a `p:pic`-shaped media element's alt text is not currently
+   * parsed (see `PptxHandlerRuntimePictureParsing.ts`).
+   */
+  altText?: string;
+  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. Same scope note as {@link altText}. */
+  title?: string;
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -6465,7 +6821,20 @@ interface PptxAnimationGraphicElementTarget {
   seriesIdx?: number;
   /** `@_categoryIdx`, 0-based category index, when the target is category-scoped. */
   categoryIdx?: number;
-  /** `@_bldStep` (ST_TLChartBuildStep): `category` / `categoryEl` / `series` / `seriesEl`. */
+  /**
+   * `p:dgm/@_id` (CT_TLBuildDiagram, ECMA-376 S19.5.10): the diagram DATA MODEL
+   * point id (`dgm:pt/@modelId`) this per-stage effect reveals, when a
+   * `p:bldDgm` build authors one effect per node instead of a single staged
+   * reveal. `dgm`-kind targets only; a `chart`-kind target never carries this.
+   * Matches `PptxSmartArtNode.id` (parsed from the same `@modelId`), so a
+   * diagram renderer can reveal the exact authored node.
+   */
+  id?: string;
+  /**
+   * `@_bldStep`: `ST_TLChartBuildStep` (`category` / `categoryEl` / `series` /
+   * `seriesEl`) for a `chart`-kind target, or `ST_TLDiagramBuildStep`
+   * (`sp` / `bg`) for a `dgm`-kind target.
+   */
   bldStep?: string;
 }
 /**
@@ -6915,6 +7284,34 @@ interface PptxNativeAnimation {
    * `childStyle`, a legacy compatibility hint. Round-tripped only.
    */
   cBhvrOverride?: 'normal' | 'childStyle';
+  /**
+   * `p:set` discrete attribute assignments composed alongside this effect
+   * (ECMA-376 S19.5.79 CT_TLSetBehavior): an instantaneous (non-interpolated)
+   * value change, as opposed to {@link attributeAnimations}'s `p:anim`
+   * keyframe ramps. PowerPoint authors several font-style emphasis effects
+   * this way (Bold Reveal, Underline, Bold Flash, Change Font Size), since
+   * "on/off" or "size N" has nothing to interpolate. Not yet consulted by
+   * shared playback (round-trip/typed-model only so far).
+   */
+  setAnimations?: PptxSetAnimation[];
+}
+/**
+ * One `p:set` discrete (non-interpolated) attribute assignment composed
+ * alongside an authored effect. See {@link PptxNativeAnimation.setAnimations}.
+ *
+ * @see ECMA-376 S19.5.79 CT_TLSetBehavior
+ */
+interface PptxSetAnimation {
+  /** Lowercased target attribute from `p:cBhvr/p:attrNameLst/p:attrName`. */
+  attrName: string;
+  /** Decoded value from `p:to` (same variant shape as a `p:tav/p:val`). */
+  value: string | boolean | number;
+  /** Discriminant indicating which `p:to` child carried the value. */
+  valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr';
+  /** Duration from this behaviour's nested `p:cTn/@dur`. */
+  durationMs?: number;
+  /** Start offset from this behaviour's nested `p:stCondLst`. */
+  delayMs?: number;
 }
 /**
  * Parsed `p:animEffect/@filter` (+ `@transition`) descriptor. ECMA-376
@@ -7182,6 +7579,16 @@ interface PptxElementAnimation {
    * OOXML equivalent and is not required for playback.
    */
   soundFileName?: string;
+  /**
+   * Per-build-level timing template(s) from the {@link sequence}'s own
+   * `p:bldP/p:tmplLst` (ECMA-376 §19.5.84), carried over from the loaded
+   * `PptxNativeAnimation.buildTemplates` this element animation was derived
+   * from so a full timing-tree rebuild (`PptxAnimationWriteService`'s
+   * `buildTimingXml`, when the slide had no prior `p:timing`) can re-emit
+   * them instead of silently dropping the deck's authored per-level
+   * defaults. Absent when {@link sequence} carries no such template.
+   */
+  buildTemplates?: PptxTimingTemplate[];
 }
 /**
  * A read-only anchor representing one of the deck's own effect groups: a
@@ -8098,6 +8505,22 @@ interface PptxActiveXControl {
   name?: string;
   /** Shape ID this control is linked to (from @spid). */
   shapeId?: string;
+  /**
+   * `p:control/@showAsIcon` (CT_Control, ECMA-376 S19.3.1.2): whether the
+   * control renders as its static icon rather than its live appearance.
+   * `undefined` when the source authored no explicit value (schema default
+   * `false`).
+   */
+  showAsIcon?: boolean;
+  /**
+   * `p:control/@imgW` in EMU (ST_PositiveCoordinate32): the width the host
+   * reserves for the control's icon/preview image. Distinct from
+   * {@link width}, which is the fallback `p:pic`'s own `a:ext/@cx` in px;
+   * `imgW`/`imgH` are direct attributes on `p:control` itself.
+   */
+  imgWidthEmu?: number;
+  /** `p:control/@imgH` in EMU (ST_PositiveCoordinate32). @see imgWidthEmu */
+  imgHeightEmu?: number;
   /** X position (px) of the control's fallback picture, if present. */
   x?: number;
   /** Y position (px) of the control's fallback picture, if present. */
@@ -8554,6 +8977,34 @@ interface PptxPhotoAlbum {
   layout?: string;
   /** Frame style applied to each photo (e.g. "frameStyle1"). */
   frame?: string;
+  /**
+   * `p:photoAlbum/@isPhoto` (ECMA-376 S19.2.1.27, CT_PhotoAlbum): whether
+   * the pictures placed by the album wizard are real photographs, as
+   * opposed to clip art or other embedded images. `undefined` when the
+   * source authored no explicit value (schema default `false`); this is a
+   * purely declarative wizard-provenance flag, not something this library
+   * gates any layout/frame behaviour on.
+   */
+  isPhoto?: boolean;
+}
+/**
+ * A recognizer-owned `p:smartTags` reference from `presentation.xml`
+ * (CT_SmartTags, ECMA-376 S19.2.1.42): a bare relationship id pointing at a
+ * legacy Office "Smart Tags" recognizer part, distinct from the
+ * user-authored `p:tags` construct (see {@link PptxTagCollection}).
+ *
+ * This library has no data model for recognizer part CONTENT (there is no
+ * way to create, inspect, or edit one through the public API), so this type
+ * only captures enough to preserve an authored reference losslessly: the
+ * relationship id and, when resolvable, the target part path.
+ */
+interface PptxSmartTagsReference {
+  /** Relationship id from `p:smartTags/@r:id`. */
+  relId: string;
+  /** Resolved ZIP path of the referenced recognizer part, when resolvable. */
+  targetPath?: string;
+  /** Raw `p:smartTags` XML retained for lossless round-trip. */
+  rawXml?: XmlObject;
 }
 /**
  * East Asian line-break (kinsoku) settings from `p:kinsoku` in `presentation.xml`.
@@ -8618,6 +9069,13 @@ interface PptxData {
   themeOptions?: PptxThemeOption[];
   /** Parsed table style definitions from `ppt/tableStyles.xml`. */
   tableStyleMap?: ParsedTableStyleMap;
+  /**
+   * The current default table style GUID (`ppt/tableStyles.xml`'s
+   * `a:tblStyleLst/@def`): the style PowerPoint applies to a newly inserted
+   * table. Matches `PptxSaveOptions.tableStylesDefaultId` so a save call
+   * that omits it can fall back to what was loaded.
+   */
+  tableStylesDefaultId?: string;
   /** Whether the presentation is password-protected. */
   isPasswordProtected?: boolean;
   /** Embedded font data (name + binary data URL) extracted from the presentation. */
@@ -8677,6 +9135,14 @@ interface PptxData {
   modifyVerifier?: PptxModifyVerifier;
   /** Photo album metadata from `p:photoAlbum` in `presentation.xml`. */
   photoAlbum?: PptxPhotoAlbum;
+  /**
+   * Legacy Smart Tags recognizer reference from `p:smartTags` in
+   * `presentation.xml`. Read-only: there is no data model for the
+   * recognizer part's own content, so this exists to make the reference
+   * inspectable and to prove it survives a save (the owning part and its
+   * relationship are preserved passively, like any other unmodelled part).
+   */
+  smartTags?: PptxSmartTagsReference;
   /** East Asian line-break settings from `p:kinsoku` in `presentation.xml`. */
   kinsoku?: PptxKinsoku;
   /** Custom XML data parts from `customXml/` in the OPC package. */
@@ -8841,6 +9307,14 @@ type FillInput = {
   type: 'solid';
   color: string;
   opacity?: number;
+  /**
+   * A theme colour to use instead of a plain hex. When set, the shape
+   * saves as `<a:schemeClr>` (e.g. `{ scheme: 'accent1', lumMod: 0.8 }`
+   * for "Accent 1, Lighter 80%") so it keeps following the theme after a
+   * later theme change; `color` still supplies the immediate resolved
+   * hex for renderers that read it directly.
+   */
+  themeColorRef?: PptxThemeColorRef;
 } | {
   type: 'gradient';
   /**
@@ -8876,6 +9350,8 @@ interface StrokeInput {
   opacity?: number;
   join?: 'round' | 'bevel' | 'miter';
   cap?: 'flat' | 'rnd' | 'sq';
+  /** A theme colour for the outline; see {@link FillInput}'s `themeColorRef`. */
+  themeColorRef?: PptxThemeColorRef;
 }
 interface ShadowInput {
   color?: string;
@@ -8892,6 +9368,8 @@ interface TextStyleInput {
   underline?: boolean;
   strikethrough?: boolean;
   color?: string;
+  /** A theme colour for the run; see {@link FillInput}'s `themeColorRef`. */
+  themeColorRef?: PptxThemeColorRef;
   alignment?: 'left' | 'center' | 'right' | 'justify';
   verticalAlignment?: 'top' | 'middle' | 'bottom';
   lineSpacing?: number;
@@ -9519,6 +9997,24 @@ interface PptxHandlerSaveOptions {
    * part untouched.
    */
   tableStyles?: ParsedTableStyleMap;
+  /**
+   * Set `ppt/tableStyles.xml`'s `<a:tblStyleLst @def>` to this style GUID
+   * (normalised to uppercase-with-braces). `undefined` preserves the
+   * existing default; there is no removal form (`@def` is required by the
+   * schema and PowerPoint always points it at a real style). No-op when the
+   * archive has no `ppt/tableStyles.xml`, same as {@link tableStyles}.
+   */
+  tableStylesDefaultId?: string;
+  /**
+   * Style GUIDs to remove from `ppt/tableStyles.xml` entirely, kept as a
+   * separate opt-in list rather than inferred from omission on
+   * {@link tableStyles}: that map is documented as safe to pass a PARTIAL
+   * edit (only the entries a caller actually touched), so treating every
+   * GUID missing from it as "delete this" would silently destroy untouched
+   * styles on an ordinary targeted edit. A GUID here that is also the
+   * current (or newly requested) default is left in place and skipped.
+   */
+  tableStylesToDelete?: string[];
   /**
    * Target output format.
    * - `'pptx'` (default): Standard presentation.