pptx-react-viewer 3.8.0 → 3.10.0

package/dist/viewer/index.d.ts

@@ -2147,6 +2147,29 @@ interface PptxElementBase {
   y: number;
   width: number;
   height: number;
+  /**
+   * The exact EMU integer `x` was parsed from (the `a:off/@_x` this
+   * element's own `a:xfrm` carried on load), when the parser could resolve
+   * one. `x` itself is always `Math.round(xEmu / EMU_PER_PX)` at parse
+   * time, but that rounding is lossy: re-deriving EMU from `x` on save
+   * (`Math.round(x * EMU_PER_PX)`) can drift from the original value by up
+   * to half a pixel's worth of EMU on every load/save cycle even when
+   * nothing touched this element. Kept alongside `x` (not instead of it) so
+   * every consumer that only cares about on-screen position is unaffected;
+   * only the save-side xfrm writer (`resolveXfrmEmu` in
+   * `xfrm-emu-resolution.ts`) reads this, and only when `x` still equals
+   * `Math.round(xEmu / EMU_PER_PX)` (i.e. nothing moved this element since
+   * load) does it re-emit `xEmu` verbatim instead of re-quantizing `x`.
+   * `undefined` for an SDK-created element or one whose transform could not
+   * be resolved to a usable `a:off` on load.
+   */
+  xEmu?: number;
+  /** The exact EMU integer `y` was parsed from (`a:off/@_y`). See {@link xEmu}. */
+  yEmu?: number;
+  /** The exact EMU integer `width` was parsed from (`a:ext/@_cx`). See {@link xEmu}. */
+  widthEmu?: number;
+  /** The exact EMU integer `height` was parsed from (`a:ext/@_cy`). See {@link xEmu}. */
+  heightEmu?: number;
   rotation?: number;
   /** Skew along the X axis in degrees (parsed from `@_skewX` in 1/60000ths of a degree). */
   skewX?: number;
@@ -2666,6 +2689,21 @@ interface PptxChartUserShapeGroupTransform {
     cx: number;
     cy: number;
   };
+  /**
+   * The group's own rotation in degrees (`a:xfrm/@rot`, stored in 60,000ths
+   * of a degree), when present. Rotates the whole group, and everything
+   * grouped inside it, as a rigid body about the CENTRE of the group's own
+   * box ({@link off}/{@link ext}); see `flattenChartUserShapes` in
+   * `chart-user-shapes-parser.ts` for how this composes onto each contained
+   * leaf's own {@link PptxChartUserShapeGroupChild.rotation}. Verified
+   * against real PowerPoint (COM): a `cdr:grpSp`'s `cdr:grpSpPr/a:xfrm` does
+   * carry `rot` the same way an ordinary shape's does.
+   */
+  rotation?: number;
+  /** The group's own horizontal flip (`a:xfrm/@flipH`), when present; composes onto children by XOR, see {@link rotation}'s doc. */
+  flipH?: boolean;
+  /** The group's own vertical flip (`a:xfrm/@flipV`), when present; composes onto children by XOR, see {@link rotation}'s doc. */
+  flipV?: boolean;
 }
 /**
  * One shape grouped inside a `cdr:grpSp` (or a nested `cdr:grpSp` itself).
@@ -2697,6 +2735,23 @@ interface PptxChartUserShapeGroupChild {
   strokeWidth?: number;
   /** Text paragraphs of the shape's `txBody`, when present. */
   paragraphs?: PptxChartUserShapeParagraph[];
+  /**
+   * A `pic` child's alt text (`cdr:nvPicPr/cdr:cNvPr/@descr`), when present.
+   * Editable independently of {@link rawXml}'s otherwise-verbatim content:
+   * the serializer patches only this attribute onto the cloned raw node.
+   */
+  altText?: string;
+  /**
+   * This child's OWN rotation in degrees (`a:xfrm/@rot`), when present.
+   * Composes with every enclosing group's own
+   * {@link PptxChartUserShapeGroupTransform.rotation} (added) to produce the
+   * leaf's final on-screen rotation; see `flattenChartUserShapes`.
+   */
+  rotation?: number;
+  /** This child's OWN horizontal flip (`a:xfrm/@flipH`); composes with an ancestor group's flip by XOR. */
+  flipH?: boolean;
+  /** This child's OWN vertical flip (`a:xfrm/@flipV`); composes with an ancestor group's flip by XOR. */
+  flipV?: boolean;
   /**
    * Verbatim source XML of a `pic`/`graphicFrame` child, or of this node
    * itself when `kind === 'grpSp'` and the nested group is untouched since
@@ -2755,6 +2810,29 @@ interface PptxChartUserShape {
   strokeWidth?: number;
   /** Text paragraphs of the shape's `txBody`, when present. */
   paragraphs?: PptxChartUserShapeParagraph[];
+  /**
+   * A `pic` anchor's alt text (`cdr:nvPicPr/cdr:cNvPr/@descr`), when
+   * present. Editable independently of {@link rawXml}'s otherwise-verbatim
+   * content: the serializer patches only this attribute onto the cloned
+   * raw node, so a picture's blip and other markup are untouched.
+   */
+  altText?: string;
+  /**
+   * This shape's OWN rotation in degrees (`a:xfrm/@rot`, on `spPr/a:xfrm`
+   * for `sp`/`cxnSp`/`pic`, or directly on a top-level `graphicFrame`'s own
+   * `a:xfrm`), when present. A top-level anchor's position/size is governed
+   * by {@link from}/{@link to}/{@link ext}, never by this `a:xfrm`'s own
+   * `off`/`ext` (see {@link rawXml}'s doc), but `rot`/`flipH`/`flipV` on that
+   * same `a:xfrm` DO apply visually: verified against real PowerPoint (COM),
+   * which writes e.g. `<a:xfrm rot="1800000"><a:off .../><a:ext .../></a:xfrm>`
+   * on a rotated overlay shape's `spPr`, with the `off`/`ext` values
+   * unrelated to the anchor's own `cdr:from`/`cdr:to`.
+   */
+  rotation?: number;
+  /** This shape's OWN horizontal flip (`a:xfrm/@flipH`); see {@link rotation}'s doc. */
+  flipH?: boolean;
+  /** This shape's OWN vertical flip (`a:xfrm/@flipV`); see {@link rotation}'s doc. */
+  flipV?: boolean;
   /**
    * Verbatim source XML of a `pic` or `graphicFrame` anchor child (the
    * `cdr:pic` / `cdr:graphicFrame` node itself, not the enclosing anchor),
@@ -2784,7 +2862,7 @@ interface PptxChartUserShape {
  * @example
  * ```ts
  * const type: PptxChartType = "bar";
- * // => "bar" — one of: "bar" | "line" | "pie" | "doughnut" | "area" | "scatter" | …
+ * // => "bar": one of: "bar" | "line" | "pie" | "doughnut" | "area" | "scatter" | …
  * ```
  */
 type PptxChartType = 'bar' | 'line' | 'pie' | 'ofPie' | 'doughnut' | 'area' | 'scatter' | 'bubble' | 'radar' | 'stock' | 'bar3D' | 'line3D' | 'pie3D' | 'area3D' | 'surface' | 'histogram' | 'waterfall' | 'funnel' | 'treemap' | 'sunburst' | 'boxWhisker' | 'regionMap' | 'combo' | 'unknown';
@@ -2819,7 +2897,7 @@ type PptxBar3DShape = 'box' | 'cone' | 'coneToMax' | 'cylinder' | 'pyramid' | 'p
  * @example
  * ```ts
  * const type: PptxChartTrendlineType = "linear";
- * // => "linear" — one of: "linear" | "exponential" | "logarithmic" | "polynomial" | "power" | "movingAvg"
+ * // => "linear": one of: "linear" | "exponential" | "logarithmic" | "polynomial" | "power" | "movingAvg"
  * ```
  */
 type PptxChartTrendlineType = 'linear' | 'exponential' | 'logarithmic' | 'polynomial' | 'power' | 'movingAvg';
@@ -2870,7 +2948,7 @@ type PptxChartErrBarType = 'both' | 'minus' | 'plus';
  * @example
  * ```ts
  * const valType: PptxChartErrValType = "percentage";
- * // => "percentage" — one of: "cust" | "fixedVal" | "percentage" | "stdDev" | "stdErr"
+ * // => "percentage": one of: "cust" | "fixedVal" | "percentage" | "stdDev" | "stdErr"
  * ```
  */
 type PptxChartErrValType = 'cust' | 'fixedVal' | 'percentage' | 'stdDev' | 'stdErr';
@@ -2989,9 +3067,29 @@ interface PptxChartDataPoint {
   bubble3D?: boolean;
   /** Per-point picture-fill flags (`c:dPt/c:pictureOptions`). */
   picture?: PptxChartDataPointPicture;
+  /**
+   * This point's identity GUID (`c:dPt/c:extLst/c:ext/c16:uniqueId/@val`,
+   * the Office 2014+ `{C3380CC4-5D6E-409C-BE32-E72D297353CC}` chart
+   * extension), read-only here: an edited point keeps its existing
+   * `c:extLst` as passthrough (see `chart-datapoint-serializer.ts`), so this
+   * field exists for introspection rather than round-trip.
+   */
+  uniqueId?: string;
 }
 /** Schema values accepted by `c:dLblPos`. */
 type PptxChartDataLabelPosition = 'bestFit' | 'b' | 'ctr' | 'inBase' | 'inEnd' | 'l' | 'outEnd' | 'r' | 't';
+/**
+ * `c15:dlblRangeCache`/`c15:datalabelsRange` (CT_SeriesDataLabelsRange):
+ * PowerPoint 2013+'s "Value From Cells" custom label source, one cell range
+ * supplying every label in a group (chart-type or series `c:dLbls`), with a
+ * cache aligned to point order. See `utils/chart-data-labels-range.ts`.
+ */
+interface PptxChartDataLabelsRange {
+  /** `c15:f`: the cell range formula (e.g. `Sheet1!$D$2:$D$5`). */
+  formula: string;
+  /** `c15:dlblRangeCache`: cached label text, index-aligned with data points. */
+  cache: string[];
+}
 /** Individual data label override (c:dLbl). */
 interface PptxChartDataLabel {
   idx: number;
@@ -3033,6 +3131,14 @@ interface PptxChartDataLabel {
    * over any chart/series-level default when set.
    */
   spPr?: PptxChartShapeProps;
+  /**
+   * `c15:xForSave`: this override exists only so its properties survive a
+   * save/reload round trip; PowerPoint merges it back onto the series'
+   * default label on load. Round-tripped as-is (an edited chart keeps an
+   * existing point's whole `extLst`, this flag included); introspection
+   * only otherwise. See `utils/chart-data-labels-range.ts`.
+   */
+  savedForCompatibilityOnly?: boolean;
 }
 /** Axis number format. */
 interface PptxChartAxisNumFmt {
@@ -3065,7 +3171,7 @@ interface PptxChartAxisFormatting extends PptxChartAxisLabelFormatting {
   axPos?: 'b' | 'l' | 'r' | 't';
   /** Unique axis identifier (c:axId/@val) used to link series to axes. */
   axisId?: number;
-  /** Cross-axis identifier — the axis this axis crosses. */
+  /** Cross-axis identifier: the axis this axis crosses. */
   crossAxisId?: number;
   /** Automatic crossing mode (`c:crosses`). Mutually exclusive with `crossesAt`. */
   crosses?: 'autoZero' | 'min' | 'max';
@@ -3317,6 +3423,54 @@ interface PptxChartSeries {
   waterfallOptions?: PptxChartWaterfallOptions;
   regionMapOptions?: PptxChartRegionMapOptions;
   treemapOptions?: PptxChartTreemapOptions;
+  /**
+   * Series-level picture-fill flags (`c:ser/c:pictureOptions`), legal
+   * wherever a per-point `c:dPt/c:pictureOptions` is (CT_BarSer): paints
+   * EVERY point in the series with one picture unless a `c:dPt` overrides it
+   * for that point alone. A point's own {@link PptxChartDataPoint.picture}
+   * takes precedence entirely (not merged field-by-field) when it resolves
+   * its own image; renderers fall back to this series-level picture only
+   * when the point has none of its own.
+   */
+  picture?: PptxChartDataPointPicture;
+  /**
+   * This series' identity GUID (`c:ser/c:extLst/c:ext/c16:uniqueId/@val`,
+   * the Office 2014+ `{C3380CC4-5D6E-409C-BE32-E72D297353CC}` chart
+   * extension). PowerPoint uses it to track a series across edits and
+   * collaborators independent of its `c:idx`/`c:order` position (the same
+   * role animation targeting and CRDT reconciliation need). An edited
+   * existing series keeps its own `c:extLst` as passthrough; a NEW series
+   * added by cloning an existing one as a template is given a freshly
+   * generated id rather than duplicating the template's (see
+   * `regenerateClonedUniqueId` in `chart-series-identity.ts`), since two
+   * series sharing one identity is exactly what this extension exists to
+   * prevent.
+   */
+  uniqueId?: string;
+}
+/**
+ * A series PowerPoint's "Chart Filters" feature hid from the plot while
+ * keeping it in the workbook (`c:<type>Chart/c:extLst/c:ext
+ * [@uri={02D57815-91ED-43cb-92C2-25804820EDAC}]/c15:filtered<Type>Series
+ * /c15:ser`). Read-mostly: {@link PptxChartData.filteredSeries} exists for
+ * introspection (AI tools, "unhide filtered series" UI) and round-trips as
+ * passthrough through the preserved chart XML when untouched. See
+ * `utils/chart-filtered-series.ts` for the parse rules and the idx-collision
+ * fix this modelling enables on save.
+ */
+interface PptxChartFilteredSeries {
+  /** `c15:ser/c:idx/@val`, the workbook column position this series still occupies. */
+  idx: number;
+  /** `c15:ser/c:order/@val`, defaulting to {@link idx} when absent. */
+  order: number;
+  /** Series name, from the hidden series' own `c:tx` cache. */
+  name?: string;
+  /** Category labels, from the hidden series' own `c:cat` cache. */
+  categories?: string[];
+  /** Data values, from the hidden series' own `c:val` cache. */
+  values?: number[];
+  /** This hidden series' own identity GUID (`c16:uniqueId`), when present. */
+  uniqueId?: string;
 }
 /**
  * Chart-level data-label options (`c:dLbls` directly under a chart-type
@@ -3340,6 +3494,19 @@ interface PptxChartDataLabelOptions {
   separator?: string;
   /** Show leader lines where supported (`c:showLeaderLines`). */
   showLeaderLines?: boolean;
+  /**
+   * Leader-line stroke styling for offset (pie/doughnut `outEnd`/`bestFit`)
+   * labels. Resolved from the base `c:leaderLines/c:spPr` when present, else
+   * falling back to the Office 2013+ chart15 extension's mirror
+   * (`c:extLst/c:ext/c15:leaderLines/c:spPr`, uri
+   * `{CE6537A1-D6FC-4f65-9D91-7224C49458BB}`), which is the one PowerPoint
+   * itself treats as authoritative when both are present. Confirmed against
+   * `e2e/fixtures/issue-132-gradient-fill.pptx` and
+   * `e2e/fixtures/issue-132-hr-deck.pptx`, both of which write only the
+   * extension form. `undefined` leaves the renderer's own default leader-line
+   * stroke.
+   */
+  leaderLineStyle?: PptxChartShapeProps;
   /**
    * Label position (`c:dLblPos`). Valid values depend on the chart type
    * (`ctr`, `inEnd`, `inBase`, `outEnd`, `bestFit`, `l`, `r`, `t`, `b`).
@@ -3360,6 +3527,22 @@ interface PptxChartDataLabelOptions {
    * (point > series > chart-type).
    */
   txPr?: PptxChartLegendTextStyle;
+  /**
+   * PowerPoint 2013+ "Value From Cells", series-wide form
+   * (`c15:datalabelsRange`, chart15 uri `{CE6537A1-...}`): one cell range
+   * supplies every label in this group, aligned by point index. A
+   * SERIES-WIDE alternative to the per-point `c15:dlblFieldTable` mechanism
+   * (already resolved into {@link PptxChartDataLabel.text} at parse time).
+   * See `utils/chart-data-labels-range.ts`.
+   */
+  dataLabelsRange?: PptxChartDataLabelsRange;
+  /**
+   * `c15:showDataLabelsRange` at the SAME level as {@link dataLabelsRange}:
+   * whether every label in this group resolves through the range's cache.
+   * Distinct from the per-point {@link PptxChartDataLabel} flag of the same
+   * XML name. Only meaningful when {@link dataLabelsRange} is set.
+   */
+  showDataLabelsRange?: boolean;
 }
 /** Typed text defaults for a single chart legend entry. */
 interface PptxChartLegendTextStyle {
@@ -3493,12 +3676,12 @@ interface PptxBubbleChartOptions {
  *
  * All fields are optional and round-trip verbatim.
  *
- * - {@link rotX} — X-axis rotation in degrees (-90…90).
- * - {@link rotY} — Y-axis rotation in degrees (0…360).
- * - {@link depthPercent} — chart depth as a percentage of base width.
- * - {@link rAngAx} — `true` if axes meet at right angles.
- * - {@link perspective} — perspective angle in degrees (0…240).
- * - {@link hPercent} — height as a percentage of chart width.
+ * - {@link rotX}: X-axis rotation in degrees (-90…90).
+ * - {@link rotY}: Y-axis rotation in degrees (0…360).
+ * - {@link depthPercent}: chart depth as a percentage of base width.
+ * - {@link rAngAx}: `true` if axes meet at right angles.
+ * - {@link perspective}: perspective angle in degrees (0…240).
+ * - {@link hPercent}: height as a percentage of chart width.
  */
 interface PptxChartView3D {
   rotX?: number;
@@ -3512,12 +3695,17 @@ interface PptxChartView3D {
  * Chart "chrome" flags from `c:chart` that round-trip cleanly even when
  * rendering ignores them.
  *
- * - {@link autoTitleDeleted} — `c:autoTitleDeleted/@val`. Suppresses the
+ * - {@link autoTitleDeleted}: `c:autoTitleDeleted/@val`. Suppresses the
  *   auto-generated title for single-series charts.
- * - {@link dispBlanksAs} — `c:dispBlanksAs/@val`. How blank cells
+ * - {@link dispBlanksAs}: `c:dispBlanksAs/@val`. How blank cells
  *   render: `"gap"`, `"zero"`, or `"span"`.
- * - {@link showDLblsOverMax} — `c:showDLblsOverMax/@val`. Keeps data
+ * - {@link showDLblsOverMax}: `c:showDLblsOverMax/@val`. Keeps data
  *   labels visible for points exceeding the value-axis maximum.
+ * - {@link dispNaAsBlank}: the Office 2017+ chart extension
+ *   `c:extLst/c:ext/c16r3:dataDisplayOptions16/c16r3:dispNaAsBlank/@val`
+ *   (uri `{56B9EC1D-385E-4148-901F-78D8002777C0}`), PowerPoint's "Show #N/A
+ *   as an empty cell" chart option. Confirmed against real corpus markup
+ *   (`e2e/fixtures/chart-data-fidelity.pptx`).
  *
  * `c:plotVisOnly` lives on {@link PptxChartData.plotVisibleOnly} and is
  * intentionally not duplicated here.
@@ -3526,6 +3714,7 @@ interface PptxChartChrome {
   autoTitleDeleted?: boolean;
   dispBlanksAs?: 'gap' | 'zero' | 'span';
   showDLblsOverMax?: boolean;
+  dispNaAsBlank?: boolean;
 }
 /** Manual chart placement from `c:layout/c:manualLayout` (CT_ManualLayout). */
 interface PptxChartManualLayout {
@@ -3621,6 +3810,26 @@ interface PptxChartData {
   categoryLevels?: string[][];
   dateCategories?: PptxChartDateCategories;
   series: PptxChartSeries[];
+  /**
+   * Series hidden from the plot by PowerPoint's "Chart Filters" feature
+   * (Series tab) but still present in the workbook, aggregated across every
+   * chart-type container (combo charts can carry more than one). Absent
+   * when the chart has no such extension. See {@link PptxChartFilteredSeries}.
+   */
+  filteredSeries?: PptxChartFilteredSeries[];
+  /**
+   * `c15:filteredSeriesTitle`: the auto-generated series title text (e.g.
+   * "Series 3") PowerPoint preserved when the chart filter hid the series
+   * whose data would otherwise have supplied it. See
+   * `utils/chart-ext-titles.ts`. Read-mostly like {@link filteredSeries}.
+   */
+  filteredSeriesTitle?: string;
+  /**
+   * `c15:filteredCategoryTitle`: the auto-numbered category labels ("1",
+   * "2", "3", ...) PowerPoint preserved when the chart filter hid the
+   * category axis source entirely. See `utils/chart-ext-titles.ts`.
+   */
+  filteredCategoryTitle?: string[];
   /** Chart style/formatting metadata. */
   style?: PptxChartStyle;
   /** Grouping mode for bar/area/line charts: 'clustered' | 'stacked' | 'percentStacked' */
@@ -3744,9 +3953,9 @@ interface PptxChartData {
   /**
    * Color cycling method from the chart color style part's `meth` attribute.
    *
-   * - `"cycle"` — repeat the palette colours in order (default)
-   * - `"withinLinear"` — gradient within each series
-   * - `"acrossLinear"` — gradient across series
+   * - `"cycle"`: repeat the palette colours in order (default)
+   * - `"withinLinear"`: gradient within each series
+   * - `"acrossLinear"`: gradient across series
    */
   colorMethod?: 'cycle' | 'withinLinear' | 'acrossLinear';
   /** Internal source color-style part path used for lossless dirty saves. */
@@ -4543,7 +4752,95 @@ interface PptxSmartArtLayoutNode {
   rules?: PptxSmartArtNumericRule[];
   /** `dgm:shape`: this node's own preset geometry override, when present. */
   shape?: PptxSmartArtLayoutNodeShape;
+  /**
+   * `dgm:presOf` (CT_PresentationOf, same iterator shape as `dgm:forEach`):
+   * which data-model point(s) this node's OWN text/geometry binds to -
+   * `axis: ['self']` the point currently being iterated, `['des']` all of
+   * its descendants, `['ch']` its direct children, and so on. Absent or
+   * empty `axis` (including a bare `<dgm:presOf/>`) means the node carries
+   * no text of its own (a pure positioning/decoration wrapper - `composite`,
+   * `sp` spacer, connector cap). See `smartart-layout-interpreter-item-
+   * roles.ts`, the one consumer: it is what lets the interpreter tell a
+   * text-bearing per-item role (a list layout's `childText`, a card
+   * layout's `roleText`/`bodyText`) apart from a same-generation sibling
+   * that positions or decorates instead.
+   */
+  presentationOf?: PptxSmartArtIteratorAttributes;
+  /**
+   * EVERY `dgm:constr` reachable from this node, including ones declared
+   * inside a `dgm:choose`/`dgm:if`/`dgm:else` that wraps THIS layoutNode's
+   * `constrLst` (a genuinely conditional constraint set, e.g. one branch
+   * per data-point count - `gear`'s composite positions its `gear1`/
+   * `gear2`/`gear3` slots this way, so its plain, direct-child-only
+   * `constraints` above is empty for it). Stops at a nested `dgm:layoutNode`
+   * boundary: that child's own conditional constrLst becomes ITS
+   * `allConstraints`, not folded into the parent's. Read-only /
+   * interpretation-only - `constraints` above (this node's own DIRECT
+   * constrLst) remains the one `applySmartArtLayoutDefinition` round-trips,
+   * so editing an unrelated property can never collapse a genuinely
+   * conditional constrLst into a single branch. `undefined` when this node
+   * declares no constrLst at all, in or out of a choose (the common case);
+   * otherwise a superset of `constraints` (every branch, blindly unioned -
+   * this interpreter does not evaluate `dgm:choose` conditions when
+   * indexing constraints, matching the same "flatten both branches"
+   * convention `nestedLayoutNodes` already uses for `children`). See
+   * `smartart-constraint-solver.ts`'s `buildConstraintIndex`, the only
+   * consumer.
+   */
+  allConstraints?: PptxSmartArtConstraint[];
   children?: PptxSmartArtLayoutNode[];
+  /**
+   * The iterator attributes of the ENCLOSING `dgm:forEach` this node was
+   * found through, when `nestedLayoutNodes` (`smartart-layout-definition
+   * .ts`) reached it by walking one - as opposed to being a direct child of
+   * its parent layoutNode, or reached only through a `dgm:choose` wrapper
+   * (a condition, not an iteration, leaves this `undefined`).
+   *
+   * `forEach` above records a node's OWN direct `dgm:forEach` children
+   * (which wrap ITS descendants); this is the opposite direction - the
+   * forEach that wraps the node ITSELF, one level up. A layoutNode can sit
+   * inside more than one enclosing forEach only via nesting, so this is
+   * always the SINGLE nearest one, not a list.
+   *
+   * This is what tells a genuinely repeated per-child template
+   * (`axis="ch"`, `ptType` absent or `"node"`) apart from a once-only or
+   * transition-only sibling that merely happens to sit inside SOME
+   * `dgm:forEach` (a `ptType="parTrans"`/`"sibTrans"` connector, or
+   * `axis="followSib" cnt="1"`) - both can be direct siblings under the
+   * SAME parent layoutNode (`lProcess1`'s `vertFlow` has one forEach for
+   * its `parTrans` connector and a SEPARATE one, `axis="ch"`, for its
+   * repeated `child` items; `vertFlow.forEach` bundles both, but only
+   * `child.forEachOrigin` says which ONE produced it). See
+   * `smartart-layout-interpreter-item-roles-recursive.ts`, the one
+   * consumer. Read-only / interpretation-only, like `allConstraints`:
+   * never round-tripped by `applySmartArtLayoutDefinition`.
+   */
+  forEachOrigin?: PptxSmartArtIteratorAttributes;
+  /**
+   * The condition of the NEAREST enclosing `dgm:if` this node was found
+   * through, when `nestedLayoutNodes` (`smartart-layout-definition.ts`)
+   * reached it via a `dgm:choose`'s `if` branch (as opposed to a direct
+   * child, a `dgm:else` branch - always `undefined` here, see below - or a
+   * `dgm:forEach`, which sets {@link forEachOrigin} instead). Lets a
+   * caller that already has the data-model node list decide whether this
+   * node's OWN branch is genuinely live for a specific point, instead of
+   * treating every choose-flattened branch as unconditionally present
+   * (`nestedLayoutNodes`' pre-existing "flatten every branch" convention,
+   * still the default when this is absent or a caller does not evaluate
+   * it) - e.g. `cycle-matrix--fallback-n2.pptx`'s `child1group`..
+   * `child4group`, each gated on a DIFFERENT top-level point existing and
+   * having its own child (`axis="ch ch" st="N 1" cnt="1 0" func="cnt"
+   * op="gte" val="1"`).
+   *
+   * Deliberately `undefined` for a `dgm:else` branch: ECMA-376 defines it
+   * as "none of the sibling ifs matched", which would need the FULL
+   * sibling list's conditions negated and ANDed together, not a single
+   * condition - no gallery fixture measured needs an else branch's own
+   * guard yet, so it is left unconditional (rendered by default, matching
+   * the pre-existing flatten-everything behaviour) rather than guessed at.
+   * Evaluate with `smartart-layout-interpreter-when.ts`'s `evaluateWhen`.
+   */
+  chooseGuard?: PptxSmartArtWhen;
 }
 /** Metadata and root node from DiagramML CT_DiagramDefinition. */
 interface PptxSmartArtLayoutDefinition {
@@ -5176,6 +5473,14 @@ interface PptxSmartArtData {
    * Consulted by the fallback layout engine for direction/org-chart hints.
    */
   presLayoutVars?: PptxSmartArtPresLayoutVars;
+  /**
+   * The deck's own theme minor-Latin font (`a:fontScheme/a:minorFont/a:latin/
+   * @typeface`): what SmartArt text actually renders in when no per-run
+   * `a:latin` override is present (the common case - see
+   * `smartart-layout-item-font-size.ts`'s font-fit, the one consumer).
+   * Undefined when the theme carries no font scheme at all.
+   */
+  themeMinorFont?: string;
   /** Relationship ID for the diagram data part (for round-trip save). */
   dataRelId?: string;
   /** Relationship ID for the diagram layout part. */
@@ -6135,7 +6440,7 @@ interface SmartArtPptxElement extends PptxElementBase {
  *
  * Used to show type-specific icons and previews in the editor.
  */
-type OleObjectType = 'excel' | 'word' | 'pdf' | 'visio' | 'mathtype' | 'package' | 'unknown';
+type OleObjectType = 'excel' | 'word' | 'powerpoint' | 'pdf' | 'visio' | 'mathtype' | 'package' | 'unknown';
 /**
  * An OLE (Object Linking and Embedding) object.
  *
@@ -6213,6 +6518,15 @@ interface OlePptxElement extends PptxElementBase {
    * `false`; `undefined` means the source authored no explicit value.
    */
   oleUpdateAutomatic?: boolean;
+  /**
+   * Set by the in-viewer OLE content editors (`ole-edit-api.ts`) whenever
+   * `oleEmbeddedData` and/or `previewImageData` have been changed in memory
+   * and still need to be written back into the saved package. Never
+   * authored from a parsed file; purely an in-memory save signal, mirroring
+   * `PptxSlide.isDirty`. The save writer clears it once the pending write
+   * has been queued.
+   */
+  oleContentDirty?: boolean;
   /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */
   altText?: string;
   /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */
@@ -6309,13 +6623,14 @@ interface MediaPptxElement extends PptxElementBase {
    */
   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`).
+   * Accessibility description. Read from `p:nvGraphicFramePr/p:cNvPr/@descr`
+   * for the `p:graphicFrame`-shaped (SDK-created) media form, or from
+   * `p:nvPicPr/p:cNvPr/@descr` for the `p:pic`-shaped media form (real
+   * PowerPoint's usual authoring shape for a video/audio placeholder); see
+   * `PptxHandlerRuntimePictureParsing.ts`.
    */
   altText?: string;
-  /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. Same scope note as {@link altText}. */
+  /** Accessibility title, from the same `@title` attribute on whichever `p:cNvPr` the media form uses. Same scope note as {@link altText}. */
   title?: string;
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
@@ -6342,6 +6657,46 @@ interface GroupPptxElement extends PptxElementBase {
   children: PptxElement[];
   /** Fill style extracted from the group's `p:grpSpPr`, used for `a:grpFill` inheritance. */
   groupFill?: ShapeStyle;
+  /**
+   * The SAME `p:grpSpPr` extraction as {@link groupFill}, kept whenever the
+   * group carries a `p:grpSpPr` at all, regardless of whether it resolved to
+   * a paintable fill.
+   *
+   * `groupFill` is `undefined` unless the group has a real fill, because
+   * `getGroupChildParentFill`/`groupChildInheritedFill` (the `a:grpFill`
+   * inheritance chain) must keep chaining through an ancestor's fill when
+   * THIS group has none of its own. A group whose `p:grpSpPr` authors only
+   * `a:effectLst` (shadow/glow/soft-edge/reflection, no fill) needs those
+   * effects to still reach the renderer, so they are kept here under a name
+   * that carries no fill-inheritance meaning. Currently only reflection is
+   * read from it (`getComputedEffectStyle`); the rest of `a:effectLst` on a
+   * group remains unsupported.
+   */
+  groupEffectStyle?: ShapeStyle;
+  /**
+   * Exact EMU the group's own `a:chOff`/`a:chExt` (the coordinate space its
+   * CHILDREN are authored in) were parsed from, alongside {@link
+   * PptxElementBase.xEmu} etc for the group's own placement in its PARENT's
+   * space. `undefined` when the source carried no usable `a:chOff`/`a:chExt`
+   * (an SDK-created group, or one whose `a:xfrm` had no child-space data).
+   *
+   * Used by `group-xfrm-preservation.ts`'s `hasCapturedChildSpace` to decide
+   * whether this group's original `a:chOff`/`a:chExt` can be re-emitted
+   * verbatim (always true once captured, regardless of whether anything in
+   * the subtree has moved or resized - only its DIRECT children's
+   * `a:off`/`a:ext` are recomputed, via `invertChildIntoGroupSpace`, when
+   * something changed), instead of the normalized `chOff 0,0` / `chExt ==
+   * ext` space the writer falls back to when this is `undefined` (or
+   * degenerate). See `group-shape-geometry.ts`'s module doc for why a group
+   * needs two coordinate systems at all.
+   */
+  chOffXEmu?: number;
+  /** See {@link chOffXEmu}. */
+  chOffYEmu?: number;
+  /** See {@link chOffXEmu}. */
+  chExtWidthEmu?: number;
+  /** See {@link chOffXEmu}. */
+  chExtHeightEmu?: number;
 }
 /**
  * A freehand ink / drawing stroke captured with a stylus or mouse.
@@ -6370,6 +6725,24 @@ interface InkPptxElement extends PptxElementBase {
    * variable-width strokes that reflect stylus/pen pressure.
    */
   inkPointPressures?: number[][];
+  /**
+   * Per-path arrays of per-point pen-tilt lean direction (degrees, straight
+   * from `PointerEvent.tiltX` on supporting hardware).
+   *
+   * Each entry corresponds to the path at the same index in `inkPaths`, and
+   * is paired positionally with {@link inkPointTiltY}. Present only when at
+   * least one point in the stroke reported a genuinely non-zero tilt: a
+   * device that never reports tilt (a mouse, or a stylus with no tilt
+   * sensor) leaves both arrays absent, the same way `inkPointPressures` is
+   * omitted when pressure never varies. When present, the renderer converts
+   * the raw `(tiltX, tiltY)` vector into a lean angle + magnitude (see
+   * `pptx-viewer-shared`'s `tiltChannelsFromVectors`) and widens the stroke
+   * perpendicular to the lean direction, approximating a chisel-tip
+   * calligraphy nib.
+   */
+  inkPointTiltX?: number[][];
+  /** Per-path, per-point pen-tilt lean direction (degrees), paired with {@link inkPointTiltX}. */
+  inkPointTiltY?: number[][];
   /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */
   extensionXml?: PptxGraphicFrameExtension[];
 }
@@ -6403,6 +6776,20 @@ interface ContentPartInkStroke {
    * {@link tiltAngles}.
    */
   tiltMagnitudes?: number[];
+  /**
+   * Which InkML channel pair {@link tiltAngles}/{@link tiltMagnitudes} were
+   * decoded from: `'azimuthAltitude'` when the source declared `AZIMUTH`
+   * (optionally paired with `ALTITUDE`); omitted (implying `OTx`/`OTy`, i.e.
+   * `'vector'`) otherwise, including for tilt this library itself captured
+   * from the Draw tool's `PointerEvent.tiltX`/`tiltY`.
+   *
+   * A save that has to rewrite this content part's InkML (see
+   * `inkml-content-part-writer.ts`) uses this to re-declare the SAME channel
+   * pair the file already used, rather than always converting to `OTx`/`OTy`;
+   * the rendered lean is identical either way; only the written channel
+   * NAMES differ.
+   */
+  tiltEncoding?: 'vector' | 'azimuthAltitude';
 }
 /**
  * A content-part element wrapped in `mc:AlternateContent`.
@@ -7059,10 +7446,27 @@ interface PptxNativeAnimation {
   buildLevel?: number;
   /** Group ID linking a `p:bldP` entry to its timing animation node. */
   groupId?: string;
-  /** Sound relationship ID to play when animation triggers (`p:stSnd`). */
+  /**
+   * Sound relationship ID to play when animation triggers. Modern PowerPoint
+   * (COM-verified against 2016) writes this as a `p:audio/p:cMediaNode`
+   * sibling of the effect's own `p:childTnLst`, targeting `p:sndTgt` rather
+   * than a shape; the legacy `p:stSnd` form (directly on `p:cTn`) is still
+   * accepted on load for round-trip of older-authored decks, but PowerPoint
+   * itself no longer writes it and does not recognise it back
+   * (`Effect.EffectInformation.SoundEffect` reads empty against it).
+   */
   soundRId?: string;
   /** Resolved sound file path from relationship. */
   soundPath?: string;
+  /**
+   * The embedded sound's `@_name` (from `p:snd`/`p:sndTgt`). For one of
+   * PowerPoint's 19 built-in stock sounds this is the exact upper-case file
+   * name PowerPoint itself writes (e.g. `"CHIMES.WAV"`); see
+   * `pptx-viewer-shared`'s `effect-sound-catalogue.ts`, which matches this
+   * value back to a gallery entry. Absent for a custom sound with no name,
+   * or when unresolved.
+   */
+  soundName?: string;
   /** Whether to stop any currently playing sound (`p:endSnd`). */
   stopSound?: boolean;
   /**
@@ -7227,17 +7631,28 @@ interface PptxNativeAnimation {
    */
   afterEffect?: boolean;
   /**
-   * "After animation" end-state behaviour carried over from the matching
-   * {@link PptxElementAnimation.afterAnimation} entry for this effect's
-   * element. Not populated by the native-timing parser itself (there is no
-   * single `p:cTn` attribute for it): `applyAfterAnimationFromEditorList` in
-   * `pptx-viewer-shared` merges it in from the editor's per-element
-   * animation list before playback, since that is the model the animation
-   * panel writes `afterAnimation` into.
+   * "After animation" end-state behaviour: dim-to-colour, hide-after-
+   * animation, or hide-on-next-click. Populated directly by the
+   * native-timing parser (`native-animation-after-effect.ts`) when the
+   * effect's `p:cTn/p:subTnLst` carries PowerPoint's genuine after-effect
+   * shape, so a real-world deck's build shows up here even with no
+   * `pptx:editorMeta`. `applyAfterAnimationFromEditorList` in
+   * `pptx-viewer-shared` overrides this from the matching
+   * {@link PptxElementAnimation.afterAnimation} entry when the editor's
+   * per-element animation list has one (the model the animation panel
+   * writes `afterAnimation` into), so an edit through our own UI always wins.
    */
   afterAnimationAction?: PptxAfterAnimationAction;
-  /** Dim-to color hex, present when {@link afterAnimationAction} is `dimToColor`. */
+  /** Dim-to color hex, present when {@link afterAnimationAction} is `dimToColor` AND the dim target is an already-resolved `a:srgbClr`. */
   afterAnimationColor?: string;
+  /**
+   * The typed theme reference when a `dimToColor` target is an `a:schemeClr`
+   * (e.g. `accent2`) instead of `a:srgbClr`: this parse layer has no theme to
+   * resolve it to sRGB with (see {@link afterAnimationColor}'s doc), so a
+   * playback consumer resolves this against the deck's theme colour map.
+   * Mutually exclusive with {@link afterAnimationColor} being set.
+   */
+  afterAnimationColorRef?: PptxThemeColorRef;
   /**
    * Parsed `p:animEffect` filter descriptor. `presetId`/`presetClass` remain
    * the primary effect selector (see `resolveEffect` in `pptx-viewer-shared`);
@@ -7369,13 +7784,46 @@ interface PptxAnimationKeyframe {
    * fidelity; consumers may use it to drive computed animation values.
    */
   fmla?: string;
+  /**
+   * The typed theme reference when a `p:val/p:clrVal` stop is an
+   * `a:schemeClr` (e.g. `accent1`), including any `tint`/`shade`/`lumMod`/
+   * `lumOff`/`alpha` children. {@link value} keeps the bare scheme name for
+   * round-trip; a playback consumer needs this ref (resolved against the
+   * deck's theme colour map) to turn the stop into a real CSS colour, which
+   * the bare name alone cannot do. Absent for an `a:srgbClr` stop, whose
+   * {@link value} is already a resolved `#rrggbb` hex string.
+   */
+  colorRef?: PptxThemeColorRef;
 }
 /** One generic `p:anim` behaviour inside a composed PowerPoint effect. */
 interface PptxAttributeAnimation {
   /** Lowercased target attribute from `p:attrNameLst`. */
   attrName: string;
-  /** Authored value stops from this behaviour's `p:tavLst`. */
+  /**
+   * Authored value stops from this behaviour's `p:tavLst`. Empty when the
+   * behaviour instead uses the simpler `from`/`to`/`by` attribute form (see
+   * below); at least one of `keyframes`, `from`/`to`, or `by` is present.
+   */
   keyframes: PptxAnimationKeyframe[];
+  /**
+   * `p:anim/@_from` (a formula string, ECMA-376 S19.5.4 CT_TLAnimateBehavior):
+   * the absolute starting value, used instead of `p:tavLst` when the
+   * behaviour only has two endpoints. PowerPoint writes this form for some
+   * built-in presets (e.g. "Grow And Turn"'s `ppt_x` fly-in): a bare
+   * `p:anim from="..." to="..."` with no `p:tavLst` child at all. See
+   * `animation-ppt-formula-ground-truth.md` in `pptx-viewer-shared` for the
+   * real-PowerPoint sample this was found in.
+   */
+  from?: string;
+  /** `p:anim/@_to`: the absolute ending value. See {@link from}. */
+  to?: string;
+  /**
+   * `p:anim/@_by`: a DELTA formula added to wherever the attribute already
+   * stands (as opposed to `from`/`to`'s absolute values), typically paired
+   * with `p:cBhvr/@_additive="sum"` so it composites with a sibling
+   * behaviour driving the same attribute instead of replacing it.
+   */
+  by?: string;
   /** Duration from this behaviour's nested `p:cTn/@dur`. */
   durationMs?: number;
   /** Start offset from this behaviour's nested `p:stCondLst`. */
@@ -7384,8 +7832,11 @@ interface PptxAttributeAnimation {
    * Interpolation mode from this behaviour's own `@_calcmode`
    * (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2): `discrete` snaps to
    * each `p:tav` stop with no interpolation, `lin` (the OOXML default)
-   * interpolates linearly, `fmla` evaluates `p:tav/@fmla` (not consulted at
-   * playback here; formulas are round-tripped only). Absent means `lin`.
+   * interpolates linearly. `fmla` as the WHOLE behaviour's calc mode has
+   * never been observed in a real PowerPoint file and is not consulted at
+   * playback; what PowerPoint actually writes is `calcmode="lin"` with a
+   * per-stop `p:tav/@fmla` (see {@link PptxAnimationKeyframe.fmla}), which
+   * IS consulted regardless of this field's value. Absent means `lin`.
    */
   calcMode?: 'discrete' | 'lin' | 'fmla';
 }
@@ -7411,16 +7862,31 @@ interface PptxColorAnimation {
    * companion to `@dir` for HSL colour-space animations.
    */
   path?: string;
-  /** Starting color as hex string. */
+  /** Starting color as hex string, or the bare scheme name (e.g. `accent1`) for a theme colour; see {@link fromColorRef}. */
   fromColor?: string;
-  /** Ending color as hex string. */
+  /** Ending color as hex string, or the bare scheme name; see {@link toColorRef}. */
   toColor?: string;
   /**
-   * Color delta (for "by" animations) as hex string. For HSL colour-space
-   * animations this retains the historical byte-packed compatibility value;
-   * consumers should prefer {@link hslDelta}, which preserves signed values.
+   * Color delta (for "by" animations) as hex string, or the bare scheme name;
+   * see {@link byColorRef}. For HSL colour-space animations this retains the
+   * historical byte-packed compatibility value; consumers should prefer
+   * {@link hslDelta}, which preserves signed values.
    */
   byColor?: string;
+  /**
+   * The typed theme reference when {@link fromColor} is an `a:schemeClr`
+   * (including `tint`/`shade`/`lumMod`/`lumOff`/`alpha`), so playback can
+   * resolve it against the deck's theme colour map. Absent when `fromColor`
+   * is already a resolved `#rrggbb` hex (an `a:srgbClr` stop).
+   */
+  fromColorRef?: PptxThemeColorRef;
+  /** The typed theme reference for {@link toColor}; see {@link fromColorRef}. */
+  toColorRef?: PptxThemeColorRef;
+  /**
+   * The typed theme reference for {@link byColor} (RGB colour space only; an
+   * HSL `by` is a signed delta, never a theme colour). See {@link fromColorRef}.
+   */
+  byColorRef?: PptxThemeColorRef;
   /**
    * Typed HSL delta from `p:by/p:hsl`. This preserves signed values and their
    * OOXML units without forcing them through the legacy byte-packed `byColor`
@@ -7560,10 +8026,24 @@ interface PptxElementAnimation {
   motionPathRotationCenterX?: number;
   /** Motion-path rotation centre Y in slide percentage units (`p:rCtr/@y`). */
   motionPathRotationCenterY?: number;
-  /** Sound relationship ID to play when animation triggers (`p:stSnd`). */
+  /**
+   * Sound relationship ID to play when animation triggers. Written on save
+   * as a `p:audio/p:cMediaNode` sibling of the effect's own `p:childTnLst`
+   * (see `PptxNativeAnimation.soundRId` for the COM-verified detail).
+   */
   soundRId?: string;
   /** Resolved sound file path from relationship. */
   soundPath?: string;
+  /**
+   * The `@_name` to write on the embedded sound (`p:sndTgt`). For a stock
+   * gallery pick this is the exact PowerPoint file name (e.g.
+   * `"CHIMES.WAV"`), which is what makes PowerPoint itself recognise the
+   * sound as that built-in entry when it reopens the saved deck (there is no
+   * separate "built-in" flag anywhere in the schema). Set by
+   * `pptx-viewer-shared`'s `setEffectSound` when the pick carries a
+   * `soundName`; absent for a custom file with no meaningful name.
+   */
+  soundName?: string;
   /** Whether to stop any currently playing sound (`p:endSnd`). */
   stopSound?: boolean;
   /**
@@ -7578,7 +8058,9 @@ interface PptxElementAnimation {
   /**
    * Display name for the chosen sound (e.g. the uploaded file's name),
    * shown by the authoring UI's sound picker. Purely cosmetic; has no
-   * OOXML equivalent and is not required for playback.
+   * OOXML equivalent and is not required for playback. For a stock gallery
+   * pick, the UI derives its label from {@link soundName} via the catalogue
+   * instead of this field.
    */
   soundFileName?: string;
   /**
@@ -8633,13 +9115,13 @@ interface PptxSlide {
   backgroundPattern?: PptxSlideBackgroundPattern;
   /**
    * `<p:bgPr/@shadeToTitle>`: boolean flag instructing the renderer to
-   * shade the background gradient toward the title placeholder's text
-   * colour. Parsed and round-tripped here on the core model; the actual
-   * visual effect is applied by `pptx-viewer-shared`'s
+   * anchor the background gradient on the title placeholder as a
+   * rectangular path gradient (COM-measured against real PowerPoint;
+   * it does NOT recolour toward the title's text colour, despite the
+   * attribute's name). Parsed and round-tripped here on the core model;
+   * the actual visual effect is applied by `pptx-viewer-shared`'s
    * `getSlideBackgroundStyle` (see `render/background-shade-to-title.ts`),
-   * consumed by all five bindings, not by core itself. That module's
-   * docstring explains the approximation: no published ECMA-376 or
-   * MS-ODRAWXML text documents the exact legacy blend. Legacy PowerPoint
+   * consumed by all five bindings, not by core itself. Legacy PowerPoint
    * 97-2003 hint, not observed in any real-world corpus file this project
    * has collected and not settable from any modern PowerPoint UI; see
    * `docs/guide/limitations.md`.
@@ -9926,7 +10408,7 @@ interface PptxHandlerLoadOptions {
   allowExternalImages?: boolean;
 }
 /** Output format for the save pipeline. */
-type PptxSaveFormat = 'pptx' | 'ppsx' | 'pptm';
+type PptxSaveFormat = 'pptx' | 'ppsx' | 'pptm' | 'ppt';
 interface PptxHandlerSaveOptions {
   headerFooter?: PptxHeaderFooter;
   presentationProperties?: PptxPresentationProperties;
@@ -10022,8 +10504,23 @@ interface PptxHandlerSaveOptions {
    * - `'pptx'` (default): Standard presentation.
    * - `'ppsx'`: Slide-show file (opens in presentation mode).
    * - `'pptm'`: Macro-enabled presentation (requires VBA data).
+   * - `'ppt'`: Legacy binary PowerPoint 97-2003 presentation. Bypasses the
+   *   OOXML ZIP pipeline entirely; see `PptxHandlerRuntimeSaveLegacyPpt`.
+   *   Elements with no binary equivalent (charts, SmartArt, media, OLE, ink,
+   *   3D models) are degraded to a rasterised preview picture or a labelled
+   *   placeholder, each reported via a `scope: 'save'`-adjacent
+   *   `PptxCompatibilityWarning`.
    */
   outputFormat?: PptxSaveFormat;
+  /**
+   * Password for RC4 CryptoAPI encryption of a `'ppt'`-format save. Ignored
+   * for every other {@link outputFormat}; encrypting a `.pptx`/`.ppsx`/`.pptm`
+   * save uses {@link IPptxHandlerRuntime.saveEncrypted}'s separate AES/Agile
+   * OLE2 wrapping instead, since the legacy binary format's own encryption
+   * scheme is embedded directly in the `.ppt` stream rather than wrapping an
+   * already-produced package.
+   */
+  pptPassword?: string;
   /**
    * Embedded fonts to write back (or add) to the saved PPTX.
    *