coily 0.13.1 → 0.15.0

package/dist/css.d.ts

@@ -0,0 +1,175 @@
+import { r as SpringState, t as SpringDefinition } from "./config-OOMMRdK8.js";
+//#region src/css.d.ts
+interface LinearEasingOptions {
+  /**
+   * Animation range the duration is tuned for, in value units. The easing
+   * shape is identical regardless; only the settle time scales with it.
+   * The keyframe helpers (`springToWaapi`, `springToCss`,
+   * `springToTransition`) default it to the largest move among their
+   * specs instead.
+   * @default 1
+   */
+  readonly displacement?: number;
+  /**
+   * Max output error of the piecewise-linear approximation, in progress
+   * units (0..1). Smaller keeps more stops.
+   * @default 0.0025
+   */
+  readonly maxError?: number;
+  /**
+   * Hard cap on generated duration, in ms, for near-undamped configs.
+   * @default 10000
+   */
+  readonly maxDuration?: number;
+}
+interface EasingBase {
+  /** A CSS `linear()` easing string. */
+  readonly easing: string;
+  /** Duration to pair the easing with, in ms. */
+  readonly duration: number;
+  /** Number of stops in the easing (diagnostic). */
+  readonly stops: number;
+  /** Worst reconstruction error vs the dense trajectory (diagnostic). */
+  readonly maxError: number;
+}
+/** The easing of a spring that comes to rest: play it once over `duration`. */
+interface SettlingEasing extends EasingBase {
+  readonly mode: 'settle';
+}
+/**
+ * The easing of a spring that never rests — an undamped oscillation,
+ * expressed as a seamless loop. Animate the property between its two
+ * swing extremes (`from` and `2 * target - from`, target at the 50%
+ * midpoint) with `animation-iteration-count: infinite` and
+ * `animation-direction: alternate`. `duration` is one half period.
+ */
+interface LoopingEasing extends EasingBase {
+  readonly mode: 'loop';
+  readonly direction: 'alternate';
+  readonly iterations: 'infinite';
+}
+type LinearEasing = SettlingEasing | LoopingEasing;
+/**
+ * Turns a resolved spring config into a CSS `linear()` easing and the
+ * duration in ms to pair it with. A spring that settles returns a
+ * `'settle'` easing. A pure undamped config (`dampingRatio: 0` with
+ * passthrough `arrival`) has no friction and never settles, so it
+ * returns a `'loop'` easing for an infinite alternating animation.
+ */
+declare function springToLinear(config: SpringDefinition, options?: LinearEasingOptions): LinearEasing;
+/**
+ * Like `springToLinear`, but from a spring caught mid-flight rather than at
+ * rest: `state` carries both the displacement from the target (`position`)
+ * and the current `velocity`, so the easing continues the motion smoothly
+ * instead of restarting. Use it to regenerate an animation when its target
+ * changes — the interruption carries momentum instead of stalling. The
+ * from-rest shape trick doesn't apply here (the curve now depends on the
+ * velocity), so this is computed per interruption, not cached per config.
+ *
+ * Always a settling easing; `position` must be nonzero.
+ */
+declare function springFromState(config: SpringDefinition, state: SpringState, options?: LinearEasingOptions): LinearEasing;
+/**
+ * Evolves a spring `state` forward by `elapsedMs`, returning the new
+ * displacement and velocity. Pair it with a running `element.animate` — read
+ * the animation's `currentTime`, evolve the state it started from, and you
+ * have the exact live velocity the Web Animations API never exposes, ready
+ * to hand to `springFromState` on interruption.
+ */
+declare function springStateAt(config: SpringDefinition, state: SpringState, elapsedMs: number): SpringState;
+/** What to animate: a CSS property from one numeric value to another. */
+interface PropertySpec {
+  /** The CSS property, e.g. `'opacity'`, `'transform'`, `'translate'`. */
+  readonly property: string;
+  /** Start value. */
+  readonly from: number;
+  /** Target value the spring is tuned toward. */
+  readonly to: number;
+  /**
+   * Unit appended to numbers, e.g. `'px'`, `'%'`, `'deg'`.
+   * @default ''
+   */
+  readonly unit?: string;
+  /**
+   * Formats an interpolated number into a property value, overriding
+   * `unit` — needed for wrapped values like `(v) => `translateX(${v}px)``.
+   */
+  readonly format?: (value: number) => string;
+  /**
+   * The property's current velocity, in its units per second. Set it to
+   * regenerate an interrupted animation from its live motion so it carries
+   * momentum instead of restarting from rest. Single-property only — a
+   * from-state easing depends on that property's velocity and can't be
+   * shared across properties.
+   */
+  readonly velocity?: number;
+}
+interface CssOptions extends LinearEasingOptions {
+  /**
+   * Name for the generated `@keyframes` rule.
+   * @default 'coily'
+   */
+  readonly name?: string;
+}
+/**
+ * Builds arguments for `element.animate(keyframes, options)`: two keyframes
+ * carrying the endpoint values, and options carrying the spring's `linear()`
+ * easing and duration. Pass an array of specs to drive several properties
+ * from one spring. A settling spring fills forwards; an undamped one repeats
+ * infinitely in alternating directions.
+ *
+ * @example
+ * ```ts
+ * const { keyframes, options } = springToWaapi(config, {
+ *   property: 'translate',
+ *   from: 0,
+ *   to: 300,
+ *   unit: 'px',
+ * })
+ * element.animate(keyframes, options)
+ * ```
+ */
+declare function springToWaapi(config: SpringDefinition, spec: PropertySpec | PropertySpec[], options?: LinearEasingOptions): {
+  keyframes: Keyframe[];
+  options: KeyframeAnimationOptions;
+};
+/**
+ * Builds CSS text for the animation: a `@keyframes` rule and an `animation`
+ * shorthand value, driving one property or several from one spring. The
+ * `name` option (default `'coily'`) names the `@keyframes` rule and is
+ * referenced by the `animation` value.
+ *
+ * @example
+ * ```ts
+ * const { keyframes, animation } = springToCss(config, {
+ *   property: 'translate',
+ *   from: 0,
+ *   to: 300,
+ *   unit: 'px',
+ * })
+ * const style = document.createElement('style')
+ * style.textContent = keyframes
+ * document.head.append(style)
+ * element.style.animation = animation
+ * ```
+ */
+declare function springToCss(config: SpringDefinition, spec: PropertySpec | PropertySpec[], options?: CssOptions): {
+  keyframes: string;
+  animation: string;
+};
+/**
+ * Builds a CSS `transition` value that springs a property change: set it on
+ * the element, then change the property (on `:hover`, a toggled class, a
+ * state attribute) to animate. Pass several specs for one `transition`
+ * across properties.
+ *
+ * Only settling springs — a transition can't loop. It also can't carry
+ * momentum: a change interrupted mid-flight restarts the spring from rest
+ * instead of reversing through its current velocity, so it stalls at the
+ * turn. For motion that's reversed often, drive a live `Spring` instead. The
+ * specs' `from`/`to` only tune the duration; the actual values live in your
+ * CSS rules.
+ */
+declare function springToTransition(config: SpringDefinition, spec: PropertySpec | PropertySpec[], options?: LinearEasingOptions): string;
+//#endregion
+export { CssOptions, LinearEasing, LinearEasingOptions, LoopingEasing, PropertySpec, SettlingEasing, springFromState, springStateAt, springToCss, springToLinear, springToTransition, springToWaapi };

package/dist/css.js

@@ -0,0 +1,294 @@
+import { i as State, n as OverdampedSolver, o as invariant, r as UnderdampedSolver, t as CriticallyDampedSolver } from "./solver-CVXOTDkZ.js";
+//#region src/css.ts
+function pickSolver(config, state) {
+	const solver = config.dampingRatio < 1 ? new UnderdampedSolver(state) : config.dampingRatio === 1 ? new CriticallyDampedSolver(state) : new OverdampedSolver(state);
+	solver.configure(config);
+	return solver;
+}
+function walk(config, displacement, spanSec, scale, stopAtRest, velocity = 0) {
+	const state = new State(config, displacement, velocity);
+	const solver = pickSolver(config, state);
+	const period = 2 * Math.PI / config.naturalFrequency;
+	const dt = Math.max(1e-4, Math.min(period / 48, spanSec / 160));
+	const points = [{
+		x: 0,
+		y: 0
+	}];
+	let t = 0;
+	while (spanSec - t > 1e-9) {
+		const step = Math.min(dt, spanSec - t);
+		solver.tick(step);
+		t += step;
+		points.push({
+			x: t / spanSec,
+			y: (1 - state.position / displacement) * scale
+		});
+		if (stopAtRest && state.isResting) break;
+	}
+	return points;
+}
+function buildEasing(points, maxError) {
+	const simplified = simplify(points, maxError);
+	return {
+		easing: format(simplified),
+		stops: simplified.length,
+		maxError: reconstructionError(points, simplified)
+	};
+}
+function buildSettle(config, displacement, durationMs, maxError, velocity = 0) {
+	const points = walk(config, displacement, durationMs / 1e3, 1, true, velocity);
+	const last = points[points.length - 1];
+	if (1 - last.x > 1e-6) points.push({
+		x: 1,
+		y: 1
+	});
+	else {
+		last.x = 1;
+		last.y = 1;
+	}
+	return {
+		mode: "settle",
+		duration: durationMs,
+		...buildEasing(points, maxError)
+	};
+}
+function buildLoop(config, displacement, maxError) {
+	const halfSec = Math.PI / config.naturalFrequency;
+	const points = walk(config, displacement, halfSec, .5, false);
+	const last = points[points.length - 1];
+	last.x = 1;
+	last.y = 1;
+	return {
+		mode: "loop",
+		duration: halfSec * 1e3,
+		direction: "alternate",
+		iterations: "infinite",
+		...buildEasing(points, maxError)
+	};
+}
+function simplify(points, epsilon) {
+	const keep = Array.from({ length: points.length }, () => false);
+	keep[0] = true;
+	keep[points.length - 1] = true;
+	const stack = [[0, points.length - 1]];
+	while (stack.length > 0) {
+		const [lo, hi] = stack.pop();
+		const a = points[lo];
+		const b = points[hi];
+		const dx = b.x - a.x;
+		let worst = -1;
+		let worstIndex = -1;
+		for (let i = lo + 1; i < hi; i += 1) {
+			const p = points[i];
+			const f = dx === 0 ? 0 : (p.x - a.x) / dx;
+			const interpolated = a.y + f * (b.y - a.y);
+			const distance = Math.abs(p.y - interpolated);
+			if (distance > worst) {
+				worst = distance;
+				worstIndex = i;
+			}
+		}
+		if (worst > epsilon && worstIndex !== -1) {
+			keep[worstIndex] = true;
+			stack.push([lo, worstIndex], [worstIndex, hi]);
+		}
+	}
+	return points.filter((_, i) => keep[i]);
+}
+function trim(value, places) {
+	return Number(value.toFixed(places)).toString();
+}
+function format(points) {
+	return `linear(${points.map((point, i) => {
+		const output = trim(point.y, 5);
+		if (i === 0 || i === points.length - 1) return output;
+		return `${output} ${trim(point.x * 100, 2)}%`;
+	}).join(", ")})`;
+}
+function reconstructionError(dense, simplified) {
+	let worst = 0;
+	let j = 0;
+	for (const point of dense) {
+		while (j < simplified.length - 2 && simplified[j + 1].x < point.x) j += 1;
+		const a = simplified[j];
+		const b = simplified[j + 1];
+		const dx = b.x - a.x;
+		const f = dx === 0 ? 0 : (point.x - a.x) / dx;
+		worst = Math.max(worst, Math.abs(point.y - (a.y + f * (b.y - a.y))));
+	}
+	return worst;
+}
+/**
+* Turns a resolved spring config into a CSS `linear()` easing and the
+* duration in ms to pair it with. A spring that settles returns a
+* `'settle'` easing. A pure undamped config (`dampingRatio: 0` with
+* passthrough `arrival`) has no friction and never settles, so it
+* returns a `'loop'` easing for an infinite alternating animation.
+*/
+function springToLinear(config, options = {}) {
+	const displacement = options.displacement ?? 1;
+	const maxError = options.maxError ?? .0025;
+	const maxDuration = options.maxDuration ?? 1e4;
+	if (config.dampingRatio === 0 && config.arrival === 1) return buildLoop(config, displacement, maxError);
+	const settleTime = config.computeTimeRemaining({
+		position: displacement,
+		velocity: 0
+	});
+	return buildSettle(config, displacement, Math.min(settleTime, maxDuration), maxError);
+}
+/**
+* Like `springToLinear`, but from a spring caught mid-flight rather than at
+* rest: `state` carries both the displacement from the target (`position`)
+* and the current `velocity`, so the easing continues the motion smoothly
+* instead of restarting. Use it to regenerate an animation when its target
+* changes — the interruption carries momentum instead of stalling. The
+* from-rest shape trick doesn't apply here (the curve now depends on the
+* velocity), so this is computed per interruption, not cached per config.
+*
+* Always a settling easing; `position` must be nonzero.
+*/
+function springFromState(config, state, options = {}) {
+	const maxError = options.maxError ?? .0025;
+	const maxDuration = options.maxDuration ?? 1e4;
+	invariant(Math.abs(state.position) > 1e-9, "springFromState needs a nonzero position (the value and target must differ)");
+	const settleTime = config.computeTimeRemaining(state);
+	return buildSettle(config, state.position, Math.min(settleTime, maxDuration), maxError, state.velocity);
+}
+/**
+* Evolves a spring `state` forward by `elapsedMs`, returning the new
+* displacement and velocity. Pair it with a running `element.animate` — read
+* the animation's `currentTime`, evolve the state it started from, and you
+* have the exact live velocity the Web Animations API never exposes, ready
+* to hand to `springFromState` on interruption.
+*/
+function springStateAt(config, state, elapsedMs) {
+	if (elapsedMs <= 0) return {
+		position: state.position,
+		velocity: state.velocity
+	};
+	const live = new State(config, state.position, state.velocity);
+	pickSolver(config, live).tick(elapsedMs / 1e3);
+	return {
+		position: live.position,
+		velocity: live.velocity
+	};
+}
+function resolveSpecs(config, specs, options) {
+	const withVelocity = specs.some((spec) => (spec.velocity ?? 0) !== 0);
+	invariant(!withVelocity || specs.length === 1, "velocity handoff is single-property: a from-state easing depends on that property, so run one animation per property");
+	const first = specs[0];
+	const easing = withVelocity ? springFromState(config, {
+		position: first.from - first.to,
+		velocity: first.velocity
+	}, options) : springToLinear(config, {
+		...options,
+		displacement: options.displacement ?? (Math.max(...specs.map((s) => Math.abs(s.to - s.from))) || 1)
+	});
+	const from = {};
+	const to = {};
+	for (const spec of specs) {
+		const format = spec.format ?? ((value) => `${Number(value.toFixed(3))}${spec.unit ?? ""}`);
+		const far = easing.mode === "loop" ? 2 * spec.to - spec.from : spec.to;
+		const start = format(spec.from);
+		const end = format(far);
+		from[spec.property] = from[spec.property] ? `${from[spec.property]} ${start}` : start;
+		to[spec.property] = to[spec.property] ? `${to[spec.property]} ${end}` : end;
+	}
+	return {
+		easing,
+		from,
+		to
+	};
+}
+function asArray(spec) {
+	return Array.isArray(spec) ? spec : [spec];
+}
+/**
+* Builds arguments for `element.animate(keyframes, options)`: two keyframes
+* carrying the endpoint values, and options carrying the spring's `linear()`
+* easing and duration. Pass an array of specs to drive several properties
+* from one spring. A settling spring fills forwards; an undamped one repeats
+* infinitely in alternating directions.
+*
+* @example
+* ```ts
+* const { keyframes, options } = springToWaapi(config, {
+*   property: 'translate',
+*   from: 0,
+*   to: 300,
+*   unit: 'px',
+* })
+* element.animate(keyframes, options)
+* ```
+*/
+function springToWaapi(config, spec, options = {}) {
+	const { easing, from, to } = resolveSpecs(config, asArray(spec), options);
+	const keyframes = [from, to];
+	const shared = {
+		duration: easing.duration,
+		easing: easing.easing
+	};
+	return {
+		keyframes,
+		options: easing.mode === "loop" ? {
+			...shared,
+			iterations: Number.POSITIVE_INFINITY,
+			direction: "alternate"
+		} : {
+			...shared,
+			fill: "forwards"
+		}
+	};
+}
+/**
+* Builds CSS text for the animation: a `@keyframes` rule and an `animation`
+* shorthand value, driving one property or several from one spring. The
+* `name` option (default `'coily'`) names the `@keyframes` rule and is
+* referenced by the `animation` value.
+*
+* @example
+* ```ts
+* const { keyframes, animation } = springToCss(config, {
+*   property: 'translate',
+*   from: 0,
+*   to: 300,
+*   unit: 'px',
+* })
+* const style = document.createElement('style')
+* style.textContent = keyframes
+* document.head.append(style)
+* element.style.animation = animation
+* ```
+*/
+function springToCss(config, spec, options = {}) {
+	const { easing, from, to } = resolveSpecs(config, asArray(spec), options);
+	const name = options.name ?? "coily";
+	const ms = `${Number(easing.duration.toFixed(1))}ms`;
+	const declare = (values) => Object.entries(values).map(([property, value]) => `${property}: ${value};`).join(" ");
+	return {
+		keyframes: `@keyframes ${name} {\n  from { ${declare(from)} }\n  to { ${declare(to)} }\n}`,
+		animation: easing.mode === "loop" ? `${ms} ${easing.easing} infinite alternate ${name}` : `${ms} ${easing.easing} forwards ${name}`
+	};
+}
+/**
+* Builds a CSS `transition` value that springs a property change: set it on
+* the element, then change the property (on `:hover`, a toggled class, a
+* state attribute) to animate. Pass several specs for one `transition`
+* across properties.
+*
+* Only settling springs — a transition can't loop. It also can't carry
+* momentum: a change interrupted mid-flight restarts the spring from rest
+* instead of reversing through its current velocity, so it stalls at the
+* turn. For motion that's reversed often, drive a live `Spring` instead. The
+* specs' `from`/`to` only tune the duration; the actual values live in your
+* CSS rules.
+*/
+function springToTransition(config, spec, options = {}) {
+	const specs = asArray(spec);
+	const { easing } = resolveSpecs(config, specs, options);
+	invariant(easing.mode === "settle", "springToTransition requires a settling spring; an undamped (looping) config has no single end state to transition to");
+	const ms = `${Number(easing.duration.toFixed(1))}ms`;
+	return specs.map((s) => `${s.property} ${ms} ${easing.easing}`).join(", ");
+}
+//#endregion
+export { springFromState, springStateAt, springToCss, springToLinear, springToTransition, springToWaapi };

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-import { _ as SpringOptions, a as ConfigShape, c as Shape, d as SpringObjectWithOffset, f as Spring, g as SpringConfig, h as SpringWithOffset, i as TickerOptions, l as SpringObject, m as SpringTarget, n as SpringSystemOptions, o as PartialShape, p as SpringPosition, r as createSpringSystem, s as ReadonlyShape, t as SpringSystem, u as SpringObjectTarget, v as SpringState, y as defineSpring } from "./system-86fsXJN_.js";
-export { type ConfigShape, type PartialShape, type ReadonlyShape, type Shape, type Spring, type SpringConfig, type SpringObject, type SpringObjectTarget, type SpringObjectWithOffset, type SpringOptions, type SpringPosition, type SpringState, type SpringSystem, type SpringSystemOptions, type SpringTarget, type SpringWithOffset, type TickerOptions, createSpringSystem, defineSpring };
+import { i as defineSpring, n as SpringDefinitionOptions, r as SpringState, t as SpringDefinition } from "./config-OOMMRdK8.js";
+import { _ as accelerationOf, a as createSpringSystem, b as SpringSourceSymbol, c as ConfigShape, g as KinematicSource, h as SpringTarget, i as SpringSystemOptions, m as Spring, n as SpringOptions, o as CompositeSpring, p as Purpose, r as SpringSystem, s as CompositeSpringTarget, t as CompositeSpringOptions, u as PurposeShape, v as velocityOf, x as mapSpring, y as SpringSource } from "./system-Du_fXXmO.js";
+export { type CompositeSpring, type CompositeSpringOptions, type CompositeSpringTarget, type ConfigShape, type KinematicSource, type Purpose, type PurposeShape, type Spring, type SpringDefinition, type SpringDefinitionOptions, type SpringOptions, type SpringSource, SpringSourceSymbol, type SpringState, type SpringSystem, type SpringSystemOptions, type SpringTarget, accelerationOf, createSpringSystem, defineSpring, mapSpring, velocityOf };

package/dist/index.js

@@ -1,2 +1,91 @@
-import { r as defineSpring, t as createSpringSystem } from "./system-Csho09XW.js";
-export { createSpringSystem, defineSpring };
+import { a as registerRecipe, i as mapSpring, n as SpringSourceSymbol, r as isSpringSource, s as defineSpring, t as createSpringSystem } from "./system-Br_cPnaN.js";
+import { o as invariant } from "./solver-CVXOTDkZ.js";
+//#region src/kinematic-source.ts
+function isKinematicSource(value) {
+	if (!isSpringSource(value)) return false;
+	const api = value[SpringSourceSymbol];
+	return "velocity" in api && "acceleration" in api;
+}
+const NOT_KINEMATIC = "expected a source in motion (a Spring or CompositeSpring); a value derived with mapSpring has neither velocity nor acceleration";
+/**
+* Derives a source from another's velocity — the rate its value changes,
+* in value units per second. `velocityOf(motion)` is a source that reads
+* `motion`'s current velocity, so speed-driven effects fall out of the
+* same follow and `mapSpring` machinery as everything else: a spring can
+* follow it (`blur.target = velocityOf(motion)`) and a map can shape it
+* (`mapSpring(velocityOf(motion), (v) => 1 + Math.abs(v) * 0.001)` for
+* squash and stretch). A scalar source yields a scalar velocity a spring
+* can follow; a `CompositeSpring` or shape yields a velocity of the same
+* shape, mapped to a scalar the way the composite itself is.
+*
+* The result is a stateless view, not a spring: it holds no
+* subscriptions and needs no disposal, and reads report the source's
+* current velocity on the fly. It updates when the source does and is
+* released with it — followers detach then, keeping their current
+* target, as they would from a disposed spring.
+*
+* Only a source in motion qualifies — a `Spring` or a `CompositeSpring`.
+* A value derived with `mapSpring` has no velocity (its rate of change
+* would need the derivative of the map), so it is rejected at the type
+* level and at runtime; take `velocityOf` of the spring the map reads
+* instead.
+*/
+function velocityOf(source) {
+	invariant(isKinematicSource(source), NOT_KINEMATIC);
+	const api = source[SpringSourceSymbol];
+	const velocity = Object.freeze({ [SpringSourceSymbol]: Object.freeze({
+		get value() {
+			return api.velocity;
+		},
+		onUpdate: (callback) => api.onUpdate(callback),
+		onDispose: (callback) => api.onDispose(callback)
+	}) });
+	registerRecipe(velocity, {
+		sources: [source],
+		read: () => api.velocity,
+		fns: []
+	});
+	return velocity;
+}
+/**
+* Derives a source from another's acceleration — the rate its velocity
+* changes, in value units per second squared. `accelerationOf(motion)`
+* spikes when `motion` is pushed hardest and passes through zero at the
+* peak of a swing, so force-driven effects fall out of the same follow
+* and `mapSpring` machinery: a spring can follow it, and a map can turn
+* it into an impact flash or a jelly wobble
+* (`mapSpring(accelerationOf(motion), (a) => Math.min(1, Math.abs(a) * 1e-4))`).
+* A scalar source yields a scalar acceleration; a `CompositeSpring` or
+* shape yields an acceleration of the same shape, mapped to a scalar the
+* way the composite itself is.
+*
+* The result is a stateless view, not a spring: it holds no
+* subscriptions and needs no disposal, and reads report the source's
+* current acceleration on the fly. It updates when the source does and
+* is released with it, followers detaching then as from a disposed
+* spring.
+*
+* Only a source in motion qualifies — a `Spring` or a `CompositeSpring`.
+* A value derived with `mapSpring` has no acceleration, so it is rejected
+* at the type level and at runtime; take `accelerationOf` of the spring
+* the map reads instead.
+*/
+function accelerationOf(source) {
+	invariant(isKinematicSource(source), NOT_KINEMATIC);
+	const api = source[SpringSourceSymbol];
+	const acceleration = Object.freeze({ [SpringSourceSymbol]: Object.freeze({
+		get value() {
+			return api.acceleration;
+		},
+		onUpdate: (callback) => api.onUpdate(callback),
+		onDispose: (callback) => api.onDispose(callback)
+	}) });
+	registerRecipe(acceleration, {
+		sources: [source],
+		read: () => api.acceleration,
+		fns: []
+	});
+	return acceleration;
+}
+//#endregion
+export { SpringSourceSymbol, accelerationOf, createSpringSystem, defineSpring, mapSpring, velocityOf };

package/dist/nuxt.d.ts

@@ -1,12 +1,58 @@
 import { NuxtModule } from "@nuxt/schema";
 //#region src/vue/nuxt.d.ts
+/**
+ * Options for the `coily` key in `nuxt.config`, passed to the app-wide
+ * spring system the module creates.
+ */
 interface CoilyModuleOptions {
+  /**
+   * Log active motion counts to the console whenever they change.
+   * @default false
+   */
   debug?: boolean;
+  /**
+   * Frame-rate cap. 0 means uncapped: one tick per displayed frame.
+   * Capped ticks land on whole display frames and receive the true
+   * elapsed time.
+   * @default 0
+   */
   fps?: number;
+  /**
+   * Frame gap in milliseconds above which the gap is treated as lag and
+   * replaced with `adjustedLag`, so springs don't teleport when frames
+   * resume. 0 disables lag clamping.
+   * @default 500
+   */
   lagThreshold?: number;
+  /**
+   * The elapsed milliseconds a lagging frame is replaced with. Clamped
+   * to at most `lagThreshold`.
+   * @default 33
+   */
   adjustedLag?: number;
+  /**
+   * How far a spring may trail a source it follows within one frame, in
+   * the value's own units. Frames whose motion would exceed it split
+   * into internal sub-steps; smaller is tighter and costs more solver
+   * work.
+   * @default 0.1
+   */
+  couplingTolerance?: number;
+  /**
+   * When springs snap to their targets instead of animating: `'user'`
+   * follows the OS prefers-reduced-motion setting, including live
+   * changes; `'always'` and `'never'` force one behavior.
+   * @default 'user'
+   */
   reducedMotion?: 'user' | 'always' | 'never';
 }
+/**
+ * The Nuxt module: creates an app-wide spring system (started on the
+ * client), auto-imports the composables and helpers `useSpring`,
+ * `useSpringSystem`, `useSpringPool`, `defineSpring`, `mapSpring`,
+ * `velocityOf`, and `accelerationOf`, and registers the `SpringValue`
+ * component. Types are left out — they would be noise in most apps.
+ */
 declare const coilyModule: NuxtModule;
 //#endregion
 export { CoilyModuleOptions, coilyModule as default };

package/dist/nuxt.js

@@ -6,6 +6,7 @@ function getPluginTemplate(options) {
 	if (options.fps !== void 0) systemOptions.fps = options.fps;
 	if (options.lagThreshold !== void 0) systemOptions.lagThreshold = options.lagThreshold;
 	if (options.adjustedLag !== void 0) systemOptions.adjustedLag = options.adjustedLag;
+	if (options.couplingTolerance !== void 0) systemOptions.couplingTolerance = options.couplingTolerance;
 	if (options.reducedMotion) systemOptions.reducedMotion = options.reducedMotion;
 	return `import { createSpringSystem } from 'coily'
 import { provideSpringSystem } from 'coily/vue'
@@ -21,6 +22,13 @@ export default defineNuxtPlugin((nuxtApp) => {
   })
 })`;
 }
+/**
+* The Nuxt module: creates an app-wide spring system (started on the
+* client), auto-imports the composables and helpers `useSpring`,
+* `useSpringSystem`, `useSpringPool`, `defineSpring`, `mapSpring`,
+* `velocityOf`, and `accelerationOf`, and registers the `SpringValue`
+* component. Types are left out — they would be noise in most apps.
+*/
 const coilyModule = defineNuxtModule({
 	meta: {
 		name: "coily",
@@ -48,28 +56,20 @@ const coilyModule = defineNuxtModule({
 				name: "useSpringPool"
 			},
 			{
-				from: "coily/vue",
-				name: "SpringRef",
-				type: true
-			},
-			{
-				from: "coily/vue",
-				name: "SpringObjectRef",
-				type: true
+				from: "coily",
+				name: "defineSpring"
 			},
 			{
-				from: "coily/vue",
-				name: "SpringPool",
-				type: true
+				from: "coily",
+				name: "mapSpring"
 			},
 			{
 				from: "coily",
-				name: "defineSpring"
+				name: "velocityOf"
 			},
 			{
 				from: "coily",
-				name: "SpringConfig",
-				type: true
+				name: "accelerationOf"
 			}
 		]);
 		addComponent({