pptx-react-viewer 3.8.0 → 3.9.0

package/dist/index.d.ts

@@ -2165,6 +2165,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;
@@ -2684,6 +2707,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).
@@ -2715,6 +2753,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
@@ -2773,6 +2828,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),
@@ -2802,7 +2880,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';
@@ -2837,7 +2915,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';
@@ -2888,7 +2966,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';
@@ -3007,6 +3085,14 @@ 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';
@@ -3083,7 +3169,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';
@@ -3335,6 +3421,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
@@ -3358,6 +3492,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`).
@@ -3511,12 +3658,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;
@@ -3530,12 +3677,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.
@@ -3544,6 +3696,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 {
@@ -3639,6 +3792,13 @@ 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[];
   /** Chart style/formatting metadata. */
   style?: PptxChartStyle;
   /** Grouping mode for bar/area/line charts: 'clustered' | 'stacked' | 'percentStacked' */
@@ -3762,9 +3922,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. */
@@ -6327,13 +6487,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[];
@@ -6360,6 +6521,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.
@@ -6388,6 +6589,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[];
 }
@@ -6421,6 +6640,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`.
@@ -7245,17 +7478,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`);
@@ -7387,13 +7631,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`. */
@@ -7402,8 +7679,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';
 }
@@ -7429,16 +7709,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`
@@ -8651,13 +8946,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`.
@@ -10899,6 +11194,23 @@ declare const THEME_CATALOG: readonly ThemeCatalogEntry[];
 /** Look up a catalog entry by key, falling back to `undefined` (the built-in default) if not found. */
 declare function resolveThemeCatalogEntry(key: string | undefined, catalog?: readonly ThemeCatalogEntry[]): ViewerTheme | undefined;
 
+//#region src/render/animation-text-style-resolve.d.ts
+/**
+ * Framework-neutral text-style override a font-style emphasis effect applies
+ * on top of its target's own authored per-run bold/italic/underline/size/
+ * colour. Every binding maps this onto its own text container so it OVERRIDES
+ * the runs' inline styles (the runs carry explicit inline styles of their
+ * own, so plain CSS inheritance cannot reach them).
+ */
+interface TextStyleAnimationDescriptor {
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  /** Relative multiplier against each run's own authored font size. */
+  fontScale?: number;
+  color?: string;
+}
+
 /** Viewer interaction mode: read-only, edit, presentation, or master-view. */
 type ViewerMode = 'preview' | 'edit' | 'present' | 'master';
 /**
@@ -11065,22 +11377,15 @@ interface CollaborationConfig {
   writeBackDebounceMs?: number;
 }
 //#endregion
-//#region src/render/animation-text-style-resolve.d.ts
+//#region src/render/animation-timeline-build-descriptors.d.ts
 /**
- * Framework-neutral text-style override a font-style emphasis effect applies
- * on top of its target's own authored per-run bold/italic/underline/size/
- * colour. Every binding maps this onto its own text container so it OVERRIDES
- * the runs' inline styles (the runs carry explicit inline styles of their
- * own, so plain CSS inheritance cannot reach them).
+ * `animation-timeline-build-descriptors` - staged-build (`p:bldChart` /
+ * `p:bldDgm`) reveal descriptor types, split out of `animation-timeline-types`
+ * to keep that module under the file-size limit. Re-exported from
+ * `animation-timeline-types` so existing imports are unaffected.
+ *
+ * @module render/animation-timeline-build-descriptors
  */
-interface TextStyleAnimationDescriptor {
-  bold?: boolean;
-  italic?: boolean;
-  underline?: boolean;
-  /** Relative multiplier against each run's own authored font size. */
-  fontScale?: number;
-  color?: string;
-}
 /**
  * Normalized staged-reveal mode for a chart graphic frame, derived from the
  * OOXML `a:bldChart/@bld` (or `p:bldOleChart/@bld`) token:
@@ -11114,12 +11419,12 @@ interface ChartRevealPoint {
  * Playback-time chart reveal state derived from AUTHORED `p:graphicEl`
  * indices (see `chart-reveal-descriptor`'s `resolveChartRevealDescriptor`),
  * rather than from click-count/time progress. Present on
- * {@link ElementAnimationState.chartReveal} only when every fired
- * chart-build step for the element carried index data; a renderer prefers
- * this over the progress-based `build`/`ElementBuildState` path when present,
- * since it reflects the real authored reveal set (correct even for a
- * reversed-order or gapped chart build), and falls back to `build` when
- * absent.
+ * {@link import('./animation-timeline-group').ElementAnimationState.chartReveal}
+ * only when every fired chart-build step for the element carried index data;
+ * a renderer prefers this over the progress-based `build`/`ElementBuildState`
+ * path when present, since it reflects the real authored reveal set (correct
+ * even for a reversed-order or gapped chart build), and falls back to `build`
+ * when absent.
  */
 interface ChartRevealDescriptor {
   /**
@@ -11140,12 +11445,13 @@ interface ChartRevealDescriptor {
  * Playback-time SmartArt diagram reveal state derived from AUTHORED
  * `p:graphicEl/p:dgm/@id` indices (see `diagram-reveal-descriptor`'s
  * `resolveDiagramRevealDescriptor`), rather than from click-count/time
- * progress. Present on {@link ElementAnimationState.diagramReveal} only when
- * every fired diagram-build step for the element carried `p:graphicEl` data.
- * A SmartArt renderer prefers this over the progress-based `build` /
- * {@link ElementBuildState} path when present, since it reflects the real
- * authored reveal set (correct even for a reversed-order or by-branch build),
- * and falls back to `build` when absent.
+ * progress. Present on
+ * {@link import('./animation-timeline-group').ElementAnimationState.diagramReveal}
+ * only when every fired diagram-build step for the element carried
+ * `p:graphicEl` data. A SmartArt renderer prefers this over the
+ * progress-based `build` / {@link ElementBuildState} path when present, since
+ * it reflects the real authored reveal set (correct even for a
+ * reversed-order or by-branch build), and falls back to `build` when absent.
  */
 interface DiagramRevealDescriptor {
   /**
@@ -11158,9 +11464,11 @@ interface DiagramRevealDescriptor {
   nodeIds: ReadonlySet<string>;
 }
 /**
- * Playback-time staged-build state surfaced on {@link ElementAnimationState}.
- * `progress` is the 0..1 fraction of the build revealed at the current playback
- * time; a consumer maps it to its own item COUNT (see `revealedStageCount`).
+ * Playback-time staged-build state surfaced on
+ * {@link import('./animation-timeline-group').ElementAnimationState}.
+ * `progress` is the 0..1 fraction of the build revealed at the current
+ * playback time; a consumer maps it to its own item COUNT (see
+ * `revealedStageCount`).
  */
 type ElementBuildState = {
   kind: 'chart';
@@ -11223,14 +11531,14 @@ interface ElementAnimationState {
   animatesStroke?: boolean;
   /**
    * Active discrete font-style / colour / size override (see
-   * {@link TimelineStep.textStyle}) a font-style emphasis effect currently
-   * applies to this element's text, OVERRIDING the runs' own inline
-   * bold/italic/underline/size/colour. `animation-playback-engine.ts` writes
-   * this on step start and again on cleanup (held in full when the effect's
-   * `p:cTn/@fill` holds its end state, otherwise reverted); a text renderer
-   * maps it onto its run markup via `buildTextStyleOverrideCss`
-   * (`animation-text-style-css.ts`). Absent means no font-style emphasis
-   * effect is currently active on this element.
+   * {@link import('./animation-timeline-step').TimelineStep.textStyle}) a
+   * font-style emphasis effect currently applies to this element's text,
+   * OVERRIDING the runs' own inline bold/italic/underline/size/colour.
+   * `animation-playback-engine.ts` writes this on step start and again on
+   * cleanup (held in full when the effect's `p:cTn/@fill` holds its end
+   * state, otherwise reverted); a text renderer maps it onto its run markup
+   * via `buildTextStyleOverrideCss` (`animation-text-style-css.ts`). Absent
+   * means no font-style emphasis effect is currently active on this element.
    */
   textStyle?: TextStyleAnimationDescriptor;
 }