@msb235/blits 0.4.0 → 0.5.0

package/dist/weigh.js

@@ -0,0 +1,89 @@
+import { envelope, weighed } from './clock.js';
+import { elapsedThen, last, record } from './history.js';
+import { ownersWeight } from './owner.js';
+import { reading } from './reading.js';
+/** Fills a voice's setting for a call to its patch, the weight aside. */
+export function prime(voice, held, now, elapsed, pass) {
+    const setting = voice.setting;
+    setting.timestamp = now;
+    setting.dt = this.capped(now - held.stepped);
+    setting.elapsed = elapsed;
+    setting.pass = pass;
+    setting.weight = 0;
+    setting.state = held.state;
+    voice.keepOn = held;
+}
+/** A gap as a `dt`: Infinity under reduced motion, and no more than `maxDt`. */
+export function capped(gap) {
+    const cap = this.opts.maxDt;
+    return this.reducedNow ? Number.POSITIVE_INFINITY : cap !== undefined && gap > cap ? cap : gap;
+}
+/** The earliest voice time a read may still ask for, for a subject delayed `delay`. */
+export function horizonFor(voice, delay, now) {
+    const history = this.opts.history;
+    return history === undefined
+        ? Number.POSITIVE_INFINITY
+        : elapsedThen(this, voice, now - history.ms) - delay;
+}
+/** The ramp a voice's own fade envelope applies this frame, 0..1. */
+export function fadeOf(voice, now, since) {
+    return envelope(voice.fade.in ?? 0, voice.out, voice.ease, this.reducedNow, now, since);
+}
+/** What every owner above a voice multiplies into its weight for a subject this frame. */
+export function ownedBy(voice, subject) {
+    return ownersWeight(voice, this.now, this.reducedNow, (o) => this.ownerBase(o, subject));
+}
+/**
+ * An owner's signal read for a subject, once a frame: kept on the owner's record for it, which
+ * no fold links, in `phase`, with the frame it was read in `probed`.
+ */
+export function ownerBase(owner, subject) {
+    const now = this.now;
+    const held = this.held(owner, subject, now, -1);
+    if (held.probed === this.frame)
+        return held.phase;
+    const kept = reading.kept;
+    this.prime(owner, held, now, owner.elapsedAt(now), 0);
+    const base = this.base(owner, subject, now, held);
+    reading.kept = kept;
+    held.stepped = now;
+    held.probed = this.frame;
+    held.phase = base;
+    return base;
+}
+/** The weight a voice gives a subject this frame, with the setting already filled in. */
+export function weigh(voice, subject, now, held) {
+    if (voice.owner !== null)
+        return this.weighOwned(voice, subject, now, held);
+    const base = this.base(voice, subject, now, held);
+    const fade = this.envelope(voice, now, held.shown);
+    return weighed(base, fade, voice.parts === null ? 1 : this.parting(voice, subject, now));
+}
+/** `weigh` for a voice an owner holds, its owners' weight folded into its fade. */
+export function weighOwned(voice, subject, now, held) {
+    // Its owners first, since a signal on one takes over the setting `base` leaves for the patch.
+    const owned = this.ownedBy(voice, subject);
+    const base = this.base(voice, subject, now, held);
+    const fade = this.envelope(voice, now, held.shown) * owned;
+    return weighed(base, fade, voice.parts === null ? 1 : this.parting(voice, subject, now));
+}
+/**
+ * A voice's weight for a subject before its fade and ramp: its signal's, or its own number.
+ * `slot` is the subject's number when lanes ask.
+ */
+export function base(voice, subject, now, held, slot = -1) {
+    this.sending.voice = voice;
+    this.sending.subject = subject;
+    const signal = typeof voice.spec.weight === 'function' ? voice.spec.weight : null;
+    if (signal === null)
+        return voice.weight;
+    const was = held.replay && last(held.replay, now, true);
+    const base = was
+        ? was.value
+        : voice.blend === null
+            ? signal(subject, voice.setting)
+            : this.blended(voice, subject, held, slot);
+    if (signal.input && !was)
+        record(this, held, base);
+    return base;
+}

package/docs/schema.html

@@ -160,7 +160,7 @@
   <h1>An effects schema, and the API around it</h1>
   <p class="lede">A small runtime package for concurrent effects. Each effect runs on its own clock with its own state and weight, and a mix folds them into one value per subject per frame by rules that belong to the channel, not the effect.</p>
   <p class="meta"><b>For:</b> whoever builds <code>blits</code>, and whoever ports klieg, wod, sherpa or magicsmoke onto it. <b>Answers:</b> what the vocabulary is, what an author writes, what a host calls, and where a second engine would plug in. The package implements this page; where the two differ, the code in <code>src/</code> is the one that runs.</p>
-  <span class="status">Built · v0.4.0 · design 2026-09-15, package 2026-09-28</span>
+  <span class="status">Built · v0.5.0 · design 2026-09-15, package 2026-09-28</span>
 </header>
 
 <h2 id="picture">In one picture</h2>
@@ -173,7 +173,7 @@
   <text x="20" y="22" class="sub">voices, each on its own clock</text>
   <rect x="20" y="32" width="170" height="44" rx="3" class="box"/>
   <text x="32" y="50">flicker · loop · w 1.0</text>
-  <text x="32" y="66" class="sub">phase wraps once per period</text>
+  <text x="32" y="66" class="sub">phase wraps once per pass</text>
   <rect x="20" y="86" width="170" height="44" rx="3" class="box hot"/>
   <text x="32" y="104">power · state · w 0.4 ↑</text>
   <text x="32" y="120" class="sub">fading in over 300 ms</text>
@@ -234,8 +234,10 @@
   <dt>Engine</dt><dd>The implementation behind a mix. One ships. The seam is the mix's own interface.</dd>
   <dt>Pose</dt><dd>What one subject looks like at one frame, once every voice has been folded in. Where a delta is partial, a pose is complete: every channel of the kit is filled. This is what a host writes.</dd>
   <dt>Influence</dt><dd>What one voice does to one subject in one frame, once its weight is applied. Not a share of the whole: two voices each contributing <code>gain: 0.1</code> leave the subject at 0.01.</dd>
-  <dt>Period</dt><dd>How long one pass of a patch lasts, in milliseconds. 0 means aperiodic.</dd>
-  <dt>Phase</dt><dd>Where a voice is within its period, 0 to 1, wrapping. The first thing a patch is handed, and what <code>stagger</code> spreads per subject.</dd>
+  <dt>Duration</dt><dd>How long one pass of a patch lasts, in milliseconds, whether or not the voice loops. 0 means the patch has no passes.</dd>
+  <dt>Pass</dt><dd>One run through a patch, phase 0 to 1.</dd>
+  <dt>Period</dt><dd>The duration a looping voice repeats. <code>Patch.period</code> is a deprecated alias for <code>duration</code>.</dd>
+  <dt>Phase</dt><dd>Where a voice is within its current pass, 0 to 1, wrapping. The first thing a patch is handed, and what <code>stagger</code> spreads per subject.</dd>
   <dt>Setting</dt><dd>What a patch may read and did not compute, for one subject this frame: the clock and <code>dt</code> the whole frame shares, the <code>elapsed</code>, <code>pass</code> and <code>weight</code> particular to the voice, its state, and whatever the host added.</dd>
   <dt>System</dt><dd>One complete area of driven behavior: a kit, the subject type it drives, and the mix over them. klieg's motion, effects and lighting are three systems in one host. Two systems never share a mix, so a voice belongs to exactly one.</dd>
   <dt>Source</dt><dd>Whatever decided a voice should exist: a score, a handler on an event, a chain handing over. There is no source type and nothing to implement &mdash; a source calls <code>cue</code> and gets a handle. The word is here so the vocabulary can name the seam it does not own.</dd>
@@ -293,27 +295,30 @@ type Kit&lt;O&gt; = { readonly [K in keyof O]-?: Channel&lt;NonNullable&lt;O[K]&
 <h2 id="patches">Patches</h2>
 <p>A patch is what an author writes. It is klieg's <code>EffectPiece</code> with three additions: the setting carries absolute time as well as normalized, a patch may declare state, and a patch declares which channels it contributes to.</p>
 
-<pre><code>interface Patch&lt;I, O, S = void&gt; {
+<pre><code>interface Patch&lt;I, O, S = void, H = unknown&gt; {
   <span class="cm">/** Which authoring form built it: `'fn'` from `patch`, `'keys'` from `keys`, `'motion'` from `spring`,
      `glide` or `tween`. An engine declares which forms it runs. */</span>
   readonly form: 'fn' | 'keys' | 'motion';
-  <span class="cm">/** Milliseconds one pass lasts. 0 is aperiodic: one pass that never ends, so `phase` and `pass` stay 0,
-     `loop` is ignored, and the patch reads `setting.elapsed` instead. */</span>
-  period: number;
+  <span class="cm">/** Milliseconds one pass lasts, whether or not the voice loops. 0 has no passes: `phase` and `pass`
+     stay 0, `loop` is ignored, and the patch reads `setting.elapsed` instead. */</span>
+  duration: number;
+  <span class="cm">/** @deprecated Use `duration`. A patch that sets only `period` still plays. */</span>
+  readonly period?: number;
   <span class="cm">/** The channels this patch contributes to. Every key `at` sets, and no others. */</span>
   readonly writes: readonly (keyof O)[];
   <span class="cm">/** The channels it was written against. `cue` refuses a kit whose channel of the same name is another kind. */</span>
   readonly kit?: Partial&lt;Kit&lt;O&gt;&gt;;
   <span class="cm">/** The fields of `setting.host` it reads. `cue` refuses a mix whose host lacks one. */</span>
   readonly reads?: readonly string[];
-  <span class="cm">/** `phase` is 0..1 across one period, wrapping. */</span>
-  at(phase: number, subject: I, setting: Setting&lt;S&gt;): Partial&lt;O&gt;;
+  <span class="cm">/** `phase` is 0..1 across one pass, wrapping. Not asked for a subject its voice gives no weight, unless the
+     voice is fading to rest; `step` still runs. */</span>
+  at(phase: number, subject: I, setting: Setting&lt;S, H&gt;): Partial&lt;O&gt;;
 
   <span class="cm">/** Per-subject state, created on the first frame this patch sees a subject. */</span>
   state?(subject: I): S;
   <span class="cm">/** Advances state once per subject per probed frame, before that frame's first `at`, by the whole gap
      since that subject last advanced. `dt` is Infinity under reduced motion. */</span>
-  step?(state: S, dt: number, subject: I, setting: Setting&lt;S&gt;): void;
+  step?(state: S, dt: number, subject: I, setting: Setting&lt;S, H&gt;): void;
 
   <span class="cm">/** Present when the patch was authored as keyframes, so an engine that reads data can. */</span>
   readonly keys?: readonly Keyframe&lt;O&gt;[];
@@ -323,7 +328,7 @@ type Kit&lt;O&gt; = { readonly [K in keyof O]-?: Channel&lt;NonNullable&lt;O[K]&
   clone?(state: S): S;
 }
 
-interface Setting&lt;S = void&gt; {
+interface Setting&lt;S = void, H = unknown&gt; {
   <span class="cm">/** The mix clock at this frame. Identical for every sample in the frame. */</span>
   timestamp: number;
   <span class="cm">/** The gap this subject is catching up by: milliseconds since it last advanced, which is the gap since
@@ -339,8 +344,8 @@ interface Setting&lt;S = void&gt; {
   weight: number;
   <span class="cm">/** This subject's state, when the patch declares one. */</span>
   state: S;
-  <span class="cm">/** Anything the host adds for its own patches: klieg's pointer and pointerInWord go here. */</span>
-  host: unknown;
+  <span class="cm">/** Anything the host adds for its own patches: klieg's pointer and pointerInWord go here. Typed as the mix's `H`. */</span>
+  host: H;
   <span class="cm">/** The state `owner` keeps for this voice and subject, made by `init` on first ask. Held by the mix, so a read at
      another time can copy it; a stateful signal keeps its state here and nowhere else. */</span>
   keep&lt;K&gt;(owner: object, init: () =&gt; K): K;
@@ -352,8 +357,8 @@ interface Setting&lt;S = void&gt; {
 <p>Three authoring forms build a patch. All return the same interface, so a voice cannot tell them apart.</p>
 <div class="tbl"><table>
   <tr><th>form</th><th>signature</th><th>what it is</th></tr>
-  <tr><td><code>fn</code></td><td><code>patch(period, at, { writes, state?, step? })</code></td><td>Procedural. Flicker, roving, a hash walk, a starter strike. Only a JS engine can run one.</td></tr>
-  <tr><td><code>keys</code></td><td><code>keys(period, stops, { ease?, easeBy?, delayBy? })</code></td><td>Declarative stops, klieg's transition sugar and wod's keyframes. Data preserved on <code>patch.keys</code> for an engine that reads data instead of calling functions.</td></tr>
+  <tr><td><code>fn</code></td><td><code>patch(duration, at, { writes, state?, step? })</code></td><td>Procedural. Flicker, roving, a hash walk, a starter strike. Only a JS engine can run one.</td></tr>
+  <tr><td><code>keys</code></td><td><code>keys(duration, stops, { ease?, easeBy?, delayBy? })</code></td><td>Declarative stops, klieg's transition sugar and wod's keyframes. Data preserved on <code>patch.keys</code> for an engine that reads data instead of calling functions.</td></tr>
   <tr><td><code>motion</code></td><td><code>spring(writes, opts)</code>, <code>glide(writes, opts)</code>, <code>tween(writes, opts)</code></td><td>Momentum, or an eased curve between two values, solved in closed form per subject; <a href="#motion">below</a>. The kind and its constants are preserved on <code>patch.motion</code>, a <code>MotionSpec</code>.</td></tr>
 </table></div>
 
@@ -366,8 +371,8 @@ interface Setting&lt;S = void&gt; {
 <h2 id="voices">Voices</h2>
 <p>A voice is a patch given a clock and a volume knob. This is the unit that answers "independent state and timeframe": two voices of the same patch are two clocks, two states, two weights.</p>
 
-<pre><code>interface VoiceSpec&lt;I, O&gt; {
-  patch: Patch&lt;I, O, any&gt;;
+<pre><code>interface VoiceSpec&lt;I, O, H = unknown&gt; {
+  patch: Patch&lt;I, O, any, H&gt;;
   <span class="cm">/** Which subjects this voice reaches. Default: all of them. The predicate is fixed at `cue`; it runs per
      subject the first time the mix sees that subject, and the answer is kept for as long as the state is. */</span>
   target?: (subject: I) =&gt; boolean;
@@ -393,7 +398,7 @@ interface Setting&lt;S = void&gt; {
 
   <span class="cm">// weight</span>
   <span class="cm">/** Steady weight, or a signal read per subject per frame. Default 1. */</span>
-  weight?: number | Signal&lt;I&gt;;
+  weight?: number | Signal&lt;I, H&gt;;
   <span class="cm">/** Ramp in and out, ms. Out applies on `fade()` and when a finite loop ends. */</span>
   fade?: { in?: number; out?: number; ease?: Easing };
   <span class="cm">/** Voices sharing a locus are alternatives: the mix folds them into one influence through each
@@ -406,7 +411,7 @@ interface Setting&lt;S = void&gt; {
      the pose of the frame before this voice first contributes, so it never reads itself. With no
      such frame on record it is this frame's pose with every other voice folded in. */</span>
   from?: 'current';
-  <span class="cm">/** Words a source attaches to its voices, so their events can be drained as a set. */</span>
+  <span class="cm">/** Words a source attaches to its voices, so their events and handles can be taken as a set. */</span>
   tags?: readonly string[];
   <span class="cm">// score</span>
   <span class="cm">/** What other voices call this one by. A label blits never reads. */</span>
@@ -415,12 +420,18 @@ interface Setting&lt;S = void&gt; {
   score?: string;
   <span class="cm">/** start or in, and out or end: each a timestamp or an anchor to another voice's mark. See Score. */</span>
   anchor?: Placement;
+  <span class="cm">/** Events at times on this voice's clock, once per pass, for `book` to hand the host ahead of time. See Time. */</span>
+  hits?: readonly { at: number; event: unknown }[];
+  <span class="cm">/** The owner it plays under, which places and times it on the owner's clock. See Score. */</span>
+  owner?: Handle&lt;I&gt;;
 }
 
 interface Handle&lt;I&gt; {
   readonly id: number;
   <span class="cm">/** <code>held</code>: a voice holding after has played every pass and shows its last frame until faded. */</span>
   readonly state: 'pending' | 'live' | 'held' | 'fading' | 'done';
+  <span class="cm">/** The owner's handle, for a voice an owner holds. */</span>
+  readonly owner: Handle&lt;I&gt; | undefined;
   <span class="cm">/** Live. Writes land on the next sync. */</span>
   weight: number;
   rate: number;
@@ -460,14 +471,14 @@ interface Handle&lt;I&gt; {
 <h2 id="mix">Mix</h2>
 <p>What a host holds. The methods are few because the voices carry the options.</p>
 
-<pre><code>function mix&lt;I, O&gt;(kit: Kit&lt;O&gt;, opts?: MixOptions): Mix&lt;I, O&gt;;
+<pre><code>function mix&lt;I, O, H = unknown&gt;(kit: Kit&lt;O&gt;, opts?: MixOptions&lt;H&gt;): Mix&lt;I, O, H&gt;;
 
-interface MixOptions {
+interface MixOptions&lt;H = unknown&gt; {
   engine?: Engine;                <span class="cm">// default: mixer</span>
   <span class="cm">/** Reduced motion: fades and warm-ups snap, `dt` reads Infinity. Read once at creation, or a signal. */</span>
   reduce?: boolean | (() =&gt; boolean);
-  <span class="cm">/** Merged into every `setting.host`. */</span>
-  host?: unknown;
+  <span class="cm">/** Merged into every `setting.host`. `H` types it for every patch and signal the mix cues, so none needs a cast. */</span>
+  host?: H;
   <span class="cm">/** The band a rest-less channel's influence switches across. Default 0.4 / 0.6, a placeholder. */</span>
   band?: { on: number; off: number };
   <span class="cm">/** The most `dt` a step or signal is handed, however long the gap. Off by default. */</span>
@@ -481,12 +492,15 @@ interface MixOptions {
   lanes?: boolean;
 }
 
-interface Mix&lt;I, O&gt; {
+interface Mix&lt;I, O, H = unknown&gt; {
   <span class="cm">/** Cues a voice. Throws when the engine cannot run the patch's form, or the kit lacks a channel it `writes`. */</span>
-  cue(spec: VoiceSpec&lt;I, O&gt;): Handle&lt;I&gt;;
+  cue(spec: VoiceSpec&lt;I, O, H&gt;): Handle&lt;I&gt;;
   <span class="cm">/** N voices whose weights split one signal, k in 0..1, cued into one locus so they fold as
-     alternatives. Two patches crossfade; more make stops. */</span>
-  blend(patches: readonly Patch&lt;I, O&gt;[], by: Signal&lt;I&gt;, spec?: Omit&lt;VoiceSpec&lt;I, O&gt;, 'patch' | 'weight'&gt;): Handle&lt;I&gt;[];
+     alternatives. Two patches crossfade; more make stops. The signal is read once per subject per
+     frame, and every member takes its share of that reading. */</span>
+  blend(patches: readonly Patch&lt;I, O, any, H&gt;[], by: Signal&lt;I, H&gt;, spec?: Omit&lt;VoiceSpec&lt;I, O, H&gt;, 'patch' | 'weight'&gt;): Handle&lt;I&gt;[];
+  <span class="cm">/** An owner: a voice with no patch that plays the voices cued with `owner: handle` on its own clock. See Score. */</span>
+  owns(spec: OwnerSpec&lt;I, H&gt;): Handle&lt;I&gt;;
 
   <span class="cm">/** The host reports the clock, once a frame. Nothing advances at the call: it publishes the reading, and
      each subject catches up by the whole gap the first time it is probed afterward. The same timestamp twice
@@ -494,6 +508,10 @@ interface Mix&lt;I, O&gt; {
   sync(timestamp: number): void;
   <span class="cm">/** The time between the last sync and the next one does not count. Called when a hidden tab comes back. */</span>
   rebase(): void;
+  <span class="cm">/** The mix's own rate, multiplied into every voice's; 0 pauses the whole mix. See Time. */</span>
+  rate: number;
+  <span class="cm">/** Moves the mix's rate to `rate` linearly over `over` ms of the host's clock. */</span>
+  ramp(rate: number, over: number): void;
   <span class="cm">/** The merged pose for one subject at the synced frame. `out` is written in place when given. */</span>
   probe(subject: I, out?: O): O;
   <span class="cm">/** Each subject's pose written into one Float64Array per channel, in the order given: what probe(subject, out)
@@ -508,12 +526,16 @@ interface Mix&lt;I, O&gt; {
   <span class="cm">/** Every mark the plan knows between two timestamps, earliest first. */</span>
   marks(from: number, to: number): Marked[];
 
+  <span class="cm">/** A handle on every voice still in the mix, pending, live, held or fading, in cue order; given a tag, only
+     the voices carrying it. Each is the handle `cue` returned for that voice. */</span>
+  voices(tag?: string): Handle&lt;I&gt;[];
+
   <span class="cm">/** Anything still contributing, fading, or pending. A host stops its loop when this is false. `cue` and
      `blend` make it true again at once; the mix never calls back into the host, so restarting the loop is
      the caller's to do on the same path that cued. */</span>
   readonly live: boolean;
   <span class="cm">/** Another frame would change no pose: every voice is done, held at a plain weight, or a motion whose every
-     subject has landed. A host may sleep its loop while this is true and `live` still is. */</span>
+     subject has landed, or, at rate 0, every voice has started at a plain weight with no anchor. A host may sleep its loop while this is true and `live` still is. */</span>
   readonly inert: boolean;
   <span class="cm">/** Fades every voice out: over `over` when given, over each voice's own `fade.out` otherwise. */</span>
   mute(opts?: { over?: number }): void;
@@ -521,6 +543,9 @@ interface Mix&lt;I, O&gt; {
   drop(subject: I): void;
   <span class="cm">/** Every event sent since the last drain, earliest first. Drain after probing. */</span>
   drain&lt;E&gt;(tag?: string): { timestamp: number; subject: I; voice: number; tags: readonly string[]; event: E }[];
+  <span class="cm">/** Hands the host each mark and hit `ahead` ms before it comes, on a clock of its own, and stops what moves. See Time. */</span>
+  book&lt;E&gt;(opts: { clock: () =&gt; number; ahead: number; late: number; tag?: string; score?: string;
+    take(item: Marked | BookedHit&lt;E&gt;, when: number, lateBy: number): { stop(): void } | undefined }): { stop(): void };
 }</code></pre>
 
 <p>A probe walks the voices that may reach its subject, not every voice. With no <code>target</code> in the mix that is all of them, so nothing is kept; once a voice targets, each subject keeps the list of voices whose <code>target</code> took it, rebuilt when a voice is cued, starts or leaves. One voice per subject on a shared mix then costs one voice per probe: 1000 subjects, each with its own voice, took 95&nbsp;ms a frame before the list and 0.45&nbsp;ms after (<code>npm run bench</code>, rows <code>own</code>). Building the list still asks every <code>target</code> of every new subject, so the first frame of that scene took 500&ndash;580&nbsp;ms. A voice that names its subjects with <code>subjects</code> is filed under each of them at <code>cue</code>, and a subject's list is built from the voices filed under it and those that name none: the same scene's first frame took 1.0&nbsp;ms, and 10.6&nbsp;ms at 10,000 subjects (rows <code>named</code>).</p>
@@ -530,17 +555,17 @@ interface Mix&lt;I, O&gt; {
 <h2 id="signals">Signals</h2>
 <p>A signal is a 0..1 scalar resolved per subject per frame. It is the package's one input type from outside the clock, and it plugs in at exactly two places: a voice's <code>weight</code>, and <code>blend</code>'s selector.</p>
 
-<pre><code>type Signal&lt;I&gt; = ((subject: I, setting: Setting) =&gt; number) &amp; { readonly input?: boolean };
+<pre><code>type Signal&lt;I, H = unknown&gt; = ((subject: I, setting: Setting&lt;void, H&gt;) =&gt; number) &amp; { readonly input?: boolean };
 
 <span class="cm">// stock combinators; klieg's own `near`, `dwell`, `level` are consumers' signals built on these</span>
 function peak&lt;I&gt;(...signals: Signal&lt;I&gt;[]): Signal&lt;I&gt;;          <span class="cm">// max</span>
-function slew&lt;I&gt;(of: Signal&lt;I&gt;, { riseMs, fallMs }): Signal&lt;I&gt;;  <span class="cm">// stateful: rate-limited follow toward its input</span>
-function lag&lt;I&gt;(of: Signal&lt;I&gt;, { riseMs, fallMs, floor }): Signal&lt;I&gt;;  <span class="cm">// stateful: exponential follow, time constants</span>
+function slew&lt;I&gt;(of: Signal&lt;I&gt;, { riseMs, fallMs, from }): Signal&lt;I&gt;;  <span class="cm">// stateful: rate-limited follow toward its input, from `from` or its input</span>
+function lag&lt;I&gt;(of: Signal&lt;I&gt;, { riseMs, fallMs, floor, from }): Signal&lt;I&gt;;  <span class="cm">// stateful: exponential follow, time constants</span>
 function level&lt;I&gt;(initial?: number): Signal&lt;I&gt; &amp; { set(v: number): void };  <span class="cm">// host-written</span>
 function gate&lt;I&gt;(of: Signal&lt;I&gt;, band: { on: number; off: number }): Signal&lt;I&gt;;  <span class="cm">// stateful: holds inside the band</span>
 function gate&lt;I&gt;(of: Signal&lt;I&gt;, at: number): Signal&lt;I&gt;;          <span class="cm">// sugar for on = off = at</span></code></pre>
 
-<p>A stateful signal keeps its state in the mix, through <code>setting.keep(owner, init)</code>: per voice and per subject, keyed by the signal itself, made on first ask. So two voices handed the same <code>slew</code> each follow on their own, and a read at another time can copy what the mix holds instead of moving it. A signal measures its own gap, from the timestamp it last saw, rather than the gap its voice caught up by. <code>input</code> marks a signal that reads something the clock does not drive: <code>level</code> sets it, and <code>peak</code>, <code>slew</code>, <code>gate</code> and <code>blend</code>&rsquo;s shares inherit it from what they read. <code>slew</code> is klieg's <code>dwell</code> with the cursor factored out; <code>gate</code> keeps one bit, which way it last switched.</p>
+<p>A stateful signal keeps its state in the mix, through <code>setting.keep(owner, init)</code>: per voice and per subject, keyed by the signal itself, made on first ask. So two voices handed the same <code>slew</code> each follow on their own, except a blend&rsquo;s members, which read their signal once and keep its state once between them; and a read at another time can copy what the mix holds instead of moving it. A signal measures its own gap, from the timestamp it last saw, rather than the gap its voice caught up by. <code>input</code> marks a signal that reads something the clock does not drive: <code>level</code> sets it, and <code>peak</code>, <code>slew</code>, <code>gate</code> and <code>blend</code>&rsquo;s shares inherit it from what they read. <code>slew</code> is klieg's <code>dwell</code> with the cursor factored out; <code>gate</code> keeps one bit, which way it last switched.</p>
 
 <p><code>slew</code> and <code>lag</code> are the package's two decay primitives. <code>slew</code> follows its input at a rate limit, no faster than <code>riseMs</code> per unit climbing or <code>fallMs</code> draining; it stays linear, because klieg's three decays are and the port's baselines depend on it. <code>lag</code> closes <code>1 − exp(−gap / ms)</code> of the distance per read, so it reads the same at any frame spacing while its input holds still; it lands on its input within <code>floor</code> (1e-6), because an exponential never reaches rest and <code>atRest</code> needs it to, and <code>floor: 0</code> keeps the curve exact. magicsmoke's intensity ease is a <code>lag</code>. It is not <code>Easing</code>, which is a curve over a known duration, and it is not called <code>ease</code> for that reason &mdash; <code>fade.ease</code> and <code>keys({ ease })</code> already mean the curve. A decay tail is a <code>slew</code> to 0 with no rise; a fade is a <code>slew</code> on a weight; klieg's <code>kicks</code> is a <code>slew</code> to 0 that <code>peak</code> pokes back up. Nothing else in the package stores a value in order to follow it. <code>gate</code> is the other half of that pair and not a substitute for it: a slew sets how fast a value may move, a band sets whether it may move at all. A slew cannot quiet a gate, because a rate limit delays a crossing without deciding it, and an input resting on the threshold drags the slewed value onto the threshold with it.</p>
 
@@ -548,11 +573,43 @@ function gate&lt;I&gt;(of: Signal&lt;I&gt;, at: number): Signal&lt;I&gt;;
 <ul>
   <li><b>The mix is pull-based on a host clock.</b> The host owns the frame loop and calls <code>sync(timestamp)</code> with milliseconds on any monotonic clock it likes. klieg passes its <code>Clock.now()</code>; wod passes <code>performance.now()</code>; a test passes integers.</li>
   <li><b>Everything in a frame reads one timestamp.</b> A second <code>sync</code> with the same value is a no-op, and every <code>probe</code> between syncs answers from the same frame. This is what makes state advance once however many probes a wrapper makes.</li>
-  <li><b>A voice's clock is <code>(timestamp − start) · rate</code>.</b> That reading is <code>setting.elapsed</code>, and its position within the period, <code>(elapsed mod period) / period</code>, is the <code>phase</code> the patch is handed first. Both reach the patch. A rate change rebases so <code>elapsed</code> is continuous.</li>
+  <li><b>A voice's clock is <code>(timestamp − start) · rate</code>.</b> That reading is <code>setting.elapsed</code>, and its position within the current pass, <code>(elapsed mod duration) / duration</code>, is the <code>phase</code> the patch is handed first. Both reach the patch. A rate change rebases so <code>elapsed</code> is continuous.</li>
+  <li><b>The mix has a rate of its own,</b> <code>mix.rate</code> and <code>mix.ramp(rate, over)</code>, shaped like a handle's and multiplied into every voice's: 0 pauses the whole mix, and a negative rate throws, since the mix only goes forward. It runs the mix clock: mix time is the host's timestamp, less what <code>rebase</code> took out, integrated at the mix's rate, and each voice integrates its own rate over mix time, so a ramp on both multiplies and no position jumps. Everything a voice owns runs on mix time and slows with it, which is what a pause has to mean for a fade caught halfway. A timestamp the host gives or reads stays on the host's clock, so a beat announced from an audio clock stays on the beat when the mix slows, and a start ahead of a paused mix waits for the host's clock to reach it. The mix's own ramp runs over host ms, since a ramp over its own slowing time would never arrive. A change made while paused lands at the next sync as always, and a weight signal is still asked at every probe, so one reading input follows it. At rate 0 the mix is <code>inert</code> once every voice not done has started, at a plain weight, with no anchor. Under <code>history</code> every rate change is kept, and a read back finds mix time through them as it finds a voice's clock through its handle's changes; without it a timestamp from before the last change converts at the rate in force, as one from before a <code>rebase</code> converts at the offset in force. weasel also scales a key and a handle; a mix leaves those levels to tags and to the host.
+    <div class="tbl"><table>
+      <tr><th>runs on mix time, at the mix's rate</th><th>stays on the host's clock</th></tr>
+      <tr><td>voice clocks, fades, a handle's <code>ramp</code>, <code>stagger</code>, an anchor's <code>by</code>, <code>stepMs</code>, <code>maxDt</code>, <code>history.ms</code>, every <code>dt</code>, <code>setting.timestamp</code> and what <code>drain</code> stamps</td><td><code>sync</code>, a <code>start</code>, an anchor given as a number, <code>announce</code>'s <code>at</code>, what <code>marks</code> reports, <code>project</code>'s timestamp, the mix's own <code>ramp</code>, and <code>book</code>'s <code>ahead</code>, <code>late</code> and <code>lateBy</code></td></tr>
+    </table></div></li>
   <li><b><code>dt</code> is derived, never supplied.</b> The gap between this sync and the last, per subject, and <code>Infinity</code> under reduced motion. A patch that integrates guards against that with a snap, as klieg's already do.</li>
   <li><b>Time away is the host's to call.</b> A hidden tab gets no frames, so its next <code>sync</code> can be an hour past the last. By default that hour is a gap like any other: fades and finite loops finish, and every subject catches up by all of it. A host that calls <code>mix.rebase()</code> on <code>visibilitychange</code> says the gap does not count, and the mix clock &mdash; what <code>setting.timestamp</code> reads, and what voices, fades and subjects run on &mdash; resumes where it was left. It is then the host's timestamp less the time taken out, and a <code>start</code> the host gives is read on the host's clock and converted. <code>maxDt</code> caps the <code>dt</code> a <code>step</code> or signal is handed for any gap, the net an integrator wants; it is off by default because a patch with a closed form wants the whole gap.</li>
   <li><b>There is no frame rate, only an optional step interval.</b> A frame is a reading, so a stateless patch reads the same at any rate. A <code>step</code> handed the frame's gap does not: an integrator gives a different answer at 30 and 144&nbsp;fps. <code>stepMs</code> runs <code>step</code> once per whole interval instead, on a grid counted from when the subject's delay ran out, carrying the remainder, so the answer and every event's time are the same at any frame rate. <code>maxDt</code> then caps how many intervals one sample runs. Signals and <code>at</code> still read the frame. The host's clock is whatever it passes <code>sync</code>: a rAF timestamp and <code>performance.now()</code> share an origin, and <code>Date.now()</code> does not.</li>
-  <li><b>Events come out by draining.</b> A patch calls <code>setting.send(event)</code>, usually from <code>step</code>, and the host calls <code>mix.drain()</code> after probing to take everything sent, earliest first. Events are made while a subject catches up, so a subject nobody probes has sent nothing yet, and promptness is the host's to buy by probing. Under <code>stepMs</code> each is stamped with the end of the interval it happened in, so the events and their times do not depend on how the probes are spaced. Time taken out by <code>rebase</code> sends nothing. The exception is a stateless patch sending from <code>at</code> on a lane: a lane fills every subject the mix has met, so it sends for each of them every frame, probed or not. This is the small half of weasel's events: no booking ahead against an outside clock, and no retraction.</li>
+  <li><b>Events come out by draining.</b> A patch calls <code>setting.send(event)</code>, usually from <code>step</code>, and the host calls <code>mix.drain()</code> after probing to take everything sent, earliest first. Events are made while a subject catches up, so a subject nobody probes has sent nothing yet, and promptness is the host's to buy by probing. Under <code>stepMs</code> each is stamped with the end of the interval it happened in, so the events and their times do not depend on how the probes are spaced. Time taken out by <code>rebase</code> sends nothing. The exception is a stateless patch sending from <code>at</code> on a lane: a lane fills every subject the mix has met, so it sends for each of them every frame, probed or not. Sent events are not known ahead, so they stay drain-only; what is known ahead is booked.</li>
+  <li id="book"><b>What the plan knows ahead is booked against an outside clock.</b> A host that schedules on a clock of its own needs to hear about a time before it arrives: a sound on an <code>AudioContext</code>, a MIDI message sent with a timestamp, a video that has to be loaded before the voice that shows it starts. <code>mix.book</code> hands it two kinds of item: every mark <code>marks</code> lists, and a voice's <b>hits</b>, events at times on its own clock.
+<pre><code>mix.cue({ patch: spin, tags: ['sound'], hits: [{ at: 0, event: 'whoosh' }, { at: 1200, event: 'clunk' }] });
+const sound = mix.book({
+  clock: () =&gt; audio.currentTime * 1000,
+  ahead: 100,
+  late: 40,
+  tag: 'sound',
+  take(item, when) {
+    if (!('hit' in item)) return;   <span class="cm">// marks come too; this booker wants hits</span>
+    const src = play(item.event, when / 1000);
+    return { stop: () =&gt; src.stop() };
+  },
+});
+
+<span class="cm">// Not sound: load a clip 2 s before the voice that shows it starts, on the same clock as sync.</span>
+mix.book({
+  clock: () =&gt; performance.now(),
+  ahead: 2000,
+  late: Infinity,
+  tag: 'video',
+  take(item) {
+    if ('hit' in item || item.mark !== 'start') return;
+    const video = load(clips[item.name]);
+    return { stop: () =&gt; video.release() };
+  },
+});</code></pre>
+    A hit plays once per pass, for the voice and never per subject, so <code>stagger</code> does not spread it; it sits on the voice clock exactly where a mark does, through the voice's rate, ramp and seeks, its owners', and <code>mix.rate</code>. Booking runs at each <code>sync</code> and takes whatever falls within <code>ahead</code> host ms, which has to cover the longest gap between syncs. <code>when</code> is on the outside clock, by an offset that folds in 5% of each frame's difference and starts over from the clock's own reading on a jump past 50&nbsp;ms (weasel's filter). Nothing is booked twice: a mark is known by its voice and which mark, a hit by its voice, index and pass. A booking whose time moves by more than 1&nbsp;ms, or that goes away, has its <code>stop</code> called and is booked again at the same sync: a seek, a rate or ramp on the voice, an owner or the mix, a fade or <code>mute</code>, a <code>rebase</code>, an anchor's target moving, the voice leaving. A fade takes away the hits after the voice is gone, and the hits within the fade still play. An item first seen already past, from a voice cued partway through or a stalled frame, is taken at the outside clock's now with <code>lateBy</code> in host ms, unless that is more than <code>late</code>. What a seek jumps over is not late; it is skipped. Hits come as the voice clock runs forward, so a voice run backwards books none. <code>tag</code> and <code>score</code> split one mix between bookers, and <code>stop()</code> on what <code>book</code> returns stops every booking still ahead. <code>project</code> books nothing, and under <code>history</code> nothing about booking is kept or replayed: a read back says what was planned, not what was booked. A mix with no booker pays nothing for it.</li>
   <li><b>A finite loop ends when its last pass does,</b> not at the frame that notices: its fade out counts from that moment, or it turns <code>held</code> then if it holds after, so it plays the same at any frame rate and a read at another time can find it. A fade's end and a handover's deadline are kept the same way.</li>
   <li><b>Calls land on the next sync.</b> A host writes <code>handle.weight</code> or calls <code>fade</code> on its own clock; the mix applies it at the first timestamp that sees it. Nothing changes mid-frame.</li>
 </ul>
@@ -564,7 +621,7 @@ function gate&lt;I&gt;(of: Signal&lt;I&gt;, at: number): Signal&lt;I&gt;;
   <tr><td>Fade in and out</td><td><code>fade: { in, out }</code> ramps the voice's weight; each channel's <code>scale</code> takes it toward rest.</td><td>klieg's <code>Timeline.weight</code>, the <code>blendMs</code> ramps, and <code>carry</code>.</td></tr>
   <tr><td>Crossfade at a phase seam</td><td>Two voices in one <code>locus</code>, one fading out as the other fades in. The locus folds them by the channel's <code>lerp</code> at their weight ratio, which on <code>sum</code> is the lurch guard klieg's timeline applies when a hold is shorter than the blend, and on every other channel is the crossfade that guard was standing in for.</td><td>enter → active → exit as three voices.</td></tr>
   <tr><td>Handover at rest</td><td><code>fade({ at: 'rest', deadline })</code> removes the voice per subject at the first frame its pose equals rest, or at the deadline. The next voice was cued already and simply becomes the only contributor.</td><td><code>turns</code>' handover rule, made available to any pair.</td></tr>
-  <tr><td>Blend between alternatives</td><td><code>mix.blend([a, b, c], by: k)</code> cues three voices whose weights are the hat functions of k at 0, ½, 1. Continuous, no rebuild, and hinge's quantization goes away for patches whose channels have rest.</td><td><code>hinge</code>'s stops mode. Its blend mode is just <code>weight: signal</code>.</td></tr>
+  <tr><td>Blend between alternatives</td><td><code>mix.blend([a, b, c], by: k)</code> cues three voices whose weights are the hat functions of k at 0, ½, 1. Continuous, no rebuild, and hinge's quantization goes away for patches whose channels have rest. <code>by</code> is read once per subject per frame, with the setting of the first member to reach the subject, and the three shares come from that one reading, however often the host probes the subject that frame.</td><td><code>hinge</code>'s stops mode. Its blend mode is just <code>weight: signal</code>.</td></tr>
   <tr><td>Retarget on interruption</td><td><code>from: 'current'</code> on a <code>keys</code> voice takes stop 0 from the subject's pose in the frame before it first contributes &mdash; every other voice folded in, itself excluded &mdash; and lerps from there through the channel's <code>lerp</code>. It also leaves at the velocity the subject had, taken from its last two probed poses: the first segment gains <code>c·u(1−u)²</code>, which is zero at both ends and flat at the end, so the segment's own curve still lands on its stop while the start matches the subject's speed. A subject that was still leaves at rest. With fewer than two poses on record, as on a mix whose host probes into its own object before any retarget is cued, it starts on the segment's own curve.</td><td>wod's base-sampling. New to klieg: a regroup could tween from mid-float instead of carrying it away.</td></tr>
 </table></div>
 
@@ -592,7 +649,7 @@ t.to(node, 40);              <span class="cm">// from wherever it is, over a ful
   <li><b>Time is the voice's</b>, so <code>rate</code> and <code>seek</code> apply. A change takes effect at the voice time it names, or, named none, at the subject's own voice time at the mix's latest frame, whether or not the host probed it then; naming one is what makes a retarget land the same at any frame rate. A subject no frame of its voice has met yet, or still inside its stagger, takes an unnamed change at its first read, after any named change due by then. <code>read</code> with no time answers at that same latest frame, counting every change due by then, and answers nothing once the voice is gone.</li>
   <li><b>History is kept to the mix's horizon.</b> Each subject keeps every stretch a read may still reach, so a read earlier than a change finds the stretch that was playing then. A mix without <code>history</code> keeps only the stretch playing now.</li>
   <li><b>A spring or a glide settles.</b> Within <code>settle</code> (1e-4) of where it heads, and that slow, it lands there exactly, so <code>atRest</code> sees it. <code>settle: 0</code> keeps the curve exact. A tween needs none: it lands on its target exactly at <code>ms</code>.</li>
-  <li><b>The state is the patch's own</b>, per subject, rather than the mix's, because the host retargets through the patch. Cue each one on one voice. A patch moves every subject on the same number of axes, and throws on a subject, a <code>to</code> or a <code>push</code> with another, leaving the subject as it was.</li>
+  <li><b>The state is the patch's own</b>, per subject, rather than the mix's, because the host retargets through the patch. Cue each one on one voice. A patch moves every subject on the same number of axes, and throws on a subject, a <code>to</code> or a <code>push</code> with another, leaving the subject as it was. Its values are the kind its channel holds, a number for a number and an array for an array: one every subject shares is refused at <code>cue</code>, one given per subject on that subject's first sample.</li>
   <li><b>The constants are data.</b> <code>patch.motion</code>, a <code>MotionSpec</code>, is <code>{ kind: 'spring', stiffness, damping, mass, settle }</code> or <code>{ kind: 'glide', ms, settle }</code> or <code>{ kind: 'tween', ms, ease }</code>, with <code>ms</code> undefined where it varies by subject, so an engine can run one without calling <code>at</code>. Where each subject starts and heads stays on the patch, since either may be a function of the subject.</li>
   <li><b>Handing motion between patches</b> is <code>read</code> on the old one and <code>from</code> plus <code>velocity</code> on the new: a fling that ends in a spring starts the spring at the glide's velocity.</li>
 </ul>
@@ -618,6 +675,26 @@ interface Projection&lt;I, O&gt; {
   <li><b>Several scores.</b> Each source keeps its own plan: a voice's <code>score</code> names it, and the mix plays every score it holds at once, the way a DAW plays every track. Names are namespaced by score, so a bare name in an anchor means a voice in the asker's score and a query names <code>score</code> to reach into another. A voice with none is in the mix's one unnamed score.</li>
   <li><b>Waiting and following.</b> An anchor with no answer &mdash; a name not cued, the <code>out</code> of a voice that loops for good &mdash; leaves the voice <code>pending</code>. While it waits it follows its target, so a target faded early brings it forward; once it starts, its start is fixed. An <code>out</code> or <code>end</code> follows until the fade begins. A target that has left keeps the time it last gave, and can be anchored to fresh only while the mix's history reaches it. An anchored mark already past starts the voice partway through. A placement that waits on itself is refused at <code>cue</code>.</li>
   <li><b>Announced marks.</b> The host puts a named mark on a score with <code>mix.announce('reply')</code>, or <code>announce('beat', { at })</code> for one it knows ahead, and anchors target it as they target a voice's marks: a voice placed <code>{ with: 'reply' }</code> waits pending until the reply is announced. A mark announced ahead is seen by a read ahead; one not yet announced makes a read ahead say <code>held</code> for whatever waits on it, and a read back sees only what had been announced by then. An announced mark stays while it is ahead or while history reaches it. Decided 2026-10-01: a <b>mark</b> is any named time an anchor can hang from, a voice's own four or one the host announced, and an <b>event</b> is only what a patch <code>send</code>s to the host. What fires a mark on a condition, such as a channel crossing a value, stays the host's: blits does not read values.</li>
+  <li id="owners"><b>Owners.</b> <code>mix.owns(spec)</code> cues an <b>owner</b>, a voice with no patch, and a voice cued with <code>owner: handle</code> plays under it, so a group can be placed, timed and faded as one. The mix's own clock is the outermost owner, and an owner is a link in the same chain: owners nest.
+<pre><code>const intro = mix.owns({ anchor: { start: { after: 'title' } }, fade: { out: 300 }, name: 'intro' });
+mix.cue({ patch: slide, owner: intro, start: 0, name: 'slide' });
+mix.cue({ patch: glow, owner: intro, anchor: { start: { after: 'slide' } } });
+intro.rate = 0.5;   <span class="cm">// both run at half speed</span>
+intro.seek(800);    <span class="cm">// both move; their state stays where it is</span>
+intro.fade();       <span class="cm">// one envelope over both</span></code></pre>
+  <div class="tbl"><table>
+    <tr><th>On the owner</th><th>What it does to the voices it holds</th></tr>
+    <tr><td><code>start</code>, <code>anchor</code>, <code>name</code>, <code>tags</code>, <code>score</code></td><td>Place the owner on its own owner's clock, as for any voice.</td></tr>
+    <tr><td>a child's <code>start</code> and <code>anchor</code></td><td>Counted on the owner's clock, in ms from when the owner starts. With neither, a child starts where that clock is when it is cued.</td></tr>
+    <tr><td>bare names in a child's anchors</td><td>Resolve among its siblings, the voices the same owner holds. A query naming a <code>score</code> looks at any depth.</td></tr>
+    <tr><td><code>rate</code>, <code>ramp</code></td><td>Multiply into each child's own rate: a child's clock reads its owner's clock where a voice's reads the mix's.</td></tr>
+    <tr><td><code>seek</code></td><td>Moves the owner's clock, and every child's phase with it. State stays where it is, as for a voice's own seek.</td></tr>
+    <tr><td><code>weight</code> (a number or a signal), <code>fade</code></td><td>Multiply into each child's weight per subject, as the child's own fade does.</td></tr>
+    <tr><td><code>hold</code></td><td>Taken by every child with no hold of its own.</td></tr>
+    <tr><td><code>played</code>, <code>done</code></td><td><code>played</code> once every child has finished its passes. The owner leaves once it has held a voice and has none left; a fade that ends takes its children with it.</td></tr>
+    <tr><td><code>loop</code></td><td>Refused at <code>owns</code>: a pass would have to restart stateful children (decided 2026-10-04).</td></tr>
+  </table></div>
+  What stays on the mix clock is what a voice's own rate leaves there: a child's fades, its <code>dt</code> and <code>setting.timestamp</code>, as a voice at half rate still fades over its <code>fade.out</code> in mix ms. An owner's fade in counts from its start. <code>mix.voices()</code> lists owners and children alike, and <code>handle.owner</code> names a child's owner. <code>marks</code> maps a child's marks to the host clock through every owner's clock, and lists one only while every clock above it is fixed. A hit a child books sits on that same chain, so an owner's rate or seek retracts it and books it again. Under <code>history</code> an owner's control changes are kept like a voice's, so a read back or ahead composes them. On lanes a child's clock is read through its owners and their weight folded into its fade, the same arithmetic the general path takes; a child whose owner weighs by a signal runs on the general path. A mix with no owner pays nothing for them.</li>
   <li><b>What comes next.</b> <code>mix.marks(from, to)</code> lists every mark the plan has fixed in a range, with each voice's id, name and tags. One nothing has fixed is left out.</li>
   <li><b>Reading another time.</b> <code>mix.project(t)</code> copies what each subject holds and reads it at <code>t</code>, sending nothing and committing nothing, so the live mix plays on exactly as if it had not been read. Ahead, it plays what is cued forward in one step across the gap. Behind, it needs <code>history</code>: the mix keeps every voice's control changes with when they landed, the voices that have left, and a copy of each stateful record per subject every <code>every</code> ms, and a read back restores the nearest copy at or before <code>t</code> and steps forward. A subject it kept nothing for starts from its voice's start with fresh state. A patch's own <code>clone</code> copies state that <code>structuredClone</code> cannot. With <code>inputs</code>, history also keeps what each input signal on a voice's weight read per subject, and a copy of the host fields patches <code>reads</code>, each time they changed, and a read back uses those instead of asking the signal or the host. Where anchors fixed a voice's start or out after the time read, it reads back as it stood then.</li>
   <li><b>How sure.</b> <code>assess</code> says per channel <code>held</code> where a voice feeding it reads input from outside the clock with no recording of it (a signal marked <code>input</code>, a patch that <code>reads</code> host fields, or a <code>from: 'current'</code> start read back with nothing kept), <code>stepped</code> where state crossed a gap in one go without <code>stepMs</code>, or a stateful signal did, and <code>exact</code> otherwise. The least sure voice decides. Under <code>stepMs</code> a read back lands on the pose the mix showed, so a scrub back and forth gives the same picture.</li>
@@ -664,14 +741,15 @@ export const mixer: Engine;   <span class="cm">// the one that ships</span></cod
   <tr><th></th><th>runs on a lane</th><th>takes the general path</th></tr>
   <tr><td>channel</td><td><code>sum</code>, <code>mul</code>, <code>max</code>, and <code>vec</code> over one of them, as the stock functions make them, bounds or not</td><td>anything else, including a custom channel claiming a stock kind</td></tr>
   <tr><td>patch</td><td><code>keys</code>; <code>fn</code> with no <code>state</code> and no <code>step</code>; <code>motion</code></td><td>a stateful <code>fn</code>, or one once it calls <code>setting.keep</code>; <code>keys</code> whose <code>lerpBy</code> is not the channel's own <code>lerp</code>; under <code>history.inputs</code>, a patch that <code>reads</code> host fields</td></tr>
-  <tr><td>voice</td><td>a number weight, with fades and <code>mute</code>; every subject, <code>target</code> or <code>subjects</code>; <code>stagger</code>, <code>loop</code>, <code>rate</code>, <code>ramp</code>, <code>seek</code>, anchors</td><td>a <code>Signal</code> weight, <code>locus</code>, <code>from: 'current'</code>, <code>fade({ at: 'rest' })</code></td></tr>
+  <tr><td>voice</td><td>a number weight, with fades and <code>mute</code>; a <code>Signal</code> weight that keeps no state, weighed for each subject by the general path&rsquo;s own <code>weigh</code>; every subject, <code>target</code> or <code>subjects</code>; <code>stagger</code>, <code>loop</code>, <code>rate</code>, <code>ramp</code>, <code>seek</code>, anchors</td><td>a <code>Signal</code> weight once it calls <code>setting.keep</code>, which the stock stateful signals do from their first call, made by the general path; under <code>history.inputs</code>, a signal reading host input; a <code>locus</code> with a motion member, or any member that cannot run on a lane, which takes every member with it; <code>from: 'current'</code>, <code>fade({ at: 'rest' })</code></td></tr>
 </table></div>
-<p>A channel is a lane only while every voice writing it qualifies, and a voice runs on lanes only while every channel it writes is one, so no patch is called twice in a frame. The mix works this out again when a voice is cued or retires, starts a fade to rest, or first keeps state; never per probe. A voice that names one subject and writes one laned channel is the exception: it joins its channel&rsquo;s crowd, below, or leaves it, without the mix qualifying anything again, since a voice that fits joining laned channels and a laned voice leaving cannot move the fixed point. Such a voice also relinks only its own subject&rsquo;s chain, and only a voice over every subject makes every subject meet the lanes again. A projection always reads through the general path.</p>
+<p>A channel is a lane only while every voice writing it qualifies, and a voice runs on lanes only while every channel it writes is one, so no patch is called twice in a frame. The mix works this out again when a voice is cued or retires, starts a fade to rest, or first keeps state; never per probe. A voice that names one subject and writes only laned channels is the exception: it joins the crowd of voices writing those channels, below, or leaves it, without the mix qualifying anything again, since a voice that fits joining laned channels and a laned voice leaving cannot move the fixed point. Such a voice also relinks only its own subject&rsquo;s chain, and only a voice over every subject makes every subject meet the lanes again. A projection always reads through the general path.</p>
 <ul>
   <li><b>Subjects are numbered on first sight.</b> A subject's first probe takes the general path, where <code>target</code>, <code>stagger</code> and the fade-in origin are worked out, and gives it a number; so does each voice's first meeting with it later. <code>drop</code> frees the number, and for an object subject so does the host letting it go. A subject the host never probes is never numbered and costs a lane nothing.</li>
   <li><b>The first probe after a <code>sync</code> fills every lane</b>, for every numbered subject each laned voice reaches, then copies the subject's values into the pose; later probes that frame only copy. A cue, retirement or handle change between two probes refills at the next one. So a frame costs the fill plus a probe per subject the host reads.</li>
   <li><b>A lane rests while its subjects go unprobed.</b> When fewer than 15% of a <code>keys</code> lane's subjects were probed in the last frame with a probe, or fewer than 60% of a <code>fn</code> or <code>motion</code> lane's, the lane stops filling and probes of its subjects take the general path; it fills again once that share reaches 25%, or 80%. Those lines sit either side of where filling and probing break even, measured at 1,000 and 10,000 subjects: about 19% for <code>keys</code>, 71&ndash;77% for a spring, and 63&ndash;100% for a stateless <code>fn</code>. Both paths give the same pose, so the switch only changes the cost.</li>
-  <li><b>Single-subject voices share a crowd.</b> A laned voice whose <code>subjects</code> names one subject and that writes one channel does not get a lane of its own: every such voice on a channel is a row in one crowd, in voice order, holding the per-subject numbers a lane keeps and a copy of what a fill reads of the voice (clock, rate, weight) and of its current stretch. The voice&rsquo;s copy is rewritten when a handle or the mix changes the voice; the stretch&rsquo;s when the patch replaces it (<code>Motions.touched</code>). A fill reads the crowd&rsquo;s flat arrays and calls the same <code>closed</code> forms, and folds each row between the lanes on either side of its voice, so the order of the fold, and so its bits, are the general path&rsquo;s. A row with a fade, a ramp, a change pending or a probe already this frame takes the per-subject step instead. Measured on teitou against the build before (2026-10-03, three alternated passes of <code>bench/frame.mjs</code>): 10k tween voices of one subject each cost 0.54&ndash;0.59 of what they did, as much as one tween voice over the same 10k subjects; 100k cost 0.31&ndash;0.33; 10k springs 0.64&ndash;0.70. Before it, the extra cost of a voice over a shared voice grew with the count, 18&nbsp;ns at 1k, 48 at 10k, 226 at 100k (<code>bench/split.mjs</code>): the fill was bound by memory, a <code>Voice</code>, a <code>Lane</code> and a patch buffer per voice. A <code>keys</code> or stateless <code>fn</code> row reads its voice the same way and then does what a lane does for one subject: reads the stops, or calls the patch through the same function a lane calls it through. Rows join at the end as voices are cued, so they stay in voice order; a retired voice&rsquo;s row is left empty until the crowd is more than half empty rows, when the next probe qualifies again and rebuilds it. Measured on teitou against the build before (2026-10-03, five alternated passes, ms a frame): 10k <code>keys</code> voices of one subject each by probe 1.30&ndash;1.89 from 1.60&ndash;1.77, and by <code>pull</code> 1.25&ndash;2.01 from 1.71&ndash;1.84, both bimodal from run to run; 10k <code>fn</code> voices by <code>pull</code> 0.93&ndash;1.18 from 1.36&ndash;1.52, and by probe 1.20&ndash;1.43 against 1.09&ndash;1.21, which a profiled run reversed. Reading the stops as flat numbers instead of through <code>readKeys</code> was tried and measured no different. With one of 10k tween voices stopped, its subject dropped and another cued every frame (<code>churn</code>), a frame costs 0.91&ndash;1.01&nbsp;ms by probe and 0.54&ndash;0.62 by <code>pull</code>, from 9.82&ndash;9.94 and 8.73&ndash;9.07. A voice naming several subjects, or one naming one and writing several channels, still has a lane of its own, which a stateless <code>fn</code> or <code>keys</code> one leaves idle: its subject takes the general path.</li>
+  <li><b>Single-subject voices share a crowd.</b> A laned voice whose <code>subjects</code> names one subject does not get a lane of its own, since it shares nothing across subjects for a lane to save: every such voice writing the same channels is a row in one crowd, in voice order. A motion voice writes one channel; a <code>keys</code> or stateless <code>fn</code> voice may write several. Crowds that share a channel take turns in voice order as a fill runs them, so a subject&rsquo;s rows fold in the order the general path folds them. A row holds the per-subject numbers a lane keeps and a copy of what a fill reads of the voice (clock, rate, weight) and of its current stretch. The voice&rsquo;s copy is rewritten when a handle or the mix changes the voice; the stretch&rsquo;s when the patch replaces it (<code>Motions.touched</code>). A fill reads the crowd&rsquo;s flat arrays and calls the same <code>closed</code> forms, and folds each row between the lanes on either side of its voice, so the order of the fold, and so its bits, are the general path&rsquo;s. A row with a fade, a ramp, a change pending or a probe already this frame takes the per-subject step instead. Measured on teitou against the build before (2026-10-03, three alternated passes of <code>bench/frame.mjs</code>): 10k tween voices of one subject each cost 0.54&ndash;0.59 of what they did, as much as one tween voice over the same 10k subjects; 100k cost 0.31&ndash;0.33; 10k springs 0.64&ndash;0.70. Before it, the extra cost of a voice over a shared voice grew with the count, 18&nbsp;ns at 1k, 48 at 10k, 226 at 100k (<code>bench/split.mjs</code>): the fill was bound by memory, a <code>Voice</code>, a <code>Lane</code> and a patch buffer per voice. A <code>keys</code> or stateless <code>fn</code> row reads its voice the same way and then does what a lane does for one subject: reads the stops, or calls the patch through the same function a lane calls it through. Rows join at the end as voices are cued, so they stay in voice order; a retired voice&rsquo;s row is left empty until the crowd is more than half empty rows, when the next probe slides the rows left down over the empty ones, in order. Rebuilding the crowds through a full qualify instead made that one frame about 9&nbsp;ms at 10k rows; sliding them keeps the worst of 12,000 <code>churn</code> frames near 3&nbsp;ms, which is collection (teitou, 2026-10-04). Measured on teitou against the build before (2026-10-03, five alternated passes, ms a frame): 10k <code>keys</code> voices of one subject each by probe 1.30&ndash;1.89 from 1.60&ndash;1.77, and by <code>pull</code> 1.25&ndash;2.01 from 1.71&ndash;1.84, both bimodal from run to run; 10k <code>fn</code> voices by <code>pull</code> 0.93&ndash;1.18 from 1.36&ndash;1.52, and by probe 1.20&ndash;1.43 against 1.09&ndash;1.21, which a profiled run reversed. Folding each row's segment straight into the lanes, through the same search <code>readKeys</code> makes, rather than through a delta, took 10k such rows read by <code>pull</code> to 0.74 of their time and by probe to 0.85 (teitou, 2026-10-04). A row's stops are now copied as it joins into one array the crowd keeps for all its rows, phase, then value per axis, so a fill reads them in place rather than through the row's voice, its tracks and each stop's own array; the search is still the one <code>segment</code> makes. A row whose stops are not plain numbers on the channel's axes reads them through its voice as before. That took 10k such rows read by <code>pull</code> from 0.66&ndash;1.02&nbsp;ms a frame to 0.34&ndash;0.36, 34&ndash;36&nbsp;ns a subject against 25 a subject and voice for keys voices over every subject, and by probe from 1.00&ndash;1.37 to 0.81&ndash;0.83 (teitou, 2026-10-05). Copying the stops into each voice's own flat arrays, with the row still reaching them through its voice, had measured no different. With one of 10k tween voices stopped, its subject dropped and another cued every frame (<code>churn</code>), a frame costs 0.91&ndash;1.01&nbsp;ms by probe and 0.54&ndash;0.62 by <code>pull</code>, from 9.82&ndash;9.94 and 8.73&ndash;9.07. A <code>fn</code> voice of one subject writing two channels, which took the general path before crowds took several channels, reads at 0.65&times; at 1k voices and 0.79&times; at 10k, and 1.05&ndash;1.11&times; at 100, where a fill&rsquo;s bookkeeping costs more than the general path it saves (rows <code>named</code>, teitou, 2026-10-04). A voice naming several subjects has a lane of its own.</li>
+  <li><b>A locus runs on lanes in two passes.</b> The general path folds a locus at its first member&rsquo;s place in the voice order, and which voice that is differs by subject. So a fill first takes each locus&rsquo;s members in voice order and, for each subject, sums their weights and lerps their values by share of the weight taken, as <code>foldLocus</code> does, with the stock channels&rsquo; own lerp; then, folding the voices in order, it folds each subject&rsquo;s locus in at whichever member met that subject first. A locus&rsquo;s members are on lanes all together or not at all, since a member left on the general path would count in its sum there but not on a lane; a motion member keeps the whole locus off. A blend&rsquo;s signal is read by whichever member fills a subject first, and kept by subject number for the others. On teitou (2026-10-04) three voices in a locus over 10k subjects take 0.72 of the time they did on the general path, and <code>mix.blend</code> of three by a stateless signal 0.84.</li>
   <li><b><code>sync</code> visits only the voices with something due.</b> Each live voice sits in a heap by the earliest mix time a sync would change it: its start, its anchored out, the end of its last pass, the end of a fade or of a subject&rsquo;s ramp out. A handle change that could bring that earlier files it again. A voice whose time cannot be put ahead, one fading to rest or held and running backwards, is visited every frame. <code>test/due.test.ts</code> plays random mixes both ways, against a full walk, and compares states, poses and marks after every sync.</li>
   <li><b>Lanes give the same pose, to the bit.</b> Both paths call the same functions for phase, envelope, weight clamp, each stock channel's fold, the easing curves and the spring solver, and clamp <code>bounds</code> the same way after. <code>test/lanes.test.ts</code> runs every case both ways and compares each probe with <code>Object.is</code>. <code>weightOf</code>, <code>atRest</code> and a finite loop's end read what the fill keeps.</li>
   <li><b>Two things differ, both documented on the API.</b> A stateless patch calling <code>setting.send</code> from <code>at</code> sends every frame for every subject a lane fills, probed or not. A patch that first calls <code>setting.keep</code> partway through playing, from a call for a subject the host did not probe that frame, advances that state once more for that subject than the general path would; a patch that keeps state from its first call, or declares <code>state</code>, never does.</li>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msb235/blits",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Concurrent effects: each on its own clock with its own state and weight, folded into one value per subject per frame",
   "keywords": [
     "animation",
@@ -45,7 +45,10 @@
     "bench": "npm run build && node bench/frame.mjs",
     "site": "npm run dev -w site",
     "site:build": "npm run build -w site",
-    "site:smoke": "npm run smoke -w site"
+    "site:smoke": "npm run smoke -w site",
+    "playground": "npm run dev -w @blits/playground",
+    "playground:smoke": "npm run smoke -w @blits/playground",
+    "playground:check": "npm run typecheck -w @blits/playground && vitest run apps/playground/test && npm run playground:smoke"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.8",