anim-engine 0.4.0 → 0.5.1

package/dist/animation/runner.js

@@ -4,13 +4,13 @@ var noOp = () => {};
 var createTweenRunner = ({ from, to, durationMs, easeFn, onStarted, onUpdate = noOp, onProgress = noOp, onEnded }) => {
 	const state = {
 		progress: 0,
-		currentValue: from,
+		value: from,
 		velocity: 0
 	};
 	let runner;
 	const step = (deltaMs) => {
 		const completed = updateTween(state, deltaMs, durationMs, easeFn, from, to);
-		onUpdate(state.currentValue, state.velocity);
+		onUpdate(state.value, state.velocity);
 		onProgress(state.progress);
 		if (completed) onEnded();
 		return completed;
@@ -19,26 +19,26 @@ var createTweenRunner = ({ from, to, durationMs, easeFn, onStarted, onUpdate = n
 		const clamped = Math.max(0, Math.min(1, progress));
 		state.progress = clamped;
 		if (clamped >= 1) {
-			state.currentValue = to;
+			state.value = to;
 			state.velocity = 0;
 		} else {
 			const range = to - from;
-			state.currentValue = from + range * easeFn(clamped);
+			state.value = from + range * easeFn(clamped);
 			state.velocity = 0;
 		}
-		onUpdate(state.currentValue, state.velocity);
-		return state.currentValue;
+		onUpdate(state.value, state.velocity);
+		return state.value;
 	};
 	const reset = () => {
 		state.progress = 0;
-		state.currentValue = from;
+		state.value = from;
 		state.velocity = 0;
 	};
 	runner = step;
 	runner.evaluate = evaluate;
 	runner.reset = reset;
-	Object.defineProperty(runner, "currentValue", {
-		get: () => state.currentValue,
+	Object.defineProperty(runner, "value", {
+		get: () => state.value,
 		configurable: true
 	});
 	Object.defineProperty(runner, "velocity", {
@@ -71,7 +71,7 @@ var createKeyframeRunner = ({ keyframes, onStarted, onUpdate = noOp, onProgress
 	for (let i = 0; i < segments.length; i++) prefixSum.push(prefixSum[i] + segments[i].durationMs);
 	const totalDurationMs = prefixSum[prefixSum.length - 1];
 	const invTotalDuration = totalDurationMs > 0 ? 1 / totalDurationMs : 1;
-	let currentValue = keyframes[0].value;
+	let value = keyframes[0].value;
 	let velocity = 0;
 	let globalProgress = 0;
 	let currentSegmentIndex = 0;
@@ -83,22 +83,22 @@ var createKeyframeRunner = ({ keyframes, onStarted, onUpdate = noOp, onProgress
 		segmentElapsed += deltaMs;
 		segmentProgress += deltaMs / segment.durationMs;
 		if (segmentProgress >= 1) segmentProgress = 1;
-		const previousValue = currentValue;
+		const previousValue = value;
 		const eased = segment.easeFn(segmentProgress);
-		currentValue = segment.from + segment.range * eased;
+		value = segment.from + segment.range * eased;
 		if (segmentProgress >= 1) {
-			currentValue = segment.to;
+			value = segment.to;
 			velocity = 0;
-		} else velocity = (currentValue - previousValue) / (deltaMs / 1e3);
+		} else velocity = (value - previousValue) / (deltaMs / 1e3);
 		const elapsedTotal = prefixSum[currentSegmentIndex] + segmentElapsed;
 		globalProgress = Math.min(elapsedTotal * invTotalDuration, 1);
 		onProgress(globalProgress);
-		onUpdate(currentValue, velocity);
+		onUpdate(value, velocity);
 		if (segmentProgress >= 1) if (currentSegmentIndex < segments.length - 1) {
 			currentSegmentIndex++;
 			segmentElapsed = 0;
 			segmentProgress = 0;
-			currentValue = segments[currentSegmentIndex].from;
+			value = segments[currentSegmentIndex].from;
 			velocity = 0;
 			globalProgress = Math.min(prefixSum[currentSegmentIndex] * invTotalDuration, 1);
 			onProgress(globalProgress);
@@ -125,18 +125,18 @@ var createKeyframeRunner = ({ keyframes, onStarted, onUpdate = noOp, onProgress
 		const segProgress = segDuration > 0 ? (elapsed - segStart) / segDuration : 1;
 		const clampedSegProgress = Math.max(0, Math.min(1, segProgress));
 		const eased = segment.easeFn(clampedSegProgress);
-		currentValue = segment.from + segment.range * eased;
+		value = segment.from + segment.range * eased;
 		velocity = 0;
 		globalProgress = clamped;
 		currentSegmentIndex = segIdx;
 		segmentElapsed = elapsed - segStart;
 		segmentProgress = clampedSegProgress;
-		onUpdate(currentValue, velocity);
+		onUpdate(value, velocity);
 		onProgress(clamped);
-		return currentValue;
+		return value;
 	};
 	const reset = () => {
-		currentValue = keyframes[0].value;
+		value = keyframes[0].value;
 		velocity = 0;
 		globalProgress = 0;
 		currentSegmentIndex = 0;
@@ -146,8 +146,8 @@ var createKeyframeRunner = ({ keyframes, onStarted, onUpdate = noOp, onProgress
 	runner = update;
 	runner.evaluate = evaluate;
 	runner.reset = reset;
-	Object.defineProperty(runner, "currentValue", {
-		get: () => currentValue,
+	Object.defineProperty(runner, "value", {
+		get: () => value,
 		configurable: true
 	});
 	Object.defineProperty(runner, "velocity", {

package/dist/animation/update.d.ts

@@ -1,7 +1,7 @@
 import { EaseFunction } from '../domain';
 export type TweenState = {
     progress: number;
-    currentValue: number;
+    value: number;
     velocity: number;
 };
 /**

package/dist/animation/update.js

@@ -7,15 +7,15 @@
 var updateTween = (state, deltaMs, durationMs, easeFn, from, to) => {
 	const thisFrameProgress = deltaMs / durationMs;
 	state.progress = Math.min(state.progress + thisFrameProgress, 1);
-	const previousValue = state.currentValue;
+	const previousValue = state.value;
 	if (state.progress >= 1) {
-		state.currentValue = to;
+		state.value = to;
 		state.velocity = 0;
 		return true;
 	}
 	const eased = easeFn(state.progress);
-	state.currentValue = from + (to - from) * eased;
-	state.velocity = (state.currentValue - previousValue) / (deltaMs / 1e3);
+	state.value = from + (to - from) * eased;
+	state.velocity = (state.value - previousValue) / (deltaMs / 1e3);
 	return false;
 };
 //#endregion

package/dist/domain/animation.d.ts

@@ -1,40 +1,155 @@
 import { EaseFunction, EaseName } from './easing';
 import { DynamicValue } from './resolve-value';
-export type AnimationStatus = "playing" | "paused" | "stopped" | "dead";
+import { ExternalTicker } from './ticker';
+/**
+ * The status of an animation, which can be "playing", "paused", or "stopped".
+ * - "playing": The animation is currently running.
+ * - "paused": The animation is temporarily halted but can be resumed.
+ * - "stopped": The animation has finished or has been stopped and is available for garbage collection if no external references remain.
+ */
+export type AnimationStatus = "playing" | "paused" | "stopped";
+/**
+ * Options for creating a single tween animation, which interpolates between a starting and ending value over a specified duration with optional easing.
+ */
 export type SingleTweenOptions = {
+    /**
+     * The starting value of the animation. Can be a number or a function that returns a number.
+     */
     from: DynamicValue;
+    /**
+     * The ending value of the animation. Can be a number or a function that returns a number.
+     */
     to: DynamicValue;
+    /**
+     * The duration of the animation in milliseconds. Can be a number or a function that returns a number.
+     */
     durationMs: DynamicValue;
+    /**
+     * The easing function or name to use for the animation.
+     */
     ease?: EaseName | EaseFunction;
+    /**
+     * Callback fired when the animation starts.
+     */
     onStarted?: () => void;
+    /**
+     * Callback fired on each animation update with the current value and velocity.
+     */
     onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * Callback fired on each animation update with the current progress (0 to 1).
+     */
     onProgress?: (progress: number) => void;
+    /**
+     * Callback fired when the animation ends.
+     */
     onEnded?: () => void;
+    /**
+     * Optional external ticker to drive the animation.
+     */
+    ticker?: ExternalTicker;
 };
+/**
+ * Object for describing a single keyframe.
+ */
 export type Keyframe = {
+    /**
+     * The value of the keyframe. Can be a number or a function that returns a number.
+     */
     value: DynamicValue;
+    /**
+     * The easing function or name to use for the keyframe.
+     */
     ease?: EaseName | EaseFunction;
+    /**
+     * The gap before the keyframe in milliseconds. Can be a number or a function that returns a number.
+     */
     gap?: DynamicValue;
 };
+/**
+ * Options for creating a keyframe animation, which consists of multiple keyframes each with their own value, easing, and optional gap.
+ */
 export type KeyframeAnimationOptions = {
+    /**
+     * The keyframes for the animation. Each keyframe defines a value, optional easing, and optional gap in milliseconds.
+     */
     keyframes: Keyframe[];
+    /**
+     * Callback fired when the animation starts.
+     */
     onStarted?: () => void;
+    /**
+     * Callback fired on each animation update with the current value and velocity.
+     */
     onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * Callback fired on each animation update with the current progress (0 to 1).
+     */
     onProgress?: (progress: number) => void;
+    /**
+     * Callback fired when the animation ends.
+     */
     onEnded?: () => void;
+    /**
+     * Optional external ticker to drive the animation.
+     */
+    ticker?: ExternalTicker;
 };
+/**
+ * Options for creating an animation, which can be either a single tween or a keyframe animation type.
+ */
 export type AnimationOptions = SingleTweenOptions | KeyframeAnimationOptions;
+/**
+ * Represents an animation instance that can be controlled and queried for its state.
+ */
 export type Animation = {
+    /**
+     * Plays the animation from the current state and returns a promise that resolves when the animation ends.
+     */
     play: () => Promise<void>;
+    /**
+     * Pauses the animation if it is currently playing.
+     */
     pause: () => void;
+    /**
+     * Resumes the animation if it is currently paused.
+     */
     resume: () => void;
+    /**
+     * Stops the animation and resets its state.
+     */
     stop: () => void;
+    /**
+     * Skips the animation to its end state immediately.
+     */
     skipToEnd: () => void;
-    kill: () => void;
-    currentValue: number;
+    /**
+     * The current value of the animation.
+     */
+    value: number;
+    /**
+     * The current velocity of the animation.
+     */
     velocity: number;
+    /**
+     * The current progress of the animation, represented as a number between 0 and 1.
+     */
     progress: number;
+    /**
+     * Sets the progress of the animation to a specific value between 0 and 1. If the animation is playing, it will be paused.
+     */
     setProgress: (value: number) => void;
+    /**
+     * The current status of the animation, which can be "playing", "paused", or "stopped".
+     * - "playing": The animation is currently running.
+     * - "paused": The animation is temporarily halted but can be resumed.
+     * - "stopped": The animation has finished or has been stopped and is available for garbage collection if no external references remain.
+     */
     status: AnimationStatus;
+    /**
+     * The total duration of the animation in milliseconds. This value is determined by the animation's configuration and keyframes.
+     * For single tween animations, this is the specified duration. For keyframe animations, this is the sum of all keyframe gaps and durations.
+     * Note that if the animation has dynamic values for duration or gaps, this value may change when the animation is played and the dynamic values are read.
+     */
     durationMs: number;
 };

package/dist/domain/color.d.ts

@@ -1,2 +1,14 @@
+/**
+ * A tuple representing an RGBA color with each channel as a float in the range [0, 1].
+ * Ordered as [red, green, blue, alpha].
+ */
 export type RgbaTuple = readonly [number, number, number, number];
+/**
+ * A function that linearly interpolates between two RGBA colors in Oklab color space.
+ *
+ * @param from - The starting color as an RgbaTuple.
+ * @param to - The ending color as an RgbaTuple.
+ * @param progress - A number between 0 and 1 representing the interpolation progress.
+ * @returns The interpolated color as an RgbaTuple.
+ */
 export type LerpRgba = (from: RgbaTuple, to: RgbaTuple, progress: number) => RgbaTuple;

package/dist/domain/easing.d.ts

@@ -1,4 +1,16 @@
+/**
+ * A function that maps a progress value `t` in [0, 1] to an eased output value.
+ * Values outside [0, 1] may be returned for overshooting easings like elastic or back.
+ */
 export type EaseFunction = (t: number) => number;
+/**
+ * Resolves an easing identifier or function into a concrete {@link EaseFunction}.
+ * If a function is passed, it is returned as-is. If a name is passed, the
+ * corresponding built-in easing function is looked up.
+ *
+ * @param ease - An easing name or a custom easing function.
+ * @returns The resolved easing function.
+ */
 export declare const resolveEasing: (ease: EaseName | EaseFunction) => EaseFunction;
 /** All 31 named easing identifiers, ordered by type. */
 export declare const EASE_NAMES: readonly ["linear", "inQuad", "outQuad", "inOutQuad", "inCubic", "outCubic", "inOutCubic", "inQuart", "outQuart", "inOutQuart", "inQuint", "outQuint", "inOutQuint", "inSine", "outSine", "inOutSine", "inExpo", "outExpo", "inOutExpo", "inCirc", "outCirc", "inOutCirc", "inBack", "outBack", "inOutBack", "inElastic", "outElastic", "inOutElastic", "inBounce", "outBounce", "inOutBounce"];

package/dist/domain/easing.js

@@ -1,4 +1,12 @@
 //#region src/domain/easing.ts
+/**
+* Resolves an easing identifier or function into a concrete {@link EaseFunction}.
+* If a function is passed, it is returned as-is. If a name is passed, the
+* corresponding built-in easing function is looked up.
+*
+* @param ease - An easing name or a custom easing function.
+* @returns The resolved easing function.
+*/
 var resolveEasing = (ease) => typeof ease === "function" ? ease : EASING_FUNCTIONS[ease];
 var pow = Math.pow;
 var sqrt = Math.sqrt;

package/dist/domain/index.d.ts

@@ -2,9 +2,9 @@ export type { AnimationStatus } from './animation';
 export type { InterpolationStatus, Interpolation, LerpOptions, SmoothDampOptions, SpringOptions, } from './interpolation';
 export type { EaseName, EaseFunction } from './easing';
 export { EASE_NAMES, cubicBezier, EASING_FUNCTIONS, resolveEasing } from './easing';
-export type { Ticker, TickHandler } from './ticker';
+export type { Ticker, TickHandler, ExternalTicker } from './ticker';
 export { resolveValue } from './resolve-value';
 export type { DynamicValue } from './resolve-value';
 export type { Animation, AnimationOptions, SingleTweenOptions, KeyframeAnimationOptions, Keyframe, } from './animation';
-export type { TimelineLayer, Timeline } from './timeline';
+export type { TimelineLayer, Timeline, TimelineCallbacks } from './timeline';
 export type { RgbaTuple, LerpRgba } from './color';

package/dist/domain/interpolation.d.ts

@@ -1,35 +1,158 @@
 import { DynamicValue } from './resolve-value';
-export type InterpolationStatus = "active" | "inactive" | "dead";
+import { ExternalTicker } from './ticker';
+/**
+ * Represents the status of an interpolation, which can be either "active" or "inactive".
+ */
+export type InterpolationStatus = "active" | "inactive";
+/**
+ * Represents an interpolation process that can be controlled and monitored.
+ *
+ * The interpolation can be resumed or stopped, and its current value, velocity, and status can be accessed.
+ */
 export type Interpolation = {
-    start: () => void;
+    /**
+     * Resumes the interpolation if it is currently inactive.
+     */
+    resume: () => void;
+    /**
+     * Stops the interpolation if it is currently active.
+     */
     stop: () => void;
-    kill: () => void;
-    setCurrentValue: (value: number) => void;
-    currentValue: number;
+    /**
+     * Sets the current value of the interpolation instantly and resets its velocity to zero.
+     */
+    setValue: (value: number) => void;
+    /**
+     * The current value of the interpolation.
+     */
+    value: number;
+    /**
+     * The current velocity of the interpolation.
+     */
     velocity: number;
+    /**
+     * The current status of the interpolation, which can be "active" or "inactive".
+     */
     status: InterpolationStatus;
 };
+/**
+ * Options for configuring a linear interpolation (lerp) function.
+ */
 export type LerpOptions = {
+    /**
+     * A function that returns the starting value for the interpolation. This is evaluated every frame.
+     */
     to: () => number;
+    /**
+     * A function that returns the ending value for the interpolation. This is evaluated every frame if a function is provided.
+     */
     smoothTimeMs: DynamicValue;
+    /**
+     * The precision threshold for determining when the interpolation has effectively reached its target. Defaults to 0.01.
+     */
     precision?: number;
+    /**
+     * A callback function that is called on every update of the interpolation, receiving the current value and velocity as arguments.
+     */
     onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * A callback function that is called when the interpolation has effectively reached its target and is considered complete.
+     */
     onEnded?: () => void;
+    /**
+     * An optional external ticker that can be provided to control the timing of the interpolation updates. If not provided, a default ticker will be used.
+     */
+    ticker?: ExternalTicker;
 };
+/**
+ * Options for configuring a smooth damped interpolation.
+ *
+ * Smooth damp progressively moves toward a target value with velocity that
+ * decreases as it approaches, producing a natural deceleration effect.
+ */
 export type SmoothDampOptions = {
+    /**
+     * A function that returns the target value to smoothly move toward.
+     * This is evaluated every frame, allowing the target to change dynamically.
+     */
     to: () => number;
+    /**
+     * The approximate time (in milliseconds) it takes for the value to settle
+     * at the target. Larger values produce slower, more gradual movement.
+     */
     smoothTimeMs: DynamicValue;
+    /**
+     * An optional maximum speed cap (in units/second). Prevents excessively
+     * fast movement when the gap between current and target is large.
+     */
     maxSpeed?: DynamicValue;
+    /**
+     * The precision threshold for determining when the interpolation has
+     * effectively reached its target. Defaults to 0.01.
+     */
     precision?: number;
+    /**
+     * A callback function that is called on every update of the interpolation,
+     * receiving the current value and velocity as arguments.
+     */
     onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * A callback function that is called when the interpolation has effectively
+     * reached its target and is considered complete.
+     */
     onEnded?: () => void;
+    /**
+     * An optional external ticker that can be provided to control the timing of
+     * the interpolation updates. If not provided, a default ticker will be used.
+     */
+    ticker?: ExternalTicker;
 };
+/**
+ * Options for configuring a spring-based interpolation.
+ *
+ * Spring physics simulate mass-spring-damper motion, producing bouncy or
+ * elastic movement toward the target value.
+ */
 export type SpringOptions = {
+    /**
+     * A function that returns the target value toward which the spring pulls.
+     * This is evaluated every frame, allowing the target to change dynamically.
+     */
     to: () => number;
+    /**
+     * The stiffness of the spring. Higher values produce faster, snappier motion.
+     * Defaults to 180.
+     */
     stiffness?: DynamicValue;
+    /**
+     * The damping coefficient. Higher values reduce oscillation and settling time.
+     * Defaults to 12.
+     */
     damping?: DynamicValue;
+    /**
+     * The mass of the simulated object. Higher values produce slower, heavier
+     * motion. Defaults to 1.
+     */
     mass?: DynamicValue;
+    /**
+     * The precision threshold for determining when the spring has effectively
+     * settled at its target (both position and velocity within tolerance).
+     * Defaults to 0.01.
+     */
     precision?: number;
+    /**
+     * A callback function that is called on every update of the spring,
+     * receiving the current value and velocity as arguments.
+     */
     onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * A callback function that is called when the spring has effectively
+     * settled at its target and is considered complete.
+     */
     onEnded?: () => void;
+    /**
+     * An optional external ticker that can be provided to control the timing of
+     * the spring updates. If not provided, a default ticker will be used.
+     */
+    ticker?: ExternalTicker;
 };

package/dist/domain/resolve-value.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Represents a value that can either be a static number or a function
+ * that returns a number. Functions are re-evaluated each time the value
+ * is resolved, allowing dynamic values that change over time.
+ */
 export type DynamicValue = number | (() => number);
+/**
+ * Resolves a {@link DynamicValue} to a concrete number.
+ * If the value is a function, it is called and its return value is used.
+ * If the value is a number, it is returned directly.
+ *
+ * @param value - The dynamic value to resolve.
+ * @returns The resolved number.
+ */
 export declare const resolveValue: (value: DynamicValue) => number;

package/dist/domain/resolve-value.js

@@ -1,4 +1,12 @@
 //#region src/domain/resolve-value.ts
+/**
+* Resolves a {@link DynamicValue} to a concrete number.
+* If the value is a function, it is called and its return value is used.
+* If the value is a number, it is returned directly.
+*
+* @param value - The dynamic value to resolve.
+* @returns The resolved number.
+*/
 var resolveValue = (value) => typeof value === "function" ? value() : value;
 //#endregion
 export { resolveValue };

package/dist/domain/ticker.d.ts

@@ -1,8 +1,36 @@
+/**
+ * A function that is called on each tick with the elapsed time in milliseconds.
+ *
+ * @param deltaMs - The time elapsed since the last tick in milliseconds.
+ */
 export type TickHandler = (deltaMs: number) => void;
+/**
+ * A ticker that drives frame updates. It manages a list of {@link TickHandler}
+ * callbacks and distributes time updates to them on each frame.
+ */
 export type Ticker = {
+    /** Starts the ticker, beginning to dispatch updates to registered handlers. */
     start: () => void;
+    /** Stops the ticker, halting further dispatch of updates. */
     stop: () => void;
+    /**
+     * Manually advances the ticker by the given delta, dispatching to all
+     * registered handlers.
+     */
     update: (deltaMs: number) => void;
+    /** Registers a handler to receive tick updates. */
     add: (handler: TickHandler) => void;
+    /** Unregisters a previously registered handler. */
+    remove: (handler: TickHandler) => void;
+};
+/**
+ * A minimal ticker interface exposing only subscription capabilities.
+ * Useful for external tickers (e.g. from a game loop or an animation
+ * framework) where start/stop/update are managed externally.
+ */
+export type ExternalTicker = {
+    /** Registers a handler to receive tick updates. */
+    add: (handler: TickHandler) => void;
+    /** Unregisters a previously registered handler. */
     remove: (handler: TickHandler) => void;
 };

package/dist/domain/timeline.d.ts

@@ -1,5 +1,11 @@
-import { DynamicValue } from '../domain';
 import { KeyframeAnimationOptions, AnimationStatus } from './animation';
+import { DynamicValue } from './resolve-value';
+import { ExternalTicker } from './ticker';
+/**
+ * A single layer in a timeline, describing when an animation plays.
+ * - `at`: The animation starts at this absolute point in time (in ms).
+ * - `gap`: The animation starts this many ms after the previous layer ends.
+ */
 export type TimelineLayer = {
     animation: KeyframeAnimationOptions;
     at: DynamicValue;
@@ -7,15 +13,54 @@ export type TimelineLayer = {
     animation: KeyframeAnimationOptions;
     gap: number;
 };
+/**
+ * Callback hooks and options for a timeline animation.
+ */
+export type TimelineCallbacks = {
+    /** Callback fired when the timeline starts playing. */
+    onStarted?: () => void;
+    /**
+     * Callback fired on each update with the current values and velocities
+     * of all layers in the timeline.
+     */
+    onUpdate?: (values: number[], velocities: number[]) => void;
+    /** Callback fired on each update with the current progress (0 to 1). */
+    onProgress?: (progress: number) => void;
+    /** Callback fired when the timeline ends. */
+    onEnded?: () => void;
+    /** Optional external ticker to drive the timeline. */
+    ticker?: ExternalTicker;
+};
+/**
+ * Represents a timeline animation instance that sequences multiple layers
+ * and can be controlled and queried for its aggregate state.
+ */
 export type Timeline = {
+    /** Plays the timeline from the current state. Returns a promise that resolves when the timeline ends. */
     play: () => Promise<void>;
+    /** Pauses the timeline if it is currently playing. */
     pause: () => void;
+    /** Resumes the timeline if it is currently paused. */
     resume: () => void;
+    /** Stops the timeline and resets its state. */
     stop: () => void;
+    /** Skips the timeline to its end state immediately. */
     skipToEnd: () => void;
-    kill: () => void;
+    /** Sets the progress of the timeline to a specific value between 0 and 1. If playing, pauses. */
     setProgress: (value: number) => void;
+    /** The current progress of the timeline (0 to 1). */
     progress: number;
+    /**
+     * The current status of the timeline, which can be "playing", "paused", or "stopped".
+     * - "playing": The timeline is currently running.
+     * - "paused": The timeline is temporarily halted but can be resumed.
+     * - "stopped": The timeline has finished or has been stopped.
+     */
     status: AnimationStatus;
+    /** The total duration of the timeline in milliseconds. */
     durationMs: number;
+    /** The current values of all layers in the timeline. */
+    values: number[];
+    /** The current velocities of all layers in the timeline. */
+    velocities: number[];
 };