@msb235/blits 0.9.0 → 0.11.0

package/dist/voice.d.ts

@@ -12,7 +12,8 @@ import { Store } from './store.js';
 import type { Anchor, Channel, FadeSpec, Handle, Patch, Setting, VoiceSpec } from './types.js';
 /**
  * A subject's record as it left a voice, faded out of it or dropped: the mix time and frame it
- * left at, and `sync` where the frame's sync made it, before the frame was read.
+ * left at, and `sync` where it shows in its own frame: left in the frame's sync, or before anything
+ * read the mix that frame.
  */
 export interface Left<I> {
     subject: I;
@@ -20,8 +21,40 @@ export interface Left<I> {
     seq: number;
     sync: boolean;
     held: Subject<unknown>;
+    /**
+     * The voice's fade of the subject as it stood on leaving, which a seek or read back to before
+     * puts back: its ramp out, while running, or its having faded out.
+     */
+    ramp: Parting | null;
+    parted: Parted | null;
+}
+/** A subject's ramp out of one voice: when it began, how long it runs, and the frame it was asked in. */
+export interface Parting {
+    at: number;
+    over: number;
+    seq: number;
+}
+export interface Parted {
+    at: number;
+    seq: number;
+    ramp: Parting | undefined;
 }
 export declare const none: readonly string[];
+/**
+ * What a copy of a record keeps for the seeks that put a record back from it: the copy's state
+ * stepped on to `ticks`, as it stood near `at`, a moment one of them sought.
+ */
+export interface Ahead<S> {
+    /** The record the last seek put back, and the moment it sought, until that record steps. */
+    put: Subject<S> | null;
+    sought: number;
+    /** The `since` of the record put back, which the steps in `state` were counted from. */
+    since: number;
+    at: number;
+    ticks: number;
+    /** Undefined until a record has stepped on from the copy. */
+    state: S | undefined;
+}
 /** Everything one voice holds for one subject, chained through the next voice that reaches it. */
 export interface Subject<S> {
     /** The voice's `target` answer, fixed on first sight. */
@@ -56,6 +89,8 @@ export interface Subject<S> {
     seeks: number;
     /** The voice's `rebuilds` when its state was last made, so a seek's rebuild reaches it once. */
     rebuilt: number;
+    /** Its kept signal state was stepped on in one go from a copy history kept, by a seek. */
+    copied: boolean;
     /** Stop 0 for a `from: 'current'` voice, taken the first frame this subject is seen. */
     base?: Record<string, unknown>;
     /** The pose's velocity per channel at that moment, units per ms, so the first segment leaves at it. */
@@ -69,6 +104,7 @@ export interface Subject<S> {
         at: number;
         seq: number;
         held: Subject<S>;
+        ahead?: Ahead<S>;
     }[];
     /** In a projection: where this record started from, and whether nothing known could be. */
     from?: number;
@@ -203,16 +239,12 @@ export declare class Voice<I, O> {
     /** Whether its patch has kept state on a record through `setting.keep`, which makes it stateful. */
     keeping: boolean;
     /** Subjects fading out of this voice alone, by the ramp each started; null while none are. */
-    parts: Map<I, {
-        at: number;
-        over: number;
-        seq: number;
-    }> | null;
-    /** Subjects faded out of this voice, by the mix time and frame each left at; null while none have. */
-    parted: Map<I, {
-        at: number;
-        seq: number;
-    }> | null;
+    parts: Map<I, Parting> | null;
+    /**
+     * Subjects faded out of this voice, by the mix time and frame each left at, and the ramp that
+     * took it out, which a seek or a read back into it puts back; null while none have.
+     */
+    parted: Map<I, Parted> | null;
     /**
      * 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.
@@ -237,6 +269,8 @@ export declare class Voice<I, O> {
     readonly freezesAfter: boolean;
     /** The mix time it first showed: when it was cued, or the first sync after. */
     opened: number;
+    /** Whether no delta its patch's `at` returned has been checked against `writes` yet. */
+    unchecked: boolean;
     /** Which of its entries in the mix's due queue is current; older ones are skipped when popped. */
     dueToken: number;
     /**
@@ -255,6 +289,8 @@ export declare class Voice<I, O> {
     /** The least stagger of any subject seen, 0 or below, which a voice running back ends at. */
     soonest: number;
     restedCount: number;
+    /** Whether a seek back to before its cue has it out of the mix, until the mix plays the cue again. */
+    parked: boolean;
     /** The mix time it was cued at; -Infinity before the first sync. */
     cuedAt: number;
     /** The frame it was cued in. */
@@ -411,6 +447,11 @@ export declare class Voice<I, O> {
      * fading out from where it ran back to its start, as one fading from its end shows its last.
      */
     get holdsFirst(): boolean;
+    /**
+     * Whether a subject past the end of its passes shows nothing: its clock runs back, so it has yet
+     * to reach them, and it does not freeze after.
+     */
+    get hidesPast(): boolean;
     /** A subject's voice time at `raw` once the voice's freezes apply; NaN where it shows nothing. */
     shownAt(raw: number): number;
     /** Records this voice's controls as they stand, from mix time `at` in frame `seq`. */
@@ -426,3 +467,8 @@ export declare class Voice<I, O> {
     /** Moves the anchor to `now`, carrying what is left of a ramp. */
     rebase(now: number): void;
 }
+/**
+ * Warns, once a patch outside production, of a key the first delta `voice` read returns outside its
+ * patch's `writes`, which the mix drops.
+ */
+export declare function checkWrites<I, O>(voice: Voice<I, O>, delta: object | null): void;

package/dist/voice.js

@@ -6,6 +6,7 @@ import { childPlayed, Holding, mixTime, ownedElapsed, ownerPatch, ownerReading,
 import { builtOf, intosOf } from './patch.js';
 import { reading } from './reading.js';
 import { Store } from './store.js';
+import { warnOnce } from './warn.js';
 export const none = Object.freeze([]);
 /**
  * A voice's `setting.keep`, one per voice: a setting is valid only during its call, so the state
@@ -62,19 +63,26 @@ class VoiceSetting {
 /** A store that fills a missing entry from `make` on first ask. */
 class Filled extends Store {
     make;
+    /** Keys deleted here, which are made afresh by whoever asks and never again by `make`. */
+    gone = null;
     constructor(make) {
         super();
         this.make = make;
     }
     get(key) {
         let v = super.get(key);
-        if (v === undefined) {
+        if (v === undefined && this.gone?.get(key) !== true) {
             v = this.make(key);
             if (v !== undefined)
                 super.set(key, v);
         }
         return v;
     }
+    delete(key) {
+        super.delete(key);
+        this.gone ??= new Store();
+        this.gone.set(key, true);
+    }
 }
 const noSend = () => { };
 export class Voice {
@@ -139,7 +147,10 @@ export class Voice {
     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 and frame each left at; null while none have. */
+    /**
+     * Subjects faded out of this voice, by the mix time and frame each left at, and the ramp that
+     * took it out, which a seek or a read back into it puts back; null while none have.
+     */
     parted = null;
     /**
      * Under history, the records of subjects that left this voice, by the mix time and frame each
@@ -165,6 +176,8 @@ export class Voice {
     freezesAfter;
     /** The mix time it first showed: when it was cued, or the first sync after. */
     opened = Number.NaN;
+    /** Whether no delta its patch's `at` returned has been checked against `writes` yet. */
+    unchecked = true;
     /** Which of its entries in the mix's due queue is current; older ones are skipped when popped. */
     dueToken = 0;
     /**
@@ -183,6 +196,8 @@ export class Voice {
     /** The least stagger of any subject seen, 0 or below, which a voice running back ends at. */
     soonest = 0;
     restedCount = 0;
+    /** Whether a seek back to before its cue has it out of the mix, until the mix plays the cue again. */
+    parked = false;
     /** The mix time it was cued at; -Infinity before the first sync. */
     cuedAt = Number.NEGATIVE_INFINITY;
     /** The frame it was cued in. */
@@ -362,6 +377,7 @@ export class Voice {
     park() {
         this.reopen(Number.NEGATIVE_INFINITY);
         this.take(this.first);
+        this.parked = true;
         this.log = null;
         this.state = 'pending';
         this.subjects = new Store();
@@ -529,9 +545,20 @@ export class Voice {
     get holdsFirst() {
         return this.freezesBefore || this.out?.back === true;
     }
+    /**
+     * Whether a subject past the end of its passes shows nothing: its clock runs back, so it has yet
+     * to reach them, and it does not freeze after.
+     */
+    get hidesPast() {
+        return !this.freezesAfter && this.backs !== (this.owner !== null && turnedBack(this));
+    }
     /** A subject's voice time at `raw` once the voice's freezes apply; NaN where it shows nothing. */
     shownAt(raw) {
-        return this.beginless ? raw : frozenTime(raw, this.holdsFirst, this.freezesAfter, this.span);
+        if (this.beginless)
+            return raw;
+        if (raw > this.span && this.hidesPast)
+            return Number.NaN;
+        return frozenTime(raw, this.holdsFirst, this.freezesAfter, this.span);
     }
     /** Records this voice's controls as they stand, from mix time `at` in frame `seq`. */
     note(at, seq, sync = false) {
@@ -600,3 +627,16 @@ export class Voice {
         rebaseWith(this, now);
     }
 }
+/**
+ * Warns, once a patch outside production, of a key the first delta `voice` read returns outside its
+ * patch's `writes`, which the mix drops.
+ */
+export function checkWrites(voice, delta) {
+    voice.unchecked = false;
+    if (delta === null || typeof delta !== 'object')
+        return;
+    const writes = voice.patch.writes;
+    for (const key in delta)
+        if (!writes.includes(key))
+            warnOnce(voice.patch, `${voice.spec.name ?? `voice ${voice.id}`}'s patch returns ${key} from at(), which is not in its writes, so the mix drops it`);
+}