@weasel-js/animator 0.0.0-stage → 1.9.4

package/dist/index.d.ts

@@ -0,0 +1,1353 @@
+import { EasingSpec, SpringPresetName, EasingName, BezierEasing, GlMat3, Path, PolygonPath } from '@weasel-js/geom';
+export { BezierEasing, EasingFn, EasingSpec, SpringPreset, SpringPresetName } from '@weasel-js/geom';
+import { ColorSpace } from '@weasel-js/paint';
+
+/** How a target's value maps to the flat numbers an animation moves, and back. */
+interface TargetAxes<T> {
+    count: number;
+    to(value: T): number[];
+    from(axes: ArrayLike<number>): T;
+    /** Indexes of axes that are angles in radians. An animation starting from one takes the short
+     *  way round to its destination. */
+    angles?: readonly number[];
+    /** Optional. `value` with `delta` added axis by axis: what `from` answers for `to(value)`
+     *  plus `delta`, built with no array between. A read of a moving target goes through it. */
+    add?(value: T, delta: ArrayLike<number>): T;
+    /** Optional. Puts `value`'s axes into `out` from `at`: what `to` answers, with no array
+     *  built. `readInto` goes through it. */
+    write?(value: T, out: AxisBuffer, at: number): void;
+}
+/** Somewhere a target's axes are written as numbers. */
+type AxisBuffer = Float64Array | Float32Array | number[];
+/** What {@link createTarget} takes. */
+interface TargetOptions<T> {
+    /** The committed value: what shows when nothing is animating. */
+    get(): T;
+    /** Commits a value: an animation's destination as it starts, and where a canceled one stopped. */
+    set(value: T): void;
+    /** How `T` maps to numbers. Default: a number, an array of numbers, or a plain object whose
+     *  fields are all numbers, read from `get()` when the target is made. */
+    axes?: TargetAxes<T>;
+    /** Called once a frame, after the frame's animations, with the value to show: on every frame
+     *  the target is moving, as an animation starts on it or is redirected, and once more as it
+     *  comes to rest. Omit for a target whose reader
+     *  calls `read()` itself. */
+    show?(value: T): void;
+    /** Called once a frame, after every target that was shown that frame: for a table that
+     *  publishes many targets at once. Targets passing the same function share one call. */
+    publish?(): void;
+}
+/**
+ * One value an animator can move. Pass it as `target` to `tween`, `spring`, `physics` or `decay`.
+ *
+ * An animation on a target commits its destination when it starts and contributes only what is
+ * left to travel, so several on one target add: a second started mid-flight bends the motion
+ * toward its own destination and neither cancels the other.
+ */
+interface Target<T> {
+    /** The value to show: the committed value plus what every running animation has left to travel. */
+    read(): T;
+    /**
+     * As `read`, as numbers: writes the value's `axisCount` axes into `out` from `at` (default 0),
+     * in the order the target's `axes.to` answers them. For a reader of many targets that wants
+     * the numbers and no value built for each.
+     */
+    readInto(out: AxisBuffer, at?: number): void;
+    /** How many axes `readInto` writes. */
+    readonly axisCount: number;
+    /** How its value maps to numbers. */
+    readonly axes: TargetAxes<T>;
+    /** The committed value: what shows once nothing is moving it. */
+    committed(): T;
+    /** Writes the committed value. Animations moving the target go on adding to the new one. */
+    commit(value: T): void;
+    /** Whether any animation is moving it. */
+    readonly active: boolean;
+    /**
+     * Stops every animation moving it. Each commits where it was, so the value on screen stays,
+     * unless `commit` is false: then the committed value is left as it stands and the target
+     * shows it. Pass false after something else has written the committed value mid-flight.
+     */
+    stop(opts?: {
+        commit?: boolean;
+    }): void;
+}
+/** Make a {@link Target} over a value the caller owns. */
+declare function createTarget<T>(opts: TargetOptions<T>): Target<T>;
+
+/** Which of a node's two per-anchor color arrays an override applies to. */
+type VertexColorChannel = 'fill' | 'stroke';
+/** Function-form override: receives the consumer-supplied base color
+ *  array and the current animation timestamp (ms, from the animator's
+ *  clock). Returns a flat RGBA float array (values in 0..1, matching
+ *  the renderer's `stroke.vertexColors` / `PathDrawCommand.vertexColors`
+ *  color space) of the same length as `base`. */
+type ColorOverrideFn = (base: readonly number[], tMs: number) => number[];
+/** Either a static per-anchor RGBA float array (0..1) or a function-form
+ *  override (see {@link ColorOverrideFn}). */
+type ColorOverride = readonly number[] | ColorOverrideFn;
+/** Per-node, per-channel store of color overrides. Attached to `useAnimator` as
+ *  `animator.colorOverrides`; painted onto scene nodes by `<SceneCanvas animator>`
+ *  and onto a `createPathLayer`'s nodes by its `colorOverrides` option. */
+declare class ColorOverrideRegistry {
+    private readonly map;
+    private readonly slots;
+    private readonly tables;
+    private _version;
+    set(id: string, channel: VertexColorChannel, override: ColorOverride): void;
+    /** Drops `id`'s override on `channel`, and the colors a finished or canceled animation on its
+     *  {@link target} left painted. An animation still running goes on. */
+    clear(id: string, channel: VertexColorChannel): void;
+    clearAll(): void;
+    /** What `set` stored for `id`'s `channel`; failing that, the colors its {@link target} paints. */
+    get(id: string, channel: VertexColorChannel): ColorOverride | undefined;
+    /** Whether anything overrides `id`, on either channel. */
+    has(id: string): boolean;
+    /**
+     * The {@link Target} for `id`'s colors on `channel`: `length` numbers, flat RGBA per anchor.
+     * Every caller for one node and channel gets the same one, so their animations add. The
+     * registry holds its committed colors and nothing writes the scene.
+     *
+     * What it paints: with no override from `set`, its colors in place of the painter's own; over
+     * one, only what its animations have left to travel, added on top. Ask again for each
+     * animation rather than keeping it: {@link release} and {@link clear} drop a resting one, and
+     * the target it had throws from then on.
+     */
+    target(id: string, channel: VertexColorChannel, length: number): Target<number[]>;
+    private tableOf;
+    private drop;
+    /** Drops the colors `id`'s {@link target} on `channel` left painted, unless an animation is
+     *  still moving it. An override from `set` stays. */
+    release(id: string, channel: VertexColorChannel): void;
+    /**
+     * The colors to paint on `id`'s `channel`, given the colors the painter would
+     * otherwise paint and the frame's timestamp. A function override needs that
+     * `base` and must return an array of its length; failing either, `base`
+     * stands. A {@link target} in motion then adds what it has left to travel.
+     */
+    resolve(id: string, channel: VertexColorChannel, base: readonly number[] | undefined, tMs: number): readonly number[] | undefined;
+    private apply;
+    version(): number;
+}
+
+/** One keyframe. `easing` shapes the approach INTO this key from the previous
+ *  one, so the first key's easing is never consulted. */
+interface Keyframe<T> {
+    /** Time within the track's timeline, in ms. */
+    t: number;
+    value: T;
+    /** A function, the name of a built-in, or cubic-bezier control points. */
+    easing?: EasingSpec;
+}
+/** A track sampled as a pure function of the playhead. Scrubbing one is free
+ *  and order-independent. Give it `onTick`, a `target`, or both. */
+interface SampledTrack<T> {
+    kind: 'sampled';
+    label?: string;
+    /** Sorted ascending by `t`. Of keys sharing a time, the last in the array is
+     *  the value at exactly that time. */
+    keys: Keyframe<T>[];
+    /** Required unless the track has a `target`, or every key's value is a number, a number
+     *  array or a plain object of numbers, all of one shape; those are lerped field by field. */
+    interpolate?: Interpolate<T>;
+    /** Built once per segment and cached. Takes precedence over `interpolate`. */
+    interpolator?: InterpolatorFactory<T>;
+    /** Told each sampled value, at any playhead. Optional beside a `target`. */
+    onTick?: (value: T) => void;
+    /**
+     * A value for the track to move. While the playhead is within the track's keys, the target
+     * shows the sampled value in place of its committed one, as under `animator.hold`, with
+     * what an animation on the target shows apart from its destination added on top. Once the playhead is past the last key, or the
+     * timeline finishes or is canceled, the target keeps the value it was showing; before the
+     * first key the track leaves the target alone.
+     *
+     * With no `interpolate` or `interpolator`, the track is sampled in the target's axes: each
+     * axis lerps on its own, an angle axis the short way round from the key before, and every
+     * sample is a value the axes built, a key's own included.
+     */
+    target?: Target<T>;
+    /** What `target` goes by in a clip, for `toClip` to write and a `ClipBinder` to resolve.
+     *  A target has no name of its own. */
+    targetName?: string;
+    /** What `interpolate` goes by in a clip, as `targetName` is for `target`. */
+    interpolateName?: string;
+    /** The track's share among the target's holds, as `HoldOptions.weight`. Default 1. */
+    weight?: number | (() => number);
+    /** The axes of the target the track holds, as `HoldOptions.axes`. Default: every axis. */
+    axes?: readonly number[];
+}
+/** A clock that events are booked against, reading in ms. An `AudioEngine`
+ *  from `@weasel-js/audio` is one. */
+interface TimelineClock {
+    now(): number;
+}
+/** What `book` hands back so the booking can be retracted. A `VoiceHandle` from
+ *  `@weasel-js/audio` is one. */
+interface EventBookingHandle {
+    stop(): void;
+}
+/** One entry on an `EventTrack`. Give it `fire`, `book`, or both. */
+interface TimelineEvent {
+    /** Time within the track's timeline, in ms. */
+    t: number;
+    /** What the event goes by in a clip: a `ClipBinder` turns it and `data` into `fire` and
+     *  `book`. */
+    name?: string;
+    /** Carried with `name` into a clip. Anything JSON holds. */
+    data?: unknown;
+    /** Runs on the frame that crosses the edge, told how far behind the frame it
+     *  was crossed, in ms — never negative, and measured against `duration` on
+     *  the loop seam, where the outgoing lap's tail fires after the wrap. */
+    fire?: (lateBy: number) => void;
+    /** Runs up to `booking.lookahead` before the edge on a timeline with a
+     *  `booking`, once per crossing, with the `booking.clock` time the edge lands
+     *  at — never earlier than that clock's `now()`. A returned handle is stopped
+     *  if a pause, seek, rate change, loop change, edit or cancel invalidates the
+     *  booking before the clock reaches `when`; the event is then booked again
+     *  wherever playback next reaches it. A booking with no handle stands. */
+    book?: (when: number) => EventBookingHandle | void;
+}
+/** A track of edge crossings, in forward playback only — a `seek` neither
+ *  fires nor books the span it skips. An event the playhead is sitting on,
+ *  after a seek or at the start, fires when playback next advances from there
+ *  and never while paused. */
+interface EventTrack {
+    kind: 'event';
+    label?: string;
+    /** Sorted ascending by `t`. */
+    events: TimelineEvent[];
+}
+/** How a timeline books its events against an outside clock. */
+interface EventBooking {
+    clock: TimelineClock;
+    /** How far ahead of the playhead to book, in clock ms. Default 100. An event
+     *  first reached later than this — after a frame longer than it — books late. */
+    lookahead?: number;
+    /** An event first reached more than this many clock ms after its edge is
+     *  skipped instead of booked late. Default `Infinity`. */
+    maxLate?: number;
+}
+/** A nested timeline, evaluated at `playhead - at`. Children are NOT registered
+ *  with the animator separately; the parent evaluates them. */
+interface TimelineTrack {
+    kind: 'timeline';
+    label?: string;
+    at: number;
+    timeline: NestedTimeline;
+}
+/** Any track a timeline can hold. */
+type Track = SampledTrack<any> | EventTrack | TimelineTrack;
+/** What a child timeline may declare. The parent owns playback, so `loop`,
+ *  `autoplay`, `onDone` and `cancelKey` have no meaning below the root. */
+interface NestedTimeline {
+    tracks: Track[];
+    /** Defaults to the largest end time across `tracks`. */
+    duration?: number;
+}
+/** What `animator.timeline` takes: a root timeline, which owns playback. */
+interface TimelineOptions extends NestedTimeline {
+    /** `true` loops forever, `n` loops n additional times. Default false. */
+    loop?: boolean | number;
+    /** Default true. When false the timeline registers but holds at t=0 until resumed. */
+    autoplay?: boolean;
+    /** Called when playback reaches the end of its last lap. */
+    onDone?: () => void;
+    /** Any new animation passed the same `cancelKey` cancels this one. */
+    cancelKey?: string;
+    /** Names this timeline in `animator.watch` events and `animator.live()`. */
+    label?: string;
+    /** Books each event's `book` against a clock the timeline does not own, so a
+     *  consumer on that clock lands it at its true sub-frame time. The frame
+     *  clock's mapping onto it is smoothed each frame and resynced on a jump. */
+    booking?: EventBooking;
+}
+/** What `animator.timeline` returns: playback control plus live editing. */
+interface TimelineHandle extends AnimationHandle {
+    /** Move the playhead. Fires no event itself, at any depth; an event exactly
+     *  at `t` fires when playback next advances. Sampled tracks are sampled at
+     *  `t` at once, so a target they hold reads the new value before the next frame. */
+    seek(t: number): void;
+    /** Change the loop policy. `true` loops forever, `n` allows n more laps,
+     *  `false` stops at `duration`. Sets policy only — a timeline already parked
+     *  at `duration` does not restart, because `rearm` declines to revive one.
+     *  Rewind it with `seek(0)` and `resume()` to play it again. */
+    setLoop(loop: boolean | number): void;
+    /** The loop policy as it now stands: `true` endless, `false` stopping at
+     *  `duration`, `n` for n laps still allowed. A finite count falls as laps
+     *  are consumed, matching what `setLoop` takes. */
+    loop(): boolean | number;
+    /** Current playhead in ms. */
+    time(): number;
+    duration(): number;
+    tracks(): readonly Track[];
+    /** Run `fn`, then recompute duration, drop cached interpolators, sample the
+     *  tracks again where the playhead stands, and notify.
+     *  Every mutation must go through this — an edited keyframe otherwise keeps
+     *  interpolating toward its old value with no visible error. */
+    edit(fn: () => void): void;
+    /** Notified after each `edit`. Returns an unsubscribe. */
+    subscribe(cb: () => void): () => void;
+    /** Notified when playback changes other than by time passing: `pause`,
+     *  `resume`, `seek`, `setTimeScale`, `setLoop`, a cancel, and the playhead
+     *  reaching the end. What a view of the playhead listens to, so a change
+     *  made elsewhere reaches it. Returns an unsubscribe. */
+    subscribePlayback(cb: () => void): () => void;
+}
+
+/** What every animation on a {@link Target} takes. */
+interface OnTarget<T> {
+    /** The value to move. */
+    target: Target<T>;
+    /** Told this animation's own value each frame: its destination plus what it has left to travel. */
+    onTick?: (value: T) => void;
+    onDone?: () => void;
+    /** Any new animation passed the same cancelKey cancels the prior one in flight. Leave it off
+     *  to let animations on one target add. */
+    cancelKey?: string;
+    /** False to take `cancelKey` without canceling the animations holding it, so it adds to them
+     *  and `cancelKey`, `pauseKey`, and `isActive` reach them all. Default true. */
+    interrupt?: boolean;
+    /** Names this animation in {@link AnimatorEvent}s and `animator.live()`. */
+    label?: string;
+}
+/** A tween on a {@link Target}. `to` is committed as it starts, and it contributes what is left
+ *  to travel, so it adds to whatever else is moving the target. */
+interface TargetTweenOptions<T> extends OnTarget<T> {
+    to: T;
+    /** Where its own travel starts. Default: the target's committed value, so the value on screen
+     *  does not move as it starts. */
+    from?: T;
+    ms: number;
+    easing?: EasingSpec;
+    /** The path from `from` to `to`, where a straight line per axis is not it. */
+    interpolate?: Interpolate<T>;
+    /** As `interpolate`, built once at the start. Takes precedence. */
+    interpolator?: InterpolatorFactory<T>;
+}
+/** A spring on a {@link Target}. Needs positive stiffness, damping and mass. Interrupting an
+ *  animation on the same target under the same `cancelKey`, it starts at that one's velocity
+ *  unless given its own. */
+interface TargetSpringOptions<T> extends OnTarget<T> {
+    to: T;
+    /** As {@link TargetTweenOptions.from}. */
+    from?: T;
+    /** Initial velocity in T-units per second. */
+    velocity?: T;
+    preset?: SpringPresetName;
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    /** Distance from `to` and speed, both in axis units, under which it has come to rest. Default 0.01. */
+    restThreshold?: number;
+}
+/** Spring and coast as one animation on a {@link Target}. With `to: null` it coasts on its
+ *  velocity, committing where it is when it stops. */
+interface TargetPhysicsOptions<T> extends Omit<TargetSpringOptions<T>, 'to'> {
+    to?: T | null;
+}
+/** What `animator.hold` takes. */
+interface HoldOptions<T> {
+    /** The value to hold. */
+    target: Target<T>;
+    /** What to show in place of the committed value: a value, or a function read each frame. */
+    value: T | (() => T);
+    /** Its share among the target's holds, 0 to 1: a number, or a function read each frame.
+     *  Default 1. Holds on one target show their weighted average, and whatever their weights
+     *  leave short of 1 is the committed value's. */
+    weight?: number | (() => number);
+    /**
+     * Indexes of the target's axes it holds, in the order the target's `TargetAxes.to` answers
+     * them. The rest are left to the target's other holds and its committed value, and a release
+     * commits only these. Default: every axis. For a rig's joints, `jointAxes`.
+     */
+    axes?: readonly number[];
+    /** Any new animation passed the same cancelKey cancels this one. */
+    cancelKey?: string;
+    /** Names this hold in {@link AnimatorEvent}s and `animator.live()`. */
+    label?: string;
+    /** With `false`, it takes its `cancelKey` without canceling whoever holds it. Default true. */
+    interrupt?: boolean;
+}
+/** What `animator.hold` returns. `cancel` commits what the hold was showing, as `release()`
+ *  does; pausing it or scaling its time changes nothing, since it has no clock. */
+interface HoldHandle extends AnimationHandle {
+    /** Says a function-form `value` or `weight` changed outside a frame, so the target shows it
+     *  now rather than at the next frame the animator happens to run. */
+    touch(): void;
+    /** Ends the hold. By default it commits the value it was showing, so the target stays where
+     *  it is; with `commit: false` the committed value is left alone and the target falls back
+     *  to it. */
+    release(opts?: {
+        commit?: boolean;
+    }): void;
+}
+/** A coast on a {@link Target}: it commits where it stops. */
+interface TargetDecayOptions<T> extends OnTarget<T> {
+    /** As {@link TargetTweenOptions.from}. */
+    from?: T;
+    velocity: T;
+    /** Per-second velocity multiplier in (0, 1). Default 0.95. */
+    friction?: number;
+    /** Speed below which it stops. Default 0.5. */
+    threshold?: number;
+}
+
+/** Blends two `T` values at eased progress `t`. Called once per frame; see
+ *  {@link InterpolatorFactory} when the blend has setup worth hoisting. */
+type Interpolate<T> = (from: T, to: T, t: number) => T;
+/** Factory interpolator: built ONCE at tween start with (from, to), the returned
+ *  function is called with `t ∈ [0, 1]` each frame. Use for interpolators with
+ *  expensive setup (color-space conversion, path-string parsing) — d3-interpolate's
+ *  shape exactly. For cheap interpolations the per-tick `Interpolate<T>` form is
+ *  fine; this is the escape hatch when setup-per-tick is wasteful. */
+type InterpolatorFactory<T> = (from: T, to: T) => (t: number) => T;
+/** A running animation. Cancel it, or bend its time — pausing and time-scaling
+ *  act on this animation's own virtual clock, independent of the animator's. */
+interface AnimationHandle {
+    /** Monotonic id assigned by the animator. */
+    id: number;
+    /** Cancel this animation. Idempotent — no-op once already finished/canceled. */
+    cancel(): void;
+    /** Freeze this animation's virtual clock. Idempotent. */
+    pause(): void;
+    /** Resume this animation's virtual clock. Idempotent. */
+    resume(): void;
+    /** Multiply this animation's virtual-clock rate by `scale`, 0 or above. 1 = normal. */
+    setTimeScale(scale: number): void;
+    /** This animation's own time scale. 1 once it has finished, since the
+     *  animator no longer holds an entry to read. */
+    timeScale(): number;
+    /** True iff this handle is currently paused. */
+    isPaused(): boolean;
+}
+/** A duration-based animation from `from` to `to` over `ms`, shaped by an
+ *  easing curve. Reach for a spring instead when the motion should respond to
+ *  where the value already is rather than restart from a fixed duration. */
+interface TweenOptions<T> {
+    /** Absent: this form hands values to `onTick`. The `Target` form of these options moves a target. */
+    target?: undefined;
+    from: T;
+    to: T;
+    ms: number;
+    easing?: EasingSpec;
+    /** Required when T is not `number`. For T = number, defaults to linear numeric lerp.
+     *  Called per-tick with `(from, to, t)`. For interpolators with expensive setup,
+     *  prefer `interpolator` which is built once at tween start. */
+    interpolate?: Interpolate<T>;
+    /** Factory interpolator built once at tween start. Takes precedence over
+     *  `interpolate` when both are provided. Use this for d3-interpolate or any
+     *  `(from, to) => (t) => v` shape. */
+    interpolator?: InterpolatorFactory<T>;
+    onTick: (value: T) => void;
+    onDone?: () => void;
+    /** Any new animation passed the same cancelKey cancels the prior one in flight. */
+    cancelKey?: string;
+    /** Names this animation in {@link AnimatorEvent}s and `animator.live()`. */
+    label?: string;
+}
+/** A spring animation: runs until the value settles on `to` rather than for a
+ *  set duration, so it absorbs an initial velocity naturally. Non-numeric `T`
+ *  needs the four vector helpers. */
+interface SpringOptions<T> {
+    /** Absent: this form hands values to `onTick`. The `Target` form of these options moves a target. */
+    target?: undefined;
+    from: T;
+    to: T;
+    /** Initial velocity in T-units per second. Default: zero (T-shape-aware). */
+    velocity?: T;
+    preset?: SpringPresetName;
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    interpolate?: Interpolate<T>;
+    /** Vector helpers — required for non-numeric T. When `from`, `to` and `velocity` are numbers, number
+     *  arrays or plain objects of numeric fields of one shape, and stiffness, damping and mass are
+     *  positive, the motion is solved in closed form and these only decide when it has come to rest —
+     *  a `subtract` that wraps an angle won't change the path. */
+    add?: (a: T, b: T) => T;
+    subtract?: (a: T, b: T) => T;
+    scale?: (v: T, k: number) => T;
+    magnitude?: (v: T) => number;
+    /** Velocity magnitude below which the spring is considered settled. Default 0.01. */
+    restThreshold?: number;
+    onTick: (value: T) => void;
+    onDone?: () => void;
+    cancelKey?: string;
+    /** Names this animation in {@link AnimatorEvent}s and `animator.live()`. */
+    label?: string;
+}
+/** Spring and decay as one animation. With a `to`, a spring pulls toward it;
+ *  with `to: null`, the value coasts on its velocity. Either can become the
+ *  other mid-flight through the handle. */
+interface PhysicsOptions<T> {
+    /** Absent: this form hands values to `onTick`. The `Target` form of these options moves a target. */
+    target?: undefined;
+    from: T;
+    /** Target. `null` ⇒ no spring force (decay-mode). */
+    to?: T | null;
+    /** Initial velocity in T-units per second. */
+    velocity?: T;
+    preset?: SpringPresetName;
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    restThreshold?: number;
+    /** Vector helpers — required for non-numeric T. When `from`, `to` and `velocity` are numbers, number
+     *  arrays or plain objects of numeric fields of one shape, and stiffness, damping and mass are
+     *  positive, the motion is solved in closed form and these only decide when it has come to rest —
+     *  a `subtract` that wraps an angle won't change the path. */
+    add?: (a: T, b: T) => T;
+    subtract?: (a: T, b: T) => T;
+    scale?: (v: T, k: number) => T;
+    magnitude?: (v: T) => number;
+    onTick: (value: T) => void;
+    onDone?: () => void;
+    cancelKey?: string;
+    /** Names this animation in {@link AnimatorEvent}s and `animator.live()`. */
+    label?: string;
+}
+/** An `AnimationHandle` that can also be steered while it runs — the point of
+ *  the physics primitive. */
+interface PhysicsHandle<T = unknown> extends AnimationHandle {
+    /** Retarget mid-flight. `null` ⇒ switch to decay-mode (no spring force). */
+    setTarget(to: T | null): void;
+    /** Replace the current velocity in T-units per second. */
+    setVelocity(v: T): void;
+}
+/** Momentum: coast from `from` at `velocity`, slowing by `friction` each
+ *  second until below `threshold`. What a flick-to-pan leaves behind. */
+interface DecayOptions<T> {
+    /** Absent: this form hands values to `onTick`. The `Target` form of these options moves a target. */
+    target?: undefined;
+    from: T;
+    velocity: T;
+    /** Per-second velocity multiplier in (0, 1). Default 0.95. */
+    friction?: number;
+    /** Velocity magnitude below which decay stops. Default 0.5. */
+    threshold?: number;
+    /** When `from` and `velocity` are numbers, number arrays or plain objects of numeric fields of one
+     *  shape and `friction` is below 1, the motion is solved in closed form: `add` and `scale` go
+     *  unused and `magnitude` only decides when it has come to rest. */
+    add: (a: T, b: T) => T;
+    scale: (v: T, k: number) => T;
+    magnitude: (v: T) => number;
+    onTick: (value: T) => void;
+    onDone?: () => void;
+    cancelKey?: string;
+    /** Names this animation in {@link AnimatorEvent}s and `animator.live()`. */
+    label?: string;
+}
+/** Options for `useAnimator`. Everything here is an injection seam for tests;
+ *  the defaults are the real clock and rAF. */
+interface UseAnimatorOptions {
+    /** Optional clock injection for tests. Returns ms since some epoch. */
+    now?: () => number;
+    /** Optional rAF / cAF injection for tests. Defaults to window.requestAnimationFrame. */
+    requestFrame?: (cb: (t: number) => void) => number;
+    cancelFrame?: (handle: number) => void;
+}
+/**
+ * Owns every running animation on a canvas and drives them from one rAF loop.
+ * Beyond the primitives (`tween`, `spring`, `decay`, `physics`) it offers
+ * composition — `loop`, `stagger` — and bulk control by handle, by cancel-key,
+ * or over everything at once.
+ *
+ * An animator does not know about the scene. An animation either reports values
+ * through `onTick` and the caller decides what to do with them, or moves a
+ * {@link Target}, where several on one target add.
+ */
+interface Animator {
+    tween<T>(opts: TweenOptions<T> | TargetTweenOptions<T>): AnimationHandle;
+    spring<T>(opts: SpringOptions<T> | TargetSpringOptions<T>): AnimationHandle;
+    decay<T>(opts: DecayOptions<T> | TargetDecayOptions<T>): AnimationHandle;
+    /** Unified spring/decay primitive. With `to` set, behaves as a spring;
+     *  with `to: null`, behaves as a velocity-driven decay. Supports
+     *  mid-flight retargeting via the returned handle's `setTarget`. */
+    physics<T>(opts: PhysicsOptions<T> | TargetPhysicsOptions<T>): PhysicsHandle<T>;
+    /** Shows a value on a {@link Target} in place of its committed one until canceled or released.
+     *  It covers an animation's move to a destination; a coast, push, or `from` offset adds on top. */
+    hold<T>(opts: HoldOptions<T>): HoldHandle;
+    /** Cancel a specific animation by handle. Pose stays at current value (no jump). */
+    cancel(handle: AnimationHandle): void;
+    /** Cancel every animation currently active under `key`. */
+    cancelKey(key: string): void;
+    /** Cancel everything. Useful from a destructor or "reset scene" path. */
+    cancelAll(): void;
+    /** True iff at least one animation is active. With `key`, scoped to that cancelKey. */
+    isActive(key?: string): boolean;
+    /**
+     * True while the animator is currently executing an animation tick. Useful
+     * for adapter wrappers (e.g. `animateOnSetPose`) that need to detect
+     * "this `setPose` was called from inside another animation's onTick"
+     * (momentum decay, in-flight tween, spring) and avoid recursively
+     * scheduling a new wrap-animation that would fight the caller.
+     */
+    isTicking(): boolean;
+    /** Freeze every animation managed by this animator. */
+    pause(): void;
+    /** Resume every animation managed by this animator. */
+    resume(): void;
+    /** True iff the animator is currently globally paused. */
+    isPaused(): boolean;
+    /** Multiply every animation's virtual-clock rate by `scale`, 0 or above. 1 = normal. */
+    setTimeScale(scale: number): void;
+    /** The global time scale. Per-animation scales multiply on top of it. */
+    timeScale(): number;
+    /** Freeze every animation whose `cancelKey` matches. */
+    pauseKey(key: string): void;
+    /** Resume every animation whose `cancelKey` matches. */
+    resumeKey(key: string): void;
+    /** Set per-animation timeScale for every animation whose `cancelKey` matches. */
+    setTimeScaleByKey(key: string, scale: number): void;
+    /**
+     * Loop primitive: repeatedly invoke `factory` to produce a child animation.
+     * The factory must wire its returned handle's `onDone` to call `next` so
+     * the loop advances. Returns a handle whose pause/resume/setTimeScale/cancel
+     * delegate to the current in-flight child (and prevent future iterations
+     * on cancel).
+     *
+     * The loop is registered with the animator under a supervisor entry so
+     * `animator.cancel(handle)`, `animator.cancelKey(opts.cancelKey)`, and
+     * `animator.isActive(opts.cancelKey)` all work for it.
+     */
+    loop(factory: LoopFactory, opts?: LoopOptions): AnimationHandle;
+    /** Sugar over `loop` for the common case of looping a tween between two
+     *  values with optional direction handling (`restart` | `reverse` |
+     *  `alternate`). Registered with the animator like `loop`. */
+    tweenLoop<T>(opts: TweenLoopOptions<T>): AnimationHandle;
+    /**
+     * Stagger primitive: schedule a per-item animation, offset by `delay` ms
+     * per index (or a custom function of the index). Two forms:
+     *   - Factory form: pass `factory` directly, returns a composite
+     *     `AnimationHandle`.
+     *   - Builder form: omit `factory`, get a `StaggerBuilder` for fluent
+     *     `.each` / `.tween` / `.springPose` calls.
+     *
+     * The composite handle's `cancel` cancels the items still waiting AND the
+     * in-flight children. The delays run on the animator's clock, not the
+     * wall's: a pause or a time scale, on the handle, by `cancelKey` or on the
+     * whole animator, holds or stretches the waiting items along with the
+     * children, and a hidden tab holds both.
+     *
+     * The stagger is registered with the animator under a supervisor entry so
+     * `animator.cancel(handle)`, `animator.cancelKey(opts.cancelKey)`, and
+     * `animator.isActive(opts.cancelKey)` all work for it.
+     */
+    stagger<TItem>(items: readonly TItem[], delay: StaggerDelay): StaggerBuilder<TItem>;
+    stagger<TItem>(items: readonly TItem[], delay: StaggerDelay, factory: StaggerFactory<TItem>, opts?: StaggerOptions): AnimationHandle;
+    /**
+     * Keyframe timeline. Registered like any other animation, so its playhead
+     * responds to `pause`, `setTimeScale` and `cancelKey`. Sampled tracks are a
+     * pure function of the playhead; event tracks fire only on forward playback.
+     */
+    timeline(opts: TimelineOptions): TimelineHandle;
+    /** Per-node, per-channel color override registry, painted onto scene nodes
+     *  by `<SceneCanvas animator>` and read by `createPathLayer`. `cycleVertexColors`
+     *  stores an override in it; `tweenVertexColors`, `springVertexColors`, and
+     *  `staggerVertexColors` move its per-node targets, which only this animator
+     *  can move. Cleared automatically on animator unmount. */
+    colorOverrides: ColorOverrideRegistry;
+    /**
+     * Subscribe to a callback fired once per RAF frame while any animation is
+     * active. Returns an unsubscribe function. Used by consumers (typically
+     * `<SceneCanvas>`) that need to repaint when an animation's side-effect
+     * is read from a non-scene channel (e.g. `colorOverrides` consulted from
+     * a custom `drawOne`) — scene mutations naturally trigger a repaint, but
+     * `colorOverrides` writes do not.
+     *
+     * The callback fires AFTER the per-frame tick of each registered
+     * animation, so by the time it runs `colorOverrides.get(...)` returns
+     * the latest values. If no animations are active, no tick fires.
+     */
+    onTick(cb: () => void): () => void;
+    /**
+     * Keep the animator's RAF loop running until the returned cancel
+     * function is called. Use for animations whose effect is read on every
+     * frame but which don't have a natural progress state (e.g.
+     * `cycleVertexColors`, which expresses its current value as a function
+     * of `performance.now()` rather than as a tween from `from` to `to`).
+     * Without a keep-alive entry the loop would idle and `onTick` would
+     * stop firing even though the override is still installed.
+     */
+    keepAlive(): () => void;
+    /**
+     * Subscribe to the lifecycle of every animation this animator runs, the
+     * composites and timelines included. Returns an unsubscribe. Events arrive
+     * synchronously, as each thing happens — see {@link AnimatorEvent} for the
+     * order. With no listener attached nothing is built or delivered, so an
+     * unwatched animator pays nothing for this.
+     */
+    watch(listener: AnimatorListener): () => void;
+    /** What is running right now, in registration order: a fresh snapshot per
+     *  call, for a debug overlay to draw. */
+    live(): LiveAnimation[];
+}
+/** Which animator call started an animation. A loop, tween loop or stagger is
+ *  an entry of its own beside the children it runs; `keepAlive` holds the
+ *  frame loop open and animates nothing. */
+type AnimationKind = 'tween' | 'spring' | 'decay' | 'physics' | 'timeline' | 'loop' | 'tweenLoop' | 'stagger' | 'keepAlive' | 'hold';
+/** Who an {@link AnimatorEvent} is about. One object per registration, so the
+ *  same animation's events share it by identity. */
+interface AnimationInfo {
+    /** The id on the animation's handle. */
+    readonly id: number;
+    readonly kind: AnimationKind;
+    /** The animation's `cancelKey`. Pose helpers key by node, as `pose:<id>`. */
+    readonly key?: string;
+    /** The animation's `label` option. */
+    readonly label?: string;
+}
+/** One row of `animator.live()`. */
+interface LiveAnimation extends AnimationInfo {
+    /** Paused on its own handle. The animator-wide pause is `animator.isPaused()`. */
+    readonly paused: boolean;
+    /** Its own time scale; the animator's multiplies on top. */
+    readonly timeScale: number;
+    /** Virtual ms its clock has advanced since it started. */
+    readonly elapsed: number;
+    /** 0 to 1, for a tween or a timeline (the playhead over its duration).
+     *  Absent where there is no end to measure against: physics, composites. */
+    readonly progress?: number;
+}
+/**
+ * One thing happening to an animation, as `animator.watch` delivers it.
+ *
+ * - `start` — registered. A finished timeline that `seek` or `edit` revives
+ *   starts again, under the same id.
+ * - `end` — finished on its own. Delivered once every animation has ticked
+ *   that frame, in registration order.
+ * - `cancel` — stopped by its handle, `cancel`, `cancelKey` or `cancelAll`.
+ * - `interrupt` — stopped because `by` claimed its `cancelKey`. Delivered
+ *   before `by`'s `start`.
+ * - `error` — its tick threw (an `onTick`, `onDone` or interpolator), so it was
+ *   taken off the table, after the frame's other animations ticked. In place of
+ *   `cancel`, or after `end` when `onDone` threw. The error is also logged.
+ * - `lap` — a looping timeline wrapped; `lap` counts wraps since it started.
+ * - `fire` — an event on a timeline's event track was crossed, at any depth.
+ *   `path` indexes from the root timeline's `tracks()` down through each
+ *   nested timeline to the event track. Delivered after the event's own `fire`.
+ */
+type AnimatorEvent = {
+    readonly type: 'start' | 'end' | 'cancel';
+    readonly animation: AnimationInfo;
+} | {
+    readonly type: 'interrupt';
+    readonly animation: AnimationInfo;
+    readonly by: AnimationInfo;
+} | {
+    readonly type: 'error';
+    readonly animation: AnimationInfo;
+    readonly error: unknown;
+} | {
+    readonly type: 'lap';
+    readonly animation: AnimationInfo;
+    readonly lap: number;
+} | {
+    readonly type: 'fire';
+    readonly animation: AnimationInfo;
+    readonly track: EventTrack;
+    readonly path: readonly number[];
+    readonly event: TimelineEvent;
+    /** As the event's own `fire` is told: ms behind the frame it was crossed. */
+    readonly lateBy: number;
+};
+/** Receives what `animator.watch` delivers. */
+type AnimatorListener = (event: AnimatorEvent) => void;
+/** Options for `Animator.loop`. */
+interface LoopOptions {
+    /** Maximum number of iterations. Default Infinity. */
+    count?: number;
+    /** Invoked when the loop reaches `count` iterations naturally (not on cancel). */
+    onDone?: () => void;
+    /** Any new animation passed the same cancelKey cancels the prior one in flight.
+     *  Also enables `animator.cancelKey` / `animator.isActive(key)` for this loop. */
+    cancelKey?: string;
+    /** Names this loop in {@link AnimatorEvent}s and `animator.live()`. */
+    label?: string;
+}
+/** A stagger run's own options: the factory form's fourth argument, and part
+ *  of every fluent builder method's options. */
+interface StaggerOptions {
+    /** Cancel-key for the supervising registration. `animator.cancelKey(key)`
+     *  cancels the whole stagger; `animator.isActive(key)` returns true while
+     *  any timer or child is alive. */
+    cancelKey?: string;
+    /** Names this stagger in {@link AnimatorEvent}s and `animator.live()`. */
+    label?: string;
+}
+/** Produces one iteration of a loop. Must arrange for `next` to be called when
+ *  the animation it returns finishes, or the loop stalls after one pass. */
+type LoopFactory = (iteration: number, next: () => void) => AnimationHandle;
+/** Per-index delay schedule. Number ⇒ `index * delay` ms. Function ⇒ caller
+ *  decides the absolute delay for each index (e.g. `i => i * i * 30`). */
+type StaggerDelay = number | ((index: number) => number);
+/** Produces the animation for one staggered item. */
+type StaggerFactory<TItem> = (item: TItem, index: number) => AnimationHandle;
+/** A `T` value or a function that derives one from the per-item context. Used
+ *  by the fluent builder methods (`.tween`, `.springPose`) so each item can
+ *  vary an option (e.g. `to: (_item, i) => (i + 1) * 10`). */
+type StaggerPerItem<T, TItem> = T | ((item: TItem, index: number) => T);
+/** Options for the stagger builder's `.tween`: a tween per item, where
+ *  `from`, `to` and `ms` may each vary by item. `cancelKey` and `label` belong
+ *  to the stagger as a whole, as in {@link StaggerOptions}. */
+interface StaggerTweenOptions<T, TItem> extends StaggerOptions {
+    from: StaggerPerItem<T, TItem>;
+    to: StaggerPerItem<T, TItem>;
+    ms: StaggerPerItem<number, TItem>;
+    easing?: EasingSpec;
+    interpolate?: Interpolate<T>;
+    onTick: (value: T, item: TItem, index: number) => void;
+    onDone?: (item: TItem, index: number) => void;
+}
+/** Fluent form of `Animator.stagger`: pick what to run per item after the
+ *  items and the delay schedule are already fixed. */
+interface StaggerBuilder<TItem> {
+    /** Run an arbitrary per-item factory. */
+    each(factory: StaggerFactory<TItem>, opts?: StaggerOptions): AnimationHandle;
+    /** Sugar: per-item `animator.tween` with per-item-varying options. */
+    tween<T>(opts: StaggerTweenOptions<T, TItem>): AnimationHandle;
+}
+/** Options for `Animator.tweenLoop` — a tween's options plus how each
+ *  iteration relates to the last. */
+interface TweenLoopOptions<T> {
+    from: T;
+    to: T;
+    ms: number;
+    easing?: EasingSpec;
+    /** `restart` (default): from→to every iteration.
+     *  `reverse`: to→from every iteration.
+     *  `alternate`: even iterations from→to, odd iterations to→from. */
+    direction?: 'restart' | 'reverse' | 'alternate';
+    count?: number;
+    interpolate?: Interpolate<T>;
+    onTick: (value: T) => void;
+    onDone?: () => void;
+    cancelKey?: string;
+    /** Names this animation in {@link AnimatorEvent}s and `animator.live()`. */
+    label?: string;
+}
+
+/** Create the animator for a canvas. One rAF loop drives every animation it
+ *  owns, and everything still running is canceled on unmount. */
+declare function useAnimator(opts?: UseAnimatorOptions): Animator;
+
+/** What {@link createTargetTable} takes. */
+interface TargetTableOptions {
+    /** How many numbers a row holds. */
+    axes: number;
+    /** Rows to make room for at first. The table grows past it. Default 64. */
+    capacity?: number;
+    /** Called after `row` is committed: by `set`, by an animation starting on it, and by one
+     *  canceled on it. */
+    set?(row: number): void;
+    /** Called once a frame, after the animator has filled `shown` for the rows it is moving. */
+    show?(): void;
+}
+/**
+ * Many like values an animator can move, kept as rows of numbers in flat arrays: for thousands
+ * of particles, dots, or vertex colors, where a `Target` apiece costs a read apiece. Each row
+ * is a target (`target(row)`), so it tweens, springs, coasts, and holds like any other, and
+ * every row's value on screen is in `shown` after each frame, with no call per row.
+ */
+interface TargetTable {
+    readonly axes: number;
+    /** How many rows are in use. */
+    readonly size: number;
+    /** Every row's committed value, row `r` at `r * axes`. A new array once the table grows, so
+     *  read it from the table each time. Write a row through `set`. */
+    readonly committed: Float64Array;
+    /** Every row's value on screen, laid out as `committed`: current after each frame of the
+     *  animator moving the rows, and whenever it is read between frames. A new array once the
+     *  table grows. */
+    readonly shown: Float64Array;
+    /** Adds a row at `value` and answers its index, which a removed row's index is reused for. */
+    add(value: ArrayLike<number>): number;
+    /** Stops whatever is moving `row` and frees it. Its target is dead from here: a row added
+     *  later may take the index, and gets a target of its own. */
+    remove(row: number): void;
+    /** Commits `value` to `row`. A row that is moving keeps what its animations have left on top. */
+    set(row: number, value: ArrayLike<number>): void;
+    /** Row `row` as a target, the same one on every call. */
+    target(row: number): Target<number[]>;
+}
+/** Make a {@link TargetTable} whose rows each hold `axes` numbers. */
+declare function createTargetTable(opts: TargetTableOptions): TargetTable;
+
+/** How a value maps to the flat numbers blits moves, and back. */
+interface Axes<T> {
+    count: number;
+    /** Equal for two values exactly when their axes line up one for one. */
+    shape: string;
+    to(v: T): number[];
+    /** The value whose `count` axes start at `at` in `a`. */
+    from(a: ArrayLike<number>, at?: number): T;
+    /** `v` with `delta` added axis by axis. */
+    add(v: T, delta: ArrayLike<number>): T;
+    /** Puts `v`'s axes into `out` from `at`. */
+    write(v: T, out: Float64Array | Float32Array | number[], at: number): void;
+}
+/** The axes of `sample`'s shape: a number, a plain array of numbers, or a plain object whose
+ *  fields are all numbers. Null for any other shape, which blits cannot move. */
+declare function axesOf<T>(sample: T): Axes<T> | null;
+
+/** Most a slewed value may change per second, in its own units, in each
+ *  direction. A direction left out is unlimited: the value jumps to a target
+ *  on that side. `0` holds the value where it is. */
+interface SlewRates {
+    rise?: number;
+    fall?: number;
+}
+/**
+ * One step of a slew limiter: `value` moved toward `target` by at most the
+ * rate for that direction times `dt` seconds, landing on `target` rather than
+ * passing it. A fast `rise` with a slow `fall` is an attack/release envelope.
+ */
+declare function slewToward(value: number, target: number, dt: number, rates: SlewRates): number;
+/** A value that follows `target` at limited rates. Both fields are writable:
+ *  set `target` to steer it, or write `value` to jump it and let it slew on
+ *  from there. Nothing moves until `step` is called. */
+interface Slew {
+    value: number;
+    target: number;
+    /** Advance `dt` seconds and return the new value. */
+    step(dt: number): number;
+}
+/** A stateful {@link slewToward}. `target` defaults to `value`, so a new slew
+ *  is at rest. */
+declare function createSlew(options?: SlewRates & {
+    value?: number;
+    target?: number;
+}): Slew;
+
+/**
+ * Color interpolator: receives two flat RGBA float arrays (values in
+ * 0..1, the renderer's color space — same shape as
+ * `stroke.vertexColors`) and a normalized progress `t` in 0..1.
+ * Returns the same-length blended array, also in 0..1 floats. Override
+ * the default per-channel lerp via `TweenVertexColorsOptions.interpolate`
+ * when a custom color-space or shaping is needed.
+ */
+type ColorInterpolate = (from: readonly number[], to: readonly number[], t: number) => number[];
+
+/** Options for `tweenVertexColors`. */
+interface TweenVertexColorsOptions {
+    id: string;
+    channel: VertexColorChannel;
+    /** Per-anchor RGBA, flat, in 0..1 floats (matches the renderer's
+     *  `stroke.vertexColors` / `PathDrawCommand.vertexColors` color space).
+     *  Length must equal `from.length`. */
+    to: readonly number[];
+    /** Per-anchor RGBA, flat, in 0..1 floats. Length must equal `to.length`
+     *  and be a positive multiple of 4. */
+    from: readonly number[];
+    ms: number;
+    easing?: EasingSpec;
+    interpolation?: ColorSpace;
+    interpolate?: ColorInterpolate;
+    onDone?: () => void;
+}
+/**
+ * Animate one node's per-anchor colors from `from` to `to` over `ms`.
+ *
+ * It moves the node's color target (`animator.colorOverrides.target`) rather
+ * than writing the scene, so nothing is recorded in history and the node's own
+ * data is untouched. Another tween or stagger on the same node and channel adds
+ * to this one; a spring interrupts it. What it painted is dropped when the last
+ * animation on the node and channel finishes, and held where it was if canceled
+ * until `animator.colorOverrides.clear`.
+ */
+declare function tweenVertexColors(animator: Animator, opts: TweenVertexColorsOptions): AnimationHandle;
+/** Options for `springVertexColors`. */
+interface SpringVertexColorsOptions {
+    id: string;
+    channel: VertexColorChannel;
+    /** Per-anchor RGBA in 0..1 floats. See `TweenVertexColorsOptions.to`. */
+    to: readonly number[];
+    /** Per-anchor RGBA in 0..1 floats. See `TweenVertexColorsOptions.from`. */
+    from: readonly number[];
+    preset?: SpringPresetName;
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    onDone?: () => void;
+}
+/**
+ * `tweenVertexColors` driven by a spring instead of a duration. Each number
+ * springs on its own, so an underdamped spring overshoots `to` and the path is
+ * a straight line in RGB.
+ *
+ * It interrupts whatever is animating the node and channel, and starts at the
+ * velocity of the one it interrupts, so retargeting mid-flight does not stall.
+ */
+declare function springVertexColors(animator: Animator, opts: SpringVertexColorsOptions): AnimationHandle;
+/** Options for `staggerVertexColors`. `origin` picks which anchor the wave
+ *  starts from and `perAnchorDelay` how far behind each successive anchor
+ *  runs. */
+interface StaggerVertexColorsOptions {
+    id: string;
+    channel: VertexColorChannel;
+    /** Per-anchor RGBA in 0..1 floats. See `TweenVertexColorsOptions.to`. */
+    to: readonly number[];
+    /** Per-anchor RGBA in 0..1 floats. See `TweenVertexColorsOptions.from`. */
+    from: readonly number[];
+    anchorMs: number;
+    perAnchorDelay: number;
+    origin?: 'first' | 'last' | number;
+    easing?: EasingSpec;
+    interpolation?: ColorSpace;
+    interpolate?: ColorInterpolate;
+    onDone?: () => void;
+}
+/** Run the same color change across a node's anchors as a wave, each anchor
+ *  starting later than the one before it. It moves the same target as
+ *  `tweenVertexColors`, and adds to other animations the same way. */
+declare function staggerVertexColors(animator: Animator, opts: StaggerVertexColorsOptions): AnimationHandle;
+
+/** Options for `cycleVertexColors`. */
+interface CycleVertexColorsOptions {
+    id: string;
+    channel: VertexColorChannel;
+    msPerCycle: number;
+    direction?: 1 | -1;
+    easing?: EasingSpec;
+    interpolation?: ColorSpace;
+    /** Custom interpolator. Receives two RGBA arrays in 0..1 floats and a
+     *  progress `t` in 0..1; returns the blended array in 0..1 floats. */
+    interpolate?: ColorInterpolate;
+}
+/** Removes an installed color cycle. Unlike the other color helpers this is
+ *  not an `AnimationHandle`, because a cycle has no progress to pause or
+ *  scale — it only ends. */
+interface CycleHandle {
+    cancel(): void;
+}
+/** Register a function override that phase-rotates the base color array
+ *  along the path index. Returns a handle whose `cancel()` removes the
+ *  override.
+ *
+ *  The override computes its value purely from `performance.now()`, so
+ *  there's no per-frame progress to register with the animator's tick
+ *  loop. To keep the loop alive (so `<SceneCanvas animator>`'s onTick
+ *  subscription continues firing redraws while the cycle is installed),
+ *  cycleVertexColors holds an `animator.keepAlive()` entry for the
+ *  lifetime of the cycle; `cancel()` releases it. */
+declare function cycleVertexColors(animator: Animator, opts: CycleVertexColorsOptions): CycleHandle;
+
+/** Build an n-anchor rainbow RGBA array sweeping the hue wheel. The
+ *  output is suitable to pass directly into `stroke.vertexColors`,
+ *  `tweenVertexColors({ from: rainbowVertexColors(n) })`, or any
+ *  other API that wants per-anchor color floats. */
+declare function rainbowVertexColors(n: number, opts?: {
+    saturation?: number;
+    lightness?: number;
+    alpha?: number;
+}): number[];
+/** Build an n-anchor solid RGBA array. Shorthand for
+ *  `[r, g, b, a, r, g, b, a, …]` — the array a `tweenVertexColors`
+ *  `to`-target typically needs. */
+declare function solidVertexColors(n: number, r: number, g: number, b: number, a?: number): number[];
+
+/**
+ * Sample a track at `t`. Pure: no state, no side effects, safe to call for any
+ * `t` in any order — which is what makes scrubbing free.
+ *
+ * `segmentCache` holds what sampling builds from the keys: the track's blits
+ * patch and its `interpolator` factories. Handed another track or a replaced
+ * `keys` array, it rebuilds; a key edited in place needs the cache dropped,
+ * which `createTimeline` does on `edit`. With no cache, every call builds afresh.
+ */
+declare function sampleTrack<T>(track: SampledTrack<T>, t: number, segmentCache?: Map<number, (u: number) => T>): T | undefined;
+
+/** A value a clip can hold: what `JSON.stringify` writes and `JSON.parse` reads back. An
+ *  object's `undefined` members are left out, as JSON leaves them. */
+type ClipValue = number | string | boolean | null | ClipValue[] | {
+    [key: string]: ClipValue | undefined;
+};
+/** A keyframe as data. Its easing is a built-in's name or bezier control points. */
+interface ClipKey {
+    t: number;
+    value: ClipValue;
+    easing?: EasingName | BezierEasing;
+}
+/** A `SampledTrack` as data: what it moves and how it interpolates are names. */
+interface ClipSampledTrack {
+    kind: 'sampled';
+    label?: string;
+    /** Resolved by `ClipBinder.target`. A track with none is sampled and moves nothing. */
+    target?: string;
+    keys: ClipKey[];
+    /** Resolved from `ClipBinder.interpolate`. Without one the track is sampled in its
+     *  target's axes, or field by field. */
+    interpolate?: string;
+    weight?: number;
+    axes?: number[];
+}
+/** An `EventTrack` as data: each event is a name and what to carry with it. */
+interface ClipEventTrack {
+    kind: 'event';
+    label?: string;
+    events: {
+        t: number;
+        name: string;
+        data?: ClipValue;
+    }[];
+}
+/** A `TimelineTrack` as data. */
+interface ClipTimelineTrack {
+    kind: 'timeline';
+    label?: string;
+    at: number;
+    timeline: ClipTimeline;
+}
+/** Any track a clip can hold. */
+type ClipTrack = ClipSampledTrack | ClipEventTrack | ClipTimelineTrack;
+/** A `NestedTimeline` as data. */
+interface ClipTimeline {
+    tracks: ClipTrack[];
+    duration?: number;
+}
+/** A timeline as data: what `JSON.stringify` can write, `bindClip` can play, and `toClip`
+ *  can read back off a live timeline. */
+interface Clip extends ClipTimeline {
+    version: 1;
+}
+/** What turns the names in a clip into the live things a timeline plays. */
+interface ClipBinder {
+    /** The target a sampled track names. */
+    target?(name: string): Target<any> | undefined;
+    /** Interpolations by name. */
+    interpolate?: Readonly<Record<string, Interpolate<any>>>;
+    /** What an event does: its `fire`, its `book`, or both. */
+    event?(name: string, data: ClipValue | undefined): Pick<TimelineEvent, 'fire' | 'book'> | undefined;
+}
+/**
+ * The live timeline a clip describes, for `animator.timeline`: each sampled track given the
+ * target and interpolation it names, each event what the binder says it does. The tracks
+ * keep those names, so `toClip` can write them back after an editor has changed them.
+ * Throws on a name the binder does not resolve.
+ */
+declare function bindClip(clip: Clip, binder: ClipBinder): NestedTimeline;
+/**
+ * A live timeline as a clip: `{ tracks, duration }` as `animator.timeline` takes them, or
+ * `{ tracks: handle.tracks() }` off a running one. Each track is written by the names it
+ * carries (`targetName`, `interpolateName`, an event's `name`), which `bindClip` sets and a
+ * track written by hand can set too. Throws, naming the track, on anything a clip cannot
+ * hold: a function with no name, an `onTick`, or a value JSON would not read back.
+ */
+declare function toClip(timeline: NestedTimeline): Clip;
+
+/** A joint's local transform. Deliberately NOT the scene's generic `TPose`:
+ *  `TPose` is consumer-defined and may be a bare AABB with no rotation term,
+ *  which a joint chain cannot compose through. */
+interface JointTransform {
+    x: number;
+    y: number;
+    /** Radians. */
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+}
+/** One joint of a `Skeleton`. */
+interface Joint {
+    name: string;
+    /** Parent joint name, or null for a root. */
+    parent: string | null;
+    /** Local transform at rest. */
+    bind: JointTransform;
+}
+/** Joints in topological order: every joint appears after its parent. */
+interface Skeleton {
+    joints: Joint[];
+}
+/** Local deltas from the bind pose, keyed by joint name. Absent joints and
+ *  absent fields mean "no change from bind". */
+type Pose = Record<string, Partial<JointTransform>>;
+/** The transform that changes nothing: origin, no rotation, unit scale. */
+declare const IDENTITY_JOINT: JointTransform;
+
+/**
+ * `pose` reflected across the rig's y axis, as deltas against the same
+ * skeleton — so the mirrored pose still blends, samples and resolves like any
+ * other.
+ *
+ * Reflecting a joint chain is conjugation: every local transform `T·R·S`
+ * becomes `F·T·R·S·F` with `F` the flip, which is again a plain transform
+ * with `x` and `rotation` negated. Every resolved joint is then exactly the
+ * original's reflection, which is how a rig faces the other way without a
+ * negative scale anywhere — a scene pose such as `RectPose` has no term to
+ * carry one. The negation applies to bind plus delta, so the delta for a
+ * joint the pose leaves at its bind is nonzero whenever the bind is.
+ *
+ * Applying it twice gives the original pose back.
+ */
+declare function mirrorPose(skeleton: Skeleton, pose: Pose): Pose;
+
+/**
+ * Resolve every joint's world transform by walking the skeleton once and
+ * composing each joint onto its already-resolved parent.
+ *
+ * `skeleton.joints` must be in topological order — a joint whose parent has not
+ * been resolved yet throws rather than silently resolving against identity,
+ * because that failure is otherwise invisible until a limb renders in the wrong
+ * place.
+ */
+declare function resolveSkeleton(skeleton: Skeleton, pose: Pose): Map<string, GlMat3>;
+
+/**
+ * The axes of `skeletonAxes(skeleton)` that belong to `joints`, for a hold or a track over part
+ * of a rig: `animator.hold({ target: rig.target, value: pose, axes: jointAxes(skeleton, arm) })`.
+ */
+declare function jointAxes(skeleton: Skeleton, joints: readonly string[]): number[];
+/**
+ * How a {@link Pose} of `skeleton` maps to the numbers an animation moves: five per joint in
+ * skeleton order (`x`, `y`, `rotation`, `scaleX`, `scaleY`), every rotation an angle, so a pose
+ * blends the short way round. A joint or field the pose leaves out reads as its identity, and a
+ * pose read back names every joint in full. Pass it as `axes` to `createTarget` for a pose target
+ * of your own; a bound rig's is `Rig.target`.
+ */
+declare function skeletonAxes(skeleton: Skeleton): TargetAxes<Pose>;
+
+/** A point in the skeleton's space — the space `resolveSkeleton` resolves into. */
+interface IkPoint {
+    x: number;
+    y: number;
+}
+/** Bounds on a joint's rotation delta from its bind, in radians, with
+ *  `-PI <= min <= max <= PI`. */
+interface IkLimit {
+    min: number;
+    max: number;
+}
+/** Options for {@link solveIk}. */
+interface SolveIkOptions {
+    /** The joints the solver may rotate, root first, each the parent of the next. */
+    joints: readonly string[];
+    /** The end effector, in the last joint's local frame — the forearm's length
+     *  along its +x for an arm, or a hand joint's bind offset. */
+    tip: IkPoint;
+    /** Where the tip should go, in skeleton space. A rig posed with a `root`
+     *  wants the target carried back through that root's inverse first. */
+    target: IkPoint;
+    /** Per-joint limits, keyed by joint name. A joint without one turns freely. */
+    limits?: Readonly<Record<string, IkLimit>>;
+    /** Two-joint chains only: the middle joint bends toward this point, in
+     *  skeleton space. Without it the chain keeps the bend the input pose has. */
+    pole?: IkPoint;
+    /** Most CCD sweeps to run. Default 32. */
+    iterations?: number;
+    /** Tip-to-target distance that counts as reached, in skeleton units.
+     *  Default 0.01. */
+    tolerance?: number;
+}
+/** What {@link solveIk} returns. */
+interface IkResult {
+    /** The input pose with each chain joint's rotation replaced. */
+    pose: Pose;
+    /** Tip-to-target distance the solve ended at. */
+    distance: number;
+    /** Whether `distance` is within the tolerance. False for a target out of
+     *  reach, which leaves the chain pointing straight at it. */
+    reached: boolean;
+    /** CCD sweeps run; 0 when the two-joint solution or the straight-line
+     *  answer for an unreachable target settled it. */
+    iterations: number;
+}
+/**
+ * Rotate a joint chain so its tip reaches `target`, returning the result as an
+ * ordinary {@link Pose} — so it keys a `SampledTrack<Pose>`, drives a rig through
+ * `Rig.pose`, and is held on a rig like any other. Weighting the IK against an
+ * animated pose is `animator.hold({ target: rig.target, value: solved, weight: w })`
+ * beside the clip at weight `1 - w`; with `axes: jointAxes(skeleton, joints)` on both, the
+ * rest of the body is left to whatever else holds it.
+ *
+ * The solver is cyclic coordinate descent: each step turns one joint so the
+ * tip lies on the ray from that joint to the target. A joint's rotation is the
+ * one term the rig lets it change, and a CCD step is exactly a change to it, so
+ * limits clamp the value the pose stores and nothing has to be converted back
+ * from positions. Each step is solved in the joint's parent frame, which makes
+ * it exact under any parent transform the skeleton composes, mirrors included.
+ *
+ * A two-joint chain is solved analytically first: of the two bends that reach
+ * the target it takes the one on `pole`'s side, or the input pose's side, and
+ * falls back to the other bend and then to CCD when limits refuse it. A target
+ * beyond the chain's reach straightens the chain toward it.
+ */
+declare function solveIk(skeleton: Skeleton, pose: Pose, options: SolveIkOptions): IkResult;
+
+/**
+ * How much each point of a path follows each joint: one array per joint name, indexed by
+ * point. Point `i` is the `i`-th coordinate pair of a polygon path's `coords`, so anchors and
+ * curve handles are weighted alike; a rect's points are its corners, clockwise from the top
+ * left. A joint left out, and an index past an array's end, weigh nothing. Weights need not
+ * sum to 1: they are normalized per point as they are applied.
+ */
+type Skin = Readonly<Record<string, readonly number[]>>;
+/**
+ * Each joint's motion since the bind pose, in world space: `world * inverse(restWorld)`.
+ * `world` is what `resolveSkeleton` or `Rig.world()` answers.
+ */
+declare function motionsFromRest(skeleton: Skeleton, world: ReadonlyMap<string, GlMat3>): Map<string, GlMat3>;
+/** The path whose points a skin indexes: a rect as its four corners. */
+declare function skinnable(path: Path): PolygonPath;
+/**
+ * Bend `path` by linear blend skinning: each point goes where its joints' motions since the
+ * bind pose would carry it, averaged by weight. `path` is the shape at the bind pose, in the
+ * space `motions` are in; it is not modified. A point no joint weighs stays where it is.
+ */
+declare function skinPath(path: Path, skin: Skin, motions: ReadonlyMap<string, GlMat3>): PolygonPath;
+
+/** Options for `autoSkin`. */
+interface AutoSkinOptions {
+    /** How fast a bone's pull falls off with distance: a weight is `1 / distance ** power`.
+     *  Higher keeps the bend closer to the joint. Default 4. */
+    power?: number;
+    /** The most joints a point follows; the nearest are kept. Default 2. */
+    max?: number;
+}
+/**
+ * Weights for `path` from how far each of its points is from each bone of `skeleton` at the
+ * bind pose. `path` is in the skeleton's space. A point on a bone follows that bone alone.
+ */
+declare function autoSkin(path: Path, skeleton: Skeleton, options?: AutoSkinOptions): Skin;
+
+/** Where each joint rests, in the skeleton's space and in its order. */
+declare function jointPositions(skeleton: Skeleton): Map<string, {
+    x: number;
+    y: number;
+}>;
+/** The joint resting nearest `(x, y)` and no further than `reach` from it, or `null`. */
+declare function jointAt(skeleton: Skeleton, x: number, y: number, reach: number): string | null;
+/** `skeleton` with `name` resting at `(x, y)`. The joints under it keep their offsets from it,
+ *  so they move along. */
+declare function moveJoint(skeleton: Skeleton, name: string, x: number, y: number): Skeleton;
+/** `skeleton` with a new joint resting at `(x, y)` under `parent`, or as a root for `null`.
+ *  Without a `name` it gets the first of `joint`, `joint2`, … not in use. */
+declare function addJoint(skeleton: Skeleton, parent: string | null, x: number, y: number, name?: string): {
+    skeleton: Skeleton;
+    name: string;
+};
+/** `skeleton` without `name` and the joints under it, and the names that went. */
+declare function removeJoint(skeleton: Skeleton, name: string): {
+    skeleton: Skeleton;
+    removed: string[];
+};
+/** `skin` without the weights of `joints`; the same object when it weighs none of them. */
+declare function dropSkinJoints(skin: Skin, joints: readonly string[]): Skin;
+
+/**
+ * `skin` with `joint`'s weight set on some points: `weights` maps a point's index to the new
+ * weight, clamped to 0..1. On each of those points the other joints are scaled to share what
+ * is left, so the point still sums to 1; a point no other joint weighs goes wholly to `joint`,
+ * as it would when the skin is applied. Every array comes back `count` long, and a joint left
+ * weighing nothing is dropped.
+ */
+declare function setWeights(skin: Skin, count: number, joint: string, weights: ReadonlyMap<number, number>): Skin;
+/**
+ * What a round brush at `(x, y)` does to one joint's weights: for each point of `coords`
+ * within `radius`, a weight falling off linearly from the center. `'add'` raises a point
+ * toward 1 and `'remove'` lowers it toward 0; neither moves a point the other way. Answers
+ * only the points that change, by index, for {@link setWeights}.
+ */
+declare function brushWeights(coords: ArrayLike<number>, x: number, y: number, radius: number, current: readonly number[] | undefined, mode: 'add' | 'remove'): Map<number, number>;
+
+export { type AnimationHandle, type AnimationInfo, type AnimationKind, type Animator, type AnimatorEvent, type AnimatorListener, type AutoSkinOptions, type Axes, type AxisBuffer, type Clip, type ClipBinder, type ClipEventTrack, type ClipKey, type ClipSampledTrack, type ClipTimeline, type ClipTimelineTrack, type ClipTrack, type ClipValue, type ColorInterpolate, type ColorOverride, type ColorOverrideFn, ColorOverrideRegistry, type CycleHandle, type CycleVertexColorsOptions, type DecayOptions, type EventBooking, type EventBookingHandle, type EventTrack, type HoldHandle, type HoldOptions, IDENTITY_JOINT, type IkLimit, type IkPoint, type IkResult, type Interpolate, type InterpolatorFactory, type Joint, type JointTransform, type Keyframe, type LiveAnimation, type LoopFactory, type LoopOptions, type NestedTimeline, type PhysicsHandle, type PhysicsOptions, type Pose, type SampledTrack, type Skeleton, type Skin, type Slew, type SlewRates, type SolveIkOptions, type SpringOptions, type SpringVertexColorsOptions, type StaggerBuilder, type StaggerDelay, type StaggerFactory, type StaggerOptions, type StaggerPerItem, type StaggerTweenOptions, type StaggerVertexColorsOptions, type Target, type TargetAxes, type TargetDecayOptions, type TargetOptions, type TargetPhysicsOptions, type TargetSpringOptions, type TargetTable, type TargetTableOptions, type TargetTweenOptions, type TimelineClock, type TimelineEvent, type TimelineHandle, type TimelineOptions, type TimelineTrack, type Track, type TweenLoopOptions, type TweenOptions, type TweenVertexColorsOptions, type UseAnimatorOptions, type VertexColorChannel, addJoint, autoSkin, axesOf, bindClip, brushWeights, createSlew, createTarget, createTargetTable, cycleVertexColors, dropSkinJoints, jointAt, jointAxes, jointPositions, mirrorPose, motionsFromRest, moveJoint, rainbowVertexColors, removeJoint, resolveSkeleton, sampleTrack, setWeights, skeletonAxes, skinPath, skinnable, slewToward, solidVertexColors, solveIk, springVertexColors, staggerVertexColors, toClip, tweenVertexColors, useAnimator };