anim-engine 0.4.0 → 0.5.0

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[];
 };

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export { createSpring } from './spring';
 export { lerpRgba, hexToRgba } from './lerp-rgba';
 export { getTicker } from './ticker';
 export { cubicBezier } from './domain';
-export type { EaseName, Interpolation, AnimationStatus, InterpolationStatus, DynamicValue, Animation, Keyframe, AnimationOptions, KeyframeAnimationOptions, TimelineLayer, Timeline, Ticker, LerpOptions, SmoothDampOptions, SpringOptions, RgbaTuple, } from './domain';
+export type { EaseName, Interpolation, AnimationStatus, InterpolationStatus, DynamicValue, Animation, Keyframe, AnimationOptions, KeyframeAnimationOptions, TimelineLayer, Timeline, Ticker, LerpOptions, SmoothDampOptions, SpringOptions, RgbaTuple, ExternalTicker, } from './domain';

package/dist/lerp/create-lerp.d.ts

@@ -1,2 +1,14 @@
 import { Interpolation, LerpOptions } from '../domain';
-export declare const createLerp: (options: LerpOptions) => Interpolation;
+/**
+ * Creates a linear interpolation that smoothly moves a value toward a
+ * target over a specified time constant. Uses exponential decay for a
+ * smooth, asymptotic approach.
+ *
+ * The interpolation automatically starts and runs until it reaches the
+ * target within the configured precision. The target is re-evaluated
+ * every frame, allowing it to change dynamically.
+ *
+ * @param options - Configuration options for the interpolation.
+ * @returns An {@link Interpolation} instance for controlling the lerp.
+ */
+export declare const createLerp: ({ precision, onUpdate, onEnded, to, smoothTimeMs: rawSmoothTimeMs, ticker, }: LerpOptions) => Interpolation;

package/dist/lerp/create-lerp.js

@@ -2,21 +2,29 @@ import { resolveValue } from "../domain/resolve-value.js";
 import { getTicker } from "../ticker/get-ticker.js";
 import { lerpStep } from "./step.js";
 //#region src/lerp/create-lerp.ts
-var createLerp = (options) => {
-	const precision = options.precision ?? .01;
-	const onUpdate = options.onUpdate;
-	const onEnded = options.onEnded;
+/**
+* Creates a linear interpolation that smoothly moves a value toward a
+* target over a specified time constant. Uses exponential decay for a
+* smooth, asymptotic approach.
+*
+* The interpolation automatically starts and runs until it reaches the
+* target within the configured precision. The target is re-evaluated
+* every frame, allowing it to change dynamically.
+*
+* @param options - Configuration options for the interpolation.
+* @returns An {@link Interpolation} instance for controlling the lerp.
+*/
+var createLerp = ({ precision = .01, onUpdate, onEnded, to, smoothTimeMs: rawSmoothTimeMs, ticker = getTicker() }) => {
 	const state = { current: 0 };
 	let previousValue = 0;
 	let currentVelocity = 0;
 	let active = true;
-	const ticker = getTicker();
-	state.current = options.to();
+	state.current = to();
 	previousValue = state.current;
 	const update = (deltaMs) => {
 		if (!active) return;
-		const target = options.to();
-		const smoothTimeMs = resolveValue(options.smoothTimeMs);
+		const target = to();
+		const smoothTimeMs = resolveValue(rawSmoothTimeMs);
 		lerpStep(state, target, smoothTimeMs, deltaMs);
 		currentVelocity = (state.current - previousValue) / (deltaMs / 1e3);
 		previousValue = state.current;
@@ -28,7 +36,7 @@ var createLerp = (options) => {
 		}
 	};
 	ticker.add(update);
-	const start = () => {
+	const resume = () => {
 		if (active) return;
 		active = true;
 		ticker.add(update);
@@ -37,20 +45,15 @@ var createLerp = (options) => {
 		active = false;
 		ticker.remove(update);
 	};
-	const kill = () => {
-		active = false;
-		ticker.remove(update);
-	};
 	return {
-		start,
+		resume,
 		stop,
-		kill,
-		setCurrentValue: (value) => {
+		setValue: (value) => {
 			state.current = value;
 			previousValue = value;
 			currentVelocity = 0;
 		},
-		get currentValue() {
+		get value() {
 			return state.current;
 		},
 		get velocity() {

package/dist/smooth-damp/create-smooth-damp.d.ts

@@ -1,2 +1,16 @@
 import { Interpolation, SmoothDampOptions } from '../domain';
-export declare const createSmoothDamp: (options: SmoothDampOptions) => Interpolation;
+/**
+ * Creates a smooth damped interpolation that progressively moves a value
+ * toward a target with velocity that decreases as it approaches, producing
+ * a natural deceleration effect.
+ *
+ * Unlike a simple lerp, smooth damp respects an optional max speed and
+ * maintains velocity continuity, making it suitable for camera-relative
+ * movement, UI animations, and game object tracking.
+ *
+ * The target is re-evaluated every frame, allowing it to change dynamically.
+ *
+ * @param options - Configuration options for the smooth damp interpolation.
+ * @returns An {@link Interpolation} instance for controlling the smooth damp.
+ */
+export declare const createSmoothDamp: ({ to, smoothTimeMs: rawSmoothTimeMs, maxSpeed: rawMaxSpeed, precision, onUpdate, onEnded, ticker, }: SmoothDampOptions) => Interpolation;

package/dist/smooth-damp/create-smooth-damp.js

@@ -2,19 +2,42 @@ import { resolveValue } from "../domain/resolve-value.js";
 import { getTicker } from "../ticker/get-ticker.js";
 import { smoothDampStep } from "./step.js";
 //#region src/smooth-damp/create-smooth-damp.ts
-var createSmoothDamp = (options) => {
-	const precision = options.precision ?? .01;
-	const onUpdate = options.onUpdate;
-	const onEnded = options.onEnded;
+/**
+* Creates a smooth damped interpolation that progressively moves a value
+* toward a target with velocity that decreases as it approaches, producing
+* a natural deceleration effect.
+*
+* Unlike a simple lerp, smooth damp respects an optional max speed and
+* maintains velocity continuity, making it suitable for camera-relative
+* movement, UI animations, and game object tracking.
+*
+* The target is re-evaluated every frame, allowing it to change dynamically.
+*
+* @param options - Configuration options for the smooth damp interpolation.
+* @returns An {@link Interpolation} instance for controlling the smooth damp.
+*/
+var createSmoothDamp = ({ to, smoothTimeMs: rawSmoothTimeMs, maxSpeed: rawMaxSpeed, precision = .01, onUpdate, onEnded, ticker = getTicker() }) => {
 	const state = {
 		current: 0,
 		velocity: 0
 	};
 	let active = true;
-	const ticker = getTicker();
-	state.current = options.to();
+	state.current = to();
+	const update = (deltaMs) => {
+		if (!active) return;
+		const target = to();
+		const smoothTimeMs = resolveValue(rawSmoothTimeMs);
+		const maxSpeed = rawMaxSpeed !== void 0 ? resolveValue(rawMaxSpeed) : Infinity;
+		smoothDampStep(state, target, smoothTimeMs, maxSpeed, deltaMs);
+		onUpdate?.(state.current, state.velocity);
+		if (onEnded && Math.abs(state.current - target) < precision && Math.abs(state.velocity) < precision) {
+			state.current = target;
+			state.velocity = 0;
+			onEnded();
+		}
+	};
 	ticker.add(update);
-	const start = () => {
+	const resume = () => {
 		if (active) return;
 		active = true;
 		ticker.add(update);
@@ -23,32 +46,14 @@ var createSmoothDamp = (options) => {
 		active = false;
 		ticker.remove(update);
 	};
-	const kill = () => {
-		active = false;
-		ticker.remove(update);
-	};
-	function update(deltaMs) {
-		if (!active) return;
-		const target = options.to();
-		const smoothTimeMs = resolveValue(options.smoothTimeMs);
-		const maxSpeed = options.maxSpeed !== void 0 ? resolveValue(options.maxSpeed) : Infinity;
-		smoothDampStep(state, target, smoothTimeMs, maxSpeed, deltaMs);
-		onUpdate?.(state.current, state.velocity);
-		if (onEnded && Math.abs(state.current - target) < precision && Math.abs(state.velocity) < precision) {
-			state.current = target;
-			state.velocity = 0;
-			onEnded();
-		}
-	}
 	return {
-		start,
+		resume,
 		stop,
-		kill,
-		setCurrentValue: (value) => {
+		setValue: (value) => {
 			state.current = value;
 			state.velocity = 0;
 		},
-		get currentValue() {
+		get value() {
 			return state.current;
 		},
 		get velocity() {

package/dist/spring/create-spring.d.ts

@@ -1,2 +1,13 @@
 import { Interpolation, SpringOptions } from '../domain';
-export declare const createSpring: (options: SpringOptions) => Interpolation;
+/**
+ * Creates a spring-based interpolation that simulates mass-spring-damper
+ * physics, producing bouncy or elastic movement toward the target value.
+ *
+ * Uses Verlet integration for stable, energy-conserving simulation.
+ * Higher stiffness produces faster, snappier motion; higher damping
+ * reduces oscillation. The target is re-evaluated every frame.
+ *
+ * @param options - Configuration options for the spring interpolation.
+ * @returns An {@link Interpolation} instance for controlling the spring.
+ */
+export declare const createSpring: ({ precision, onUpdate, onEnded, to: rawTo, stiffness: rawStiffness, damping: rawDamping, mass: rawMass, ticker, }: SpringOptions) => Interpolation;

package/dist/spring/create-spring.js

@@ -2,22 +2,25 @@ import { resolveValue } from "../domain/resolve-value.js";
 import { getTicker } from "../ticker/get-ticker.js";
 import { verletStep } from "./verlet.js";
 //#region src/spring/create-spring.ts
-var createSpring = (options) => {
-	const precision = options.precision ?? .01;
-	const onUpdate = options.onUpdate;
-	const onEnded = options.onEnded;
-	const rawTo = options.to;
-	const rawStiffness = options.stiffness ?? 180;
-	const rawDamping = options.damping ?? 12;
-	const rawMass = options.mass ?? 1;
+/**
+* Creates a spring-based interpolation that simulates mass-spring-damper
+* physics, producing bouncy or elastic movement toward the target value.
+*
+* Uses Verlet integration for stable, energy-conserving simulation.
+* Higher stiffness produces faster, snappier motion; higher damping
+* reduces oscillation. The target is re-evaluated every frame.
+*
+* @param options - Configuration options for the spring interpolation.
+* @returns An {@link Interpolation} instance for controlling the spring.
+*/
+var createSpring = ({ precision = .01, onUpdate, onEnded, to: rawTo, stiffness: rawStiffness = 180, damping: rawDamping = 12, mass: rawMass = 1, ticker = getTicker() }) => {
 	const state = {
 		current: rawTo(),
 		velocity: 0
 	};
 	let active = true;
-	const ticker = getTicker();
 	ticker.add(update);
-	const start = () => {
+	const resume = () => {
 		if (active) return;
 		active = true;
 		ticker.add(update);
@@ -26,10 +29,6 @@ var createSpring = (options) => {
 		active = false;
 		ticker.remove(update);
 	};
-	const kill = () => {
-		active = false;
-		ticker.remove(update);
-	};
 	function update(deltaMs) {
 		if (!active) return;
 		const target = rawTo();
@@ -45,14 +44,13 @@ var createSpring = (options) => {
 		}
 	}
 	return {
-		start,
+		resume,
 		stop,
-		kill,
-		setCurrentValue: (value) => {
+		setValue: (value) => {
 			state.current = value;
 			state.velocity = 0;
 		},
-		get currentValue() {
+		get value() {
 			return state.current;
 		},
 		get velocity() {

package/dist/ticker/get-ticker.d.ts

@@ -1,5 +1,13 @@
 import { Ticker } from '../domain';
-/** Returns the default ticker singleton. Created lazily on first access. */
+/**
+ * Returns the application-wide default ticker singleton.
+ *
+ * The ticker is created lazily on first access and reused for all
+ * subsequent calls. It drives all animations and interpolations that
+ * don't specify an external ticker.
+ *
+ * @returns The default {@link Ticker} instance.
+ */
 export declare const getTicker: () => Ticker;
 /**
  * Create a ticker that drives active animations.

package/dist/ticker/get-ticker.js

@@ -1,6 +1,14 @@
 //#region src/ticker/get-ticker.ts
 var singleton;
-/** Returns the default ticker singleton. Created lazily on first access. */
+/**
+* Returns the application-wide default ticker singleton.
+*
+* The ticker is created lazily on first access and reused for all
+* subsequent calls. It drives all animations and interpolations that
+* don't specify an external ticker.
+*
+* @returns The default {@link Ticker} instance.
+*/
 var getTicker = () => {
 	if (!singleton) singleton = createTicker();
 	return singleton;

package/dist/timeline/create-timeline.d.ts

@@ -1,6 +1,16 @@
-import { TimelineLayer, Timeline } from '../domain';
-export declare const createTimeline: (layers: TimelineLayer[], options?: {
-    onStarted?: () => void;
-    onProgress?: (progress: number) => void;
-    onEnded?: () => void;
-}) => Timeline;
+import { TimelineLayer, Timeline, TimelineCallbacks, ExternalTicker } from '../domain';
+/**
+ * Creates a timeline animation that sequences multiple keyframe animation
+ * layers, each starting at a specified time or gap after the previous layer.
+ *
+ * The timeline aggregates all layers into a single controllable animation
+ * with its own play/pause/resume/stop semantics and returns the combined
+ * values and velocities of all layers on each update.
+ *
+ * @param layers - An array of {@link TimelineLayer} configs describing each
+ *   animation in the sequence and when it should play.
+ * @param callbacks - Optional callback hooks and configuration.
+ * @param ticker - An optional external ticker. Defaults to the global ticker.
+ * @returns A {@link Timeline} instance for controlling the sequenced animation.
+ */
+export declare const createTimeline: (layers: TimelineLayer[], { onStarted, onUpdate, onEnded, onProgress }?: TimelineCallbacks, ticker?: ExternalTicker) => Timeline;

package/dist/timeline/create-timeline.js

@@ -38,17 +38,40 @@ var buildFromConfigs = (rawLayers) => {
 		totalDurationMs: Math.max(0, ...activeLayers.map((l) => l.endAt))
 	};
 };
-var createTimeline = (layers, options) => {
-	const { onStarted, onEnded, onProgress = noOp } = options ?? {};
+/**
+* Creates a timeline animation that sequences multiple keyframe animation
+* layers, each starting at a specified time or gap after the previous layer.
+*
+* The timeline aggregates all layers into a single controllable animation
+* with its own play/pause/resume/stop semantics and returns the combined
+* values and velocities of all layers on each update.
+*
+* @param layers - An array of {@link TimelineLayer} configs describing each
+*   animation in the sequence and when it should play.
+* @param callbacks - Optional callback hooks and configuration.
+* @param ticker - An optional external ticker. Defaults to the global ticker.
+* @returns A {@link Timeline} instance for controlling the sequenced animation.
+*/
+var createTimeline = (layers, { onStarted, onUpdate, onEnded, onProgress = noOp } = {}, ticker = getTicker()) => {
 	const rawLayers = layers;
 	let state = buildFromConfigs(rawLayers);
 	let activeLayers = state.activeLayers;
 	let totalDurationMs = state.totalDurationMs;
+	let valuesCache = [];
+	let velocitiesCache = [];
+	const syncValues = () => {
+		valuesCache.length = activeLayers.length;
+		velocitiesCache.length = activeLayers.length;
+		for (let i = 0; i < activeLayers.length; i++) {
+			valuesCache[i] = activeLayers[i].runner.velocity;
+			velocitiesCache[i] = activeLayers[i].runner.velocity;
+		}
+	};
+	syncValues();
 	let timelineStatus = "stopped";
 	let elapsedMs = 0;
 	let resolvePromise;
 	let remainingLayers = activeLayers.length;
-	const ticker = getTicker();
 	const finish = () => {
 		timelineStatus = "stopped";
 		ticker.remove(update);
@@ -71,15 +94,19 @@ var createTimeline = (layers, options) => {
 				}
 			}
 		}
+		syncValues();
+		onUpdate?.(valuesCache, velocitiesCache);
 		onProgress(totalDurationMs > 0 ? Math.min(elapsedMs / totalDurationMs, 1) : 1);
 		if (remainingLayers <= 0) finish();
 	};
 	const play = () => {
-		if (timelineStatus === "dead") throw new Error("Cannot play a dead timeline");
 		state = buildFromConfigs(rawLayers);
 		activeLayers = state.activeLayers;
 		totalDurationMs = state.totalDurationMs;
 		remainingLayers = activeLayers.length;
+		valuesCache = [];
+		velocitiesCache = [];
+		syncValues();
 		elapsedMs = 0;
 		const promise = new Promise((resolve) => {
 			resolvePromise = resolve;
@@ -111,17 +138,13 @@ var createTimeline = (layers, options) => {
 			layer.runner.evaluate(1);
 			layer.runner.onEnded?.();
 		}
+		syncValues();
 		timelineStatus = "stopped";
 		ticker.remove(update);
 		onEnded?.();
 		resolvePromise?.();
 		resolvePromise = void 0;
 	};
-	const kill = () => {
-		timelineStatus = "dead";
-		ticker.remove(update);
-		resolvePromise = void 0;
-	};
 	const setProgress = (value) => {
 		if (timelineStatus === "playing") pause();
 		elapsedMs = Math.max(0, Math.min(1, value)) * totalDurationMs;
@@ -136,6 +159,7 @@ var createTimeline = (layers, options) => {
 			layer.runner.evaluate(localProgress);
 			layer.ended = localProgress >= 1;
 		}
+		syncValues();
 		remainingLayers = activeLayers.filter((l) => !l.ended).length;
 	};
 	return {
@@ -144,11 +168,16 @@ var createTimeline = (layers, options) => {
 		resume,
 		stop,
 		skipToEnd,
-		kill,
 		setProgress,
 		get progress() {
 			return totalDurationMs > 0 ? Math.min(elapsedMs / totalDurationMs, 1) : 1;
 		},
+		get values() {
+			return valuesCache;
+		},
+		get velocities() {
+			return velocitiesCache;
+		},
 		get status() {
 			return timelineStatus;
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anim-engine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "JavaScript library for animating numbers",
   "license": "MIT",