anim-engine 0.1.1

package/dist/animation/create-animation.js

@@ -0,0 +1,336 @@
+import { easingFunctions } from "../easing/easing.js";
+import { getTicker } from "../ticker/get-ticker.js";
+import { updateTween } from "./update.js";
+//#region src/animation/create-animation.ts
+var resolveEasing = (ease) => typeof ease === "function" ? ease : easingFunctions[ease];
+var isKeyframeMode = (options) => {
+	return "keyframes" in options && Array.isArray(options.keyframes);
+};
+var createAnimation = (options) => {
+	if (isKeyframeMode(options)) return createKeyframeAnimation(options);
+	return createSingleTween(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 state = {
+		progress: 0,
+		currentValue: 0,
+		velocity: 0
+	};
+	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);
+		onUpdate?.(state.currentValue, state.velocity);
+		if (completed) handleCompletion();
+	};
+	let currentEase = resolveEasing(easeName);
+	const play = () => {
+		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;
+		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?.();
+		return promise;
+	};
+	const pause = () => {
+		if (status !== "playing") return;
+		status = "paused";
+		ticker.remove(update);
+	};
+	const resume = () => {
+		if (status !== "paused") return;
+		status = "playing";
+		ticker.add(update);
+	};
+	const stop = () => {
+		stopped = true;
+		status = "stopped";
+		ticker.remove(update);
+		resolvePromise?.(controls);
+		resolvePromise = void 0;
+	};
+	const skipToEnd = () => {
+		const skipTo = typeof rawTo === "function" ? rawTo() : rawTo;
+		state.currentValue = skipTo;
+		state.velocity = 0;
+		state.progress = 1;
+		onUpdate?.(state.currentValue, state.velocity);
+		if (status === "playing" || status === "paused") onEnded?.();
+		status = "stopped";
+		ticker.remove(update);
+		resolvePromise?.(controls);
+		resolvePromise = void 0;
+	};
+	const kill = () => {
+		status = "dead";
+		ticker.remove(update);
+		stopped = true;
+		resolvePromise = void 0;
+	};
+	function handleCompletion() {
+		onEnded?.();
+		status = "stopped";
+		ticker.remove(update);
+		resolvePromise?.(controls);
+		resolvePromise = void 0;
+	}
+	const controls = {
+		play,
+		pause,
+		resume,
+		stop,
+		skipToEnd,
+		kill,
+		setCurrentValue: (value) => {
+			state.currentValue = value;
+			state.velocity = 0;
+		},
+		get currentValue() {
+			return state.currentValue;
+		},
+		get velocity() {
+			return state.velocity;
+		},
+		get progress() {
+			return state.progress;
+		},
+		setProgress(value) {
+			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.velocity = 0;
+			onUpdate?.(state.currentValue, state.velocity);
+		},
+		get status() {
+			return status;
+		},
+		get durationMs() {
+			return durationMs;
+		}
+	};
+	return controls;
+};
+var createKeyframeAnimation = (options) => {
+	const keyframes = 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 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
+	});
+	const state = {
+		progress: 0,
+		currentValue: 0,
+		velocity: 0
+	};
+	let status = "stopped";
+	let stopped = false;
+	let resolvePromise;
+	let currentSegmentIndex = 0;
+	let previousValue = resolveKeyframeValue(sorted[0]);
+	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 segmentProgress = 0;
+	let segmentElapsed = 0;
+	const play = () => {
+		if (status === "dead") throw new Error("Cannot play a dead animation");
+		stopped = false;
+		currentSegmentIndex = 0;
+		segmentElapsed = 0;
+		segmentProgress = 0;
+		state.progress = 0;
+		state.currentValue = segments[0].from;
+		previousValue = segments[0].from;
+		state.velocity = 0;
+		const promise = new Promise((resolve) => {
+			resolvePromise = resolve;
+		});
+		status = "playing";
+		ticker.add(update);
+		return promise;
+	};
+	const pause = () => {
+		if (status !== "playing") return;
+		status = "paused";
+		ticker.remove(update);
+	};
+	const resume = () => {
+		if (status !== "paused") return;
+		status = "playing";
+		ticker.add(update);
+	};
+	const stop = () => {
+		stopped = true;
+		status = "stopped";
+		ticker.remove(update);
+		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);
+		if (status === "playing" || status === "paused") onEnded?.();
+		status = "stopped";
+		ticker.remove(update);
+		resolvePromise?.(controls);
+		resolvePromise = void 0;
+	};
+	const kill = () => {
+		status = "dead";
+		ticker.remove(update);
+		stopped = true;
+		resolvePromise = void 0;
+	};
+	const controls = {
+		play,
+		pause,
+		resume,
+		stop,
+		skipToEnd,
+		kill,
+		setCurrentValue: (value) => {
+			state.currentValue = value;
+			state.velocity = 0;
+		},
+		get currentValue() {
+			return state.currentValue;
+		},
+		get velocity() {
+			return state.velocity;
+		},
+		get progress() {
+			return state.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);
+		},
+		get status() {
+			return status;
+		},
+		get durationMs() {
+			return totalDurationMs;
+		}
+	};
+	return controls;
+};
+//#endregion
+export { createAnimation };

package/dist/animation/update.d.ts

@@ -0,0 +1,12 @@
+import { EaseFunction } from '../shared/types';
+export type TweenState = {
+    progress: number;
+    currentValue: number;
+    velocity: number;
+};
+/**
+ * Advance a tween by one frame.
+ * Mutates `state` in place — zero allocation.
+ * Returns `true` if the tween has completed (progress >= 1).
+ */
+export declare const updateTween: (state: TweenState, deltaMs: number, durationMs: number, easeFn: EaseFunction, from: number, to: number) => boolean;

package/dist/animation/update.js

@@ -0,0 +1,22 @@
+//#region src/animation/update.ts
+/**
+* Advance a tween by one frame.
+* Mutates `state` in place — zero allocation.
+* Returns `true` if the tween has completed (progress >= 1).
+*/
+var updateTween = (state, deltaMs, durationMs, easeFn, from, to) => {
+	const thisFrameProgress = deltaMs / durationMs;
+	state.progress = Math.min(state.progress + thisFrameProgress, 1);
+	const previousValue = state.currentValue;
+	if (state.progress >= 1) {
+		state.currentValue = to;
+		state.velocity = 0;
+		return true;
+	}
+	const eased = easeFn(state.progress);
+	state.currentValue = from + (to - from) * eased;
+	state.velocity = (state.currentValue - previousValue) / (deltaMs / 1e3);
+	return false;
+};
+//#endregion
+export { updateTween };

package/dist/benchmarks/easing.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/benchmarks/vs-gsap.bench.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,26 @@
+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];

package/dist/color/lerp-oklab.js

@@ -0,0 +1,182 @@
+//#region src/color/lerp-oklab.ts
+/**
+* Pre-computed constants for Oklab conversion.
+*
+* sRGB → linear → LMS → LMS' (cube root) → Oklab
+*/
+var rgbToLmsMatrix = [
+	.4122214708,
+	.5363325363,
+	.0514459929,
+	.2119034982,
+	.6806995451,
+	.1073969566,
+	.0883024619,
+	.2817188376,
+	.6299787005
+];
+var lmsPrimeToLabMatrix = [
+	.2104542553,
+	.793617785,
+	-.0040720468,
+	1.9779984951,
+	-2.428592205,
+	.4505937099,
+	.0259040371,
+	.7827717662,
+	-.808675766
+];
+var labToLmsPrimeMatrix = [
+	1,
+	.3963377922,
+	.2158037583,
+	1,
+	-.1055613423,
+	-.0638541728,
+	1,
+	-.0894841825,
+	-1.2914855377
+];
+var lmsToLinearRgbMatrix = [
+	4.0767416621,
+	-3.3077115913,
+	.2309699292,
+	-1.2684380046,
+	2.6097574011,
+	-.3413193965,
+	-.0041960863,
+	-.7034186147,
+	1.707614701
+];
+/**
+* Convert a normalized sRGB channel to linear.
+*/
+var srgbToLinear = (channel) => {
+	if (channel <= .04045) return channel / 12.92;
+	return ((channel + .055) / 1.055) ** 2.4;
+};
+/**
+* Convert a linear channel to sRGB.
+*/
+var linearToSrgb = (channel) => {
+	if (channel <= .0031308) return channel * 12.92;
+	return 1.055 * channel ** (1 / 2.4) - .055;
+};
+/**
+* Convert an RGB tuple to Oklab [L, a, b].
+* All values in [0, 1] range (except a/b which can be negative).
+*/
+var rgbToOklab = (r, g, b) => {
+	const rLin = srgbToLinear(r);
+	const gLin = srgbToLinear(g);
+	const bLin = srgbToLinear(b);
+	const lLms = rgbToLmsMatrix[0] * rLin + rgbToLmsMatrix[1] * gLin + rgbToLmsMatrix[2] * bLin;
+	const mLms = rgbToLmsMatrix[3] * rLin + rgbToLmsMatrix[4] * gLin + rgbToLmsMatrix[5] * bLin;
+	const sLms = rgbToLmsMatrix[6] * rLin + rgbToLmsMatrix[7] * gLin + rgbToLmsMatrix[8] * bLin;
+	const lPrime = Math.cbrt(lLms);
+	const mPrime = Math.cbrt(mLms);
+	const sPrime = Math.cbrt(sLms);
+	return [
+		lmsPrimeToLabMatrix[0] * lPrime + lmsPrimeToLabMatrix[1] * mPrime + lmsPrimeToLabMatrix[2] * sPrime,
+		lmsPrimeToLabMatrix[3] * lPrime + lmsPrimeToLabMatrix[4] * mPrime + lmsPrimeToLabMatrix[5] * sPrime,
+		lmsPrimeToLabMatrix[6] * lPrime + lmsPrimeToLabMatrix[7] * mPrime + lmsPrimeToLabMatrix[8] * sPrime
+	];
+};
+/**
+* Convert an Oklab [L, a, b] tuple back to sRGB [R, G, B].
+* All values clamped to [0, 1].
+*/
+var oklabToRgb = (L, aL, bL) => {
+	const lPrime = labToLmsPrimeMatrix[0] * L + labToLmsPrimeMatrix[1] * aL + labToLmsPrimeMatrix[2] * bL;
+	const mPrime = labToLmsPrimeMatrix[3] * L + labToLmsPrimeMatrix[4] * aL + labToLmsPrimeMatrix[5] * bL;
+	const sPrime = labToLmsPrimeMatrix[6] * L + labToLmsPrimeMatrix[7] * aL + labToLmsPrimeMatrix[8] * bL;
+	const lLms = lPrime * lPrime * lPrime;
+	const mLms = mPrime * mPrime * mPrime;
+	const sLms = sPrime * sPrime * sPrime;
+	const rLin = lmsToLinearRgbMatrix[0] * lLms + lmsToLinearRgbMatrix[1] * mLms + lmsToLinearRgbMatrix[2] * sLms;
+	const gLin = lmsToLinearRgbMatrix[3] * lLms + lmsToLinearRgbMatrix[4] * mLms + lmsToLinearRgbMatrix[5] * sLms;
+	const bLin = lmsToLinearRgbMatrix[6] * lLms + lmsToLinearRgbMatrix[7] * mLms + lmsToLinearRgbMatrix[8] * sLms;
+	return [
+		clamp(linearToSrgb(rLin)),
+		clamp(linearToSrgb(gLin)),
+		clamp(linearToSrgb(bLin))
+	];
+};
+/**
+* Clamp a value to [0, 1].
+*/
+var clamp = (value) => {
+	if (value < 0) return 0;
+	if (value > 1) return 1;
+	return value;
+};
+/**
+* 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.
+*/
+var lerpOklab = (from, to, progress) => {
+	const clampedProgress = clamp(progress);
+	const [lFrom, aFrom, bFrom] = rgbToOklab(from[0], from[1], from[2]);
+	const [lTo, aTo, bTo] = rgbToOklab(to[0], to[1], to[2]);
+	const [r, g, b] = oklabToRgb(lFrom + (lTo - lFrom) * clampedProgress, aFrom + (aTo - aFrom) * clampedProgress, bFrom + (bTo - bFrom) * clampedProgress);
+	return [
+		r,
+		g,
+		b,
+		clamp(from[3] + (to[3] - from[3]) * clampedProgress)
+	];
+};
+/**
+* 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.
+*/
+var hexToRgba = (hex) => {
+	const cleaned = hex.startsWith("#") ? hex.slice(1) : hex;
+	if (!/^[0-9a-fA-F]+$/.test(cleaned)) return [
+		0,
+		0,
+		0,
+		1
+	];
+	if (cleaned.length === 3) return [
+		parseInt(cleaned[0] + cleaned[0], 16) / 255,
+		parseInt(cleaned[1] + cleaned[1], 16) / 255,
+		parseInt(cleaned[2] + cleaned[2], 16) / 255,
+		1
+	];
+	if (cleaned.length === 4) return [
+		parseInt(cleaned[0] + cleaned[0], 16) / 255,
+		parseInt(cleaned[1] + cleaned[1], 16) / 255,
+		parseInt(cleaned[2] + cleaned[2], 16) / 255,
+		parseInt(cleaned[3] + cleaned[3], 16) / 255
+	];
+	if (cleaned.length >= 6) return [
+		parseInt(cleaned.slice(0, 2), 16) / 255,
+		parseInt(cleaned.slice(2, 4), 16) / 255,
+		parseInt(cleaned.slice(4, 6), 16) / 255,
+		cleaned.length >= 8 ? parseInt(cleaned.slice(6, 8), 16) / 255 : 1
+	];
+	return [
+		0,
+		0,
+		0,
+		1
+	];
+};
+//#endregion
+export { hexToRgba, lerpOklab };

package/dist/easing/easing.d.ts

@@ -0,0 +1,16 @@
+import { EaseName, EaseFunction } from '../shared/types';
+/** All 31 named easing identifiers, ordered by type. */
+export declare const EASE_NAMES: EaseName[];
+export declare const easingFunctions: Record<EaseName, EaseFunction>;
+/**
+ * Cubic bezier easing. Builds a pre-computed lookup table at construction time
+ * for O(log n) binary search at runtime — no Newton iteration, no allocation
+ * per frame.
+ *
+ * @param p1x - First control point x coordinate.
+ * @param p1y - First control point y coordinate.
+ * @param p2x - Second control point x coordinate.
+ * @param p2y - Second control point y coordinate.
+ * @returns An EaseFunction suitable for use with animate() or createTimeline().
+ */
+export declare const cubicBezier: (p1x: number, p1y: number, p2x: number, p2y: number) => EaseFunction;