@vune-ui/animation 0.1.20

package/dist/src/gesture/index.js

@@ -0,0 +1,376 @@
+import { defaultEngine } from '../core/default-engine.js';
+import { inertia as inertiaSpec } from '../core/kinetics.js';
+import { spring } from '../core/specs.js';
+
+const DEFAULT_WINDOW_MS = 120;
+const DEFAULT_MAX_SAMPLES = 12;
+
+function nowMs() {
+  return globalThis.performance?.now?.() ?? Date.now();
+}
+
+function finite(value, fallback = 0) {
+  return Number.isFinite(value) ? Number(value) : fallback;
+}
+
+export class VelocityTracker {
+  constructor({ windowMs = DEFAULT_WINDOW_MS, maxSamples = DEFAULT_MAX_SAMPLES, maxVelocity = 100000 } = {}) {
+    this.windowMs = Math.max(16, finite(windowMs, DEFAULT_WINDOW_MS));
+    this.maxSamples = Math.max(2, Math.floor(finite(maxSamples, DEFAULT_MAX_SAMPLES)));
+    this.maxVelocity = Math.max(1, finite(maxVelocity, 100000));
+    this.values = new Float64Array(this.maxSamples);
+    this.times = new Float64Array(this.maxSamples);
+    this.head = 0;
+    this.count = 0;
+  }
+
+  #index(logicalIndex) {
+    return (this.head + logicalIndex) % this.maxSamples;
+  }
+
+  reset(value, time = nowMs()) {
+    this.head = 0;
+    this.count = 0;
+    this.add(value, time);
+    return this;
+  }
+
+  add(value, time = nowMs()) {
+    value = finite(value);
+    time = finite(time, nowMs());
+    if (this.count > 0) {
+      const lastIndex = this.#index(this.count - 1);
+      const lastTime = this.times[lastIndex];
+      if (time < lastTime) return this;
+      if (time === lastTime) {
+        this.values[lastIndex] = value;
+        return this;
+      }
+    }
+
+    let index;
+    if (this.count < this.maxSamples) {
+      index = this.#index(this.count);
+      this.count += 1;
+    } else {
+      this.head = (this.head + 1) % this.maxSamples;
+      index = this.#index(this.count - 1);
+    }
+    this.values[index] = value;
+    this.times[index] = time;
+
+    const cutoff = time - this.windowMs;
+    while (this.count > 2 && this.times[this.head] < cutoff) {
+      this.head = (this.head + 1) % this.maxSamples;
+      this.count -= 1;
+    }
+    return this;
+  }
+
+  get velocity() {
+    if (this.count < 2) return 0;
+    const latestIndex = this.#index(this.count - 1);
+    const latest = this.times[latestIndex];
+    const weightScale = Math.max(24, this.windowMs * 0.55);
+    let weightSum = 0;
+    let meanT = 0;
+    let meanX = 0;
+
+    for (let i = 0; i < this.count; i += 1) {
+      const index = this.#index(i);
+      const ageMs = latest - this.times[index];
+      const weight = Math.exp(-ageMs / weightScale);
+      const t = (this.times[index] - latest) / 1000;
+      weightSum += weight;
+      meanT += t * weight;
+      meanX += this.values[index] * weight;
+    }
+    if (weightSum <= 0) return 0;
+    meanT /= weightSum;
+    meanX /= weightSum;
+
+    let numerator = 0;
+    let denominator = 0;
+    for (let i = 0; i < this.count; i += 1) {
+      const index = this.#index(i);
+      const ageMs = latest - this.times[index];
+      const weight = Math.exp(-ageMs / weightScale);
+      const t = (this.times[index] - latest) / 1000 - meanT;
+      const x = this.values[index] - meanX;
+      numerator += weight * t * x;
+      denominator += weight * t * t;
+    }
+    if (denominator < 1e-9) return 0;
+    const velocity = numerator / denominator;
+    return Math.max(-this.maxVelocity, Math.min(this.maxVelocity, velocity));
+  }
+}
+
+export function rubberBandDistance(distance, dimension = 320, constant = 0.55) {
+  const sign = Math.sign(distance);
+  const d = Math.abs(finite(distance));
+  const size = Math.max(1, Math.abs(finite(dimension, 320)));
+  const c = Math.max(0, finite(constant, 0.55));
+  if (d === 0 || c === 0) return 0;
+  return sign * ((d * c * size) / (size + c * d));
+}
+
+export function constrainWithRubberBand(value, min = -Infinity, max = Infinity, {
+  enabled = true,
+  constant = 0.55,
+  dimension,
+} = {}) {
+  if (min > max) throw new RangeError('min cannot be greater than max.');
+  if (value < min) {
+    if (!enabled) return min;
+    const size = dimension ?? (Number.isFinite(max - min) ? max - min : 320);
+    return min + rubberBandDistance(value - min, size, constant);
+  }
+  if (value > max) {
+    if (!enabled) return max;
+    const size = dimension ?? (Number.isFinite(max - min) ? max - min : 320);
+    return max + rubberBandDistance(value - max, size, constant);
+  }
+  return value;
+}
+
+function resolveBounds(bounds) {
+  const source = typeof bounds === 'function' ? bounds() : bounds;
+  return {
+    minX: Number.isFinite(source?.minX) ? source.minX : -Infinity,
+    maxX: Number.isFinite(source?.maxX) ? source.maxX : Infinity,
+    minY: Number.isFinite(source?.minY) ? source.minY : -Infinity,
+    maxY: Number.isFinite(source?.maxY) ? source.maxY : Infinity,
+  };
+}
+
+function nearestSnap(target, points) {
+  if (typeof points === 'function') {
+    const value = Number(points(target));
+    return Number.isFinite(value) ? value : target;
+  }
+  if (!Array.isArray(points) || points.length === 0) return target;
+  let best = target;
+  let bestDistance = Infinity;
+  for (const point of points) {
+    if (!Number.isFinite(point)) continue;
+    const distance = Math.abs(point - target);
+    if (distance < bestDistance) {
+      best = point;
+      bestDistance = distance;
+    }
+  }
+  return best;
+}
+
+function groupControls(controls) {
+  const active = controls.filter(Boolean);
+  return {
+    cancel() { for (const control of active) control.cancel(); },
+    finish() { for (const control of active) control.finish(); },
+    finished: Promise.all(active.map((control) => control.finished)),
+  };
+}
+
+export class DragController {
+  constructor({
+    x = null,
+    y = null,
+    axis = 'both',
+    engine = defaultEngine,
+    bounds = null,
+    momentum = true,
+    inertia = {},
+    rubberBand = true,
+    rubberBandConstant = 0.55,
+    rubberBandDimension,
+    directionLock = false,
+    directionLockThreshold = 8,
+    snapX = null,
+    snapY = null,
+    settle = {},
+    velocity = {},
+    onStart,
+    onMove,
+    onEnd,
+  } = {}) {
+    if (!['x', 'y', 'both'].includes(axis)) throw new TypeError("axis must be 'x', 'y', or 'both'.");
+    if ((axis === 'x' || axis === 'both') && !x?.set) throw new TypeError('DragController requires x MotionValue for the selected axis.');
+    if ((axis === 'y' || axis === 'both') && !y?.set) throw new TypeError('DragController requires y MotionValue for the selected axis.');
+    this.x = x;
+    this.y = y;
+    this.axis = axis;
+    this.engine = engine;
+    this.boundsSource = bounds;
+    this.momentum = momentum;
+    this.inertiaOptions = inertia;
+    this.rubberBand = rubberBand;
+    this.rubberBandConstant = rubberBandConstant;
+    this.rubberBandDimension = rubberBandDimension;
+    this.directionLock = directionLock;
+    this.directionLockThreshold = Math.max(0, directionLockThreshold);
+    this.snapX = snapX;
+    this.snapY = snapY;
+    this.settleOptions = settle;
+    this.onStart = onStart;
+    this.onMove = onMove;
+    this.onEnd = onEnd;
+    this.trackerX = new VelocityTracker(velocity);
+    this.trackerY = new VelocityTracker(velocity);
+    this.active = false;
+    this.lockedAxis = null;
+    this.startPoint = { x: 0, y: 0 };
+    this.startValue = { x: 0, y: 0 };
+    this.lastPoint = { x: 0, y: 0 };
+  }
+
+  #axisEnabled(axis) {
+    if (this.lockedAxis) return this.lockedAxis === axis;
+    return this.axis === 'both' || this.axis === axis;
+  }
+
+  #rubberOptions(axis, bounds) {
+    const enabled = this.rubberBand !== false;
+    const constant = typeof this.rubberBand === 'number' ? this.rubberBand : this.rubberBandConstant;
+    const dimension = typeof this.rubberBandDimension === 'object'
+      ? this.rubberBandDimension?.[axis]
+      : this.rubberBandDimension;
+    return { enabled, constant, dimension };
+  }
+
+  start(point, time = nowMs()) {
+    const px = finite(point?.x);
+    const py = finite(point?.y);
+    if (this.x) this.engine.stop(this.x, 'interrupted');
+    if (this.y) this.engine.stop(this.y, 'interrupted');
+    this.active = true;
+    this.lockedAxis = null;
+    this.startPoint = { x: px, y: py };
+    this.lastPoint = { x: px, y: py };
+    this.startValue = { x: this.x?.get?.() ?? 0, y: this.y?.get?.() ?? 0 };
+    this.trackerX.reset(px, time);
+    this.trackerY.reset(py, time);
+    const state = this.getState();
+    this.onStart?.(state);
+    return state;
+  }
+
+  move(point, time = nowMs()) {
+    if (!this.active) return this.getState();
+    const px = finite(point?.x, this.lastPoint.x);
+    const py = finite(point?.y, this.lastPoint.y);
+    this.lastPoint = { x: px, y: py };
+    this.trackerX.add(px, time);
+    this.trackerY.add(py, time);
+
+    const dx = px - this.startPoint.x;
+    const dy = py - this.startPoint.y;
+    if (this.directionLock && !this.lockedAxis) {
+      if (Math.hypot(dx, dy) < this.directionLockThreshold) {
+        const state = this.getState();
+        this.onMove?.(state);
+        return state;
+      }
+      this.lockedAxis = this.axis === 'both'
+        ? (Math.abs(dx) >= Math.abs(dy) ? 'x' : 'y')
+        : this.axis;
+    }
+
+    const bounds = resolveBounds(this.boundsSource);
+    if (this.x && this.#axisEnabled('x')) {
+      const raw = this.startValue.x + dx;
+      const next = constrainWithRubberBand(raw, bounds.minX, bounds.maxX, this.#rubberOptions('x', bounds));
+      this.x.set(next, this.trackerX.velocity);
+    }
+    if (this.y && this.#axisEnabled('y')) {
+      const raw = this.startValue.y + dy;
+      const next = constrainWithRubberBand(raw, bounds.minY, bounds.maxY, this.#rubberOptions('y', bounds));
+      this.y.set(next, this.trackerY.velocity);
+    }
+
+    const state = this.getState();
+    this.onMove?.(state);
+    return state;
+  }
+
+  #releaseAxis(axis, motion, velocity, min, max, snap) {
+    if (!motion || !this.#axisEnabled(axis)) return null;
+    const current = motion.get();
+    const outside = current < min || current > max;
+    if (!this.momentum && !outside) {
+      motion.set(current, 0);
+      return null;
+    }
+
+    if (!this.momentum && outside) {
+      const target = Math.max(min, Math.min(max, current));
+      return this.engine.animate(motion, target, spring({
+        response: this.settleOptions.response ?? 0.28,
+        dampingRatio: this.settleOptions.dampingRatio ?? 0.82,
+        initialVelocity: velocity,
+      }));
+    }
+
+    const userModify = this.inertiaOptions.modifyTarget;
+    const modifyTarget = (target) => {
+      const modified = typeof userModify === 'function' ? userModify(target, axis) : target;
+      return nearestSnap(modified, snap);
+    };
+    return this.engine.animateVelocity(motion, inertiaSpec({
+      ...this.inertiaOptions,
+      velocity,
+      min,
+      max,
+      modifyTarget,
+    }));
+  }
+
+  end(time = nowMs()) {
+    if (!this.active) return { ...this.getState(), controls: groupControls([]) };
+    this.trackerX.add(this.lastPoint.x, time);
+    this.trackerY.add(this.lastPoint.y, time);
+    this.active = false;
+    const velocity = { x: this.trackerX.velocity, y: this.trackerY.velocity };
+    const bounds = resolveBounds(this.boundsSource);
+    const controls = [
+      this.#releaseAxis('x', this.x, velocity.x, bounds.minX, bounds.maxX, this.snapX),
+      this.#releaseAxis('y', this.y, velocity.y, bounds.minY, bounds.maxY, this.snapY),
+    ];
+    const result = { ...this.getState(), velocity, controls: groupControls(controls) };
+    this.onEnd?.(result);
+    return result;
+  }
+
+  cancel({ settle = true } = {}) {
+    if (!this.active) return this.getState();
+    this.active = false;
+    if (settle) {
+      const bounds = resolveBounds(this.boundsSource);
+      for (const [axis, motion, min, max] of [
+        ['x', this.x, bounds.minX, bounds.maxX],
+        ['y', this.y, bounds.minY, bounds.maxY],
+      ]) {
+        if (!motion || !this.#axisEnabled(axis)) continue;
+        const target = Math.max(min, Math.min(max, motion.get()));
+        if (target !== motion.get()) this.engine.animate(motion, target, spring({ response: 0.25, dampingRatio: 0.9 }));
+        else motion.set(motion.get(), 0);
+      }
+    }
+    return this.getState();
+  }
+
+  getState() {
+    return {
+      active: this.active,
+      axis: this.axis,
+      lockedAxis: this.lockedAxis,
+      point: { ...this.lastPoint },
+      value: { x: this.x?.get?.() ?? null, y: this.y?.get?.() ?? null },
+      velocity: { x: this.trackerX.velocity, y: this.trackerY.velocity },
+    };
+  }
+}
+
+export function createDragController(options) {
+  return new DragController(options);
+}

package/dist/src/index.js

@@ -0,0 +1,53 @@
+export { MotionValue, motionValue } from './core/motion-value.js';
+export { MotionEngine } from './core/engine.js';
+export { FrameBudgetGovernor } from './core/frame-budget.js';
+export { compileEasing, evaluateCompiledEasing, derivativeCompiledEasing } from './core/easing.js';
+export { AnimationControls } from './core/controls.js';
+export { animate, animateVelocity, animateDecay, animateInertia, defaultEngine } from './core/default-engine.js';
+export { compileMotionPlan, resolveMotionPlan, isMotionExecutionPlan } from './core/planner.js';
+export {
+  spring,
+  timing,
+  cubicBezier,
+  curves,
+  smooth,
+  snappy,
+  bouncy,
+  gentle,
+  interactive,
+  resolveMotionSpec,
+} from './core/specs.js';
+export { delay, parallel, sequence } from './core/composition.js';
+export {
+  decay,
+  inertia,
+  projectDecayTarget,
+  stepDecay,
+  stepDampedSpring,
+} from './core/kinetics.js';
+export {
+  animateInterpolated,
+  createInterpolator,
+  interpolateNumber,
+  interpolateColor,
+  mixColor,
+  parseColor,
+  formatColor,
+  interpolateTransform,
+  mixTransform,
+  parseTransform,
+  formatTransform,
+} from './interpolate/index.js';
+
+export { parsePath, normalizePathPair, PathMorpher, createPathMorpher, interpolatePath } from './path/index.js';
+export { materials, resolveMaterial, mixMaterial, interpolateMaterial, materialToCss } from './material/index.js';
+
+export { VelocityTracker, DragController, createDragController, rubberBandDistance, constrainWithRubberBand } from './gesture/index.js';
+
+export { Timeline, TimelinePlayer, PhaseTimeline, TimelineScrubber, timeline, createPhaseTimeline, createTimelineScrubber, stagger } from './timeline/index.js';
+
+export { StateTransitionGraph, TransitionController, PresenceController, createStateTransitionGraph, createTransition, createPresence } from './transition/index.js';
+
+export { ScrollTracker, ScrollObserver, ScrollTimelineLink, createScrollTracker, observeScroll, readScrollMetrics, bindScrollTimeline } from './scroll/index.js';
+export { ConstraintNode, ConstraintGraph, createConstraintGraph } from './constraints/index.js';
+export { WebGPUSpringBatch } from './webgpu/index.js';

package/dist/src/interpolate/color.js

@@ -0,0 +1,223 @@
+const NAMED = Object.freeze({
+  transparent: [0, 0, 0, 0],
+  black: [0, 0, 0, 1],
+  white: [1, 1, 1, 1],
+  red: [1, 0, 0, 1],
+  green: [0, 0.5019607843, 0, 1],
+  blue: [0, 0, 1, 1],
+  yellow: [1, 1, 0, 1],
+  cyan: [0, 1, 1, 1],
+  aqua: [0, 1, 1, 1],
+  magenta: [1, 0, 1, 1],
+  fuchsia: [1, 0, 1, 1],
+  gray: [0.5019607843, 0.5019607843, 0.5019607843, 1],
+  grey: [0.5019607843, 0.5019607843, 0.5019607843, 1],
+});
+
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+const lerp = (a, b, t) => a + (b - a) * t;
+
+function parseRgbChannel(token) {
+  const value = token.trim();
+  if (value.endsWith('%')) return clamp01(Number.parseFloat(value) / 100);
+  return clamp01(Number.parseFloat(value) / 255);
+}
+
+function parseAlpha(token = '1') {
+  const value = token.trim();
+  if (value.endsWith('%')) return clamp01(Number.parseFloat(value) / 100);
+  return clamp01(Number.parseFloat(value));
+}
+
+function parseAngle(token) {
+  const value = token.trim().toLowerCase();
+  if (value.endsWith('turn')) return Number.parseFloat(value) * 360;
+  if (value.endsWith('rad')) return Number.parseFloat(value) * 180 / Math.PI;
+  if (value.endsWith('grad')) return Number.parseFloat(value) * 0.9;
+  return Number.parseFloat(value);
+}
+
+function hslToRgb(h, s, l) {
+  const hue = ((h % 360) + 360) % 360 / 360;
+  if (s === 0) return [l, l, l];
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const channel = (offset) => {
+    let t = hue + offset;
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+  return [channel(1 / 3), channel(0), channel(-1 / 3)];
+}
+
+function splitFunctionalBody(body) {
+  const slash = body.split('/');
+  const main = slash[0].trim();
+  const alpha = slash[1]?.trim();
+  const parts = main.includes(',')
+    ? main.split(',').map((part) => part.trim()).filter(Boolean)
+    : main.split(/\s+/).filter(Boolean);
+  if (parts.length === 4 && alpha == null) return { parts: parts.slice(0, 3), alpha: parts[3] };
+  return { parts, alpha };
+}
+
+export function parseColor(input) {
+  if (input && typeof input === 'object') {
+    if (Array.isArray(input) && input.length >= 3) {
+      return { r: clamp01(Number(input[0])), g: clamp01(Number(input[1])), b: clamp01(Number(input[2])), a: clamp01(Number(input[3] ?? 1)) };
+    }
+    if ('r' in input && 'g' in input && 'b' in input) {
+      return { r: clamp01(Number(input.r)), g: clamp01(Number(input.g)), b: clamp01(Number(input.b)), a: clamp01(Number(input.a ?? 1)) };
+    }
+  }
+
+  if (typeof input !== 'string') throw new TypeError('Color must be a CSS color string or {r,g,b,a}.');
+  const text = input.trim().toLowerCase();
+  if (NAMED[text]) {
+    const [r, g, b, a] = NAMED[text];
+    return { r, g, b, a };
+  }
+
+  if (text.startsWith('#')) {
+    const hex = text.slice(1);
+    if (![3, 4, 6, 8].includes(hex.length) || !/^[0-9a-f]+$/i.test(hex)) throw new TypeError(`Unsupported hex color: ${input}`);
+    const expanded = hex.length <= 4 ? [...hex].map((char) => char + char).join('') : hex;
+    const value = Number.parseInt(expanded, 16);
+    if (expanded.length === 6) {
+      return { r: ((value >> 16) & 255) / 255, g: ((value >> 8) & 255) / 255, b: (value & 255) / 255, a: 1 };
+    }
+    return { r: ((value >> 24) & 255) / 255, g: ((value >> 16) & 255) / 255, b: ((value >> 8) & 255) / 255, a: (value & 255) / 255 };
+  }
+
+  let match = text.match(/^rgba?\((.*)\)$/);
+  if (match) {
+    const { parts, alpha } = splitFunctionalBody(match[1]);
+    if (parts.length !== 3) throw new TypeError(`Invalid rgb() color: ${input}`);
+    return { r: parseRgbChannel(parts[0]), g: parseRgbChannel(parts[1]), b: parseRgbChannel(parts[2]), a: parseAlpha(alpha) };
+  }
+
+  match = text.match(/^hsla?\((.*)\)$/);
+  if (match) {
+    const { parts, alpha } = splitFunctionalBody(match[1]);
+    if (parts.length !== 3 || !parts[1].endsWith('%') || !parts[2].endsWith('%')) throw new TypeError(`Invalid hsl() color: ${input}`);
+    const [r, g, b] = hslToRgb(parseAngle(parts[0]), clamp01(Number.parseFloat(parts[1]) / 100), clamp01(Number.parseFloat(parts[2]) / 100));
+    return { r, g, b, a: parseAlpha(alpha) };
+  }
+
+  throw new TypeError(`Unsupported color syntax: ${input}`);
+}
+
+export function formatColor(color) {
+  const r = Math.round(clamp01(color.r) * 255);
+  const g = Math.round(clamp01(color.g) * 255);
+  const b = Math.round(clamp01(color.b) * 255);
+  const a = Math.round(clamp01(color.a ?? 1) * 10000) / 10000;
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+export function srgbToLinear(value) {
+  const c = clamp01(value);
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+export function linearToSrgb(value) {
+  const c = Math.max(0, value);
+  return clamp01(c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055);
+}
+
+export function linearRgbToOklab({ r, g, b }) {
+  const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+  const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+  const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+  const l3 = Math.cbrt(l);
+  const m3 = Math.cbrt(m);
+  const s3 = Math.cbrt(s);
+  return {
+    l: 0.2104542553 * l3 + 0.793617785 * m3 - 0.0040720468 * s3,
+    a: 1.9779984951 * l3 - 2.428592205 * m3 + 0.4505937099 * s3,
+    b: 0.0259040371 * l3 + 0.7827717662 * m3 - 0.808675766 * s3,
+  };
+}
+
+export function oklabToLinearRgb({ l, a, b }) {
+  const lp = l + 0.3963377774 * a + 0.2158037573 * b;
+  const mp = l - 0.1055613458 * a - 0.0638541728 * b;
+  const sp = l - 0.0894841775 * a - 1.291485548 * b;
+  const l3 = lp ** 3;
+  const m3 = mp ** 3;
+  const s3 = sp ** 3;
+  return {
+    r: 4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3,
+    g: -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3,
+    b: -0.0041960863 * l3 - 0.7034186147 * m3 + 1.707614701 * s3,
+  };
+}
+
+function toLinear(color) {
+  return { r: srgbToLinear(color.r), g: srgbToLinear(color.g), b: srgbToLinear(color.b) };
+}
+
+function fromLinear(color, alpha) {
+  return { r: linearToSrgb(color.r), g: linearToSrgb(color.g), b: linearToSrgb(color.b), a: alpha };
+}
+
+function shortestHue(from, to) {
+  let delta = (to - from) % 360;
+  if (delta > 180) delta -= 360;
+  if (delta < -180) delta += 360;
+  return delta;
+}
+
+export function mixColor(fromInput, toInput, t, { space = 'oklab' } = {}) {
+  let from = parseColor(fromInput);
+  let to = parseColor(toInput);
+  const progress = clamp01(t);
+  const alpha = lerp(from.a, to.a, progress);
+
+  // CSS transparent is transparent black. Borrow the visible endpoint's chroma
+  // when one side is fully transparent so fades do not pass through a dark halo.
+  if (from.a <= 1e-8 && to.a > 1e-8) from = { ...from, r: to.r, g: to.g, b: to.b };
+  if (to.a <= 1e-8 && from.a > 1e-8) to = { ...to, r: from.r, g: from.g, b: from.b };
+
+  if (space === 'srgb') {
+    return { r: lerp(from.r, to.r, progress), g: lerp(from.g, to.g, progress), b: lerp(from.b, to.b, progress), a: alpha };
+  }
+
+  const fromLinearColor = toLinear(from);
+  const toLinearColor = toLinear(to);
+  if (space === 'linear-srgb') {
+    return fromLinear({
+      r: lerp(fromLinearColor.r, toLinearColor.r, progress),
+      g: lerp(fromLinearColor.g, toLinearColor.g, progress),
+      b: lerp(fromLinearColor.b, toLinearColor.b, progress),
+    }, alpha);
+  }
+
+  const a = linearRgbToOklab(fromLinearColor);
+  const b = linearRgbToOklab(toLinearColor);
+  let lab;
+  if (space === 'oklch') {
+    const c1 = Math.hypot(a.a, a.b);
+    const c2 = Math.hypot(b.a, b.b);
+    const h1 = Math.atan2(a.b, a.a) * 180 / Math.PI;
+    const h2 = Math.atan2(b.b, b.a) * 180 / Math.PI;
+    const c = lerp(c1, c2, progress);
+    const h = h1 + shortestHue(h1, h2) * progress;
+    lab = { l: lerp(a.l, b.l, progress), a: c * Math.cos(h * Math.PI / 180), b: c * Math.sin(h * Math.PI / 180) };
+  } else if (space === 'oklab') {
+    lab = { l: lerp(a.l, b.l, progress), a: lerp(a.a, b.a, progress), b: lerp(a.b, b.b, progress) };
+  } else {
+    throw new TypeError(`Unknown color interpolation space: ${space}`);
+  }
+  return fromLinear(oklabToLinearRgb(lab), alpha);
+}
+
+export function interpolateColor(from, to, options) {
+  const start = parseColor(from);
+  const end = parseColor(to);
+  return (progress) => formatColor(mixColor(start, end, progress, options));
+}

package/dist/src/interpolate/css.d.ts

@@ -0,0 +1,13 @@
+export {
+  createInterpolator,
+  interpolateNumber,
+  interpolateColor,
+  mixColor,
+  parseColor,
+  formatColor,
+  interpolateTransform,
+  mixTransform,
+  parseTransform,
+  formatTransform,
+} from '../../index.js';
+export type { InterpolatorOptions } from '../../index.js';

package/dist/src/interpolate/css.js

@@ -0,0 +1,34 @@
+import { interpolateColor } from './color.js';
+import { interpolateTransform } from './transform.js';
+
+export * from './color.js';
+export * from './transform.js';
+
+export function interpolateNumber(from, to) {
+  const a = Number(from);
+  const b = Number(to);
+  if (!Number.isFinite(a) || !Number.isFinite(b)) throw new TypeError('Numeric interpolation requires finite numbers.');
+  return (progress) => a + (b - a) * progress;
+}
+
+/**
+ * Lean CSS-oriented interpolator. Unlike the broad interpolate entry point,
+ * this module intentionally does not statically import SVG path or material
+ * interpolation, so DOM-only consumers do not pay for those feature families.
+ */
+export function createInterpolator(from, to, options = {}) {
+  if (typeof options.interpolate === 'function') return (progress) => options.interpolate(from, to, progress);
+  if (typeof from === 'number' && typeof to === 'number') return interpolateNumber(from, to);
+  if (options.type === 'transform' || (typeof from === 'object' && from !== null && typeof to === 'object' && to !== null && ('x' in from || 'scale' in from || 'rotate' in from))) {
+    return interpolateTransform(from, to, options.transform);
+  }
+  if (options.type === 'color') return interpolateColor(from, to, options.color);
+  if (options.type === 'path' || options.type === 'material') {
+    throw new TypeError(`The CSS interpolator does not include ${options.type} interpolation. Import from @vune-ui/animation/interpolate for that feature.`);
+  }
+  if (typeof from === 'string' && typeof to === 'string') {
+    try { return interpolateColor(from, to, options.color); } catch {}
+    try { return interpolateTransform(from, to, options.transform); } catch {}
+  }
+  throw new TypeError('No CSS interpolator is available for these values. Pass options.type or options.interpolate.');
+}