coily 0.12.2 → 0.14.0

package/README.md

@@ -1,254 +1,201 @@
-# `coily`
+# coily
 
-Spring Physics Utilities
+Simulate values using spring physics.
 
-## Installation & Setup
+Coily animates numbers and whole numeric shapes with damped spring motion. It computes each frame from the closed-form solution of the spring equation (underdamped, critically damped, or overdamped) rather than numerical integration, so motion doesn't accumulate error and you can retarget a spring mid-flight without losing momentum.
 
-`coily` is available on npm and can be installed with your favorite package manager:
+The core has zero dependencies and runs anywhere (it falls back from `requestAnimationFrame` to `setTimeout` outside the browser). Vue and Nuxt integrations ship as separate entry points, with `vue` and `@nuxt/kit` as optional peer dependencies.
 
-```shell
-$ yarn add coily
-# or
-$ npm i coily
+## Install
+
+```sh
+pnpm add coily
 ```
 
-Then import the creator from the package in your code:
+## Quick start
 
-```typescript
-import { createSpring } from 'coily'
+```ts
+import { createSpringSystem, defineSpring } from 'coily'
 
-const spring = createSpring(0, { mass: 1, tension: 100, friction: 25 })
-```
+const system = createSpringSystem()
+system.start()
 
-## Usage
+const spring = system.createSpring(0, defineSpring({ tension: 500, damping: 40 }))
 
-### Creating a Spring
+spring.onUpdate(() => {
+  ball.style.setProperty('--x', String(spring.value))
+})
+
+// Animate toward a new target at any time. Position and velocity
+// carry over, so interruptions look natural.
+spring.target = 300
+```
 
-The `createSpring` function takes the following arguments:
+## Configuring springs
 
-- `initial: number`
-  The initial value of the spring, and its target. All springs start in a resting state, but you can set `spring.target`
-  at any time
+`defineSpring` accepts several input shapes and derives whatever you leave out:
 
-- `config: SpringConfig`
-  The configuration for the spring. `SpringConfig` takes the following parameters:
-  - `config.mass: number`
-    How massive the spring is. A lower number will allow the spring to speed up and slow down more quickly than a
-    larger number. Larger numbers are more likely to overshoot the `target`
+```ts
+defineSpring({ tension: 500, damping: 40 }) // direct physical parameters
+defineSpring({ tension: 500, dampingRatio: 0.7 }) // damping derived
+defineSpring({ tension: 500, bounce: 0.3 }) // bounce = 1 - dampingRatio
+defineSpring({ duration: 750, dampingRatio: 1 }) // tuned to settle in ~750ms
+defineSpring({ duration: 750, bounce: 0.5 })
+```
 
-  - `config.tension: number`
-    How much force the spring experiences toward its `target`. A higher value will move the spring more quickly, and
-    allow the spring to potentially overshoot.
+- **`tension`**: stiffness (> 0)
+- **`damping`**: friction (>= 0)
+- **`dampingRatio`**: 0 = undamped, < 1 = bouncy, 1 = critically damped, > 1 = overdamped
+- **`bounce`**: a friendlier alias for damping ratio, from -1 (overdamped) to 1 (max bounce)
+- **`duration`**: target settle time in ms. Assumes an initial displacement of 1. Pass `displacement` matching your animation range for accurate timing
+- **`mass`**: defaults to 1
+- **`precision`**: decimal places of the resting threshold (default 2). A spring is _resting_ once its remaining motion cannot reach half a unit in the last place (0.005 at the default). Coily never rounds values. Set `precision` to match your domain's resolution (see [PRECISION.md](https://github.com/tkofh/coily/blob/main/PRECISION.md))
 
-  - `config.friction: number`
-    How much dampening the spring experiences against its tension. A higher friction will make sure the spring doesn't
-    move too quickly, and slows down dramatically as it approaches the `target`
+Without a config, springs are critically damped with a ~500ms settle time.
 
-- `options: SpringOptions`
-  Additional options for the spring. `SpringOptions` takes the following parameters:
-  - `options.restingDistance: number`
-    The minimum difference between the `target` and `value` at which the spring will consider itself "at" the `target`
+## Spring API
 
-  - `options.restingVelocity: number`
-    The minimum velocity at which the spring will consider itself "not moving"
+- `spring.target`: set to animate toward a new value
+- `spring.value`: current value, writable to displace the spring
+- `spring.velocity`: current velocity, writable to fling
+- `spring.jumpTo(v)`: snap to a value with no animation
+- `spring.config`: assign a new `SpringDefinition`, or `null` to revert to the default
+- `spring.isResting`, `spring.timeRemaining`: settle state and estimated ms until rest
+- `spring.settled`: a promise that resolves when the spring next comes to rest (immediately if already resting). Retargeting mid-flight extends the wait; disposing resolves it. `await spring.settled` to sequence animations
+- `spring.onUpdate(cb)` / `onStart(cb)` / `onStop(cb)` / `onDispose(cb)`: subscribe. Each returns an unsubscribe function. `start` fires when the spring leaves rest, `stop` when it settles. The two always alternate, and retargeting mid-flight fires neither
+- `spring.dispose()`: release the spring (calling it twice is a no-op)
 
-  - `options.arrivalBehavior: 'bounce' | 'clamp' | 'none' | number | ((velocity: number) => number)`
-    How the spring's `velocity` behaves when it arrives at its `target` value.
-    `velocity` is expressed in unit/second. Defaults to `none`.
-    - `'bounce'`: multiplies the velocity by -1, bouncing the value back in the direction from which it came
-    - `'clamp'`: multiplies the velocity by 0, instantly stopping the spring at its value
-    - `'none'`: multiplies the velocity by 1, allowing the spring to overshoot as necessary
-    - `number`: multiplies the velocity by the given number
-    - `(velocity: number) => number`: sets the velocity to the result of a function whose only argument is the
-      previous velocity
+### Chaining
 
-#### Spring Config Tips
+A spring can follow another spring's live value instead of a fixed number: assign a spring to `target`, or pass one straight to `createSpring` to follow from birth. `mapSpring` derives new followable values from existing ones (offsets, mirrors, clamps, any pure function of the value):
 
-The configuration object above provides a good starting point when picking your config:
+```ts
+const leader = system.createSpring(0)
 
-```typescript
-createSpring(0, { mass: 1, tension: 100, friction: 25 })
+const follower = system.createSpring(leader)
+const trailing = system.createSpring(mapSpring(leader, (v) => v + 20))
+const mirrored = system.createSpring(mapSpring(leader, (v) => -v))
 ```
 
-Don't be afraid to make `mass` a decimal, and don't be afraid of large tensions and frictions either. Picking the
-configuration is more of an art than a science.
+A follower's config is its own: following changes what a spring chases, never how it moves. To match a leader's feel, pass its config at creation — `system.createSpring(leader, leader.config)` — or share a `defineSpring` constant. Assigning a number to `target` unfollows.
 
-#### Spring Options
+`mapSpring` also combines several springs: pass a shape (a plain object or array with springs at the leaves, nested arbitrarily) and a function of their values:
 
-The spring options object is helpful in reducing the amount of computation your springs perform. If the spring was
-allowed to wait until its `velocity` and difference (`value` - `target`) were _at_ zero, it would imperceptibly update
-every frame for a very long time.
+```ts
+const x = system.createSpring(0)
+const y = system.createSpring(0)
 
-The `restingDistance` and `restingVelocity` options help combat this, by telling the spring at what point it should
-consider itself on target and resting. Once the velocity is less than `restingVelocity` and the difference
-between `value` and `target` is less than `restingDistance`, the spring sets its `value` to its `target` and enters
-the `resting` state.
+const distance = system.createSpring(mapSpring({ x, y }, ({ x, y }) => Math.hypot(x, y)))
+```
 
-### Working With Springs
+Composite springs (below) are sources of their whole value shape, so one map can derive a scalar from every channel at once:
 
-#### Reading Information
+```ts
+const point = system.createSpring({ x: 3, y: 4 })
 
-The spring exposes some readonly information such as its `value`, `state` and `velocity`:
+const magnitude = system.createSpring(mapSpring(point, ({ x, y }) => Math.hypot(x, y)))
+```
 
-```typescript
-/**
- * The current value of the spring
- */
-spring.value
+A mapped value is a `SpringSource`, the contract `target` accepts and every `Spring` implements. A `CompositeSpring` is a source _of its shape_: `mapSpring` reads it, alone or at the leaves of a shape, but only scalar sources can be followed directly.
 
-/**
- * In which state the spring is currently. Will be one of:
- * - "resting"
- * - "moving"
- * - "frozen"
- */
-spring.state
+Follow graphs may contain cycles: retargets never re-emit, so nothing loops within a frame. Mutual followers converge to a shared value. A cycle whose maps expand (`(v) => v + 10` in both directions) chases forever and never rests, keeping the system awake until you break the cycle.
 
-/**
- * How fast the spring is currently moving, and in which direction
- */
-spring.velocity
-```
+### Composites
 
-Additionally, `target` and `config` can be updated whenever:
+`createSpring` also takes any numeric shape: a plain object or array whose leaves are all numbers, nested arbitrarily. Each leaf becomes an independent channel behind one composite API, a `CompositeSpring`:
 
-```typescript
-/**
- * Get & Set the target of the spring
- */
-console.log(spring.target)
-spring.target = 10
+```ts
+const spring = system.createSpring({ position: { x: 0, y: 0 }, opacity: 1 })
 
-/**
- * Get & Set the config of the spring
- */
-console.log(spring.config)
-spring.config = { mass: 0.1, tension: 500, friction: 5 }
+spring.target = { position: { x: 100 } } // a partial target leaves other channels alone
+spring.value // { position: { x, y }, opacity } — a stable, read-only mirror
 ```
 
-#### Updating
+The shape is fixed at creation, and unknown channels throw with their path (`position.z`). `value`, `velocity`, and `jumpTo` take the same partial shapes. Composites coalesce their events: `update` fires at most once per frame with every channel in its final per-frame state, and `stop` always lands after that frame's final `update`. `settled` and reduced motion compose channel-wise.
 
-To simulate the spring and update its value, call the `simulate` method and pass in the number of milliseconds since the
-last update:
+The `Shape` type validates shapes at compile time too (interfaces like your own `Vector2` work without index signatures) and rejects non-numeric, optional, or `undefined`-typed channels where they're declared.
 
-```typescript
-// Tickloop is a library that exposes a simple requestAnimationFrame based update loop
-import { createTicker } from 'tickloop'
-import { createSpring } from 'coily'
+Configs apply per channel. Pass a single `SpringDefinition` for every channel, or a shape mirroring the value with configs (or `null` to revert) at any level. A config at a subtree covers every channel below it:
 
-const spring = createSpring(0, { mass: 1, tension: 100, friction: 20 })
+```ts
+spring.config = { position: stiff, opacity: defineSpring({ duration: 300, dampingRatio: 1 }) }
+```
 
-const ticker = createTicker()
-ticker.add((_, delta) => {
-  spring.simulate(delta)
-})
+Configs are `SpringDefinition` instances, built with `defineSpring`. Config positions don't accept bare option objects: a plain object is always a per-channel shape, so any non-config leaf it reaches throws with its path.
+
+Composite springs chain channel-wise. Assign another composite spring of the exact same shape to follow it whole, or name channels individually: each channel of a partial target takes a number or a scalar `SpringSource`. While following, a partial target detaches only the channels it names:
+
+```ts
+follower.target = leader
+
+// or mix numbers and live sources per channel
+follower.target = {
+  opacity: 0.5,
+  position: { x: mapSpring(leader, ({ position }) => -position.x) },
+}
 ```
 
-#### Freezing
+## Reduced motion
 
-To hold a spring in place (while maintaining its velocity), use the `freeze()` (and `unfreeze()`) methods.
-Calling `freeze()` will set the spring's `state` to `'frozen'`
+Coily respects `prefers-reduced-motion` by default. When it's active, springs snap to their targets instead of animating: retargets and value writes apply instantly, and springs ignore velocity impulses. Events stay coherent (one `update` per change, no `start`/`stop`, and `settled` resolves immediately), so code written against the animated path keeps working.
 
-```typescript
-const spring = createSpring(0, { mass: 1, tension: 100, friction: 20 })
+Control it with the `reducedMotion` system option: `'always'`, `'never'`, or the default `'user'`, which follows the OS setting — a live change finishes in-flight animations instantly. Read `system.reducedMotion` to gate decorative effects (particles, flourishes) in your own code.
 
-spring.target = 100
+## Vue
 
-console.log(spring.value) // 0
+Call `useSpringSystem()` once near the root of your app. It returns the spring system provided by this component or an ancestor. If none exists, it creates one, provides it to descendants, and starts/stops it with the component lifecycle. It's idempotent, and options apply only when a system is created:
 
-spring.freeze()
-spring.simulate(1000)
+```ts
+import { useSpringSystem } from 'coily/vue'
 
-console.log(spring.value) // 0
+const system = useSpringSystem() // e.g. read system.reducedMotion to gate decorative effects
 ```
 
-### Creating a Spring System
+(`provideSpringSystem(system, app?)` remains for plugging in a system you created yourself — mostly useful in tests. You manage `start()`/`stop()` for it.)
 
-Manually updating every spring with its `simulate` method would be tedious to say the least. Where possible, prefer
-using a `SpringSystem` to group springs together and provide a single call site for updating each spring:
+Then animate anywhere below:
 
-```typescript
-import { createSpringSystem } from 'coily'
+```vue
+<script setup>
+import { useSpring } from 'coily/vue'
 
-// First, create the system
-const system = createSpringSystem()
-
-// Then, create some springs
-const spring1 = system.createSpring(0, { mass: 1, tension: 100, friction: 20 })
-const spring2 = system.createSpring(0, { mass: 0.25, tension: 50, friction: 10 })
+const target = ref(0)
+const x = useSpring(target, { duration: 500, bounce: 0.3 })
+</script>
 
-// Simulate all springs at once from the system
-system.simulate(16)
+<template>
+  <div class="ball" :style="{ translate: `${x}px 0` }" @click="target = 300" />
+</template>
 ```
 
-Should a spring become irrelevant for some reason, remember to call the `cleanup` method so that the system stops
-updating it:
+`useSpring` returns a `SpringRef`: a writable ref of the animated value with `velocity`, `isResting`, and `timeRemaining` refs plus `jumpTo()` attached. The target can be a ref, a getter, or another `SpringRef` (which chains the springs). Options are also reactive: swap configs and the spring reconfigures in place.
 
-```typescript
-import { createSpringSystem } from 'coily'
+A `SpringRef` is also a `SpringSource`, and `useSpring` follows any source: chain through `mapSpring` (`useSpring(mapSpring({ x, y }, ({ x, y }) => Math.hypot(x, y)))`), or pass a getter of a source to switch leaders reactively (`useSpring(() => (split.value ? left : right))`). Following bypasses Vue reactivity — followers subscribe to the backing spring directly — so an effect or getter never gains a dependency on a leader's animation.
 
-const system = createSpringSystem()
+Numeric shapes work the same way: pass a record or array (plain, ref, or getter) and get a `CompositeSpringRef`. Reads are the deep-readonly composite value, writes take partial shapes, options accept reactive per-channel config shapes, and passing another `CompositeSpringRef` follows it channel-wise. Deeply reactive targets retarget on nested mutation. For several _independent_ scalar springs, map over the targets (composables are loop-safe): `targets.map((t) => useSpring(t))`.
 
-const spring = system.createSpring(0, { mass: 1, tension: 100, friction: 20 })
+There's also a renderless `<SpringValue :target="n">` component exposing `{ value, velocity, isResting, timeRemaining, jumpTo }` through its default slot.
 
-// Later
+`useSpringPool()` covers imperative work: a dynamic set of springs created and disposed at arbitrary times (particles, per-item effects). It returns `createSpring` bound to the provided system. The pool disposes every spring created through it when the component's scope is torn down, so leaked motions are structurally impossible. Disposing a spring manually before that is fine.
 
-system.cleanup(spring)
-```
+## Nuxt
 
-### Spring Chains
-
-Sometimes the `target` of one spring should be the `value` of another.
-This can be tedious to set up manually and involves juggling multiple updates per frame to get a good look at the
-current state.
-
-Spring Chains help with this problem by building on the `createSpring` API. You'll still supply an `initial` target,
-a `SpringConfig`, and an optional `SpringOptions`. You'll also pass an array of chain "links" that describe additional
-values in the chain.
-
-The links take one of two forms:
-
-- A fixed, additive offset from the previous value, e.g. `50` will make Spring 2 target Spring 1's current value plus 50.
-- A function with the following signature:
-  ```typescript
-  const link = (
-    previousSpringValue: number,
-    previousSpringTarget: number,
-    currentSpringValue?: number,
-    currentSpringTarget?: number
-  ): number => /* ... */
-  ```
-  The `currentSpringTarget` and `currentSpringValue` will be `undefined` the first time the function is called, as the
-  targets are initialized for all springs.
-
-#### Creating
-
-```typescript
-const chain = createSpringChain(
-  0, // initial
-  [50, 50, (value) => value * 1.25],
-  { mass: 10, tension: 3000, friction: 300 }, // config
-)
+```ts
+export default defineNuxtConfig({
+  modules: ['coily/nuxt'],
+  coily: {
+    debug: false, // debug logs active motion counts
+    reducedMotion: 'user', // 'user' | 'always' | 'never'
+  },
+})
 ```
 
-#### Reading State
-
-Spring Chains have almost the same interface as Springs do.
+The module provides a spring system for the whole app (started on the client), auto-imports `useSpring`, `useSpringSystem`, `useSpringPool`, and `defineSpring`, and registers the `SpringValue` component.
 
-Instead of a single `value`, they have an array of numbers as their value. The same goes for `targets`, `states`,
-and `velocities`. Each of these arrays are updated _in place_, which means it is safe to grab a reference to the value
-and read from it later.
+## Timing
 
-Additionally, Spring Chains have a singular `state` property which indicates if _any_ of its links are in a `'moving'` state or not.
+The built-in ticker advances springs once per displayed frame, so motion is as smooth as the screen it runs on: 60Hz, 120Hz, or adaptive sync. The loop sleeps while every spring is at rest (an idle system schedules no frames) and wakes on the next write. Set `fps` (option/property) to cap the rate: capped ticks land on whole display frames and still receive the true elapsed time. The ticker clamps large frame gaps (e.g. returning from a backgrounded tab) via `lagThreshold` (default 500ms) and `adjustedLag` (default 33ms), so springs don't teleport. For manual stepping, skip `system.start()` and call `system.advance(dtMs)` yourself.
 
-There is also a singular `target` property which returns the first target in the chain. Setting this will update the springs as well.
+## License
 
-```typescript
-chain.values // readonly number[]
-chain.velocities // readonly number[]
-chain.targets // readonly number[]
-chain.states // readonly number[]
-
-chain.target = 10 // get and set the first target
-chain.state // if any children are 'moving', this will be moving. if the chain is frozen, it will be 'frozen'. otherwise, it is 'resting'.
-```
+MIT

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { _ as defineSpring, a as Spring2D, c as Spring2DWithOffset, d as SpringPosition, f as SpringTarget, g as SpringState, h as SpringOptions, i as TickerOptions, l as Vector2, m as SpringConfig, n as SpringSystemOptions, o as Spring2DPosition, p as SpringWithOffset, r as createSpringSystem, s as Spring2DTarget, t as SpringSystem, u as Spring } from "./system-coAFNYnb.js";
-export { type Spring, type Spring2D, type Spring2DPosition, type Spring2DTarget, type Spring2DWithOffset, type SpringConfig, type SpringOptions, type SpringPosition, type SpringState, type SpringSystem, type SpringSystemOptions, type SpringTarget, type SpringWithOffset, type TickerOptions, type Vector2, createSpringSystem, defineSpring };
+import { C as SpringDefinitionOptions, S as SpringDefinition, T as defineSpring, _ 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, w as SpringState, x as mapSpring, y as SpringSource } from "./system-Ci-R4RaI.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,78 @@
-import { r as defineSpring, t as createSpringSystem } from "./system-Bzrx4uso.js";
-export { createSpringSystem, defineSpring };
+import { i as mapSpring, n as SpringSourceSymbol, o as defineSpring, r as isSpringSource, s as invariant, t as createSpringSystem } from "./system-BXxAHM2a.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];
+	return Object.freeze({ [SpringSourceSymbol]: Object.freeze({
+		get value() {
+			return api.velocity;
+		},
+		onUpdate: (callback) => api.onUpdate(callback),
+		onDispose: (callback) => api.onDispose(callback)
+	}) });
+}
+/**
+* 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];
+	return Object.freeze({ [SpringSourceSymbol]: Object.freeze({
+		get value() {
+			return api.acceleration;
+		},
+		onUpdate: (callback) => api.onUpdate(callback),
+		onDispose: (callback) => api.onDispose(callback)
+	}) });
+}
+//#endregion
+export { SpringSourceSymbol, accelerationOf, createSpringSystem, defineSpring, mapSpring, velocityOf };

package/dist/nuxt.d.ts

@@ -1,9 +1,50 @@
 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;
+  /**
+   * 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

@@ -1,12 +1,18 @@
 import { addComponent, addImports, addPluginTemplate, defineNuxtModule } from "@nuxt/kit";
 //#region src/vue/nuxt.ts
 function getPluginTemplate(options) {
+	const systemOptions = {};
+	if (options.debug) systemOptions.debug = true;
+	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.reducedMotion) systemOptions.reducedMotion = options.reducedMotion;
 	return `import { createSpringSystem } from 'coily'
 import { provideSpringSystem } from 'coily/vue'
 
 export default defineNuxtPlugin((nuxtApp) => {
   nuxtApp.hook('app:created', (vueApp) => {
-    const system = createSpringSystem(${options.debug ? "{ debug: true }" : ""})
+    const system = createSpringSystem(${Object.keys(systemOptions).length > 0 ? JSON.stringify(systemOptions) : ""})
     provideSpringSystem(system, vueApp)
 
     if(import.meta.client) {
@@ -15,6 +21,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",
@@ -35,26 +48,27 @@ const coilyModule = defineNuxtModule({
 			},
 			{
 				from: "coily/vue",
-				name: "useSpring2D"
+				name: "useSpringSystem"
 			},
 			{
 				from: "coily/vue",
-				name: "SpringRef",
-				type: true
+				name: "useSpringPool"
 			},
 			{
-				from: "coily/vue",
-				name: "SpringRef2D",
-				type: true
+				from: "coily",
+				name: "defineSpring"
 			},
 			{
 				from: "coily",
-				name: "defineSpring"
+				name: "mapSpring"
+			},
+			{
+				from: "coily",
+				name: "velocityOf"
 			},
 			{
 				from: "coily",
-				name: "SpringConfig",
-				type: true
+				name: "accelerationOf"
 			}
 		]);
 		addComponent({