anim-engine 0.1.2 → 0.1.3

package/README.md

@@ -135,16 +135,15 @@ anim.skipToEnd(); // jumps to end, resolves promise
 
 **Single-tween options:**
 
-| Option       | Type                                         | Default     | Description                                                  |
-| ------------ | -------------------------------------------- | ----------- | ------------------------------------------------------------ |
-| `from`       | `number \| () => number`                     | —           | Start value (static or dynamic)                              |
-| `to`         | `number \| () => number`                     | —           | End value (static or dynamic)                                |
-| `durationMs` | `number`                                     | —           | Duration in milliseconds                                     |
-| `ease`       | `EaseName \| EaseFunction`                   | `"inOutSine"` | Easing function or name                                    |
-| `delayMs`    | `number`                                     | `0`         | Delay before starting                                        |
-| `onStarted`  | `() => void`                                | —           | Called when animation begins (after delay)                   |
-| `onUpdate`   | `(value: number, velocity: number) => void`  | —           | Called every frame with current value and velocity (units/s) |
-| `onEnded`    | `() => void`                                | —           | Called when animation completes                              |
+| Option       | Type                                         | Default       | Description                                                  |
+| ------------ | -------------------------------------------- | ------------- | ------------------------------------------------------------ |
+| `from`       | `number \| () => number`                     | —             | Start value (static or dynamic)                              |
+| `to`         | `number \| () => number`                     | —             | End value (static or dynamic)                                |
+| `durationMs` | `number \| () => number`                     | —             | Duration in milliseconds (static or dynamic)                 |
+| `ease`       | `EaseName \| EaseFunction`                   | `"inOutSine"`   | Easing function or name                                      |
+| `onStarted`  | `() => void`                                 | —             | Called when animation begins                                 |
+| `onUpdate`   | `(value: number, velocity: number) => void`  | —             | Called every frame with current value and velocity (units/s) |
+| `onEnded`    | `() => void`                                 | —             | Called when animation completes                              |
 **Returns:** `Animation`
 
 ### Keyframes
@@ -166,7 +165,7 @@ const anim = createAnimation({
 });
 ```
 
-Each keyframe's `at` is in milliseconds — the last keyframe's `at` sets the total duration (1000ms in this example). If no `ease` is specified, the previous segment's ease carries forward.
+Each keyframe's `at` is in milliseconds — the last keyframe's `at` sets the total duration (1000ms in this example). Both `at` and `value` accept `DynamicValue` for per-play resolution. If no `ease` is specified, the previous segment's ease carries forward.
 
 **Keyframe options:**
 
@@ -484,17 +483,46 @@ You can pass the result directly to any `ease` option — it's an `EaseFunction`
 
 ## Dynamic values
 
-All primitives accept `number | (() => number)` for value parameters. Use a function to update the target every frame without recreating the animation:
+The `DynamicValue` type (`number | (() => number)`) lets you provide values that are resolved at runtime. How often they're resolved depends on the primitive:
+
+### Timed animations (per-play)
+
+In `createAnimation` — tweens and keyframes — all dynamic values are resolved **once when `play()` is called** and cached for the duration of that run. The frame-hot update path reads from the cache with zero overhead:
+
+```ts
+const anim = createAnimation({
+  from: () => getLayoutStart(),
+  to: () => getLayoutEnd(),
+  durationMs: () => 500 / speedMultiplier,
+  keyframes: [
+    { at: 0, value: 0 },
+    { at: () => scrollHeight * 0.3, value: 50 },
+    { at: () => scrollHeight, value: 100 },
+  ],
+});
+
+// Values resolved here, cached for duration
+await anim.play();
+
+// On re-play, values are re-resolved
+await anim.play();
+```
+
+This means `from`, `to`, `durationMs`, `keyframe.at`, and `keyframe.value` are all evaluated at play time and remain stable throughout the animation. If you need truly per-frame dynamic values, that's the domain of continuous primitives.
+
+### Continuous primitives (per-frame)
+
+In `createSpring`, `createSmoothDamp`, and `createLerp`, dynamic values are resolved **every frame** — these primitives are designed to chase live targets:
 
 ```ts
 const spring = createSpring({
-  to: () => getMousePosition(), // starts at current mouse position // re-read every frame
-  stiffness: () => sliderValue, // dynamic stiffness
+  to: () => getMousePosition(), // re-read every frame
+  stiffness: () => sliderValue,  // dynamic stiffness
   damping: () => dampingValue,
 });
 ```
 
-The function is called every frame inside the ticker update — no getter/setter objects, no mutation of the returned controls.
+This distinction reflects the two use-cases: timed animations describe a fixed motion path evaluated at start, while continuous primitives describe ongoing behaviour that adapts to changing input.
 
 ## Benchmarks
 
@@ -626,7 +654,7 @@ requestAnimationFrame(gameLoop);
 | `AnimationStatus`    | `"playing" \| "paused" \| "stopped" \| "dead"` (for `Animation` / `Timeline`)                                           |
 | `InterpolationStatus` | `"active" \| "inactive" \| "dead"` (for `Interpolation`)                                           |
 | `AnimationOptions`   | Single tween or keyframe animation options (discriminated union)                                                         |
-| `Keyframe`           | `{ at, value, ease? }`                                                                                                  |
+| `Keyframe`           | `{ at: DynamicValue, value: DynamicValue, ease?: EaseName \| EaseFunction }`                                            |
 | `TimelineLayer`      | `{ at: number; animation: Animation \| Animation[] } \| { gap: number; animation: Animation \| Animation[] }`           |
 | `SpringOptions`      | `to`, `stiffness`, `damping`, `mass`, `precision?`, `onUpdate`, `onEnded`                                                  |
 | `SmoothDampOptions`  | `to`, `smoothTimeMs`, `maxSpeed?`, `precision?`, `onUpdate`, `onEnded`                                                                     |

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

@@ -2,15 +2,14 @@ import { Animation, DynamicValue, EaseFunction, EaseName } from '../shared/types
 export type SingleTweenOptions = {
     from: DynamicValue;
     to: DynamicValue;
-    durationMs: number;
+    durationMs: DynamicValue;
     ease?: EaseName | EaseFunction;
-    delayMs?: number;
     onStarted?: () => void;
     onUpdate?: (value: number, velocity: number) => void;
     onEnded?: () => void;
 };
 export type Keyframe = {
-    at: number;
+    at: DynamicValue;
     value: DynamicValue;
     ease?: EaseName | EaseFunction;
 };

package/dist/animation/create-animation.js

@@ -12,10 +12,13 @@ var createAnimation = (options) => {
 };
 var createSingleTween = (options) => {
 	const easeName = options.ease ?? "inOutSine";
-	const delayMs = options.delayMs ?? 0;
-	const { onStarted, onUpdate, onEnded, durationMs } = options;
-	let rawFrom = options.from;
-	let rawTo = options.to;
+	const { onStarted, onUpdate, onEnded } = options;
+	const rawFrom = options.from;
+	const rawTo = options.to;
+	const rawDurationMs = options.durationMs;
+	let cachedFrom = typeof rawFrom === "function" ? rawFrom() : rawFrom;
+	let cachedTo = typeof rawTo === "function" ? rawTo() : rawTo;
+	let cachedDurationMs = typeof rawDurationMs === "function" ? rawDurationMs() : rawDurationMs;
 	const state = {
 		progress: 0,
 		currentValue: 0,
@@ -24,21 +27,10 @@ var createSingleTween = (options) => {
 	let status = "stopped";
 	let stopped = false;
 	let resolvePromise;
-	let delayRemainingMs = 0;
-	let pendingStart = false;
 	const ticker = getTicker();
 	const update = (deltaMs) => {
 		if (stopped) return;
-		if (pendingStart) {
-			delayRemainingMs -= deltaMs;
-			if (delayRemainingMs > 0) return;
-			pendingStart = false;
-			onStarted?.();
-			deltaMs = -delayRemainingMs;
-		}
-		const from = typeof rawFrom === "function" ? rawFrom() : rawFrom;
-		const to = typeof rawTo === "function" ? rawTo() : rawTo;
-		const completed = updateTween(state, deltaMs, durationMs, currentEase, from, to);
+		const completed = updateTween(state, deltaMs, cachedDurationMs, currentEase, cachedFrom, cachedTo);
 		onUpdate?.(state.currentValue, state.velocity);
 		if (completed) handleCompletion();
 	};
@@ -47,22 +39,17 @@ var createSingleTween = (options) => {
 		if (status === "dead") throw new Error("Cannot play a dead animation");
 		stopped = false;
 		state.progress = 0;
-		const initFrom = typeof rawFrom === "function" ? rawFrom() : rawFrom;
-		state.currentValue = initFrom;
+		cachedFrom = typeof rawFrom === "function" ? rawFrom() : rawFrom;
+		cachedTo = typeof rawTo === "function" ? rawTo() : rawTo;
+		cachedDurationMs = typeof rawDurationMs === "function" ? rawDurationMs() : rawDurationMs;
+		state.currentValue = cachedFrom;
 		state.velocity = 0;
-		if (delayMs > 0) {
-			delayRemainingMs = delayMs;
-			pendingStart = true;
-		} else {
-			pendingStart = false;
-			delayRemainingMs = 0;
-		}
 		const promise = new Promise((resolve) => {
 			resolvePromise = resolve;
 		});
 		status = "playing";
 		ticker.add(update);
-		if (delayRemainingMs <= 0) onStarted?.();
+		onStarted?.();
 		return promise;
 	};
 	const pause = () => {
@@ -83,8 +70,7 @@ var createSingleTween = (options) => {
 		resolvePromise = void 0;
 	};
 	const skipToEnd = () => {
-		const skipTo = typeof rawTo === "function" ? rawTo() : rawTo;
-		state.currentValue = skipTo;
+		state.currentValue = cachedTo;
 		state.velocity = 0;
 		state.progress = 1;
 		onUpdate?.(state.currentValue, state.velocity);
@@ -131,9 +117,7 @@ var createSingleTween = (options) => {
 			if (status === "playing") pause();
 			const clamped = Math.max(0, Math.min(1, value));
 			state.progress = clamped;
-			const from = typeof rawFrom === "function" ? rawFrom() : rawFrom;
-			const to = typeof rawTo === "function" ? rawTo() : rawTo;
-			state.currentValue = from + (to - from) * currentEase(clamped);
+			state.currentValue = cachedFrom + (cachedTo - cachedFrom) * currentEase(clamped);
 			state.velocity = 0;
 			onUpdate?.(state.currentValue, state.velocity);
 		},
@@ -141,46 +125,57 @@ var createSingleTween = (options) => {
 			return status;
 		},
 		get durationMs() {
-			return durationMs;
+			return cachedDurationMs;
 		}
 	};
 	return controls;
 };
 var createKeyframeAnimation = (options) => {
-	const keyframes = options.keyframes;
+	const rawKeyframes = options.keyframes;
 	const onUpdate = options.onUpdate;
 	const onProgress = options.onProgress;
 	const onEnded = options.onEnded;
-	const sorted = [...keyframes].sort((a, b) => a.at - b.at);
-	const totalDurationMs = sorted[sorted.length - 1].at;
-	const invTotalDuration = 1 / totalDurationMs;
-	const resolveKeyframeValue = (kf) => {
-		return typeof kf.value === "function" ? kf.value() : kf.value;
+	const resolveKeyframeValue = (kf) => typeof kf.value === "function" ? kf.value() : kf.value;
+	const resolveKeyframeAt = (kf) => typeof kf.at === "function" ? kf.at() : kf.at;
+	let segments = [];
+	let prefixSum = [0];
+	let totalDurationMs = 0;
+	let invTotalDuration = 0;
+	const rebuild = () => {
+		const sorted = [...rawKeyframes].map((kf) => ({
+			...kf,
+			at: resolveKeyframeAt(kf)
+		})).sort((a, b) => a.at - b.at);
+		totalDurationMs = sorted[sorted.length - 1].at;
+		invTotalDuration = totalDurationMs > 0 ? 1 / totalDurationMs : 0;
+		segments = [];
+		for (let i = 0; i < sorted.length - 1; i++) {
+			const current = sorted[i];
+			const next = sorted[i + 1];
+			const from = resolveKeyframeValue(current);
+			const to = resolveKeyframeValue(next);
+			segments.push({
+				from,
+				to,
+				range: to - from,
+				durationMs: next.at - current.at,
+				easeFn: resolveEasing(next.ease ?? "inOutSine")
+			});
+		}
+		if (segments.length === 0) {
+			const v = resolveKeyframeValue(sorted[0]);
+			segments.push({
+				from: v,
+				to: v,
+				range: 0,
+				durationMs: totalDurationMs,
+				easeFn: resolveEasing("linear")
+			});
+		}
+		prefixSum = [0];
+		for (let i = 0; i < segments.length; i++) prefixSum.push(prefixSum[i] + segments[i].durationMs);
 	};
-	const segments = [];
-	for (let i = 0; i < sorted.length - 1; i++) {
-		const current = sorted[i];
-		const next = sorted[i + 1];
-		const from = resolveKeyframeValue(current);
-		const to = resolveKeyframeValue(next);
-		segments.push({
-			from,
-			to,
-			range: to - from,
-			durationMs: next.at - current.at,
-			easeFn: resolveEasing(next.ease ?? "inOutSine")
-		});
-	}
-	const prefixSum = [0];
-	for (let i = 0; i < segments.length; i++) prefixSum.push(prefixSum[i] + segments[i].durationMs);
-	if (segments.length === 0) return createSingleTween({
-		from: resolveKeyframeValue(sorted[0]),
-		to: resolveKeyframeValue(sorted[0]),
-		durationMs: totalDurationMs,
-		ease: "linear",
-		onUpdate,
-		onEnded
-	});
+	rebuild();
 	const state = {
 		progress: 0,
 		currentValue: 0,
@@ -190,7 +185,7 @@ var createKeyframeAnimation = (options) => {
 	let stopped = false;
 	let resolvePromise;
 	let currentSegmentIndex = 0;
-	let previousValue = resolveKeyframeValue(sorted[0]);
+	let previousValue = segments[0].from;
 	const ticker = getTicker();
 	const update = (deltaMs) => {
 		if (stopped) return;
@@ -230,6 +225,7 @@ var createKeyframeAnimation = (options) => {
 	let segmentElapsed = 0;
 	const play = () => {
 		if (status === "dead") throw new Error("Cannot play a dead animation");
+		rebuild();
 		stopped = false;
 		currentSegmentIndex = 0;
 		segmentElapsed = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anim-engine",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "description": "JavaScript library for animating numbers",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "prepublishOnly": "npm run build",
     "bench": "vitest bench src/benchmarks/ --run",
     "bench:baseline": "vitest bench src/benchmarks/ --run --outputJson baselines/benchmark.json",
+    "bench:compare": "vitest bench src/benchmarks/ --run --compare baselines/benchmark.json",
     "format": "oxfmt src/",
     "format:check": "oxfmt --check src/",
     "fmt": "oxfmt src/"