anim-engine 0.3.2 → 0.5.0

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

@@ -1,20 +1,43 @@
-import { getTicker } from "../domain/ticker.js";
 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/smooth-damp/index.d.ts

@@ -0,0 +1 @@
+export { createSmoothDamp } from './create-smooth-damp';

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

@@ -1,11 +1,13 @@
-import { Interpolation, DynamicValue } from '../domain';
-export type SpringOptions = {
-    to: () => number;
-    stiffness?: DynamicValue;
-    damping?: DynamicValue;
-    mass?: DynamicValue;
-    precision?: number;
-    onUpdate?: (value: number, velocity: number) => void;
-    onEnded?: () => void;
-};
-export declare const createSpring: (options: SpringOptions) => Interpolation;
+import { Interpolation, SpringOptions } from '../domain';
+/**
+ * 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

@@ -1,23 +1,26 @@
-import { getTicker } from "../domain/ticker.js";
 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/spring/index.d.ts

@@ -0,0 +1 @@
+export { createSpring } from './create-spring';

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

@@ -0,0 +1,25 @@
+import { Ticker } from '../domain';
+/**
+ * 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.
+ *
+ * Does NOT auto-start. The user must explicitly call either:
+ * - `start()` — begins a `requestAnimationFrame` loop
+ * - `update(deltaMs)` — drive manually from a game loop
+ *
+ * `add()` and `remove()` register/unregister animations without
+ * side effects on the rAF loop.
+ *
+ * Uses a flat array with undefined-tombstone removal for safe concurrent
+ * modification during iteration. Compacted after each frame.
+ */
+export declare const createTicker: () => Ticker;

package/dist/{domain/ticker.js → ticker/get-ticker.js}

@@ -1,6 +1,14 @@
-//#region src/domain/ticker.ts
+//#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/ticker/index.d.ts

@@ -0,0 +1 @@
+export { getTicker } from './get-ticker';

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

@@ -1,9 +1,9 @@
 import { resolveEasing } from "../domain/easing.js";
-import { getTicker } from "../domain/ticker.js";
 import { resolveValue } from "../domain/resolve-value.js";
+import { getTicker } from "../ticker/get-ticker.js";
 import { createKeyframeRunner } from "../animation/runner.js";
 //#region src/timeline/create-timeline.ts
-var noop = () => {};
+var noOp = () => {};
 var buildFromConfigs = (rawLayers) => {
 	const activeLayers = [];
 	let previousEndAt = 0;
@@ -38,18 +38,40 @@ var buildFromConfigs = (rawLayers) => {
 		totalDurationMs: Math.max(0, ...activeLayers.map((l) => l.endAt))
 	};
 };
-var createTimeline = (layers, options) => {
-	const { onStarted, onEnded } = options ?? {};
-	const onProgress = options?.onProgress ?? noop;
+/**
+* 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);
@@ -72,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;
@@ -112,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;
@@ -137,6 +159,7 @@ var createTimeline = (layers, options) => {
 			layer.runner.evaluate(localProgress);
 			layer.ended = localProgress >= 1;
 		}
+		syncValues();
 		remainingLayers = activeLayers.filter((l) => !l.ended).length;
 	};
 	return {
@@ -145,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/dist/timeline/index.d.ts

@@ -0,0 +1 @@
+export { createTimeline } from './create-timeline';

package/package.json

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

package/dist/color/lerp-oklab.d.ts

@@ -1,26 +0,0 @@
-export type RgbaTuple = readonly [number, number, number, number];
-/**
- * Interpolate between two RGBA colors in Oklab space.
- *
- * The RGB channels are converted to Oklab, lerped perceptually uniformly,
- * and converted back. The alpha channel is lerped linearly.
- *
- * @param from - Starting RGBA tuple [R, G, B, A], each 0–1.
- * @param to - Ending RGBA tuple [R, G, B, A], each 0–1.
- * @param progress - Interpolation factor (0 = from, 1 = to).
- * @returns A new RGBA tuple [R, G, B, A], each 0–1.
- */
-export declare const lerpOklab: (from: RgbaTuple, to: RgbaTuple, progress: number) => [number, number, number, number];
-/**
- * Parse a hex color string into an RGBA tuple.
- *
- * Accepts formats:
- *   - `#RGB`
- *   - `#RGBA`
- *   - `#RRGGBB`
- *   - `#RRGGBBAA`
- *
- * @param hex - Hex color string with optional leading `#`.
- * @returns An RGBA tuple [R, G, B, A], each 0–1.
- */
-export declare const hexToRgba: (hex: string) => [number, number, number, number];