@weasel-js/animator 1.9.4 → 1.10.0

package/README.md

@@ -23,14 +23,32 @@ animator.spring({ target, to: 40 }); // bends the motion; neither cancels the ot
 
 | Export | What it is |
 |---|---|
-| `useAnimator()` | The animator: `tween`, `spring`, `physics`, `decay`, `hold`, `loop`, `stagger`, `timeline`, and `watch`. The frame loop stops while its host is unseen. |
-| `createTarget(opts)` | One value an animator moves. Animations on a target add, so a second one bends the first. |
+| `useAnimator()` | The animator: `tween`, `spring`, `physics`, `decay`, `hold`, `loop`, `stagger`, `timeline`, `watch`, and `live`, with `pause`, `resume`, and `setTimeScale` over everything it runs. The frame loop stops while its host is unseen. |
+| `createTarget(opts)` | One value an animator moves. Animations on a target add, so a second one bends the first. `target.axisIndexes(['y'])` answers where the axes it names sit among the target's numbers. |
 | `createTargetTable(opts)` | Many like values as rows of flat arrays, shown in one pass. |
 | `sampleTrack`, the `Track` types | Keyframe tracks for `animator.timeline`. |
 | `resolveSkeleton`, `skeletonAxes`, `solveIk`, `mirrorPose` | Skeleton math: joints to matrices, a skeleton pose as a target's axes, two-bone IK. |
 | `tweenVertexColors` and its siblings, `ColorOverrideRegistry` | Per-vertex color animation, and the table a renderer reads the colors from. |
 | `createSlew`, `slewToward` | A value that follows another at a bounded rate. |
 
+A hold or a timeline track over part of a target names the axes it holds, by the value's own
+fields or by index. A rig's pose target names its axes `<joint>.<field>`, so a joint's name
+reaches all five of its axes:
+
+```tsx
+animator.hold({ target, value: { x: 0, y: 120 }, axes: ['y'] });
+animator.hold({ target: rig.target, value: pose, axes: ['armL', 'foreL.rotation'] });
+```
+
+`animator.stagger(items, delay)` answers a builder. Its `.tween` and `.spring` move the items
+themselves where they are targets, a `target` named per item otherwise, and hand values to
+`onTick` with neither; `.each` runs any factory.
+
+```tsx
+animator.stagger(targets, 80).spring({ to: (target) => ({ ...target.committed(), y: 200 }), preset: 'wobbly' });
+animator.stagger(rows, 80).tween({ target: (row) => row.target, to: 1, ms: 300 });
+```
+
 Moving a scene node's pose is `@weasel-js/core`'s half: `tweenPose`, `springPose`,
 `momentum`, `bindRig`, and `useAnimatedReflow` drive this animator against a scene. How
 animations combine on a target is in

package/dist/index.d.ts

@@ -2,6 +2,17 @@ import { EasingSpec, SpringPresetName, EasingName, BezierEasing, GlMat3, Path, P
 export { BezierEasing, EasingFn, EasingSpec, SpringPreset, SpringPresetName } from '@weasel-js/geom';
 import { ColorSpace } from '@weasel-js/paint';
 
+/**
+ * What an axis of a `T` goes by: a field of a plain object, or a path into a nested one, as a
+ * pose's `knee` and `knee.rotation` are. `never` for a number or an array, whose axes have
+ * indexes only.
+ */
+type AxisName<T> = T extends number | readonly unknown[] ? never : T extends object ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends number ? K : K | `${K}.${string}`;
+}[keyof T & string] : string;
+/** One of a target's axes: its index, or its name where the target's axes have names. */
+type AxisRef<T = unknown> = number | AxisName<T>;
+
 /** How a target's value maps to the flat numbers an animation moves, and back. */
 interface TargetAxes<T> {
     count: number;
@@ -10,6 +21,9 @@ interface TargetAxes<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[];
+    /** A name for each axis, in the order `to` answers them, for `axes` options to go by. A dot
+     *  makes a path: `knee.rotation` is also reached as `knee`, with the joint's other axes. */
+    names?: readonly string[];
     /** 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;
@@ -57,6 +71,12 @@ interface Target<T> {
     readonly axisCount: number;
     /** How its value maps to numbers. */
     readonly axes: TargetAxes<T>;
+    /**
+     * The indexes of the axes `axes` names, in the order named: what a hold's or a track's `axes`
+     * resolves through. A name is one of `axes.names`, or a path over several of them; an index
+     * passes through. Throws on a name or an index the target has no axis for.
+     */
+    axisIndexes(axes: readonly AxisRef<T>[]): number[];
     /** 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. */
@@ -173,8 +193,11 @@ interface SampledTrack<T> {
     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[];
+    /** What a function `weight` goes by in a clip, as `targetName` is for `target`. */
+    weightName?: string;
+    /** The axes of the target the track holds, by name or by index, as `HoldOptions.axes`.
+     *  Default: every axis. A clip carries them as they are written here. */
+    axes?: readonly AxisRef<T>[];
 }
 /** A clock that events are booked against, reading in ms. An `AudioEngine`
  *  from `@weasel-js/audio` is one. */
@@ -349,18 +372,21 @@ interface TargetPhysicsOptions<T> extends Omit<TargetSpringOptions<T>, 'to'> {
 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. */
+    /** What to show in place of the committed value: a value, or a function read each frame.
+     *  A value is read as the hold starts and again at `touch()`, and costs a frame nothing. */
     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`.
+     * The axes of the target it holds, each by name or by index: a plain object's fields
+     * (`['y']`), a rig's joints (`['armL', 'foreL']`) or one of a joint's own
+     * (`['armL.rotation']`), as `target.axisIndexes` resolves them when the hold starts. The
+     * rest are left to the target's other holds and its committed value, and a release commits
+     * only these. Default: every axis.
      */
-    axes?: readonly number[];
+    axes?: readonly AxisRef<T>[];
     /** Any new animation passed the same cancelKey cancels this one. */
     cancelKey?: string;
     /** Names this hold in {@link AnimatorEvent}s and `animator.live()`. */
@@ -372,7 +398,8 @@ interface HoldOptions<T> {
  *  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. */
+     *  now rather than at the next frame the animator happens to run. A `value` given as an
+     *  object and then written in place shows only once this is called. */
     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
@@ -392,14 +419,112 @@ interface TargetDecayOptions<T> extends OnTarget<T> {
     threshold?: number;
 }
 
+/** 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;
+}
+/** 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`, `.spring`) 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` in its `onTick` form: 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 {
+    /** Absent: this form hands values to `onTick`. {@link StaggerTargetTweenOptions} moves targets. */
+    target?: undefined;
+    from: StaggerPerItem<T, TItem>;
+    to: StaggerPerItem<T, TItem>;
+    ms: StaggerPerItem<number, TItem>;
+    easing?: EasingSpec;
+    interpolate?: Interpolate<T>;
+    interpolator?: InterpolatorFactory<T>;
+    onTick: (value: T, item: TItem, index: number) => void;
+    onDone?: (item: TItem, index: number) => void;
+}
+/** Options for the stagger builder's `.spring` in its `onTick` form: a spring per item, where
+ *  `from`, `to` and `velocity` may each vary by item. */
+interface StaggerSpringOptions<T, TItem> extends StaggerOptions, Pick<SpringOptions<T>, 'preset' | 'stiffness' | 'damping' | 'mass' | 'interpolate' | 'add' | 'subtract' | 'scale' | 'magnitude' | 'restThreshold'> {
+    /** Absent: this form hands values to `onTick`. {@link StaggerTargetSpringOptions} moves targets. */
+    target?: undefined;
+    from: StaggerPerItem<T, TItem>;
+    to: StaggerPerItem<T, TItem>;
+    velocity?: StaggerPerItem<T, TItem>;
+    onTick: (value: T, item: TItem, index: number) => void;
+    onDone?: (item: TItem, index: number) => void;
+}
+/** What the stagger builder's methods share where each item's animation moves a {@link Target}. */
+interface StaggerOnTarget<T, TItem> extends StaggerOptions {
+    /** The target an item's animation moves: one for them all, or a function of the item.
+     *  Default: the item itself, where the items are targets. */
+    target?: StaggerPerItem<Target<T>, TItem>;
+    /** Told an item's animation's own value each frame, as `TargetTweenOptions.onTick` is. */
+    onTick?: (value: T, item: TItem, index: number) => void;
+    onDone?: (item: TItem, index: number) => void;
+}
+/** Options for the stagger builder's `.tween` moving targets: `animator.tween`'s target form
+ *  per item, where `to`, `from` and `ms` may each vary by item. The tweens share no
+ *  `cancelKey`, so each adds to whatever else is moving its target. */
+interface StaggerTargetTweenOptions<T, TItem> extends StaggerOnTarget<T, TItem>, Pick<TargetTweenOptions<T>, 'easing' | 'interpolate' | 'interpolator'> {
+    to: StaggerPerItem<T, TItem>;
+    from?: StaggerPerItem<T, TItem>;
+    ms: StaggerPerItem<number, TItem>;
+}
+/** Options for the stagger builder's `.spring` moving targets: `animator.spring`'s target
+ *  form per item, where `to`, `from` and `velocity` may each vary by item. */
+interface StaggerTargetSpringOptions<T, TItem> extends StaggerOnTarget<T, TItem>, Pick<TargetSpringOptions<T>, 'preset' | 'stiffness' | 'damping' | 'mass' | 'restThreshold'> {
+    to: StaggerPerItem<T, TItem>;
+    from?: StaggerPerItem<T, TItem>;
+    velocity?: StaggerPerItem<T, TItem>;
+}
+/** `.tween`'s options where the items are targets, each moved by its own tween. No options
+ *  fit where they are not. */
+type StaggerItemTweenOptions<TItem> = TItem extends Target<infer T> ? StaggerTargetTweenOptions<T, TItem> : never;
+/** `.spring`'s options where the items are targets, as {@link StaggerItemTweenOptions}. */
+type StaggerItemSpringOptions<TItem> = TItem extends Target<infer T> ? StaggerTargetSpringOptions<T, TItem> : never;
+/** Narrows a builder method's target options to the call that names its `target`. */
+type Naming = {
+    target: NonNullable<unknown>;
+};
+/**
+ * Fluent form of `Animator.stagger`: pick what to run per item after the
+ * items and the delay schedule are already fixed.
+ *
+ * `.tween` and `.spring` each take three shapes of options. Where the items are targets, each
+ * item's animation moves the item: `animator.stagger(targets, 80).spring({ to: (t) => ... })`.
+ * With a `target`, it moves the target that names for the item. With neither, it hands its
+ * values to `onTick`.
+ */
+interface StaggerBuilder<TItem> {
+    /** Run an arbitrary per-item factory. */
+    each(factory: StaggerFactory<TItem>, opts?: StaggerOptions): AnimationHandle;
+    /** Per-item `animator.tween` with per-item-varying options. */
+    tween(opts: StaggerItemTweenOptions<TItem>): AnimationHandle;
+    tween<T>(opts: StaggerTargetTweenOptions<T, TItem> & Naming): AnimationHandle;
+    tween<T>(opts: StaggerTweenOptions<T, TItem>): AnimationHandle;
+    /** Per-item `animator.spring` with per-item-varying options. */
+    spring(opts: StaggerItemSpringOptions<TItem>): AnimationHandle;
+    spring<T>(opts: StaggerTargetSpringOptions<T, TItem> & Naming): AnimationHandle;
+    spring<T>(opts: StaggerSpringOptions<T, TItem>): AnimationHandle;
+}
+
 /** 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. */
+/** 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. */
 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. */
@@ -430,13 +555,10 @@ interface TweenOptions<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. */
+    /** Required when T is not `number`. For T = number, defaults to linear numeric lerp. */
     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. */
+    /** Factory interpolator built once at tween start. Takes precedence over `interpolate`
+     *  when both are provided. */
     interpolator?: InterpolatorFactory<T>;
     onTick: (value: T) => void;
     onDone?: () => void;
@@ -560,9 +682,8 @@ 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`. */
+    /** With `to` set, behaves as a spring; with `to: null`, as a velocity-driven decay.
+     *  Retarget mid-flight 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. */
@@ -576,11 +697,9 @@ interface Animator {
     /** 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.
+     * True while the animator is executing an animation tick. Lets an adapter wrapper detect a
+     * `setPose` called from inside another animation's onTick and avoid scheduling a new
+     * animation that would fight the caller.
      */
     isTicking(): boolean;
     /** Freeze every animation managed by this animator. */
@@ -600,37 +719,26 @@ interface Animator {
     /** 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
+     * Repeatedly invokes `factory` to produce a child animation. The factory must wire its
+     * returned handle's `onDone` to call `next` so the loop advances. The returned handle's
+     * pause/resume/setTimeScale/cancel delegate to the in-flight child, and
      * `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`. */
+    /** Sugar over `loop`: a tween between two values, repeated per `direction`. 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.
+     * Schedules a per-item animation, offset by `delay` ms per index (or a custom function of
+     * the index). Pass `factory` and get a composite `AnimationHandle`; omit it and get a
+     * `StaggerBuilder` for fluent `.each` / `.tween` / `.spring` calls, the last two of which
+     * move the items themselves where they are targets.
      *
-     * 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
+     * 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 holds or stretches the waiting items along with the children, and a hidden tab
+     * holds both. `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>;
@@ -641,33 +749,21 @@ interface Animator {
      * 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. */
+    /** Per-node, per-channel color override registry, painted onto scene nodes by
+     *  `<SceneCanvas animator>` and read by `createPathLayer`. Only this animator can move its
+     *  per-node targets. 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.
+     * Subscribe to a callback fired once per RAF frame while any animation is active; returns
+     * an unsubscribe. For consumers that repaint from a non-scene channel such as
+     * `colorOverrides`, whose writes do not trigger a repaint the way scene mutations do.
+     * Fires AFTER the frame's animations have ticked.
      */
     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.
+     * Keeps the animator's RAF loop running until the returned cancel function is called. For
+     * effects read on every frame that have no progress state of their own; without it the
+     * loop would idle and `onTick` would stop firing.
      */
     keepAlive(): () => void;
     /**
@@ -765,48 +861,9 @@ interface LoopOptions {
     /** 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> {
@@ -831,10 +888,15 @@ interface TweenLoopOptions<T> {
  *  owns, and everything still running is canceled on unmount. */
 declare function useAnimator(opts?: UseAnimatorOptions): Animator;
 
+/** The arrays a table can keep its rows' values on screen in. */
+type ShownArray = Float64Array | Float32Array;
 /** What {@link createTargetTable} takes. */
-interface TargetTableOptions {
+interface TargetTableOptions<S extends ShownArray = Float64Array> {
     /** How many numbers a row holds. */
     axes: number;
+    /** The kind of array to keep `shown` in. Default `Float64Array`. Pass `Float32Array` for a
+     *  painter that uploads it: the table then fills that each frame, and no copy is made. */
+    shown?: new (length: number) => S;
     /** 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
@@ -849,7 +911,7 @@ interface TargetTableOptions {
  * 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 {
+interface TargetTable<S extends ShownArray = Float64Array> {
     readonly axes: number;
     /** How many rows are in use. */
     readonly size: number;
@@ -858,8 +920,8 @@ interface TargetTable {
     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;
+     *  table grows. A `Float32Array` where the table was made with `shown: Float32Array`. */
+    readonly shown: S;
     /** 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
@@ -871,13 +933,15 @@ interface TargetTable {
     target(row: number): Target<number[]>;
 }
 /** Make a {@link TargetTable} whose rows each hold `axes` numbers. */
-declare function createTargetTable(opts: TargetTableOptions): TargetTable;
+declare function createTargetTable<S extends ShownArray = Float64Array>(opts: TargetTableOptions<S>): TargetTable<S>;
 
 /** 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;
+    /** A name for each axis where the value has them: a plain object's fields. */
+    names?: readonly string[];
     to(v: T): number[];
     /** The value whose `count` axes start at `at` in `a`. */
     from(a: ArrayLike<number>, at?: number): T;
@@ -1066,6 +1130,8 @@ type ClipValue = number | string | boolean | null | ClipValue[] | {
 /** A keyframe as data. Its easing is a built-in's name or bezier control points. */
 interface ClipKey {
     t: number;
+    /** A typed array in the live key's value, as a `Path` has, is held as a `TaggedTypedArray`
+     *  from `@weasel-js/geom`: `{ __ta: 'f32', data: [...] }`. `bindClip` makes it the array again. */
     value: ClipValue;
     easing?: EasingName | BezierEasing;
 }
@@ -1079,8 +1145,12 @@ interface ClipSampledTrack {
     /** 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[];
+    /** The track's share of its target: a number, or a name for `ClipBinder.weight` to resolve
+     *  into a function read each frame, as a crossfade's is. */
+    weight?: number | string;
+    /** The part of the target the track holds: the target's names for its axes, a rig's joints
+     *  among them, or positions in its axes where it has no names. */
+    axes?: number[] | string[];
 }
 /** An `EventTrack` as data: each event is a name and what to carry with it. */
 interface ClipEventTrack {
@@ -1117,6 +1187,8 @@ interface ClipBinder {
     target?(name: string): Target<any> | undefined;
     /** Interpolations by name. */
     interpolate?: Readonly<Record<string, Interpolate<any>>>;
+    /** The function a track's named weight stands for. */
+    weight?(name: string): (() => number) | undefined;
     /** What an event does: its `fire`, its `book`, or both. */
     event?(name: string, data: ClipValue | undefined): Pick<TimelineEvent, 'fire' | 'book'> | undefined;
 }
@@ -1131,8 +1203,9 @@ 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.
+ * track written by hand can set too. A typed array in a key's value is written tagged.
+ * 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;
 
@@ -1167,17 +1240,11 @@ 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.
+ * skeleton — so the mirrored pose still blends, samples, and resolves like any
+ * other, and a rig faces the other way without a negative scale anywhere.
  *
+ * Each joint's `x` and `rotation` are negated as 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;
@@ -1194,14 +1261,16 @@ declare function mirrorPose(skeleton: Skeleton, pose: Pose): Pose;
 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) })`.
+ * The axes of `skeletonAxes(skeleton)` that belong to `joints`, as indexes, for a caller with
+ * a skeleton and no target. A hold or a track on a rig's target takes the joints' names
+ * themselves: `animator.hold({ target: rig.target, value: pose, axes: 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
+ * blends the short way round. Each axis is named `<joint>.<field>`, so `axes: ['knee']` on a hold
+ * reaches a joint's five and `['knee.rotation']` one of them. 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`.
  */
@@ -1254,23 +1323,16 @@ interface IkResult {
 }
 /**
  * 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
+ * ordinary {@link Pose}. 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.
+ * The solver is cyclic coordinate descent, and limits clamp the rotation the
+ * pose stores. 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;
 
@@ -1350,4 +1412,4 @@ declare function setWeights(skin: Skin, count: number, joint: string, weights: R
  */
 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 };
+export { type AnimationHandle, type AnimationInfo, type AnimationKind, type Animator, type AnimatorEvent, type AnimatorListener, type AutoSkinOptions, type Axes, type AxisBuffer, type AxisName, type AxisRef, 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 Naming, type NestedTimeline, type PhysicsHandle, type PhysicsOptions, type Pose, type SampledTrack, type ShownArray, type Skeleton, type Skin, type Slew, type SlewRates, type SolveIkOptions, type SpringOptions, type SpringVertexColorsOptions, type StaggerBuilder, type StaggerDelay, type StaggerFactory, type StaggerItemSpringOptions, type StaggerItemTweenOptions, type StaggerOptions, type StaggerPerItem, type StaggerSpringOptions, type StaggerTargetSpringOptions, type StaggerTargetTweenOptions, 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 };