@pixerate/editor 0.26.1 → 0.28.0

package/dist/animation/index.d.cts

@@ -0,0 +1,296 @@
+/**
+ * Keyframe easing: the curve a segment follows from one keyframe to the next.
+ *
+ * - `hold` keeps the first keyframe's value until the next one (a step).
+ * - `linear` and the CSS presets (`ease`, `ease-in`, `ease-out`, `ease-in-out`) are
+ *   CSS-compatible `cubic-bezier()` curves; `{ type: 'cubic-bezier', x1, y1, x2, y2 }` is any
+ *   such curve (x1 / y1 is the leaving keyframe's out handle, x2 / y2 the next one's in handle).
+ * - `spring` is a damped spring settling on the next value (it may overshoot).
+ */
+/** Named easing presets. */
+type AnimationEasingPreset = 'linear' | 'hold' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'ease-in-back' | 'ease-out-back' | 'spring';
+interface CubicBezierEasing {
+    type: 'cubic-bezier';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+interface SpringEasing {
+    type: 'spring';
+    /** Spring stiffness (default 170). */
+    stiffness?: number;
+    /** Damping (default 26). */
+    damping?: number;
+    /** Mass (default 1). */
+    mass?: number;
+    /** Initial velocity in units of the segment's value change per second (default 0). */
+    velocity?: number;
+}
+type AnimationEasing = AnimationEasingPreset | CubicBezierEasing | SpringEasing;
+/** Preset names, in picker order. */
+declare const ANIMATION_EASING_PRESETS: readonly AnimationEasingPreset[];
+/** Picker labels for the presets. */
+declare const ANIMATION_EASING_LABELS: Readonly<Record<AnimationEasingPreset, string>>;
+/** The CSS control points of the bezier presets (CSS Easing Functions Level 1 values for the CSS keywords). */
+declare const CUBIC_BEZIER_PRESETS: Readonly<Record<string, readonly [number, number, number, number]>>;
+/**
+ * Solves a CSS `cubic-bezier(x1, y1, x2, y2)` for y at progress x (Newton steps with a
+ * bisection fallback). x1 / x2 are clamped to 0–1 as CSS requires.
+ */
+declare function cubicBezierAt(x1: number, y1: number, x2: number, y2: number, x: number): number;
+/**
+ * Normalised position of a damped spring released from 0 towards 1, `seconds` after release.
+ * Closed form for under-, critically and over-damped springs.
+ */
+declare function springAt(spring: Omit<SpringEasing, 'type'>, seconds: number): number;
+/** Resolves an easing to a cubic-bezier, spring or hold descriptor (unknown input → linear). */
+declare function resolveEasing(easing: AnimationEasing | string | undefined | null): CubicBezierEasing | Required<SpringEasing> | 'hold';
+/**
+ * Eased progress for linear progress `u` (0–1) through a segment lasting `durationMs`
+ * (springs depend on real time; other curves ignore it). `hold` returns 0 until `u` reaches 1.
+ */
+declare function evaluateEasing(easing: AnimationEasing | string | undefined | null, u: number, durationMs?: number): number;
+/**
+ * The easing filmcraft (and Premiere) derive from temporal "influence" handles: flat handles of
+ * the given influences (0.01–1, default 1/3) on the leaving and arriving keyframe.
+ */
+declare function easingFromInfluence(outInfluence?: number, inInfluence?: number): CubicBezierEasing;
+/**
+ * Parses a CSS easing (`linear`, `ease…`, `cubic-bezier(…)`, `steps(1, end)` / `step-end` →
+ * hold) or a preset name. Returns `null` for anything else.
+ */
+declare function parseCssEasing(text: string): AnimationEasing | null;
+/** Whether a value is a usable easing (preset name, CSS easing string or descriptor). */
+declare function isAnimationEasing(value: unknown): value is AnimationEasing;
+/**
+ * The CSS `animation-timing-function` for an easing: a keyword or `cubic-bezier()`,
+ * `steps(1, end)` for hold, and a sampled `linear(…)` for springs over `durationMs`.
+ */
+declare function easingToCss(easing: AnimationEasing | string | undefined | null, durationMs?: number, samples?: number): string;
+/** Short label for an easing (a preset's label, or `Custom` / `Spring`). */
+declare function easingLabel(easing: AnimationEasing | undefined | null): string;
+
+/**
+ * Colour interpolation in OKLab (Björn Ottosson's perceptual space, as CSS Color 4 uses for
+ * `color-mix(in oklab, …)`), with premultiplied alpha so a fade to `transparent` does not
+ * darken through black.
+ */
+interface OklabColor {
+    /** Lightness, 0–1. */
+    l: number;
+    a: number;
+    b: number;
+    /** Alpha, 0–1. */
+    alpha: number;
+}
+/** sRGB channels (0–1) to OKLab. */
+declare function rgbToOklab(r: number, g: number, b: number, alpha?: number): OklabColor;
+/** OKLab to sRGB channels (0–1, clamped into gamut). */
+declare function oklabToRgb(color: OklabColor): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/** Parses a CSS colour (hex, `rgb()` / `rgba()`, `transparent`, `black`, `white`) to OKLab, or `null`. */
+declare function parseOklab(input: unknown): OklabColor | null;
+/** Formats OKLab as `#rrggbb` (or `#rrggbbaa` when translucent). */
+declare function formatOklab(color: OklabColor): string;
+/**
+ * Mixes two colours at `t` (0 = `from`, 1 = `to`) in OKLab with premultiplied alpha.
+ * Returns `null` when either is not a readable colour.
+ */
+declare function mixColorsOklab(from: unknown, to: unknown, t: number): string | null;
+
+/**
+ * Keyframe tracks, independent of what they animate: each track is a list of keyframes
+ * `{ time (ms), value, easing }`, where the easing governs the segment *leaving* the keyframe
+ * (filmcraft / After Effects convention).
+ */
+/** Keyframe times closer than this (ms) are the same time. */
+declare const ANIMATION_TIME_EPSILON = 0.000001;
+/** A keyframe value: a number, or a CSS colour for colour properties. */
+type AnimationValue = number | string;
+interface AnimationKeyframe {
+    /** Time in milliseconds from the start of the timeline. */
+    time: number;
+    value: AnimationValue;
+    /** Easing of the segment from this keyframe to the next (default `linear`). */
+    easing?: AnimationEasing;
+}
+interface AnimationTrack {
+    keyframes: AnimationKeyframe[];
+    /** Disabled tracks keep their keyframes but do not animate (default `true`). */
+    enabled?: boolean;
+}
+/** How a track's values interpolate: numbers linearly, colours in OKLab. */
+type AnimationValueType = 'number' | 'color';
+/** Whether `value` is a well-formed keyframe. */
+declare function isAnimationKeyframe(value: unknown): value is AnimationKeyframe;
+/**
+ * Keyframes sorted by time, invalid entries dropped and duplicate times merged (the *later*
+ * entry in the array wins, so appending a keyframe replaces one at the same time). Cached per
+ * array (revalidated by element identity), so evaluating every frame does not re-sort; treat
+ * keyframe objects as immutable.
+ */
+declare function normalizeKeyframes(keyframes: readonly AnimationKeyframe[] | undefined | null): AnimationKeyframe[];
+
+/** How time past the end of the timeline maps back into it. */
+type AnimationLoopMode = 'none' | 'loop' | 'ping-pong';
+/**
+ * Interpolates between two keyframe values: numbers linearly, colours in OKLab (premultiplied
+ * alpha). Mismatched or unreadable values hold `from` until `t` reaches 1.
+ */
+declare function interpolateAnimationValue(from: AnimationValue, to: AnimationValue, t: number, type?: AnimationValueType): AnimationValue;
+/**
+ * A track's value at `time`. Before the first keyframe it holds the first value, after the
+ * last the last value. Keyframes may be unsorted or share times (see `normalizeKeyframes`).
+ * Returns `undefined` for a track without valid keyframes.
+ */
+declare function evaluateTrack(track: AnimationTrack | readonly AnimationKeyframe[] | undefined | null, time: number, type?: AnimationValueType): AnimationValue | undefined;
+/**
+ * Maps a running time onto the timeline `[0, duration]`: clamped (`none`), wrapped (`loop`)
+ * or bounced (`ping-pong`).
+ */
+declare function wrapAnimationTime(time: number, duration: number, loop?: AnimationLoopMode): number;
+
+/**
+ * The time source that animations (and canvas agent performances) play on.
+ *
+ * Defaults to `realClock` (requestAnimationFrame and setTimeout).
+ * A `ManualClock` moves only when told to via `advance(ms)` or `tick(fps)`,
+ * enabling deterministic frame-by-frame stepping for testing, video generation,
+ * or headless server environments.
+ */
+interface Clock {
+    /** Current time in milliseconds. */
+    now(): number;
+    /** Resolves on the next animation frame. */
+    frame(): Promise<void>;
+    /** Resolves after `ms` milliseconds of this clock's time. */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Whether the clock follows wall time. Live clocks stop or degrade when the
+     * tab is in the background (browsers pause animation frames), so transitions
+     * can commit immediately rather than leaving operations hanging.
+     */
+    readonly live: boolean;
+}
+/** Whether the browser tab is hidden (where RAF pauses). */
+declare const pageHidden: () => boolean;
+/** Real-time clock using requestAnimationFrame and setTimeout. */
+declare const realClock: Clock;
+/**
+ * A deterministic clock that only moves forward when `advance` or `tick` is called.
+ * Allows step-by-step frame testing and video rendering without waiting for real time.
+ */
+declare class ManualClock implements Clock {
+    readonly live = false;
+    private time;
+    private frames;
+    private sleepers;
+    private seq;
+    constructor(start?: number);
+    now(): number;
+    frame(): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    /** Whether any frames or sleep timers are currently pending. */
+    get pending(): boolean;
+    /** Advances time by `ms`, resolving due sleep timers in order, followed by queued frames. */
+    advance(ms: number): Promise<void>;
+    /** Convenience method to advance by 1 frame at a given fps (default: 60fps = 16.67ms). */
+    tick(fps?: number): Promise<void>;
+}
+
+interface AnimationPlayerState {
+    /** Playhead time in ms, inside `[0, duration]`. */
+    time: number;
+    playing: boolean;
+    /** True between `scrub` and `endScrub`. */
+    scrubbing: boolean;
+    loop: AnimationLoopMode;
+    /** Speed multiplier (negative plays backwards). */
+    playbackRate: number;
+    duration: number;
+}
+interface AnimationPlayerOptions {
+    /** Time source (default `realClock`: requestAnimationFrame). Pass a `ManualClock` in tests or for rendering. */
+    clock?: Clock;
+    /** Timeline length in ms, or a getter (e.g. the last keyframe time). Default 1000. */
+    duration?: number | (() => number);
+    loop?: AnimationLoopMode;
+    playbackRate?: number;
+    /** Initial playhead time (default 0). */
+    time?: number;
+    /** Called whenever the playhead moves (playback, seek, scrub). */
+    onTime?: (time: number) => void;
+    /** Called when non-looping playback reaches the end (or the start, playing backwards). */
+    onEnd?: () => void;
+}
+/**
+ * Plays a timeline on an injectable `Clock`: play / pause / seek / scrub with looping,
+ * ping-pong and playback rate. It only asks the clock for frames while playing, so a
+ * `ManualClock` steps it deterministically and the real clock's requestAnimationFrame is the
+ * only place wall time enters.
+ *
+ * `getState()` returns a cached snapshot replaced on change (usable with `useSyncExternalStore`).
+ */
+declare class AnimationPlayer {
+    private readonly clock;
+    private durationSource;
+    private onTime?;
+    private onEnd?;
+    private time;
+    private playing;
+    private scrubbing;
+    private resumeAfterScrub;
+    private loop;
+    private rate;
+    /** Unwrapped time at `anchorAt` (keeps the ping-pong direction across frames). */
+    private anchorRaw;
+    private anchorAt;
+    private generation;
+    private cached;
+    private listeners;
+    constructor(options?: AnimationPlayerOptions);
+    /** Current timeline length (ms). */
+    get duration(): number;
+    get currentTime(): number;
+    get isPlaying(): boolean;
+    getState(): AnimationPlayerState;
+    subscribe(listener: (state: AnimationPlayerState) => void): () => void;
+    /** Replaces the callbacks (hooks keep them current without recreating the player). */
+    setCallbacks(callbacks: {
+        onTime?: (time: number) => void;
+        onEnd?: () => void;
+    }): void;
+    setDuration(duration: number | (() => number)): void;
+    setLoop(loop: AnimationLoopMode): void;
+    setPlaybackRate(rate: number): void;
+    /** Starts playing from the playhead (from the start again when a one-shot play had ended). */
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Pauses and returns to the start. */
+    stop(): void;
+    /** Moves the playhead (clamped to the timeline); playback continues from there. */
+    seek(time: number): void;
+    /** Seeks while dragging the playhead: playback pauses until `endScrub`. */
+    scrub(time: number): void;
+    /** Ends a scrub, resuming playback if it was playing when the scrub began. */
+    endScrub(): void;
+    /** Stops scheduling frames and drops listeners. */
+    destroy(): void;
+    private clamp;
+    private reanchor;
+    private rawNow;
+    private schedule;
+    /** Advances the playhead to the clock's time; `notify` emits the change. */
+    private tick;
+    private snapshot;
+    private emit;
+}
+declare function createAnimationPlayer(options?: AnimationPlayerOptions): AnimationPlayer;
+
+export { ANIMATION_EASING_LABELS, ANIMATION_EASING_PRESETS, ANIMATION_TIME_EPSILON, type AnimationEasing, type AnimationEasingPreset, type AnimationKeyframe, type AnimationLoopMode, AnimationPlayer, type AnimationPlayerOptions, type AnimationPlayerState, type AnimationTrack, type AnimationValue, type AnimationValueType, CUBIC_BEZIER_PRESETS, type Clock, type CubicBezierEasing, ManualClock, type OklabColor, type SpringEasing, createAnimationPlayer, cubicBezierAt, easingFromInfluence, easingLabel, easingToCss, evaluateEasing, evaluateTrack, formatOklab, interpolateAnimationValue, isAnimationEasing, isAnimationKeyframe, mixColorsOklab, normalizeKeyframes, oklabToRgb, pageHidden, parseCssEasing, parseOklab, realClock, resolveEasing, rgbToOklab, springAt, wrapAnimationTime };

package/dist/animation/index.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Keyframe easing: the curve a segment follows from one keyframe to the next.
+ *
+ * - `hold` keeps the first keyframe's value until the next one (a step).
+ * - `linear` and the CSS presets (`ease`, `ease-in`, `ease-out`, `ease-in-out`) are
+ *   CSS-compatible `cubic-bezier()` curves; `{ type: 'cubic-bezier', x1, y1, x2, y2 }` is any
+ *   such curve (x1 / y1 is the leaving keyframe's out handle, x2 / y2 the next one's in handle).
+ * - `spring` is a damped spring settling on the next value (it may overshoot).
+ */
+/** Named easing presets. */
+type AnimationEasingPreset = 'linear' | 'hold' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'ease-in-back' | 'ease-out-back' | 'spring';
+interface CubicBezierEasing {
+    type: 'cubic-bezier';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+interface SpringEasing {
+    type: 'spring';
+    /** Spring stiffness (default 170). */
+    stiffness?: number;
+    /** Damping (default 26). */
+    damping?: number;
+    /** Mass (default 1). */
+    mass?: number;
+    /** Initial velocity in units of the segment's value change per second (default 0). */
+    velocity?: number;
+}
+type AnimationEasing = AnimationEasingPreset | CubicBezierEasing | SpringEasing;
+/** Preset names, in picker order. */
+declare const ANIMATION_EASING_PRESETS: readonly AnimationEasingPreset[];
+/** Picker labels for the presets. */
+declare const ANIMATION_EASING_LABELS: Readonly<Record<AnimationEasingPreset, string>>;
+/** The CSS control points of the bezier presets (CSS Easing Functions Level 1 values for the CSS keywords). */
+declare const CUBIC_BEZIER_PRESETS: Readonly<Record<string, readonly [number, number, number, number]>>;
+/**
+ * Solves a CSS `cubic-bezier(x1, y1, x2, y2)` for y at progress x (Newton steps with a
+ * bisection fallback). x1 / x2 are clamped to 0–1 as CSS requires.
+ */
+declare function cubicBezierAt(x1: number, y1: number, x2: number, y2: number, x: number): number;
+/**
+ * Normalised position of a damped spring released from 0 towards 1, `seconds` after release.
+ * Closed form for under-, critically and over-damped springs.
+ */
+declare function springAt(spring: Omit<SpringEasing, 'type'>, seconds: number): number;
+/** Resolves an easing to a cubic-bezier, spring or hold descriptor (unknown input → linear). */
+declare function resolveEasing(easing: AnimationEasing | string | undefined | null): CubicBezierEasing | Required<SpringEasing> | 'hold';
+/**
+ * Eased progress for linear progress `u` (0–1) through a segment lasting `durationMs`
+ * (springs depend on real time; other curves ignore it). `hold` returns 0 until `u` reaches 1.
+ */
+declare function evaluateEasing(easing: AnimationEasing | string | undefined | null, u: number, durationMs?: number): number;
+/**
+ * The easing filmcraft (and Premiere) derive from temporal "influence" handles: flat handles of
+ * the given influences (0.01–1, default 1/3) on the leaving and arriving keyframe.
+ */
+declare function easingFromInfluence(outInfluence?: number, inInfluence?: number): CubicBezierEasing;
+/**
+ * Parses a CSS easing (`linear`, `ease…`, `cubic-bezier(…)`, `steps(1, end)` / `step-end` →
+ * hold) or a preset name. Returns `null` for anything else.
+ */
+declare function parseCssEasing(text: string): AnimationEasing | null;
+/** Whether a value is a usable easing (preset name, CSS easing string or descriptor). */
+declare function isAnimationEasing(value: unknown): value is AnimationEasing;
+/**
+ * The CSS `animation-timing-function` for an easing: a keyword or `cubic-bezier()`,
+ * `steps(1, end)` for hold, and a sampled `linear(…)` for springs over `durationMs`.
+ */
+declare function easingToCss(easing: AnimationEasing | string | undefined | null, durationMs?: number, samples?: number): string;
+/** Short label for an easing (a preset's label, or `Custom` / `Spring`). */
+declare function easingLabel(easing: AnimationEasing | undefined | null): string;
+
+/**
+ * Colour interpolation in OKLab (Björn Ottosson's perceptual space, as CSS Color 4 uses for
+ * `color-mix(in oklab, …)`), with premultiplied alpha so a fade to `transparent` does not
+ * darken through black.
+ */
+interface OklabColor {
+    /** Lightness, 0–1. */
+    l: number;
+    a: number;
+    b: number;
+    /** Alpha, 0–1. */
+    alpha: number;
+}
+/** sRGB channels (0–1) to OKLab. */
+declare function rgbToOklab(r: number, g: number, b: number, alpha?: number): OklabColor;
+/** OKLab to sRGB channels (0–1, clamped into gamut). */
+declare function oklabToRgb(color: OklabColor): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/** Parses a CSS colour (hex, `rgb()` / `rgba()`, `transparent`, `black`, `white`) to OKLab, or `null`. */
+declare function parseOklab(input: unknown): OklabColor | null;
+/** Formats OKLab as `#rrggbb` (or `#rrggbbaa` when translucent). */
+declare function formatOklab(color: OklabColor): string;
+/**
+ * Mixes two colours at `t` (0 = `from`, 1 = `to`) in OKLab with premultiplied alpha.
+ * Returns `null` when either is not a readable colour.
+ */
+declare function mixColorsOklab(from: unknown, to: unknown, t: number): string | null;
+
+/**
+ * Keyframe tracks, independent of what they animate: each track is a list of keyframes
+ * `{ time (ms), value, easing }`, where the easing governs the segment *leaving* the keyframe
+ * (filmcraft / After Effects convention).
+ */
+/** Keyframe times closer than this (ms) are the same time. */
+declare const ANIMATION_TIME_EPSILON = 0.000001;
+/** A keyframe value: a number, or a CSS colour for colour properties. */
+type AnimationValue = number | string;
+interface AnimationKeyframe {
+    /** Time in milliseconds from the start of the timeline. */
+    time: number;
+    value: AnimationValue;
+    /** Easing of the segment from this keyframe to the next (default `linear`). */
+    easing?: AnimationEasing;
+}
+interface AnimationTrack {
+    keyframes: AnimationKeyframe[];
+    /** Disabled tracks keep their keyframes but do not animate (default `true`). */
+    enabled?: boolean;
+}
+/** How a track's values interpolate: numbers linearly, colours in OKLab. */
+type AnimationValueType = 'number' | 'color';
+/** Whether `value` is a well-formed keyframe. */
+declare function isAnimationKeyframe(value: unknown): value is AnimationKeyframe;
+/**
+ * Keyframes sorted by time, invalid entries dropped and duplicate times merged (the *later*
+ * entry in the array wins, so appending a keyframe replaces one at the same time). Cached per
+ * array (revalidated by element identity), so evaluating every frame does not re-sort; treat
+ * keyframe objects as immutable.
+ */
+declare function normalizeKeyframes(keyframes: readonly AnimationKeyframe[] | undefined | null): AnimationKeyframe[];
+
+/** How time past the end of the timeline maps back into it. */
+type AnimationLoopMode = 'none' | 'loop' | 'ping-pong';
+/**
+ * Interpolates between two keyframe values: numbers linearly, colours in OKLab (premultiplied
+ * alpha). Mismatched or unreadable values hold `from` until `t` reaches 1.
+ */
+declare function interpolateAnimationValue(from: AnimationValue, to: AnimationValue, t: number, type?: AnimationValueType): AnimationValue;
+/**
+ * A track's value at `time`. Before the first keyframe it holds the first value, after the
+ * last the last value. Keyframes may be unsorted or share times (see `normalizeKeyframes`).
+ * Returns `undefined` for a track without valid keyframes.
+ */
+declare function evaluateTrack(track: AnimationTrack | readonly AnimationKeyframe[] | undefined | null, time: number, type?: AnimationValueType): AnimationValue | undefined;
+/**
+ * Maps a running time onto the timeline `[0, duration]`: clamped (`none`), wrapped (`loop`)
+ * or bounced (`ping-pong`).
+ */
+declare function wrapAnimationTime(time: number, duration: number, loop?: AnimationLoopMode): number;
+
+/**
+ * The time source that animations (and canvas agent performances) play on.
+ *
+ * Defaults to `realClock` (requestAnimationFrame and setTimeout).
+ * A `ManualClock` moves only when told to via `advance(ms)` or `tick(fps)`,
+ * enabling deterministic frame-by-frame stepping for testing, video generation,
+ * or headless server environments.
+ */
+interface Clock {
+    /** Current time in milliseconds. */
+    now(): number;
+    /** Resolves on the next animation frame. */
+    frame(): Promise<void>;
+    /** Resolves after `ms` milliseconds of this clock's time. */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Whether the clock follows wall time. Live clocks stop or degrade when the
+     * tab is in the background (browsers pause animation frames), so transitions
+     * can commit immediately rather than leaving operations hanging.
+     */
+    readonly live: boolean;
+}
+/** Whether the browser tab is hidden (where RAF pauses). */
+declare const pageHidden: () => boolean;
+/** Real-time clock using requestAnimationFrame and setTimeout. */
+declare const realClock: Clock;
+/**
+ * A deterministic clock that only moves forward when `advance` or `tick` is called.
+ * Allows step-by-step frame testing and video rendering without waiting for real time.
+ */
+declare class ManualClock implements Clock {
+    readonly live = false;
+    private time;
+    private frames;
+    private sleepers;
+    private seq;
+    constructor(start?: number);
+    now(): number;
+    frame(): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    /** Whether any frames or sleep timers are currently pending. */
+    get pending(): boolean;
+    /** Advances time by `ms`, resolving due sleep timers in order, followed by queued frames. */
+    advance(ms: number): Promise<void>;
+    /** Convenience method to advance by 1 frame at a given fps (default: 60fps = 16.67ms). */
+    tick(fps?: number): Promise<void>;
+}
+
+interface AnimationPlayerState {
+    /** Playhead time in ms, inside `[0, duration]`. */
+    time: number;
+    playing: boolean;
+    /** True between `scrub` and `endScrub`. */
+    scrubbing: boolean;
+    loop: AnimationLoopMode;
+    /** Speed multiplier (negative plays backwards). */
+    playbackRate: number;
+    duration: number;
+}
+interface AnimationPlayerOptions {
+    /** Time source (default `realClock`: requestAnimationFrame). Pass a `ManualClock` in tests or for rendering. */
+    clock?: Clock;
+    /** Timeline length in ms, or a getter (e.g. the last keyframe time). Default 1000. */
+    duration?: number | (() => number);
+    loop?: AnimationLoopMode;
+    playbackRate?: number;
+    /** Initial playhead time (default 0). */
+    time?: number;
+    /** Called whenever the playhead moves (playback, seek, scrub). */
+    onTime?: (time: number) => void;
+    /** Called when non-looping playback reaches the end (or the start, playing backwards). */
+    onEnd?: () => void;
+}
+/**
+ * Plays a timeline on an injectable `Clock`: play / pause / seek / scrub with looping,
+ * ping-pong and playback rate. It only asks the clock for frames while playing, so a
+ * `ManualClock` steps it deterministically and the real clock's requestAnimationFrame is the
+ * only place wall time enters.
+ *
+ * `getState()` returns a cached snapshot replaced on change (usable with `useSyncExternalStore`).
+ */
+declare class AnimationPlayer {
+    private readonly clock;
+    private durationSource;
+    private onTime?;
+    private onEnd?;
+    private time;
+    private playing;
+    private scrubbing;
+    private resumeAfterScrub;
+    private loop;
+    private rate;
+    /** Unwrapped time at `anchorAt` (keeps the ping-pong direction across frames). */
+    private anchorRaw;
+    private anchorAt;
+    private generation;
+    private cached;
+    private listeners;
+    constructor(options?: AnimationPlayerOptions);
+    /** Current timeline length (ms). */
+    get duration(): number;
+    get currentTime(): number;
+    get isPlaying(): boolean;
+    getState(): AnimationPlayerState;
+    subscribe(listener: (state: AnimationPlayerState) => void): () => void;
+    /** Replaces the callbacks (hooks keep them current without recreating the player). */
+    setCallbacks(callbacks: {
+        onTime?: (time: number) => void;
+        onEnd?: () => void;
+    }): void;
+    setDuration(duration: number | (() => number)): void;
+    setLoop(loop: AnimationLoopMode): void;
+    setPlaybackRate(rate: number): void;
+    /** Starts playing from the playhead (from the start again when a one-shot play had ended). */
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Pauses and returns to the start. */
+    stop(): void;
+    /** Moves the playhead (clamped to the timeline); playback continues from there. */
+    seek(time: number): void;
+    /** Seeks while dragging the playhead: playback pauses until `endScrub`. */
+    scrub(time: number): void;
+    /** Ends a scrub, resuming playback if it was playing when the scrub began. */
+    endScrub(): void;
+    /** Stops scheduling frames and drops listeners. */
+    destroy(): void;
+    private clamp;
+    private reanchor;
+    private rawNow;
+    private schedule;
+    /** Advances the playhead to the clock's time; `notify` emits the change. */
+    private tick;
+    private snapshot;
+    private emit;
+}
+declare function createAnimationPlayer(options?: AnimationPlayerOptions): AnimationPlayer;
+
+export { ANIMATION_EASING_LABELS, ANIMATION_EASING_PRESETS, ANIMATION_TIME_EPSILON, type AnimationEasing, type AnimationEasingPreset, type AnimationKeyframe, type AnimationLoopMode, AnimationPlayer, type AnimationPlayerOptions, type AnimationPlayerState, type AnimationTrack, type AnimationValue, type AnimationValueType, CUBIC_BEZIER_PRESETS, type Clock, type CubicBezierEasing, ManualClock, type OklabColor, type SpringEasing, createAnimationPlayer, cubicBezierAt, easingFromInfluence, easingLabel, easingToCss, evaluateEasing, evaluateTrack, formatOklab, interpolateAnimationValue, isAnimationEasing, isAnimationKeyframe, mixColorsOklab, normalizeKeyframes, oklabToRgb, pageHidden, parseCssEasing, parseOklab, realClock, resolveEasing, rgbToOklab, springAt, wrapAnimationTime };

package/dist/animation/index.js

@@ -0,0 +1,62 @@
+import {
+  ANIMATION_EASING_LABELS,
+  ANIMATION_EASING_PRESETS,
+  ANIMATION_TIME_EPSILON,
+  AnimationPlayer,
+  CUBIC_BEZIER_PRESETS,
+  ManualClock,
+  createAnimationPlayer,
+  cubicBezierAt,
+  easingFromInfluence,
+  easingLabel,
+  easingToCss,
+  evaluateEasing,
+  evaluateTrack,
+  formatOklab,
+  interpolateAnimationValue,
+  isAnimationEasing,
+  isAnimationKeyframe,
+  mixColorsOklab,
+  normalizeKeyframes,
+  oklabToRgb,
+  pageHidden,
+  parseCssEasing,
+  parseOklab,
+  realClock,
+  resolveEasing,
+  rgbToOklab,
+  springAt,
+  wrapAnimationTime
+} from "../chunk-PWJARCI4.js";
+import "../chunk-TGD52FEZ.js";
+export {
+  ANIMATION_EASING_LABELS,
+  ANIMATION_EASING_PRESETS,
+  ANIMATION_TIME_EPSILON,
+  AnimationPlayer,
+  CUBIC_BEZIER_PRESETS,
+  ManualClock,
+  createAnimationPlayer,
+  cubicBezierAt,
+  easingFromInfluence,
+  easingLabel,
+  easingToCss,
+  evaluateEasing,
+  evaluateTrack,
+  formatOklab,
+  interpolateAnimationValue,
+  isAnimationEasing,
+  isAnimationKeyframe,
+  mixColorsOklab,
+  normalizeKeyframes,
+  oklabToRgb,
+  pageHidden,
+  parseCssEasing,
+  parseOklab,
+  realClock,
+  resolveEasing,
+  rgbToOklab,
+  springAt,
+  wrapAnimationTime
+};
+//# sourceMappingURL=index.js.map

package/dist/animation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}