@msb235/blits 0.7.1 → 0.8.0

package/dist/voice.js

@@ -3,7 +3,7 @@ import { curve } from './easing.js';
 import { motionOf } from './motion.js';
 import { Named } from './named.js';
 import { childPlayed, Holding, mixTime, ownedElapsed, ownerPatch } from './owner.js';
-import { builtOf, durationOf, intosOf } from './patch.js';
+import { builtOf, intosOf } from './patch.js';
 import { reading } from './reading.js';
 import { Store } from './store.js';
 export const none = Object.freeze([]);
@@ -118,17 +118,32 @@ export class Voice {
     holder = null;
     /** Whether its channels run as lanes this frame, so the general fold passes it by. */
     laned = false;
-    /** How many times it has been sought, so a delta read before a seek is not handed out after it. */
+    /**
+     * How many times it has been sought or touched, so a delta read before either is not handed out
+     * after it.
+     */
     seeks = 0;
+    /** Whether the host has written to its handle, so it no longer plays as it was cued. */
+    written = false;
+    /** How many of `seeks` were the mix's `touch`, which moves no clock. */
+    touches = 0;
+    /** How many times its clock has jumped, which a booker counts hits again from. */
+    get jumps() {
+        return this.seeks - this.touches;
+    }
+    /** Seeks that rebuild state; a record stamped with fewer makes its state again before stepping. */
+    rebuilds = 0;
+    /** Whether its span's last fit jumped it to its end, which leaves it no time in that fit. */
+    skipped = false;
     /** Whether its patch has kept state on a record through `setting.keep`, which makes it stateful. */
     keeping = false;
     /** Subjects fading out of this voice alone, by the ramp each started; null while none are. */
     parts = null;
-    /** Subjects faded out of this voice, by the mix time each left at; null while none have. */
+    /** Subjects faded out of this voice, by the mix time and frame each left at; null while none have. */
     parted = null;
     /**
-     * Under history, the records of subjects that left this voice, by the mix time each left at,
-     * while a seek or a read back may reach them; null while none have.
+     * Under history, the records of subjects that left this voice, by the mix time and frame each
+     * left at, while a seek or a read back may reach them; null while none have.
      */
     left = null;
     ease;
@@ -146,8 +161,13 @@ export class Voice {
     opened = Number.NaN;
     /** Which of its entries in the mix's due queue is current; older ones are skipped when popped. */
     dueToken = 0;
-    /** Records made while it was pending, whose `since` its start may since have moved. */
+    /**
+     * Records whose `since` was still ahead when last worked out, which a later start, rate change
+     * or seek moves; null while none are.
+     */
     early = null;
+    /** The clocks it ran on before its current one, where a subject's origin may lie; null for none. */
+    clocks = null;
     /** Reused for every call this voice makes, so it is valid only during the call. */
     setting;
     /** Every subject this voice has been asked about, so a handover knows when it is finished. */
@@ -157,8 +177,12 @@ export class Voice {
     restedCount = 0;
     /** The mix time it was cued at; -Infinity before the first sync. */
     cuedAt = Number.NEGATIVE_INFINITY;
-    /** The mix time it left at. */
+    /** The frame it was cued in. */
+    cuedSeq = Number.NEGATIVE_INFINITY;
+    /** The mix time it left at, which a fade or seek given a time already passed puts behind now. */
     doneAt = Number.POSITIVE_INFINITY;
+    /** The frame its leaving was decided in, which a seek or read back partitions by. */
+    doneSeq = Number.POSITIVE_INFINITY;
     /** Under `history`, its controls after each change, oldest first. */
     log = null;
     /** Under `history`, its controls as `cue` left them, which a voice parked by a seek takes back. */
@@ -187,6 +211,20 @@ export class Voice {
     unreached = null;
     /** By subject number, a bit set where `unreached` stands for the subject; null until one is. */
     unreachedBits = null;
+    /** Whether one record stands for every subject: see `shares` in `everyone.ts`. */
+    sharing = false;
+    /** That record, null until a chain first asks and once the voice shares no more. */
+    everyone = null;
+    /** While sharing, by subject number: a bit where a chain has asked about the subject. */
+    sighted = null;
+    /** While sharing, by subject number: the weight last given the subject on the general path. */
+    weights = null;
+    /**
+     * While sharing a patch that is called, by subject number: when it was last called for the
+     * subject and at what `seeks`, side by side, and the delta that call gave.
+     */
+    stamps = null;
+    deltas = null;
     /** The handle `cue` returned, which `voices` hands back too. */
     handle = null;
     /** With a history store, the key of every subject it has a record of; null without one. */
@@ -201,8 +239,10 @@ export class Voice {
      */
     finished = false;
     playedAs = undefined;
-    /** The mix time `played` was settled at, so a seek back to before it can open it again. */
+    /** The mix time `played` was settled at. */
     playedAt = Number.NaN;
+    /** The frame `played` was settled in, so a seek back to before it can open it again. */
+    playedSeq = Number.NaN;
     donePromise = null;
     doneSettle = null;
     playedPromise = null;
@@ -241,18 +281,19 @@ export class Voice {
      * Its finite loop ended (true) or it left first (false), whichever comes first, noticed at mix
      * time `at`: `played` resolves.
      */
-    play(played, at) {
+    play(played, at, seq) {
         if (this.quiet || this.playedAs !== undefined)
             return;
         this.playedAs = played;
         this.playedAt = at;
+        this.playedSeq = seq;
         this.playedSettle?.(played);
         if (played && this.owner !== null)
-            childPlayed(this.owner, at);
+            childPlayed(this.owner, at, seq);
     }
-    /** How `played` settled, and the mix time it did; undefined while it has not. */
+    /** How `played` settled, and the mix time and frame it did; undefined while it has not. */
     get settled() {
-        return { played: this.playedAs, at: this.playedAt };
+        return { played: this.playedAs, at: this.playedAt, seq: this.playedSeq };
     }
     /** Whether `played` settled true, which its owner counted. */
     get passed() {
@@ -263,42 +304,50 @@ export class Voice {
         return this.playedAs === false;
     }
     /**
-     * A seek back to mix time `t`: `done` and `played`, where they settled after it, start over with
+     * A seek back to frame `seq`: `done` and `played`, where they settled after it, start over with
      * fresh promises. True where `played` had settled true, which its owner counted.
      */
-    reopen(t) {
+    reopen(seq) {
         let unplayed = false;
-        if (this.playedAs !== undefined && !(this.playedAt <= t)) {
+        if (this.playedAs !== undefined && !(this.playedSeq <= seq)) {
             unplayed = this.playedAs;
             this.playedAs = undefined;
             this.playedPromise = null;
             this.playedSettle = null;
         }
-        if (this.finished && !(this.doneAt <= t)) {
+        if (this.finished && !(this.doneSeq <= seq)) {
             this.finished = false;
             this.donePromise = null;
             this.doneSettle = null;
         }
         return unplayed;
     }
-    /**
-     * A seek back to before its cue: out of the mix, as `cue` left it, until the mix plays the cue
-     * again. What it played since is forgotten, and `done` and `played` start over where they had
-     * settled.
-     */
-    park() {
-        this.reopen(Number.NEGATIVE_INFINITY);
-        const c = this.first;
+    /** Takes on a set of controls: its clock, weight, fades and where its anchors put it. */
+    take(c) {
         this.anchorNow = c.anchorNow;
         this.anchorElapsed = c.anchorElapsed;
         this.rate = c.rate;
         this.ramp = c.ramp;
         this.weight = c.weight;
         this.out = c.out;
+        this.back = c.back;
         this.start = c.start;
         this.outAt = c.outAt;
         this.outOver = c.outOver;
         this.outSet = c.outSet;
+        this.rebuilds = c.rebuilds;
+        const clocks = this.clocks;
+        if (clocks !== null && clocks.length !== c.past)
+            this.clocks = c.past === 0 ? null : clocks.slice(0, c.past);
+    }
+    /**
+     * A seek back to before its cue: out of the mix, as `cue` left it, until the mix plays the cue
+     * again. What it played since is forgotten, and `done` and `played` start over where they had
+     * settled.
+     */
+    park() {
+        this.reopen(Number.NEGATIVE_INFINITY);
+        this.take(this.first);
         this.log = null;
         this.state = 'pending';
         this.subjects = new Store();
@@ -316,7 +365,9 @@ export class Voice {
         this.latest = 0;
         this.restedCount = 0;
         this.cuedAt = Number.NEGATIVE_INFINITY;
+        this.cuedSeq = Number.NEGATIVE_INFINITY;
         this.doneAt = Number.POSITIVE_INFINITY;
+        this.doneSeq = Number.POSITIVE_INFINITY;
         this.placing = false;
         this.answers = null;
         this.folds = null;
@@ -324,6 +375,12 @@ export class Voice {
         this.ownKept = null;
         this.unreached = null;
         this.unreachedBits = null;
+        this.sharing = false;
+        this.everyone = null;
+        this.sighted = null;
+        this.weights = null;
+        this.stamps = null;
+        this.deltas = null;
         if (this.holding !== null)
             this.holding = new Holding();
     }
@@ -346,13 +403,13 @@ export class Voice {
             : undefined;
         this.ease = fade.ease === undefined ? undefined : curve(fade.ease);
         this.passes = passesOf(spec.loop);
-        this.duration = durationOf(patch);
+        this.duration = patch.duration;
         this.span =
             this.duration > 0 && Number.isFinite(this.passes)
                 ? this.duration * this.passes
                 : Number.POSITIVE_INFINITY;
         this.motion = motionOf(patch);
-        const freezes = this.motion === undefined ? (spec.freeze ?? spec.hold) : undefined;
+        const freezes = this.motion === undefined ? spec.freeze : undefined;
         // A voice with no freeze of its own takes its owner's.
         const inherits = freezes === undefined && this.motion === undefined && owner !== null;
         this.freezesBefore = inherits
@@ -375,10 +432,11 @@ export class Voice {
         const t = timeWith(this, elapsed);
         return this.owner === null ? t : mixTime(this.owner, t);
     }
-    /** Records this voice's controls as they stand, from mix time `at`. */
-    note(at, sync = false) {
+    /** Records this voice's controls as they stand, from mix time `at` in frame `seq`. */
+    note(at, seq, sync = false) {
         this.log?.push({
             at,
+            seq,
             sync,
             anchorNow: this.anchorNow,
             anchorElapsed: this.anchorElapsed,
@@ -391,13 +449,17 @@ export class Voice {
             outAt: this.outAt,
             outOver: this.outOver,
             outSet: this.outSet,
+            rebuilds: this.rebuilds,
+            past: this.clocks?.length ?? 0,
         });
     }
     /**
      * A copy for a projection: its own setting, which sends nothing, and its own per-subject records,
-     * filled from `fill`. With `controls` it takes those, as the voice stood at an earlier time.
+     * filled from `fill`. With `controls` it takes those, as the voice stood at an earlier time. With
+     * `share`, a voice keeping one record for every subject gives its copy a copy of that one, which
+     * a read ahead starts every subject from; `fill` then serves only a copy that shares no more.
      */
-    copy(fill, controls) {
+    copy(fill, controls, share = false) {
         // A literal keeps the copy in fast mode, where `Object.assign` left it a dictionary that every
         // read in a projection looked up by name.
         const v = { __proto__: Voice.prototype, ...this };
@@ -411,22 +473,22 @@ export class Voice {
         v.laned = false;
         v.log = null;
         v.early = null;
-        if (controls) {
-            v.anchorNow = controls.anchorNow;
-            v.anchorElapsed = controls.anchorElapsed;
-            v.rate = controls.rate;
-            v.ramp = controls.ramp;
-            v.weight = controls.weight;
-            v.out = controls.out;
-            v.back = controls.back;
-            v.start = controls.start;
-            v.outAt = controls.outAt;
-            v.outOver = controls.outOver;
-            v.outSet = controls.outSet;
-        }
+        if (controls)
+            v.take(controls);
+        if (v.clocks === this.clocks && v.clocks !== null)
+            v.clocks = v.clocks.slice();
         v.quiet = true;
         v.unreached = null;
         v.unreachedBits = null;
+        const all = share && this.sharing ? this.everyone : null;
+        v.sharing = all !== null;
+        // Its delta is the live voice's to write into, and a keys voice's is in the live scratch.
+        v.everyone =
+            all === null ? null : { ...all, delta: null, probed: Number.NaN, from: all.stepped };
+        v.sighted = null;
+        v.weights = null;
+        v.stamps = null;
+        v.deltas = null;
         return v;
     }
     rateAt(now) {

package/dist/wave.d.ts

@@ -0,0 +1,42 @@
+import type { Kit, Patch } from './types.js';
+/**
+ * The shape of one cycle of a `wave`.
+ *
+ * @category patch
+ */
+export type WaveShape = 'sine' | 'triangle' | 'saw' | 'square';
+/**
+ * What `wave` takes besides its duration.
+ *
+ * @category patch
+ */
+export interface WaveOptions<O> {
+    /** Default 'sine'. */
+    shape?: WaveShape;
+    /** Whole or fractional cycles per pass of the patch's duration. Default 1. */
+    cycles?: number;
+    /** Where in its cycle the wave starts, 0..1. Default 0. */
+    phase?: number;
+    /** Peak swing per channel, either side of the channel's rest. Its keys are the patch's writes,
+     *  and only a channel holding a number can take one. */
+    depth: {
+        [K in keyof O as NonNullable<O[K]> extends number ? K : never]?: number;
+    };
+    /** The channels this wave was written against, which `cue` checks a mix's kit against. Each
+     *  channel swings around its rest here, so a `mul` channel pulses around 1; without it, around 0. */
+    kit?: Partial<Kit<O>>;
+}
+/**
+ * The unit wave: -1..1 at `x` cycles, starting at 0 and rising (square: +1 for the first half).
+ *
+ * @category patch
+ */
+export declare function waveAt(shape: WaveShape, x: number): number;
+/**
+ * A periodic swing on each channel `depth` names, around its rest: an LFO for a bob, a sway or a
+ * pulse. An `fn` patch that keeps its options on `patch.wave`, for an engine reading the wave
+ * rather than calling it.
+ *
+ * @category patch
+ */
+export declare function wave<I, O>(duration: number, opts: WaveOptions<O>): Patch<I, O, void>;

package/dist/wave.js

@@ -0,0 +1,62 @@
+import { patch } from './patch.js';
+/**
+ * The unit wave: -1..1 at `x` cycles, starting at 0 and rising (square: +1 for the first half).
+ *
+ * @category patch
+ */
+export function waveAt(shape, x) {
+    const u = x - Math.floor(x);
+    switch (shape) {
+        case 'sine':
+            return Math.sin(2 * Math.PI * u);
+        case 'triangle':
+            return u < 0.25 ? 4 * u : u < 0.75 ? 2 - 4 * u : 4 * u - 4;
+        case 'saw':
+            return u < 0.5 ? 2 * u : 2 * u - 2;
+        case 'square':
+            return u < 0.5 ? 1 : -1;
+    }
+}
+const plans = new WeakMap();
+function planOf(opts) {
+    let plan = plans.get(opts);
+    if (plan === undefined) {
+        const depth = opts.depth;
+        const writes = Object.keys(depth);
+        plan = {
+            shape: opts.shape ?? 'sine',
+            cycles: opts.cycles ?? 1,
+            start: opts.phase ?? 0,
+            writes,
+            depths: writes.map((c) => depth[c]),
+            rests: writes.map((c) => {
+                const rest = opts.kit?.[c]?.rest;
+                return typeof rest === 'number' ? rest : 0;
+            }),
+        };
+        plans.set(opts, plan);
+    }
+    return plan;
+}
+/**
+ * A periodic swing on each channel `depth` names, around its rest: an LFO for a bob, a sway or a
+ * pulse. An `fn` patch that keeps its options on `patch.wave`, for an engine reading the wave
+ * rather than calling it.
+ *
+ * @category patch
+ */
+export function wave(duration, opts) {
+    const own = planOf(opts);
+    const made = patch(duration, 
+    // A copy of the patch carries this `at` with a `wave` of its own, which it is read by.
+    function at(phase) {
+        const plan = this.wave === opts ? own : planOf(this.wave);
+        const unit = waveAt(plan.shape, phase * plan.cycles + plan.start);
+        const out = {};
+        for (let i = 0; i < plan.writes.length; i++)
+            out[plan.writes[i]] =
+                plan.rests[i] + plan.depths[i] * unit;
+        return out;
+    }, { writes: own.writes, kit: opts.kit });
+    return { ...made, wave: opts };
+}

package/dist/weigh.js

@@ -39,7 +39,7 @@ export function ownedBy(voice, subject) {
  */
 export function ownerBase(owner, subject) {
     const now = this.now;
-    const held = this.held(owner, subject, now, -1);
+    const held = this.held(owner, subject, -1);
     if (held.probed === this.frame)
         return held.phase;
     const kept = reading.kept;