coily 0.13.1 → 0.15.0

package/README.md

@@ -2,9 +2,9 @@
 
 Simulate values using spring physics.
 
-Coily animates numbers — and whole numeric shapes — with damped spring motion. Each frame is computed 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 springs can be retargeted mid-flight without losing momentum.
+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.
 
-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; `vue` and `@nuxt/kit` are optional peer dependencies.
+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.
 
 ## Install
 
@@ -33,7 +33,7 @@ spring.target = 300
 
 ## Configuring springs
 
-`defineSpring` accepts several input shapes; whatever you leave out is derived:
+`defineSpring` accepts several input shapes and derives whatever you leave out:
 
 ```ts
 defineSpring({ tension: 500, damping: 40 }) // direct physical parameters
@@ -41,81 +41,115 @@ 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 })
+defineSpring({ tension: 500, bounce: 0.9, arrival: 'stop' }) // dead-stop at the target, no overshoot
 ```
 
-- **`tension`** — stiffness (> 0)
-- **`damping`** — friction (≥ 0)
-- **`dampingRatio`** — 0 = undamped, < 1 = bouncy, 1 = critically damped, > 1 = overdamped
-- **`bounce`** — friendlier alias for damping ratio: −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. Values are never rounded; set precision to match your domain's resolution (see [PRECISION.md](https://github.com/tkofh/coily/blob/main/PRECISION.md))
+- **`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`**: settle time in ms — the spring rests at this time, within a frame (a bouncy config can rest up to one oscillation earlier). 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))
+- **`arrival`**: what the motion does when the value reaches the target. `'passthrough'` (default) swings through and settles; `'stop'` ends the motion exactly on the target the first time it gets there, however bouncy the config; a number between -1 and 1 scales the velocity at every crossing — negative values rebound. Crossings are solved exactly, never sampled frame by frame (see [PRECISION.md](https://github.com/tkofh/coily/blob/main/PRECISION.md))
 
 Without a config, springs are critically damped with a ~500ms settle time.
 
 ## Spring API
 
-- `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 `SpringConfig`, or `null` to revert to the default (or the leader's, if following)
-- `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)
+- `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 ms until rest — solved from the motion, not estimated (see [PRECISION.md](https://github.com/tkofh/coily/blob/main/PRECISION.md))
+- `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)
 
 ### Chaining
 
-A spring can follow another spring's live value instead of a fixed number:
+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):
 
 ```ts
 const leader = system.createSpring(0)
-const follower = system.createSpring({ target: leader })
-const trailing = system.createSpring({ target: { spring: leader, offset: 20 } })
+
+const follower = system.createSpring(leader)
+const trailing = system.createSpring(mapSpring(leader, (v) => v + 20))
+const mirrored = system.createSpring(mapSpring(leader, (v) => -v))
 ```
 
-Followers inherit the leader's config unless given their own. Assigning a number to `target` unfollows.
+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.
+
+`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:
 
-### Objects
+```ts
+const x = system.createSpring(0)
+const y = system.createSpring(0)
+
+const distance = system.createSpring(mapSpring({ x, y }, ({ x, y }) => Math.hypot(x, y)))
+```
 
-`system.createSpringObject(value, config?)` springs over 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:
+Composite springs (below) are sources of their whole value shape, so one map can derive a scalar from every channel at once:
 
 ```ts
-const spring = system.createSpringObject({ position: { x: 0, y: 0 }, opacity: 1 })
+const point = system.createSpring({ x: 3, y: 4 })
+
+const magnitude = system.createSpring(mapSpring(point, ({ x, y }) => Math.hypot(x, y)))
+```
+
+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.
+
+Chains advance in dependency order: each frame, a spring moves after the springs it follows — whatever order anything was created or wired in — so a follower always chases its leader's current value rather than last frame's. Update events fire once per spring per frame, after every spring has moved, in that same leader-first order. A callback that reads another spring sees its final value for the frame, and a spring retargeted from inside a callback starts moving on the next frame.
 
-spring.target = { position: { x: 100 } } // partial — other channels are left alone
+Following is accurate within the frame, too: a follower integrates against the path its leader actually traveled, not a value sampled once at the frame boundary, and when a single frame carries more motion than the system's `couplingTolerance` allows (0.1 value units by default), the system splits that frame into internal sub-steps. Dropped frames and teleporting targets refine themselves; update events still fire once per frame. The result is that a chain keeps the same shape at 30fps as at 120fps — see https://github.com/tkofh/coily/blob/main/PRECISION.md for the model.
+
+Follow graphs may contain cycles: retargets never re-emit, so nothing loops within a frame. Mutual followers converge to a shared value — the same value at any frame rate. A cycle has no order that puts every member after its leaders, so members advance in creation order and the edge that closes the loop chases one frame behind. 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.
+
+### Composites
+
+`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`:
+
+```ts
+const spring = system.createSpring({ position: { x: 0, y: 0 }, opacity: 1 })
+
+spring.target = { position: { x: 100 } } // a partial target leaves other channels alone
 spring.value // { position: { x, y }, opacity } — a stable, read-only mirror
 ```
 
-The shape is fixed at creation, and unknown channels throw with their path (`position.z`). `value`, `velocity`, and `jumpTo` take the same partial shapes. Composite events are coalesced: `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.
+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.
 
-Shapes are validated at compile time too (the `Shape` type — interfaces like your own `Vector2` work without index signatures): non-numeric, optional, or `undefined`-typed channels are rejected where they're declared.
+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.
 
-Configs apply per channel. Pass a single `SpringConfig` 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:
+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:
 
 ```ts
 spring.config = { position: stiff, opacity: defineSpring({ duration: 300, dampingRatio: 1 }) }
 ```
 
-Configs are `SpringConfig` instances — build them with `defineSpring`. Unlike the scalar `useSpring` above, config positions here 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.
+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.
 
-Spring objects chain channel-wise. Assign another spring object of the exact same shape (optionally with a partial offset shape), and a partial numeric target detaches only the channels it names:
+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
-trailing.target = { spring: leader, offset: { position: { x: 20 } } }
+
+// or mix numbers and live sources per channel
+follower.target = {
+  opacity: 0.5,
+  position: { x: mapSpring(leader, ({ position }) => -position.x) },
+}
 ```
 
 ## Reduced motion
 
-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, velocity impulses are ignored, and springs created displaced start at their target. Events stay coherent — one `update` per change, no `start`/`stop`, and `settled` resolves immediately — so code written against the animated path keeps working.
+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.
 
-Control it with the `reducedMotion` system option: `'user'` (default — follow the OS setting, including live changes, which finish in-flight animations instantly), `'always'`, or `'never'`. Read `system.reducedMotion` to gate purely decorative effects (particles, flourishes) in your own code.
+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.
 
 ## Vue
 
-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 actually created:
+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:
 
 ```ts
 import { useSpringSystem } from 'coily/vue'
@@ -140,13 +174,15 @@ const x = useSpring(target, { duration: 500, bounce: 0.3 })
 </template>
 ```
 
-`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.
+`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.
+
+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.
 
-Numeric shapes work the same way: pass a record or array (plain, ref, or getter) and get a `SpringObjectRef`. Reads are the deep-readonly composite value, writes take partial shapes, options accept reactive per-channel config shapes, and passing another `SpringObjectRef` 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))`.
+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))`.
 
 There's also a renderless `<SpringValue :target="n">` component exposing `{ value, velocity, isResting, timeRemaining, jumpTo }` through its default slot.
 
-For imperative work — a dynamic set of springs created and disposed at arbitrary times (particles, per-item effects) — `useSpringPool()` returns `createSpring`/`createSpringObject` bound to the provided system. Every spring created through the pool is disposed automatically when the component's scope is torn down, so leaked motions are structurally impossible; disposing a spring manually before that is fine.
+`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.
 
 ## Nuxt
 
@@ -164,7 +200,7 @@ The module provides a spring system for the whole app (started on the client), a
 
 ## Timing
 
-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; caps are paced to whole display frames, and each tick still receives the true elapsed time. Large frame gaps — e.g. returning from a backgrounded tab — are clamped 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.
+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.
 
 ## License
 

package/dist/config-OOMMRdK8.d.ts

@@ -0,0 +1,312 @@
+//#region src/config.d.ts
+/**
+ * A spring's instantaneous motion, measured relative to its target.
+ * `SpringDefinition.computeTimeRemaining` takes one; build it from a live
+ * spring as `{ position: spring.value - spring.target, velocity: spring.velocity }`.
+ */
+interface SpringState {
+  /** Displacement from the target in value units. 0 means at the target. */
+  readonly position: number;
+  /** Rate of change of the displacement, in value units per second. */
+  readonly velocity: number;
+}
+interface BaseOptions {
+  /**
+   * Decimal places of the resting threshold. A spring rests once its
+   * remaining motion cannot reach half a unit in the last place —
+   * `0.5 * 10^-precision`, or 0.005 at the default.
+   *
+   * Values are never rounded; precision only decides rest. See
+   * https://github.com/tkofh/coily/blob/main/PRECISION.md.
+   *
+   * @default 2
+   */
+  readonly precision?: number | undefined;
+  /**
+   * What the motion does when the value reaches the target, as a
+   * multiplier applied to the velocity at every crossing.
+   *
+   * - `'passthrough'` — multiplier 1. The motion is untouched: the value
+   *   swings through the target and settles as its damping dictates.
+   * - `'stop'` — multiplier 0. Motion ends at the target the first time
+   *   the value gets there, with no overshoot, however bouncy the config.
+   * - A number between -1 and 1 sets the multiplier directly. Negative
+   *   values rebound: `-0.75` reverses the motion with three quarters of
+   *   its speed, at every return. Values between 0 and 1 pass through
+   *   slowed.
+   *
+   * Crossings are solved from the motion's closed form, never sampled
+   * frame by frame, so a `'stop'` lands the value exactly on the target
+   * whatever the frame timing. See
+   * https://github.com/tkofh/coily/blob/main/PRECISION.md.
+   *
+   * @default 'passthrough'
+   */
+  readonly arrival?: 'passthrough' | 'stop' | number | undefined;
+}
+interface WithMass {
+  /**
+   * Mass of the moving value. Heavier springs accelerate more slowly and
+   * carry more momentum through the target. Must be greater than 0.
+   * @default 1
+   */
+  readonly mass?: number | undefined;
+}
+interface WithoutMass {
+  /**
+   * Mass is derived from the other parameters in this input shape
+   * and cannot be provided.
+   */
+  readonly mass?: undefined;
+}
+interface WithTension {
+  /**
+   * Spring stiffness. Higher tension pulls toward the target harder,
+   * making the whole motion faster. Must be greater than 0.
+   */
+  readonly tension: number;
+}
+interface WithDamping {
+  /**
+   * Friction strength. Higher damping bleeds off velocity faster and
+   * reduces bounce; at 0 the spring oscillates forever. Must be greater
+   * than or equal to 0.
+   */
+  readonly damping: number;
+}
+interface WithDampingRatio {
+  /**
+   * Damping as a fraction of critical damping — the character of the
+   * motion, independent of its speed. Below 1 the spring overshoots and
+   * bounces. At 1 it settles as fast as possible without overshooting.
+   * Above 1 it settles slower, still without overshooting. At 0 it never
+   * settles. Must be greater than or equal to 0.
+   */
+  readonly dampingRatio: number;
+}
+interface WithBounce {
+  /**
+   * Bounciness, converted to a damping ratio as `1 - bounce`. 0 settles
+   * as fast as possible without overshooting. Positive values overshoot
+   * and bounce; 1, maximum bounce, is clamped just short of undamped so
+   * the spring still settles. Negative values settle without bounce, more
+   * slowly. Must be between -1 and 1.
+   */
+  readonly bounce: number;
+}
+interface WithDuration {
+  /**
+   * Settle time in milliseconds. The spring is tuned so it rests at this
+   * time, assuming it starts `displacement` away from the target: rest
+   * lands within a frame of the requested duration, and a bouncy config
+   * can rest up to one oscillation earlier. Must be greater than 0.
+   */
+  readonly duration: number;
+}
+interface WithDisplacement {
+  /**
+   * The initial displacement the duration tuning assumes. Set it to your
+   * animation's range — 300 when animating 0 to 300 — so the settle
+   * timing holds; timing skews as the real displacement diverges from
+   * this value. Must not be 0.
+   * @default 1
+   */
+  readonly displacement?: number | undefined;
+}
+interface DirectOptions extends BaseOptions, WithMass, WithTension, WithDamping {}
+interface TensionRatioOptions extends BaseOptions, WithMass, WithTension, WithDampingRatio {}
+interface TensionBounceOptions extends BaseOptions, WithMass, WithTension, WithBounce {}
+interface DampingRatioOptions extends BaseOptions, WithMass, WithDamping, WithDampingRatio {}
+interface DampingBounceOptions extends BaseOptions, WithMass, WithDamping, WithBounce {}
+interface TensionDampingRatioOptions extends BaseOptions, WithoutMass, WithTension, WithDamping, WithDampingRatio {}
+interface TensionDampingBounceOptions extends BaseOptions, WithoutMass, WithTension, WithDamping, WithBounce {}
+interface DurationOptions extends BaseOptions, WithMass, WithDampingRatio, WithDuration, WithDisplacement {}
+interface BounceDurationOptions extends BaseOptions, WithMass, WithBounce, WithDuration, WithDisplacement {}
+interface TensionDurationOptions extends BaseOptions, WithoutMass, WithTension, WithDampingRatio, WithDuration, WithDisplacement {}
+interface TensionBounceDurationOptions extends BaseOptions, WithoutMass, WithTension, WithBounce, WithDuration, WithDisplacement {}
+interface DampingDurationOptions extends BaseOptions, WithoutMass, WithDamping, WithDampingRatio, WithDuration, WithDisplacement {}
+interface DampingBounceDurationOptions extends BaseOptions, WithoutMass, WithDamping, WithBounce, WithDuration, WithDisplacement {}
+/** Every option key accepted by at least one `defineSpring` input shape. */
+type SpringOptionKeys = 'mass' | 'tension' | 'damping' | 'dampingRatio' | 'bounce' | 'duration' | 'displacement' | 'precision' | 'arrival';
+/**
+ * Marks every option key foreign to `T` as "absent or undefined", so mixing
+ * properties from different input shapes fails to type-check instead of
+ * silently resolving to an unintended shape at runtime.
+ */
+type Exact<T> = T & { [K in Exclude<SpringOptionKeys, keyof T>]?: undefined; };
+/**
+ * Every input `defineSpring` accepts: one of the documented parameter
+ * combinations, exactly as written — keys from different combinations
+ * don't mix.
+ */
+type SpringDefinitionOptions = Exact<DirectOptions> | Exact<TensionRatioOptions> | Exact<TensionBounceOptions> | Exact<DampingRatioOptions> | Exact<DampingBounceOptions> | Exact<TensionDampingRatioOptions> | Exact<TensionDampingBounceOptions> | Exact<DurationOptions> | Exact<BounceDurationOptions> | Exact<TensionDurationOptions> | Exact<TensionBounceDurationOptions> | Exact<DampingDurationOptions> | Exact<DampingBounceDurationOptions>;
+/**
+ * Immutable, resolved spring parameters. Whatever `defineSpring` input
+ * shape produced it, a config carries concrete `mass`, `tension`,
+ * `damping`, and `precision`, plus the quantities derived from them.
+ * Instances are frozen and safe to share between springs; to change a
+ * spring's behavior, assign a new config via `spring.config`.
+ */
+declare class SpringDefinition {
+  /** The config for springs created without one: critically damped, settling in about 500ms. */
+  static readonly default: SpringDefinition;
+  /** Mass of the moving value, as provided or derived. */
+  readonly mass: number;
+  /** Spring stiffness, as provided or derived. */
+  readonly tension: number;
+  /** Friction strength, as provided or derived. */
+  readonly damping: number;
+  /** Decimal places of the resting threshold — see `restingMagnitude`. */
+  readonly precision: number;
+  /**
+   * Velocity multiplier applied when the value crosses the target, as
+   * provided or resolved from its named form. 1 (`'passthrough'`) leaves
+   * the motion untouched, 0 (`'stop'`) ends it at the target, negative
+   * values rebound.
+   */
+  readonly arrival: number;
+  /** Oscillation rate with no damping: `sqrt(tension / mass)`, in radians per second. */
+  readonly naturalFrequency: number;
+  /** The damping at which bounce disappears: `2 * mass * naturalFrequency`. */
+  readonly criticalDamping: number;
+  /**
+   * `damping / criticalDamping`. Below 1 the spring overshoots and
+   * bounces, at 1 it settles fastest without overshooting, above 1 it
+   * settles slower.
+   */
+  readonly dampingRatio: number;
+  /** Resting threshold in value units: half a unit in the last `precision` place. */
+  readonly restingMagnitude: number;
+  constructor(input: SpringDefinitionOptions);
+  /**
+   * Computes when a spring with this config comes to rest from `state`,
+   * in ms.
+   *
+   * The time is solved from the motion's decay bound rather than
+   * estimated: the spring is resting at the first tick at or after it.
+   * An underdamped spring can also rest earlier — its rest amplitude
+   * pulses, and a frame that samples a dip inside the resting threshold
+   * rests there — so read the value as "no later than", tight in
+   * practice. See
+   * https://github.com/tkofh/coily/blob/main/PRECISION.md.
+   *
+   * Returns 0 when `state` is already inside the resting threshold.
+   * Returns Infinity when the motion never settles: a `dampingRatio` of
+   * 0 whose `arrival` neither stops nor slows it. When `arrival` is 0
+   * the result is capped at the first target crossing, where such a
+   * spring rests exactly; other multipliers fold their per-crossing
+   * velocity loss into the time.
+   */
+  computeTimeRemaining(state: SpringState): number;
+}
+/**
+ * Creates a config from direct physical parameters: you set stiffness
+ * and friction exactly.
+ */
+declare function defineSpring(input: Exact<DirectOptions>): SpringDefinition;
+/**
+ * Creates a config from stiffness and motion character. Damping is
+ * derived as `2 * dampingRatio * sqrt(mass * tension)`.
+ */
+declare function defineSpring(input: Exact<TensionRatioOptions>): SpringDefinition;
+/**
+ * Creates a config from stiffness and bounciness. Damping is derived to
+ * match the requested bounce, from -1 (no bounce, slow settle) to 1
+ * (maximum bounce).
+ */
+declare function defineSpring(input: Exact<TensionBounceOptions>): SpringDefinition;
+/**
+ * Creates a config from friction and motion character. Tension is
+ * derived as `damping^2 / (4 * dampingRatio^2 * mass)`; `dampingRatio`
+ * must be greater than 0.
+ */
+declare function defineSpring(input: Exact<DampingRatioOptions>): SpringDefinition;
+/**
+ * Creates a config from friction and bounciness. Tension is derived to
+ * match the requested bounce; `bounce` must be less than 1.
+ */
+declare function defineSpring(input: Exact<DampingBounceOptions>): SpringDefinition;
+/**
+ * Creates a config from all three physical knobs. Mass is derived as
+ * `damping^2 / (4 * dampingRatio^2 * tension)` and cannot be provided;
+ * `dampingRatio` must be greater than 0.
+ */
+declare function defineSpring(input: Exact<TensionDampingRatioOptions>): SpringDefinition;
+/**
+ * Creates a config from all three physical knobs. Mass is derived from
+ * tension, damping, and the requested bounce, and cannot be provided;
+ * `bounce` must be less than 1.
+ */
+declare function defineSpring(input: Exact<TensionDampingBounceOptions>): SpringDefinition;
+/**
+ * Tunes the spring to rest at `duration` milliseconds, with
+ * `dampingRatio` setting the motion's character. Tension and damping are
+ * both derived.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target — pass a `displacement` matching your animation range
+ * for accurate timing.
+ *
+ * @example
+ * ```ts
+ * // Tuned for a 300px move; rests within 750ms
+ * defineSpring({ duration: 750, dampingRatio: 1, displacement: 300 })
+ * ```
+ */
+declare function defineSpring(input: Exact<DurationOptions>): SpringDefinition;
+/**
+ * Tunes the spring to rest at `duration` milliseconds, with
+ * `bounce` setting how oscillatory the settling motion is. Tension and
+ * damping are both derived.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target — pass a `displacement` matching your animation range
+ * for accurate timing.
+ */
+declare function defineSpring(input: Exact<BounceDurationOptions>): SpringDefinition;
+/**
+ * Tunes a spring of the given stiffness to rest at `duration`
+ * milliseconds. Mass is derived from tension and the computed natural
+ * frequency, then damping from mass and `dampingRatio`; mass cannot be
+ * provided.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target — pass a `displacement` matching your animation range
+ * for accurate timing.
+ */
+declare function defineSpring(input: Exact<TensionDurationOptions>): SpringDefinition;
+/**
+ * Tunes a spring of the given stiffness to rest at `duration`
+ * milliseconds, with `bounce` setting how oscillatory the settling motion
+ * is. Mass is derived from tension and the computed natural frequency,
+ * and cannot be provided.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target — pass a `displacement` matching your animation range
+ * for accurate timing.
+ */
+declare function defineSpring(input: Exact<TensionBounceDurationOptions>): SpringDefinition;
+/**
+ * Tunes a spring of the given friction to rest at `duration`
+ * milliseconds. Mass is derived from damping, `dampingRatio`, and the
+ * computed natural frequency, then tension from mass; mass cannot be
+ * provided.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target — pass a `displacement` matching your animation range
+ * for accurate timing.
+ */
+declare function defineSpring(input: Exact<DampingDurationOptions>): SpringDefinition;
+/**
+ * Tunes a spring of the given friction to rest at `duration`
+ * milliseconds, with `bounce` setting how oscillatory the settling motion
+ * is. Mass is derived from damping and the computed natural frequency,
+ * and cannot be provided.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target — pass a `displacement` matching your animation range
+ * for accurate timing.
+ */
+declare function defineSpring(input: Exact<DampingBounceDurationOptions>): SpringDefinition;
+//#endregion
+export { defineSpring as i, SpringDefinitionOptions as n, SpringState as r, SpringDefinition as t };