ooxml-ui 0.30.0 → 0.31.0

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

@@ -0,0 +1,277 @@
+/**
+ * `animation-timeline-engine`  -  `TimelineEngine`, a pure stateful controller
+ * that tracks which click-group is active and computes per-element visibility +
+ * active CSS animation. No DOM, no RAF; the binding drives `advance()` from its
+ * own playback loop and applies the resulting CSS.
+ *
+ * @module render/animation-timeline-engine
+ */
+import type { PptxNativeAnimation } from 'ooxml-core/pptx';
+import type { ElementBuildStateOptions } from './animation-build.js';
+import type { AnimationRenderContext } from './animation-render-context.js';
+import type { AnimationTimeline, TimelineClickGroup, ElementAnimationState } from './animation-timeline-types.js';
+/**
+ * Options for {@link TimelineEngine.getElementStates}. Re-exported alias of
+ * {@link ElementBuildStateOptions} so callers can import it from the engine.
+ */
+export type ElementStatesOptions = ElementBuildStateOptions;
+/**
+ * Stateful engine that tracks which click-group we are on and
+ * which elements should be visible/animated/hidden.
+ */
+export declare class TimelineEngine {
+    private readonly timeline;
+    private currentGroupIndex;
+    /**
+     * Map of elementId → CSS animation string for all animations
+     * that have been triggered so far (cumulative).
+     */
+    private readonly activeAnimations;
+    /**
+     * Map of elementId → the most recently applied step carrying a staged-build
+     * or colour-target descriptor. Used to surface `build` / `animatesFill` /
+     * `animatesStroke` on {@link ElementAnimationState}.
+     */
+    private readonly activeSteps;
+    /**
+     * Cumulative (oldest-first) history of fired chart-build steps per element,
+     * keyed by elementId. See {@link StepApplicationState.chartRevealHistory}
+     * (`animation-sequence-gating`) for why this is separate from
+     * {@link activeSteps}: a per-series/per-category build fires ONE step per
+     * stage against the SAME chart elementId, so only a full history (not just
+     * the latest) lets `getElementStates` derive the authored reveal set.
+     */
+    private readonly chartRevealHistory;
+    /**
+     * Each chart element's static build mode + `animateBackground` flag,
+     * collected once from the timeline (authored constants, not playback
+     * state). See `chart-reveal-descriptor`'s `collectChartBuildInfo`.
+     */
+    private readonly chartBuildInfo;
+    /**
+     * Cumulative (oldest-first) history of fired diagram-build steps per
+     * element, mirroring {@link chartRevealHistory} for `p:bldDgm` per-node
+     * builds. See `diagram-reveal-descriptor`'s `resolveDiagramRevealDescriptor`.
+     */
+    private readonly diagramRevealHistory;
+    /**
+     * Each diagram element's static build mode, collected once from the
+     * timeline. See `diagram-reveal-descriptor`'s `collectDiagramBuildInfo`.
+     */
+    private readonly diagramBuildInfo;
+    /**
+     * Set of element IDs whose entrance animation has played.
+     * These elements become visible.
+     */
+    private readonly revealedElements;
+    /**
+     * Set of element IDs whose exit animation has played.
+     * These elements become hidden after animation.
+     */
+    private readonly exitedElements;
+    /**
+     * Tracks the current click-group index for each interactive sequence
+     * (keyed by trigger shape ID).
+     */
+    private readonly interactiveGroupIndexes;
+    /**
+     * Tracks the current click-group index for each hover sequence
+     * (keyed by trigger shape ID).
+     */
+    private readonly hoverGroupIndexes;
+    /**
+     * Wall-clock time (from the `nowMs` passed to `advance`) that the current
+     * main-sequence click-group started, or `undefined` before the first
+     * advance. Read by {@link shouldBlockNextAdvance} to honour `@concurrent`
+     * / `@nextAc`.
+     */
+    private mainGroupStartedAtMs;
+    /** Same as {@link mainGroupStartedAtMs}, one entry per interactive sequence. */
+    private readonly interactiveGroupStartedAtMs;
+    /** Same as {@link mainGroupStartedAtMs}, one entry per hover sequence. */
+    private readonly hoverGroupStartedAtMs;
+    /**
+     * Per-step `@restart` runtime state (ECMA-376 S19.5.27), keyed by object
+     * identity: the same {@link TimelineStep} object is reused across repeated
+     * `advance`/`advanceInteractive`/`advanceHover` calls (it lives in the
+     * precomputed {@link AnimationTimeline}), so identity is a stable key
+     * without needing a synthetic id on the step itself.
+     */
+    private stepRestartState;
+    /**
+     * Tracks which element currently "holds" each `p:excl` group (exclGroupId
+     * -> elementId). When a new exclusive step starts, any other element
+     * holding the SAME group has its running animation stopped: ECMA-376
+     * S19.5.24 CT_TLExclusiveTimeNode allows at most one child of an
+     * exclusive container to play at a time.
+     */
+    private readonly exclusiveHolders;
+    /**
+     * Element ids currently running a `step.endsOnNextClick` loop ("Repeat
+     * until next click"), mapped to the step that started it. See
+     * {@link StepApplicationState.loopEndingOnNextClick} and
+     * {@link freezeLoopsEndingOnNextClick}.
+     */
+    private readonly loopEndingOnNextClick;
+    constructor(timeline: AnimationTimeline);
+    /**
+     * Build a TimelineEngine from a slide's native animations. `renderContext`
+     * (see `animation-render-context.ts`) supplies the animated elements' real
+     * geometry and the deck's theme colour map, when the caller built one.
+     */
+    static fromAnimations(nativeAnimations: ReadonlyArray<PptxNativeAnimation>, renderContext?: AnimationRenderContext, pixelateMosaic?: boolean): TimelineEngine;
+    /** The underlying timeline data. */
+    getTimeline(): AnimationTimeline;
+    /** True if there are more click-groups to play. */
+    hasMoreSteps(): boolean;
+    /** Total number of click-groups. */
+    get totalGroups(): number;
+    /** Index of the current click-group (-1 = not started). */
+    get currentGroup(): number;
+    /**
+     * Advance to the next click-group.
+     *
+     * Returns `null` only when genuinely exhausted (no groups at all, or
+     * already at the last one) - every binding falls through to slide
+     * navigation on `null`, which is correct there. When the currently-active
+     * group's `@concurrent`/`@nextAc` (ECMA-376 S19.5.60) say this advance
+     * should be swallowed instead (see {@link shouldBlockNextAdvance}), this
+     * returns {@link EMPTY_CLICK_GROUP} - a truthy, no-op group - so the click
+     * still reads as "consumed here" rather than "nothing left, leave the
+     * slide". `nowMs` defaults to `Date.now()`; a caller passes it explicitly
+     * to test the gating deterministically.
+     */
+    advance(nowMs?: number): TimelineClickGroup | null;
+    /**
+     * Freeze every currently-active `step.endsOnNextClick` loop ("Repeat until
+     * next click") in place: appends ` paused` to its running CSS `animation`
+     * shorthand, which stops the infinite iteration at whatever frame it is
+     * currently on (the `animation-name`/duration/delay are unchanged, so the
+     * browser preserves the animation's current position instead of
+     * restarting it) rather than snapping back to the element's un-animated
+     * base style. Only `advance()` (the main click sequence) calls this: see
+     * `TimelineStep.endsOnNextClick`'s doc for why interactive/hover sequences
+     * are a different mechanism and out of scope here.
+     */
+    private freezeLoopsEndingOnNextClick;
+    /**
+     * Shared "advance one click-group forward within a track" logic used by
+     * {@link advance}, {@link advanceInteractive} and {@link advanceHover}: each
+     * owns its own group list, current index, and start-time, but the gating
+     * and index arithmetic are identical.
+     *
+     * `'blocked'` and `'exhausted'` are kept distinct (rather than both
+     * collapsing to `null`) because the caller must react differently: a
+     * blocked advance was consumed (return {@link EMPTY_CLICK_GROUP}, index
+     * unchanged so a later call can genuinely advance), while an exhausted one
+     * genuinely has nothing left (return `null`).
+     */
+    private advanceSequenceGroup;
+    /**
+     * Peek at the next click-group without advancing.
+     * Returns the next group or `null` if no more groups remain.
+     */
+    peekNext(): TimelineClickGroup | null;
+    /**
+     * Check if the next click-group should auto-advance (play automatically
+     * without requiring a click).
+     */
+    shouldAutoAdvance(): boolean;
+    /**
+     * Get the auto-advance delay for the next group (ms).
+     * Returns 0 if the next group is not auto-advance or doesn't exist.
+     */
+    getAutoAdvanceDelay(): number;
+    /**
+     * Returns whether an element should be visible given the current
+     * timeline state.
+     *
+     * - Elements without entrance animations: always visible.
+     * - Elements with entrance animations: hidden until their entrance
+     *   click-group has been reached.
+     * - Elements with exit animations that have played: hidden.
+     */
+    isElementVisible(elementId: string): boolean;
+    /**
+     * Returns the CSS animation string for an element if one is currently
+     * active, or `undefined`.
+     */
+    getElementAnimation(elementId: string): string | undefined;
+    /**
+     * Build a snapshot of the current animation state for all elements.
+     * Returns a map: elementId → { visible, cssAnimation }.
+     */
+    getElementStates(elementIds: ReadonlyArray<string>, options?: ElementStatesOptions): Map<string, ElementAnimationState>;
+    /**
+     * Check whether a shape ID is a trigger for an interactive sequence.
+     */
+    hasInteractiveSequence(shapeId: string): boolean;
+    /**
+     * Get all shape IDs that are interactive sequence triggers.
+     */
+    getInteractiveTriggerShapeIds(): ReadonlySet<string>;
+    /**
+     * Check whether a shape ID is a trigger for a hover sequence.
+     */
+    hasHoverSequence(shapeId: string): boolean;
+    /**
+     * Get all shape IDs that are hover sequence triggers.
+     */
+    getHoverTriggerShapeIds(): ReadonlySet<string>;
+    /**
+     * Advance the interactive sequence for a given trigger shape.
+     *
+     * Returns `null` only when genuinely exhausted; a request swallowed by
+     * `@concurrent`/`@nextAc` instead returns {@link EMPTY_CLICK_GROUP} (see
+     * {@link advance}'s doc for why the distinction matters to a caller).
+     */
+    advanceInteractive(triggerShapeId: string, nowMs?: number): TimelineClickGroup | null;
+    /**
+     * Advance the hover sequence for a given trigger shape.
+     *
+     * Returns `null` only when genuinely exhausted; a request swallowed by
+     * `@concurrent`/`@nextAc` instead returns {@link EMPTY_CLICK_GROUP} (see
+     * {@link advance}'s doc for why the distinction matters to a caller).
+     */
+    advanceHover(triggerShapeId: string, nowMs?: number): TimelineClickGroup | null;
+    /**
+     * Reset the hover sequence for a given trigger shape so it can replay on
+     * the next hover, UNLESS the sequence's most recently played group is still
+     * active and its `@prevAc` (ECMA-376 S19.5.60) says not to back out of it
+     * yet - see {@link shouldBlockReset}. `nowMs` defaults to `Date.now()`.
+     */
+    resetHover(triggerShapeId: string, nowMs?: number): void;
+    /**
+     * Jump to the END of the timeline: every click-group counted as played, every
+     * entrance revealed and every exit applied, with no CSS animation attached so
+     * nothing replays.
+     *
+     * This is what PowerPoint shows when you step BACKWARD onto a slide: it
+     * appears with its builds already complete, and a further back press walks
+     * them off again. Re-running the timeline from zero instead made a deck whose
+     * opening build auto-starts restart its animation every time the presenter
+     * stepped back onto it.
+     */
+    completeAll(): void;
+    /**
+     * Reset the engine to its initial state (no animations played).
+     */
+    reset(): void;
+    /**
+     * Apply a group's steps to the internal tracking state, honouring each
+     * step's `@restart` (see {@link applyRestartGatedStep}), and return the
+     * EFFECTIVE group: one whose `steps` omits any step a `@restart` block skipped.
+     *
+     * Every binding's playback loop (React's `applyAnimationGroupSteps` and its
+     * Vue/Angular/Svelte/Vanilla equivalents) applies CSS and schedules cleanup
+     * timers purely from the group `advance`/`advanceInteractive`/`advanceHover`
+     * hand back, so a blocked step must never reach that list - otherwise a
+     * binding would re-apply (and re-schedule cleanup for) an effect the deck
+     * said must not restart, even though this engine's own bookkeeping already
+     * refused it. When nothing was blocked (by far the common case, since most
+     * decks never set `@restart`), the original `group` reference is returned
+     * unchanged.
+     */
+    private applyGroupSteps;
+}
+//# sourceMappingURL=animation-timeline-engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-engine.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AASzE,OAAO,KAAK,EACX,iBAAiB,EACjB,kBAAkB,EAElB,qBAAqB,EAGrB,MAAM,4BAA4B,CAAC;AAOpC;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,wBAAwB,CAAC;AAM5D;;;GAGG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,iBAAiB,CAAS;IAClC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsB;IACvD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA8B;IACjE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAG7B;IACF;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA8B;IACnE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkD;IACnF;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAc;IAC/C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAc;IAC7C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAsB;IAC9D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsB;IACxD;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB,CAAqB;IACjD,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAsB;IAClE,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAsB;IAC5D;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB,CAA0C;IAClE;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsB;IACvD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA4B;IAElE,YAAmB,QAAQ,EAAE,iBAAiB,EAkB7C;IAED;;;;OAIG;IACH,OAAc,cAAc,CAC3B,gBAAgB,EAAE,aAAa,CAAC,mBAAmB,CAAC,EACpD,aAAa,CAAC,EAAE,sBAAsB,EAKtC,cAAc,CAAC,EAAE,OAAO,GACtB,cAAc,CAEhB;IAED,oCAAoC;IAC7B,WAAW,IAAI,iBAAiB,CAEtC;IAED,mDAAmD;IAC5C,YAAY,IAAI,OAAO,CAE7B;IAED,oCAAoC;IACpC,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED,2DAA2D;IAC3D,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED;;;;;;;;;;;;OAYG;IACI,OAAO,CAAC,KAAK,GAAE,MAAmB,GAAG,kBAAkB,GAAG,IAAI,CAuBpE;IAED;;;;;;;;;;OAUG;IACH,OAAO,CAAC,4BAA4B;IAUpC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;;OAGG;IACI,QAAQ,IAAI,kBAAkB,GAAG,IAAI,CAM3C;IAED;;;OAGG;IACI,iBAAiB,IAAI,OAAO,CAGlC;IAED;;;OAGG;IACI,mBAAmB,IAAI,MAAM,CAMnC;IAED;;;;;;;;OAQG;IACI,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAYlD;IAED;;;OAGG;IACI,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhE;IAED;;;OAGG;IACI,gBAAgB,CACtB,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,EACjC,OAAO,CAAC,EAAE,oBAAoB,GAC5B,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,CA4BpC;IAED;;OAEG;IACI,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtD;IAED;;OAEG;IACI,6BAA6B,IAAI,WAAW,CAAC,MAAM,CAAC,CAE1D;IAED;;OAEG;IACI,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEhD;IAED;;OAEG;IACI,uBAAuB,IAAI,WAAW,CAAC,MAAM,CAAC,CAEpD;IAED;;;;;;OAMG;IACI,kBAAkB,CACxB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAmB,GACxB,kBAAkB,GAAG,IAAI,CA0B3B;IAED;;;;;;OAMG;IACI,YAAY,CAClB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAmB,GACxB,kBAAkB,GAAG,IAAI,CAoB3B;IAED;;;;;OAKG;IACI,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,IAAI,CAS1E;IAED;;;;;;;;;;OAUG;IACI,WAAW,IAAI,IAAI,CA0BzB;IAED;;OAEG;IACI,KAAK,IAAI,IAAI,CAkBnB;IAED;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,eAAe;CAmCvB"}

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

@@ -0,0 +1,10 @@
+import type { PptxNativeAnimation } from 'ooxml-core/pptx';
+import type { AnimationStep, EffectName, TimelineStep, TimelineClickGroup } from './animation-timeline-types.js';
+export declare function cssKeyframeName(effect: EffectName | string): string;
+export declare function defaultDuration(presetClass: PptxNativeAnimation['presetClass']): number;
+export declare function fillModeForClass(presetClass: PptxNativeAnimation['presetClass']): AnimationStep['fillMode'];
+export declare function finalizeClickGroup(steps: TimelineStep[], options?: {
+    autoAdvance?: boolean;
+    autoAdvanceDelayMs?: number;
+}): TimelineClickGroup;
+//# sourceMappingURL=animation-timeline-group-helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-group-helpers.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-group-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,KAAK,EACX,aAAa,EACb,UAAU,EACV,YAAY,EACZ,kBAAkB,EAClB,MAAM,4BAA4B,CAAC;AAMpC,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,mBAAmB,CAAC,aAAa,CAAC,GAAG,MAAM,CAavF;AAED,wBAAgB,gBAAgB,CAC/B,WAAW,EAAE,mBAAmB,CAAC,aAAa,CAAC,GAC7C,aAAa,CAAC,UAAU,CAAC,CAW3B;AAED,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,YAAY,EAAE,EACrB,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D,kBAAkB,CA4BpB"}

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

@@ -0,0 +1,147 @@
+/**
+ * `animation-timeline-group` - click-group and whole-timeline models
+ * ({@link TimelineClickGroup}, {@link AnimationTimeline},
+ * {@link ElementAnimationState}, {@link AnimationStyle}), 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-group
+ */
+import type { TextStyleAnimationDescriptor } from './animation-text-style-resolve.js';
+import type { ChartBuildMode, ChartRevealDescriptor, DiagramBuildMode, DiagramRevealDescriptor, ElementBuildState } from './animation-timeline-build-descriptors.js';
+import type { TimelineStep } from './animation-timeline-step.js';
+/** A group of animation steps that play on a single click/advance action. */
+export interface TimelineClickGroup {
+    /** Steps that play when this group triggers. */
+    steps: TimelineStep[];
+    /**
+     * Total duration (ms) from first step start to last step end
+     * within this click-group.
+     */
+    totalDurationMs: number;
+    /**
+     * Whether this group should auto-advance (play automatically without a click).
+     * True when the group consists entirely of afterPrevious/withPrevious/afterDelay
+     * animations that were folded into the previous click-group's timeline.
+     */
+    autoAdvance?: boolean;
+    /**
+     * Delay in ms before auto-advancing to this group (relative to
+     * the end of the preceding group). Only meaningful when `autoAdvance` is true.
+     */
+    autoAdvanceDelayMs?: number;
+    /**
+     * `p:seq/@concurrent` of the innermost enclosing sequence (ECMA-376
+     * S19.5.60), when this group's steps are governed by one. `true` lets this
+     * group's effects play alongside the surrounding timeline instead of
+     * blocking a "next" advance / hover-reset request while still active.
+     * Absent means no enclosing `p:seq` set it (the OOXML default is `false`,
+     * i.e. non-concurrent).
+     */
+    seqConcurrent?: boolean;
+    /**
+     * `p:seq/@nextAc` of the innermost enclosing sequence (ST_TLNextActionType,
+     * ECMA-376 S19.5.60). See {@link import('./animation-sequence-gating').shouldBlockNextAdvance}
+     * for how this is honoured.
+     */
+    seqNextAction?: 'none' | 'seek';
+    /**
+     * `p:seq/@prevAc` of the innermost enclosing sequence (ST_TLPreviousActionType,
+     * ECMA-376 S19.5.60). See {@link import('./animation-sequence-gating').shouldBlockReset}
+     * for how this is honoured.
+     */
+    seqPrevAction?: 'none' | 'skipTimeNode';
+}
+/** The full animation timeline for a slide. */
+export interface AnimationTimeline {
+    /** Ordered list of click-groups. Each click advances to the next group. */
+    clickGroups: TimelineClickGroup[];
+    /** Set of element IDs that have entrance animations (initially hidden). */
+    entranceElementIds: ReadonlySet<string>;
+    /** All CSS @keyframes definitions needed by this timeline. */
+    keyframesCss: string;
+    /**
+     * Interactive sequences keyed by trigger shape ID.
+     * When a shape is clicked, its click-groups play independently of the main timeline.
+     */
+    interactiveSequences: ReadonlyMap<string, TimelineClickGroup[]>;
+    /** Interactive sequences whose `p:endSync/p:rtn val="all"` permits replay. */
+    restartableInteractiveSequences?: ReadonlySet<string>;
+    /**
+     * Hover sequences keyed by trigger shape ID.
+     * When a shape is hovered over, its click-groups play.
+     * Supports both onMouseOver (start) and onMouseOut (reverse/stop).
+     */
+    hoverSequences: ReadonlyMap<string, TimelineClickGroup[]>;
+}
+/** Snapshot of a single element's animation state at a point in the timeline. */
+export interface ElementAnimationState {
+    /** Whether the element should be visible. */
+    visible: boolean;
+    /** CSS animation shorthand to apply (undefined = no active animation). */
+    cssAnimation: string | undefined;
+    /**
+     * Staged-build reveal state, present only when the active animation builds a
+     * chart or SmartArt diagram in stages (`p:bldChart` / `p:bldDgm`) rather than
+     * revealing the whole element at once. A staged renderer multiplies
+     * `build.progress` (0..1) by its own series / category / level COUNT to
+     * decide how many stages are revealed at the current playback time; see
+     * {@link import('./animation-build').revealedStageCount}. Absent for ordinary
+     * whole-element entrances, so existing renderers are unaffected.
+     */
+    build?: ElementBuildState;
+    /**
+     * Authored-index chart reveal state (see {@link ChartRevealDescriptor}),
+     * present only when every fired chart-build step for this element carried
+     * `p:graphicEl` index data. A chart renderer prefers this over `build` when
+     * present; `chart-build`'s `resolveRevealedChartData` picks between the two.
+     */
+    chartReveal?: {
+        mode: ChartBuildMode;
+        descriptor: ChartRevealDescriptor;
+    };
+    /**
+     * Authored-index SmartArt diagram reveal state (see
+     * {@link DiagramRevealDescriptor}), present only when every fired
+     * diagram-build step for this element carried `p:graphicEl` node-id data.
+     * `diagram-build`'s `resolveRevealedSmartArtNodes` prefers this over `build`
+     * when present.
+     */
+    diagramReveal?: {
+        mode: DiagramBuildMode;
+        descriptor: DiagramRevealDescriptor;
+    };
+    /**
+     * True when an active `p:animClr` color animation targets this shape's fill.
+     * A vector renderer should then paint the fill with `fill: inherit` so the
+     * wrapper-level colour keyframes cascade to the SVG path. Absent/false means
+     * no active fill-colour animation.
+     */
+    animatesFill?: boolean;
+    /**
+     * True when an active `p:animClr` color animation targets this shape's
+     * stroke. A vector renderer should then paint the stroke with
+     * `stroke: inherit`. Absent/false means no active stroke-colour animation.
+     */
+    animatesStroke?: boolean;
+    /**
+     * Active discrete font-style / colour / size override (see
+     * {@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;
+}
+/**
+ * Neutral CSS-properties shape returned by initial-style helpers. Bindings that
+ * use a framework-specific style type (e.g. React's `CSSProperties`) cast this
+ * at the boundary. Keys are camelCase to match inline-style objects.
+ */
+export type AnimationStyle = Record<string, string | number>;
+//# sourceMappingURL=animation-timeline-group.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-group.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-group.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,KAAK,EACX,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC;CACxC;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,2EAA2E;IAC3E,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAChE,8EAA8E;IAC9E,+BAA+B,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtD;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;CAC1D;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACrC,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,cAAc,CAAC;QAAC,UAAU,EAAE,qBAAqB,CAAA;KAAE,CAAC;IAC1E;;;;;;OAMG;IACH,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,UAAU,EAAE,uBAAuB,CAAA;KAAE,CAAC;IAChF;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,4BAA4B,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC"}

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

@@ -0,0 +1,67 @@
+/**
+ * `animation-timeline-helpers` - pure helpers for the native-animation timeline:
+ * effect resolution, dynamic (motion-path / rotation / scale / colour) keyframe
+ * generation, default durations, fill-mode mapping, and click-group finalisation.
+ *
+ * Two dynamic-keyframe builders coexist (with deliberately distinct keyframe
+ * name prefixes so the two playback models never collide):
+ *  - {@link buildDynamicKeyframes} (plural) - `pptx-motionPath-*` / `pptx-rotateBy-*`
+ *    / `pptx-scaleBy-*`. Used by the flat {@link AnimationStep} sequencer.
+ *  - {@link buildDynamicKeyframe} (singular) - `pptx-tl-motion-*` / `pptx-tl-rotate-*`
+ *    / `pptx-tl-scale-*`, plus motion-path auto-rotate. Used by the click-group
+ *    {@link buildTimeline} engine.
+ *
+ * @module render/animation-timeline-helpers
+ */
+import type { PptxNativeAnimation } from 'ooxml-core/pptx';
+import type { AnimationElementBox, AnimationRenderContext } from './animation-render-context.js';
+import type { EffectName } from './animation-timeline-types.js';
+/**
+ * Resolve the static {@link EffectName} for a native animation from its
+ * `presetClass` + `presetId`. Returns `undefined` for path/motion/rotation/scale
+ * animations (which are handled dynamically) and for unknown ids.
+ *
+ * `presetId` is the PRIMARY selector. When it is absent, or present but not
+ * in {@link PRESET_ID_TO_EFFECT} (a preset a tool other than PowerPoint wrote,
+ * or one this catalogue does not yet cover), the animation's parsed
+ * `p:animEffect/@filter` (`anim.effectFilter`) is consulted as a FALLBACK via
+ * `resolveFilterEffect`, so a deck whose only description of the effect is
+ * the filter string (no recognisable `presetId`) still resolves to a real
+ * effect instead of falling straight to the neutral safety net. `path`-class
+ * animations (motion path) never consult the filter: `p:animEffect` filters
+ * describe reveal/conceal transitions, not motion.
+ *
+ * @param pixelateMosaic - Forwarded to {@link resolveFilterEffect} unchanged;
+ *   see its doc for the `pixelate` filter family default (snap to end state,
+ *   matching PowerPoint) versus this opt-in mosaic override.
+ */
+export declare function resolveEffect(anim: PptxNativeAnimation, pixelateMosaic?: boolean): EffectName | undefined;
+/**
+ * The animated element's real box + the deck's theme colour map, when the
+ * caller built one (see `animation-render-context.ts`). Resolves cross-axis
+ * `p:anim` geometry formulas (Grow And Turn's `-#ppt_w/2` fly-in) and
+ * scheme-colour (`a:schemeClr`) ramp stops that would otherwise fall back to
+ * canned timing / be dropped.
+ */
+export declare function boxForAnimation(anim: PptxNativeAnimation, renderContext: AnimationRenderContext | undefined): AnimationElementBox | undefined;
+/**
+ * Build a dynamic CSS `@keyframes` block for motion path, rotation, scale, or
+ * colour animations that don't map to a static effect preset. Uses the
+ * `pptx-motionPath-*` / `pptx-rotateBy-*` / `pptx-scaleBy-*` / `pptx-color-*`
+ * name prefixes (flat-sequence model).
+ */
+export declare function buildDynamicKeyframes(anim: PptxNativeAnimation, uid: number, renderContext?: AnimationRenderContext): {
+    keyframeName: string;
+    css: string;
+} | undefined;
+/**
+ * Build a dynamic CSS `@keyframes` block for the click-group timeline engine.
+ * Uses the `pptx-tl-motion-*` / `pptx-tl-rotate-*` / `pptx-tl-scale-*` /
+ * `pptx-tl-color-*` prefixes and supports motion-path auto-rotate.
+ */
+export declare function buildDynamicKeyframe(anim: PptxNativeAnimation, uid: number, renderContext?: AnimationRenderContext): {
+    keyframeName: string;
+    css: string;
+} | undefined;
+export { cssKeyframeName, defaultDuration, fillModeForClass, finalizeClickGroup, } from './animation-timeline-group-helpers.js';
+//# sourceMappingURL=animation-timeline-helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-helpers.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAe3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAG9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAO7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,mBAAmB,EACzB,cAAc,CAAC,EAAE,OAAO,GACtB,UAAU,GAAG,SAAS,CA0CxB;AA+DD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,mBAAmB,EACzB,aAAa,EAAE,sBAAsB,GAAG,SAAS,GAC/C,mBAAmB,GAAG,SAAS,CAMjC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,MAAM,EACX,aAAa,CAAC,EAAE,sBAAsB,GACpC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA8CnD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,MAAM,EACX,aAAa,CAAC,EAAE,sBAAsB,GACpC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA2CnD;AAED,OAAO,EACN,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GAClB,MAAM,oCAAoC,CAAC"}

package/dist/pptx/render/animation-timeline-regular-step.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `animation-timeline-regular-step` - the per-animation step-building loop
+ * body used by `animation-timeline-builder`'s main (non-interactive,
+ * non-hover) click-group pass. Split out of `animation-timeline-builder` to
+ * keep that module under the file-size limit; behaviour is unchanged, this
+ * is the same loop body threaded through an explicit mutable state bag
+ * instead of closure-captured locals, with the effect-resolution and
+ * scheduling sub-steps further split into `animation-timeline-step-effect`
+ * and `animation-timeline-step-scheduling`.
+ *
+ * @module render/animation-timeline-regular-step
+ */
+import type { PptxNativeAnimation } from 'ooxml-core/pptx';
+import type { AnimationRenderContext } from './animation-render-context.js';
+import type { EffectName, TimelineStep, TimelineClickGroup } from './animation-timeline-types.js';
+/** Mutable state threaded through the main click-group building loop. */
+export interface RegularBuildState {
+    clickGroups: TimelineClickGroup[];
+    entranceIds: Set<string>;
+    neededKeyframes: Set<EffectName>;
+    dynamicBlocks: string[];
+    dynamicUid: number;
+    currentGroup: TimelineStep[];
+    currentGroupLastParallelIndex: number | undefined;
+    /** Whether the current group was started by an onClick trigger. */
+    currentGroupIsClick: boolean;
+    /**
+     * Whether the current group's OOXML click step begins on slide entry rather
+     * than on a click (`groupAutoStart` from the parse layer).
+     */
+    currentGroupAutoStart: boolean;
+    /**
+     * Effect-wrapper (`p:par`) index of the sub-group being filled, and the time
+     * that wrapper starts relative to the click group. Siblings of one wrapper all
+     * measure their delay from `subGroupStartMs`; a new wrapper chains off the
+     * previous step instead.
+     */
+    subGroupIndex: number | undefined;
+    subGroupStartMs: number;
+    /**
+     * Maps each effect's own `p:cTn/@_id` (`PptxNativeAnimation.nodeId`) to the
+     * {@link TimelineStep} built for it, so a LATER effect whose `p:cond/@_tn`
+     * (`dependsOnTimeNodeId`) names an EARLIER, non-adjacent node can schedule
+     * off that node's real computed end time instead of assuming it is always
+     * the positionally-previous step (ECMA-376 S19.5.28 CT_TLTimeCondition; see
+     * `animation-advanced-triggers`).
+     */
+    stepsByNodeId: Map<number, TimelineStep>;
+}
+/** Create a fresh {@link RegularBuildState} for the main click-group pass. */
+export declare function createRegularBuildState(): RegularBuildState;
+/**
+ * Expand an animation with `iterate` configuration into multiple
+ * staggered sub-animations. Each sub-element gets a slightly delayed copy.
+ *
+ * - `iterate.type === "lt"` (letter): creates per-character animations
+ * - `iterate.type === "wd"` (word): creates per-word animations
+ * - `iterate.type === "el"` (element): no expansion needed
+ *
+ * The iterate timing interval (`tmPct` or `tmAbs`) controls the stagger
+ * delay between consecutive sub-elements.
+ */
+export declare function expandIterateAnimation(anim: PptxNativeAnimation): PptxNativeAnimation[];
+/**
+ * Process one native animation into the main click-group timeline, mutating
+ * `state` in place (pushing finished click-groups, growing the current one,
+ * and accumulating keyframe/dynamic-CSS bookkeeping).
+ *
+ * See `buildTimeline`'s module doc for the grouping rules this implements.
+ */
+export declare function processRegularAnimation(state: RegularBuildState, anim: PptxNativeAnimation, renderContext: AnimationRenderContext | undefined, pixelateMosaic?: boolean): void;
+export { finalizeClickGroup } from './animation-timeline-helpers.js';
+//# sourceMappingURL=animation-timeline-regular-step.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"animation-timeline-regular-step.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/animation-timeline-regular-step.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAwB,MAAM,iBAAiB,CAAC;AASjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAOzE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,eAAe,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACjC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,6BAA6B,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,mEAAmE;IACnE,mBAAmB,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,qBAAqB,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACzC;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,IAAI,iBAAiB,CAe3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,mBAAmB,EAAE,CAOvF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,mBAAmB,EACzB,aAAa,EAAE,sBAAsB,GAAG,SAAS,EAGjD,cAAc,CAAC,EAAE,OAAO,GACtB,IAAI,CA4KN;AAKD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC"}