pptx-react-viewer 3.8.0 → 3.9.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,6 +3067,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';
@@ -3065,7 +3151,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 +3403,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 +3474,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`).
@@ -3493,12 +3640,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 +3659,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 +3678,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 +3774,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' */
@@ -3744,9 +3904,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. */
@@ -6309,13 +6469,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 +6503,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 +6571,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 +6622,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`.
@@ -7227,17 +7460,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 +7613,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 +7661,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 +7691,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`
@@ -8633,13 +8928,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`.