@msb235/blits 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,61 @@ This package follows [semver](https://semver.org). Below 1.0.0, a breaking chang
 version and everything else the patch. Each release lists its changes as **Breaking**, **Added** and
 **Fixed**, and the release workflow refuses a tag with no section here.
 
+## 0.14.0
+
+### Added
+
+- `set(subject, value, at?)` on `spring`, `glide`, `tween`, and a voice's handle puts a subject at a
+  value and keeps its velocity: a spring or tween heads for its target from there, a glide coasts
+  on. A seek plays it again, as it does a push.
+- `@msb235/blits/fling`: `fling(element, motion, subject, opts)` drags a subject by pointer and
+  flings it on release, and `track` reads a pointer's velocity from its samples with no listeners
+  of its own. The package still builds without the DOM's types.
+- `glide` takes `bounds: [min, max]`, per axis and optionally per subject: a coast that would stop
+  past an edge springs back to it from where it crosses, on a critically damped spring of
+  `stiffness` (default 170). A `set` past an edge stays there until the next push. `g.bounds(subject)`
+  reads them, and `Patch.motion` reports the `stiffness` of a glide that has them.
+- `fling` resists a drag past a glide's bounds, carrying the subject at most `give` (default 120)
+  past an edge, and a press holds a subject springing back past one where it is.
+
+### Fixed
+
+- A voice cued with no `start` into a mix whose frame loop sleeps on `inert`, as `ticker` does,
+  starts at the next sync. It started at the last one, so an effect cued after a pause had already
+  played that far, and a short one was over before its first frame.
+- A patch that names no host type can be cued and blended in a mix that declares one, so a patch
+  library's patches type-check in a host-typed mix. `VoiceSpec.patch`, `BlendMember.patch`, and
+  `blend`'s members take a patch keeping any state.
+- A seek back keeps out a subject that had already left a voice at rest by then. After a fade with
+  `at: 'rest'`, a seek to a moment where that subject was moving again put it back in the voice,
+  playing.
+
+## 0.13.0
+
+### Breaking
+
+- A mix's stock `band` is on at any weight above 0 and off at 0, where it was on above 0.6 and off
+  below 0.4. A channel with no rest, such as `last()`, now shows its value through a whole fade in or
+  out. Pass `band: { on: 0.6, off: 0.4 }` for the old behavior. `fold` follows the same default.
+
+### Added
+
+- A mix's `loci`: tags that act as loci, so a voice carrying one folds with the others carrying it,
+  as if its `locus` named the tag.
+
+### Fixed
+
+- A seek with `state: 'keep'` that sends a subject back before its start now starts it afresh there.
+  It kept the state it had stepped to, so what it showed, and how it played on from its start,
+  depended on how often the host had read it, and a mix seek could put back the state from before.
+- A mix sought back and then ahead to where it stood reads the same `now` on its next sync as one
+  never sought. At some mix rates it read one rounding step off, and every later sync kept the error.
+- Replacing voices costs less a frame: a crowd catches up only the rows marked stale, where it
+  scanned every row, and a few retired voices are spliced out of the list. One subject leaving for
+  good each frame and a new one coming (`turnover^`, 10,000 subjects) takes 0.286 ms a frame
+  against 0.315, and one voice replaced in place each frame (`churn^`) 0.224 against 0.252 (teitou,
+  medians of nine runs of 5,000 frames, each in its own process); steady voices are unchanged.
+
 ## 0.12.1
 
 ### Added

package/README.md

@@ -102,6 +102,23 @@ import { kit, mix, patch, sum } from '@msb235/blits/lean';
 
 Everything else is the same and so are the poses. `lanes: true` is refused there.
 
+## Dragging and flinging
+
+`@msb235/blits/fling` drags a motion patch's subject by pointer and flings it on release:
+
+```ts
+import { fling } from '@msb235/blits/fling';
+
+const scroll = glide<Page, Pose>('y', { from: 0 });
+mix.cue({ patch: scroll });
+const off = fling(element, scroll, page, { scale: -1 }); // content moves against the drag
+```
+
+A press stops the glide where it is, each move puts it under the pointer, and letting go pushes it at
+the pointer's velocity. `track` reads that velocity from any `(t, x)` samples, with no listeners of
+its own. Anything else in the mix can read the glide's position and velocity, so parallax, a header
+that shrinks or a blur that grows with speed are voices driven by a signal over `scroll.read(page)`.
+
 ## Writing patches for blits in another library
 
 A library that ships patches exports them with the channels they write, as a `Kit` of its own

package/dist/channels.d.ts

@@ -1,4 +1,9 @@
 import type { Channel, Kit } from './types.js';
+/** The band a mix switches a rest-less channel's contribution across where its options name none. */
+export declare const STOCK_BAND: {
+    readonly on: number;
+    readonly off: 0;
+};
 /** The stock numeric channels' `lerp`, which `vec` applies per axis and lanes call directly. */
 export declare const lerpNumber: (a: number, b: number, u: number) => number;
 /**

package/dist/channels.js

@@ -1,4 +1,6 @@
 import { shared } from './shared.js';
+/** The band a mix switches a rest-less channel's contribution across where its options name none. */
+export const STOCK_BAND = { on: Number.MIN_VALUE, off: 0 };
 /** The stock numeric channels' `lerp`, which `vec` applies per axis and lanes call directly. */
 export const lerpNumber = (a, b, u) => a + (b - a) * u;
 const mix = lerpNumber;

package/dist/closed.d.ts

@@ -5,6 +5,7 @@ export declare const CRITICAL = 1;
 export declare const OVER = 2;
 export declare const COAST = 3;
 export declare const EASED = 4;
+export declare const BOUND = 5;
 /**
  * A stretch at voice time `t`, released at `at` from `x0` moving at `v0` toward `to` (each read
  * from its offset), into `xo` and `vo`: the one copy of the closed forms, which `law` (a patch's

package/dist/closed.js

@@ -6,6 +6,7 @@ export const CRITICAL = 1;
 export const OVER = 2;
 export const COAST = 3;
 export const EASED = 4;
+export const BOUND = 5;
 const solved = { y: 0, dy: 0 };
 /**
  * The terms of a stretch that depend only on how long since its release, the same on every axis, so
@@ -114,6 +115,46 @@ function solveGlide(law, y0) {
     solved.y = y0 * e;
     solved.dy = (-y0 / tau) * e;
 }
+/**
+ * A glide with bounds, heading for `goal`: the rest point itself where the coast stops inside them,
+ * else the edge it springs back to. Which one is read off the stretch, so no stretch carries more
+ * than an unbounded one: the coast's own rest, worked out as the glide's `aim` does, is `goal`
+ * exactly when it stops inside; past it on the side `x0` is on too, the subject was let go past the
+ * edge and springs back at once; else it coasts until it crosses the edge and springs from there,
+ * at the speed it crossed at. The spring is critically damped, its ω₀ the law's `k2`.
+ */
+function solveBound(law, x0, goal, v0, t) {
+    const tau = law[2];
+    const y0 = x0 - goal;
+    const over = x0 + v0 * tau - goal;
+    if (over === 0) {
+        solveGlide(law, y0);
+        return;
+    }
+    const w0 = law[3];
+    if (y0 * over > 0) {
+        const e = Math.exp(-w0 * t);
+        const b = v0 + w0 * y0;
+        const y = e * (y0 + b * t);
+        solved.y = y;
+        solved.dy = e * b - w0 * y;
+        return;
+    }
+    // e^(−t/τ) where the coast meets the edge: the fraction of its speed it still has there.
+    const left = 1 + y0 / (v0 * tau);
+    const cross = left > 0 ? -tau * Math.log(left) : Number.POSITIVE_INFINITY;
+    if (t < cross) {
+        const e = timed.e;
+        solved.y = y0 + v0 * tau * (1 - e);
+        solved.dy = v0 * e;
+        return;
+    }
+    const s = t - cross;
+    const vc = v0 * left;
+    const e = Math.exp(-w0 * s);
+    solved.y = e * vc * s;
+    solved.dy = e * vc * (1 - w0 * s);
+}
 /**
  * A stretch at voice time `t`, released at `at` from `x0` moving at `v0` toward `to` (each read
  * from its offset), into `xo` and `vo`: the one copy of the closed forms, which `law` (a patch's
@@ -130,7 +171,10 @@ export function closed(law, ease, n, at, ms, x0, x, v0, v, to, g, t, xo, vo) {
     prepare(law, dt);
     for (let i = 0; i < n; i++) {
         const goal = to[g + i];
-        solve(law, x0[x + i] - goal, v0[v + i], dt);
+        if (law[0] === BOUND)
+            solveBound(law, x0[x + i], goal, v0[v + i], dt);
+        else
+            solve(law, x0[x + i] - goal, v0[v + i], dt);
         xo[i] = goal + solved.y;
         vo[i] = solved.dy;
         if (Math.abs(solved.y) > settle || Math.abs(solved.dy) > settle)

package/dist/crowd.d.ts

@@ -92,6 +92,8 @@ export declare class Crowd<I, O> implements Positions<I, O> {
     dead: number;
     /** Whether some row is `Flag.STALE`, for `freshen` to copy before the fill's loop. */
     stale: boolean;
+    /** The rows marked stale since the last `freshen`, which checks each is still stale. */
+    staleRows: number[];
     readonly xs: Float64Array;
     readonly vs: Float64Array;
     /** What a keys row reads into, folded before the next row reads. */

package/dist/crowd.js

@@ -54,6 +54,8 @@ export class Crowd {
     dead = 0;
     /** Whether some row is `Flag.STALE`, for `freshen` to copy before the fill's loop. */
     stale = false;
+    /** The rows marked stale since the last `freshen`, which checks each is still stale. */
+    staleRows = [];
     xs;
     vs;
     /** What a keys row reads into, folded before the next row reads. */
@@ -82,6 +84,7 @@ export class Crowd {
     restale(p, flags) {
         this.hot[p * this.stride + 0 /* Hot.FLAGS */] = flags | 4 /* Flag.STALE */;
         this.stale = true;
+        this.staleRows.push(p);
     }
     /** Samples of another width than the channel's, which `samples` cannot hold, by row. */
     odd = null;
@@ -347,7 +350,12 @@ export function freshen(c) {
     c.stale = false;
     const hot = c.hot;
     const H = c.stride;
-    for (let p = 0; p < c.list.length; p++) {
+    const rows = c.staleRows;
+    c.staleRows = [];
+    for (let i = 0; i < rows.length; i++) {
+        const p = rows[i];
+        if (p >= c.list.length)
+            continue;
         const f = hot[p * H + 0 /* Hot.FLAGS */];
         if ((f & 4 /* Flag.STALE */) === 0 || (f & 128 /* Flag.MOTION */) === 0)
             continue;

package/dist/cue.d.ts

@@ -1,6 +1,6 @@
 import type { Mixer } from './mixer.js';
 import type { Handle, Kit, Patch, VoiceSpec } from './types.js';
-export declare function cue<I, O>(mix: Mixer<I, O>, spec: VoiceSpec<I, O>): Handle<I>;
+export declare function cue<I, O>(mix: Mixer<I, O>, given: VoiceSpec<I, O>): Handle<I>;
 /** Refuses a patch writing a channel `kit` lacks, or holds as another kind than it was written for. */
 export declare function fitsKit<I, O, S, H>(patch: Patch<I, O, S, H>, kit: Kit<O>): void;
 /** Refuses a spec whose patch the mix cannot play, or whose state its history cannot keep. */

package/dist/cue.js

@@ -17,7 +17,8 @@ import { checkChild, refit } from './spans.js';
 import { cuedById, motionOwner } from './strays.js';
 import { record, unplayable } from './tape.js';
 import { Voice } from './voice.js';
-export function cue(mix, spec) {
+export function cue(mix, given) {
+    const spec = locusOf(mix, given);
     const patch = spec.patch;
     playable(mix, spec);
     if (spec.from === 'current' && patch.form !== 'keys')
@@ -43,7 +44,10 @@ export function cue(mix, spec) {
                 ? mixAt(mix, spec.start - mix.offset)
                 : Number.isNaN(mix.now)
                     ? 0
-                    : mix.now;
+                    : // A loop asleep on an inert mix syncs next when it wakes, which is the cue's "now".
+                        mix.asleep
+                            ? Number.POSITIVE_INFINITY
+                            : mix.now;
     const voice = new Voice(mix.nextId++, spec, patch, spec.fade ?? noFade, local, start, mix.slotOf, mix.channels, mix.opts.host, mix.send, owner);
     if (patch === ownerPatch && mix.fitting !== null)
         voice.fitting = mix.fitting;
@@ -55,6 +59,10 @@ export function cue(mix, spec) {
         checkChild(spec, voice);
     if (mix.pace !== null && owner === null && spec.start !== undefined && voice.state === 'pending')
         voice.pinned = spec.start - mix.offset;
+    if (start === Number.POSITIVE_INFINITY && !anchored && !owner?.fitting) {
+        voice.waking = true;
+        mix.waking = true;
+    }
     enter(mix, voice);
     const h = handle(mix, voice);
     voice.handle = h;
@@ -88,6 +96,22 @@ export function fitsKit(patch, kit) {
             throw new Error(`blits: channel ${String(channel)} is ${here.kind ?? 'a custom channel'} in this kit, but the patch was written for ${wanted.kind ?? 'a custom channel'}`);
     }
 }
+/** The spec with its `locus` set from a tag the mix declares one, where it carries one. */
+function locusOf(mix, spec) {
+    const loci = mix.opts.loci;
+    const tags = spec.tags;
+    if (loci === undefined || tags === undefined)
+        return spec;
+    let locus = spec.locus;
+    for (const tag of tags) {
+        if (!loci.includes(tag) || tag === locus)
+            continue;
+        if (locus !== undefined)
+            throw new Error(`blits: a voice folds in one locus, not both ${locus} and ${tag}`);
+        locus = tag;
+    }
+    return locus === spec.locus ? spec : { ...spec, locus };
+}
 /** Refuses a spec whose patch the mix cannot play, or whose state its history cannot keep. */
 export function playable(mix, spec) {
     const patch = spec.patch;

package/dist/fling.d.ts

@@ -0,0 +1,66 @@
+import type { Moving, Value } from './motion.js';
+/**
+ * A pointer's recent path, for the velocity it is let go at.
+ *
+ * @category fling
+ */
+export interface Track<V extends Value = number> {
+    /** Where it was at `t`, ms; samples must come in time order. */
+    add(t: number, x: V): void;
+    /**
+     * Units per second at `at`, default the latest sample: the least-squares slope of the samples
+     * within `ms` of the latest, or zero once the latest is more than `stop` ms before `at`, or with
+     * fewer than two samples.
+     */
+    velocity(at?: number): V;
+    clear(): void;
+}
+/**
+ * Tracks a pointer's velocity from its samples, with no listeners of its own: anything that can give
+ * a time and a position can feed it.
+ *
+ * @category fling
+ */
+export declare function track<V extends Value = number>(opts?: {
+    /** How far back the slope reads, ms. Default 100. */
+    ms?: number;
+    /** How long a pointer can sit still before letting go and still fling, ms. Default 40. */
+    stop?: number;
+}): Track<V>;
+/** The part of a pointer event `fling` reads. */
+export interface PointerLike {
+    pointerId: number;
+    clientX: number;
+    clientY: number;
+    timeStamp: number;
+}
+/** Anything pointer events come from: an element, or a stand-in for one. */
+export interface PointerTarget {
+    addEventListener(type: string, fn: (e: PointerLike) => void): void;
+    removeEventListener(type: string, fn: (e: PointerLike) => void): void;
+    setPointerCapture?(pointerId: number): void;
+}
+/**
+ * Drags `subject` of a motion patch, usually a `glide`, by pointer on `target`, and flings it on
+ * release at the pointer's velocity: a press stops it where it is, each move `set`s it under the
+ * pointer, and letting go `push`es it. Past the edge of a glide's `bounds` it follows less and less
+ * of the drag, never more than `give` past. One pointer at a time; a canceled one lets go at rest.
+ * Returns the function that removes its listeners.
+ *
+ * @category fling
+ */
+export declare function fling<I, O, V extends Value = number>(target: PointerTarget, motion: Pick<Moving<I, O, V>, 'read' | 'set' | 'push'> & {
+    bounds?(subject: I): readonly [min: V, max: V] | undefined;
+}, subject: I, opts?: {
+    /** Which pointer axes it follows: `'xy'` moves a subject on two axes. Default `'y'`. */
+    axis?: 'x' | 'y' | 'xy';
+    /** Units per pixel of pointer travel; -1 scrolls content against the drag. Default 1. */
+    scale?: number;
+    /**
+     * How far past an edge of the glide's bounds a drag can carry the subject, in its units; 0
+     * holds it at the edge. Default 120.
+     */
+    give?: number;
+    ms?: number;
+    stop?: number;
+}): () => void;

package/dist/fling.js

@@ -0,0 +1,162 @@
+/**
+ * Tracks a pointer's velocity from its samples, with no listeners of its own: anything that can give
+ * a time and a position can feed it.
+ *
+ * @category fling
+ */
+export function track(opts = {}) {
+    const span = opts.ms ?? 100;
+    const stop = opts.stop ?? 40;
+    if (!(span > 0) || !(stop >= 0))
+        throw new RangeError('blits: a track takes a positive ms and a stop of 0 or more');
+    const ts = [];
+    const xs = [];
+    let scalar = true;
+    return {
+        add(t, x) {
+            scalar = typeof x === 'number';
+            ts.push(t);
+            xs.push(typeof x === 'number' ? [x] : [...x]);
+            let drop = 0;
+            while (t - ts[drop] > span)
+                drop++;
+            if (drop > 0) {
+                ts.splice(0, drop);
+                xs.splice(0, drop);
+            }
+        },
+        velocity(at) {
+            const n = ts.length;
+            const axes = n === 0 ? 1 : xs[0].length;
+            const out = new Array(axes).fill(0);
+            const last = ts[n - 1];
+            if (n >= 2 && !((at ?? last) - last > stop)) {
+                let mt = 0;
+                for (const t of ts)
+                    mt += t;
+                mt /= n;
+                let tt = 0;
+                for (const t of ts)
+                    tt += (t - mt) ** 2;
+                if (tt > 0)
+                    for (let k = 0; k < axes; k++) {
+                        let mx = 0;
+                        for (const x of xs)
+                            mx += x[k];
+                        mx /= n;
+                        let tx = 0;
+                        for (let i = 0; i < n; i++)
+                            tx += (ts[i] - mt) * (xs[i][k] - mx);
+                        out[k] = (tx / tt) * 1000;
+                    }
+            }
+            return (scalar ? out[0] : out);
+        },
+        clear() {
+            ts.length = 0;
+            xs.length = 0;
+        },
+    };
+}
+/** How much of a drag past an edge the subject follows, right at the edge. */
+const PULL = 0.55;
+/** How far a drag `d` past an edge carries the subject, never as far as `give`. */
+const resist = (d, give) => give > 0 ? give * (1 - 1 / ((PULL * d) / give + 1)) : 0;
+/** The drag past an edge that carries the subject `r` past it, as `resist` maps it. */
+const unresist = (r, give) => {
+    const held = Math.min(r, give * 0.99);
+    return give > 0 ? (give * held) / (PULL * (give - held)) : 0;
+};
+/**
+ * Drags `subject` of a motion patch, usually a `glide`, by pointer on `target`, and flings it on
+ * release at the pointer's velocity: a press stops it where it is, each move `set`s it under the
+ * pointer, and letting go `push`es it. Past the edge of a glide's `bounds` it follows less and less
+ * of the drag, never more than `give` past. One pointer at a time; a canceled one lets go at rest.
+ * Returns the function that removes its listeners.
+ *
+ * @category fling
+ */
+export function fling(target, motion, subject, opts = {}) {
+    const axis = opts.axis ?? 'y';
+    const scale = opts.scale ?? 1;
+    const give = opts.give ?? 120;
+    if (!(give >= 0))
+        throw new RangeError('blits: a fling takes a give of 0 or more');
+    let lo;
+    let hi;
+    /** Where the drag `x` puts the subject, past an edge carried by `resist`. */
+    const held = (x) => lo === undefined || hi === undefined
+        ? x
+        : x.map((xi, k) => {
+            const a = lo[k];
+            const b = hi[k];
+            return xi < a ? a - resist(a - xi, give) : xi > b ? b + resist(xi - b, give) : xi;
+        });
+    /** The drag that puts the subject at `x`, as `held` maps it. */
+    const dragged = (x) => lo === undefined || hi === undefined
+        ? x
+        : x.map((xi, k) => {
+            const a = lo[k];
+            const b = hi[k];
+            return xi < a ? a - unresist(a - xi, give) : xi > b ? b + unresist(xi - b, give) : xi;
+        });
+    const path = track(opts);
+    let id;
+    let from = [];
+    let p0 = [];
+    const at = (e) => axis === 'x' ? [e.clientX] : axis === 'y' ? [e.clientY] : [e.clientX, e.clientY];
+    const value = (x) => (axis === 'xy' ? x : x[0]);
+    const flat = (v) => (typeof v === 'number' ? [v] : [...v]);
+    const zero = () => value(from.map(() => 0));
+    const down = (e) => {
+        if (id !== undefined)
+            return;
+        const now = motion.read(subject);
+        if (now === undefined)
+            return;
+        id = e.pointerId;
+        target.setPointerCapture?.(id);
+        const edges = motion.bounds?.(subject);
+        lo = edges === undefined ? undefined : flat(edges[0]);
+        hi = edges === undefined ? undefined : flat(edges[1]);
+        const here = flat(now.value);
+        from = dragged(here);
+        p0 = at(e);
+        motion.push(subject, zero());
+        // The push alone would spring a subject caught past an edge back; a set there holds it.
+        motion.set(subject, value(here));
+        path.clear();
+        path.add(e.timeStamp, here);
+    };
+    const move = (e) => {
+        if (e.pointerId !== id)
+            return;
+        const x = held(at(e).map((p, k) => from[k] + (p - p0[k]) * scale));
+        motion.set(subject, value(x));
+        path.add(e.timeStamp, x);
+    };
+    const up = (e) => {
+        if (e.pointerId !== id)
+            return;
+        id = undefined;
+        motion.push(subject, value(path.velocity(e.timeStamp)));
+    };
+    const cancel = (e) => {
+        if (e.pointerId !== id)
+            return;
+        id = undefined;
+        motion.push(subject, zero());
+    };
+    const on = [
+        ['pointerdown', down],
+        ['pointermove', move],
+        ['pointerup', up],
+        ['pointercancel', cancel],
+    ];
+    for (const [type, fn] of on)
+        target.addEventListener(type, fn);
+    return () => {
+        for (const [type, fn] of on)
+            target.removeEventListener(type, fn);
+    };
+}

package/dist/fold.js

@@ -2,6 +2,7 @@ import { foldNumber } from './channels.js';
 import { passAt, phaseAt, phaseBefore, silent, stepOf } from './clock.js';
 import { copy as copyValue, first } from './clone.js';
 import { open as openRecord, shut as shutRecord, weighAt } from './everyone.js';
+import { waits } from './held.js';
 import { apart, copyState, recordHost, remember } from './history.js';
 import { stateful } from './hosts.js';
 import { locusScratch } from './locus.js';
@@ -59,6 +60,13 @@ function rebuild(mix, voice, subject, now, held) {
     held.stepped = held.since < now ? held.since : now;
     held.probed = Number.NaN;
 }
+/** Whether a seek since its last read moved a stateful record's origin, as one back before it does. */
+function sentBack(mix, voice, held) {
+    const p = voice.patch;
+    if (p.state === undefined && p.step === undefined && !voice.keeping)
+        return false;
+    return mix.sinceOf(voice, held.delay) !== held.since;
+}
 /**
  * One live voice's delta for one subject this frame, through its record for the subject, or null
  * when it does not reach. Its weight is left in `w`.
@@ -71,6 +79,11 @@ export function contribution(voice, subject, now, held) {
         return null;
     if (held.rebuilt !== voice.rebuilds)
         rebuild(this, voice, subject, now, held);
+    else if (held.seeks !== voice.seeks && sentBack(this, voice, held)) {
+        // A seek sent it back before its start, so it starts afresh there, whatever state it kept.
+        rebuild(this, voice, subject, now, held);
+        waits(voice, held, now);
+    }
     const raw = voice.rawAt(now, held.delay);
     const early = voice.before(raw, now);
     if (early && !voice.holdsFirst)
@@ -177,6 +190,7 @@ export function contribution(voice, subject, now, held) {
     if (voice.out?.rest && this.isRest(delta)) {
         held.weight = 0;
         held.rested = true;
+        held.restedAt = now;
         voice.restedCount++;
         return null;
     }

package/dist/handle.d.ts

@@ -68,5 +68,6 @@ export declare class VoiceHandle<I, O> implements Handle<I> {
     weightOf(subject: I): number;
     to(subject: I, target: Value, at?: number): void;
     push(subject: I, velocity: Value, at?: number): void;
+    set(subject: I, value: Value, at?: number): void;
     read(subject: I, at?: number): Motion<Value> | undefined;
 }

package/dist/handle.js

@@ -115,7 +115,7 @@ export class VoiceHandle {
         // A pending voice's clock is anchored at its start, so it starts there on time.
         if (voice.state !== 'pending') {
             const u = this.#host.nowFor(voice);
-            leave(voice, u);
+            leave(voice, u, true);
             voice.rebase(u);
         }
         voice.anchorElapsed = elapsed;
@@ -164,6 +164,11 @@ export class VoiceHandle {
         if (voice !== null)
             moves(voice.patch, 'push', 'a spring or a glide').push(subject, velocity, at);
     }
+    set(subject, value, at) {
+        const voice = this.#voice;
+        if (voice !== null)
+            moves(voice.patch, 'set', 'a motion patch').set(subject, value, at);
+    }
     read(subject, at) {
         const voice = this.#voice;
         if (voice === null || motionOf(voice.patch) === undefined)

package/dist/held.d.ts

@@ -24,6 +24,8 @@ export declare function sinceOf<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, del
  * the voice first showed, for one freezing before.
  */
 export declare function shownOf<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, since: number): number;
+/** Lists a record whose origin is still ahead of `now`, for a later change to the clock to move. */
+export declare function waits<I, O>(voice: Voice<I, O>, held: Subject<unknown>, now: number): void;
 /**
  * A pending voice starts at `now`. Starting anywhere but 0 it was sought there, so a record made
  * while it waited is made again for where its clock is.

package/dist/held.js

@@ -64,19 +64,7 @@ export function held(voice, subject, slot, guess = null) {
         held.unknown = (this.backward && voice.spec.from === 'current') || fresh;
     }
     voice.subjects.set(subject, held);
-    if (!(since <= now)) {
-        voice.early ??= [];
-        const early = voice.early;
-        // Prunes at each doubling, so records whose origin has passed are not kept to the voice's end.
-        if (early.length >= 64 && (early.length & (early.length - 1)) === 0) {
-            let kept = 0;
-            for (const h of early)
-                if (!(h.since <= now))
-                    early[kept++] = h;
-            early.length = kept;
-        }
-        early.push(held);
-    }
+    waits(voice, held, now);
     // A subject a voice saw while it shared one record was counted then.
     if (sighted(voice, slot))
         inherit(voice, held, slot);
@@ -137,6 +125,22 @@ export function shownOf(voice, since) {
     const from = since < start ? start : since;
     return voice.freezesBefore && voice.opened < from ? voice.opened : from;
 }
+/** Lists a record whose origin is still ahead of `now`, for a later change to the clock to move. */
+export function waits(voice, held, now) {
+    if (held.since <= now)
+        return;
+    voice.early ??= [];
+    const early = voice.early;
+    // Prunes at each doubling, so records whose origin has passed are not kept to the voice's end.
+    if (early.length >= 64 && (early.length & (early.length - 1)) === 0) {
+        let kept = 0;
+        for (const h of early)
+            if (!(h.since <= now))
+                early[kept++] = h;
+        early.length = kept;
+    }
+    early.push(held);
+}
 /**
  * A pending voice starts at `now`. Starting anywhere but 0 it was sought there, so a record made
  * while it waited is made again for where its clock is.
@@ -154,7 +158,11 @@ export function begin(mix, voice, now) {
 }
 /** Counts a record whose `since` was still ahead from where its voice's clock now puts it. */
 export function origin(mix, voice, held) {
+    const was = held.since;
     held.since = mix.sinceOf(voice, held.delay);
+    // Sent back before a start it had passed: its next read starts it afresh.
+    if (held.since !== was && (held.ticks > 0 || held.stepped > was))
+        held.rebuilt = -1;
     held.shown = mix.shownOf(voice, held.since);
     if (held.ticks === 0 && held.stepped > held.since)
         held.stepped = held.since;

package/dist/history.js

@@ -122,6 +122,7 @@ export function copyHeld(voice, h, shared = false) {
         shown: h.shown,
         weight: h.weight,
         rested: h.rested,
+        restedAt: h.restedAt,
         bands: h.bands === null ? null : h.bands.slice(),
         state: h.state === undefined || shared ? h.state : copyState(voice, h.state),
         stepped: h.stepped,
@@ -172,6 +173,7 @@ export function copyHeldInto(voice, h, into, shared = false) {
     into.shown = h.shown;
     into.weight = h.weight;
     into.rested = h.rested;
+    into.restedAt = h.restedAt;
     into.bands = h.bands === null ? null : h.bands.slice();
     into.state = h.state === undefined || shared ? h.state : copyState(voice, h.state);
     into.stepped = h.stepped;