coily 0.13.1 → 0.15.0

package/dist/system-Du_fXXmO.d.ts

@@ -0,0 +1,940 @@
+import { t as SpringDefinition } from "./config-OOMMRdK8.js";
+//#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;
+  /** Monotone creation id: breaks ties wherever motions need a deterministic order. */
+  readonly _id: number;
+  /** Tick-pass marker written by `MotionSet` so a motion re-added mid-pass isn't ticked twice. */
+  _pass: number;
+  /**
+   * Frame marker written by `MotionSet`: sub-steps share one frame, and
+   * the first advance in it queues the motion for the settle sweep.
+   */
+  _frame: number;
+  /**
+   * Dependency rank written by `FollowGraph`: motions the follow graph
+   * touches count up from 0, leaders before followers; -1 marks a motion
+   * outside the graph.
+   */
+  _rank: number;
+  /**
+   * The edge this motion follows through, or null. Written by
+   * `FollowGraph` on edge add/remove so the tick's hot loop reads a
+   * field instead of a map.
+   */
+  _edge: FollowEdge | null;
+  /**
+   * A first-order-hold ramp slope in value units per second, armed by a
+   * ramped `recouple` immediately before the `_advance` that consumes
+   * it (read-and-clear; no user code runs between the two). 0 means the
+   * target holds still across the step — every path but a ramped
+   * recouple.
+   */
+  _ramp: number;
+  /**
+   * The edges reading this motion, or null when none. Written by
+   * `FollowGraph` with the rank cache, so it can lag a mid-pass edge
+   * change until the next recompute; the tick tolerates stale entries.
+   */
+  _followers: FollowEdge[] | null;
+  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;
+  /**
+   * Advances the simulation and emits nothing. The tick pass advances
+   * every motion through this, then delivers the frame's events with
+   * `_settleFrame`; the synchronous `tick` wraps the two.
+   *
+   * A pending `_ramp` integrates the step against a target moving at
+   * that slope instead of holding still: one affine transform around
+   * the unchanged solver. With the target at `p(t) = p0 + g*t`, the
+   * displacement u = x - p(t) obeys the homogeneous equation shifted by
+   * the constant u_ss = -(2*zeta/wn)*g = -(damping/tension)*g, so the
+   * solver ticks w = u - u_ss exactly and the results shift back.
+   * Measuring u from the moving target makes the ramp endpoint and the
+   * new target coincide — the armer assigns the target, no rebase
+   * arithmetic exists. The ramp is an argument of the step, never
+   * persistent solver state: g = 0 takes the plain step below, so a
+   * motion that never ramps steps bit-exactly like an isolated spring.
+   */
+  _advance(dt: number): void;
+  /**
+   * Emits the frame's `update`, then reconciles `stop`/`start`. The tick
+   * pass calls this in dependency order after every motion has advanced,
+   * so update callbacks read frame-final values everywhere.
+   */
+  _settleFrame(): void;
+  finish(): void;
+  /**
+   * The sub-step controller's shock signal, read by a follower's `plan`
+   * with this motion as its leader: deviation from the quasi-steady
+   * tracking manifold x = -(damping/tension) * v, where damping/tension
+   * is 2*zeta/wn. Near zero while chasing any smoothly moving target at
+   * any speed; the full displacement after a target teleport;
+   * (damping/tension) * |v| after a fling.
+   */
+  _manifoldDeviation(): number;
+  /** Acceleration from current state, for `plan`'s kinematic bound on a shock frame. */
+  _acceleration(): number;
+  onUpdate(callback: () => void): () => void;
+  onStart(callback: () => void): () => void;
+  onStop(callback: () => void): () => void;
+  onDispose(callback: () => void): () => void;
+  dispose(): void;
+}
+//#endregion
+//#region src/follow-graph.d.ts
+/**
+ * One follow relationship, as the system sees it: which motion
+ * retargets, which motions it reads, how to re-anchor it, and the
+ * sub-step controller's per-edge state. `Spring` registers an edge when
+ * a follow is wired to a source with resolvable motions, and
+ * unregisters it on unfollow and dispose.
+ */
+interface FollowEdge {
+  /** The motion that retargets when its leaders advance. */
+  readonly follower: Motion;
+  /** The distinct motions behind the followed source, per `resolveLeaderMotions`. */
+  readonly leaders: readonly Motion[];
+  /**
+   * Whether the follower shares a Tarjan SCC with any of its leaders,
+   * self-follow included. Written by `FollowGraph` on recompute. Routes
+   * `plan` to the ZOH sub-step law: FOH destabilizes cycles that are
+   * stable under ZOH, so no ramp may ever arm inside an SCC.
+   */
+  _cyclic: boolean;
+  /** The follower's target as of the last `plan` call. */
+  _prevValue: number;
+  /** The followed value's frame delta observed by the last `plan` call. */
+  _d1: number;
+  /** The frame delta one older than `_d1`; their difference estimates curvature. */
+  _d2: number;
+  /**
+   * Re-anchors the follower to the followed source's current value.
+   * `h` is the step the follower is about to advance by, in seconds
+   * (the internal tick unit). On an edge where a ramp may arm —
+   * acyclic, passthrough arrival, `h > 0`, not a reduced-motion jump —
+   * it retargets and arms the follower's `_ramp` with the delta over
+   * `h`, so the coming advance integrates against the leader's motion.
+   * Every other edge retargets with the exact semantics of the
+   * leader-update handler (finite guard, reduced-motion jump).
+   */
+  recouple(h: number): void;
+  /**
+   * Refreshes the estimator from the follower's current target and
+   * returns this edge's sub-step demand for a frame of `dt` seconds —
+   * unclamped; the caller maxes over edges and clamps. Runs no user
+   * code: history is the target trail, freshness reads leader motion
+   * state. Call at most once per edge per frame, before any motion
+   * advances.
+   */
+  plan(dt: number): number;
+}
+/**
+ * The follow graph as a walkable structure: one edge per following
+ * motion, and a cached dependency rank over every motion the edges
+ * touch. `MotionSet` owns one; springs register and unregister edges as
+ * follows are wired and torn down. What the tick reads per motion —
+ * `_edge`, `_followers`, `_rank` — lives on the motions themselves;
+ * this class is their writer.
+ */
+declare class FollowGraph {
+  #private;
+  /** Whether no edges are registered, letting the tick skip ordering work entirely. */
+  get isEmpty(): boolean;
+  /** Every registered edge, valid after `ensureOrder`; the plan pass walks this once per frame. */
+  get edges(): readonly FollowEdge[];
+  /**
+   * Registers `edge`, replacing any edge with the same follower: a
+   * spring follows at most one source at a time.
+   */
+  addEdge(edge: FollowEdge): void;
+  /** Drops the edge whose follower is `motion`, if one is registered. */
+  removeEdge(follower: Motion): void;
+  /**
+   * Recomputes ranks if an edge was added or removed since the last
+   * call; clean calls return immediately. Afterward, motions the graph
+   * touches hold ranks counting up from 0 with every leader ranked
+   * before its followers, members of a cycle rank in ascending creation
+   * id, and motions outside the graph hold -1. Ranks are canonical: a
+   * function of graph structure and creation order, never of wiring
+   * order.
+   */
+  ensureOrder(): 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;
+  /**
+   * The coupling error budget, in value units: the local per-frame error
+   * the sub-step controller targets on each follow edge, floored by the
+   * follower's resting magnitude. `SpringSystem` exposes it as the
+   * `couplingTolerance` option and property; validation lives there.
+   */
+  couplingTolerance: number;
+  readonly flushes: FlushQueue;
+  /** Follow edges registered by following springs, with the dependency rank over their motions. */
+  readonly graph: FollowGraph;
+  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;
+  /** The config's arrival multiplier. */
+  get arrival(): number;
+  set config(value: SpringDefinition | null);
+  /**
+   * Milliseconds until the spring rests: 0 while resting, Infinity when
+   * the motion never settles. The time is solved from the motion, not
+   * estimated — the spring is resting at the first tick at or after it,
+   * and a bouncy spring can rest up to one oscillation earlier when a
+   * frame samples a low pulse. When the config's `arrival` is 0, it is
+   * capped at the exact ms of the first target crossing.
+   */
+  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 {
+  /**
+   * How far a spring may trail a source it follows within one frame, in
+   * the value's own units. A frame whose motion would exceed it is split
+   * into internal sub-steps (at most 8), so followed chains stay
+   * accurate through slow frames and sudden retargets. Smaller is
+   * tighter and costs more solver work; it never goes finer than the
+   * follower's resting precision, and listeners still fire once per
+   * frame. Springs that follow nothing are unaffected.
+   * @default 0.1
+   */
+  couplingTolerance?: number | undefined;
+  /**
+   * 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;
+  /**
+   * How far a spring may trail a source it follows within one frame, in
+   * the value's own units — see the `couplingTolerance` option.
+   * Assignment accepts any finite number >= 0 and applies from the next
+   * frame; 0 means as fine as the follower's resting precision allows.
+   */
+  couplingTolerance: number;
+  /**
+   * 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 { 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, mapSpring as x, SpringSource as y };