@msb235/blits 0.5.0 → 0.7.0

package/dist/cue.js

@@ -1,15 +1,58 @@
 import { checkHits } from './book.js';
 import { changed, index } from './chain.js';
 import { schedule } from './due.js';
+import { VoiceHandle } from './handle.js';
 import { started } from './held.js';
 import { handle } from './hosts.js';
 import { motionOf } from './motion.js';
-import { adopt, ownerReading } from './owner.js';
+import { adopt, ownerPatch, ownerReading } from './owner.js';
 import { durationOf } from './patch.js';
 import { checkPlacement, localNow, mixAt, pin, place } from './place.js';
+import { checkChild, refit } from './spans.js';
 import { motionOwner } from './strays.js';
+import { record } from './tape.js';
 import { Voice } from './voice.js';
 export function cue(mix, spec) {
+    const patch = spec.patch;
+    playable(mix, spec);
+    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 || owner?.fitting
+        ? 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 (patch === ownerPatch && mix.fitting !== null)
+        voice.fitting = mix.fitting;
+    if (owner?.fitting)
+        checkChild(spec, voice);
+    if (mix.pace !== null && owner === null && spec.start !== undefined && voice.state === 'pending')
+        voice.pinned = spec.start - mix.offset;
+    enter(mix, voice);
+    const h = handle(mix, voice);
+    voice.handle = h;
+    // By its handle, so a voice a history store paged out and a seek revived is the one cued again.
+    record(mix, 'cue', () => recue(mix, VoiceHandle.voiceOf(h) ?? lost(h)));
+    return h;
+}
+/** Refuses a spec whose patch the mix cannot play, or whose state its history cannot keep. */
+export function playable(mix, spec) {
     const patch = spec.patch;
     for (const channel of patch.writes) {
         if (!(channel in mix.kit))
@@ -34,29 +77,30 @@ export function cue(mix, spec) {
             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');
+    if (mix.transport.pager !== null &&
+        (patch.state !== undefined || patch.step !== undefined) &&
+        (patch.pack === undefined || patch.unpack === undefined))
+        throw new Error("blits: this mix's history has a store, which keeps a stateful patch's state as data; give the patch pack and unpack");
+    if (spec.as !== undefined && mix.transport.pager !== null && !mix.opts.history?.revive)
+        throw new Error('blits: a voice cued with as needs history.revive to rebuild it from');
+}
+/** A voice parked by a seek, cued again as the mix plays past its cue, on the handle it had. */
+function recue(mix, voice) {
+    const owner = voice.owner;
+    if ((owner === null ? mix.now : ownerReading(owner, mix.now)) >= voice.start)
+        voice.state = 'live';
+    enter(mix, voice);
+}
+function lost(h) {
+    throw new Error(`blits: voice ${h.id} is paged out, and the seek that plays its cue again did not load it`);
+}
+/** Puts a voice just made, or parked by a seek, into the mix. */
+function enter(mix, voice) {
+    const spec = voice.spec;
+    const owner = voice.owner;
     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);
+    const motion = voice.motion;
     if (owner !== null)
         adopt(owner, voice);
     if (voice.holding !== null) {
@@ -68,15 +112,21 @@ export function cue(mix, spec) {
         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);
+    // A start the host gave by its own clock, where the mix's rate puts it.
+    if (!Number.isNaN(voice.pinned) && voice.state === 'pending')
+        pin(mix, voice, voice.pinned);
     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);
+    // In id order, which a voice cued again after later ones keeps by going in at its place.
+    const cued = mix.cued;
+    let i = cued.length;
+    while (i > 0 && cued[i - 1].id > voice.id)
+        i--;
+    cued.splice(i, 0, voice);
     index(mix, voice);
     changed(mix, voice);
     mix.stir();
@@ -95,14 +145,15 @@ export function cue(mix, spec) {
             changed(mix, voice);
         }
     }
+    if (owner?.fitting)
+        refit(mix, owner);
     // 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);
+        voice.first ??= voice.log[0];
     }
     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) {

package/dist/due.js

@@ -15,6 +15,9 @@ function dueOf(mix, voice) {
     if (voice.parts !== null)
         for (const r of voice.parts.values())
             due = Math.min(due, r.at + r.over);
+    const back = voice.back;
+    if (back !== null)
+        due = Math.min(due, back.at + (1 - back.from) * back.over);
     if (voice.state === 'pending')
         return Math.min(due, Number.isNaN(voice.start) ? due : voice.start);
     if (voice.state === 'fading') {
@@ -26,10 +29,10 @@ function dueOf(mix, voice) {
     due = Math.min(due, voice.outAt);
     if (Number.isFinite(voice.span)) {
         const end = voice.span + voice.latest;
-        // A held voice goes live again once its clock is back before its end: by a seek, by a
+        // 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 === 'held') {
+        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)

package/dist/fade.d.ts

@@ -16,4 +16,17 @@ export declare function beginFade<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, op
     at?: 'rest';
     deadline?: number;
 }, at?: number): void;
+/**
+ * Turns a fading voice around: it climbs back from where its fade out had got to, up the same
+ * curve, at the whole curve per `over` ms. A fade waiting for rest is taken back at once. A voice
+ * not fading is left as it is.
+ */
+export declare function beginRise<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, opts: {
+    over?: number;
+}): void;
+/**
+ * Fades a voice out from mix time `at`: ahead, it plays untouched until then and begins its fade
+ * exactly there; at or behind now, the fade began then and is partway.
+ */
+export declare function fadeAt<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, at: number, over: number | undefined): void;
 export declare function retire<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>, at?: number): void;

package/dist/fade.js

@@ -1,9 +1,10 @@
 import { changed } from './chain.js';
 import { envelope } from './clock.js';
 import { schedule } from './due.js';
-import { noted } from './history.js';
+import { leave, noted, releasing } from './history.js';
 import { orphan } from './owner.js';
 import { startOf } from './place.js';
+import { lingers, refit } from './spans.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) {
@@ -43,7 +44,7 @@ export function part(mix, voice, subject, at) {
     forgetIn(mix, voice, subject);
     const motion = voice.motion;
     if (motion !== undefined && asks(mix, motion, voice))
-        motion.release(subject);
+        motion.release(subject, ...releasing(mix));
 }
 /** Brings a subject faded out of a voice back, to be met afresh on its next probe. */
 export function unpart(mix, voice, subject) {
@@ -63,6 +64,7 @@ function forgetIn(mix, voice, subject) {
         unreach(voice, head.slot, false);
     const held = voice.subjects.get(subject);
     if (held !== undefined) {
+        leave(mix, voice, subject, held);
         voice.subjects.delete(subject);
         if (held.reaches)
             voice.seen--;
@@ -102,6 +104,52 @@ export function beginFade(mix, voice, opts, at) {
     if (over === 0 && opts.at !== 'rest')
         retire(mix, voice, voice.out.at);
 }
+/**
+ * Turns a fading voice around: it climbs back from where its fade out had got to, up the same
+ * curve, at the whole curve per `over` ms. A fade waiting for rest is taken back at once. A voice
+ * not fading is left as it is.
+ */
+export function beginRise(mix, voice, opts) {
+    const out = voice.out;
+    if (voice.state !== 'fading' && voice.outSet) {
+        // A fade set ahead and not begun is taken back, and the weight never moved.
+        voice.outAt = Number.POSITIVE_INFINITY;
+        voice.outOver = Number.NaN;
+        voice.outSet = false;
+        noted(mix, voice);
+        return;
+    }
+    if (voice.state !== 'fading' || out === null)
+        return;
+    const at = Number.isNaN(mix.now) ? startOf(voice) : mix.now;
+    const over = mix.reduced ? 0 : (opts.over ?? voice.fade.in ?? voice.fade.out ?? 0);
+    const left = out.rest || out.over === 0 ? 1 : 1 - (at - out.at) / out.over;
+    const from = left < 0 ? 0 : left > 1 ? 1 : left;
+    voice.out = null;
+    voice.outAt = Number.POSITIVE_INFINITY;
+    voice.state = 'live';
+    voice.back = over > 0 && from < 1 ? { from, at, over } : null;
+    noted(mix, voice);
+    mix.lanes?.refill();
+}
+/**
+ * Fades a voice out from mix time `at`: ahead, it plays untouched until then and begins its fade
+ * exactly there; at or behind now, the fade began then and is partway.
+ */
+export function fadeAt(mix, voice, at, over) {
+    if (voice.state === 'done' || voice.state === 'fading')
+        return;
+    const now = Number.isNaN(mix.now) ? startOf(voice) : mix.now;
+    if (at <= now) {
+        beginFade(mix, voice, { over }, Math.max(startOf(voice), at));
+        mix.stir();
+        return;
+    }
+    voice.outAt = at;
+    voice.outOver = over ?? Number.NaN;
+    voice.outSet = true;
+    noted(mix, voice);
+}
 /** 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) {
@@ -118,7 +166,7 @@ export function retire(mix, voice, at) {
     voice.keepOn = null;
     mix.retired.push(voice);
     voice.doneAt = at ?? (Number.isNaN(mix.now) ? Number.NEGATIVE_INFINITY : mix.now);
-    voice.play(false);
+    voice.play(false, voice.doneAt);
     voice.resolve();
     // An owner takes what it holds with it, and leaves with its last child.
     if (voice.holding !== null)
@@ -126,8 +174,11 @@ export function retire(mix, voice, at) {
             if (child.state !== 'done')
                 retire(mix, child, voice.doneAt);
     if (voice.owner !== null) {
+        const span = voice.owner;
         const owner = orphan(voice);
-        if (owner !== null)
+        if (owner !== null && !lingers(owner, voice.doneAt))
             retire(mix, owner, voice.doneAt);
+        else if (span.fitting !== null && span.state !== 'done')
+            refit(mix, span);
     }
 }

package/dist/fill.d.ts

@@ -23,7 +23,7 @@ export declare function reset<I, O>(this: Lanes<I, O>, lane: Lane<I, O>): void;
 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
+ * as the general path's `contribution` 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;

package/dist/fill.js

@@ -3,7 +3,7 @@ import { passAt, phaseAt, silent, weighed } from './clock.js';
 import { flush } from './columns.js';
 import { crowdsUpTo, freshen } from './crowd.js';
 import { foldLocus, gatherLocus } from './gather.js';
-import { held } from './lane.js';
+import { frozenAt } from './lane.js';
 import { reach } from './meet.js';
 import { absent } from './numbers.js';
 import { AT, NOTHING, readKeys, seg, segment, shifted } from './patch.js';
@@ -39,6 +39,7 @@ export function fillAll(lanes, now, version) {
         const decide = lanes.fresh;
         lanes.fresh = false;
         const share = lanes.live > 0 ? lanes.lastDistinct / lanes.live : 1;
+        lanes.lately = share < 1 ? lanes.lastFrom : -1;
         // Deciding which lanes and crowds go idle first, then running them, in voice order: a crowd's
         // rows are folded between the lanes on either side of their voices, as the general path
         // folds every voice in order.
@@ -95,11 +96,9 @@ export function fillAll(lanes, now, version) {
                 }
         }
         // With every lane idle there was nothing to fill, and no subject reads a lane this frame.
-        if (busy)
-            for (let s = 0; s < size; s++)
-                lanes.per[s * 6 /* Per.SLOT */ + 0 /* Per.FILLED */] = lanes.fills;
+        lanes.busyFill = busy ? lanes.fills : 0;
         for (const slot of lanes.late)
-            lanes.per[slot * 6 /* Per.SLOT */ + 0 /* Per.FILLED */] = 0;
+            lanes.per[slot * 6 /* Per.SLOT */ + 0 /* Per.FILLED */] = lanes.fills;
         if (lanes.holding) {
             lanes.subjects.fill(undefined, 0, size);
             lanes.holding = false;
@@ -208,7 +207,11 @@ export function reset(lane) {
     lane.read = false;
     lane.weighed = false;
     // With no fade in or out the envelope is 1 for every subject, which is what it would return.
-    lane.flat = !((voice.fade.in ?? 0) > 0) && voice.out === null && voice.owner === null;
+    lane.flat =
+        !((voice.fade.in ?? 0) > 0) &&
+            voice.out === null &&
+            voice.back === null &&
+            voice.owner === null;
     lane.fade = 1;
 }
 /** One voice's contribution to every subject it plays on. */
@@ -238,7 +241,7 @@ export function run(lane) {
 }
 /**
  * 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
+ * as the general path's `contribution` does where it returns one, which is what makes a voice in a
  * locus one of its members for the subject.
  */
 export function one(lane, p, slot, elapsedNow, duration, passes) {
@@ -249,8 +252,10 @@ export function one(lane, p, slot, elapsedNow, duration, passes) {
     // A probe read this subject from the last fill: keep the weight it read for `weightOf`.
     if (this.per[slot * 6 /* Per.SLOT */ + 5 /* Per.LANE_FILL */] === this.fills - 1)
         data[o + 3 /* Row.PROBED */] = data[o + 2 /* Row.WEIGHT */];
+    if (this.lately >= 0 && this.unread(slot))
+        return false;
     const delay = data[o + 0 /* Row.DELAY */];
-    const elapsed = held(voice, elapsedNow - delay);
+    const elapsed = frozenAt(voice, elapsedNow - delay);
     if (!(elapsed >= 0)) {
         data[o + 2 /* Row.WEIGHT */] = 0;
         return false;
@@ -278,6 +283,8 @@ export function one(lane, p, slot, elapsedNow, duration, passes) {
     else
         w = weighed(voice.weight, lane.fade, this.parting(voice, slot));
     data[o + 2 /* Row.WEIGHT */] = w;
+    this.folding = lane;
+    this.rec = lane.records[p] ?? null;
     if (voice.built !== null) {
         if (!lane.read || !Object.is(elapsed, lane.readAt)) {
             this.readKeyed(voice, lane.phase, lane.delta, lane.scratch);
@@ -367,12 +374,12 @@ export function call(voice, chans, rec, slot, elapsed, phase, pass, delay, w) {
     else
         reading.horizon = Number.POSITIVE_INFINITY;
     const delta = voice.patch.at(phase, subject, voice.setting);
-    // What `influence` leaves on the record, so a probe on the general path this frame reuses it.
+    // What `contribution` leaves on the record, so a probe on the general path this frame reuses it.
     rec.delta = delta;
     rec.probed = this.now;
     rec.seeks = voice.seeks;
     if (this.keeps)
-        host.after(voice, rec);
+        host.after(voice, subject, rec);
     if (reading.kept !== kept && !voice.keeping)
         host.kept(voice);
     if (w > 0)

package/dist/fit.d.ts

@@ -0,0 +1,144 @@
+/**
+ * How hard a claim on time holds when it meets another: the weaker gives way.
+ *
+ * @category score
+ */
+export type Strength = 'weak' | 'strong' | 'required';
+/**
+ * How a span lays its children out: each after the one before has ended, partway through it, or
+ * all at once.
+ *
+ * @category score
+ */
+export type Order = 'queue' | 'stagger' | 'together';
+/**
+ * One child of a span as a fit sees it: what is left of it, and the ways it may give way.
+ *
+ * @category score
+ */
+export interface Claim {
+    /** Span ms left of it at its own rate. */
+    natural: number;
+    /** A playing child has started, and stays at the front. */
+    state: 'pending' | 'playing';
+    /** How many times faster it may play; 1 for no faster. */
+    faster: number;
+    /** How many times slower it may play; 1 for no slower. */
+    slower: number;
+    /** Whether it may run alongside the one before it where the span's order would not have it. */
+    overlap: boolean;
+    /** Whether it may jump to its end instead of playing. */
+    ballast: boolean;
+    priority: Strength;
+}
+/**
+ * The span as a fit sees it.
+ *
+ * @category score
+ */
+export interface SpanClaim {
+    /** Span ms left of its budget; Infinity for a span with none. */
+    left: number;
+    /** Its whole budget. */
+    budget: number;
+    priority: Strength;
+    order: Order;
+    /** How far through the one before a staggered child starts, 0..1. */
+    share: number;
+}
+/**
+ * What a fit decides, per child in the order given: a rate over its own, and whether it is
+ * skipped. `share` is how far through the one before a child that may overlap starts, and `allow`
+ * the span ms the span may run past its budget.
+ *
+ * @category score
+ */
+export interface FitPlan {
+    rate: number[];
+    skip: boolean[];
+    share: number;
+    allow: number;
+}
+/**
+ * A strategy for fitting a span's children into its budget: from the plan so far to a new one.
+ *
+ * @category score
+ */
+export type Fit = (span: SpanClaim, kids: readonly Claim[], plan: FitPlan) => FitPlan;
+/** How far through the one before a child starts under each order, before any fit. */
+export declare function shareOf(order: Order, stagger: number): number;
+/**
+ * The plan before any fit: every child at its own rate, played, in the span's order.
+ *
+ * @category score
+ */
+export declare function plain(span: SpanClaim, kids: readonly Claim[]): FitPlan;
+/**
+ * Where a plan puts each child, span ms from now, and how long they take together. A playing child
+ * is where it is, at 0; each pending one starts its share through the one before it.
+ *
+ * @category score
+ */
+export declare function layout(span: SpanClaim, kids: readonly Claim[], plan: FitPlan): {
+    at: number[];
+    length: number;
+};
+/**
+ * Moves every child's rate by one factor toward the budget, before the span's fit: faster where
+ * they run past it, each no faster than its `faster` allows, and slower where they leave room in
+ * it, each no slower than its `slower` allows, so they fill it.
+ */
+export declare function rescale(span: SpanClaim, kids: readonly Claim[], plan: FitPlan): FitPlan;
+/**
+ * Starts children that may overlap sooner after the one before, toward all at once, until they
+ * fit.
+ *
+ * @category score
+ */
+export declare function condense(): Fit;
+/**
+ * Jumps children that may be skipped to their end, latest first, until they fit.
+ *
+ * @category score
+ */
+export declare function shed(): Fit;
+/**
+ * Jumps every child left to its end at once, whether or not it fits otherwise.
+ *
+ * @category score
+ */
+export declare function conclude(): Fit;
+/**
+ * Lets the span run past its budget: up to `cap` times it, or without limit.
+ *
+ * @category score
+ */
+export declare function overrun(opts?: {
+    cap?: number;
+}): Fit;
+/**
+ * Tries each fit in turn, handing the plan on, and stops once the children fit.
+ *
+ * @category score
+ */
+export declare function pipe(...fits_: readonly Fit[]): Fit;
+/**
+ * Every way of giving way after the span's retiming, overrunning only once the rest are spent.
+ *
+ * @category score
+ */
+export declare function lax(opts?: {
+    cap?: number;
+}): Fit;
+/** The fit a span takes without one of its own. */
+export declare const defaultFit: Fit;
+/**
+ * A span's fit settled: the plan, and what it had to do past the strategy, which starts from the
+ * children retimed toward the budget. Where the children still
+ * do not fit, a span weaker than `strong` lets them run long; otherwise `spill` either skips
+ * every child weaker than the span (`instant`), or lets them run long (`overrun`).
+ */
+export declare function settle(span: SpanClaim, kids: readonly Claim[], fit: Fit, spill: 'instant' | 'overrun'): {
+    plan: FitPlan;
+    fell: boolean;
+};