@msb235/blits 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ This package follows [semver](https://semver.org). Below 1.0.0, a breaking chang
 version and everything else the patch. Each release lists its changes as **Breaking**, **Added** and
 **Fixed**, and the release workflow refuses a tag with no section here.
 
+## 0.10.0
+
+### Breaking
+
+- A booker is ended with `cancel()`, and `take` returns `{ cancel() }` to hear that its item moved
+  or went away. Both were `stop`: `mix.book(...).stop()` and `{ stop() }`.
+
+### Added
+
+- A booked hit carries `subjects`: the ones its voice names with `subjects`, or undefined for a
+  voice that names none. `BookedHit` and `BookOptions` take the subject type as a second
+  parameter.
+- `at(timestamp)` on a booker: where a host time falls on the outside clock, by the offset the
+  booker keeps.
+- `mix.timestamp`: the host's timestamp at the last sync.
+
 ## 0.9.0
 
 ### Breaking

package/README.md

@@ -123,7 +123,7 @@ do yet.
 
 ## Status
 
-v0.9.0, with five consumers. magicsmoke runs every fault on it, wod its wheel, tricks and
+v0.10.0, with five consumers. magicsmoke runs every fault on it, wod its wheel, tricks and
 transitions, weasel its animator's tweens, sherpa its seams, and
 [klieg](https://github.com/orochi235/klieg) composes all three of its systems — letter motion,
 part effects, and the environment a sign is lit by — on a mix each.

package/dist/book.d.ts

@@ -19,7 +19,7 @@ export interface BookHost<I, O> {
     /** Mix time a voice is gone at, where something has fixed it. */
     endOf(voice: Voice<I, O>): number | undefined;
     marks(from: number, to: number): Listed[];
-    /** The booker stopped: forget it. */
+    /** The booker canceled: forget it. */
     unhook(booker: Book<I, O>): void;
 }
 /** Refuses hits a voice could never play. */
@@ -34,22 +34,23 @@ export declare class Book<I, O> implements Booker {
     /** The mix clock at the previous sync, where a voice's clock change counts from. */
     private prev;
     private round;
-    private stopped;
+    private canceled;
     /** The host time the mix last sought at: a mark at or before it was taken before the seek. */
     private floor;
     /** Bookings of marks, by `keyOf`, kept while listed so one already taken is not taken late. */
     private readonly marked;
     private readonly tracks;
     private readonly due;
-    constructor(host: BookHost<I, O>, opts: BookOptions);
+    constructor(host: BookHost<I, O>, opts: BookOptions<unknown, I>);
     /** Books what comes within `ahead` of this sync, and retracts what moved. */
     sync(): void;
-    stop(): void;
+    cancel(): void;
     /**
-     * The mix was sought to `host.now`, back or ahead: what is booked ahead is stopped, and
+     * The mix was sought to `host.now`, back or ahead: what is booked ahead is canceled, and
      * everything after that moment is booked as the mix reaches it.
      */
     sought(): void;
+    at(timestamp: number): number;
     /** Whether a standing booking now falls at host time `time` within `RETIME_MS`. */
     private stands;
     private fits;

package/dist/book.js

@@ -2,7 +2,7 @@
 const RESYNC_MS = 50;
 /** The share of each frame's residual folded into the offset. */
 const SLEW = 0.05;
-/** A booking whose time moves by more than this is stopped and taken again. */
+/** A booking whose time moves by more than this is canceled and taken again. */
 const RETIME_MS = 1;
 const none = [];
 /** Refuses hits a voice could never play. */
@@ -23,7 +23,7 @@ export class Book {
     /** The mix clock at the previous sync, where a voice's clock change counts from. */
     prev = Number.NaN;
     round = 0;
-    stopped = false;
+    canceled = false;
     /** The host time the mix last sought at: a mark at or before it was taken before the seek. */
     floor = Number.NEGATIVE_INFINITY;
     /** Bookings of marks, by `keyOf`, kept while listed so one already taken is not taken late. */
@@ -36,7 +36,7 @@ export class Book {
     }
     /** Books what comes within `ahead` of this sync, and retracts what moved. */
     sync() {
-        if (this.stopped)
+        if (this.canceled)
             return;
         const host = this.host;
         const now = host.timestamp;
@@ -72,36 +72,36 @@ export class Book {
                 if (b.time <= now)
                     t.booked.delete(k);
     }
-    stop() {
-        if (this.stopped)
+    cancel() {
+        if (this.canceled)
             return;
-        this.stopped = true;
+        this.canceled = true;
         for (const b of this.marked.values())
             if (b.time > this.last)
-                b.taken?.stop();
+                b.taken?.cancel();
         for (const t of this.tracks.values())
             for (const b of t.booked.values())
                 if (b.time > this.last)
-                    b.taken?.stop();
+                    b.taken?.cancel();
         this.marked.clear();
         this.tracks.clear();
         this.host.unhook(this);
     }
     /**
-     * The mix was sought to `host.now`, back or ahead: what is booked ahead is stopped, and
+     * The mix was sought to `host.now`, back or ahead: what is booked ahead is canceled, and
      * everything after that moment is booked as the mix reaches it.
      */
     sought() {
-        if (this.stopped)
+        if (this.canceled)
             return;
         const last = this.last;
         for (const b of this.marked.values())
             if (b.time > last)
-                b.taken?.stop();
+                b.taken?.cancel();
         for (const t of this.tracks.values())
             for (const b of t.booked.values())
                 if (b.time > last)
-                    b.taken?.stop();
+                    b.taken?.cancel();
         this.marked.clear();
         this.tracks.clear();
         const host = this.host;
@@ -116,6 +116,9 @@ export class Book {
                     met: this.round,
                 });
     }
+    at(timestamp) {
+        return this.est + (timestamp - this.last);
+    }
     /** Whether a standing booking now falls at host time `time` within `RETIME_MS`. */
     stands(b, time) {
         if (time === undefined || !Number.isFinite(time))
@@ -139,7 +142,7 @@ export class Book {
             if (b !== undefined) {
                 if (b.time <= now || this.stands(b, m.timestamp))
                     continue;
-                b.taken?.stop();
+                b.taken?.cancel();
                 marked.delete(key);
             }
             const { order: _, ...item } = m;
@@ -148,7 +151,7 @@ export class Book {
         for (const [key, b] of marked)
             if (!seen.has(key)) {
                 if (b.time > now)
-                    b.taken?.stop();
+                    b.taken?.cancel();
                 marked.delete(key);
             }
     }
@@ -184,7 +187,7 @@ export class Book {
                 const time = this.timeOfHit(voice, hits, Math.floor(key / n), key % n, end);
                 if (this.stands(b, time))
                     continue;
-                b.taken?.stop();
+                b.taken?.cancel();
                 t.booked.delete(key);
                 moved = true;
             }
@@ -217,6 +220,7 @@ export class Book {
                         score: voice.spec.score,
                         name: voice.spec.name,
                         tags: voice.spec.tags ?? none,
+                        subjects: voice.named?.list,
                     };
                     this.due.push({ time, item, into: t.booked, key });
                 }
@@ -228,7 +232,7 @@ export class Book {
                 continue;
             for (const b of t.booked.values())
                 if (b.time > now)
-                    b.taken?.stop();
+                    b.taken?.cancel();
             this.tracks.delete(voice);
         }
     }

package/dist/hosts.d.ts

@@ -2,7 +2,7 @@ import type { LaneHost } from './lanes.js';
 import type { Mixer } from './mixer.js';
 import type { Booker, BookOptions, Handle } from './types.js';
 import type { Voice } from './voice.js';
-export declare function book<I, O>(mix: Mixer<I, O>, opts: BookOptions): Booker;
+export declare function book<I, O>(mix: Mixer<I, O>, opts: BookOptions<unknown, I>): Booker;
 export declare function laneHost<I, O>(mix: Mixer<I, O>): LaneHost<I, O>;
 /**
  * Whether a voice's patch and spec can run on a lane, its channels aside. A voice whose patch has

package/dist/mixer.d.ts

@@ -202,6 +202,7 @@ export declare class Mixer<I, O> implements Mix<I, O> {
     set announced(v: Announced[]);
     get nextId(): number;
     set nextId(v: number);
+    get timestamp(): number;
     get last(): number;
     get tape(): Tape | undefined;
     get replaying(): boolean;
@@ -215,7 +216,7 @@ export declare class Mixer<I, O> implements Mix<I, O> {
     owns(spec: OwnerSpec<I>): Handle<I>;
     span(spec: SpanSpec<I>): SpanHandle<I>;
     sync(timestamp: number): void;
-    book(opts: BookOptions): Booker;
+    book<E = unknown>(opts: BookOptions<E, I>): Booker;
     probe(subject: I, out?: O): O;
     pull(subjects: Iterable<I>, into: Columns<O>): void;
     seek(time: number): void;

package/dist/mixer.js

@@ -287,6 +287,9 @@ export class Mixer {
     set nextId(v) {
         this.transport.nextId = v;
     }
+    get timestamp() {
+        return this.transport.last;
+    }
     get last() {
         return this.transport.last;
     }

package/dist/types/mix.d.ts

@@ -239,6 +239,8 @@ export interface Mix<I, O, H = unknown> {
      * sync. Host time at the mix's rate, less what `rebase` took out and `seek` moved.
      */
     readonly now: number;
+    /** The host's timestamp at the last sync; NaN before the first. */
+    readonly timestamp: number;
     /** The tape `history.tape` made, undefined without one. */
     readonly tape: Tape | undefined;
     /**
@@ -322,7 +324,7 @@ export interface Mix<I, O, H = unknown> {
      * its voice and which mark, a hit by its voice, index and pass. `project` books nothing, and
      * nothing about booking is replayed under `history`. A mix with no booker pays nothing for it.
      */
-    book<E = unknown>(opts: BookOptions<E>): Booker;
+    book<E = unknown>(opts: BookOptions<E, I>): Booker;
 }
 /**
  * The implementation behind a mix: which patch forms it runs, and how it makes one.

package/dist/types/place.d.ts

@@ -103,7 +103,7 @@ export interface Hit<E = unknown> {
  *
  * @category score
  */
-export interface BookedHit<E = unknown> {
+export interface BookedHit<E = unknown, I = unknown> {
     /** On the host's clock. */
     timestamp: number;
     voice: number;
@@ -115,13 +115,15 @@ export interface BookedHit<E = unknown> {
     score: string | undefined;
     name: string | undefined;
     tags: readonly string[];
+    /** The subjects its voice names with `subjects`; undefined for a voice that names none. */
+    subjects: readonly I[] | undefined;
 }
 /**
  * What `book` takes: an outside clock, how far ahead to book on it, and what to do with each item.
  *
  * @category score
  */
-export interface BookOptions<E = unknown> {
+export interface BookOptions<E = unknown, I = unknown> {
     /**
      * The outside clock, in ms: `audio.currentTime * 1000`, `performance.now()`, or whatever the host
      * schedules against. Read once a sync. The mix maps its host time onto it by an offset that folds
@@ -136,13 +138,13 @@ export interface BookOptions<E = unknown> {
     /**
      * Called once per item: a mark as `marks` lists it, or a hit. `when` is on the outside clock;
      * `lateBy` is how many host ms past the item was when first seen, which is then taken at the
-     * clock's now; it is 0 for one booked ahead. Return a `stop` to hear about a booking whose time moved by
+     * clock's now; it is 0 for one booked ahead. Return a `cancel` to hear about a booking whose time moved by
      * more than 1 ms or that went away (a seek, a rate or ramp on the voice or the mix, a fade, a
      * `rebase`, an anchor's target moving, the voice leaving); the item is then booked again, at its
      * new time, at the same sync.
      */
-    take(item: Marked | BookedHit<E>, when: number, lateBy: number): {
-        stop(): void;
+    take(item: Marked | BookedHit<E, I>, when: number, lateBy: number): {
+        cancel(): void;
     } | undefined;
     /** Book only the voices, and announced marks, carrying this tag. */
     tag?: string;
@@ -155,6 +157,11 @@ export interface BookOptions<E = unknown> {
  * @category score
  */
 export interface Booker {
-    /** Stops every booking still ahead, and books nothing more. */
-    stop(): void;
+    /** Cancels every booking still ahead, and books nothing more. */
+    cancel(): void;
+    /**
+     * Where host `timestamp` falls on the outside clock, by the offset as the last sync left it;
+     * NaN before the first sync.
+     */
+    at(timestamp: number): number;
 }

package/docs/schema.html

@@ -161,7 +161,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.9.0 · design 2026-09-15, package 2026-09-28</span>
+  <span class="status">Built · v0.10.0 · design 2026-09-15, package 2026-09-28</span>
 </header>
 
 <h2 id="picture">In one picture</h2>
@@ -593,6 +593,8 @@ interface Mix&lt;I, O, H = unknown&gt; {
   atRest(subject: I): boolean;
   <span class="cm">/** The mix clock at the last sync or seek, which `seek` and `project` take; NaN before the first sync. */</span>
   readonly now: number;
+  <span class="cm">/** The host's timestamp at the last sync; NaN before the first. */</span>
+  readonly timestamp: number;
   <span class="cm">/** The mix read at another mix time without moving it: ahead plays what is cued forward, behind needs `history` unless
      every voice still plays as it was cued. */</span>
   project(time: number): Projection&lt;I, O&gt;;
@@ -631,9 +633,10 @@ interface Mix&lt;I, O, H = unknown&gt; {
   touch(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>
+  <span class="cm">/** Hands the host each mark and hit `ahead` ms before it comes, on a clock of its own, and cancels 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 };
+    take(item: Marked | BookedHit&lt;E, I&gt;, when: number, lateBy: number): { cancel(): void } | undefined }):
+    { cancel(): void; at(timestamp: number): number };
 }</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>
@@ -697,7 +700,7 @@ mix.book({
   take(item) {
     if ('hit' in item || item.mark !== 'start') return;
     const video = load(clips[item.name]);
-    return { stop: () =&gt; video.release() };
+    return { cancel: () =&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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msb235/blits",
-  "version": "0.9.0",
+  "version": "0.10.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",