@sigx/lynx-motion 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@sigx/lynx-motion",
+  "version": "0.1.0",
+  "description": "Animation primitives for sigx-lynx — spring/tween drivers built on AnimatedValue",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "keywords": [
+    "sigx",
+    "lynx",
+    "animation",
+    "spring",
+    "tween",
+    "motion"
+  ],
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "dependencies": {
+    "@sigx/lynx": "^0.1.4"
+  },
+  "devDependencies": {
+    "@lynx-js/react": "^0.119.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.12",
+    "@sigx/lynx-plugin": "^0.2.7",
+    "@sigx/lynx-runtime-main": "^0.2.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/signalxjs/lynx.git",
+    "directory": "packages/lynx-motion"
+  },
+  "homepage": "https://github.com/signalxjs/lynx/tree/main/packages/lynx-motion",
+  "bugs": {
+    "url": "https://github.com/signalxjs/lynx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && tsgo --emitDeclarationOnly",
+    "dev": "vite build --watch"
+  }
+}

package/src/animate.ts

@@ -0,0 +1,293 @@
+/**
+ * Animation orchestration ported from `@lynx-js/motion/dist/mini/core/animate.js`
+ * v0.0.3 (Apache-2.0). Spring solver + easeOut math from
+ * `motion-dom` v12.23.12 + `motion-utils` v12.23.6 (also Apache-2.0),
+ * inlined directly inside the worklet body.
+ *
+ * Why everything is inlined inside the function: SWC's worklet transform
+ * captures any free identifier referenced by the worklet body into the
+ * `_c` map. Plain JS function references at module scope (or sibling
+ * imports) don't survive JSON serialization across the MT/BG bridge — they
+ * arrive on MT as undefined or stringified placeholders. Upstream
+ * motion-mini sidesteps this by making every helper its own `'main thread'`
+ * worklet (so the placeholder objects survive). For Phase 2.7 we keep the
+ * port simpler by inlining the math straight into the `animate` worklet
+ * body, with `inflight` cancellation state tucked on `globalThis` so it's
+ * not a free-identifier capture.
+ *
+ * Sigx-specific adaptations:
+ *   - Operates on sigx's `SharedValue<number>` (writes `sv.current.value`)
+ *     instead of motion's `MotionValue`.
+ *   - Per-SharedValue cancellation tracking via `globalThis.__sigxMotionInflight`.
+ *   - Uses `globalThis.requestAnimationFrame` (installed by upstream's
+ *     worklet-runtime IIFE on MT, Lynx SDK ≥ 2.16); falls back to
+ *     `setTimeout(cb, 16)` otherwise.
+ *
+ * The standalone modules `easings.ts` and `spring.ts` still ship as a
+ * pure-math API for non-worklet callers (tests, BG-side debugging). They
+ * are NOT imported by this worklet.
+ */
+
+import type { SharedValue } from '@sigx/lynx';
+
+// ============================================================================
+// Public types
+// ============================================================================
+
+export interface SpringOptions {
+  stiffness?: number;
+  damping?: number;
+  mass?: number;
+  velocity?: number;
+  restSpeed?: number;
+  restDelta?: number;
+}
+
+export interface TimingOptions {
+  /** Tween duration in seconds. Default 0.3. */
+  duration?: number;
+}
+
+export interface AnimateOptions extends SpringOptions, TimingOptions {
+  type?: 'spring' | 'tween';
+}
+
+// Note: motion-style `onUpdate` / `onComplete` / custom `ease` callbacks are
+// intentionally NOT in this surface. Function references don't survive
+// worklet `_c` capture across the MT/BG bridge — they'd be silent footguns.
+// Sigx-native equivalents (zero extra wiring, integrate with reactivity):
+//   onUpdate(v) → BG: `effect(() => doX(sv.value))`
+//   onComplete() → `await withSpring(sv, target); doNext()`
+//   ease: customFn → use a built-in (`linear`, `easeIn`, `easeOut`, etc.);
+//     custom curves are rare and would need a `registerEasing(name, fn)`
+//     pattern (deferred follow-up).
+
+export interface AnimateControls {
+  stop(): void;
+  finished: Promise<void>;
+}
+
+// ============================================================================
+// Public API — all math inlined inside the worklet body.
+// ============================================================================
+
+/**
+ * Animate a `SharedValue<number>` toward `target`. Returns
+ * `{ stop, finished }`. Default is spring; pass `type: 'tween'` or
+ * `{ duration }` to use a tween with `easeOut`.
+ */
+export function animate(
+  sv: SharedValue<number>,
+  target: number,
+  options: AnimateOptions = {},
+): AnimateControls {
+  'main thread';
+
+  // ─── Inlined: in-flight cancellation map (per-SharedValue) ──────────
+  // Stash on globalThis so SWC doesn't capture a module-scope reference
+  // into _c. The map persists across animate() calls on MT.
+  const g = globalThis as { __sigxMotionInflight?: Map<number, () => void> };
+  if (!g.__sigxMotionInflight) g.__sigxMotionInflight = new Map();
+  const inflight = g.__sigxMotionInflight;
+
+  const prev = inflight.get(sv._wvid);
+  if (prev) prev();
+
+  const startValue = sv.current.value;
+
+  const isSpring =
+    options.type === 'spring' ||
+    (options.type !== 'tween' && options.duration == null);
+
+  // ─── Inlined: spring solver (motion-dom port, Apache-2.0) ────────────
+  // Returns { next(elapsedMs): { done, value } }. Only built when isSpring.
+  const buildSolver = (): ((t: number) => { done: boolean; value: number }) | null => {
+    if (!isSpring) return null;
+
+    const stiffness = options.stiffness ?? 100;
+    const damping = options.damping ?? 10;
+    const mass = options.mass ?? 1;
+    const initialVelocity = -((options.velocity ?? 0) / 1000); // ms→s, sign convention
+
+    const dampingRatio = damping / (2 * Math.sqrt(stiffness * mass));
+    const initialDelta = target - startValue;
+    const undampedAngularFreq = Math.sqrt(stiffness / mass) / 1000;
+
+    const isGranularScale = Math.abs(initialDelta) < 5;
+    const restSpeed = options.restSpeed ?? (isGranularScale ? 0.01 : 2);
+    const restDelta = options.restDelta ?? (isGranularScale ? 0.005 : 0.5);
+
+    let resolveSpring: (t: number) => number;
+
+    if (dampingRatio < 1) {
+      const angularFreq = undampedAngularFreq * Math.sqrt(1 - dampingRatio * dampingRatio);
+      resolveSpring = (t) => {
+        const envelope = Math.exp(-dampingRatio * undampedAngularFreq * t);
+        return target - envelope *
+          (((initialVelocity + dampingRatio * undampedAngularFreq * initialDelta) / angularFreq) *
+            Math.sin(angularFreq * t) +
+            initialDelta * Math.cos(angularFreq * t));
+      };
+    } else if (dampingRatio === 1) {
+      resolveSpring = (t) =>
+        target - Math.exp(-undampedAngularFreq * t) *
+          (initialDelta + (initialVelocity + undampedAngularFreq * initialDelta) * t);
+    } else {
+      const dampedAngularFreq = undampedAngularFreq * Math.sqrt(dampingRatio * dampingRatio - 1);
+      resolveSpring = (t) => {
+        const envelope = Math.exp(-dampingRatio * undampedAngularFreq * t);
+        const freqForT = Math.min(dampedAngularFreq * t, 300);
+        return target - (envelope *
+          ((initialVelocity + dampingRatio * undampedAngularFreq * initialDelta) * Math.sinh(freqForT) +
+            dampedAngularFreq * initialDelta * Math.cosh(freqForT))) / dampedAngularFreq;
+      };
+    }
+
+    // Velocity sample: 5ms-window finite-difference of resolveSpring.
+    const calcVelocity = (t: number, current: number): number => {
+      const prevT = Math.max(t - 5, 0);
+      const prevVal = resolveSpring(prevT);
+      const dt = t - prevT;
+      return dt ? (current - prevVal) * (1000 / dt) : 0;
+    };
+
+    return (t: number) => {
+      const current = resolveSpring(t);
+      let currentVelocity = t === 0 ? initialVelocity : 0;
+      if (dampingRatio < 1) {
+        currentVelocity = t === 0 ? initialVelocity * 1000 : calcVelocity(t, current);
+      }
+      const isBelowVelocityThreshold = Math.abs(currentVelocity) <= restSpeed;
+      const isBelowDisplacementThreshold = Math.abs(target - current) <= restDelta;
+      const done = isBelowVelocityThreshold && isBelowDisplacementThreshold;
+      return { done, value: done ? target : current };
+    };
+  };
+
+  const solverNext = buildSolver();
+
+  // ─── Inlined: easeOut (cubicBezier(0, 0, 0.58, 1)) ────────────────────
+  const calcBezier = (t: number, a1: number, a2: number): number =>
+    (((1.0 - 3.0 * a2 + 3.0 * a1) * t + (3.0 * a2 - 6.0 * a1)) * t + 3.0 * a1) * t;
+
+  const binarySubdivide = (x: number, mX1: number, mX2: number): number => {
+    let lo = 0, hi = 1, cT = 0, cX: number, i = 0;
+    do {
+      cT = lo + (hi - lo) / 2;
+      cX = calcBezier(cT, mX1, mX2) - x;
+      if (cX > 0) hi = cT; else lo = cT;
+    } while (Math.abs(cX) > 1e-7 && ++i < 12);
+    return cT;
+  };
+
+  const easeOutDefault = (t: number): number => {
+    if (t === 0 || t === 1) return t;
+    return calcBezier(binarySubdivide(t, 0, 0.58), 0, 1);
+  };
+
+  const duration = options.duration ?? 0.3;
+  const startTime = Date.now();
+
+  let canceled = false;
+  let resolvePromise: (() => void) | undefined;
+  let settled = false;
+  const finished = new Promise<void>((resolve) => { resolvePromise = resolve; });
+
+  const settle = (): void => {
+    if (settled) return;
+    settled = true;
+    if (inflight.get(sv._wvid) === stop) inflight.delete(sv._wvid);
+    resolvePromise?.();
+  };
+
+  const stop = (): void => {
+    if (canceled) return;
+    canceled = true;
+    settle();
+  };
+
+  inflight.set(sv._wvid, stop);
+
+  // ─── Inlined: tick scheduler ──────────────────────────────────────────
+  // `globalThis.requestAnimationFrame` is installed by upstream's
+  // worklet-runtime IIFE on MT; falls back to `setTimeout(cb, 16)` when
+  // unavailable (older SDKs, test environments).
+  const rafGlobal = globalThis as { requestAnimationFrame?: (cb: () => void) => void };
+  const scheduleNext = (cb: () => void): void => {
+    if (typeof rafGlobal.requestAnimationFrame === 'function') {
+      rafGlobal.requestAnimationFrame(cb);
+    } else {
+      setTimeout(cb, 16);
+    }
+  };
+
+  // ─── Flush trigger (microtask-debounced) ─────────────────────────────
+  // Writing `sv.current.value` is a plain ref mutation — it doesn't
+  // schedule the native flush by itself. Without a flush, the SharedValue
+  // bridge never publishes the new value to BG and `useAnimatedStyle`
+  // bindings never apply.
+  //
+  // We coalesce calls via a `globalThis.__sigxMotionFlushScheduled` flag:
+  // multiple ticks across multiple concurrent animations within the same
+  // microtask boundary all set the flag, the first one schedules the
+  // microtask, the rest see the flag and bail. End result: ONE flush per
+  // microtask regardless of how many animations are live. Same pattern
+  // upstream's `MTElementWrapper.flushElementTree` uses.
+  const flushTree = (): void => {
+    const g = globalThis as Record<string, unknown>;
+    if (g['__sigxMotionFlushScheduled']) return;
+    g['__sigxMotionFlushScheduled'] = true;
+    Promise.resolve().then(() => {
+      g['__sigxMotionFlushScheduled'] = false;
+      const fn = g['__FlushElementTree'] as (() => void) | undefined;
+      if (fn) fn();
+    });
+  };
+
+  const tick = (): void => {
+    if (canceled) return;
+
+    const now = Date.now();
+    const elapsedMs = now - startTime;
+    const elapsedSec = elapsedMs / 1000;
+
+    let current: number;
+    let done: boolean;
+
+    if (solverNext) {
+      const state = solverNext(elapsedMs);
+      current = state.value;
+      done = state.done;
+    } else if (elapsedSec >= duration) {
+      current = target;
+      done = true;
+    } else {
+      const p = elapsedSec / duration;
+      current = startValue + (target - startValue) * easeOutDefault(p);
+      done = false;
+    }
+
+    sv.current.value = current;
+    flushTree();
+
+    if (done) {
+      if (!solverNext && sv.current.value !== target) {
+        sv.current.value = target;
+        flushTree();
+      }
+      settle();
+    } else {
+      scheduleNext(tick);
+    }
+  };
+
+  scheduleNext(tick);
+
+  return { stop, finished };
+}
+
+/** Test hook — clear the in-flight map. Not part of the public API. */
+export function _resetInflight(): void {
+  const g = globalThis as { __sigxMotionInflight?: Map<number, () => void> };
+  if (g.__sigxMotionInflight) g.__sigxMotionInflight.clear();
+}

package/src/easings.ts

@@ -0,0 +1,98 @@
+/**
+ * Easing functions ported from `motion-utils` v12.23.6 (Apache-2.0).
+ * Upstream: https://github.com/motiondivision/motion/tree/main/packages/motion-utils/src/easing
+ *
+ * Sigx adaptation:
+ *   - Inlined into a single file (cubic-bezier + modifiers + named easings).
+ *   - No `'main thread'` directive; these are pure math functions safe to
+ *     call from BG or MT context. Sigx's tween path on MT calls them
+ *     directly inside the worklet body.
+ *
+ * Reference for individual implementations:
+ *   - cubicBezier: motion-utils/src/easing/cubic-bezier.ts (modified from
+ *     Gaëtan Renaudeau's BezierEasing — https://github.com/gre/bezier-easing,
+ *     MIT-licensed)
+ *   - ease.ts, back.ts, circ.ts, anticipate.ts, modifiers/{mirror,reverse}.ts
+ *
+ * Verbatim translation; any divergence from upstream is a bug.
+ */
+
+export type Easing = (t: number) => number;
+
+// noop — identity; serves as `linear` and as the cubic-bezier shortcut when
+// (mX1, mY1) === (mX2, mY2).
+const noop: Easing = (t) => t;
+
+// ---- cubic bezier ---------------------------------------------------------
+
+const calcBezier = (t: number, a1: number, a2: number): number =>
+  (((1.0 - 3.0 * a2 + 3.0 * a1) * t + (3.0 * a2 - 6.0 * a1)) * t + 3.0 * a1) *
+  t;
+
+const subdivisionPrecision = 0.0000001;
+const subdivisionMaxIterations = 12;
+
+function binarySubdivide(
+  x: number,
+  lowerBound: number,
+  upperBound: number,
+  mX1: number,
+  mX2: number,
+): number {
+  let currentX: number;
+  let currentT: number = 0;
+  let i = 0;
+  do {
+    currentT = lowerBound + (upperBound - lowerBound) / 2.0;
+    currentX = calcBezier(currentT, mX1, mX2) - x;
+    if (currentX > 0.0) {
+      upperBound = currentT;
+    } else {
+      lowerBound = currentT;
+    }
+  } while (
+    Math.abs(currentX) > subdivisionPrecision &&
+    ++i < subdivisionMaxIterations
+  );
+  return currentT;
+}
+
+export function cubicBezier(
+  mX1: number,
+  mY1: number,
+  mX2: number,
+  mY2: number,
+): Easing {
+  if (mX1 === mY1 && mX2 === mY2) return noop;
+  const getTForX = (aX: number) => binarySubdivide(aX, 0, 1, mX1, mX2);
+  return (t) => (t === 0 || t === 1 ? t : calcBezier(getTForX(t), mY1, mY2));
+}
+
+// ---- modifiers ------------------------------------------------------------
+
+/** Reverses an easing — turns easeIn into easeOut. */
+export const reverseEasing = (easing: Easing): Easing => (p) =>
+  1 - easing(1 - p);
+
+/** Mirrors an easing across the midpoint — turns easeIn into easeInOut. */
+export const mirrorEasing = (easing: Easing): Easing => (p) =>
+  p <= 0.5 ? easing(2 * p) / 2 : (2 - easing(2 * (1 - p))) / 2;
+
+// ---- named easings --------------------------------------------------------
+
+export const linear: Easing = noop;
+
+export const easeIn: Easing = cubicBezier(0.42, 0, 1, 1);
+export const easeOut: Easing = cubicBezier(0, 0, 0.58, 1);
+export const easeInOut: Easing = cubicBezier(0.42, 0, 0.58, 1);
+
+export const circIn: Easing = (p) => 1 - Math.sin(Math.acos(p));
+export const circOut: Easing = reverseEasing(circIn);
+export const circInOut: Easing = mirrorEasing(circIn);
+
+export const backOut: Easing = cubicBezier(0.33, 1.53, 0.69, 0.99);
+export const backIn: Easing = reverseEasing(backOut);
+export const backInOut: Easing = mirrorEasing(backIn);
+
+export const anticipate: Easing = (p) =>
+  (p *= 2) < 1 ? 0.5 * backIn(p) : 0.5 * (2 - Math.pow(2, -10 * (p - 1)));

package/src/index.ts

@@ -0,0 +1,46 @@
+// Animation orchestration ('main thread' worklets that operate on SharedValue)
+export { animate } from './animate.js';
+export type {
+  AnimateOptions,
+  AnimateControls,
+  SpringOptions,
+  TimingOptions,
+} from './animate.js';
+
+// Convenience wrappers
+export { withSpring } from './with-spring.js';
+export { withTiming } from './with-timing.js';
+
+// Spring solver — pure-math API for non-worklet callers (tests, BG-side
+// debugging, future scroll-driven derived values). NOT used by the worklet
+// path: `animate()` has its own inlined copy of the solver to avoid
+// cross-file `_c` capture of plain function references that don't survive
+// JSON serialization across the MT/BG bridge.
+export { spring, clamp } from './spring.js';
+export type {
+  SpringSolver,
+  SpringStep,
+  SpringSolverOptions,
+} from './spring.js';
+
+// Easings — same story as spring: pure-math API for non-worklet uses; the
+// `animate()` worklet has its own inlined `easeOut`. Custom easings passed
+// via `animate(sv, target, { ease: customFn })` will not survive worklet
+// capture and is documented as out-of-scope for v0.1.
+export {
+  cubicBezier,
+  reverseEasing,
+  mirrorEasing,
+  linear,
+  easeIn,
+  easeOut,
+  easeInOut,
+  circIn,
+  circOut,
+  circInOut,
+  backIn,
+  backOut,
+  backInOut,
+  anticipate,
+} from './easings.js';
+export type { Easing } from './easings.js';

package/src/spring.ts

@@ -0,0 +1,198 @@
+/**
+ * Spring solver ported from `motion-dom` v12.23.12 + `motion-utils` v12.23.6
+ * (both Apache-2.0).
+ * Upstream:
+ *   - https://github.com/motiondivision/motion/tree/main/packages/motion-dom/src/animation/generators/spring
+ *   - https://github.com/motiondivision/motion/tree/main/packages/motion-utils/src
+ *
+ * Sigx adaptation:
+ *   - Inlined the motion-utils helpers we depend on (`clamp`,
+ *     `millisecondsToSeconds`, `secondsToMilliseconds`, `velocityPerSecond`)
+ *     and the velocity calculator from `motion-dom/animation/generators/utils`.
+ *     These are tiny pure functions; inlining keeps `@sigx/lynx-motion` zero-deps
+ *     beyond the sigx workspace.
+ *   - Skipped the duration→physics resolution path (motion's `findSpring`).
+ *     Phase 2.7 ships only physics-based options (stiffness/damping/mass).
+ *     If a future user wants `withSpring(av, target, { duration, bounce })`,
+ *     add `findSpring` then.
+ *   - `calculatedDuration` and `toString()` / `toTransition()` from upstream
+ *     are dropped; they're for WAAPI integration which Lynx doesn't use.
+ *
+ * Verbatim translation of the integrator math; any divergence is a bug.
+ */
+
+// ---- inlined helpers ------------------------------------------------------
+
+const clamp = (min: number, max: number, v: number): number =>
+  v > max ? max : v < min ? min : v;
+
+const millisecondsToSeconds = (ms: number): number => ms / 1000;
+const secondsToMilliseconds = (s: number): number => s * 1000;
+
+const velocityPerSecond = (velocity: number, frameDuration: number): number =>
+  frameDuration ? velocity * (1000 / frameDuration) : 0;
+
+const velocitySampleDuration = 5; // ms
+const calcGeneratorVelocity = (
+  resolveValue: (t: number) => number,
+  t: number,
+  current: number,
+): number => {
+  const prevT = Math.max(t - velocitySampleDuration, 0);
+  return velocityPerSecond(current - resolveValue(prevT), t - prevT);
+};
+
+// ---- defaults -------------------------------------------------------------
+
+const springDefaults = {
+  stiffness: 100,
+  damping: 10,
+  mass: 1.0,
+  velocity: 0.0,
+  restSpeed: { granular: 0.01, default: 2 },
+  restDelta: { granular: 0.005, default: 0.5 },
+};
+
+// ---- public API -----------------------------------------------------------
+
+export interface SpringOptions {
+  /** Spring physics. Default 100. */
+  stiffness?: number;
+  /** Spring damping. Default 10. */
+  damping?: number;
+  /** Mass of the spring object. Default 1. */
+  mass?: number;
+  /** Initial velocity in units/sec. Default 0. */
+  velocity?: number;
+  /** Threshold below which the spring is considered at rest. */
+  restSpeed?: number;
+  restDelta?: number;
+}
+
+export interface SpringStep {
+  done: boolean;
+  value: number;
+}
+
+export interface SpringSolver {
+  /**
+   * Advance the spring to `t` ms after `t=0`. Returns the integrated value
+   * and a `done` flag set when the spring is below the rest thresholds.
+   */
+  next(t: number): SpringStep;
+}
+
+export interface SpringSolverOptions extends SpringOptions {
+  /** Required: `[origin, target]`. Pinned to a 2-element keyframes shape. */
+  keyframes: [number, number];
+}
+
+/**
+ * Build a spring solver. Call `.next(elapsedMs)` repeatedly to step the
+ * animation. The solver owns no time state — call `.next` with the current
+ * elapsed time each tick (motion's pattern).
+ */
+export function spring(options: SpringSolverOptions): SpringSolver {
+  const origin = options.keyframes[0];
+  const target = options.keyframes[1];
+
+  const state: SpringStep = { done: false, value: origin };
+
+  const stiffness = options.stiffness ?? springDefaults.stiffness;
+  const damping = options.damping ?? springDefaults.damping;
+  const mass = options.mass ?? springDefaults.mass;
+  // Negate to match motion's convention: positive velocity moves toward
+  // target, but the integrator expects velocity in source-units convention.
+  const initialVelocity = -millisecondsToSeconds(options.velocity ?? 0);
+
+  const dampingRatio = damping / (2 * Math.sqrt(stiffness * mass));
+  const initialDelta = target - origin;
+  const undampedAngularFreq = millisecondsToSeconds(
+    Math.sqrt(stiffness / mass),
+  );
+
+  const isGranularScale = Math.abs(initialDelta) < 5;
+  const restSpeed =
+    options.restSpeed ??
+    (isGranularScale
+      ? springDefaults.restSpeed.granular
+      : springDefaults.restSpeed.default);
+  const restDelta =
+    options.restDelta ??
+    (isGranularScale
+      ? springDefaults.restDelta.granular
+      : springDefaults.restDelta.default);
+
+  let resolveSpring: (t: number) => number;
+
+  if (dampingRatio < 1) {
+    // Underdamped — oscillates while decaying.
+    const angularFreq =
+      undampedAngularFreq * Math.sqrt(1 - dampingRatio * dampingRatio);
+    resolveSpring = (t) => {
+      const envelope = Math.exp(-dampingRatio * undampedAngularFreq * t);
+      return (
+        target -
+        envelope *
+          (((initialVelocity +
+            dampingRatio * undampedAngularFreq * initialDelta) /
+            angularFreq) *
+            Math.sin(angularFreq * t) +
+            initialDelta * Math.cos(angularFreq * t))
+      );
+    };
+  } else if (dampingRatio === 1) {
+    // Critically damped — fastest non-oscillating return.
+    resolveSpring = (t) =>
+      target -
+      Math.exp(-undampedAngularFreq * t) *
+        (initialDelta +
+          (initialVelocity + undampedAngularFreq * initialDelta) * t);
+  } else {
+    // Overdamped — slow non-oscillating return.
+    const dampedAngularFreq =
+      undampedAngularFreq * Math.sqrt(dampingRatio * dampingRatio - 1);
+    resolveSpring = (t) => {
+      const envelope = Math.exp(-dampingRatio * undampedAngularFreq * t);
+      // Cap freq*t to keep sinh/cosh from hitting Infinity.
+      const freqForT = Math.min(dampedAngularFreq * t, 300);
+      return (
+        target -
+        (envelope *
+          ((initialVelocity +
+            dampingRatio * undampedAngularFreq * initialDelta) *
+            Math.sinh(freqForT) +
+            dampedAngularFreq * initialDelta * Math.cosh(freqForT))) /
+          dampedAngularFreq
+      );
+    };
+  }
+
+  return {
+    next(t: number): SpringStep {
+      const current = resolveSpring(t);
+
+      let currentVelocity = t === 0 ? initialVelocity : 0.0;
+      // Velocity calc only needed for underdamped — over/critically-damped
+      // can't overshoot, so position alone tells us we're done.
+      if (dampingRatio < 1) {
+        currentVelocity =
+          t === 0
+            ? secondsToMilliseconds(initialVelocity)
+            : calcGeneratorVelocity(resolveSpring, t, current);
+      }
+
+      const isBelowVelocityThreshold = Math.abs(currentVelocity) <= restSpeed;
+      const isBelowDisplacementThreshold =
+        Math.abs(target - current) <= restDelta;
+
+      state.done = isBelowVelocityThreshold && isBelowDisplacementThreshold;
+      state.value = state.done ? target : current;
+      return state;
+    },
+  };
+}
+
+// Re-export `clamp` because it's small and useful for animation math, and
+// motion-mini exports it from its mini surface.
+export { clamp };