coily 0.12.2 → 0.14.0

package/dist/system-Ci-R4RaI.d.ts

@@ -0,0 +1,1032 @@
+//#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;
+}
+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 {
+  /**
+   * Target settle time in milliseconds. The spring is tuned so its motion
+   * decays into the resting threshold within this time, assuming it
+   * starts `displacement` away from the target. Actual rest lands at or
+   * before the requested duration. 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';
+/**
+ * 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;
+  /** 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);
+  /**
+   * Estimates how long a spring with this config takes to come to rest
+   * from `state`, in milliseconds.
+   *
+   * The estimate follows the motion's decay envelope with a 2x safety
+   * margin, so actual rest usually lands earlier. Returns 0 when `state`
+   * is already inside the resting threshold, and Infinity when the config
+   * never settles (a `dampingRatio` of 0).
+   */
+  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 settle within `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 settle within `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 settle within `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 settle within `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 settle within `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 settle within `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
+//#region src/flush-queue.d.ts
+/**
+ * Defers callbacks while inside a batch or tick: `request` runs the
+ * callback immediately at depth 0 and queues it — deduplicated — until
+ * the outermost exit otherwise. Composite springs use it to coalesce
+ * per-channel events into composite ones.
+ */
+declare class FlushQueue {
+  #private;
+  request(callback: () => void): void;
+  batch(fn: () => void): void;
+  enter(): void;
+  exit(): void;
+}
+//#endregion
+//#region src/motion.d.ts
+/**
+ * One spring simulation in displacement space: position is measured from
+ * the target (0 means settled), so retargeting is a rebase performed by
+ * the owning `Spring`. Picks the closed-form solver for the config's
+ * damping regime and emits update/start/stop/dispose events.
+ */
+declare class Motion {
+  #private;
+  /** Tick-pass marker written by `MotionSet` so a motion re-added mid-pass isn't ticked twice. */
+  _pass: number;
+  respectsReducedMotion: boolean;
+  constructor(config: SpringDefinition, position: number, velocity: number);
+  get position(): number;
+  set position(value: number);
+  get velocity(): number;
+  set velocity(value: number);
+  get timeRemaining(): number;
+  get isResting(): boolean;
+  configure(config: SpringDefinition): void;
+  tick(dt: number, emit?: boolean): void;
+  finish(): void;
+  onUpdate(callback: () => void): () => void;
+  onStart(callback: () => void): () => void;
+  onStop(callback: () => void): () => void;
+  onDispose(callback: () => void): () => void;
+  dispose(): void;
+}
+//#endregion
+//#region src/motion-set.d.ts
+/**
+ * The set of motions currently moving. Motions leave the set as they
+ * rest and re-enter on any write that disturbs them; `onWake` tells the
+ * ticker the set became non-empty so it can stop sleeping.
+ */
+declare class MotionSet {
+  #private;
+  reduced: boolean;
+  onWake: (() => void) | null;
+  readonly flushes: FlushQueue;
+  constructor(debug?: boolean);
+  get size(): number;
+  add(motion: Motion): void;
+  remove(motion: Motion): void;
+  finishAll(): void;
+  tick(dt: number): void;
+}
+//#endregion
+//#region src/spring-source.d.ts
+/**
+ * The property key that brands a `SpringSource` and holds the channel its
+ * followers read. A registry symbol (`Symbol.for('coily/spring-source')`),
+ * so sources from one copy of coily are recognized by another when a
+ * bundle duplicates the library.
+ */
+declare const SpringSourceSymbol: unique symbol;
+/**
+ * What a source exposes to its followers, held under `SpringSourceSymbol`
+ * on the source object. Followers read `value` on every update and
+ * detach on dispose.
+ */
+interface SpringSourceApi<T = number> {
+  /** The current value, in value units. */
+  readonly value: T;
+  /** Subscribes to value changes. Returns an unsubscribe function. */
+  onUpdate(callback: () => void): () => void;
+  /** Subscribes to the source being released. Returns an unsubscribe function. */
+  onDispose(callback: () => void): () => void;
+}
+/**
+ * A live value a spring can animate toward or derive from. `T` is the
+ * value's type: a scalar source (`T = number`, the default) can be
+ * assigned to `Spring.target`, which then tracks it momentum intact.
+ *
+ * Every `Spring` is a `SpringSource`, every `CompositeSpring` is a
+ * `SpringSource` of its value shape, and `mapSpring`, `velocityOf`, and
+ * `accelerationOf` derive fresh sources from existing ones. You take
+ * sources from those APIs and pass them wherever one is accepted; the
+ * type names such a value in your own signatures.
+ */
+interface SpringSource<T = number> {
+  readonly [SpringSourceSymbol]: SpringSourceApi<T>;
+}
+/**
+ * Compile-time validation of a shape of sources: every leaf must be a
+ * `SpringSource`, every branch a plain object or array with at least one
+ * leaf. Used as `sources: T & SourceShape<T>` so an invalid leaf errors
+ * on that property rather than on the whole argument. Purely structural,
+ * and mirrored by the runtime validation for untyped callers. Optional
+ * and `undefined`-typed leaves are rejected.
+ */
+type SourceShape<T> = 0 extends 1 & T ? T : T extends SpringSource<unknown> ? SpringSource<unknown> : T extends ((...args: never) => unknown) | (abstract new (...args: never) => unknown) ? never : T extends readonly never[] ? never : T extends object ? keyof T extends never ? never : { [K in keyof T]-?: 0 extends 1 & T[K] ? T[K] : undefined extends T[K] ? never : SourceShape<T[K]>; } : never;
+/**
+ * The value shape a shape of sources produces: the same nesting with
+ * every `SpringSource` leaf replaced by its value — `number` for a
+ * scalar spring, the read-only value shape for a composite. What `map`
+ * receives when `mapSpring` is given a shape.
+ */
+type SourceValues<T> = T extends SpringSource<infer V> ? V : { readonly [K in keyof T]: SourceValues<T[K]>; };
+/**
+ * Derives a source from another by a pure function of its value:
+ * `mapSpring(leader, (v) => v + 10)` follows 10 above the leader,
+ * `(v) => -v` mirrors it. Maps compose — a mapped source is a
+ * `SpringSource` like any other, so it can be mapped again, used as a
+ * leaf of a shape map, or followed by several springs at once.
+ *
+ * The result is a stateless view, not a spring: it holds no
+ * subscriptions and needs no disposal, and reads compute `map` of the
+ * source's current value on the fly. `map` must be pure — it runs on
+ * every read and every source update, and nothing re-evaluates it when
+ * anything other than `source` changes. Composition is flat: mapping a
+ * mapped source extends its pipeline rather than wrapping it, so chains
+ * cost one function call per map however long they grow.
+ */
+declare function mapSpring(source: SpringSource, map: (value: number) => number): SpringSource;
+/**
+ * Derives a scalar source from several channels by a pure function of
+ * their values. `sources` is a shape — a plain object or array with
+ * `SpringSource` leaves, nested arbitrarily — or a single non-scalar
+ * source such as a `CompositeSpring`. `map` receives the matching
+ * values: each leaf's current number for a shape
+ * (`mapSpring({ x, y }, ({ x, y }) => Math.hypot(x, y))`), the
+ * live value shape for a composite
+ * (`mapSpring(point, ({ x, y }) => Math.hypot(x, y))`). Invalid
+ * leaves throw with their path (`position.z`).
+ *
+ * The result is a stateless view, not a spring: it holds no
+ * subscriptions and needs no disposal, and reads compute `map` over the
+ * sources' values on the fly. `map` must be pure — it runs on every
+ * read and every source update — and must not retain what it receives:
+ * every call hands it the same live mirror of the values, refreshed in
+ * place. The mapped source is released with the first of its sources:
+ * followers detach then, keeping their current target, as they would
+ * from a disposed spring.
+ */
+declare function mapSpring<const T extends object>(sources: T & SourceShape<T>, map: (values: SourceValues<T>) => number): SpringSource;
+//#endregion
+//#region src/kinematic-source.d.ts
+/**
+ * A `SpringSourceApi` whose value is in motion, so it also reports the
+ * value's derivatives: `velocity` (the rate `value` changes, in value
+ * units per second) and `acceleration` (the rate `velocity` changes, in
+ * value units per second squared). A `Spring` and a `CompositeSpring`
+ * carry both exactly — they fall out of the same equation that drives
+ * the motion — as does a source bridging a value whose motion it tracks.
+ * A value derived with `mapSpring` does not: it holds no motion of its
+ * own, so its derivatives would need the derivative of an arbitrary
+ * function. `velocityOf` and `accelerationOf` read this slot.
+ */
+interface KinematicSourceApi<T = number> extends SpringSourceApi<T> {
+  /** The current velocity, in value units per second. */
+  readonly velocity: T;
+  /** The current acceleration, in value units per second squared. */
+  readonly acceleration: T;
+}
+/**
+ * A `SpringSource` whose value is in motion, so it also carries the
+ * value's `velocity` and `acceleration` — every `Spring` and
+ * `CompositeSpring` is one. `velocityOf` and `accelerationOf` accept
+ * these; a plain `SpringSource` (such as a `mapSpring` result) is not
+ * assignable, since a value derivation is not in motion.
+ */
+interface KinematicSource<T = number> extends SpringSource<T> {
+  readonly [SpringSourceSymbol]: KinematicSourceApi<T>;
+}
+/**
+ * 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.
+ */
+declare function velocityOf<T>(source: KinematicSource<T>): SpringSource<T>;
+/**
+ * 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.
+ */
+declare function accelerationOf<T>(source: KinematicSource<T>): SpringSource<T>;
+//#endregion
+//#region src/spring.d.ts
+/**
+ * What a spring can animate toward: a fixed number, or a `SpringSource`
+ * — another spring, or a value derived from one with `mapSpring` —
+ * whose live value the spring follows.
+ */
+type SpringTarget = number | SpringSource;
+/**
+ * What a spring animates, which decides whether reduced motion applies to
+ * it. `'motion'` moves something on screen — position, scale, rotation —
+ * and snaps to its target under reduced motion. `'appearance'` changes
+ * how something looks without moving it — a cross-fade, a color, a blur —
+ * and keeps animating under reduced motion, since it carries no motion to
+ * reduce. Fixed when the spring is created; read it back from
+ * `Spring.purpose`.
+ */
+type Purpose = 'motion' | 'appearance';
+/**
+ * One animated number, driven toward its target with damped spring
+ * motion. Create springs with `SpringSystem.createSpring`; the owning
+ * system advances them, so a spring only moves while its system runs.
+ *
+ * Reads return the exact simulated state; nothing is rounded. Numeric
+ * writes — `target`, `value`, `velocity`, `jumpTo` — require finite
+ * numbers: `NaN` or an infinity throws rather than poisoning the
+ * simulation. See
+ * https://github.com/tkofh/coily/blob/main/PRECISION.md for the
+ * numerical contract.
+ */
+declare class Spring implements KinematicSource {
+  #private;
+  /** Brands the spring as a `KinematicSource` whose api is the spring itself. */
+  get [SpringSourceSymbol](): KinematicSourceApi<number>;
+  constructor(motions: MotionSet, value: number, config?: SpringDefinition, purpose?: Purpose);
+  /**
+   * The value the spring is animating toward. While following a source,
+   * reads return the source's value as of its last update.
+   *
+   * Assignment accepts any `SpringTarget`:
+   * - A number retargets the spring. The current value and momentum carry
+   *   over, so mid-flight retargets stay smooth. Assigning a number while
+   *   following also stops the following.
+   * - A `SpringSource` — a `Spring`, or a value derived with `mapSpring` —
+   *   makes this spring follow the source's live value.
+   *
+   * Under reduced motion, retargets apply instantly — unless `purpose` is
+   * `'appearance'`, in which case they animate as normal.
+   */
+  get target(): number;
+  set target(value: SpringTarget);
+  /**
+   * The current animated value: the target plus the remaining
+   * displacement.
+   *
+   * Writing displaces the spring: it keeps its target and springs back
+   * from the written value, notifying update listeners synchronously.
+   * Writing the current value is a no-op. Under reduced motion a write
+   * jumps the spring — target included — to the written value, unless
+   * `purpose` is `'appearance'`, in which case it displaces as normal.
+   */
+  get value(): number;
+  set value(value: number);
+  /**
+   * The current velocity, in value units per second.
+   *
+   * Writing flings the spring: motion continues from the current value
+   * with the written velocity, then settles back to the target. Under
+   * reduced motion writes are ignored, unless `purpose` is `'appearance'`,
+   * in which case the fling applies as normal.
+   */
+  get velocity(): number;
+  set velocity(value: number);
+  /**
+   * The current acceleration, in value units per second squared — how
+   * fast the velocity is changing. Read-only: acceleration is the
+   * spring's stiffness and friction acting on its current displacement
+   * and velocity, so it follows from the motion rather than being set.
+   * To fling the spring, write `velocity` instead.
+   */
+  get acceleration(): number;
+  /**
+   * What the spring animates — `'motion'` or `'appearance'` — fixed when
+   * it was created. An `'appearance'` spring opts out of reduced motion:
+   * it keeps animating where a `'motion'` spring snaps to its target. See
+   * `Purpose`.
+   */
+  get purpose(): Purpose;
+  /**
+   * The spring's `SpringDefinition`: the one it was created with or last
+   * assigned, otherwise `SpringDefinition.default`. Following a source
+   * never changes it — how a spring chases its target is the spring's
+   * own setting.
+   *
+   * Assigning a config reconfigures the spring in place — value and
+   * velocity are preserved, so mid-flight reconfigures stay smooth.
+   * Assigning `null` reverts to the default.
+   */
+  get config(): SpringDefinition;
+  /** The config's mass. */
+  get mass(): number;
+  /** The config's tension (stiffness). */
+  get tension(): number;
+  /** The config's damping (friction). */
+  get damping(): number;
+  /** The config's damping ratio. */
+  get dampingRatio(): number;
+  /** The config's resting precision. */
+  get precision(): number;
+  set config(value: SpringDefinition | null);
+  /**
+   * Estimated milliseconds until the spring rests: 0 while resting,
+   * Infinity when undamped. The estimate carries a safety margin, so
+   * actual rest usually lands earlier.
+   */
+  get timeRemaining(): number;
+  /**
+   * Whether the spring's remaining motion is inside its resting
+   * threshold. Resting springs cost nothing until the next write. See
+   * https://github.com/tkofh/coily/blob/main/PRECISION.md for the rest
+   * test.
+   */
+  get isResting(): boolean;
+  /**
+   * A promise that resolves when the spring next comes to rest — already
+   * resolved while resting or after dispose. Retargeting mid-flight
+   * extends the wait; disposing resolves it.
+   *
+   * @example
+   * ```ts
+   * spring.target = 300
+   * await spring.settled
+   * // the spring is at 300 and resting
+   * ```
+   */
+  get settled(): Promise<void>;
+  /**
+   * Snaps the spring to `value` with no animation: target and value both
+   * become `value` and velocity clears. Listeners are notified
+   * synchronously — `update`, plus `stop` if the spring was moving.
+   */
+  jumpTo(value: number): void;
+  /**
+   * Releases the spring permanently: stops following, detaches followers
+   * (each keeps its current target), resolves `settled`, and notifies
+   * dispose listeners. Calling it again is a no-op.
+   *
+   * A disposed spring keeps its final value readable; writes throw.
+   */
+  dispose(): void;
+  /**
+   * Subscribes to value changes: every tick the spring moves, plus
+   * synchronous `value` writes and `jumpTo` calls. Returns an unsubscribe
+   * function.
+   */
+  onUpdate(callback: () => void): () => void;
+  /**
+   * Subscribes to the spring leaving rest. `start` and `stop` always
+   * alternate; retargeting mid-flight fires neither. Returns an
+   * unsubscribe function.
+   */
+  onStart(callback: () => void): () => void;
+  /**
+   * Subscribes to the spring coming to rest, whether by settling or by
+   * `jumpTo`. Always alternates with `start`. Returns an unsubscribe
+   * function.
+   */
+  onStop(callback: () => void): () => void;
+  /** Subscribes to `dispose`, which fires once. Returns an unsubscribe function. */
+  onDispose(callback: () => void): () => void;
+}
+//#endregion
+//#region src/composite-spring.d.ts
+/**
+ * Compile-time validation of a value shape: every channel must be a `number`,
+ * every branch a plain object or array with at least one channel. Used as
+ * `value: T & Shape<T>` so an invalid channel errors on that property rather
+ * than on the whole argument. Purely structural — interfaces satisfy it
+ * without index signatures — and mirrored by the runtime
+ * validation for untyped callers. Optional and `undefined`-typed channels
+ * are rejected: a channel that may be absent would make two springs of the
+ * same declared shape structurally incompatible at runtime.
+ */
+type Shape<T> = 0 extends 1 & T ? T : T extends number ? number : T extends ((...args: never) => unknown) | (abstract new (...args: never) => unknown) ? never : T extends readonly never[] ? never : T extends object ? keyof T extends never ? never : { [K in keyof T]-?: 0 extends 1 & T[K] ? T[K] : undefined extends T[K] ? never : Shape<T[K]>; } : never;
+/**
+ * A partial view of a value shape: the same nesting with any subset of the
+ * numeric channels present. Absent (or `undefined`) channels are left alone.
+ */
+type PartialShape<T> = T extends number ? number : { readonly [K in keyof T]?: PartialShape<T[K]> | undefined; };
+/**
+ * A deep-readonly view of a value shape. Composite reads (`target`, `value`,
+ * `velocity`, `acceleration`) return the spring's live mirror objects —
+ * refreshed in place on every read — so their channels are typed read-only.
+ */
+type ReadonlyShape<T> = T extends number ? number : { readonly [K in keyof T]: ReadonlyShape<T[K]>; };
+/**
+ * Configuration for a composite spring: a single `SpringDefinition` applied to every
+ * channel, or an object mirroring the value shape with configs at any level.
+ * A config at a subtree applies to every channel below it.
+ * `null` reverts to the default config.
+ * Configs are always `SpringDefinition` instances (from `defineSpring`), so a
+ * plain object is unambiguously a config shape and any non-config leaf it
+ * reaches is an error.
+ */
+type ConfigShape<T> = SpringDefinition | null | (T extends number ? never : { readonly [K in keyof T]?: ConfigShape<T[K]> | undefined; });
+/**
+ * What each channel of a composite spring animates: a single `Purpose`
+ * for every channel, or a shape mirroring the value with purposes at any
+ * level. A purpose at a subtree covers every channel below it, and any
+ * channel it doesn't reach defaults to `'motion'`. Fixed when the spring
+ * is created. See `Purpose`.
+ */
+type PurposeShape<T> = Purpose | (T extends number ? never : { readonly [K in keyof T]?: PurposeShape<T[K]> | undefined; });
+/**
+ * A partial target shape: the same nesting as the value with any subset
+ * of the channels present, each taking a number to animate toward or a
+ * scalar `SpringSource` to follow. Absent (or `undefined`) channels are
+ * left alone.
+ */
+type TargetShape<T> = T extends number ? number | SpringSource : { readonly [K in keyof T]?: TargetShape<T[K]> | undefined; };
+/**
+ * What a composite spring can animate toward: a partial shape mixing
+ * numbers and scalar `SpringSource`s per channel, or another composite
+ * spring of the same shape to follow channel by channel.
+ */
+type CompositeSpringTarget<T extends object> = TargetShape<T> | CompositeSpring<T>;
+/**
+ * A composite spring over a fixed numeric shape — a nested plain object
+ * or array whose leaves are all numbers. Each leaf runs an independent
+ * spring, called a channel, behind one API: targets, values, velocities,
+ * and configs read and write as (partial) shapes, and events are
+ * coalesced across channels. Create composite springs with
+ * `SpringSystem.createSpring`.
+ *
+ * A composite spring is a `SpringSource` of its value shape: `mapSpring`
+ * derives scalar sources from it — alone or at the leaves of a shape —
+ * which springs can then follow. Only scalar sources are followable
+ * directly.
+ *
+ * The shape is fixed at construction. Writes naming unknown channels
+ * throw with the channel's path (`position.z`), and so do non-finite
+ * channel values.
+ */
+declare class CompositeSpring<in out T extends object> implements KinematicSource<ReadonlyShape<T>> {
+  #private;
+  /** Brands the composite as a `KinematicSource` whose api is the composite itself. */
+  get [SpringSourceSymbol](): KinematicSourceApi<ReadonlyShape<T>>;
+  constructor(motions: MotionSet, value: T & Shape<T>, config?: ConfigShape<T>, purpose?: PurposeShape<T>);
+  /**
+   * The value each channel is animating toward, as a read-only mirror of
+   * the shape. The mirror object is reused: every read refreshes its
+   * numbers in place, so read it fresh rather than holding it across
+   * frames.
+   *
+   * Assignment accepts a `CompositeSpringTarget`:
+   * - A partial shape retargets the channels it names and leaves the
+   *   others alone. Each named channel takes a number, or a scalar
+   *   `SpringSource` to follow — a `Spring`, or a value derived with
+   *   `mapSpring`. While following a leader, naming a channel also
+   *   detaches that channel from it.
+   * - A `CompositeSpring` of the same shape follows the leader channel by
+   *   channel.
+   *
+   * Unknown channels throw with their path.
+   */
+  get target(): ReadonlyShape<T>;
+  set target(value: CompositeSpringTarget<T>);
+  /**
+   * The current animated value of every channel, as a read-only mirror of
+   * the shape. The mirror object is reused: every read refreshes its
+   * numbers in place, so read it fresh rather than holding it across
+   * frames.
+   *
+   * Assignment takes a partial shape and displaces the channels it names:
+   * each keeps its target and springs back from the written value, with
+   * one coalesced `update` fired synchronously. Under reduced motion a
+   * write jumps the named channels — targets included — except channels
+   * whose `purpose` is `'appearance'`, which displace as normal.
+   */
+  get value(): ReadonlyShape<T>;
+  set value(value: PartialShape<T>);
+  /**
+   * The current velocity of every channel in value units per second, as a
+   * read-only mirror of the shape — reused and refreshed in place on each
+   * read.
+   *
+   * Assignment takes a partial shape and flings the channels it names;
+   * the rest are untouched. Under reduced motion writes are ignored,
+   * except on channels whose `purpose` is `'appearance'`.
+   */
+  get velocity(): ReadonlyShape<T>;
+  set velocity(value: PartialShape<T>);
+  /**
+   * The current acceleration of every channel in value units per second
+   * squared, as a read-only mirror of the shape — reused and refreshed in
+   * place on each read. Read-only, like each channel's: acceleration
+   * follows from the motion. To fling channels, write `velocity`.
+   */
+  get acceleration(): ReadonlyShape<T>;
+  /**
+   * The shared config when every channel resolves to the same
+   * `SpringDefinition`, and `null` when they differ.
+   *
+   * Assignment accepts a `ConfigShape`: one config for every channel,
+   * `null` to revert every channel to the default, or a shape mirroring
+   * the value with configs at any level — a config at a subtree covers
+   * every channel below it. Non-config leaves throw with their path.
+   */
+  get config(): SpringDefinition | null;
+  set config(value: ConfigShape<T>);
+  /**
+   * The shared purpose when every channel resolves to the same `Purpose`,
+   * and `null` when they differ. Fixed when the spring is created — an
+   * `'appearance'` channel opts out of reduced motion. See `Purpose`.
+   */
+  get purpose(): Purpose | null;
+  /** The largest `timeRemaining` across channels, in milliseconds. */
+  get timeRemaining(): number;
+  /** Whether every channel is resting. */
+  get isResting(): boolean;
+  /**
+   * A promise that resolves when every channel next rests — already
+   * resolved while resting or after dispose. Retargeting any channel
+   * mid-flight extends the wait; disposing resolves it.
+   */
+  get settled(): Promise<void>;
+  /**
+   * Snaps the channels the partial shape names to the given values with
+   * no animation, notifying listeners synchronously. Channels it leaves
+   * out are untouched.
+   */
+  jumpTo(value: PartialShape<T>): void;
+  /**
+   * Releases every channel permanently: resolves `settled` and notifies
+   * dispose listeners. Calling it again is a no-op.
+   *
+   * A disposed composite spring keeps its final values readable; writes
+   * throw.
+   */
+  dispose(): void;
+  /**
+   * Subscribes to coalesced value changes: at most one `update` per tick,
+   * fired after every channel has advanced, plus one per synchronous
+   * write. Returns an unsubscribe function.
+   */
+  onUpdate(callback: () => void): () => void;
+  /**
+   * Subscribes to the composite leaving rest: a channel starts moving
+   * while all were resting. Always alternates with `stop`. Returns an
+   * unsubscribe function.
+   */
+  onStart(callback: () => void): () => void;
+  /**
+   * Subscribes to the composite coming to rest: every channel resting,
+   * fired after that tick's final `update`. Always alternates with
+   * `start`. Returns an unsubscribe function.
+   */
+  onStop(callback: () => void): () => void;
+  /** Subscribes to `dispose`, which fires once. Returns an unsubscribe function. */
+  onDispose(callback: () => void): () => void;
+}
+//#endregion
+//#region src/ticker.d.ts
+/** Frame timing options for a spring system. */
+interface TickerOptions {
+  /**
+   * Frame-rate cap. 0 means uncapped: one tick per displayed frame,
+   * whatever rate the screen runs at — 60Hz, 120Hz, or adaptive. Capped
+   * ticks are paced to whole display frames, near the requested rate, and
+   * each still receives the true elapsed time.
+   * @default 0
+   */
+  readonly fps?: number | undefined;
+  /**
+   * Frame gap in milliseconds above which the gap is treated as lag — a
+   * backgrounded tab, a blocking task — and replaced with `adjustedLag`,
+   * so springs don't teleport when frames resume. 0 disables lag
+   * clamping.
+   * @default 500
+   */
+  readonly lagThreshold?: number | undefined;
+  /**
+   * The elapsed milliseconds a lagging frame is replaced with. Clamped to
+   * at most `lagThreshold`.
+   * @default 33
+   */
+  readonly adjustedLag?: number | undefined;
+}
+//#endregion
+//#region src/system.d.ts
+/**
+ * Per-spring options for `SpringSystem.createSpring`, separate from the
+ * physical `config`.
+ */
+interface SpringOptions {
+  /**
+   * What the spring animates, which decides whether reduced motion applies
+   * to it. `'appearance'` — a cross-fade, a color, a blur — keeps
+   * animating under reduced motion; `'motion'` snaps to the target. Fixed
+   * for the spring's life. See `Purpose`.
+   * @default 'motion'
+   */
+  purpose?: Purpose | undefined;
+}
+/**
+ * Per-spring options for a composite `SpringSystem.createSpring`, separate
+ * from the physical `config`.
+ */
+interface CompositeSpringOptions<T extends object> {
+  /**
+   * What each channel animates, deciding reduced-motion behavior per
+   * channel: a single `Purpose` for every channel, or a shape mirroring
+   * the value with purposes at any level — a purpose at a subtree covers
+   * every channel below it. Channels it doesn't reach default to
+   * `'motion'`. Fixed for the spring's life. See `PurposeShape`.
+   * @default 'motion'
+   */
+  purpose?: PurposeShape<T> | undefined;
+}
+interface SpringSystemOptions extends TickerOptions {
+  /**
+   * Log active motion counts to the console whenever they change.
+   * @default false
+   */
+  debug?: boolean | undefined;
+  /**
+   * When springs snap to their targets instead of animating. `'user'`
+   * follows the OS prefers-reduced-motion setting, including live changes
+   * — switching it on finishes in-flight motion instantly. `'always'` and
+   * `'never'` force one behavior.
+   * @default 'user'
+   */
+  reducedMotion?: 'user' | 'always' | 'never' | undefined;
+}
+/**
+ * Owns springs and advances them over time. Create one with
+ * `createSpringSystem`, then either `start()` it to animate on real
+ * frames or call `advance` yourself for manual stepping.
+ */
+interface SpringSystem {
+  /**
+   * Creates a spring at rest at `value`. Without `config`, springs use
+   * the default: critically damped, settling in about 500ms. To follow
+   * another spring from birth, pass it in place of `value`.
+   *
+   * `options.purpose` marks what the spring animates: `'appearance'`
+   * keeps animating under reduced motion, `'motion'` (the default) snaps.
+   */
+  createSpring(value: number, config?: SpringDefinition, options?: SpringOptions): Spring;
+  /**
+   * Creates a spring already following `source` — a `Spring`, or a value
+   * derived with `mapSpring`. It starts at the source's current value,
+   * so nothing moves until the source does; equivalent to creating a
+   * spring at that value and assigning `source` to its `target`.
+   *
+   * `options.purpose` marks what the spring animates: `'appearance'`
+   * keeps animating under reduced motion, `'motion'` (the default) snaps.
+   */
+  createSpring(source: SpringSource, config?: SpringDefinition, options?: SpringOptions): Spring;
+  /**
+   * Creates a composite spring over a numeric shape: a plain object or
+   * array, nested arbitrarily, whose leaves are all numbers. Each leaf
+   * becomes an independently sprung channel.
+   *
+   * `config` applies per channel: a single `SpringDefinition` for every
+   * channel, or a shape mirroring the value with configs at any level.
+   * `options.purpose` marks reduced-motion behavior the same way, per
+   * channel — an `'appearance'` channel keeps animating.
+   */
+  createSpring<T extends object>(value: T & Shape<T>, config?: ConfigShape<T>, options?: CompositeSpringOptions<T>): CompositeSpring<T>;
+  /**
+   * Advances every moving spring by `dt` milliseconds. For manual
+   * stepping in place of `start()` — tests, custom loops, offline
+   * rendering.
+   */
+  advance(dt: number): void;
+  /**
+   * Begins animating on real frames: one tick per displayed frame, via
+   * `requestAnimationFrame` in the browser and a `setTimeout` fallback
+   * elsewhere. An idle system sleeps — no frames are scheduled while
+   * every spring rests.
+   */
+  start(): void;
+  /** Stops animating. Springs hold their state until `start` or `advance`. */
+  stop(): void;
+  /**
+   * Whether the system is between `start()` and `stop()`. Sleeping while
+   * idle still counts as running.
+   */
+  readonly running: boolean;
+  /**
+   * Whether springs currently snap instead of animating, per the
+   * `reducedMotion` option and, in `'user'` mode, the live OS setting.
+   * Read it to gate purely decorative effects of your own. Springs
+   * created with `purpose: 'appearance'` animate regardless.
+   */
+  readonly reducedMotion: boolean;
+  /**
+   * Frame-rate cap. 0 means uncapped: one tick per displayed frame,
+   * whatever rate the screen runs at. Capped ticks land on whole display
+   * frames and receive the true elapsed time.
+   */
+  fps: number;
+  /**
+   * Frame gap in milliseconds above which the gap is treated as lag — a
+   * backgrounded tab, a blocking task — and replaced with `adjustedLag`,
+   * so springs don't teleport when frames resume. 0 disables lag
+   * clamping.
+   */
+  lagThreshold: number;
+  /** The elapsed milliseconds a lagging frame is replaced with. Clamped to at most `lagThreshold`. */
+  adjustedLag: number;
+}
+/**
+ * Creates a spring system: the entry point of the library.
+ *
+ * @example
+ * ```ts
+ * const system = createSpringSystem()
+ * system.start()
+ *
+ * const spring = system.createSpring(0)
+ * spring.onUpdate(() => {
+ *   element.style.translate = `${spring.value}px 0`
+ * })
+ * spring.target = 300
+ * ```
+ */
+declare function createSpringSystem(options?: SpringSystemOptions): SpringSystem;
+//#endregion
+export { SpringDefinitionOptions as C, SpringDefinition as S, defineSpring as T, accelerationOf as _, createSpringSystem as a, SpringSourceSymbol as b, ConfigShape as c, ReadonlyShape as d, Shape as f, KinematicSource as g, SpringTarget as h, SpringSystemOptions as i, PartialShape as l, Spring as m, SpringOptions as n, CompositeSpring as o, Purpose as p, SpringSystem as r, CompositeSpringTarget as s, CompositeSpringOptions as t, PurposeShape as u, velocityOf as v, SpringState as w, mapSpring as x, SpringSource as y };