@msb235/blits 0.4.0 → 0.6.0

package/dist/cue.d.ts

@@ -0,0 +1,3 @@
+import type { Mixer } from './mixer.js';
+import type { Handle, VoiceSpec } from './types.js';
+export declare function cue<I, O>(mix: Mixer<I, O>, spec: VoiceSpec<I, O>): Handle<I>;

package/dist/cue.js

@@ -0,0 +1,115 @@
+import { checkHits } from './book.js';
+import { changed, index } from './chain.js';
+import { schedule } from './due.js';
+import { started } from './held.js';
+import { handle } from './hosts.js';
+import { motionOf } from './motion.js';
+import { adopt, ownerReading } from './owner.js';
+import { durationOf } from './patch.js';
+import { checkPlacement, localNow, mixAt, pin, place } from './place.js';
+import { motionOwner } from './strays.js';
+import { Voice } from './voice.js';
+export function cue(mix, spec) {
+    const patch = spec.patch;
+    for (const channel of patch.writes) {
+        if (!(channel in mix.kit))
+            throw new Error(`blits: kit has no channel ${String(channel)}, which this patch writes`);
+        const wanted = patch.kit?.[channel];
+        const here = mix.kit[channel];
+        if (wanted && wanted !== here && (wanted.kind === undefined || wanted.kind !== here.kind))
+            throw new Error(`blits: channel ${String(channel)} is ${here.kind ?? 'a custom channel'} in this kit, but the patch was written for ${wanted.kind ?? 'a custom channel'}`);
+    }
+    const motion = motionOf(patch);
+    if (motion !== undefined) {
+        const channel = patch.writes[0];
+        const rest = mix.kit[channel].rest;
+        if (typeof rest === 'number')
+            motion.cuedOn(String(channel), true);
+        else if (Array.isArray(rest) || ArrayBuffer.isView(rest))
+            motion.cuedOn(String(channel), false);
+    }
+    if (patch.reads) {
+        const host = mix.opts.host;
+        for (const field of patch.reads)
+            if (typeof host !== 'object' || host === null || !(field in host))
+                throw new Error(`blits: the patch reads host.${field}, which this mix's host lacks`);
+    }
+    if (spec.from === 'current' && patch.form !== 'keys')
+        throw new Error("blits: from: 'current' needs a keys patch");
+    if (spec.subjects !== undefined && spec.target !== undefined)
+        throw new Error('blits: a voice takes target or subjects, not both');
+    const anchor = spec.anchor;
+    const owner = spec.owner === undefined ? null : ownerOf(mix, spec.owner);
+    if (anchor)
+        checkPlacement(mix, spec, anchor, owner);
+    if (spec.hits !== undefined)
+        checkHits(spec.hits, durationOf(patch));
+    const anchored = anchor !== undefined && (anchor.start !== undefined || anchor.in !== undefined);
+    // A voice an owner holds is placed on the owner's clock: ms from when it starts.
+    const local = owner === null ? mix.now : ownerReading(owner, mix.now);
+    const start = anchored
+        ? Number.POSITIVE_INFINITY
+        : owner !== null
+            ? (spec.start ?? (local > 0 ? local : 0))
+            : spec.start !== undefined
+                ? mixAt(mix, spec.start - mix.offset)
+                : Number.isNaN(mix.now)
+                    ? 0
+                    : mix.now;
+    const voice = new Voice(mix.nextId++, spec, patch, spec.fade ?? {}, local, start, mix.slotOf, mix.channels, mix.opts.host, mix.send, owner);
+    if (owner !== null)
+        adopt(owner, voice);
+    if (voice.holding !== null) {
+        mix.owners ??= [];
+        mix.owners.push(voice);
+    }
+    if (!Number.isNaN(mix.now)) {
+        voice.cuedAt = mix.now;
+        voice.opened = mix.now;
+    }
+    voice.placing = anchored;
+    if (mix.pace !== null && owner === null && spec.start !== undefined && voice.state === 'pending')
+        pin(mix, voice, spec.start - mix.offset);
+    if (motion !== undefined) {
+        mix.playing.set(motion, (mix.playing.get(motion) ?? 0) + 1);
+        mix.owner ??= motionOwner(new WeakRef(mix));
+        motion.owner = mix.owner;
+        motion.ownerId = voice.id;
+    }
+    mix.cued.push(voice);
+    index(mix, voice);
+    changed(mix, voice);
+    mix.stir();
+    if (spec.locus !== undefined)
+        mix.loci++;
+    if (spec.from === 'current')
+        mix.wantsPose = true;
+    if (anchor) {
+        mix.anchored++;
+        place(mix);
+        if (!Number.isNaN(mix.now) &&
+            voice.state === 'pending' &&
+            localNow(mix, voice) >= voice.start) {
+            voice.state = 'live';
+            started(mix, voice);
+            changed(mix, voice);
+        }
+    }
+    // After placing, so the controls it starts with are where its anchors put it at the cue.
+    if (mix.opts.history) {
+        voice.log = [];
+        voice.note(Number.NEGATIVE_INFINITY);
+    }
+    schedule(mix, voice);
+    voice.handle = handle(mix, voice);
+    return voice.handle;
+}
+/** The owner a handle names, refused where it is not one of this mix's or has left. */
+function ownerOf(mix, handle) {
+    const found = mix.owners?.find((v) => v.handle === handle);
+    if (found === undefined)
+        throw new Error('blits: owner is not a handle mix.owns returned on this mix');
+    if (found.state === 'done')
+        throw new Error('blits: that owner has left the mix');
+    return found;
+}

package/dist/due.d.ts

@@ -0,0 +1,12 @@
+import type { Mixer } from './mixer.js';
+import type { Voice } from './voice.js';
+/** One entry in a mix's due queue; stale once its voice has been scheduled again. */
+export interface Due<I, O> {
+    at: number;
+    voice: Voice<I, O>;
+    token: number;
+}
+/** Files a voice in the due queue at its current due, replacing any entry it had. */
+export declare function schedule<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>): void;
+/** Takes every current entry due by `now` off the queue, in cue order. */
+export declare function popDue<I, O>(mix: Mixer<I, O>, now: number): Voice<I, O>[];

package/dist/due.js

@@ -0,0 +1,93 @@
+/**
+ * The earliest mix time `moveTo` would change a voice: its start, its anchored out, the end of
+ * its last pass, the end of its fade or of a subject's ramp out; -Infinity where it must be
+ * visited every frame, Infinity where nothing will happen until a handle or anchor changes it.
+ * Early is safe, since a visit that finds nothing due schedules again; late is not, so anything
+ * that can bring it earlier calls `schedule`.
+ */
+function dueOf(mix, voice) {
+    if (voice.state === 'done')
+        return Number.POSITIVE_INFINITY;
+    // An owner and the voices it holds run on clocks that move with it, so each is visited every frame.
+    if (Number.isNaN(voice.opened) || voice.owner !== null || voice.holding !== null)
+        return Number.NEGATIVE_INFINITY;
+    let due = Number.POSITIVE_INFINITY;
+    if (voice.parts !== null)
+        for (const r of voice.parts.values())
+            due = Math.min(due, r.at + r.over);
+    if (voice.state === 'pending')
+        return Math.min(due, Number.isNaN(voice.start) ? due : voice.start);
+    if (voice.state === 'fading') {
+        const out = voice.out;
+        if (out === null || out.rest)
+            return Number.NEGATIVE_INFINITY;
+        return Math.min(due, out.at + out.over);
+    }
+    due = Math.min(due, voice.outAt);
+    if (Number.isFinite(voice.span)) {
+        const end = voice.span + voice.latest;
+        // A frozen voice goes live again once its clock is back before its end: by a seek, by a
+        // subject staggered later than any before, or by running backwards, which is checked each
+        // frame while it can.
+        if (voice.state === 'frozen') {
+            if (voice.rate <= 0 || voice.ramp !== null)
+                return Number.NEGATIVE_INFINITY;
+            if (!Number.isNaN(mix.now) && voice.elapsedAt(mix.now) < end)
+                return Number.NEGATIVE_INFINITY;
+        }
+        if (voice.state === 'live')
+            due = Math.min(due, voice.timeAt(end));
+    }
+    return due;
+}
+/** Files a voice in the due queue at its current due, replacing any entry it had. */
+export function schedule(mix, voice) {
+    if (mix.projecting)
+        return;
+    mix.lanes?.voiceChanged(voice.id);
+    const token = ++voice.dueToken;
+    const due = dueOf(mix, voice);
+    if (due === Number.POSITIVE_INFINITY)
+        return;
+    const heap = mix.due;
+    heap.push({ at: Number.isNaN(due) ? Number.NEGATIVE_INFINITY : due, voice, token });
+    let i = heap.length - 1;
+    while (i > 0) {
+        const up = (i - 1) >> 1;
+        if (heap[up].at <= heap[i].at)
+            break;
+        [heap[up], heap[i]] = [heap[i], heap[up]];
+        i = up;
+    }
+}
+/** Takes every current entry due by `now` off the queue, in cue order. */
+export function popDue(mix, now) {
+    const heap = mix.due;
+    const at = (k) => k < heap.length ? heap[k].at : Number.POSITIVE_INFINITY;
+    const out = [];
+    while (heap.length > 0 && heap[0].at <= now) {
+        const top = heap[0];
+        const last = heap.pop();
+        if (heap.length > 0) {
+            heap[0] = last;
+            let i = 0;
+            for (;;) {
+                const l = 2 * i + 1;
+                const r = l + 1;
+                const m0 = at(l) < at(i) ? l : i;
+                const m = at(r) < at(m0) ? r : m0;
+                if (m === i)
+                    break;
+                [heap[m], heap[i]] = [heap[i], heap[m]];
+                i = m;
+            }
+        }
+        if (top.token === top.voice.dueToken && top.voice.state !== 'done') {
+            top.voice.dueToken++;
+            out.push(top.voice);
+        }
+    }
+    if (out.length > 1)
+        out.sort((a, b) => a.id - b.id);
+    return out;
+}

package/dist/fade.d.ts

@@ -0,0 +1,19 @@
+import type { Mixer } from './mixer.js';
+import type { Voice } from './voice.js';
+/** Starts one subject's ramp out of a voice, or takes it out at once for a ramp of 0. */
+export declare function fadeSubject<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, subject: I, over?: number): void;
+/** What a subject's own ramp out of a voice leaves of its weight this frame, 0..1. */
+export declare function parting<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, now: number): number;
+/**
+ * Takes a subject out of one voice for good, as of mix time `at`: the voice forgets its record,
+ * its lane position and a motion patch's state for it, and reaches it no more.
+ */
+export declare function part<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, subject: I, at: number): void;
+/** Brings a subject faded out of a voice back, to be met afresh on its next probe. */
+export declare function unpart<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, subject: I): void;
+export declare function beginFade<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, opts: {
+    over?: number;
+    at?: 'rest';
+    deadline?: number;
+}, at?: number): void;
+export declare function retire<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, at?: number): void;

package/dist/fade.js

@@ -0,0 +1,133 @@
+import { changed } from './chain.js';
+import { envelope } from './clock.js';
+import { schedule } from './due.js';
+import { noted } from './history.js';
+import { orphan } from './owner.js';
+import { startOf } from './place.js';
+import { unreach } from './unreached.js';
+/** Starts one subject's ramp out of a voice, or takes it out at once for a ramp of 0. */
+export function fadeSubject(mix, voice, subject, over) {
+    if (voice.state === 'done' || voice.parted?.has(subject) || voice.parts?.has(subject))
+        return;
+    mix.stir();
+    const ms = mix.reduced ? 0 : (over ?? voice.fade.out ?? 0);
+    const at = Number.isNaN(mix.now) ? startOf(voice) : mix.now;
+    if (ms === 0) {
+        part(mix, voice, subject, at);
+        return;
+    }
+    voice.parts ??= new Map();
+    voice.parts.set(subject, { at, over: ms });
+    mix.parters.add(voice);
+    schedule(mix, voice);
+    mix.lanes?.refill();
+}
+/** What a subject's own ramp out of a voice leaves of its weight this frame, 0..1. */
+export function parting(voice, subject, now) {
+    const r = voice.parts?.get(subject);
+    if (r === undefined)
+        return 1;
+    return envelope(0, { at: r.at, over: r.over, rest: false }, voice.ease, this.reducedNow, now, 0);
+}
+/**
+ * Takes a subject out of one voice for good, as of mix time `at`: the voice forgets its record,
+ * its lane position and a motion patch's state for it, and reaches it no more.
+ */
+export function part(mix, voice, subject, at) {
+    voice.parts?.delete(subject);
+    if (voice.parts?.size === 0)
+        voice.parts = null;
+    voice.parted ??= new Map();
+    voice.parted.set(subject, at);
+    mix.parters.add(voice);
+    forgetIn(mix, voice, subject);
+    const motion = voice.motion;
+    if (motion !== undefined && asks(mix, motion, voice))
+        motion.release(subject);
+}
+/** Brings a subject faded out of a voice back, to be met afresh on its next probe. */
+export function unpart(mix, voice, subject) {
+    if (voice.parted?.delete(subject) !== true)
+        return;
+    if (voice.parted.size === 0)
+        voice.parted = null;
+    forgetIn(mix, voice, subject);
+    const slot = mix.chains.get(subject)?.slot ?? -1;
+    if (slot >= 0)
+        mix.lanes?.rejoin(slot);
+}
+/** Drops a voice's record of a subject and relinks the subject's chain without it. */
+function forgetIn(mix, voice, subject) {
+    const head = mix.chains.get(subject);
+    if (head !== undefined && head.slot >= 0)
+        unreach(voice, head.slot, false);
+    const held = voice.subjects.get(subject);
+    if (held !== undefined) {
+        voice.subjects.delete(subject);
+        if (held.reaches)
+            voice.seen--;
+        if (held.rested)
+            voice.restedCount--;
+        if (voice.holder === held)
+            voice.holder = null;
+    }
+    if (head === undefined)
+        return;
+    head.version = Number.NaN;
+    mix.relinks++;
+    if (voice.laned && head.slot >= 0)
+        mix.lanes?.part(voice.id, head.slot);
+    mix.lanes?.refill();
+}
+export function beginFade(mix, voice, opts, at) {
+    if (voice.state === 'done' || voice.state === 'fading')
+        return;
+    const over = mix.reduced ? 0 : (opts.over ?? voice.fade.out ?? 0);
+    // A voice is linked into its subjects' chains once it plays, and a fading one plays.
+    if (voice.state === 'pending')
+        changed(mix, voice);
+    voice.state = 'fading';
+    voice.out = {
+        from: 1,
+        at: at ?? (Number.isNaN(mix.now) ? startOf(voice) : mix.now),
+        over,
+        rest: opts.at === 'rest',
+        deadline: opts.deadline,
+    };
+    noted(mix, voice);
+    if (opts.at === 'rest')
+        mix.lanes?.invalidate();
+    else
+        mix.lanes?.refill();
+    if (over === 0 && opts.at !== 'rest')
+        retire(mix, voice, voice.out.at);
+}
+/** Removes a voice, recording that it left at `at`, default now. */
+/** Whether a motion patch still asks this voice of this mix for its time. */
+function asks(mix, motion, voice) {
+    return motion.owner === mix.owner && motion.ownerId === voice.id;
+}
+export function retire(mix, voice, at) {
+    if (voice.holding === null)
+        mix.lanes?.touch(voice);
+    const motion = voice.motion;
+    if (motion !== undefined && asks(mix, motion, voice))
+        motion.owner = null;
+    voice.state = 'done';
+    // The record its setting last wrote to, which a retired voice no longer calls for.
+    voice.keepOn = null;
+    mix.retired.push(voice);
+    voice.doneAt = at ?? (Number.isNaN(mix.now) ? Number.NEGATIVE_INFINITY : mix.now);
+    voice.play(false);
+    voice.resolve();
+    // An owner takes what it holds with it, and leaves with its last child.
+    if (voice.holding !== null)
+        for (const child of [...voice.holding.children])
+            if (child.state !== 'done')
+                retire(mix, child, voice.doneAt);
+    if (voice.owner !== null) {
+        const owner = orphan(voice);
+        if (owner !== null)
+            retire(mix, owner, voice.doneAt);
+    }
+}

package/dist/fill.d.ts

@@ -0,0 +1,42 @@
+import { type Lane, type Laned, type Paced } from './lane.js';
+import type { Lanes } from './lanes.js';
+import { absent } from './numbers.js';
+import { type Scratch } from './patch.js';
+import type { Subject, Voice } from './voice.js';
+export declare function fillAll<I, O>(lanes: Lanes<I, O>, now: number, version: number): void;
+/** Leaves a lane's subjects to the general path until it wakes, keeping what `weightOf` reports. */
+export declare function rest<I, O>(lanes: Lanes<I, O>, lane: Paced): void;
+export declare function wake<I, O>(lanes: Lanes<I, O>, lane: Paced): void;
+/**
+ * A voice with a signal weight: its weight for the subject at `slot` under the voice's fade `fade`,
+ * through the general path's own arithmetic; NaN where that path has not made the voice's first
+ * call for the subject, which it then makes this frame, so a signal that keeps state is first
+ * called where the general path would call it.
+ */
+export declare function signalled<I, O>(this: Lanes<I, O>, voice: Voice<I, O>, slot: number, rec: Subject<unknown>, elapsed: number, pass: number, fade: number): number;
+/** What a subject's own ramp out of a voice leaves of its weight: 1 with none. */
+export declare function parting<I, O>(this: Lanes<I, O>, voice: Voice<I, O>, slot: number): number;
+export declare function subjectAt<I, O>(this: Lanes<I, O>, slot: number): I | typeof absent;
+/** What a lane remembers within one fill, cleared before the fill runs it. */
+export declare function reset<I, O>(this: Lanes<I, O>, lane: Lane<I, O>): void;
+/** One voice's contribution to every subject it plays on. */
+export declare function run<I, O>(this: Lanes<I, O>, lane: Lane<I, O>): void;
+/**
+ * One subject's contribution from a lane's voice. True where the voice gave the subject a delta,
+ * as the general path's `influence` does where it returns one, which is what makes a voice in a
+ * locus one of its members for the subject.
+ */
+export declare function one<I, O>(this: Lanes<I, O>, lane: Lane<I, O>, p: number, slot: number, elapsedNow: number, duration: number, passes: number): boolean;
+/**
+ * A keys voice's stops at `phase` folded straight into a subject's values, without a delta: what
+ * `readKeyed` then `foldDelta` give, through the same segment search and the stock channels' own
+ * lerp, which is all a laned keys voice can use.
+ */
+export declare function foldKeys<I, O>(this: Lanes<I, O>, voice: Voice<I, O>, chans: readonly Laned[], phase: number, slot: number, w: number): void;
+/** Reads a keys voice's stops at `phase` into `delta`, interpolating into the reader's `scratch`. */
+export declare function readKeyed<I, O>(this: Lanes<I, O>, voice: Voice<I, O>, phase: number, delta: Record<string, unknown>, scratch: Scratch): void;
+/**
+ * Calls a stateless fn voice's patch for a subject its general path has met, and folds the delta;
+ * false for a subject the host has let go of.
+ */
+export declare function call<I, O>(this: Lanes<I, O>, voice: Voice<I, O>, chans: readonly Laned[], rec: Subject<unknown>, slot: number, elapsed: number, phase: number, pass: number, delay: number, w: number): boolean;