ooxml-ui 0.30.1 → 1.0.0

package/dist/pptx/render/animation-text-style-resolve.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `animation-text-style-resolve` - resolves the discrete font-style / colour /
+ * size override PowerPoint's font-style emphasis effects apply to their
+ * target's text: Bold Flash, Bold Reveal, Underline, Brush On Underline,
+ * Font Style / Change Font Style, Change Font Size, and the font-style `p:set`
+ * siblings composed alongside Wave / Grow With Color / Teeter.
+ *
+ * PowerPoint authors these two ways, both already parsed by core:
+ *  - A `p:set` discrete (non-interpolated) assignment
+ *    ({@link PptxNativeAnimation.setAnimations}, ECMA-376 S19.5.79
+ *    CT_TLSetBehavior): the value snaps on once and holds until the effect's
+ *    `p:cTn/@fill` says otherwise (Bold Reveal, Underline / Brush On
+ *    Underline).
+ *  - A generic `p:anim` ramp ({@link PptxNativeAnimation.attributeAnimations},
+ *    ECMA-376 S19.5.2 CT_TLAnimateBehavior) whose `p:tavLst` stops are not
+ *    numerically interpolatable for a boolean attribute (Bold Flash): only the
+ *    LAST stop's value is meaningful, the same "snap at the end" reading
+ *    PowerPoint itself gives a discrete `calcMode` ramp.
+ *
+ * Ground truth (COM `AddEffect` + raw OOXML inspection, see
+ * `animation-emphasis-ground-truth-early.ts`): `style.fontWeight` (bold),
+ * `style.fontStyle` (italic), `style.textDecorationUnderline` (underline),
+ * `style.fontSize` (a numeric ramp: this module reads its FIRST/LAST stop
+ * ratio as {@link TextStyleAnimationDescriptor.fontScale}, a relative
+ * multiplier rather than an absolute size, since a shape's runs may not all
+ * share the authored effect's own reference size), and `style.color` (font
+ * colour, distinct from `fillcolor`/`stroke.color`, which the existing
+ * `p:animClr` colour-animation path already owns).
+ *
+ * Deliberately does NOT model a "during" vs "after" phase distinction: the
+ * hold-vs-revert decision this effect's `p:cTn/@fill` makes is already
+ * computed once, correctly, by `animation-fill-repeat.ts`'s
+ * `shouldHoldEndState` (the exact same rule CSS-animation steps already use
+ * to decide whether their final frame persists on cleanup) and surfaced on
+ * {@link import('./animation-timeline-types').TimelineStep.holdEndState}.
+ * `animation-text-style-state.ts` reuses that flag rather than recomputing
+ * hold/revert semantics a second time here.
+ *
+ * @module render/animation-text-style-resolve
+ */
+import type { PptxNativeAnimation } from 'ooxml-core/pptx';
+/**
+ * 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).
+ */
+export interface TextStyleAnimationDescriptor {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    /** Relative multiplier against each run's own authored font size. */
+    fontScale?: number;
+    color?: string;
+}
+/**
+ * Resolve the text-style override an authored effect composes via `p:set`
+ * siblings and/or a `style.fontsize`/boolean `p:anim` ramp. Returns
+ * `undefined` when the effect carries none of the recognised attrs, so a
+ * caller can fall back to the neutral emphasis animation exactly as before.
+ */
+export declare function resolveTextStyleAnimation(anim: Pick<PptxNativeAnimation, 'setAnimations' | 'attributeAnimations'>): TextStyleAnimationDescriptor | undefined;
+//# sourceMappingURL=animation-text-style-resolve.d.ts.map

package/dist/pptx/render/animation-text-style-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-text-style-resolve.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-text-style-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAEX,mBAAmB,EAEnB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,WAAW,4BAA4B;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAmGD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,eAAe,GAAG,qBAAqB,CAAC,GACtE,4BAA4B,GAAG,SAAS,CAW1C"}

package/dist/pptx/render/animation-text-style-state.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `animation-text-style-state` - pure merge/revert helpers for carrying a
+ * {@link TextStyleAnimationDescriptor} through `animation-playback-engine.ts`'s
+ * step-start and step-cleanup writes, mirroring how `carryBuildState` already
+ * carries `build`/`chartReveal`/`diagramReveal` forward so one step's write
+ * never clobbers a concern a DIFFERENT still-active step on the same element
+ * owns.
+ *
+ * @module render/animation-text-style-state
+ */
+import type { TextStyleAnimationDescriptor } from './animation-text-style-resolve.js';
+/**
+ * Merge a step's text-style override onto whatever the element already
+ * carries (from a still-active earlier step), on step START. The new step's
+ * fields win on a conflict; fields it does not mention pass through
+ * unchanged.
+ */
+export declare function mergeTextStyleOnStart(carried: TextStyleAnimationDescriptor | undefined, stepStyle: TextStyleAnimationDescriptor | undefined): TextStyleAnimationDescriptor | undefined;
+/**
+ * Resolve the text-style override left after a step's CLEANUP.
+ *
+ * `holdEndState` mirrors `p:cTn/@fill="hold"/"freeze"/"transition"` (see
+ * `animation-fill-repeat.ts`'s `shouldHoldEndState`, the same flag that keeps
+ * a CSS animation's final frame attached instead of clearing it): when set,
+ * the step's fields stay merged in permanently; otherwise only the KEYS this
+ * step itself set are reverted, so a different still-active step's fields
+ * (e.g. a concurrent colour change) are not clobbered.
+ */
+export declare function resolveTextStyleOnCleanup(carried: TextStyleAnimationDescriptor | undefined, stepStyle: TextStyleAnimationDescriptor | undefined, holdEndState: boolean | undefined): TextStyleAnimationDescriptor | undefined;
+//# sourceMappingURL=animation-text-style-state.d.ts.map

package/dist/pptx/render/animation-text-style-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-text-style-state.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-text-style-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAEnF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,4BAA4B,GAAG,SAAS,EACjD,SAAS,EAAE,4BAA4B,GAAG,SAAS,GACjD,4BAA4B,GAAG,SAAS,CAK1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,4BAA4B,GAAG,SAAS,EACjD,SAAS,EAAE,4BAA4B,GAAG,SAAS,EACnD,YAAY,EAAE,OAAO,GAAG,SAAS,GAC/B,4BAA4B,GAAG,SAAS,CAe1C"}

package/dist/pptx/render/animation-timeline-absolute.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `animation-timeline-absolute`  -  dynamic CSS `@keyframes` for the absolute
+ * `from`/`to` form of `p:animRot` (ST_Angle) and `p:animScale`
+ * (percentage), and for a `p:tavLst` ramp attached to a generic `p:anim`
+ * behaviour (opacity or colour).
+ *
+ * {@link buildDynamicKeyframe} / {@link buildDynamicKeyframes} in
+ * `animation-timeline-helpers` already handle the RELATIVE `@by` form
+ * (`rotationBy` / `scaleByX` / `scaleByY`); this module covers the sibling
+ * absolute form, which OOXML allows instead of (or alongside) `@by`:
+ * ECMA-376 S19.5.7 CT_TLAnimateRotationBehavior and S19.5.8
+ * CT_TLAnimateScaleBehavior both make `from`/`to`/`by` independently
+ * optional. Only the relative form was ever read, so a deck that authored
+ * "rotate from 0 to 180" (no `@by`) or "scale from 50% to 150%" produced no
+ * rotation/scale keyframes at all and the effect silently did nothing.
+ *
+ * `p:tavLst` (ECMA-376 S19.5.30 CT_TLAnimVariantList) is schema-generic: a
+ * `p:anim` node can drive ANY attribute its `p:attrNameLst/p:attrName` names,
+ * and until the core parser surfaced that name (`PptxNativeAnimation.attrName`)
+ * this module could only guess from the keyframe VALUE shape, which is why it
+ * only ever recognised a numeric `[0, 1]` ramp as opacity. With the attribute
+ * name available, {@link buildOpacityTavKeyframe} now confirms it against a
+ * known opacity name instead of trusting the value shape alone, and
+ * {@link buildColorTavKeyframe} covers the sibling case: a multi-stop colour
+ * ramp on `fillcolor` / `fill.color` / `style.color` / `stroke.color`, reusing
+ * the same attribute -> CSS-property mapping as the dedicated `p:animClr`
+ * behaviour (`animation-color.ts`). Every other attribute name (position,
+ * size, and anything this module cannot confirm a CSS mapping for) is left on
+ * the caller's canned-timing fallback; see `docs/guide/limitations.md`.
+ *
+ * @module render/animation-timeline-absolute
+ */
+import type { PptxNativeAnimation } from 'ooxml-core/pptx';
+/**
+ * Build an absolute-rotation `@keyframes` block from `rotationFrom`/
+ * `rotationTo`, or `undefined` when the animation has no absolute rotation
+ * (including when a relative `rotationBy` is present, which the caller
+ * already handles and takes priority over this).
+ *
+ * A `from` with no `to` (or vice versa) still produces a sensible sweep: the
+ * missing bound defaults to the other one's value so the animation is a
+ * no-op turn rather than being dropped, matching how PowerPoint treats a
+ * partially-specified rotation as ending at its one given angle.
+ */
+export declare function buildAbsoluteRotationKeyframe(anim: Pick<PptxNativeAnimation, 'rotationBy' | 'rotationFrom' | 'rotationTo'>, namePrefix: string, uid: number): {
+    keyframeName: string;
+    css: string;
+} | undefined;
+/**
+ * Build an absolute-scale `@keyframes` block from `scaleFromX`/`scaleFromY`/
+ * `scaleToX`/`scaleToY`, or `undefined` when the animation has no absolute
+ * scale (including when a relative `scaleByX`/`scaleByY` is present, which
+ * the caller already handles and takes priority over this).
+ *
+ * A missing `from` defaults to 1 (unscaled) and a missing `to` defaults to
+ * the `from` value, mirroring {@link buildAbsoluteRotationKeyframe}'s
+ * one-bound-given handling.
+ */
+export declare function buildAbsoluteScaleKeyframe(anim: Pick<PptxNativeAnimation, 'scaleByX' | 'scaleByY' | 'scaleFromX' | 'scaleFromY' | 'scaleToX' | 'scaleToY'>, namePrefix: string, uid: number): {
+    keyframeName: string;
+    css: string;
+} | undefined;
+/**
+ * Build a multi-stop opacity `@keyframes` block from a `p:tavLst` keyframe
+ * list (parsed onto {@link PptxNativeAnimation.keyframes}), or `undefined`
+ * when the list is missing, has fewer than two usable stops, names an
+ * attribute other than opacity, or carries a value shape this can't
+ * confidently interpret as opacity.
+ *
+ * `p:tavLst` is schema-generic (ECMA-376 S19.5.30 CT_TLAnimVariantList): a
+ * `p:anim` node can drive any numeric/string/color/bool attribute its
+ * `p:attrNameLst` names. When the parser DID surface that name
+ * ({@link PptxNativeAnimation.attrName}), it is trusted outright: anything
+ * other than a known opacity name bails immediately, so e.g. a `ppt_w`
+ * size ramp that happens to fall in `[0, 1]` is never misread as opacity.
+ * When the name is absent (older parses, or a deck whose `p:cBhvr` omitted
+ * `p:attrNameLst` entirely), this falls back to the original heuristic:
+ * numeric (`flt`/`int`) stops in the `[0, 1]` fractional range on an
+ * EMPHASIS effect, which is exactly what PowerPoint's own "Transparency"
+ * effect (and any custom multi-stage fade) writes. Outside that shape the
+ * caller keeps its existing (2-stop, canned) behaviour, so nothing regresses.
+ */
+export declare function buildOpacityTavKeyframe(anim: Pick<PptxNativeAnimation, 'keyframes' | 'presetClass' | 'attrName' | 'calcMode'>, namePrefix: string, uid: number): {
+    keyframeName: string;
+    css: string;
+} | undefined;
+/**
+ * Build a multi-stop colour `@keyframes` block from a `p:tavLst` keyframe
+ * list whose `p:attrName` names a known colour attribute (`fillcolor`,
+ * `fill.color`, `style.color`, `stroke.color`), or `undefined` when the
+ * attribute is unrecognised, there are fewer than two usable stops, or any
+ * stop isn't a resolvable colour.
+ *
+ * This is the sibling of {@link buildOpacityTavKeyframe} for the OTHER shape
+ * `p:tavLst` playback can now place with confidence: a full multi-stop colour
+ * ramp authored on a generic `p:anim` node, as opposed to the two/three-stop
+ * `from`/`to`/`by` model the dedicated `p:animClr` behaviour uses (already
+ * handled via {@link PptxNativeAnimation.colorAnimation}, which this
+ * function defers to when present so an incidental `p:tavLst` on that same
+ * node never overrides it). A scheme-colour token (`a:schemeClr`, e.g.
+ * `"accent1"`) resolves via each stop's {@link PptxAnimationKeyframe.colorRef}
+ * against `themeColorMap`; a stop that is neither a resolved `#rrggbb` hex
+ * nor a resolvable scheme ref also bails to the caller's canned fallback
+ * rather than emitting invalid CSS.
+ *
+ * Reuses {@link resolveCssProperties} (`animation-color.ts`) for the
+ * attribute -> CSS-property mapping, the same one `p:animClr` keyframes use,
+ * so a `fillcolor` ramp painting an SVG shape's fill behaves identically
+ * whichever OOXML behaviour authored it.
+ */
+export declare function buildColorTavKeyframe(anim: Pick<PptxNativeAnimation, 'keyframes' | 'attrName' | 'colorAnimation' | 'calcMode'>, namePrefix: string, uid: number, themeColorMap?: Readonly<Record<string, string>>): {
+    keyframeName: string;
+    css: string;
+} | undefined;
+//# sourceMappingURL=animation-timeline-absolute.d.ts.map

package/dist/pptx/render/animation-timeline-absolute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-absolute.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-absolute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAyB,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAKlF;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC5C,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,YAAY,GAAG,cAAc,GAAG,YAAY,CAAC,EAC7E,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACT;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAcnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACzC,IAAI,EAAE,IAAI,CACT,mBAAmB,EACnB,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,UAAU,GAAG,UAAU,CAC/E,EACD,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACT;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAqBnD;AAsCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACtC,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC,EACtF,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACT;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAmCnD;AAaD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,UAAU,GAAG,gBAAgB,GAAG,UAAU,CAAC,EACzF,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC9C;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAyCnD"}

package/dist/pptx/render/animation-timeline-build-descriptors.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `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
+ */
+/**
+ * Normalized staged-reveal mode for a chart graphic frame, derived from the
+ * OOXML `a:bldChart/@bld` (or `p:bldOleChart/@bld`) token:
+ *  - `asOne`      the whole chart appears at once (`allAtOnce`).
+ *  - `bySeries`   one data series is revealed per stage (`series`).
+ *  - `byCategory` one category is revealed per stage (`category`).
+ *  - `byElement`  one series/category ELEMENT is revealed per stage
+ *                 (`seriesElement` / `categoryElement`).
+ */
+export type ChartBuildMode = 'asOne' | 'bySeries' | 'byCategory' | 'byElement';
+/**
+ * Normalized staged-reveal mode for a SmartArt diagram, derived from the OOXML
+ * `a:bldDgm/@bld` or `p:bldDgm/@bld` token:
+ *  - `asOne`        the whole diagram appears at once (`whole` / `allAtOnce`).
+ *  - `byOne`        one node is revealed per stage (`one`, and the assorted
+ *                   `depthBy*` / `breadthBy*` / directional traversals).
+ *  - `byLvl`        levels are revealed one element at a time (`lvlOne`).
+ *  - `byLvlAtOnce`  a whole level is revealed per stage (`lvlAtOnce`).
+ */
+export type DiagramBuildMode = 'asOne' | 'byOne' | 'byLvl' | 'byLvlAtOnce';
+/**
+ * Static staged-build descriptor attached to a {@link import('./animation-timeline-step').TimelineStep}.
+ * Carries only the graphic KIND + normalized MODE; the per-tick reveal
+ * fraction is computed separately (see {@link ElementBuildState.progress})
+ * because it is a function of playback time, not of the parsed animation.
+ *
+ * The chart variant's `animateBackground` mirrors `a:bldChart/@animBg`
+ * (default `true`): whether the chart's background/axes/gridlines/legend
+ * arrive WITH the first revealed stage (`true`, the default) or are shown
+ * throughout regardless of build progress (`false`). See
+ * `chart-reveal-descriptor`'s `resolveChartRevealDescriptor`.
+ */
+export type StepBuildDescriptor = {
+    kind: 'chart';
+    mode: ChartBuildMode;
+    animateBackground?: boolean;
+} | {
+    kind: 'diagram';
+    mode: DiagramBuildMode;
+};
+/**
+ * `p:spTgt/p:graphicEl` (CT_TLGraphicalObjectBuildElement, ECMA-376 S19.5.34)
+ * index data carried by a {@link import('./animation-timeline-step').TimelineStep}'s
+ * source animation target, when a deck authors one effect per chart
+ * series/category/element instead of a single `p:bldGraphic` staged reveal.
+ * Only `seriesIdx` set means "whole series"; only `categoryIdx` set means
+ * "whole category"; both set means a single (series, category) cell. See
+ * `chart-reveal-descriptor`.
+ *
+ * `id` is the diagram counterpart (`p:dgm/@id`): the SmartArt data-model point
+ * id a per-node `p:bldDgm` effect reveals (matches `PptxSmartArtNode.id`).
+ * `bldStep` doubles as the diagram build step (`sp` / `bg`) for a `dgm`-kind
+ * target; see `diagram-reveal-descriptor`.
+ */
+export interface TimelineStepGraphicElement {
+    seriesIdx?: number;
+    categoryIdx?: number;
+    id?: string;
+    bldStep?: string;
+}
+/**
+ * One authored `p:graphicEl` reveal unit resolved onto a chart, per
+ * `TimelineStepGraphicElement`'s "both indices set" case: a single (series,
+ * category) cell revealed by a `bldStep="seriesEl"`/`"categoryEl"` effect.
+ */
+export interface ChartRevealPoint {
+    seriesIdx: number;
+    categoryIdx: number;
+}
+/**
+ * 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 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.
+ */
+export interface ChartRevealDescriptor {
+    /**
+     * Whether the chart's background/axes/gridlines/legend should currently be
+     * visible: always `true` when the chart's `animateBackground` is `false`
+     * ("shown throughout"), otherwise `true` from the first revealed stage
+     * onward.
+     */
+    background: boolean;
+    /** Whole series revealed by a `bldStep="series"` effect. */
+    series: ReadonlySet<number>;
+    /** Whole categories revealed by a `bldStep="category"` effect. */
+    categories: ReadonlySet<number>;
+    /** Individual cells revealed by a `bldStep="seriesEl"`/`"categoryEl"` effect. */
+    points: readonly ChartRevealPoint[];
+}
+/**
+ * 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 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.
+ */
+export interface DiagramRevealDescriptor {
+    /**
+     * Whether the diagram's background/connector chrome should currently be
+     * visible: `true` once any node-revealing or background-revealing
+     * (`bldStep="bg"`) step has fired.
+     */
+    background: boolean;
+    /** Data-model point ids (`PptxSmartArtNode.id`) revealed so far. */
+    nodeIds: ReadonlySet<string>;
+}
+/**
+ * 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`).
+ */
+export type ElementBuildState = {
+    kind: 'chart';
+    mode: ChartBuildMode;
+    progress: number;
+} | {
+    kind: 'diagram';
+    mode: DiagramBuildMode;
+    progress: number;
+};
+/** Which shape paint property an active `p:animClr` color animation targets. */
+export type ColorAnimationTarget = 'fill' | 'stroke';
+//# sourceMappingURL=animation-timeline-build-descriptors.d.ts.map

package/dist/pptx/render/animation-timeline-build-descriptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-build-descriptors.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-build-descriptors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAC;AAE/E;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,aAAa,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAC5B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,0BAA0B;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACrC;;;;;OAKG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B,kEAAkE;IAClE,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,iFAAiF;IACjF,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACvC;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,oEAAoE;IACpE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAC1B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,QAAQ,CAAC"}

package/dist/pptx/render/animation-timeline-build-level.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `animation-timeline-build-level`  -  groups paragraph indices for a
+ * by-paragraph text build according to `p:bldP/@bldLvl`.
+ *
+ * @module render/animation-timeline-build-level
+ */
+/**
+ * Default `p:bldP/@bldLvl` (ECMA-376 S19.5.6 CT_TLBuildParagraph): when the
+ * attribute is absent, PowerPoint's own default is "By 1st Level Paragraphs".
+ */
+export declare const DEFAULT_BUILD_LEVEL = 1;
+/**
+ * Group paragraph indices (in original document order) into the click steps a
+ * "By Nth Level Paragraphs" build produces.
+ *
+ * `buildLevel` (1-based) says which outline levels get their own click: a
+ * paragraph at 0-based outline `level` OPENS a new step when
+ * `level < buildLevel`, otherwise it attaches to (plays with) the most recent
+ * step opened by a shallower-or-equal paragraph. The very first paragraph
+ * always opens a step, even if its own level is `>= buildLevel`, matching
+ * PowerPoint's own behaviour of showing whatever comes first on the first
+ * advance.
+ *
+ * With the default `buildLevel = 1` (0-based top-level paragraphs, i.e.
+ * `level = 0`), every top-level bullet gets its own click and its nested
+ * sub-bullets (level 1+) reveal together with it, which is PowerPoint's "By
+ * 1st Level Paragraphs" default. Before this existed, every paragraph got its
+ * own click regardless of nesting, so a sub-bullet needed an extra click
+ * separate from its parent.
+ *
+ * @param levels - 0-based outline level per paragraph, in document order.
+ * @param buildLevel - `p:bldP/@bldLvl`, or {@link DEFAULT_BUILD_LEVEL} when absent.
+ * @returns Groups of paragraph indices, in document order; each group's first
+ *          index is the paragraph whose click reveals the whole group.
+ */
+export declare function groupParagraphsByBuildLevel(levels: readonly number[], buildLevel?: number): number[][];
+//# sourceMappingURL=animation-timeline-build-level.d.ts.map

package/dist/pptx/render/animation-timeline-build-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-build-level.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-build-level.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,UAAU,GAAE,MAA4B,GACtC,MAAM,EAAE,EAAE,CAYZ"}

package/dist/pptx/render/animation-timeline-builder-helpers.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `animation-timeline-builder-helpers` - small pure helpers used by
+ * `animation-timeline-builder`'s click-group and sequence builders, split out
+ * to keep those modules under the file-size limit.
+ *
+ * @module render/animation-timeline-builder-helpers
+ */
+import type { PptxNativeAnimation } from 'ooxml-core/pptx';
+import type { EffectName, TimelineStep } from './animation-timeline-types.js';
+/** Clamp a value into the closed unit interval. */
+export declare function clamp01(value: number): number;
+/**
+ * Map an animation's parsed `accel`/`decel` fractions to a CSS timing function
+ * (see `cssEasingForAccelDecel`): neither set plays at constant speed
+ * (`linear`), like PowerPoint; otherwise PowerPoint's exact speed-up / cruise
+ * / slow-down profile.
+ */
+export declare function cssEasingForAnimation(anim: PptxNativeAnimation): string;
+/**
+ * Resolve the active-color-animation paint targets for a step, or `undefined`
+ * when the animation drives no fill / stroke colour (so the field stays absent).
+ *
+ * `tavColorApplied` must be `true` only when `buildColorTavKeyframe`
+ * actually produced a keyframe block for this step: `anim.attrName` alone
+ * isn't enough, because it can name a colour attribute whose `p:tavLst`
+ * stops couldn't be resolved to CSS colours (e.g. scheme-colour tokens), in
+ * which case the step falls back to an unrelated effect and must NOT be
+ * flagged as animating fill/stroke, or the renderer would suppress the
+ * shape's static paint for an animation that never actually runs.
+ */
+export declare function stepColorTargets(anim: PptxNativeAnimation, tavColorApplied: boolean): TimelineStep['colorTargets'];
+/**
+ * Resolve a fallback {@link EffectName} for an animation whose preset we do
+ * not model (no static effect and no dynamic keyframe).
+ *
+ * Without this, an unmapped animation was silently dropped, which broke slide
+ * visibility semantics: an unmapped **entrance** was never registered as
+ * hidden-until-its-start, so it stayed visible from the very first frame; an
+ * unmapped **exit** never hid its element. We substitute a neutral fade so the
+ * element still transitions in (entrance) or out (exit) at the correct time.
+ *
+ * Emphasis / motion-path presets carry no show/hide semantics, so a missing
+ * one is safe to skip and returns `undefined`.
+ */
+export declare function fallbackEffectForClass(presetClass: PptxNativeAnimation['presetClass']): EffectName | undefined;
+/**
+ * An emphasis whose visible work is entirely a `p:set`/`p:anim` text-style
+ * change (no mapped preset effect, no transform). Such a step must not fall
+ * through to the neutral `pulse` safety net.
+ */
+export declare function isTextStyleOnlyEmphasis(anim: PptxNativeAnimation): boolean;
+//# sourceMappingURL=animation-timeline-builder-helpers.d.ts.map

package/dist/pptx/render/animation-timeline-builder-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-builder-helpers.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-builder-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAK3D,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE3E,mDAAmD;AACnD,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAEvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,mBAAmB,EACzB,eAAe,EAAE,OAAO,GACtB,YAAY,CAAC,cAAc,CAAC,CAW9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACrC,WAAW,EAAE,mBAAmB,CAAC,aAAa,CAAC,GAC7C,UAAU,GAAG,SAAS,CAexB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAE1E"}

package/dist/pptx/render/animation-timeline-builder.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `animation-timeline-builder` - `buildTimeline`, which turns a flat list of
+ * native animations into an {@link AnimationTimeline} of click-groups (plus
+ * interactive + hover sequences and the aggregated `@keyframes` CSS). Pure.
+ *
+ * The per-animation step-building loop bodies live in sibling modules (split
+ * out to keep this file under the repo's file-size limit):
+ * `animation-timeline-regular-step` (the main click-group pass),
+ * `animation-timeline-step-effect` / `animation-timeline-step-scheduling`
+ * (its effect-resolution and delay-scheduling sub-steps), and
+ * `animation-timeline-sequence-builder` (interactive + hover sequences).
+ *
+ * @module render/animation-timeline-builder
+ */
+import type { PptxNativeAnimation } from 'ooxml-core/pptx';
+import type { AnimationRenderContext } from './animation-render-context.js';
+import type { AnimationTimeline } from './animation-timeline-types.js';
+/**
+ * Build click-groups from a flat list of native animations.
+ *
+ * Grouping logic:
+ * - An ``onClick`` animation starts a **new** click-group.
+ * - A ``withPrevious`` animation is added to the **current** click-group
+ *   and plays simultaneously with the previous step.
+ * - An ``afterPrevious`` animation is added to the **current** click-group
+ *   but delayed until the previous step completes.
+ * - An ``afterDelay`` animation behaves like afterPrevious plus its
+ *   triggerDelay.
+ * - ``onHover`` animations are separated into hover sequences (like
+ *   interactive sequences but triggered by mouse hover).
+ * - The very first animation implicitly starts a click-group even when
+ *   its trigger is withPrevious or afterPrevious (same as PowerPoint).
+ *
+ * Auto-advance: When an onClick group is immediately followed by
+ * afterPrevious/withPrevious/afterDelay animations that would form
+ * their own group (because no onClick precedes them), those groups
+ * are marked with `autoAdvance: true` so the playback engine can
+ * automatically advance through them without requiring a click.
+ */
+export declare function buildTimeline(nativeAnimations: ReadonlyArray<PptxNativeAnimation>, renderContext?: AnimationRenderContext, pixelateMosaic?: boolean): AnimationTimeline;
+//# sourceMappingURL=animation-timeline-builder.d.ts.map

package/dist/pptx/render/animation-timeline-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-builder.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAK3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAYzE,OAAO,KAAK,EAAkC,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AA2DpG;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC5B,gBAAgB,EAAE,aAAa,CAAC,mBAAmB,CAAC,EACpD,aAAa,CAAC,EAAE,sBAAsB,EAMtC,cAAc,CAAC,EAAE,OAAO,GACtB,iBAAiB,CA4FnB"}

package/dist/pptx/render/animation-timeline-effect-names.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `animation-timeline-effect-names` - the {@link EffectName} catalog, 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-effect-names
+ */
+import type { SlideFilterEffectName } from './animation-slide-filter.js';
+import type { StripsEffectName } from './animation-strips-reveal.js';
+/** Catalog of static effect keyframe short-names (without the `pptx-` prefix). */
+export type EffectName = StripsEffectName | SlideFilterEffectName | 'appear' | 'fadeIn' | 'flyInLeft' | 'flyInRight' | 'flyInTop' | 'flyInBottom' | 'zoomIn' | 'bounceIn' | 'wipeIn' | 'splitIn' | 'dissolveIn' | 'wheelIn' | 'wheelIn1' | 'wheelIn2' | 'wheelIn3' | 'wheelIn4' | 'wheelIn8' | 'blindsIn' | 'blindsInVertical' | 'blindsInHorizontal' | 'boxIn' | 'circleIn' | 'floatIn' | 'riseUp' | 'swivel' | 'expandIn' | 'checkerboardIn' | 'checkerboardInAcross' | 'checkerboardInDown' | 'flashIn' | 'peekIn' | 'randomBarsIn' | 'randomBarsInVertical' | 'randomBarsInHorizontal' | 'spinnerIn' | 'growTurnIn' | 'diamondIn' | 'plusIn' | 'boxInFromCenter' | 'circleInFromCenter' | 'diamondInFromCenter' | 'plusInFromCenter' | 'wedgeIn' | 'spiralIn' | 'boomerangIn' | 'creditsIn' | 'floatUpIn' | 'pinwheelIn' | 'whipIn' | 'curveUpIn' | 'foldIn' | 'lightSpeedIn' | 'flipIn' | 'glideIn' | 'compressIn' | 'unfoldIn' | 'rotateIn' | 'centerRevolveIn' | 'dropIn' | 'cutIn' | 'stretchInLeft' | 'stretchInRight' | 'stretchInTop' | 'stretchInBottom' | 'newsflashIn' | 'pixelateIn' | 'disappear' | 'fadeOut' | 'flyOutLeft' | 'flyOutRight' | 'flyOutTop' | 'flyOutBottom' | 'zoomOut' | 'bounceOut' | 'sinkDown' | 'wipeOut' | 'shrinkOut' | 'dissolveOut' | 'cutOut' | 'stretchOutLeft' | 'stretchOutRight' | 'stretchOutTop' | 'stretchOutBottom' | 'newsflashOut' | 'pixelateOut' | 'boxOut' | 'circleOut' | 'checkerboardOut' | 'blindsOut' | 'wheelOut' | 'randomBarsOut' | 'diamondOut' | 'plusOut' | 'boxOutFromCenter' | 'circleOutFromCenter' | 'diamondOutFromCenter' | 'plusOutFromCenter' | 'wedgeOut' | 'peekOut' | 'splitOut' | 'spiralOut' | 'boomerangOut' | 'creditsOut' | 'floatDownOut' | 'pinwheelOut' | 'spinnerOut' | 'whipOut' | 'curveDownOut' | 'unfoldOut' | 'lightSpeedOut' | 'flipOut' | 'glideOut' | 'foldOut' | 'rotateOut' | 'centerRevolveOut' | 'dropOut' | 'flashOnceOut' | 'peekOutDown' | 'pulse' | 'blink' | 'shimmer' | 'spin' | 'teeter' | 'growShrink' | 'transparency' | 'boldFlash' | 'wave' | 'colorWave' | 'bounce' | 'flash';
+//# sourceMappingURL=animation-timeline-effect-names.d.ts.map

package/dist/pptx/render/animation-timeline-effect-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-effect-names.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-effect-names.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAGnB,gBAAgB,GAGhB,qBAAqB,GACrB,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,UAAU,GACV,aAAa,GACb,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,SAAS,GAIT,UAAU,GACV,UAAU,GACV,UAAU,GACV,UAAU,GACV,UAAU,GACV,UAAU,GAGV,kBAAkB,GAClB,oBAAoB,GACpB,OAAO,GACP,UAAU,GACV,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,gBAAgB,GAGhB,sBAAsB,GACtB,oBAAoB,GACpB,SAAS,GACT,QAAQ,GACR,cAAc,GAGd,sBAAsB,GACtB,wBAAwB,GACxB,WAAW,GACX,YAAY,GACZ,WAAW,GACX,QAAQ,GAGR,iBAAiB,GACjB,oBAAoB,GACpB,qBAAqB,GACrB,kBAAkB,GAClB,SAAS,GAaT,UAAU,GACV,aAAa,GACb,WAAW,GACX,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,cAAc,GACd,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,UAAU,GACV,UAAU,GACV,iBAAiB,GACjB,QAAQ,GACR,OAAO,GACP,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,iBAAiB,GACjB,aAAa,GAGb,YAAY,GACZ,WAAW,GACX,SAAS,GACT,YAAY,GACZ,aAAa,GACb,WAAW,GACX,cAAc,GACd,SAAS,GACT,WAAW,GACX,UAAU,GACV,SAAS,GACT,WAAW,GACX,aAAa,GACb,QAAQ,GACR,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,GACf,kBAAkB,GAClB,cAAc,GAEd,aAAa,GACb,QAAQ,GACR,WAAW,GACX,iBAAiB,GACjB,WAAW,GACX,UAAU,GACV,eAAe,GACf,YAAY,GACZ,SAAS,GAIT,kBAAkB,GAClB,qBAAqB,GACrB,sBAAsB,GACtB,mBAAmB,GACnB,UAAU,GAKV,SAAS,GACT,UAAU,GACV,WAAW,GACX,cAAc,GACd,YAAY,GACZ,cAAc,GACd,aAAa,GACb,YAAY,GACZ,SAAS,GACT,cAAc,GACd,WAAW,GACX,eAAe,GACf,SAAS,GACT,UAAU,GACV,SAAS,GACT,WAAW,GACX,kBAAkB,GAClB,SAAS,GAKT,cAAc,GACd,aAAa,GACb,OAAO,GACP,OAAO,GACP,SAAS,GACT,MAAM,GACN,QAAQ,GACR,YAAY,GACZ,cAAc,GACd,WAAW,GACX,MAAM,GACN,WAAW,GACX,QAAQ,GACR,OAAO,CAAC"}