anim-engine 0.4.0 → 0.5.1

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,42 @@ 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 = [];
+	let valuesDirty = true;
+	const syncValues = () => {
+		if (!valuesDirty) return;
+		valuesDirty = false;
+		valuesCache.length = activeLayers.length;
+		velocitiesCache.length = activeLayers.length;
+		for (let i = 0; i < activeLayers.length; i++) {
+			valuesCache[i] = activeLayers[i].runner.value;
+			velocitiesCache[i] = activeLayers[i].runner.velocity;
+		}
+	};
 	let timelineStatus = "stopped";
 	let elapsedMs = 0;
 	let resolvePromise;
 	let remainingLayers = activeLayers.length;
-	const ticker = getTicker();
 	const finish = () => {
 		timelineStatus = "stopped";
 		ticker.remove(update);
@@ -71,15 +96,22 @@ var createTimeline = (layers, options) => {
 				}
 			}
 		}
+		valuesDirty = true;
+		if (onUpdate) {
+			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 +143,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 +164,7 @@ var createTimeline = (layers, options) => {
 			layer.runner.evaluate(localProgress);
 			layer.ended = localProgress >= 1;
 		}
+		syncValues();
 		remainingLayers = activeLayers.filter((l) => !l.ended).length;
 	};
 	return {
@@ -144,11 +173,18 @@ var createTimeline = (layers, options) => {
 		resume,
 		stop,
 		skipToEnd,
-		kill,
 		setProgress,
 		get progress() {
 			return totalDurationMs > 0 ? Math.min(elapsedMs / totalDurationMs, 1) : 1;
 		},
+		get values() {
+			syncValues();
+			return valuesCache;
+		},
+		get velocities() {
+			syncValues();
+			return velocitiesCache;
+		},
 		get status() {
 			return timelineStatus;
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anim-engine",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "private": false,
   "description": "JavaScript library for animating numbers",
   "license": "MIT",
@@ -11,7 +11,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE.txt"
+    "LICENSE.txt",
+    "SKILL.md"
   ],
   "type": "module",
   "sideEffects": false,