@msb235/blits 0.15.0 → 0.15.1

package/dist/strays.js

@@ -1,3 +1,4 @@
+import { delayOf } from './delay.js';
 import { unpart } from './fade.js';
 import { pageOut } from './paging.js';
 import { record, taping, unplayable } from './tape.js';
@@ -75,7 +76,7 @@ export function motionOwner(mix) {
                 return Number.NaN;
             unpart(m, v, subject);
             // Its record is gone until it is next read, so its stagger is asked here as it will be there.
-            return timeIn(m, v, v.spec.stagger ? v.spec.stagger(subject) : 0);
+            return timeIn(m, v, delayOf(v, subject));
         },
     };
 }
@@ -107,7 +108,7 @@ function changeAhead(to, id, motion, given, change) {
             unpart(to, v, subject);
         if (at === undefined) {
             const frame = frameOf(to, v, subject);
-            const back = parted ? timeIn(to, v, v.spec.stagger ? v.spec.stagger(subject) : 0) : frame;
+            const back = parted ? timeIn(to, v, delayOf(v, subject)) : frame;
             if (!Number.isNaN(frame))
                 at = frame;
             else if (!Number.isNaN(back))

package/dist/trace.d.ts

@@ -0,0 +1,4 @@
+import type { Mixer } from './mixer.js';
+import type { Trace, TraceOptions } from './types.js';
+/** `mix.trace`: see `Mix.trace`. */
+export declare function traceMix<I, O>(mix: Mixer<I, O>, from: number, to: number, opts?: TraceOptions): Trace<I, O>;

package/dist/trace.js

@@ -0,0 +1,255 @@
+import { straight } from './easing.js';
+/**
+ * How far inside a sampled stretch its ends are read, ms, but for the window's own: a stretch ends
+ * where a voice may jump, and its end is read on its own side of the jump.
+ */
+const NUDGE = 1e-6;
+/** Two values at one time this close are one point, not a jump. */
+const close = (a, b) => Math.abs(a - b) <= 1e-6 * Math.max(1, Math.abs(a), Math.abs(b));
+/** `mix.trace`: see `Mix.trace`. */
+export function traceMix(mix, from, to, opts = {}) {
+    if (!(from <= to) || !Number.isFinite(from) || !Number.isFinite(to))
+        throw new RangeError(`blits: a trace runs from a time to one no earlier, not ${from} to ${to}`);
+    const grid = opts.grid ?? 5;
+    if (!(grid > 0 && grid < Number.POSITIVE_INFINITY))
+        throw new RangeError(`blits: a trace's grid is a finite number of ms above 0, not ${grid}`);
+    const known = knowable(mix, from);
+    const projections = new Map();
+    const poses = new Map();
+    const plans = new Map();
+    const poseAt = (subject, t) => {
+        let mine = poses.get(subject);
+        if (mine === undefined) {
+            mine = new Map();
+            poses.set(subject, mine);
+        }
+        let pose = mine.get(t);
+        if (pose === undefined) {
+            let p = projections.get(t);
+            if (p === undefined) {
+                p = mix.project(t);
+                projections.set(t, p);
+            }
+            pose = p.probe(subject, mix.pose());
+            mine.set(t, pose);
+        }
+        return pose;
+    };
+    return {
+        from,
+        to,
+        of(subject, channel) {
+            const name = channel;
+            const slot = mix.slotOf.get(name);
+            if (slot === undefined)
+                throw new Error(`blits: the mix has no channel ${name}`);
+            const value = (t) => {
+                const v = poseAt(subject, t)[name];
+                return typeof v === 'number' ? v : Number.NaN;
+            };
+            let plan = plans.get(subject);
+            if (plan === undefined) {
+                plan = planOf(mix, subject, from, to);
+                plans.set(subject, plan);
+            }
+            const op = mix.scalars[slot];
+            const shaped = known &&
+                !plan.unknown.has(slot) &&
+                !mix.bounded.includes(slot) &&
+                (op === 'sum' || (op === 'mul' && (plan.writers.get(slot) ?? 0) <= 1));
+            const bent = plan.bent.get(slot);
+            const straightOver = (a, b) => shaped && (bent === undefined || bent.every(([lo, hi]) => !(lo < b && hi > a)));
+            if (from === to)
+                return { at: [from], value: [value(from)], exact: shaped };
+            const at = [];
+            const values = [];
+            let exact = true;
+            const add = (t, v) => {
+                const n = at.length;
+                if (n > 0 && at[n - 1] === t && close(values[n - 1], v))
+                    values[n - 1] = v;
+                else {
+                    at.push(t);
+                    values.push(v);
+                }
+            };
+            const knots = [from, ...(plan.knots.get(slot) ?? []), to];
+            for (let i = 0; i + 1 < knots.length; i++) {
+                const a = knots[i];
+                const b = knots[i + 1];
+                if (straightOver(a, b)) {
+                    // Read inside, so a jump at either end is not read; the line reaches each end exactly.
+                    const t1 = a + (b - a) / 3;
+                    const t2 = b - (b - a) / 3;
+                    const v1 = value(t1);
+                    const slope = (value(t2) - v1) / (t2 - t1);
+                    add(a, v1 - slope * (t1 - a));
+                    add(b, v1 + slope * (b - t1));
+                    continue;
+                }
+                exact = false;
+                const e = Math.min(NUDGE, (b - a) / 4);
+                add(a, value(a === from ? a : a + e));
+                for (let k = Math.max(0, Math.ceil((a - from) / grid));; k++) {
+                    const g = from + k * grid;
+                    if (g >= b - e)
+                        break;
+                    if (g > a + e)
+                        add(g, value(g));
+                }
+                add(b, value(b === to ? b : b - e));
+            }
+            return { at, value: values, exact };
+        },
+    };
+}
+/**
+ * Whether the mix's own state lets a trace know any shape: a window at or after the mix's time,
+ * with no recorded call ahead.
+ */
+function knowable(mix, from) {
+    const transport = mix.transport;
+    if (!(from >= mix.now))
+        return false;
+    const tape = transport.tape;
+    return tape === undefined || tape.timestampAt(tape.undoDepth()) === undefined;
+}
+function planOf(mix, subject, from, to) {
+    const plan = { knots: new Map(), bent: new Map(), unknown: new Set(), writers: new Map() };
+    for (const voice of mix.cued) {
+        if (voice.state === 'done' || !mix.aims(voice, subject))
+            continue;
+        if (shapeOf(mix, voice, subject, from, to, plan))
+            continue;
+        for (const slot of voice.slots)
+            plan.unknown.add(slot);
+    }
+    for (const [slot, knots] of plan.knots)
+        plan.knots.set(slot, knots.sort((a, b) => a - b).filter((t, i, all) => i === 0 || t !== all[i - 1]));
+    return plan;
+}
+/** The most breakpoints one voice may add to a window before it is read on the grid instead. */
+const MOST = 4096;
+/**
+ * Adds a voice's breakpoints for one subject to `plan`, and returns true, where its shape is known
+ * through the window: a `keys` voice on its own clock at a steady rate and a number weight. Returns
+ * false, adding nothing, for any other.
+ */
+function shapeOf(mix, voice, subject, from, to, plan) {
+    const spec = voice.spec;
+    const built = voice.built;
+    const patch = voice.patch;
+    if (patch.form !== 'keys' || built === null || patch.step !== undefined)
+        return false;
+    if (typeof spec.weight === 'function' || voice.owner !== null || voice.holding !== null)
+        return false;
+    if (voice.fitting !== null || voice.arc !== null || voice.blend !== null)
+        return false;
+    if (spec.anchor !== undefined || spec.role !== undefined || spec.within !== undefined)
+        return false;
+    if (spec.stepMs !== undefined || spec.from !== undefined)
+        return false;
+    if (voice.ramp !== null || !(voice.rate > 0) || voice.out !== null || voice.back !== null)
+        return false;
+    if (voice.parts !== null || voice.parted !== null || voice.left !== null)
+        return false;
+    if (Number.isFinite(voice.outAt) || voice.state === 'fading')
+        return false;
+    // Under a mix rate, a waiting voice's start is pinned to the host's clock, where a ramp moves it.
+    if (voice.state === 'pending' && mix.transport.pace !== null)
+        return false;
+    const knots = [];
+    const bent = [];
+    const bentBy = new Map();
+    const at = (t) => {
+        if (t > from && t < to)
+            knots.push(t);
+    };
+    const reduced = mix.reduced;
+    const held = voice.sharing ? undefined : voice.subjects.get(subject);
+    const delay = held?.delay ?? (spec.stagger ? spec.stagger(subject) : 0);
+    const time = (raw) => voice.timeAt(raw + delay);
+    const fadeIn = reduced ? 0 : (voice.fade.in ?? 0);
+    if (fadeIn > 0) {
+        // Where its fade in counts from is known only once the subject has met the voice.
+        if (held === undefined)
+            return false;
+        if (held.shown + fadeIn > from) {
+            bent.push([held.shown, held.shown + fadeIn]);
+            at(held.shown);
+            at(held.shown + fadeIn);
+        }
+    }
+    const duration = voice.duration;
+    const span = voice.span;
+    at(voice.start);
+    at(time(0));
+    if (Number.isFinite(span))
+        at(time(span));
+    const ends = voice.endsAt();
+    at(ends);
+    if (!voice.freezesAfter && Number.isFinite(ends)) {
+        const over = reduced ? 0 : Number.isNaN(voice.outOver) ? (voice.fade.out ?? 0) : voice.outOver;
+        if (over > 0) {
+            bent.push([ends, ends + over]);
+            at(ends + over);
+        }
+        // It leaves when its latest subject ends, which a subject first met later can move.
+        if (spec.stagger !== undefined)
+            bent.push([time(span), Number.POSITIVE_INFINITY]);
+    }
+    if (duration > 0) {
+        const first = Math.max(0, Math.floor((voice.elapsedAt(from) - delay) / duration));
+        const last = Math.min(Math.ceil(voice.passes) - 1, Math.floor((voice.elapsedAt(to) - delay) / duration));
+        let stops = 0;
+        for (const track of built.tracks)
+            stops += track.all.length + 1;
+        if ((last - first + 1) * stops > MOST)
+            return false;
+        for (let pass = first; pass <= last; pass++) {
+            const base = pass * duration;
+            at(time(base));
+            at(time(base + duration));
+            for (const track of built.tracks) {
+                const slot = mix.slotOf.get(track.channel);
+                if (track.numbers === null)
+                    return false;
+                const wait = track.delay;
+                if (wait >= duration)
+                    continue;
+                if (wait > 0)
+                    at(time(base + wait));
+                let before = Number.NaN;
+                for (const pt of track.all) {
+                    const t = time(base + wait + Math.min(1, Math.max(0, pt.at)) * (duration - wait));
+                    at(t);
+                    if (!Number.isNaN(before) && !straight(pt.ease)) {
+                        const list = bentBy.get(slot);
+                        if (list === undefined)
+                            bentBy.set(slot, [[before, t]]);
+                        else
+                            list.push([before, t]);
+                    }
+                    before = t;
+                }
+            }
+        }
+    }
+    for (const slot of voice.slots) {
+        const times = plan.knots.get(slot);
+        if (times === undefined)
+            plan.knots.set(slot, [...knots]);
+        else
+            times.push(...knots);
+        plan.writers.set(slot, (plan.writers.get(slot) ?? 0) + 1);
+        const mine = [...bent, ...(bentBy.get(slot) ?? [])];
+        if (mine.length === 0)
+            continue;
+        const list = plan.bent.get(slot);
+        if (list === undefined)
+            plan.bent.set(slot, mine);
+        else
+            list.push(...mine);
+    }
+    return true;
+}

package/dist/types/mix.d.ts

@@ -3,6 +3,7 @@ import type { Kit } from './channel.js';
 import type { HistoryOptions, Tape } from './history.js';
 import type { Band, Easing, Patch, Sent, Signal } from './patch.js';
 import type { Booker, BookOptions, Marked } from './place.js';
+import type { Trace, TraceOptions } from './trace.js';
 import type { Transport } from './transport.js';
 import type { BlendMember, Circle, Handle, OwnerSpec, SpanHandle, SpanSpec, VoiceSpec } from './voice.js';
 /**
@@ -250,6 +251,20 @@ export interface Mix<I, O, H = unknown> {
     project(at: number | {
         readonly frame: number;
     }): Projection<I, O>;
+    /**
+     * Reads the mix over a window of mix time, `from` to `to`, without moving it, as `project` reads
+     * one moment: `trace.of(subject, channel)` gives that channel as points joined by straight lines.
+     * Where every voice feeding the channel is a `keys` voice whose shape is known through the
+     * window, the points are its own breakpoints and the lines are exact; elsewhere the run is read
+     * every `grid` ms, as many `project` calls would read it.
+     *
+     * Exact needs, of each voice reaching the subject and writing the channel: a `keys` patch whose
+     * stops are plain numbers, eased `linear`; a number weight; no owner, anchor, role, blend,
+     * `within`, `stepMs`, `from: 'current'`, or rate ramp; a fade in finished by `from` and no fade
+     * out under way or due. The channel folds by `sum`, or by `mul` from one such voice, and has no
+     * `bounds`. The window lies at or after the mix's own time, and the tape holds no calls ahead.
+     */
+    trace(from: number, to: number, opts?: TraceOptions): Trace<I, O>;
     /**
      * Moves the mix to mix time `time` and plays on from there. It lands as the mix stood at the end
      * of that frame; where rate 0 held the clock at `time` for several frames, the last of them.

package/dist/types/trace.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What `mix.trace` takes besides its window.
+ *
+ * @category mix
+ */
+export interface TraceOptions {
+    /**
+     * Where a run cannot be known exactly, how far apart it is read, in ms of mix time. Default 5.
+     */
+    grid?: number;
+}
+/**
+ * One channel of one subject over a trace's window, as points joined by straight lines: the value
+ * between two points is the straight line between them. Two points at one time are a jump, from
+ * the first value to the second. The first point is at the window's start and the last at its end.
+ *
+ * @category mix
+ */
+export interface Run {
+    /** Mix times, ascending; a time given twice is a jump. */
+    readonly at: readonly number[];
+    /** The channel's value at each of `at`; NaN where it holds no number. */
+    readonly value: readonly number[];
+    /**
+     * Whether the lines are the mix's own values everywhere in the window, not only at the points.
+     * Where they are not, the points are each `grid` apart and the lines between them approximate.
+     */
+    readonly exact: boolean;
+}
+/**
+ * The channels of `O` that hold one number.
+ *
+ * @category mix
+ */
+export type NumberChannel<O> = {
+    [K in keyof O]-?: NonNullable<O[K]> extends number ? K : never;
+}[keyof O];
+/**
+ * The mix read over a window of mix time, with nothing in the live mix moved. Valid until the mix
+ * is next synced or cued.
+ *
+ * @category mix
+ */
+export interface Trace<I, O> {
+    /** The window's start, in mix time. */
+    readonly from: number;
+    /** The window's end, in mix time. */
+    readonly to: number;
+    /** One subject's channel over the window. */
+    of(subject: I, channel: NumberChannel<O>): Run;
+}

package/dist/types/trace.js

@@ -0,0 +1 @@
+export {};

package/dist/types/voice.d.ts

@@ -135,13 +135,16 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
     /**
      * How many passes the voice plays. true loops for good, false plays one pass, n plays n passes.
      * A finite loop leaves when its
-     * passes are done for the latest-staggered subject it has seen — over `fade.out` where one is
-     * set, at once where none is — unless it freezes after. Default: false.
+     * passes are done for its latest-staggered subject — over `fade.out` where one is set, at once
+     * where none is — unless it freezes after. Default: false.
      */
     loop?: boolean | number;
     /**
      * Per-subject delay in voice ms. It is klieg's stagger grammar reduced to the one thing the mix
-     * needs. Like `target`, it runs once per subject on first sight, and the answer is kept.
+     * needs. It runs once per subject and the answer is kept: at `cue` for every subject a voice
+     * names in `subjects`, else, like `target`, on first sight. So a voice naming its subjects ends by
+     * all of them, and one reaching them by `target` ends by those the mix has been asked about: a
+     * subject first read later than that sees a finite loop already over.
      */
     stagger?: (subject: I) => number;
     /**
@@ -373,7 +376,8 @@ export interface SubjectFade<I = unknown> {
     /**
      * The one subject to fade out of this voice, which plays on for the rest. Once the ramp ends
      * the voice forgets the subject and reaches it no more, until a motion patch's `to` or `push`
-     * or the mix's `drop` brings it back, met afresh: `from`, `target` and `stagger` asked again.
+     * or the mix's `drop` brings it back, met afresh: `from` and `target` asked again, and
+     * `stagger` too unless the voice names its `subjects`.
      */
     subject: I;
     /** The ramp, ms. Defaults to the voice's own `fade.out`; 0 takes the subject out at once. */
@@ -466,7 +470,8 @@ export interface Handle<I = unknown> {
     readonly done: Promise<void>;
     /**
      * Resolves true when a finite loop's last pass ends, false if the voice leaves before that. The
-     * last pass is the one for the latest-staggered subject it has seen. Never rejects.
+     * last pass is the one for its latest-staggered subject; `stagger` says which subjects count.
+     * Never rejects.
      */
     readonly played: Promise<boolean>;
 }

package/dist/types.d.ts

@@ -5,6 +5,7 @@ export type * from './types/mix.js';
 export type * from './types/motion.js';
 export type * from './types/patch.js';
 export type * from './types/place.js';
+export type * from './types/trace.js';
 export type * from './types/transport.js';
 export type * from './types/voice.js';
 export type * from './types/watch.js';

package/dist/unreached.d.ts

@@ -3,3 +3,5 @@ import type { Voice } from './voice.js';
 export declare function unreached<I, O>(voice: Voice<I, O>, slot: number): boolean;
 /** Marks or clears the subject numbered `slot` as one the voice does not reach. */
 export declare function unreach<I, O>(voice: Voice<I, O>, slot: number, on: boolean): void;
+/** The subject numbered `from` is numbered `to` now, a number let go of: its mark moves along. */
+export declare function reunreach<I, O>(voice: Voice<I, O>, from: number, to: number): void;

package/dist/unreached.js

@@ -22,3 +22,10 @@ export function unreach(voice, slot, on) {
     const bit = 1 << (slot & 31);
     bits[word] = on ? bits[word] | bit : bits[word] & ~bit;
 }
+/** The subject numbered `from` is numbered `to` now, a number let go of: its mark moves along. */
+export function reunreach(voice, from, to) {
+    if (!unreached(voice, from))
+        return;
+    unreach(voice, to, true);
+    unreach(voice, from, false);
+}

package/dist/voice.d.ts

@@ -9,6 +9,7 @@ import { Named } from './named.js';
 import type { Past } from './origin.js';
 import { Holding } from './owner.js';
 import { type Built, intosOf, type Scratch } from './patch.js';
+import type { Seat } from './seat.js';
 import { VoiceSetting } from './setting.js';
 import type { Fitting } from './spans.js';
 import { Store } from './store.js';
@@ -101,6 +102,8 @@ export declare class Voice<I, O> {
     holder: Subject<unknown> | null;
     /** Whether its channels run as lanes this frame, so the general fold passes it by. */
     laned: boolean;
+    /** Its crowd row, while its channels run in a crowd. */
+    seat: Seat<I, O> | null;
     /**
      * How many times it has been sought or touched, so a delta read before either is not handed out
      * after it.

package/dist/voice.js

@@ -72,6 +72,8 @@ export class Voice {
     holder = null;
     /** Whether its channels run as lanes this frame, so the general fold passes it by. */
     laned = false;
+    /** Its crowd row, while its channels run in a crowd. */
+    seat = null;
     /**
      * How many times it has been sought or touched, so a delta read before either is not handed out
      * after it.
@@ -358,8 +360,8 @@ export class Voice {
         this.dueToken++;
         this.early = null;
         this.seen = 0;
-        this.latest = 0;
-        this.soonest = 0;
+        this.latest = this.named?.latest ?? 0;
+        this.soonest = this.named?.soonest ?? 0;
         this.restedCount = 0;
         this.cuedAt = Number.NEGATIVE_INFINITY;
         this.cuedSeq = Number.NEGATIVE_INFINITY;
@@ -393,7 +395,10 @@ export class Voice {
         this.holding = patch === ownerPatch ? new Holding() : null;
         const wrote = writing(patch.writes, slotOf, channels);
         this.slots = wrote.slots;
-        this.named = spec.subjects ? new Named(spec.subjects) : null;
+        this.named = spec.subjects ? new Named(spec.subjects, spec.stagger) : null;
+        // Every subject's stagger is known at cue, so a finite loop ends by them all, read or not.
+        this.latest = this.named?.latest ?? 0;
+        this.soonest = this.named?.soonest ?? 0;
         this.built = patch.form === 'keys' && patch.keys ? builtOf(patch) : null;
         this.lerps = wrote.lerps;
         this.intos = this.built
@@ -567,6 +572,7 @@ export class Voice {
         v.scratch = [];
         v.holder = null;
         v.laned = false;
+        v.seat = null;
         v.log = null;
         v.early = null;
         if (controls)

package/docs/schema.html

@@ -928,6 +928,7 @@ for (const step of steps) mix.arc({ owner: program, active: stage(step), hold: 4
   </ul></li>
   <li><b>What comes next.</b> <code>mix.marks(from, to)</code> lists every mark the plan has fixed in a range, a voice's five and those placed inside it, 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, stopping at each known event on the way (see <b>Reading ahead at known events</b> below). Behind, it reads from <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. Without <code>history</code> a read back works only where how the mix stands now says what it showed then: every voice plays as it was cued and reads by its clock alone, the mix's rate was never set, and <code>t</code> is no earlier than the last cue, <code>drop</code>, <code>touch</code>, <code>announce</code>, or <code>rebase</code>, or the last frame a voice left in; anywhere else it throws and says why. 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 id="trace"><b>Reading over a window.</b> <code>mix.trace(from, to, { grid })</code> reads the mix from mix time <code>from</code> to <code>to</code>, moving nothing, and <code>trace.of(subject, channel)</code> gives one channel holding a number as a run: times and values, joined by straight lines, with a time given twice for a jump. Where every voice feeding the channel has a shape known through the window, the run's points are its breakpoints and the lines are the mix's own values, and <code>exact</code> says so; elsewhere the run is read every <code>grid</code> ms (default 5), as that many <code>project</code> calls would read it. A known shape is a <code>keys</code> voice with plain number stops eased <code>linear</code>, a number weight, a steady rate, and no owner, anchor, role, blend, <code>within</code>, <code>stepMs</code> or <code>from: 'current'</code>; its fade in finished by <code>from</code>, and no fade out under way or set. The channel folds by <code>sum</code>, or by <code>mul</code> from one such voice, with no <code>bounds</code>. The window starts at or after the mix's own time, and the tape holds no call ahead. Every value still comes from <code>project</code>: the trace only chooses where to read, and which stretches a line may join. One trace shares its reads among the subjects asked about. blits-tone schedules its curves from it.</li>
   <li id="seek"><b>Seeking.</b> <code>mix.seek(t)</code> moves the live mix to mix time <code>t</code>, as it stood at the end of that frame, and it plays on from there. It needs <code>history</code> with a <code>tape</code>, and reaches back as far as a read back does. <code>history.tape</code> takes weasel-history's <code>createHistory</code> from <code>@weasel-js/history</code>, or anything of the <code>Tape</code> shape, and the mix records on it every call the host makes on the mix, its handles and its motion patches: cues, weight, rate, seeks and fades, retargets and pushes, the mix's rate, marks, <code>mute</code> and <code>drop</code>, each at the host time it was made, so the frames rate 0 holds at one mix time stay apart. Where it held the clock at <code>t</code> for several frames, a seek or read back to <code>t</code> lands on the last of them; <code>mix.seq</code> numbers the frame being played, higher with each sync and seek, and <code>seek({ frame })</code> and <code>project({ frame })</code> take that number to reach an earlier one. A frame history no longer holds, through age or because an earlier seek went back before it, throws, and one a store paged needs <code>prepare</code> of its mix time first. What history keeps is filed by the frame a change was decided in, so a fade given a time already passed, or a handle seek past a voice's end, comes back with a seek to before the call even though its time is earlier. The tape lives as long as the mix and is never saved.
     <ul>
       <li><b>Back.</b> The mix restores itself from what history kept: each voice's controls, the voices and marks, and the mix's rate, as they stood at <code>t</code>. Voices that left after it are back on the handles the host holds, with <code>done</code> and <code>played</code> starting over where they had settled since. Voices cued after it wait as <code>pending</code> on theirs until the mix plays their cue again; on a branch that never does, they wait for good. A write to the handle of a voice waiting so changes nothing, and the tape does not record it. A handle&rsquo;s <code>weightOf</code> reads 0 for a subject until it is probed again, since the weight its last probe read by <code>t</code> is not kept. Each stateful record is put back from the copy kept nearest before <code>t</code> the first time it is touched, and steps once to where it is next probed, exact under <code>stepMs</code>. A subject faded out of a voice or dropped after <code>t</code> comes back with the record it had, a motion patch&rsquo;s state for it included, which history keeps for it from when it left; the lanes qualify afresh. Recorded input and host fields after <code>t</code> are let go, so signals and host fields read live again, and <code>assess</code> says <code>held</code> for what they feed.</li>
@@ -1143,6 +1144,16 @@ export const mixer: Engine;   <span class="cm">// the one that ships</span></cod
   <li><b>The owner's calls on blits-tone</b>: its names (<code>drive</code>, <code>attach</code>, <code>detach</code>, <code>write</code>, <code>cancel</code>, and the options <code>ahead</code>, <code>grid</code>, <code>late</code>, <code>clock</code>, <code>take</code>, <code>tag</code>, <code>score</code>); its tests taking <code>node-web-audio-api</code>, a prebuilt native binary of about 40 MB, as a dev dependency so Tone's offline render runs in Node with no audio device; and a subject binding one <code>Target</code> per channel, so a host that wants every subject heard builds a synth per subject and attaches it (all 2026-10-11).</li>
 </ul>
 
+<h3>Reading over a window</h3>
+<p>See <a href="#trace">Reading over a window</a>. Each is the owner&rsquo;s to overturn (2026-10-29).</p>
+<ul>
+  <li><b>The name <code>trace</code></b>, one syllable beside <code>project</code> and <code>marks</code>, for the read; <code>Trace</code> for what it returns, <code>of</code> for its read of one subject's channel (as <code>TransportProjection.of</code> reads one mix), and <code>Run</code> for the result.</li>
+  <li><b>A run is a polyline</b>: parallel arrays of times and values, straight lines between points, a time given twice for a jump, and one <code>exact</code> for the whole run. Not a list of typed segments (step, linear, exponential, curve): nothing the engine knows exactly is other than straight or a step, and a polyline is what both a Web Audio parameter and a chart take.</li>
+  <li><b>Known shapes come from the voices, values from <code>project</code></b>. The trace reads each straight stretch at its thirds and extends the line to both ends, so a jump at either end is never read across; a stretch it cannot vouch for is read on the grid, its ends a millionth of a ms inside. What counts as known is a whitelist in <code>shapeOf</code> (<code>src/trace.ts</code>); anything not on it is read on the grid, so a feature added later is sampled until someone vouches for it.</li>
+  <li><b>Exact is per channel, not per stretch</b>: one eased segment makes the whole run inexact, though its straight stretches still come as their breakpoints.</li>
+  <li><b>Windows behind the mix are read on the grid</b>, since the voices' controls then may differ from now.</li>
+</ul>
+
 <h3>Shipped as is</h3>
 <p>Two behaviors shipped without a view from the owner, to reopen if a consumer trips on one (2026-10-18):</p>
 <ul>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msb235/blits",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Concurrent effects: each on its own clock with its own state and weight, folded into one value per subject per frame",
   "keywords": [
     "animation",