anim-engine 0.1.3 → 0.3.0

package/README.md

@@ -1,4 +1,13 @@
-# anim-engine
+<h1 align="center">anim-engine</h1>
+
+<div align="center">
+
+[![NPM Version](https://img.shields.io/npm/v/anim-engine.svg)](https://www.npmjs.com/package/anim-engine)
+[![License](https://img.shields.io/npm/l/anim-engine.svg)](https://github.com/LukeCarlThompson/anim-engine/blob/main/packages/anim-engine/LICENSE)
+[![CI](https://github.com/LukeCarlThompson/anim-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/LukeCarlThompson/anim-engine/actions)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue)](https://www.typescriptlang.org/)
+
+</div>
 
 **Renderer-agnostic animation for JavaScript runtimes.** A fast, lightweight, pure-numeric animation engine.
 
@@ -33,7 +42,7 @@ ESM only. Tree-shakeable — import only what you use.
 ```ts
 import { createAnimation, getTicker } from "anim-engine";
 
-// The ticker drives all animations. Start it once.
+// The ticker drives all animations. Start it once or drive it with an external ticker.
 getTicker().start();
 
 const anim = createAnimation({
@@ -63,28 +72,28 @@ By restricting itself to numeric values, the engine eliminates string parsing, c
 
 ## Key advantages
 
-|                              |                                                                                                                |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| ⚡ **Fast**                  | 1.7–9.9× faster than GSAP across tweens, keyframes, and concurrent animations (see [benchmarks](#benchmarks)). |
-| 🪶 **Lightweight**           | Tree-shakeable ESM — import only what you use. No DOM, no canvas, no dependencies.                             |
-| 🎯 **Numbers only**          | A single numeric type for all values. No strings, no transforms, no branches. Predictable performance.         |
-| 🔌 **Renderer-agnostic**     | Feed values to PixiJS, ThreeJS, DOM, canvas2d, or WebGL. Same API everywhere.                                  |
-| 🧩 **Composable models**     | Animations, keyframes, and timelines compose cleanly — put tweens inside timelines, nest keyframes anywhere.   |
-| 🔄 **Continuous primitives** | Spring, smooth damp, and lerp chase live targets with zero setup — pass `() => value` for dynamic targets.     |
-| 🚫 **No GC pressure**        | Zero object allocations in hot update paths. State is mutated in place.                                        |
-| 🎨 **Perceptual color**      | Oklab interpolation via `lerpOklab` — no muddy browns. Compose it into any `onUpdate`.                         |
-| 📐 **TypeScript-first**      | Full type exports, exhaustive discriminated unions, no `any`.                                                  |
-| 🔧 **Ticker control**        | Bring your own game loop or use the built-in rAF ticker. Explicit — never auto-starts.                         |
+|                              |                                                                                                                                     |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| ⚡ **Fast**                  | 1.7–7.5× faster than GSAP overall; 3.0–6.2× when comparing equivalent `onUpdate` callback dispatch (see [benchmarks](#benchmarks)). |
+| 🪶 **Lightweight**           | Tree-shakeable ESM — import only what you use. No DOM, no canvas, no dependencies.                                                  |
+| 🎯 **Numbers only**          | A single numeric type for all values. No strings, no transforms, no branches. Predictable performance.                              |
+| 🔌 **Renderer-agnostic**     | Feed values to PixiJS, ThreeJS, DOM, canvas2d, or WebGL. Same API everywhere.                                                       |
+| 🧩 **Composable models**     | Animations, keyframes, and timelines compose cleanly — put tweens inside timelines, nest keyframes anywhere.                        |
+| 🔄 **Continuous primitives** | Spring, smooth damp, and lerp chase live targets with zero setup — pass `() => value` for dynamic targets.                          |
+| 🚫 **No GC pressure**        | Zero object allocations in hot update paths. State is mutated in place.                                                             |
+| 🎨 **Perceptual color**      | Oklab interpolation via `lerpOklab` — no muddy browns. Compose it into any `onUpdate`.                                              |
+| 📐 **TypeScript-first**      | Full type exports, exhaustive discriminated unions, no `any`.                                                                       |
+| 🔧 **Ticker control**        | Bring your own game loop or use the built-in rAF ticker. Explicit — never auto-starts.                                              |
 
 ## Primitives
 
 ### Timed (return `Animation`)
 
-| Primitive                                   | Returns      | Description                                              |
-| ------------------------------------------- | ------------ | -------------------------------------------------------- |
-| [`createAnimation`](#createanimation)       | `Animation`  | Timed tween from A to B with easing and delay |
-| [`createAnimation` (keyframes)](#keyframes) | `Animation`  | Multi-segment interpolation with per-segment easing      |
-| [`createTimeline`](#createtimeline)         | `Timeline`   | Orchestrate multiple animations on a shared timeline     |
+| Primitive                                   | Returns     | Description                                          |
+| ------------------------------------------- | ----------- | ---------------------------------------------------- |
+| [`createAnimation`](#createanimation)       | `Animation` | Timed tween from A to B with easing and delay        |
+| [`createAnimation` (keyframes)](#keyframes) | `Animation` | Multi-segment interpolation with per-segment easing  |
+| [`createTimeline`](#createtimeline)         | `Timeline`  | Orchestrate multiple animations on a shared timeline |
 
 Animations have `play()`/`pause()`/`resume()`/`stop()`/`skipToEnd()`/`kill()` controls, return a `Promise` from `play()`, and emit `onUpdate`/`onEnded`/`onProgress` callbacks.
 
@@ -135,46 +144,48 @@ 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 \| () => 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                              |
+| Option       | Type                                        | Default       | Description                                                  |
+| ------------ | ------------------------------------------- | ------------- | ------------------------------------------------------------ |
+| `from`       | `number \| () => number`                    | —             | Start value                                                  |
+| `to`         | `number \| () => number`                    | —             | End value                                                    |
+| `durationMs` | `number \| () => number`                    | —             | Duration in milliseconds                                     |
+| `ease`       | `EaseName \| EaseFunction`                  | `"inOutSine"` | Easing function or name                                      |
+| `onStarted`  | `() => void`                                | —             | Called when playback 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
 
-Multi-segment animation with per-keyframe easing. The last keyframe's `at` value determines total duration. Mutually exclusive with `from`/`to`/`durationMs`.
+Multi-segment animation with per-keyframe easing. The first keyframe is the starting point (no gap/ease). Each subsequent keyframe specifies the gap from the previous one and an optional easing. Total duration is the sum of all gaps.
 
 ```ts
 import { createAnimation } from "anim-engine";
 
 const anim = createAnimation({
   keyframes: [
-    { at: 0, value: 0 },
-    { at: 300, value: 50, ease: "outCubic" },
-    { at: 700, value: 80, ease: "inOutQuad" },
-    { at: 1000, value: 100 },
+    { value: 0 },
+    { value: 50, gap: 300, ease: "outCubic" },
+    { value: 80, gap: 400, ease: "inOutQuad" },
+    { value: 100, gap: 300 },
   ],
   onUpdate: (value) => (sprite.x = value),
   onProgress: (progress) => console.log(`${Math.round(progress * 100)}%`),
 });
 ```
 
-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.
+Each keyframe's `gap` is in milliseconds from the previous keyframe. Total duration is the sum of all gaps (1000ms in this example). If no `ease` is specified on a keyframe, `"inOutSine"` is used as the default.
 
 **Keyframe options:**
 
-| Option       | Type                                        | Description                                               |
-| ------------ | ------------------------------------------- | --------------------------------------------------------- |
-| `keyframes`  | `Keyframe[]`                                | Array of `{ at, value, ease? }` keyframes                 |
-| `onUpdate`   | `(value: number, velocity: number) => void` | Called every frame with current value and velocity        |
-| `onProgress` | `(progress: number) => void`                | Called every frame with 0–1 global progress               |
-| `onEnded`    | `() => void`                               | Called when the keyframe animation completes              |
+| Option       | Type                                        | Description                                        |
+| ------------ | ------------------------------------------- | -------------------------------------------------- |
+| `keyframes`  | `Keyframe[]`                                | Array of `{ value, gap?, ease? }` keyframes        |
+| `onStarted`  | `() => void`                                | Called when playback begins                        |
+| `onUpdate`   | `(value: number, velocity: number) => void` | Called every frame with current value and velocity |
+| `onProgress` | `(progress: number) => void`                | Called every frame with 0–1 global progress        |
+| `onEnded`    | `() => void`                                | Called when the keyframe animation completes       |
 
 **Returns:** `Animation`
 
@@ -217,45 +228,38 @@ for (let i = 0; i < 6; i++) {
 For more complex sequences, use `createTimeline`:
 
 ```ts
-import { createAnimation, createTimeline } from "anim-engine";
-
-const fadeIn = createAnimation({ from: 0, to: 1, durationMs: 300 });
-const fadeOut = createAnimation({ from: 1, to: 0, durationMs: 300 });
+import { createTimeline } from "anim-engine";
 
 const flash = createTimeline([
-  { at: 0, animation: fadeIn },
-  { gap: 0, animation: fadeOut },
+  { at: 0, animation: { keyframes: [{ value: 0 }, { value: 1, gap: 300 }] } },
+  { gap: 0, animation: { keyframes: [{ value: 1 }, { value: 0, gap: 300 }] } },
 ]);
 await flash.play();
 ```
 
-
 ### createTimeline
 
-Compose multiple animations on a shared timeline with `at` or `gap` positions.
+Compose multiple keyframe animations on a shared timeline with `at` or `gap` positions. Parallelism comes from multiple layers at the same `at`.
 
 ```ts
-import { createAnimation, createTimeline } from "anim-engine";
-
-const fadeIn = createAnimation({
-  from: 0,
-  to: 1,
-  durationMs: 500,
-  onUpdate: (v) => (sprite.alpha = v),
-});
-
-const slideIn = createAnimation({
-  from: -100,
-  to: 0,
-  durationMs: 800,
-  ease: "outBack",
-  onUpdate: (v) => (sprite.x = v),
-});
+import { createTimeline } from "anim-engine";
 
 const timeline = createTimeline(
   [
-    { at: 0, animation: [fadeIn, slideIn] },
-    { gap: 200, animation: slideIn },
+    {
+      at: 0,
+      animation: {
+        keyframes: [{ value: 0 }, { value: 1, gap: 500 }],
+        onUpdate: (v) => (sprite.alpha = v),
+      },
+    },
+    {
+      at: 0,
+      animation: {
+        keyframes: [{ value: -100 }, { value: 0, gap: 800, ease: "outBack" }],
+        onUpdate: (v) => (sprite.x = v),
+      },
+    },
   ],
   {
     onProgress: (progress) => console.log(`overall: ${progress}`),
@@ -269,8 +273,8 @@ timeline.play();
 
 ```ts
 type TimelineLayer =
-  | { at: number; animation: Animation | Animation[] }
-  | { gap: number; animation: Animation | Animation[] };
+  | { animation: KeyframedAnimationOptions; at: DynamicValue }
+  | { animation: KeyframedAnimationOptions; gap: number };
 ```
 
 | Parameter            | Type                 | Description                                                    |
@@ -280,7 +284,7 @@ type TimelineLayer =
 | `options.onProgress` | `(progress) => void` | Called every frame with overall 0–1 progress                   |
 | `options.onEnded`    | `() => void`         | Called when timeline finishes                                  |
 
-`gap` is relative to the end of all animations in the previous layer. Pass a single `Animation` or an array for parallel animations within the layer.
+`gap` is relative to the end of the previous layer. Use multiple layers at the same `at` for parallel animations. A simple tween is expressed as a 2-keyframe sequence: `{ value: from }, { value: to, gap: durationMs }`.
 
 ### Continuous primitives
 
@@ -379,8 +383,8 @@ Perceptually uniform Oklab interpolation. Straight RGB lerp produces muddy trans
 ```ts
 import { lerpOklab, hexToRgba } from "anim-engine";
 
-hexToRgba("#ff6b6b");  // → [1, 0.42, 0.42, 1]
-hexToRgba("#f80");      // → [1, 0.533, 0, 1] (shorthand)
+hexToRgba("#ff6b6b"); // → [1, 0.42, 0.42, 1]
+hexToRgba("#f80"); // → [1, 0.533, 0, 1] (shorthand)
 hexToRgba("#ff804080"); // → [1, 0.502, 0.251, 0.502] (with alpha)
 
 const fromColor = hexToRgba("#ff6b6b");
@@ -517,7 +521,7 @@ In `createSpring`, `createSmoothDamp`, and `createLerp`, dynamic values are reso
 ```ts
 const spring = createSpring({
   to: () => getMousePosition(), // re-read every frame
-  stiffness: () => sliderValue,  // dynamic stiffness
+  stiffness: () => sliderValue, // dynamic stiffness
   damping: () => dampingValue,
 });
 ```
@@ -526,18 +530,34 @@ This distinction reflects the two use-cases: timed animations describe a fixed m
 
 ## Benchmarks
 
-Performance comparison against GSAP (vitest bench, Apple Silicon M-series, Node 24).
+Performance comparison against GSAP (vitest bench, Apple Silicon M-series, Node 24). All easing functions are matched between libraries.
+
+### vs GSAP internal mutation
+
+GSAP defaults to mutating target properties directly. This is faster than dispatching callbacks but couples GSAP to the mutation pattern. Anim-engine always dispatches via `onUpdate` (renderer-agnostic).
+
+| Benchmark                                     | anim-engine  | GSAP         | Ratio       |
+| --------------------------------------------- | ------------ | ------------ | ----------- |
+| **Single tween** (cubic, 1000 frames)         | 40,814 ops/s | 10,776 ops/s | 3.8× faster |
+| **Single tween** (linear, 1000 frames)        | 28,590 ops/s | 14,499 ops/s | 2.0× faster |
+| **Single tween** (cubic bezier, 1000 frames)  | 21,449 ops/s | 12,637 ops/s | 1.7× faster |
+| **Keyframe** (3 segments, 1000 frames)        | 26,741 ops/s | 3,549 ops/s  | 7.5× faster |
+| **50 concurrent tweens** (500 frames)         | 892 ops/s    | 438 ops/s    | 2.0× faster |
+| **200 concurrent tweens** (500 frames)        | 200 ops/s    | 106 ops/s    | 1.9× faster |
+| **1000 concurrent tweens** (500 frames)       | 38 ops/s     | 22 ops/s     | 1.7× faster |
+| **50 concurrent keyframes** (500 frames)      | 934 ops/s    | 174 ops/s    | 5.4× faster |
+| **50-layer timeline** (staggered, 500 frames) | 710 ops/s    | 404 ops/s    | 1.8× faster |
+| **50 tweens re-play** (2 cycles, 500 frames)  | 558 ops/s    | 128 ops/s    | 4.4× faster |
+
+### vs GSAP onUpdate (fair comparison)
 
-| Benchmark                                    | anim-engine  | GSAP         | Ratio        |
-| -------------------------------------------- | ------------ | ------------ | ------------ |
-| **Single tween** (cubic, 1000 frames)        | 43,265 ops/s | 9,542 ops/s  | 4.53× faster |
-| **Single tween** (linear, 1000 frames)       | 30,461 ops/s | 16,195 ops/s | 1.88× faster |
-| **Single tween** (cubic bezier, 1000 frames) | 21,439 ops/s | 12,869 ops/s | 1.67× faster |
-| **Keyframe** (3 segments, 1000 frames)       | 35,307 ops/s | 3,560 ops/s  | 9.92× faster |
-| **50 concurrent tweens** (500 frames)        | 942 ops/s    | 473 ops/s    | 1.99× faster |
-| **50 concurrent keyframes** (500 frames)     | 918 ops/s    | 171 ops/s    | 5.38× faster |
+gsap also supports `onUpdate` callbacks, which is equivalent to anim-engine's renderer-agnostic model. This is the apples-to-apples comparison.
 
-Easing functions are matched between libraries (cubic = GSAP `power2.out`, cubic bezier = identical control points via GSAP `CustomEase`). Linear strips out easing to show pure framework overhead.
+| Benchmark                              | anim-engine  | GSAP (onUpdate) | Ratio       |
+| -------------------------------------- | ------------ | --------------- | ----------- |
+| **Single tween** (cubic, 1000 frames)  | 40,814 ops/s | 6,618 ops/s     | 6.2× faster |
+| **50 concurrent tweens** (500 frames)  | 892 ops/s    | 273 ops/s       | 3.3× faster |
+| **200 concurrent tweens** (500 frames) | 200 ops/s    | 66 ops/s        | 3.0× faster |
 
 Run locally: `npm run bench`
 
@@ -643,24 +663,25 @@ requestAnimationFrame(gameLoop);
 
 ### Type exports
 
-| Type                 | Description                                                                                                             |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `Animation`          | `play`, `pause`, `resume`, `stop`, `skipToEnd`, `kill`, `setCurrentValue`, `setProgress`, `currentValue`, `velocity`, `progress` (readonly), `status` |
-| `Interpolation`      | `start`, `stop`, `kill`, `setCurrentValue`, `currentValue`, `velocity`, `status`                                             |
-| `Timeline`           | `play`, `pause`, `resume`, `stop`, `skipToEnd`, `kill`, `setProgress`, `progress`, `status`                                            |
-| `EaseName`           | Union of 31 ease name strings                                                                                           |
-| `EaseFunction`       | `(t: number) => number`                                                                                                 |
-| `DynamicValue`       | `number \| (() => number)`                                                                                             |
-| `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: 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`                                                                     |
-| `LerpOptions`        | `to`, `smoothTimeMs`, `precision?`, `onUpdate`, `onEnded`                                                                                        |
-| `RgbaTuple`          | `readonly [number, number, number, number]`                                                                             |
-| `TickerControls`     | `start`, `stop`, `update`, `add`, `remove`                                                                              |
+| Type                        | Description                                                                                                             |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `Animation`                 | `play`, `pause`, `resume`, `stop`, `skipToEnd`, `kill`, `setProgress`, `currentValue`, `velocity`, `progress`, `status` |
+| `Interpolation`             | `start`, `stop`, `kill`, `setCurrentValue`, `currentValue`, `velocity`, `status`                                        |
+| `Timeline`                  | `play`, `pause`, `resume`, `stop`, `skipToEnd`, `kill`, `setProgress`, `progress`, `status`                             |
+| `EaseName`                  | Union of 31 ease name strings                                                                                           |
+| `EaseFunction`              | `(t: number) => number`                                                                                                 |
+| `DynamicValue`              | `number \| (() => number)`                                                                                              |
+| `AnimationStatus`           | `"playing" \| "paused" \| "stopped" \| "dead"` (for `Animation` / `Timeline`)                                           |
+| `InterpolationStatus`       | `"active" \| "inactive" \| "dead"` (for `Interpolation`)                                                                |
+| `AnimationOptions`          | Single tween or keyframe animation options (discriminated union)                                                        |
+| `Keyframe`                  | `{ value, gap?, ease? }`                                                                                                |
+| `KeyframedAnimationOptions` | `{ keyframes: Keyframe[], onStarted?, onUpdate?, onProgress?, onEnded? }`                                               |
+| `TimelineLayer`             | `{ animation: KeyframedAnimationOptions; at: DynamicValue } \| { animation: KeyframedAnimationOptions; gap: number }`     |
+| `SpringOptions`             | `to`, `stiffness`, `damping`, `mass`, `precision?`, `onUpdate`, `onEnded`                                               |
+| `SmoothDampOptions`         | `to`, `smoothTimeMs`, `maxSpeed?`, `precision?`, `onUpdate`, `onEnded`                                                  |
+| `LerpOptions`               | `to`, `smoothTimeMs`, `precision?`, `onUpdate`, `onEnded`                                                               |
+| `RgbaTuple`                 | `readonly [number, number, number, number]`                                                                             |
+| `TickerControls`            | `start`, `stop`, `update`, `add`, `remove`                                                                              |
 
 ## License
 

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

@@ -9,12 +9,13 @@ export type SingleTweenOptions = {
     onEnded?: () => void;
 };
 export type Keyframe = {
-    at: DynamicValue;
     value: DynamicValue;
     ease?: EaseName | EaseFunction;
+    gap?: DynamicValue;
 };
 export type KeyframedAnimationOptions = {
     keyframes: Keyframe[];
+    onStarted?: () => void;
     onUpdate?: (value: number, velocity: number) => void;
     onProgress?: (progress: number) => void;
     onEnded?: () => void;

package/dist/animation/create-animation.js

@@ -1,8 +1,9 @@
 import { easingFunctions } from "../easing/easing.js";
 import { getTicker } from "../ticker/get-ticker.js";
-import { updateTween } from "./update.js";
+import { createKeyframeRunner, createTweenRunner } from "./runner.js";
 //#region src/animation/create-animation.ts
 var resolveEasing = (ease) => typeof ease === "function" ? ease : easingFunctions[ease];
+var resolveValue = (v) => typeof v === "function" ? v() : v;
 var isKeyframeMode = (options) => {
 	return "keyframes" in options && Array.isArray(options.keyframes);
 };
@@ -16,83 +17,75 @@ var createSingleTween = (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,
-		velocity: 0
-	};
+	let cachedDurationMs = resolveValue(rawDurationMs);
 	let status = "stopped";
-	let stopped = false;
 	let resolvePromise;
 	const ticker = getTicker();
-	const update = (deltaMs) => {
-		if (stopped) return;
-		const completed = updateTween(state, deltaMs, cachedDurationMs, currentEase, cachedFrom, cachedTo);
-		onUpdate?.(state.currentValue, state.velocity);
-		if (completed) handleCompletion();
+	let runner;
+	const finish = () => {
+		status = "stopped";
+		ticker.remove(runner);
+		resolvePromise?.(controls);
+		resolvePromise = void 0;
+	};
+	const buildRunner = () => {
+		const from = resolveValue(rawFrom);
+		const to = resolveValue(rawTo);
+		cachedDurationMs = resolveValue(rawDurationMs);
+		return createTweenRunner({
+			from,
+			to,
+			durationMs: cachedDurationMs,
+			easeFn: resolveEasing(easeName),
+			onStarted,
+			onUpdate,
+			onEnded,
+			onComplete: finish
+		});
 	};
-	let currentEase = resolveEasing(easeName);
+	const hasDynamic = typeof rawFrom === "function" || typeof rawTo === "function" || typeof rawDurationMs === "function";
+	runner = buildRunner();
 	const play = () => {
 		if (status === "dead") throw new Error("Cannot play a dead animation");
-		stopped = false;
-		state.progress = 0;
-		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 (hasDynamic) runner = buildRunner();
+		else runner.reset();
 		const promise = new Promise((resolve) => {
 			resolvePromise = resolve;
 		});
 		status = "playing";
-		ticker.add(update);
+		ticker.add(runner);
 		onStarted?.();
 		return promise;
 	};
 	const pause = () => {
 		if (status !== "playing") return;
 		status = "paused";
-		ticker.remove(update);
+		ticker.remove(runner);
 	};
 	const resume = () => {
 		if (status !== "paused") return;
 		status = "playing";
-		ticker.add(update);
+		ticker.add(runner);
 	};
 	const stop = () => {
-		stopped = true;
 		status = "stopped";
-		ticker.remove(update);
+		ticker.remove(runner);
 		resolvePromise?.(controls);
 		resolvePromise = void 0;
 	};
 	const skipToEnd = () => {
-		state.currentValue = cachedTo;
-		state.velocity = 0;
-		state.progress = 1;
-		onUpdate?.(state.currentValue, state.velocity);
+		runner.evaluate(1);
 		if (status === "playing" || status === "paused") onEnded?.();
 		status = "stopped";
-		ticker.remove(update);
+		ticker.remove(runner);
 		resolvePromise?.(controls);
 		resolvePromise = void 0;
 	};
 	const kill = () => {
 		status = "dead";
-		ticker.remove(update);
-		stopped = true;
+		ticker.remove(runner);
 		resolvePromise = void 0;
 	};
-	function handleCompletion() {
-		onEnded?.();
-		status = "stopped";
-		ticker.remove(update);
-		resolvePromise?.(controls);
-		resolvePromise = void 0;
-	}
 	const controls = {
 		play,
 		pause,
@@ -100,26 +93,18 @@ var createSingleTween = (options) => {
 		stop,
 		skipToEnd,
 		kill,
-		setCurrentValue: (value) => {
-			state.currentValue = value;
-			state.velocity = 0;
-		},
 		get currentValue() {
-			return state.currentValue;
+			return runner.currentValue;
 		},
 		get velocity() {
-			return state.velocity;
+			return runner.velocity;
 		},
 		get progress() {
-			return state.progress;
+			return runner.progress;
 		},
 		setProgress(value) {
 			if (status === "playing") pause();
-			const clamped = Math.max(0, Math.min(1, value));
-			state.progress = clamped;
-			state.currentValue = cachedFrom + (cachedTo - cachedFrom) * currentEase(clamped);
-			state.velocity = 0;
-			onUpdate?.(state.currentValue, state.velocity);
+			runner.evaluate(Math.max(0, Math.min(1, value)));
 		},
 		get status() {
 			return status;
@@ -131,149 +116,80 @@ var createSingleTween = (options) => {
 	return controls;
 };
 var createKeyframeAnimation = (options) => {
-	const rawKeyframes = options.keyframes;
-	const onUpdate = options.onUpdate;
-	const onProgress = options.onProgress;
-	const onEnded = options.onEnded;
-	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);
-	};
-	rebuild();
-	const state = {
-		progress: 0,
-		currentValue: 0,
-		velocity: 0
+	const { keyframes: rawKeyframes, onStarted, onUpdate, onProgress, onEnded } = options;
+	const resolveKeyframeGaps = () => {
+		let total = 0;
+		for (let i = 1; i < rawKeyframes.length; i++) total += resolveValue(rawKeyframes[i].gap ?? 0);
+		return total;
 	};
+	let cachedDurationMs = resolveKeyframeGaps();
 	let status = "stopped";
-	let stopped = false;
 	let resolvePromise;
-	let currentSegmentIndex = 0;
-	let previousValue = segments[0].from;
 	const ticker = getTicker();
-	const update = (deltaMs) => {
-		if (stopped) return;
-		const segment = segments[currentSegmentIndex];
-		segmentElapsed += deltaMs;
-		segmentProgress += deltaMs / segment.durationMs;
-		if (segmentProgress >= 1) segmentProgress = 1;
-		const eased = segment.easeFn(segmentProgress);
-		previousValue = state.currentValue;
-		state.currentValue = segment.from + segment.range * eased;
-		if (segmentProgress >= 1) {
-			state.currentValue = segment.to;
-			state.velocity = 0;
-		} else state.velocity = (state.currentValue - previousValue) / (deltaMs / 1e3);
-		const elapsedTotal = prefixSum[currentSegmentIndex] + segmentElapsed;
-		state.progress = Math.min(elapsedTotal * invTotalDuration, 1);
-		onProgress?.(state.progress);
-		onUpdate?.(state.currentValue, state.velocity);
-		if (segmentProgress >= 1) if (currentSegmentIndex < segments.length - 1) {
-			currentSegmentIndex++;
-			segmentElapsed = 0;
-			segmentProgress = 0;
-			state.currentValue = segments[currentSegmentIndex].from;
-			previousValue = state.currentValue;
-			state.velocity = 0;
-			state.progress = Math.min(prefixSum[currentSegmentIndex] * invTotalDuration, 1);
-			onProgress?.(state.progress);
-		} else {
-			status = "stopped";
-			ticker.remove(update);
-			onEnded?.();
-			resolvePromise?.(controls);
-			resolvePromise = void 0;
-		}
+	let runner;
+	const finish = () => {
+		status = "stopped";
+		ticker.remove(runner);
+		resolvePromise?.(controls);
+		resolvePromise = void 0;
 	};
-	let segmentProgress = 0;
-	let segmentElapsed = 0;
+	const buildRunner = () => {
+		return createKeyframeRunner({
+			keyframes: rawKeyframes.map((kf, i) => ({
+				value: resolveValue(kf.value),
+				gap: i === 0 ? 0 : resolveValue(kf.gap ?? 0),
+				easeFn: resolveEasing(kf.ease ?? "inOutSine")
+			})),
+			onStarted,
+			onUpdate,
+			onProgress,
+			onEnded,
+			onComplete: finish
+		});
+	};
+	const hasDynamic = rawKeyframes.some((kf) => typeof kf.value === "function" || typeof kf.gap === "function");
+	runner = buildRunner();
 	const play = () => {
 		if (status === "dead") throw new Error("Cannot play a dead animation");
-		rebuild();
-		stopped = false;
-		currentSegmentIndex = 0;
-		segmentElapsed = 0;
-		segmentProgress = 0;
-		state.progress = 0;
-		state.currentValue = segments[0].from;
-		previousValue = segments[0].from;
-		state.velocity = 0;
+		if (hasDynamic) {
+			runner = buildRunner();
+			cachedDurationMs = resolveKeyframeGaps();
+		} else runner.reset();
 		const promise = new Promise((resolve) => {
 			resolvePromise = resolve;
 		});
 		status = "playing";
-		ticker.add(update);
+		ticker.add(runner);
+		onStarted?.();
 		return promise;
 	};
 	const pause = () => {
 		if (status !== "playing") return;
 		status = "paused";
-		ticker.remove(update);
+		ticker.remove(runner);
 	};
 	const resume = () => {
 		if (status !== "paused") return;
 		status = "playing";
-		ticker.add(update);
+		ticker.add(runner);
 	};
 	const stop = () => {
-		stopped = true;
 		status = "stopped";
-		ticker.remove(update);
+		ticker.remove(runner);
 		resolvePromise?.(controls);
 		resolvePromise = void 0;
 	};
 	const skipToEnd = () => {
-		const last = segments[segments.length - 1];
-		state.currentValue = last.to;
-		state.velocity = 0;
-		state.progress = 1;
-		onUpdate?.(state.currentValue, state.velocity);
+		runner.evaluate(1);
 		if (status === "playing" || status === "paused") onEnded?.();
 		status = "stopped";
-		ticker.remove(update);
+		ticker.remove(runner);
 		resolvePromise?.(controls);
 		resolvePromise = void 0;
 	};
 	const kill = () => {
 		status = "dead";
-		ticker.remove(update);
-		stopped = true;
+		ticker.remove(runner);
 		resolvePromise = void 0;
 	};
 	const controls = {
@@ -283,47 +199,24 @@ var createKeyframeAnimation = (options) => {
 		stop,
 		skipToEnd,
 		kill,
-		setCurrentValue: (value) => {
-			state.currentValue = value;
-			state.velocity = 0;
-		},
 		get currentValue() {
-			return state.currentValue;
+			return runner.currentValue;
 		},
 		get velocity() {
-			return state.velocity;
+			return runner.velocity;
 		},
 		get progress() {
-			return state.progress;
+			return runner.progress;
 		},
 		setProgress(value) {
 			if (status === "playing") pause();
-			const clamped = Math.max(0, Math.min(1, value));
-			state.progress = clamped;
-			const elapsed = clamped * totalDurationMs;
-			let segIdx = 0;
-			for (let i = 0; i < segments.length; i++) {
-				if (elapsed <= prefixSum[i + 1]) {
-					segIdx = i;
-					break;
-				}
-				segIdx = i;
-			}
-			const segment = segments[segIdx];
-			const segStart = prefixSum[segIdx];
-			const segDuration = segment.durationMs;
-			const segProgress = segDuration > 0 ? (elapsed - segStart) / segDuration : 1;
-			const eased = segment.easeFn(Math.max(0, Math.min(1, segProgress)));
-			state.currentValue = segment.from + segment.range * eased;
-			state.velocity = 0;
-			onUpdate?.(state.currentValue, state.velocity);
-			onProgress?.(clamped);
+			runner.evaluate(Math.max(0, Math.min(1, value)));
 		},
 		get status() {
 			return status;
 		},
 		get durationMs() {
-			return totalDurationMs;
+			return cachedDurationMs;
 		}
 	};
 	return controls;

package/dist/animation/runner.d.ts

@@ -0,0 +1,37 @@
+import { EaseFunction } from '../shared/types';
+export type Runner = {
+    (deltaMs: number): boolean;
+    evaluate: (progress: number) => number;
+    reset: () => void;
+    currentValue: number;
+    velocity: number;
+    progress: number;
+    onStarted: (() => void) | undefined;
+    onUpdate: ((value: number, velocity: number) => void) | undefined;
+    onProgress: ((progress: number) => void) | undefined;
+    onEnded: (() => void) | undefined;
+};
+export type TweenRunnerConfig = {
+    from: number;
+    to: number;
+    durationMs: number;
+    easeFn: EaseFunction;
+    onStarted?: () => void;
+    onUpdate?: (value: number, velocity: number) => void;
+    onEnded?: () => void;
+    onComplete?: () => void;
+};
+export declare const createTweenRunner: (config: TweenRunnerConfig) => Runner;
+export type KeyframeRunnerConfig = {
+    keyframes: {
+        value: number;
+        gap: number;
+        easeFn: EaseFunction;
+    }[];
+    onStarted?: () => void;
+    onUpdate?: (value: number, velocity: number) => void;
+    onProgress?: (progress: number) => void;
+    onEnded?: () => void;
+    onComplete?: () => void;
+};
+export declare const createKeyframeRunner: (config: KeyframeRunnerConfig) => Runner;

package/dist/animation/runner.js

@@ -0,0 +1,220 @@
+import { updateTween } from "./update.js";
+//#region src/animation/runner.ts
+var noop = () => {};
+var createTweenRunner = (config) => {
+	const { from, to, durationMs, easeFn } = config;
+	const onStarted = config.onStarted;
+	const onUpdate = config.onUpdate ?? noop;
+	const onEnded = config.onEnded;
+	const onComplete = config.onComplete;
+	const state = {
+		progress: 0,
+		currentValue: from,
+		velocity: 0
+	};
+	let runner;
+	const step = (deltaMs) => {
+		const completed = updateTween(state, deltaMs, durationMs, easeFn, from, to);
+		onUpdate(state.currentValue, state.velocity);
+		if (completed) {
+			onEnded?.();
+			onComplete?.();
+		}
+		return completed;
+	};
+	const evaluate = (progress) => {
+		const clamped = Math.max(0, Math.min(1, progress));
+		state.progress = clamped;
+		if (clamped >= 1) {
+			state.currentValue = to;
+			state.velocity = 0;
+		} else {
+			const range = to - from;
+			state.currentValue = from + range * easeFn(clamped);
+			state.velocity = 0;
+		}
+		onUpdate(state.currentValue, state.velocity);
+		return state.currentValue;
+	};
+	const reset = () => {
+		state.progress = 0;
+		state.currentValue = from;
+		state.velocity = 0;
+	};
+	runner = step;
+	runner.evaluate = evaluate;
+	runner.reset = reset;
+	Object.defineProperty(runner, "currentValue", {
+		get: () => state.currentValue,
+		configurable: true
+	});
+	Object.defineProperty(runner, "velocity", {
+		get: () => state.velocity,
+		configurable: true
+	});
+	Object.defineProperty(runner, "progress", {
+		get: () => state.progress,
+		configurable: true
+	});
+	runner.onStarted = onStarted;
+	runner.onUpdate = config.onUpdate;
+	runner.onProgress = void 0;
+	runner.onEnded = onEnded;
+	return runner;
+};
+var createKeyframeRunner = (config) => {
+	const { keyframes } = config;
+	const onStarted = config.onStarted;
+	const onUpdate = config.onUpdate ?? noop;
+	const onProgress = config.onProgress ?? noop;
+	const onEnded = config.onEnded;
+	const onComplete = config.onComplete;
+	const segments = [];
+	for (let i = 0; i < keyframes.length - 1; i++) {
+		const cur = keyframes[i];
+		const nxt = keyframes[i + 1];
+		segments.push({
+			from: cur.value,
+			to: nxt.value,
+			range: nxt.value - cur.value,
+			durationMs: nxt.gap,
+			easeFn: nxt.easeFn
+		});
+	}
+	const prefixSum = [0];
+	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 velocity = 0;
+	let globalProgress = 0;
+	let currentSegmentIndex = 0;
+	let segmentElapsed = 0;
+	let segmentProgress = 0;
+	let runner;
+	if (segments.length === 0) {
+		const complete = () => {
+			onEnded?.();
+			onComplete?.();
+		};
+		const step = (_deltaMs) => {
+			onUpdate(currentValue, 0);
+			onProgress(1);
+			complete();
+			return true;
+		};
+		const evaluate = (prog) => {
+			onUpdate(currentValue, 0);
+			onProgress(Math.max(0, Math.min(1, prog)));
+			return currentValue;
+		};
+		runner = step;
+		runner.evaluate = evaluate;
+		runner.reset = () => {};
+		Object.defineProperty(runner, "currentValue", {
+			get: () => currentValue,
+			configurable: true
+		});
+		Object.defineProperty(runner, "velocity", {
+			get: () => 0,
+			configurable: true
+		});
+		Object.defineProperty(runner, "progress", {
+			get: () => 1,
+			configurable: true
+		});
+		runner.onStarted = onStarted;
+		runner.onUpdate = config.onUpdate;
+		runner.onProgress = config.onProgress;
+		runner.onEnded = onEnded;
+		return runner;
+	}
+	const step = (deltaMs) => {
+		const segment = segments[currentSegmentIndex];
+		segmentElapsed += deltaMs;
+		segmentProgress += deltaMs / segment.durationMs;
+		if (segmentProgress >= 1) segmentProgress = 1;
+		const previousValue = currentValue;
+		const eased = segment.easeFn(segmentProgress);
+		currentValue = segment.from + segment.range * eased;
+		if (segmentProgress >= 1) {
+			currentValue = segment.to;
+			velocity = 0;
+		} else velocity = (currentValue - previousValue) / (deltaMs / 1e3);
+		const elapsedTotal = prefixSum[currentSegmentIndex] + segmentElapsed;
+		globalProgress = Math.min(elapsedTotal * invTotalDuration, 1);
+		onProgress(globalProgress);
+		onUpdate(currentValue, velocity);
+		if (segmentProgress >= 1) if (currentSegmentIndex < segments.length - 1) {
+			currentSegmentIndex++;
+			segmentElapsed = 0;
+			segmentProgress = 0;
+			currentValue = segments[currentSegmentIndex].from;
+			velocity = 0;
+			globalProgress = Math.min(prefixSum[currentSegmentIndex] * invTotalDuration, 1);
+			onProgress(globalProgress);
+		} else {
+			onEnded?.();
+			onComplete?.();
+			return true;
+		}
+		return false;
+	};
+	const evaluate = (progress) => {
+		const clamped = Math.max(0, Math.min(1, progress));
+		const elapsed = clamped * totalDurationMs;
+		let segIdx = 0;
+		for (let i = 0; i < segments.length; i++) {
+			if (elapsed <= prefixSum[i + 1]) {
+				segIdx = i;
+				break;
+			}
+			segIdx = i;
+		}
+		const segment = segments[segIdx];
+		const segStart = prefixSum[segIdx];
+		const segDuration = segment.durationMs;
+		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;
+		velocity = 0;
+		globalProgress = clamped;
+		currentSegmentIndex = segIdx;
+		segmentElapsed = elapsed - segStart;
+		segmentProgress = clampedSegProgress;
+		onUpdate(currentValue, velocity);
+		onProgress(clamped);
+		return currentValue;
+	};
+	const reset = () => {
+		currentValue = keyframes[0].value;
+		velocity = 0;
+		globalProgress = 0;
+		currentSegmentIndex = 0;
+		segmentElapsed = 0;
+		segmentProgress = 0;
+	};
+	runner = step;
+	runner.evaluate = evaluate;
+	runner.reset = reset;
+	Object.defineProperty(runner, "currentValue", {
+		get: () => currentValue,
+		configurable: true
+	});
+	Object.defineProperty(runner, "velocity", {
+		get: () => velocity,
+		configurable: true
+	});
+	Object.defineProperty(runner, "progress", {
+		get: () => globalProgress,
+		configurable: true
+	});
+	runner.onStarted = onStarted;
+	runner.onUpdate = config.onUpdate;
+	runner.onProgress = config.onProgress;
+	runner.onEnded = onEnded;
+	return runner;
+};
+//#endregion
+export { createKeyframeRunner, createTweenRunner };

package/dist/shared/types.d.ts

@@ -10,7 +10,6 @@ export type Animation = {
     stop: () => void;
     skipToEnd: () => void;
     kill: () => void;
-    setCurrentValue: (value: number) => void;
     currentValue: number;
     velocity: number;
     progress: number;

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

@@ -1,10 +1,11 @@
-import { Animation, AnimationStatus } from '../shared/types';
+import { KeyframedAnimationOptions } from '../animation/create-animation';
+import { AnimationStatus, DynamicValue } from '../shared/types';
 export type TimelineLayer = {
-    at: number;
-    animation: Animation | Animation[];
+    animation: KeyframedAnimationOptions;
+    at: DynamicValue;
 } | {
+    animation: KeyframedAnimationOptions;
     gap: number;
-    animation: Animation | Animation[];
 };
 export type Timeline = {
     play: () => Promise<Timeline>;

package/dist/timeline/create-timeline.js

@@ -1,119 +1,144 @@
+import { easingFunctions } from "../easing/easing.js";
 import { getTicker } from "../ticker/get-ticker.js";
+import { createKeyframeRunner } from "../animation/runner.js";
 //#region src/timeline/create-timeline.ts
-var createTimeline = (layers, options) => {
-	const { onStarted, onProgress, onEnded } = options ?? {};
-	const batches = [];
-	let lastBatchEnd = 0;
-	for (const layer of layers) {
-		const anims = Array.isArray(layer.animation) ? layer.animation : [layer.animation];
-		const startAt = "at" in layer ? layer.at : lastBatchEnd + layer.gap;
-		const endAt = startAt + Math.max(...anims.map((a) => a.durationMs));
-		batches.push({
-			animations: anims,
+var noop = () => {};
+var resolveValue = (v) => typeof v === "function" ? v() : v;
+var resolveEasing = (ease) => typeof ease === "function" ? ease : easingFunctions[ease];
+var buildFromConfigs = (rawLayers) => {
+	const activeLayers = [];
+	let previousEndAt = 0;
+	for (const layer of rawLayers) {
+		const startAt = "at" in layer ? resolveValue(layer.at) : previousEndAt + layer.gap;
+		const resolvedKeyframes = layer.animation.keyframes.map((kf, j) => ({
+			value: resolveValue(kf.value),
+			gap: j === 0 ? 0 : resolveValue(kf.gap ?? 0),
+			easeFn: resolveEasing(kf.ease ?? "inOutSine")
+		}));
+		let layerDuration = 0;
+		for (let i = 1; i < resolvedKeyframes.length; i++) layerDuration += resolvedKeyframes[i].gap;
+		const runner = createKeyframeRunner({
+			keyframes: resolvedKeyframes,
+			onStarted: layer.animation.onStarted,
+			onUpdate: layer.animation.onUpdate,
+			onProgress: layer.animation.onProgress,
+			onEnded: layer.animation.onEnded
+		});
+		activeLayers.push({
 			startAt,
-			endAt,
-			started: false
+			endAt: startAt + layerDuration,
+			runner,
+			started: false,
+			ended: false
 		});
-		lastBatchEnd = endAt;
+		previousEndAt = startAt + layerDuration;
 	}
-	batches.sort((a, b) => a.startAt - b.startAt);
-	const totalDurationMs = Math.max(0, ...batches.map((b) => b.endAt));
-	let status = "stopped";
+	activeLayers.sort((a, b) => a.startAt - b.startAt);
+	return {
+		activeLayers,
+		totalDurationMs: Math.max(0, ...activeLayers.map((l) => l.endAt))
+	};
+};
+var createTimeline = (layers, options) => {
+	const { onStarted, onEnded } = options ?? {};
+	const onProgress = options?.onProgress ?? noop;
+	const rawLayers = layers;
+	let state = buildFromConfigs(rawLayers);
+	let activeLayers = state.activeLayers;
+	let totalDurationMs = state.totalDurationMs;
+	let timelineStatus = "stopped";
 	let elapsedMs = 0;
 	let resolvePromise;
-	let pendingAnimations = 0;
+	let remainingLayers = activeLayers.length;
 	const ticker = getTicker();
+	const finish = () => {
+		timelineStatus = "stopped";
+		ticker.remove(update);
+		onEnded?.();
+		resolvePromise?.(timeline);
+		resolvePromise = void 0;
+	};
+	const update = (deltaMs) => {
+		elapsedMs += deltaMs;
+		for (const layer of activeLayers) {
+			if (!layer.started && elapsedMs >= layer.startAt) {
+				layer.runner.reset();
+				layer.runner.onStarted?.();
+				layer.started = true;
+			}
+			if (layer.started && !layer.ended) {
+				if (layer.runner(deltaMs)) {
+					layer.ended = true;
+					remainingLayers--;
+				}
+			}
+		}
+		onProgress(totalDurationMs > 0 ? Math.min(elapsedMs / totalDurationMs, 1) : 1);
+		if (remainingLayers <= 0) finish();
+	};
 	const play = () => {
-		if (status === "dead") throw new Error("Cannot play a dead timeline");
+		if (timelineStatus === "dead") throw new Error("Cannot play a dead timeline");
+		state = buildFromConfigs(rawLayers);
+		activeLayers = state.activeLayers;
+		totalDurationMs = state.totalDurationMs;
+		remainingLayers = activeLayers.length;
 		elapsedMs = 0;
-		pendingAnimations = 0;
-		batches.forEach((b) => {
-			b.started = false;
-		});
 		const promise = new Promise((resolve) => {
 			resolvePromise = resolve;
 		});
-		status = "playing";
+		timelineStatus = "playing";
 		onStarted?.();
 		ticker.add(update);
 		return promise;
 	};
 	const pause = () => {
-		if (status !== "playing") return;
-		status = "paused";
+		if (timelineStatus !== "playing") return;
+		timelineStatus = "paused";
 		ticker.remove(update);
-		for (const batch of batches) if (batch.started) {
-			for (const anim of batch.animations) if (anim.status === "playing") anim.pause();
-		}
 	};
 	const resume = () => {
-		if (status !== "paused") return;
-		status = "playing";
-		for (const batch of batches) if (batch.started) {
-			for (const anim of batch.animations) if (anim.status === "paused") anim.resume();
-		}
+		if (timelineStatus !== "paused") return;
+		timelineStatus = "playing";
 		ticker.add(update);
 	};
 	const stop = () => {
-		if (status !== "playing" && status !== "paused") return;
-		status = "stopped";
+		if (timelineStatus !== "playing" && timelineStatus !== "paused") return;
+		timelineStatus = "stopped";
 		ticker.remove(update);
-		for (const batch of batches) if (batch.started) for (const anim of batch.animations) anim.stop();
 		resolvePromise?.(timeline);
 		resolvePromise = void 0;
 	};
 	const skipToEnd = () => {
-		status = "stopped";
+		for (const layer of activeLayers) {
+			layer.runner.evaluate(1);
+			layer.runner.onEnded?.();
+		}
+		timelineStatus = "stopped";
 		ticker.remove(update);
-		for (const batch of batches) for (const anim of batch.animations) anim.skipToEnd();
 		onEnded?.();
 		resolvePromise?.(timeline);
 		resolvePromise = void 0;
 	};
 	const kill = () => {
-		status = "dead";
-		ticker.remove(update);
-		for (const batch of batches) for (const anim of batch.animations) anim.kill();
-		resolvePromise = void 0;
-	};
-	const update = (deltaMs) => {
-		if (status !== "playing") return;
-		elapsedMs += deltaMs;
-		for (const batch of batches) if (!batch.started && elapsedMs >= batch.startAt) {
-			batch.started = true;
-			pendingAnimations += batch.animations.length;
-			for (const anim of batch.animations) anim.play().then(() => {
-				pendingAnimations--;
-				checkComplete();
-			});
-		}
-		onProgress?.(totalDurationMs > 0 ? Math.min(elapsedMs / totalDurationMs, 1) : 0);
-		if (batches.every((b) => b.started) && pendingAnimations <= 0) finish();
-	};
-	const checkComplete = () => {
-		if (pendingAnimations <= 0 && status === "playing" && batches.every((b) => b.started)) finish();
-	};
-	const finish = () => {
-		status = "stopped";
+		timelineStatus = "dead";
 		ticker.remove(update);
-		onEnded?.();
-		resolvePromise?.(timeline);
 		resolvePromise = void 0;
 	};
 	const setProgress = (value) => {
-		if (status === "playing") pause();
+		if (timelineStatus === "playing") pause();
 		elapsedMs = Math.max(0, Math.min(1, value)) * totalDurationMs;
-		for (const batch of batches) if (elapsedMs < batch.startAt) {
-			for (const anim of batch.animations) anim.setProgress(0);
-			batch.started = false;
+		for (const layer of activeLayers) if (elapsedMs < layer.startAt) {
+			layer.runner.evaluate(0);
+			layer.started = false;
+			layer.ended = false;
 		} else {
-			batch.started = true;
-			const batchElapsed = elapsedMs - batch.startAt;
-			for (const anim of batch.animations) {
-				const localProgress = anim.durationMs > 0 ? Math.min(batchElapsed / anim.durationMs, 1) : 1;
-				anim.setProgress(localProgress);
-			}
+			layer.started = true;
+			const layerDuration = layer.endAt - layer.startAt;
+			const localProgress = layerDuration > 0 ? Math.min((elapsedMs - layer.startAt) / layerDuration, 1) : 1;
+			layer.runner.evaluate(localProgress);
+			layer.ended = localProgress >= 1;
 		}
+		remainingLayers = activeLayers.filter((l) => !l.ended).length;
 	};
 	const timeline = {
 		play,
@@ -124,10 +149,10 @@ var createTimeline = (layers, options) => {
 		kill,
 		setProgress,
 		get progress() {
-			return totalDurationMs > 0 ? Math.min(elapsedMs / totalDurationMs, 1) : 0;
+			return totalDurationMs > 0 ? Math.min(elapsedMs / totalDurationMs, 1) : 1;
 		},
 		get status() {
-			return status;
+			return timelineStatus;
 		},
 		get durationMs() {
 			return totalDurationMs;

package/package.json

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