coily 0.15.0 → 0.16.0

package/dist/system-C7PbI4L0.d.ts

@@ -0,0 +1,1213 @@
+import { t as SpringDefinition } from "./config-B8M2xp26.js";
+//#region src/flush-queue.d.ts
+/**
+ * Defers callbacks while inside a batch or tick. At depth 0, `request`
+ * runs the callback immediately. Otherwise it queues the callback, once
+ * per callback, until the outermost exit. Composite springs use it to
+ * merge 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
+/**
+ * Something the system advances frame by frame: a spring's `SpringMotion`
+ * or a ramp's `RampMotion`. `MotionSet` ticks motions and `FollowGraph`
+ * orders them through the members declared here. Owners keep their motion
+ * in a private field, so none of this reaches the public api.
+ *
+ * A tick runs in two phases. Every moving motion first advances silently,
+ * so followers recouple against frame-current values. Then each motion
+ * that advanced delivers its events in `endFrame`.
+ */
+declare abstract class Motion {
+  /**
+   * Creation order across every kind of motion. The lower id goes first
+   * wherever motions need a deterministic order and nothing else decides.
+   */
+  readonly id: number;
+  /**
+   * The last ordered pass that advanced the motion, written by
+   * `MotionSet`, so a motion queued twice in one pass advances once.
+   */
+  pass: number;
+  /**
+   * The last ordered frame that advanced the motion, written by
+   * `MotionSet`. Sub-steps share one frame, and the first advance in it
+   * queues the motion for `endFrame`.
+   */
+  frame: number;
+  /**
+   * Dependency rank, written by `FollowGraph`. Motions in the follow
+   * graph count up from 0, leaders before followers. -1 marks a motion
+   * outside the graph.
+   */
+  rank: number;
+  /**
+   * The edge this motion follows through, or null. `FollowGraph` writes
+   * it. Only a spring follows.
+   */
+  edge: FollowEdge | null;
+  /**
+   * The edges that read this motion, or null when none do. `FollowGraph`
+   * rebuilds them with the ranks, so they can lag a mid-pass edge change
+   * until the next recompute. The tick tolerates stale entries.
+   */
+  followers: FollowEdge[] | null;
+  /** Whether the motion has stopped moving. `MotionSet` drops it once true. */
+  abstract get isResting(): boolean;
+  /** The current velocity, in value units per second. */
+  abstract get velocity(): number;
+  /** The current acceleration, in value units per second squared. */
+  abstract get acceleration(): number;
+  /** Advances by `h` seconds and emits nothing. Events wait for `endFrame`. */
+  abstract advance(h: number): void;
+  /** Delivers the frame's events, after every motion has advanced. */
+  abstract endFrame(): void;
+  /**
+   * Applies a change of the system's reduced-motion setting, which
+   * `MotionSet.reduced` already holds. A motion whose purpose is
+   * `'nonmotion'` ignores it.
+   */
+  abstract applyReducedMotion(reduced: boolean): void;
+  /**
+   * How far the motion sits from steady tracking. A follower's `plan`
+   * reads it from its leader as the sub-step controller's shock signal.
+   * A motion that nothing can knock off its course returns 0.
+   */
+  abstract manifoldDeviation(): number;
+  /**
+   * Whether the motion's slope changes at a known moment within the next
+   * `dt` seconds. Planning from history can't foresee that, so a
+   * follower's `plan` demands the sub-step cap on that frame.
+   */
+  abstract kinksWithin(dt: number): boolean;
+}
+//#endregion
+//#region src/follow-graph.d.ts
+/**
+ * The sub-step controller's history of one followed value: its last
+ * observed value, `delta`, and `curvature`.
+ */
+declare class TargetTrail {
+  #private;
+  constructor(value: number);
+  /** The change between the last two observed values. */
+  get delta(): number;
+  /** The latest `delta` minus the one before it. 0 while the value moves in a straight line. */
+  get curvature(): number;
+  /** Records this frame's value and returns the change since the last one. */
+  observe(value: number): number;
+  /** Restarts the trail at `value` without recording a change. */
+  anchor(value: number): void;
+}
+/**
+ * One follow relationship: the motion that retargets, the motions it
+ * reads, how to re-anchor it, and the sub-step controller's per-edge
+ * state. `Spring` registers one when it follows 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 leader, self-follow
+   * included. `FollowGraph` writes it on recompute. A cyclic edge stays on
+   * ZOH (zero-order hold) and never arms a slope, because FOH (first-order
+   * hold) destabilizes cycles that are stable under ZOH.
+   */
+  cyclic: boolean;
+  /** The follower's target as `plan` observes it once per frame. */
+  readonly trail: TargetTrail;
+  /**
+   * Re-anchors the follower to the followed source's current value before
+   * an advance of `h` seconds (the internal tick unit). A reduced-motion
+   * jump rests the follower on the new target and emits nothing. Its
+   * `endFrame` delivers the events in the settle sweep. An acyclic edge
+   * with passthrough arrival and `h > 0` retargets and arms the follower's
+   * slope at the delta over `h`, so the advance integrates against the
+   * leader's motion. Every other edge retargets exactly as the
+   * leader-update handler does (finite guard, rebase).
+   */
+  recouple(h: number): void;
+  /**
+   * Refreshes the estimator from the follower's current target and
+   * returns the edge's unclamped sub-step demand for a frame of `dt`
+   * seconds. The caller clamps the max over edges. Runs no user code:
+   * history comes from `trail`, freshness from leader motion state. Call
+   * it at most once per edge per frame, before any motion advances.
+   */
+  plan(dt: number): number;
+}
+/**
+ * The follow graph: one edge per following motion, and a cached
+ * dependency rank over every motion the edges touch. `MotionSet` owns
+ * one. This class writes `edge`, `followers`, and `rank` onto the
+ * motions, where the tick reads them.
+ */
+declare class FollowGraph {
+  #private;
+  /** Whether no edges are registered. The tick then skips all ordering work. */
+  get isEmpty(): boolean;
+  /** Every registered edge, current as of the last `ensureOrder`. */
+  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 `follower`, if one is registered. */
+  removeEdge(follower: Motion): void;
+  /**
+   * Recomputes ranks if an edge was added or removed since the last call.
+   * Afterward, motions the graph touches rank up from 0, every leader
+   * before its followers, and motions outside it hold -1. Cycle members
+   * rank in ascending creation id. Ranks depend on graph structure and
+   * creation order, never on wiring order.
+   */
+  ensureOrder(): void;
+}
+//#endregion
+//#region src/motion-set.d.ts
+/**
+ * The set of motions the tick advances. A motion leaves when it rests and
+ * re-enters on any write that disturbs it. A ramp is in the set only
+ * while something watches it frame by frame. `onWake` fires when the set
+ * becomes non-empty, waking a sleeping ticker.
+ */
+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` validates and exposes it
+   * as the `couplingTolerance` option and property.
+   */
+  couplingTolerance: number;
+  readonly flushes: FlushQueue;
+  /** Follow edges registered by following springs, with the dependency rank over their motions. */
+  readonly graph: FollowGraph;
+  /**
+   * Motions a reduced-motion change must reach while out of the tick: a
+   * `'motion'` ramp that moves on the clock unwatched, or one holding
+   * still under reduced motion. Each member keeps its membership current.
+   */
+  readonly reducible: Set<Motion>;
+  /**
+   * Returns the idle wall time, in seconds, the clock has not counted yet.
+   * Null when no ticker counts idle time. The ticker installs it, and
+   * moves the total in with `credit` on its first frame after starting or
+   * waking, and when it stops.
+   */
+  idleTime: (() => number) | null;
+  constructor(debug?: boolean);
+  get size(): number;
+  /**
+   * The system clock in seconds, which ramps read their position from. It
+   * moves only forward: by each tick's `dt` when the advance phase ends,
+   * and by idle wall time while the ticker sleeps. Wall time is read once
+   * per microtask checkpoint, so the clock holds still through
+   * synchronous code.
+   */
+  get time(): number;
+  /**
+   * The id of the tick whose advance phase is running, or 0 between
+   * phases. A ramp steps a cached value through the sub-steps of the
+   * phase and reads its anchor formula everywhere else.
+   */
+  get advancing(): number;
+  /** Adds idle wall time to the clock, in seconds. */
+  credit(seconds: number): void;
+  add(motion: Motion): void;
+  remove(motion: Motion): void;
+  /**
+   * Whether the motion is in the set. A motion that rests mid-pass leaves
+   * before its own `endFrame`, so motions ask here rather than track it.
+   */
+  has(motion: Motion): boolean;
+  /**
+   * Applies a reduced-motion change to the `reducible` registry first,
+   * because a ramp's jump retargets its followers, then to every moving
+   * motion, leaders before followers. A motion reached twice changes once.
+   */
+  setReduced(reduced: boolean): void;
+  tick(dt: number): void;
+}
+//#endregion
+//#region src/spring-source.d.ts
+/**
+ * The property key that brands a `SpringSource` and holds the api its
+ * followers read. It is a registry symbol
+ * (`Symbol.for('coily/spring-source')`), so one copy of coily
+ * recognizes sources from 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 of type `T` that a spring can animate toward or derive
+ * from. Assign a scalar source (`T = number`, the default) to
+ * `Spring.target`, and the spring tracks it with its momentum intact.
+ *
+ * Every `Spring` and `Ramp` is a `SpringSource`, and every
+ * `CompositeSpring` is a `SpringSource` of its value shape. `mapSpring`,
+ * `velocityOf`, `accelerationOf`, and `targetOf` derive new sources from
+ * existing ones. Use the type to name 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`, and every branch a plain object or array with at least
+ * one leaf. `mapSpring` takes `sources: T & SourceShape<T>`, so an
+ * invalid leaf errors on that property, not on the whole argument. The
+ * check is structural only, and the runtime validation repeats it for
+ * untyped callers. It rejects optional and `undefined`-typed leaves.
+ */
+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. A scalar spring leaf
+ * becomes `number`, and a composite leaf becomes its read-only value
+ * shape. This is what `map` receives when you give `mapSpring` 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, and
+ * `(v) => -v` mirrors it. Like any `SpringSource`, the result 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. `map` runs on every read, and
+ * each follower reads on every source update, so `map` must be pure.
+ * Nothing re-evaluates it when anything other than `source` changes.
+ * Mapping a mapped source extends its pipeline instead of wrapping it,
+ * so a chain costs one function call per map.
+ */
+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 single non-scalar source such as a
+ * `CompositeSpring`, or a shape: a plain object or array with
+ * `SpringSource` leaves, nested to any depth. `map` receives the
+ * matching values. For a shape, that is each leaf's current number
+ * (`mapSpring({ x, y }, ({ x, y }) => Math.hypot(x, y))`). For a
+ * composite, it is the live value shape
+ * (`mapSpring(point, ({ x, y }) => Math.hypot(x, y))`). An invalid leaf
+ * throws with its path (`position.z`).
+ *
+ * The result is a stateless view, not a spring. It holds no
+ * subscriptions and needs no disposal. `map` runs on every read, and
+ * each follower reads on every source update, so `map` must be pure.
+ * Every call hands it the same live mirror, refreshed in place, so `map`
+ * must not keep what it receives. The mapped source is released with the
+ * first of its sources, and followers then detach and keep their current
+ * target.
+ */
+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
+ * `velocity` and `acceleration`. A `Spring`, a `CompositeSpring`, and a
+ * `Ramp` report both exactly, from the model that moves the value. A
+ * source you write yourself can report them if it tracks a value in
+ * motion. A `mapSpring` result cannot, since it holds no motion of its
+ * own. `velocityOf` and `accelerationOf` read this slot.
+ */
+interface KinematicSourceApi<T = number> extends SpringSourceApi<T> {
+  /** The rate `value` is changing, in value units per second. */
+  readonly velocity: T;
+  /** The rate `velocity` is changing, in value units per second squared. */
+  readonly acceleration: T;
+}
+/**
+ * A `SpringSource` whose value is in motion, so it also carries
+ * `velocity` and `acceleration`. Every `Spring`, `CompositeSpring`, and
+ * `Ramp` is one, and `velocityOf` and `accelerationOf` accept these. A
+ * plain `SpringSource`, such as a `mapSpring` result, is not assignable.
+ */
+interface KinematicSource<T = number> extends SpringSource<T> {
+  readonly [SpringSourceSymbol]: KinematicSourceApi<T>;
+}
+/**
+ * A `KinematicSourceApi` that also reports `target`, where its motion is
+ * heading. A `Spring`, a `CompositeSpring`, and a `Ramp` carry it, and
+ * `targetOf` reads it.
+ */
+interface TargetedSourceApi<T = number> extends KinematicSourceApi<T> {
+  /** The value the motion is heading toward, in value units. */
+  readonly target: T;
+}
+/**
+ * A `KinematicSource` that also carries the `target` its motion is heading
+ * toward: every `Spring`, `CompositeSpring`, and `Ramp`, and the Vue refs
+ * that wrap them. `targetOf` accepts these. A `mapSpring` result is not
+ * assignable, because a value derivation has no target.
+ */
+interface TargetedSource<T = number> extends KinematicSource<T> {
+  readonly [SpringSourceSymbol]: TargetedSourceApi<T>;
+}
+/**
+ * Derives a source that reads another source's velocity: the rate its
+ * value changes, in value units per second. Speed-driven effects then
+ * use the same tools 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
+ * `CompositeSpring` yields a velocity of its own shape, which you map to
+ * a scalar as you would its value.
+ *
+ * The result is a stateless view that holds no subscriptions and needs
+ * no disposal. Each read reports the source's current velocity. It
+ * updates when the source does and is released with it, and followers
+ * then detach and keep their current target.
+ *
+ * Only a `Spring`, a `CompositeSpring`, a `Ramp`, or a Vue ref that wraps
+ * one qualifies. A `mapSpring` result has no velocity, and `velocityOf`
+ * rejects it 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 that reads another source's acceleration: the rate
+ * its velocity changes, in value units per second squared. On a spring it
+ * is largest just after a retarget and near the far end of each swing,
+ * and passes through zero where a swing moves fastest. 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`
+ * yields an acceleration of its own shape, which you map to a scalar as
+ * you would its value. A `Ramp`'s acceleration is always 0.
+ *
+ * The result is a stateless view that holds no subscriptions and needs
+ * no disposal. Each read reports the source's current acceleration. It
+ * updates when the source does and is released with it, and followers
+ * then detach and keep their current target.
+ *
+ * Only a `Spring`, a `CompositeSpring`, a `Ramp`, or a Vue ref that wraps
+ * one qualifies. A `mapSpring` result has no acceleration, and
+ * `accelerationOf` rejects it 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>;
+/**
+ * Derives a source that reads a spring's or ramp's target: where it is
+ * heading, not where it is. Pair it with the source in a `mapSpring`
+ * shape to measure against the destination, such as remaining travel,
+ * progress, or a lead that anticipates the move. A `Spring` or a bounded
+ * `Ramp` yields a scalar target that a spring can follow. An endless
+ * `Ramp` yields `Infinity` or `-Infinity`, and a spring that follows it
+ * throws. A `CompositeSpring` yields a target of its own shape, which you
+ * map to a scalar as you would its value.
+ *
+ * ```ts
+ * const system = createSpringSystem()
+ * const body = system.createSpring(0)
+ * // The eyes look ahead by the body's remaining travel, capped at 20.
+ * const lead = mapSpring({ value: body, target: targetOf(body) }, ({ value, target }) =>
+ *   Math.max(-20, Math.min(20, target - value)),
+ * )
+ * const eyes = system.createSpring(lead)
+ *
+ * body.target = 100
+ * system.advance(100)
+ * eyes.target // 20: the body still has more than 20 to go
+ * ```
+ *
+ * The result is a stateless view that holds no subscriptions and needs
+ * no disposal. Each read reports the spring's current target. It updates
+ * when the spring does, but assigning `target` emits nothing by itself,
+ * so followers pick up a new target on the next frame, when the spring
+ * starts toward it. Under reduced motion, a `'motion'` spring jumps to
+ * its new target and notifies followers at once. The view is released
+ * with the spring, and followers then detach and keep their current
+ * target.
+ *
+ * Only a `Spring`, a `CompositeSpring`, a `Ramp`, or a Vue ref that wraps
+ * one has a target. `targetOf` rejects a `mapSpring` result at the type
+ * level and at runtime.
+ */
+declare function targetOf<T>(spring: TargetedSource<T>): SpringSource<T>;
+//#endregion
+//#region src/spring.d.ts
+/**
+ * What a spring can animate toward. A number is a fixed target. A
+ * `SpringSource` (another spring, or a value derived from one with
+ * `mapSpring`) is a live value that the spring follows.
+ */
+type SpringTarget = number | SpringSource;
+/**
+ * What a spring animates, which decides whether reduced motion applies.
+ * `'motion'` moves something on screen, such as position, scale, or
+ * rotation, and snaps to its target under reduced motion. `'nonmotion'`
+ * moves nothing, such as a cross-fade, a color, a blur, or a number that
+ * never reaches the screen, and keeps animating under reduced motion.
+ * Fixed at creation. Read it back from `Spring.purpose`.
+ */
+type Purpose = 'motion' | 'nonmotion';
+/**
+ * One animated number, driven toward its target with damped spring
+ * motion. Create springs with `SpringSystem.createSpring`. A spring moves
+ * only when its system advances it.
+ *
+ * Reads return the exact, unrounded simulated state. Numeric writes
+ * (`target`, `value`, `velocity`, `jumpTo`) throw on `NaN` or an
+ * infinity. See https://github.com/tkofh/coily/blob/main/PRECISION.md
+ * for the numerical contract.
+ */
+declare class Spring implements TargetedSource {
+  #private;
+  /** Brands the spring as a `TargetedSource` whose api is the spring itself. */
+  get [SpringSourceSymbol](): TargetedSourceApi<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 smoothly, keeping the current value and velocity.
+   *   It also ends any 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
+   * `'nonmotion'`.
+   */
+  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, springs back from
+   * the written value, and notifies update listeners synchronously.
+   * Writing the current value is a no-op. Under reduced motion, a write
+   * jumps value and target together unless `purpose` is `'nonmotion'`.
+   */
+  get value(): number;
+  set value(value: number);
+  /**
+   * The current velocity, in value units per second.
+   *
+   * Writing flings the spring from its current value, and it settles back
+   * to the target. Under reduced motion, the write is ignored unless
+   * `purpose` is `'nonmotion'`.
+   */
+  get velocity(): number;
+  set velocity(value: number);
+  /**
+   * The current acceleration, in value units per second squared.
+   * Read-only, because stiffness and friction derive it from the current
+   * displacement and velocity. To fling the spring, write `velocity`.
+   */
+  get acceleration(): number;
+  /**
+   * What the spring animates, fixed at creation. Under reduced motion, a
+   * `'motion'` spring snaps to its target and a `'nonmotion'` spring keeps
+   * animating. 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.
+   *
+   * Assigning reconfigures the spring in place, keeping value and
+   * velocity, so mid-flight changes stay smooth. `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 precision: decimal places of the resting threshold. */
+  get precision(): number;
+  /** The config's arrival multiplier, applied to the velocity at each target crossing. */
+  get arrival(): number;
+  set config(value: SpringDefinition | null);
+  /**
+   * The time until the spring rests, in ms, solved from the motion: 0
+   * while resting, `Infinity` when it never settles. The spring rests at
+   * the first tick at or after this time. A bouncy spring can rest up to
+   * one oscillation earlier, when a frame samples a low point of the
+   * bounce. With `arrival: 0`, the time is capped at the first target
+   * crossing, exact to the ms.
+   */
+  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 rests or is disposed.
+   * It is already resolved while the spring rests and after dispose.
+   * Retargeting mid-flight extends the wait.
+   *
+   * @example
+   * ```ts
+   * spring.target = 300
+   * await spring.settled
+   * // the spring is at 300 and resting
+   * ```
+   */
+  get settled(): Promise<void>;
+  /**
+   * Snaps target and value to `value` and zeroes the velocity, with no
+   * animation. Listeners fire synchronously: `update`, plus `stop` if the
+   * spring was moving.
+   */
+  jumpTo(value: number): void;
+  /**
+   * Releases the spring permanently. It 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, and 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. It is purely structural, so interfaces
+ * satisfy it without index signatures, and runtime validation mirrors it
+ * 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. A write leaves absent or `undefined` channels
+ * unchanged.
+ */
+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, and
+ * every read refreshes them in place, 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 a
+ * channel that no purpose reaches defaults to `'motion'`. The purposes
+ * are 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. A write leaves absent or `undefined`
+ * channels unchanged.
+ */
+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. Targets, values, velocities, and configs read
+ * and write as shapes, writes can name any subset of the channels, and
+ * events coalesce across channels. Create one with
+ * `SpringSystem.createSpring`.
+ *
+ * A composite spring is a `SpringSource` of its value shape. Springs
+ * follow only scalar sources, so use `mapSpring` to derive one from the
+ * composite, alone or at the leaves of a shape.
+ *
+ * A write that names an unknown channel or gives one a non-finite value
+ * throws with the channel's path (`position.z`) and changes nothing.
+ */
+declare class CompositeSpring<in out T extends object> implements TargetedSource<ReadonlyShape<T>> {
+  #private;
+  /** Brands the composite as a `TargetedSource` whose api is the composite itself. */
+  get [SpringSourceSymbol](): TargetedSourceApi<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 is reused and refreshed in place on each read,
+   * so read it fresh instead of holding it across frames.
+   *
+   * Assignment accepts a `CompositeSpringTarget`:
+   * - A partial shape retargets the channels it names, each to a number
+   *   or to a scalar `SpringSource` to follow, such as a `Spring` or a
+   *   `mapSpring` result. Naming a channel detaches it from any leader.
+   * - A `CompositeSpring` of the same shape becomes the leader, and each
+   *   channel follows the matching leader channel.
+   *
+   * Unknown channels throw with their path. Under reduced motion,
+   * retargets apply instantly, except on channels whose `purpose` is
+   * `'nonmotion'`.
+   */
+  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 is reused and refreshed in place on each read,
+   * so read it fresh instead of holding it across frames.
+   *
+   * Assignment displaces the channels a partial shape names. Each keeps
+   * its target and springs back from the written value. The write fires
+   * one coalesced `update` synchronously. Under reduced motion, the named
+   * channels jump to the written values, targets included, except on
+   * channels whose `purpose` is `'nonmotion'`.
+   */
+  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. The mirror is reused and refreshed in
+   * place on each read.
+   *
+   * Assignment flings the channels a partial shape names. Under reduced
+   * motion, writes are ignored, except on channels whose `purpose` is
+   * `'nonmotion'`.
+   */
+  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. The mirror is reused and
+   * refreshed in place on each read. 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 whose configs each cover their subtree. Non-config leaves
+   * throw with their path. Assigning a `null` read back reverts every
+   * channel to the default rather than restoring the mix.
+   */
+  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. The purposes are fixed when the spring is
+   * created. A `'nonmotion'` channel opts out of reduced motion. See
+   * `Purpose`.
+   */
+  get purpose(): Purpose | null;
+  /** The largest `timeRemaining` across channels, in ms. */
+  get timeRemaining(): number;
+  /** Whether every channel is resting. */
+  get isResting(): boolean;
+  /**
+   * A promise that resolves when every channel next rests. It is already
+   * resolved while the composite rests or after dispose. Retargeting any
+   * channel mid-flight extends the wait, and disposing resolves it.
+   */
+  get settled(): Promise<void>;
+  /**
+   * Snaps the channels a partial shape names to the given values with no
+   * animation, setting both target and value. Fires one `update`
+   * synchronously, plus `stop` if the jump leaves every channel resting.
+   */
+  jumpTo(value: PartialShape<T>): void;
+  /**
+   * Releases every channel permanently. Each channel stops following, and
+   * its followers detach and keep their current targets. `settled`
+   * resolves and dispose listeners fire. Calling it again is a no-op.
+   * Afterward, final values stay readable and writes throw.
+   */
+  dispose(): void;
+  /**
+   * Subscribes to coalesced value changes. `update` fires at most once per
+   * tick, after every channel advances, and once per synchronous write that
+   * moves a channel, such as a `value` write or `jumpTo`. Returns an
+   * unsubscribe function.
+   */
+  onUpdate(callback: () => void): () => void;
+  /**
+   * Subscribes to the composite leaving rest. `start` fires when a channel
+   * starts to move and no other channel was moving. It always alternates
+   * with `stop`. Returns an unsubscribe function.
+   */
+  onStart(callback: () => void): () => void;
+  /**
+   * Subscribes to the composite coming to rest. `stop` fires when every
+   * channel rests, after that tick's final `update`. It 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/ramp.d.ts
+/** Options for `SpringSystem.createRamp`. */
+interface RampOptions {
+  /**
+   * The ramp's speed, in value units per second. Must be finite and
+   * >= 0. A rate of 0 rests the ramp where it is.
+   */
+  rate: number;
+  /**
+   * Where the ramp heads. `Infinity` or `-Infinity` makes it endless in
+   * that direction.
+   * @default the starting value, so the ramp starts at rest
+   */
+  target?: number | undefined;
+  /**
+   * What the ramp drives, which decides whether reduced motion applies.
+   * Under reduced motion, a `'motion'` ramp jumps to a bounded target and
+   * holds still on an endless one. A `'nonmotion'` ramp, such as a clock
+   * for logic, keeps moving. Fixed for the ramp's life. See `Purpose`.
+   * @default 'motion'
+   */
+  purpose?: Purpose | undefined;
+}
+/**
+ * A value that moves toward its target at a fixed speed, in a straight
+ * line, and stops there. Create ramps with `SpringSystem.createRamp`.
+ *
+ * A ramp is a `SpringSource`, so a spring can follow it. With the
+ * default `arrival`, the spring integrates against the ramp's steady
+ * motion exactly, where a target assigned once per frame would reach it
+ * as a staircase. With any other `arrival`, the spring holds the target
+ * still within each of a frame's sub-steps, one stair per sub-step.
+ * Typical uses are an endless spin, a heading that turns at a capped
+ * speed, and a clock in ms mapped into a shape with `mapSpring`.
+ *
+ * ```ts
+ * const system = createSpringSystem()
+ * const sweep = system.createRamp(0, { rate: 270, target: Infinity })
+ * const ring = system.createSpring(sweep, defineSpring({ duration: 300, dampingRatio: 1 }))
+ *
+ * system.advance(1000)
+ * sweep.value // 270
+ * ```
+ *
+ * A ramp costs nothing per frame unless something watches it: an
+ * `onUpdate` listener, a following spring, or, on a bounded ramp, an
+ * `onStop` listener or a pending `settled`. An unwatched ramp still
+ * moves, and a read reports where it is.
+ *
+ * Ramps move on the system clock. It counts frame time, `advance` calls,
+ * and the time a started system spends asleep, and stops while the
+ * system is stopped. A sleeping system skips the time the page is
+ * hidden. An awake system gets no frames in a hidden tab, so the hidden
+ * spell counts as one frame on return: `adjustedLag` ms if it lasted
+ * longer than `lagThreshold`, in full otherwise or with lag clamping off.
+ *
+ * The clock holds still through synchronous code, so every read in one
+ * event handler or render sees the same moment. A ramp created and read
+ * with no `await` in between reads its starting value.
+ *
+ * Under reduced motion, a `'motion'` ramp jumps to a bounded target, and
+ * an endless one holds still until reduced motion turns off, then
+ * resumes. A `'nonmotion'` ramp keeps moving.
+ */
+declare class Ramp implements TargetedSource {
+  #private;
+  /** Brands the ramp as a `TargetedSource` whose api is the ramp itself. */
+  get [SpringSourceSymbol](): TargetedSourceApi<number>;
+  constructor(motions: MotionSet, from: number, options: RampOptions);
+  /**
+   * The current value.
+   *
+   * Assignment accepts a finite number. It moves the ramp there at once,
+   * keeping its target and rate, and notifies update listeners
+   * synchronously. Writing the
+   * current value does nothing. Under reduced motion, a `'motion'` ramp
+   * with a bounded target rests at the written value, which becomes its
+   * target too.
+   */
+  get value(): number;
+  set value(value: number);
+  /**
+   * Where the ramp is heading, or `Infinity` or `-Infinity` for an
+   * endless ramp.
+   *
+   * Assignment accepts any number but `NaN`, and sends the ramp toward the
+   * new target at its current rate.
+   * It emits `start` if the ramp was resting, and no `update`, since the
+   * value has not moved. Under reduced motion, a `'motion'` ramp jumps to
+   * a bounded target, notifying update listeners, and holds still toward
+   * an endless one.
+   */
+  get target(): number;
+  set target(target: number);
+  /**
+   * The ramp's speed, in value units per second.
+   *
+   * Assignment accepts any finite number >= 0 and applies from the
+   * current value on. A rate of 0 rests the ramp where it is.
+   */
+  get rate(): number;
+  set rate(rate: number);
+  /**
+   * The current velocity, in value units per second. It is `rate`
+   * signed toward the target while the ramp moves, and 0 at rest.
+   */
+  get velocity(): number;
+  /** Always 0, since a ramp moves at a constant speed. */
+  get acceleration(): number;
+  /**
+   * What the ramp drives, `'motion'` or `'nonmotion'`, fixed when the
+   * ramp was created. A `'nonmotion'` ramp ignores reduced motion. See
+   * `Purpose`.
+   */
+  get purpose(): Purpose;
+  /**
+   * Whether the ramp is still: at its target, at a rate of 0, held under
+   * reduced motion, or disposed.
+   */
+  get isResting(): boolean;
+  /**
+   * The time until the ramp reaches its target, in ms. It is 0 at rest,
+   * and `Infinity` while the ramp moves toward an endless target.
+   */
+  get timeRemaining(): number;
+  /**
+   * A promise that resolves when the ramp next comes to rest. Already
+   * resolved while the ramp rests and after dispose. A pending
+   * `settled` keeps a bounded ramp in the frame loop, so the promise
+   * resolves on the frame the ramp arrives.
+   *
+   * ```ts
+   * ramp.target = 100
+   * await ramp.settled
+   * // the ramp is at 100
+   * ```
+   */
+  get settled(): Promise<void>;
+  /**
+   * Rests the ramp at `value`, which becomes both its value and target.
+   * Notifies update listeners synchronously, and emits `stop` if the ramp
+   * was moving.
+   */
+  jumpTo(value: number): void;
+  /**
+   * Releases the ramp permanently. It stops where it is, `settled`
+   * resolves, and dispose listeners run. Followers detach and keep their
+   * current target. Calling it again does nothing.
+   *
+   * The final value stays readable, and writes throw.
+   */
+  dispose(): void;
+  /**
+   * Subscribes to value changes: every frame the ramp moves, plus
+   * synchronous `value` writes, `jumpTo` calls, and reduced-motion jumps.
+   * A subscribed listener keeps the ramp in the frame loop. Returns an
+   * unsubscribe function.
+   */
+  onUpdate(callback: () => void): () => void;
+  /**
+   * Subscribes to the ramp leaving rest. `start` and `stop` alternate.
+   * Returns an unsubscribe function.
+   */
+  onStart(callback: () => void): () => void;
+  /**
+   * Subscribes to the ramp coming to rest: arriving at its target,
+   * `jumpTo`, a rate of 0, or holding under reduced motion. A subscribed
+   * listener keeps a bounded ramp in the frame loop, so the event fires
+   * on the frame it arrives. 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, in frames per second. 0 means uncapped: one tick per
+   * displayed frame, at whatever rate the screen runs. Capped ticks land
+   * on whole display frames near the requested rate, and each receives
+   * the true elapsed time. Must be >= 0.
+   * @default 0
+   */
+  readonly fps?: number | undefined;
+  /**
+   * The longest frame gap, in ms, that counts as a normal frame. A longer
+   * gap, such as a backgrounded tab or a blocking task, is lag, and the
+   * ticker replaces it with `adjustedLag` so springs do not teleport. 0
+   * disables lag clamping and reads back as 0. Must be >= 0.
+   * @default 500
+   */
+  readonly lagThreshold?: number | undefined;
+  /**
+   * The elapsed time, in ms, that replaces a lagging frame, capped at
+   * `lagThreshold` ms. It reads back as given, even above `lagThreshold`.
+   * Must be >= 0.
+   * @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. Under reduced motion, a `'motion'` spring
+   * snaps to its target and a `'nonmotion'` spring (a cross-fade, a color,
+   * a blur) keeps animating. 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, which decides its reduced-motion behavior.
+   * Give one `Purpose` for every channel, or a shape mirroring the value
+   * with purposes at any level. A subtree's purpose covers every channel
+   * below it, and unreached channels 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 can trail a source it follows within one frame, in
+   * the value's own units. Frames that would exceed it split into internal
+   * sub-steps (at most 8), keeping followed chains accurate through slow
+   * frames and sudden retargets. Smaller is tighter and costs more solver
+   * work, but never finer than the follower's resting precision. Listeners
+   * still fire once per frame, and springs that follow nothing are
+   * unaffected.
+   * @default 0.1
+   */
+  couplingTolerance?: number | undefined;
+  /**
+   * Logs the count of active motions to the console after each frame
+   * where it changed.
+   * @default false
+   */
+  debug?: boolean | undefined;
+  /**
+   * When reduced motion applies, making `'motion'` springs and ramps jump
+   * to their targets instead of animating. `'user'` follows the OS
+   * prefers-reduced-motion setting live, and a switch to reduced finishes
+   * in-flight motion at once. `'always'` and `'never'` force one behavior.
+   * @default 'user'
+   */
+  reducedMotion?: 'user' | 'always' | 'never' | undefined;
+}
+/**
+ * Owns springs and ramps 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`, the spring
+   * uses the default: critically damped, settling in about 500 ms. To
+   * follow a source from creation, pass it in place of `value`.
+   *
+   * `options.purpose` marks what the spring animates: `'nonmotion'`
+   * keeps animating under reduced motion, `'motion'` (the default) snaps.
+   */
+  createSpring(value: number, config?: SpringDefinition, options?: SpringOptions): Spring;
+  /**
+   * Creates a spring that already follows `source`, which can be any
+   * scalar `SpringSource`: a `Spring`, a `Ramp`, or a value derived with
+   * `mapSpring`, `velocityOf`, `accelerationOf`, or `targetOf`. Passing
+   * a composite source throws, so derive a scalar from it with
+   * `mapSpring`. The spring starts at the source's current value, the same
+   * as creating it there and assigning `source` to its `target`.
+   *
+   * `options.purpose` marks what the spring animates: `'nonmotion'`
+   * 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. A `'nonmotion'` channel keeps animating.
+   */
+  createSpring<T extends object>(value: T & Shape<T>, config?: ConfigShape<T>, options?: CompositeSpringOptions<T>): CompositeSpring<T>;
+  /**
+   * Creates a ramp at `from`: a value that moves in a straight line toward
+   * `options.target` at `options.rate` value units per second, then stops.
+   * Without a target it starts at rest, and `Infinity` or `-Infinity`
+   * makes it endless. A spring following a ramp with the default `arrival`
+   * integrates its steady motion exactly, not a per-frame staircase.
+   *
+   * ```ts
+   * // An endless spin at 270 deg/s, with a spring lagging behind it.
+   * const sweep = system.createRamp(0, { rate: 270, target: Infinity })
+   * const ring = system.createSpring(sweep)
+   *
+   * // A clock: 0 to 600 over 600 ms, mapped into a pulse.
+   * const clock = system.createRamp(0, { rate: 1000, target: 600 })
+   * const pulse = system.createSpring(mapSpring(clock, (ms) => Math.sin((Math.PI * ms) / 600)))
+   * ```
+   *
+   * Under reduced motion, a `'motion'` ramp (the default `purpose`) jumps
+   * to a bounded target and holds still on an endless one. A `'nonmotion'`
+   * ramp keeps moving.
+   */
+  createRamp(from: number, options: RampOptions): Ramp;
+  /**
+   * Advances every moving spring and ramp by `dt` ms, for manual stepping
+   * in place of `start()`: tests, custom loops, offline rendering. Throws
+   * unless `dt` is finite and >= 0.
+   */
+  advance(dt: number): void;
+  /**
+   * Begins animating on real frames: one tick per displayed frame, through
+   * `requestAnimationFrame` in the browser and a `setTimeout` fallback
+   * elsewhere. An idle system sleeps, scheduling no frames while every
+   * spring rests and no ramp advances with the frame loop. Throws after
+   * `dispose`.
+   */
+  start(): void;
+  /** Stops animating. Springs and ramps 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;
+  /**
+   * Stops the system for good and removes the page listeners it added at
+   * creation: visibility and, with `reducedMotion: 'user'`, the media
+   * query. Dispose a system you no longer need. `useSpringSystem` disposes
+   * the system it creates on unmount. Calling it again is a no-op.
+   *
+   * After dispose, `start()` throws. `advance` still steps the springs
+   * and ramps, and `reducedMotion` no longer follows the user setting.
+   */
+  dispose(): void;
+  /**
+   * Whether reduced motion is on, per the `reducedMotion` option and, in
+   * `'user'` mode, the live OS setting. While on, `'motion'` springs and
+   * ramps jump instead of animating, and `'nonmotion'` ones still animate.
+   * Read it to gate decorative effects of your own.
+   */
+  readonly reducedMotion: boolean;
+  /**
+   * How far a spring can 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, in frames per second. 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. Assignment
+   * accepts any number >= 0.
+   */
+  fps: number;
+  /**
+   * Frame gap, in ms, above which the system treats the gap as lag (a
+   * backgrounded tab, a blocking task) and replaces it with `adjustedLag`,
+   * so springs do not teleport when frames resume. Assignment accepts any
+   * number >= 0, and 0 disables lag clamping.
+   */
+  lagThreshold: number;
+  /**
+   * The elapsed ms that replaces a lagging frame's gap. A frame uses at
+   * most `lagThreshold` ms of it. Reads return the value last set, even
+   * above `lagThreshold`. Assignment accepts any number >= 0.
+   */
+  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 { SpringSourceSymbol as A, accelerationOf as C, SourceValues as D, SourceShape as E, SpringSource as O, TargetedSourceApi as S, velocityOf as T, Spring as _, createSpringSystem as a, KinematicSourceApi as b, CompositeSpring as c, PartialShape as d, PurposeShape as f, Purpose as g, TargetShape as h, SpringSystemOptions as i, mapSpring as j, SpringSourceApi as k, CompositeSpringTarget as l, Shape as m, SpringOptions as n, Ramp as o, ReadonlyShape as p, SpringSystem as r, RampOptions as s, CompositeSpringOptions as t, ConfigShape as u, SpringTarget as v, targetOf as w, TargetedSource as x, KinematicSource as y };