coily 0.15.0 → 0.16.0

package/dist/{config-OOMMRdK8.d.ts → config-B8M2xp26.d.ts}

@@ -1,7 +1,7 @@
 //#region src/config.d.ts
 /**
  * A spring's instantaneous motion, measured relative to its target.
- * `SpringDefinition.computeTimeRemaining` takes one; build it from a live
+ * `SpringDefinition.computeTimeRemaining` takes one. Build it from a live
  * spring as `{ position: spring.value - spring.target, velocity: spring.velocity }`.
  */
 interface SpringState {
@@ -13,31 +13,34 @@ interface SpringState {
 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.
+   * remaining motion fits within `0.5 * 10^-precision` (0.005 at the
+   * default). Values are never rounded.
    *
-   * Values are never rounded; precision only decides rest. See
+   * Duration configs are tuned against this threshold, so they rest at
+   * their `duration` at any precision. 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.
+   * Velocity multiplier applied each time the value crosses the target.
    *
-   * - `'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.
+   * - `'passthrough'` (1) leaves the motion alone. The value swings
+   *   through the target and settles as its damping allows.
+   * - `'stop'` (0) ends the motion at the first crossing, 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.
+   *   values rebound. `-0.75` reverses at three quarters speed on every
+   *   return. Values between 0 and 1 pass through slower.
    *
-   * 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
+   * A motion that never crosses ignores `arrival`. With `dampingRatio` 1
+   * or above (`bounce` 0 or below), a spring retargeted from rest closes
+   * in from one side. It crosses only when it starts with enough velocity
+   * toward the target, or when the target moves past it.
+   *
+   * Crossings are solved exactly, never sampled per frame, so `'stop'`
+   * lands exactly on the target at any frame timing. See
    * https://github.com/tkofh/coily/blob/main/PRECISION.md.
    *
    * @default 'passthrough'
@@ -53,10 +56,7 @@ interface WithMass {
   readonly mass?: number | undefined;
 }
 interface WithoutMass {
-  /**
-   * Mass is derived from the other parameters in this input shape
-   * and cannot be provided.
-   */
+  /** Derived from the other parameters in this input shape. Cannot be provided. */
   readonly mass?: undefined;
 }
 interface WithTension {
@@ -68,47 +68,48 @@ interface WithTension {
 }
 interface WithDamping {
   /**
-   * Friction strength. Higher damping bleeds off velocity faster and
-   * reduces bounce; at 0 the spring oscillates forever. Must be greater
+   * Friction strength. Higher damping removes 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.
+   * Damping as a fraction of critical damping, the friction at which
+   * bounce disappears. It sets the motion's character independent of its
+   * speed. Below 1 the spring bounces, and at 0 it never settles. At 1 it
+   * settles fastest without overshooting. Above 1 it settles slower, still
+   * without overshooting. 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.
+   * fastest without overshooting. Positive values bounce. Negative values
+   * settle slower without bouncing. At 1 the ratio clamps just short of
+   * undamped, so the spring still settles. Must be between -1 and 1, and
+   * below 1 in a config that sets `damping` without `duration`.
    */
   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.
+   * Settle time in ms. Starting `displacement` away from the target, the
+   * spring rests within a frame of it at any `precision`. A bouncy config
+   * can rest earlier, by up to about one oscillation (several short ones
+   * when `bounce` is near 1). 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.
+   * The starting distance from the target that the `duration` tuning
+   * assumes. Set it to your animation's range (300 when animating 0 to
+   * 300). Timing drifts as the real distance departs from it. The sign is
+   * ignored. The magnitude must exceed the resting threshold,
+   * `0.5 * 10^-precision`.
    * @default 1
    */
   readonly displacement?: number | undefined;
@@ -129,23 +130,21 @@ interface DampingBounceDurationOptions extends BaseOptions, WithoutMass, WithDam
 /** 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.
+ * Marks every option key foreign to `T` as absent or undefined, so mixing
+ * keys from different input shapes fails to type-check.
  */
 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.
+ * combinations, with no keys mixed in from another.
  */
 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`.
+ * Resolved spring parameters, frozen and safe to share between springs.
+ * Whatever `defineSpring` input shape produced it, a config has concrete
+ * `mass`, `tension`, `damping`, `precision`, and `arrival`, plus the
+ * quantities derived from them. To change a spring's behavior, assign a
+ * new config to `spring.config`.
  */
 declare class SpringDefinition {
   /** The config for springs created without one: critically damped, settling in about 500ms. */
@@ -156,13 +155,13 @@ declare class SpringDefinition {
   readonly tension: number;
   /** Friction strength, as provided or derived. */
   readonly damping: number;
-  /** Decimal places of the resting threshold — see `restingMagnitude`. */
+  /** 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.
+   * Velocity multiplier applied each time the value crosses the target.
+   * `'passthrough'` resolves to 1, which leaves the motion untouched.
+   * `'stop'` resolves to 0, which ends it at the target. Negative values
+   * rebound.
    */
   readonly arrival: number;
   /** Oscillation rate with no damping: `sqrt(tension / mass)`, in radians per second. */
@@ -170,39 +169,33 @@ declare class SpringDefinition {
   /** 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.
+   * `damping / criticalDamping`. Below 1 the spring 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. */
+  /** Resting threshold in value units, `0.5 * 10^-precision`. */
   readonly restingMagnitude: number;
   constructor(input: SpringDefinitionOptions);
   /**
-   * Computes when a spring with this config comes to rest from `state`,
-   * in ms.
+   * Computes the time in ms until a spring with this config rests from
+   * `state`, solved exactly from the motion's decay bound. The spring
+   * rests at the first tick at or after it.
    *
-   * 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.
+   * An underdamped spring can also rest earlier, on a frame that samples
+   * a dip in its pulsing rest amplitude, so read the result as "no later
+   * than". The motion an early rest cuts off never leaves the resting
+   * threshold. 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.
+   * Returns Infinity when the motion never settles: a `dampingRatio` of 0
+   * whose `arrival` neither stops nor slows it. With `arrival` 0, the
+   * result is capped at the first target crossing, where the 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.
- */
+/** Creates a config with stiffness (`tension`) and friction (`damping`) set directly. */
 declare function defineSpring(input: Exact<DirectOptions>): SpringDefinition;
 /**
  * Creates a config from stiffness and motion character. Damping is
@@ -217,95 +210,85 @@ declare function defineSpring(input: Exact<TensionRatioOptions>): SpringDefiniti
 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`
+ * 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.
+ * Creates a config from friction and bounciness, deriving tension.
+ * `bounce` must be less than 1, since the derived tension grows without
+ * limit as it nears 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.
+ * Creates a config from all three physical parameters. 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.
+ * Creates a config from tension, damping, and bounce. Mass is derived and
+ * cannot be provided. `bounce` must be less than 1, since the derived
+ * mass grows without limit as it nears 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.
+ * Tunes the spring to rest at `duration` ms, deriving tension and
+ * damping. `dampingRatio` sets the motion's character and must be
+ * greater than 0.
  *
  * The timing assumes the motion starts `displacement` (default 1) away
- * from the target — pass a `displacement` matching your animation range
- * for accurate timing.
+ * from the target. Pass your animation's range for accurate timing.
  *
  * @example
  * ```ts
- * // Tuned for a 300px move; rests within 750ms
+ * // 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.
+ * Tunes the spring to rest at `duration` ms, deriving tension and
+ * damping. `bounce` sets how oscillatory the settling motion is.
  *
  * The timing assumes the motion starts `displacement` (default 1) away
- * from the target — pass a `displacement` matching your animation range
- * for accurate timing.
+ * from the target. Pass your animation's 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.
+ * Tunes a spring of the given stiffness to rest at `duration` ms. Mass is
+ * derived to meet the timing, then damping from mass and `dampingRatio`.
+ * Mass cannot be provided, and `dampingRatio` must be greater than 0.
  *
  * The timing assumes the motion starts `displacement` (default 1) away
- * from the target — pass a `displacement` matching your animation range
- * for accurate timing.
+ * from the target. Pass your animation's 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.
+ * Tunes a spring of the given stiffness to rest at `duration` ms, with
+ * `bounce` setting how oscillatory the settling motion is. Mass is
+ * derived to meet the timing 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.
+ * from the target. Pass your animation's 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.
+ * Tunes a spring of the given friction to rest at `duration` ms. Mass is
+ * derived to meet the timing, then tension from mass. Mass cannot be
+ * provided, and `dampingRatio` must be greater than 0.
  *
  * The timing assumes the motion starts `displacement` (default 1) away
- * from the target — pass a `displacement` matching your animation range
- * for accurate timing.
+ * from the target. Pass your animation's 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.
+ * Tunes a spring of the given friction to rest at `duration` ms, with
+ * `bounce` setting how oscillatory the settling motion is. Mass is
+ * derived to meet the timing 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.
+ * from the target. Pass your animation's range for accurate timing.
  */
 declare function defineSpring(input: Exact<DampingBounceDurationOptions>): SpringDefinition;
 //#endregion

package/dist/css.d.ts

@@ -1,23 +1,27 @@
-import { r as SpringState, t as SpringDefinition } from "./config-OOMMRdK8.js";
+import { r as SpringState, t as SpringDefinition } from "./config-B8M2xp26.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.
+   * The size of the move the easing is timed for, in value units. A larger
+   * move takes longer to come within the fixed rest threshold, so it gets a
+   * longer duration, different `linear()` stop percentages, and possibly a
+   * different stop count. The keyframe helpers (`springToWaapi`,
+   * `springToCss`, `springToTransition`) default it to the largest move
+   * among their specs.
    * @default 1
    */
   readonly displacement?: number;
   /**
-   * Max output error of the piecewise-linear approximation, in progress
-   * units (0..1). Smaller keeps more stops.
+   * The largest output error allowed in the piecewise-linear
+   * approximation, in progress units (0 at the start, 1 at the target). A
+   * smaller value keeps more stops.
    * @default 0.0025
    */
   readonly maxError?: number;
   /**
-   * Hard cap on generated duration, in ms, for near-undamped configs.
+   * The longest duration to generate, in ms. It cuts off configs with so
+   * little damping (friction) that they take very long to settle. A
+   * `'loop'` easing ignores the cap and lasts one half period.
    * @default 10000
    */
   readonly maxDuration?: number;
@@ -29,7 +33,7 @@ interface EasingBase {
   readonly duration: number;
   /** Number of stops in the easing (diagnostic). */
   readonly stops: number;
-  /** Worst reconstruction error vs the dense trajectory (diagnostic). */
+  /** The largest error of `easing` against the dense samples (diagnostic). */
   readonly maxError: number;
 }
 /** The easing of a spring that comes to rest: play it once over `duration`. */
@@ -37,11 +41,11 @@ 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.
+ * The easing of a spring that never rests: an undamped oscillation (no
+ * friction), expressed as an infinite loop. Animate the property between
+ * its two swing extremes, `from` and `2 * target - from`, with the target
+ * at the 50% midpoint. Use `animation-iteration-count: infinite` and
+ * `animation-direction: alternate`. `duration` is one half period, in ms.
  */
 interface LoopingEasing extends EasingBase {
   readonly mode: 'loop';
@@ -50,57 +54,62 @@ interface LoopingEasing extends EasingBase {
 }
 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.
+ * Turns a spring config into a CSS `linear()` easing and the duration in
+ * ms to pair it with. A settling config returns a `'settle'` easing. A
+ * pure undamped config (`dampingRatio: 0` with passthrough `arrival`)
+ * never settles and returns a `'loop'` easing for an infinite alternating
+ * animation. Any other config that never settles, such as
+ * `dampingRatio: 0` with `arrival: -1`, returns a `'settle'` easing cut
+ * off at `maxDuration`.
  */
 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.
+ * Like `springToLinear`, but for a spring caught mid-flight. `state`
+ * carries the displacement from the target (`position`) and the current
+ * `velocity`, so the easing continues the motion instead of restarting it.
+ * Use it to regenerate an animation when its target changes. The curve
+ * depends on the velocity, so compute it per interruption instead of
+ * caching it per config.
  *
- * Always a settling easing; `position` must be nonzero.
+ * The result is always a `'settle'` easing, timed from `position`, so
+ * `options.displacement` is ignored. A config that never settles is cut
+ * off at `maxDuration`. Throws when `position` is 0 (within 1e-9), even if
+ * `velocity` is not.
  */
 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.
+ * Advances a spring `state` by `elapsedMs` ms and returns the new
+ * displacement and velocity. `elapsedMs <= 0` returns a copy of `state`.
+ *
+ * The Web Animations API doesn't expose velocity, so to interrupt a running
+ * `element.animate`, advance the state it started from by its `currentTime`
+ * and hand the result to `springFromState`.
  */
 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'`. */
+  /** The CSS property, for example `'opacity'`, `'transform'`, or `'translate'`. */
   readonly property: string;
-  /** Start value. */
+  /** The start value. */
   readonly from: number;
-  /** Target value the spring is tuned toward. */
+  /** The target value. */
   readonly to: number;
   /**
-   * Unit appended to numbers, e.g. `'px'`, `'%'`, `'deg'`.
+   * Unit appended to numbers, for example `'px'`, `'%'`, or `'deg'`.
    * @default ''
    */
   readonly unit?: string;
   /**
    * Formats an interpolated number into a property value, overriding
-   * `unit` — needed for wrapped values like `(v) => `translateX(${v}px)``.
+   * `unit`. Use it for values that wrap the number, such as
+   * ``(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.
+   * regenerate an interrupted animation with its momentum instead of from
+   * rest. A spec with a nonzero velocity must be the only spec in the call,
+   * or the call throws.
    */
   readonly velocity?: number;
 }
@@ -115,7 +124,7 @@ interface CssOptions extends LinearEasingOptions {
  * 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
+ * from one spring. A settling spring fills forwards. An undamped one repeats
  * infinitely in alternating directions.
  *
  * @example
@@ -134,10 +143,11 @@ declare function springToWaapi(config: SpringDefinition, spec: PropertySpec | Pr
   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.
+ * Builds CSS text for the animation: a `@keyframes` rule named by `name`
+ * (default `'coily'`) and an `animation` shorthand value that references
+ * it, driving one property or several from one spring. A settling spring
+ * fills forwards. An undamped one repeats infinitely in alternating
+ * directions.
  *
  * @example
  * ```ts
@@ -158,17 +168,35 @@ declare function springToCss(config: SpringDefinition, spec: PropertySpec | Prop
   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.
+ * Builds a CSS `transition` value that animates a property change with the
+ * spring. Set it on the element, then change the property, for example on
+ * `:hover`, with a toggled class, or with a state attribute. Pass several
+ * specs to build one `transition` for several properties.
+ *
+ * The values come from your CSS rules. Each spec's `from` and `to` only
+ * size the move, which tunes the duration. An undamped (looping) config
+ * throws, because a transition cannot loop.
+ *
+ * A transition starts from rest unless its spec carries a `velocity`, in
+ * the property's units per second, such as a drag's speed at release. The
+ * velocity reshapes the curve and the duration, so build the transition at
+ * the handoff. A spec with a velocity must be the only spec in the call.
+ *
+ * ```ts
+ * // Release a dragged card back to 0 at the drag's speed.
+ * card.style.transition = springToTransition(config, {
+ *   property: 'translate',
+ *   from: dragX,
+ *   to: 0,
+ *   velocity: releaseVelocity,
+ * })
+ * card.style.translate = '0px'
+ * ```
  *
- * 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.
+ * The browser carries no momentum between transitions, so a change that
+ * interrupts one mid-flight stalls at the turn. To keep the momentum, read
+ * the velocity with `springStateAt` and rebuild the transition with it.
+ * For motion that reverses often, drive a live `Spring` instead.
  */
 declare function springToTransition(config: SpringDefinition, spec: PropertySpec | PropertySpec[], options?: LinearEasingOptions): string;
 //#endregion