@vune-ui/animation 0.1.20

package/dist/src/core/frame-budget.js

@@ -0,0 +1,30 @@
+import { FrameBudgetGovernor as ExecutionFrameBudgetGovernor } from '@vune-ui/execution';
+
+// Backend threshold policy remains animation-owned. The sampling, EMA,
+// pressure, and subscription signal are shared with other execution clients.
+export class FrameBudgetGovernor extends ExecutionFrameBudgetGovernor {
+  constructor({
+    budgetMs = 8,
+    alpha = 0.12,
+    minWasmThreshold = 64,
+    minWorkerThreshold = 512,
+  } = {}) {
+    super({ budgetMs, alpha });
+    this.minWasmThreshold = Math.max(1, Math.floor(minWasmThreshold));
+    this.minWorkerThreshold = Math.max(this.minWasmThreshold, Math.floor(minWorkerThreshold));
+  }
+
+  wasmThreshold(baseThreshold, activeCount) {
+    const base = Math.max(1, Math.floor(baseThreshold));
+    if (this.pressure < 0.75 || activeCount < this.minWasmThreshold) return base;
+    const pressureScale = this.pressure >= 1.15 ? 0.35 : 0.6;
+    return Math.max(this.minWasmThreshold, Math.min(base, Math.floor(base * pressureScale)));
+  }
+
+  workerThreshold(baseThreshold, activeCount) {
+    const base = Math.max(1, Math.floor(baseThreshold));
+    if (this.pressure < 1 || activeCount < this.minWorkerThreshold) return base;
+    const pressureScale = this.pressure >= 1.35 ? 0.35 : 0.6;
+    return Math.max(this.minWorkerThreshold, Math.min(base, Math.floor(base * pressureScale)));
+  }
+}

package/dist/src/core/index.d.ts

@@ -0,0 +1,43 @@
+export {
+  MotionValue,
+  motionValue,
+  AnimationControls,
+  animate,
+  animateVelocity,
+  animateDecay,
+  animateInertia,
+  defaultEngine,
+  compileMotionPlan,
+  resolveMotionPlan,
+  isMotionExecutionPlan,
+  spring,
+  timing,
+  cubicBezier,
+  curves,
+  smooth,
+  snappy,
+  bouncy,
+  gentle,
+  interactive,
+  resolveMotionSpec,
+  compileEasing,
+  evaluateCompiledEasing,
+  derivativeCompiledEasing,
+} from '../../index.js';
+export type {
+  AnimationResult,
+  AnimationStatus,
+  MotionExecutionPlan,
+  ResolvedMotionExecutionPlan,
+  MotionSpec,
+  SpringSpec,
+  TimingSpec,
+  ProfileSpec,
+  DecayOptions,
+  DecaySpec,
+  InertiaOptions,
+  InertiaSpec,
+  VelocityAnimationSpec,
+  BezierCurve,
+  CompiledEasing,
+} from '../../index.js';

package/dist/src/core/index.js

@@ -0,0 +1,17 @@
+export { MotionValue, motionValue } from './motion-value.js';
+export { AnimationControls } from './controls.js';
+export { animate, animateVelocity, animateDecay, animateInertia, defaultEngine } from './default-engine.js';
+export { compileMotionPlan, resolveMotionPlan, isMotionExecutionPlan } from './planner.js';
+export {
+  spring,
+  timing,
+  cubicBezier,
+  curves,
+  smooth,
+  snappy,
+  bouncy,
+  gentle,
+  interactive,
+  resolveMotionSpec,
+} from './specs.js';
+export { compileEasing, evaluateCompiledEasing, derivativeCompiledEasing } from './easing.js';

package/dist/src/core/js-spring-batch.js

@@ -0,0 +1,57 @@
+const MAX_STEP_SECONDS = 1 / 240;
+const MAX_SUBSTEPS = 32;
+
+export class JsSpringBatch {
+  constructor(capacity = 256) {
+    this.kind = 'js';
+    this.capacity = capacity;
+    this.positions = new Float32Array(capacity);
+    this.velocities = new Float32Array(capacity);
+    this.targets = new Float32Array(capacity);
+    this.omegas = new Float32Array(capacity);
+    this.dampingRatios = new Float32Array(capacity);
+  }
+
+  ensureCapacity(required) {
+    if (required <= this.capacity) return;
+    let next = this.capacity;
+    while (next < required) next *= 2;
+    for (const key of ['positions', 'velocities', 'targets', 'omegas', 'dampingRatios']) {
+      const old = this[key];
+      const replacement = new Float32Array(next);
+      replacement.set(old);
+      this[key] = replacement;
+    }
+    this.capacity = next;
+  }
+
+  copyInto(other, count) {
+    other.positions.set(this.positions.subarray(0, count));
+    other.velocities.set(this.velocities.subarray(0, count));
+    other.targets.set(this.targets.subarray(0, count));
+    other.omegas.set(this.omegas.subarray(0, count));
+    other.dampingRatios.set(this.dampingRatios.subarray(0, count));
+  }
+
+  step(count, dtSeconds) {
+    if (count === 0 || dtSeconds <= 0) return;
+    let steps = 1;
+    while (dtSeconds / steps > MAX_STEP_SECONDS && steps < MAX_SUBSTEPS) steps += 1;
+    const h = dtSeconds / steps;
+
+    for (let s = 0; s < steps; s += 1) {
+      for (let i = 0; i < count; i += 1) {
+        let x = this.positions[i];
+        let v = this.velocities[i];
+        const target = this.targets[i];
+        const omega = this.omegas[i];
+        const zeta = this.dampingRatios[i];
+        const acceleration = omega * omega * (target - x) - 2 * zeta * omega * v;
+        v += acceleration * h;
+        x += v * h;
+        this.positions[i] = x;
+        this.velocities[i] = v;
+      }
+    }
+  }
+}

package/dist/src/core/kinetics.js

@@ -0,0 +1,140 @@
+import { clamp, springParamsFromResponse } from './math.js';
+
+const DEFAULT_TAU = 0.325;
+const DEFAULT_REST_SPEED = 5;
+const DEFAULT_REST_DELTA = 0.5;
+
+function finiteOr(value, fallback) {
+  return Number.isFinite(value) ? Number(value) : fallback;
+}
+
+function optionalBound(value, fallback) {
+  return Number.isFinite(value) ? Number(value) : fallback;
+}
+
+export function decay(options = {}) {
+  return Object.freeze({
+    kind: 'decay',
+    velocity: Number.isFinite(options.velocity) ? Number(options.velocity) : undefined,
+    timeConstant: Math.max(0.016, finiteOr(options.timeConstant, DEFAULT_TAU)),
+    power: Math.max(0, finiteOr(options.power, 1)),
+    restSpeed: Math.max(0, finiteOr(options.restSpeed, DEFAULT_REST_SPEED)),
+    modifyTarget: typeof options.modifyTarget === 'function' ? options.modifyTarget : undefined,
+  });
+}
+
+export function inertia(options = {}) {
+  const bounce = options.bounce && options.bounce.kind === 'spring'
+    ? options.bounce
+    : { kind: 'spring', ...springParamsFromResponse(
+      finiteOr(options.bounceResponse, 0.28),
+      finiteOr(options.bounceDampingRatio, 0.82),
+    ) };
+
+  const min = optionalBound(options.min, -Infinity);
+  const max = optionalBound(options.max, Infinity);
+  if (min > max) throw new RangeError('inertia() min cannot be greater than max.');
+
+  return Object.freeze({
+    kind: 'inertia',
+    velocity: Number.isFinite(options.velocity) ? Number(options.velocity) : undefined,
+    timeConstant: Math.max(0.016, finiteOr(options.timeConstant, DEFAULT_TAU)),
+    power: Math.max(0, finiteOr(options.power, 0.8)),
+    restSpeed: Math.max(0, finiteOr(options.restSpeed, DEFAULT_REST_SPEED)),
+    restDelta: Math.max(0, finiteOr(options.restDelta, DEFAULT_REST_DELTA)),
+    min,
+    max,
+    bounceOmega: bounce.omega,
+    bounceDampingRatio: bounce.dampingRatio,
+    modifyTarget: typeof options.modifyTarget === 'function' ? options.modifyTarget : undefined,
+  });
+}
+
+export function projectDecayTarget(value, velocity, spec) {
+  const base = value + velocity * spec.timeConstant * spec.power;
+  const modified = spec.modifyTarget ? Number(spec.modifyTarget(base)) : base;
+  return Number.isFinite(modified) ? modified : base;
+}
+
+export function nearestBound(value, min = -Infinity, max = Infinity) {
+  if (value < min) return min;
+  if (value > max) return max;
+  return null;
+}
+
+export function clampToBounds(value, min = -Infinity, max = Infinity) {
+  if (!Number.isFinite(min) && !Number.isFinite(max)) return value;
+  return clamp(value, min, max);
+}
+
+// Exact exponential integration for dv/dt = -v/tau. This is frame-rate
+// independent and lands asymptotically at x + v*tau.
+export function stepDecay(position, velocity, dtSeconds, timeConstant, out = undefined) {
+  const result = out ?? { position: 0, velocity: 0 };
+  if (!(dtSeconds > 0) || !(timeConstant > 0)) {
+    result.position = position;
+    result.velocity = velocity;
+    return result;
+  }
+  const attenuation = Math.exp(-dtSeconds / timeConstant);
+  result.position = position + velocity * timeConstant * (1 - attenuation);
+  result.velocity = velocity * attenuation;
+  return result;
+}
+
+// Exact solution of y'' + 2*zeta*omega*y' + omega^2*y = 0 around target.
+// Used for low-count interaction settling so it remains stable across long or
+// irregular pointer frames without sub-stepping.
+export function stepDampedSpring(position, velocity, target, omega, dampingRatio, dtSeconds, out = undefined) {
+  const result = out ?? { position: 0, velocity: 0 };
+  if (!(dtSeconds > 0) || !(omega > 0)) {
+    result.position = position;
+    result.velocity = velocity;
+    return result;
+  }
+  const y0 = position - target;
+  const v0 = velocity;
+  const zeta = Math.max(0, dampingRatio);
+  const criticalEpsilon = 1e-4;
+
+  if (zeta < 1 - criticalEpsilon) {
+    const alpha = zeta * omega;
+    const wd = omega * Math.sqrt(1 - zeta * zeta);
+    const exp = Math.exp(-alpha * dtSeconds);
+    const sin = Math.sin(wd * dtSeconds);
+    const cos = Math.cos(wd * dtSeconds);
+    const b = (v0 + alpha * y0) / wd;
+    const y = exp * (y0 * cos + b * sin);
+    const v = exp * (
+      -alpha * (y0 * cos + b * sin)
+      + (-y0 * wd * sin + b * wd * cos)
+    );
+    result.position = target + y;
+    result.velocity = v;
+    return result;
+  }
+
+  if (zeta > 1 + criticalEpsilon) {
+    const root = Math.sqrt(zeta * zeta - 1);
+    const r1 = -omega * (zeta - root);
+    const r2 = -omega * (zeta + root);
+    const denominator = r1 - r2;
+    const c1 = (v0 - r2 * y0) / denominator;
+    const c2 = y0 - c1;
+    const e1 = Math.exp(r1 * dtSeconds);
+    const e2 = Math.exp(r2 * dtSeconds);
+    const y = c1 * e1 + c2 * e2;
+    const v = c1 * r1 * e1 + c2 * r2 * e2;
+    result.position = target + y;
+    result.velocity = v;
+    return result;
+  }
+
+  const exp = Math.exp(-omega * dtSeconds);
+  const b = v0 + omega * y0;
+  const y = exp * (y0 + b * dtSeconds);
+  const v = exp * (b - omega * (y0 + b * dtSeconds));
+  result.position = target + y;
+  result.velocity = v;
+  return result;
+}

package/dist/src/core/math.js

@@ -0,0 +1,20 @@
+export const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+
+export function springParamsFromResponse(response = 0.38, dampingRatio = 0.82) {
+  const safeResponse = Math.max(0.05, Number(response) || 0.38);
+  return {
+    omega: (Math.PI * 2) / safeResponse,
+    dampingRatio: Math.max(0, Number(dampingRatio) || 0),
+  };
+}
+
+export function springParamsFromPhysics({ mass = 1, stiffness = 170, damping = 18 } = {}) {
+  const m = Math.max(1e-6, mass);
+  const k = Math.max(1e-6, stiffness);
+  const c = Math.max(0, damping);
+  const omega = Math.sqrt(k / m);
+  return {
+    omega,
+    dampingRatio: c / (2 * Math.sqrt(k * m)),
+  };
+}

package/dist/src/core/motion-value.js

@@ -0,0 +1,53 @@
+export class MotionValue {
+  #value;
+  #velocity = 0;
+  #listeners = new Set();
+  #valueListeners = new Set();
+  #version = 0;
+
+  constructor(initial = 0) {
+    if (!Number.isFinite(initial)) throw new TypeError('MotionValue requires a finite number.');
+    this.#value = initial;
+  }
+
+  get() { return this.#value; }
+  getVelocity() { return this.#velocity; }
+  getVersion() { return this.#version; }
+
+  set(value, velocity = 0) {
+    if (!Number.isFinite(value)) return;
+    this.#commit(value, velocity);
+  }
+
+  #commit(value, velocity) {
+    if (Object.is(value, this.#value) && Object.is(velocity, this.#velocity)) return;
+    const previous = this.#value;
+    this.#value = value;
+    this.#velocity = velocity;
+    this.#version += 1;
+
+    for (const listener of this.#valueListeners) listener(value);
+    if (this.#listeners.size > 0) {
+      const info = { previous, velocity, version: this.#version };
+      for (const listener of this.#listeners) listener(value, info);
+    }
+  }
+
+  _commit(value, velocity) { this.#commit(value, velocity); }
+
+  subscribe(listener, { emitCurrent = true } = {}) {
+    this.#listeners.add(listener);
+    if (emitCurrent) listener(this.#value, { previous: this.#value, velocity: this.#velocity, version: this.#version });
+    return () => this.#listeners.delete(listener);
+  }
+
+  subscribeValue(listener, { emitCurrent = true } = {}) {
+    this.#valueListeners.add(listener);
+    if (emitCurrent) listener(this.#value);
+    return () => this.#valueListeners.delete(listener);
+  }
+}
+
+export function motionValue(initial = 0) {
+  return new MotionValue(initial);
+}

package/dist/src/core/planner.js

@@ -0,0 +1,72 @@
+import { compileEasing } from './easing.js';
+import { resolveMotionSpec, smooth } from './specs.js';
+
+const compiledPlans = new WeakMap();
+const resolvedProfilePlans = new WeakMap();
+const maximumResolvedProfilePlans = 64;
+const defaultProfile = smooth();
+
+function freezePlan(plan) {
+  return Object.freeze({ kind: 'motion-plan', ...plan });
+}
+
+function compileResolvedSpec(spec) {
+  if (!spec || typeof spec !== 'object') throw new TypeError('Motion spec must be an object.');
+  if (spec.kind === 'spring') {
+    return freezePlan({
+      route: 'spring',
+      spec,
+      omega: spec.omega,
+      dampingRatio: spec.dampingRatio,
+      initialVelocity: spec.initialVelocity,
+      blendDurationMs: Math.max(0, Number(spec.blendDuration) || 0) * 1000,
+    });
+  }
+  if (spec.kind === 'timing') {
+    return freezePlan({
+      route: 'timing',
+      spec,
+      durationMs: Math.max(0, spec.duration) * 1000,
+      easing: compileEasing(spec.curve),
+    });
+  }
+  if (spec.kind === 'profile') return freezePlan({ route: 'profile', spec });
+  throw new TypeError(`Unknown motion spec kind: ${String(spec.kind)}`);
+}
+
+export function isMotionExecutionPlan(value) {
+  return Boolean(value && typeof value === 'object' && value.kind === 'motion-plan');
+}
+
+/**
+ * Compile the invariant half of a motion request once. Spring coefficients and
+ * timing easing tables are frozen into the returned plan; adaptive profiles
+ * intentionally retain a tiny dynamic resolver because their response depends
+ * on the current travel distance.
+ */
+export function compileMotionPlan(requestedSpec) {
+  if (isMotionExecutionPlan(requestedSpec)) return requestedSpec;
+  const spec = requestedSpec ?? defaultProfile;
+  if (!spec || typeof spec !== 'object') throw new TypeError('Motion spec must be an object.');
+  const cached = compiledPlans.get(spec);
+  if (cached) return cached;
+  const plan = compileResolvedSpec(spec);
+  compiledPlans.set(spec, plan);
+  return plan;
+}
+
+/** Resolve only the distance-sensitive portion of a compiled plan. */
+export function resolveMotionPlan(requestedPlan, from, to) {
+  const plan = compileMotionPlan(requestedPlan);
+  if (plan.route !== 'profile') return plan;
+  const distance = Math.abs(to - from);
+  let cache = resolvedProfilePlans.get(plan.spec);
+  if (!cache) { cache = new Map(); resolvedProfilePlans.set(plan.spec, cache); }
+  const cached = cache.get(distance);
+  if (cached) { cache.delete(distance); cache.set(distance, cached); return cached; }
+  const resolved = resolveMotionSpec(plan.spec, from, to);
+  const compiled = compileResolvedSpec(resolved);
+  cache.set(distance, compiled);
+  while (cache.size > maximumResolvedProfilePlans) cache.delete(cache.keys().next().value);
+  return compiled;
+}

package/dist/src/core/specs.js

@@ -0,0 +1,70 @@
+import { clamp, springParamsFromPhysics, springParamsFromResponse } from './math.js';
+
+export function spring(options = {}) {
+  const { response = 0.38, dampingRatio = 0.82, initialVelocity, blendDuration = 0 } = options;
+  const params = springParamsFromResponse(response, dampingRatio);
+  return Object.freeze({ kind: 'spring', ...params, initialVelocity, blendDuration: Math.max(0, Number(blendDuration) || 0), source: 'response' });
+}
+
+spring.physics = function physics(options = {}) {
+  const params = springParamsFromPhysics(options);
+  return Object.freeze({
+    kind: 'spring',
+    ...params,
+    initialVelocity: options.initialVelocity,
+    blendDuration: Math.max(0, Number(options.blendDuration) || 0),
+    source: 'physics',
+  });
+};
+
+export function cubicBezier(x1, y1, x2, y2) {
+  return Object.freeze({ kind: 'bezier', x1, y1, x2, y2 });
+}
+
+export const curves = Object.freeze({
+  linear: cubicBezier(0, 0, 1, 1),
+  easeIn: cubicBezier(0.42, 0, 1, 1),
+  easeOut: cubicBezier(0, 0, 0.58, 1),
+  easeInOut: cubicBezier(0.42, 0, 0.58, 1),
+  smooth: cubicBezier(0.22, 1, 0.36, 1),
+});
+
+export function timing({ duration = 0.3, curve = curves.easeInOut } = {}) {
+  return Object.freeze({
+    kind: 'timing',
+    duration: Math.max(0, duration),
+    curve,
+  });
+}
+
+function profile(name, options = {}) {
+  return Object.freeze({ kind: 'profile', name, options: Object.freeze({ ...options }) });
+}
+
+export const smooth = (options) => profile('smooth', options);
+export const snappy = (options) => profile('snappy', options);
+export const bouncy = (options) => profile('bouncy', options);
+export const gentle = (options) => profile('gentle', options);
+export const interactive = (options) => profile('interactive', options);
+
+export function resolveMotionSpec(spec, from, to) {
+  if (!spec || spec.kind !== 'profile') return spec || smooth();
+
+  const distance = Math.abs(to - from);
+  const normalized = clamp(Math.log1p(distance) / Math.log1p(1000), 0, 1);
+  const bias = Number(spec.options?.responseBias || 0);
+
+  switch (spec.name) {
+    case 'snappy':
+      return spring({ response: 0.19 + normalized * 0.08 + bias, dampingRatio: 0.88 });
+    case 'bouncy':
+      return spring({ response: 0.31 + normalized * 0.09 + bias, dampingRatio: 0.67 });
+    case 'gentle':
+      return spring({ response: 0.43 + normalized * 0.12 + bias, dampingRatio: 0.98 });
+    case 'interactive':
+      return spring({ response: 0.20 + normalized * 0.09 + bias, dampingRatio: 0.84 });
+    case 'smooth':
+    default:
+      return spring({ response: 0.26 + normalized * 0.16 + bias, dampingRatio: 0.92 });
+  }
+}

package/dist/src/dom/index.d.ts

@@ -0,0 +1,41 @@
+import type {
+  AnimationControls,
+  MotionSpec,
+  MotionValue,
+  MotionEngine,
+  InterpolatorOptions,
+  MaterialInput,
+  ColorSpace,
+  PathMorphOptions,
+} from '../../index.js';
+export function configureDomBatching(options?: { scheduler?: 'microtask' | 'raf' }): void;
+export function flushDomCommits(): number;
+export function bindMotionStyles(element: HTMLElement, bindings: Record<string, MotionValue>): () => void;
+export function bindStyleValue(element: HTMLElement, property: string, motion: MotionValue, options?: { unit?: string }): () => void;
+export function animateStyle(element: HTMLElement, property: string, from: unknown, to: unknown, spec?: MotionSpec, options?: InterpolatorOptions & { engine?: MotionEngine }): AnimationControls;
+export function cancelStyleAnimations(element: Element, properties?: string | string[]): number;
+export function ownStyleAnimation<T extends { cancel(): void; readonly finished: Promise<unknown> }>(element: Element, properties: string | string[], control: T): T;
+export function animateStyleOwned(element: HTMLElement, property: string, from: unknown, to: unknown, spec?: MotionSpec, options?: InterpolatorOptions & { engine?: MotionEngine }): AnimationControls;
+export function applyMaterial(element: HTMLElement, material: MaterialInput, options?: { background?: boolean }): void;
+export function animateMaterial(element: HTMLElement, from: MaterialInput, to: MaterialInput, spec?: MotionSpec, options?: { background?: boolean; colorSpace?: ColorSpace; engine?: MotionEngine }): AnimationControls;
+export function animateAttribute(element: Element, name: string, from: unknown, to: unknown, spec?: MotionSpec, options?: InterpolatorOptions & { engine?: MotionEngine }): AnimationControls;
+export function animatePath(element: Element, from: string, to: string, spec?: MotionSpec, options?: PathMorphOptions & { engine?: MotionEngine }): AnimationControls;
+export function animateNative(element: Element, keyframes: Keyframe[] | PropertyIndexedKeyframes, options?: { duration?: number; easing?: string; fill?: FillMode }): Animation;
+
+export function bindPointerDrag(
+  element: HTMLElement,
+  controller: {
+    start(point: { x: number; y: number }, time?: number): unknown;
+    move(point: { x: number; y: number }, time?: number): unknown;
+    end(time?: number): unknown;
+    cancel(options?: { settle?: boolean }): unknown;
+  },
+  options?: {
+    button?: number;
+    pointerCapture?: boolean;
+    preventDefault?: boolean;
+    touchAction?: string | null;
+    coalesced?: boolean;
+    filter?: (event: PointerEvent) => boolean;
+  },
+): () => void;