@msb235/blits 0.8.1 → 0.9.0

package/dist/types/patch.d.ts

@@ -39,12 +39,16 @@ export interface Setting<S = void, H = unknown> {
      * The gap this subject is catching up by: milliseconds since it last advanced, which is the gap
      * since the previous sync only for a subject sampled every frame. Infinity under reduced motion;
      * no more than `maxDt` where the mix sets one. Inside a `step` under `stepMs`, it is `stepMs`, and
-     * `timestamp` is the end of that interval.
+     * `timestamp` is the end of that interval. A lane samples a subject for one frame after its last
+     * probe. A read by `project` is one sample, so its gap is not the gap a frame of play has.
      */
     dt: number;
-    /** Milliseconds this voice has been playing, rate applied. */
+    /**
+     * Milliseconds this voice has been playing, rate applied. Below 0 only for a voice with no end
+     * cued backward, which plays into the passes before its first.
+     */
     elapsed: number;
-    /** Which pass this is, 0 first. */
+    /** Which pass this is, 0 first; below 0 where `elapsed` is. */
     pass: number;
     /** This voice's weight for this subject this frame, after fades, signals and any locus. */
     weight: number;

package/dist/types/place.d.ts

@@ -55,7 +55,10 @@ export type Anchor = {
  * Where a voice sits on the mix clock: at most one of `start` and `in`, and at most one of `out`
  * and `end`, each a timestamp on the host's clock or an anchor to another voice. A voice whose
  * anchor has no answer yet waits pending; one whose anchored mark is already past starts partway
- * through, as playback does from the middle of a region.
+ * through, as playback does from the middle of a region. A fade out begins no earlier than the
+ * voice starts: an `end` that leaves less room than `fade.out` shortens the fade to fit, and one
+ * before the start makes the voice an instant, which starts and ends at its start and shows
+ * nothing.
  *
  * @category score
  */

package/dist/types/voice.d.ts

@@ -61,15 +61,30 @@ export interface VoiceSpec<I, O, H = unknown> extends SpanHints {
     subjects?: readonly I[];
     /**
      * When the voice starts, in ms on the host's clock, the one it passes `sync`: a rAF timestamp and
-     * `performance.now()` share an origin, `Date.now()` does not. Default: the next sync.
+     * `performance.now()` share an origin, `Date.now()` does not. Default: the time the mix last
+     * synced to, and 0 for a voice cued before the first sync, which that sync finds already as far
+     * in as its timestamp.
      */
     start?: number;
-    /** Playback rate. 1 is real time; 0 freezes. */
+    /**
+     * Playback rate. 1 is real time; 0 freezes; below 0 plays backward, to end where the voice
+     * starts as a voice playing forward ends where its last pass does: `played` resolves, and it
+     * leaves over `fade.out` or, freezing before, holds its first frame.
+     */
     rate?: number;
+    /**
+     * Where in itself the voice starts, in voice ms, as `seek` on its handle sets. Default 0, or
+     * for a voice cued backward its end: `duration` times its passes. A voice with no end cued
+     * backward (a loop for good, or a patch with no duration) starts at 0 and has no first pass
+     * either: it plays into the pass before, `setting.pass` and `setting.elapsed` below 0, for
+     * every subject from the voice's start whatever its stagger. A motion's stretches begin at 0,
+     * so one cued backward with no `seek` has ended as it starts.
+     */
+    seek?: number;
     /**
      * true loops for good, false plays one pass, n plays n passes. A finite loop leaves when its
      * passes are done for the latest-staggered subject it has seen — over `fade.out` where one is
-     * set, at once where none is — unless it freezes after.
+     * set, at once where none is — unless it freezes after. Default: true.
      */
     loop?: boolean | number;
     /**
@@ -249,7 +264,8 @@ export interface Handle<I = unknown> {
     weight: number;
     /**
      * Playback rate now. Setting it changes speed at once; `ramp` eases into a new one. On a voice
-     * still pending, a rate above 0 applies from the voice's start, which stays where it is.
+     * still pending, a rate or a ramp applies from the voice's start, which stays where it is: at
+     * rate 0 it starts on time and holds its first frame.
      */
     rate: number;
     /**
@@ -265,6 +281,8 @@ export interface Handle<I = unknown> {
      * it was. Answers how sure the state now is: `exact` for a voice with none, or rebuilt under
      * `stepMs` with no `maxDt`; `stepped` where it was caught up in one step or holds signal state;
      * `held` where it was kept, or depends on host fields or an input weight the rebuild cannot know.
+     * A voice still pending starts on time, already at `elapsed`, and one that freezes before shows
+     * that frame while it waits.
      */
     seek(elapsed: number, opts?: SeekOptions): Doubt;
     /**

package/dist/unpage.d.ts

@@ -5,4 +5,4 @@ import type { Transport } from './transport.js';
  */
 export declare function cover(transport: Transport, t: number): boolean;
 /** A seek back to frame `seq`: what the store and `prepare` hold after it is from a future the tape makes again. */
-export declare function cut(transport: Transport, seq: number, unpaged: boolean): void;
+export declare function cut(transport: Transport, seq: number): void;

package/dist/unpage.js

@@ -30,12 +30,11 @@ export function cover(transport, t) {
     return true;
 }
 /** A seek back to frame `seq`: what the store and `prepare` hold after it is from a future the tape makes again. */
-export function cut(transport, seq, unpaged) {
+export function cut(transport, seq) {
     const pager = transport.pager;
     if (pager === null)
         return;
-    if (unpaged)
-        pager.store.cut(seq);
+    pager.store.cut(seq);
     const loaded = pager.loaded;
     if (loaded !== null)
         loaded.records = loaded.records.filter((r) => r.seq <= seq);

package/dist/voice.d.ts

@@ -127,6 +127,8 @@ export interface Ramp {
     over: number;
     rest: boolean;
     deadline?: number;
+    /** Begun where the voice ran back to its start, whose first frame it holds through the fade. */
+    back?: boolean;
 }
 /**
  * A climb back from a fade out that was turned around: from `from`, the place along the fade's
@@ -224,6 +226,12 @@ export declare class Voice<I, O> {
     readonly span: number;
     /** The state behind a motion patch, undefined for any other. */
     readonly motion: Motions<I> | undefined;
+    /**
+     * Whether it has no first pass: cued backward with no end to start from, it plays from 0 into
+     * the pass before, so no time on its clock is before its start. Never a motion, whose stretches
+     * begin at 0.
+     */
+    readonly beginless: boolean;
     /** Its `freeze`, for a patch it applies to: motion keeps its target already. */
     readonly freezesBefore: boolean;
     readonly freezesAfter: boolean;
@@ -244,6 +252,8 @@ export declare class Voice<I, O> {
     seen: number;
     /** The longest stagger of any subject seen, so a finite loop waits for the last of them. */
     latest: number;
+    /** The least stagger of any subject seen, 0 or below, which a voice running back ends at. */
+    soonest: number;
     restedCount: number;
     /** The mix time it was cued at; -Infinity before the first sync. */
     cuedAt: number;
@@ -253,6 +263,10 @@ export declare class Voice<I, O> {
     doneAt: number;
     /** The frame its leaving was decided in, which a seek or read back partitions by. */
     doneSeq: number;
+    /** The mix time of that frame, later than `doneAt` for a leaving put behind now. */
+    decidedAt: number;
+    /** The latest mix time a seek or read back to finds it still playing. */
+    get reachedTo(): number;
     /** Under `history`, its controls after each change, oldest first. */
     log: Controls[] | null;
     /** Under `history`, its controls as `cue` left them, which a voice parked by a seek takes back. */
@@ -361,6 +375,44 @@ export declare class Voice<I, O> {
     elapsedAt(now: number): number;
     /** The mix time its clock reads `elapsed`, inverting `elapsedAt`; Infinity where it never will. */
     timeAt(elapsed: number): number;
+    /**
+     * Whether its clock runs back by its controls: at a rate below 0, or on a ramp between rates
+     * neither of which is above it. A ramp through 0 says neither way until it has turned.
+     */
+    get backs(): boolean;
+    /** Whether its ramp takes its rate through 0, which turns its clock around partway. */
+    get turns(): boolean;
+    /**
+     * The mix time its passes run out by its controls now: its last pass's end running forward, its
+     * first pass's start running back. Infinity where they never do, and while a ramp has yet to
+     * turn it around.
+     */
+    endsAt(): number;
+    /**
+     * The mix time its clock ran back to `elapsed` by `now`, by its controls now: where a subject
+     * `elapsed` into it reached its start. NaN where it has not, and for a voice an owner holds.
+     */
+    ranBackTo(elapsed: number, now: number): number;
+    /** Whether it has yet to start at mix time `now`: pending, or fading out from before its start. */
+    unstarted(now: number): boolean;
+    /**
+     * A subject's voice time at mix time `now`, `delay` into the voice, before its freezes apply. A
+     * voice yet to start reads where it will: its clock is anchored there, and read at any time
+     * before would have a voice sought ahead, or running back, play before its start.
+     */
+    rawAt(now: number, delay: number): number;
+    /**
+     * Whether a subject at `raw` is before its start at mix time `now`: it shows nothing, or its
+     * first frame frozen.
+     */
+    before(raw: number, now: number): boolean;
+    /**
+     * Whether a subject before its start shows its first frame: the voice freezes before, or is
+     * fading out from where it ran back to its start, as one fading from its end shows its last.
+     */
+    get holdsFirst(): 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`. */
     note(at: number, seq: number, sync?: boolean): void;
     /**

package/dist/voice.js

@@ -1,8 +1,8 @@
-import { elapsedWith, passesOf, rateWith, rebaseWith, timeWith } from './clock.js';
+import { backWith, elapsedWith, frozenTime, passesOf, rateWith, rebaseWith, timeWith, } from './clock.js';
 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 { childPlayed, Holding, mixTime, ownedElapsed, ownerPatch, ownerReading, turnedBack, } from './owner.js';
 import { builtOf, intosOf } from './patch.js';
 import { reading } from './reading.js';
 import { Store } from './store.js';
@@ -154,6 +154,12 @@ export class Voice {
     span;
     /** The state behind a motion patch, undefined for any other. */
     motion;
+    /**
+     * Whether it has no first pass: cued backward with no end to start from, it plays from 0 into
+     * the pass before, so no time on its clock is before its start. Never a motion, whose stretches
+     * begin at 0.
+     */
+    beginless;
     /** Its `freeze`, for a patch it applies to: motion keeps its target already. */
     freezesBefore;
     freezesAfter;
@@ -174,6 +180,8 @@ export class Voice {
     seen = 0;
     /** The longest stagger of any subject seen, so a finite loop waits for the last of them. */
     latest = 0;
+    /** The least stagger of any subject seen, 0 or below, which a voice running back ends at. */
+    soonest = 0;
     restedCount = 0;
     /** The mix time it was cued at; -Infinity before the first sync. */
     cuedAt = Number.NEGATIVE_INFINITY;
@@ -183,6 +191,12 @@ export class Voice {
     doneAt = Number.POSITIVE_INFINITY;
     /** The frame its leaving was decided in, which a seek or read back partitions by. */
     doneSeq = Number.POSITIVE_INFINITY;
+    /** The mix time of that frame, later than `doneAt` for a leaving put behind now. */
+    decidedAt = Number.NEGATIVE_INFINITY;
+    /** The latest mix time a seek or read back to finds it still playing. */
+    get reachedTo() {
+        return this.doneAt > this.decidedAt ? this.doneAt : this.decidedAt;
+    }
     /** 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. */
@@ -363,6 +377,7 @@ export class Voice {
         this.early = null;
         this.seen = 0;
         this.latest = 0;
+        this.soonest = 0;
         this.restedCount = 0;
         this.cuedAt = Number.NEGATIVE_INFINITY;
         this.cuedSeq = Number.NEGATIVE_INFINITY;
@@ -419,7 +434,11 @@ export class Voice {
         this.setting = new VoiceSetting(host, send, this);
         this.rate = spec.rate ?? 1;
         this.weight = typeof spec.weight === 'number' ? spec.weight : 1;
+        const endless = !Number.isFinite(this.span);
+        this.beginless = this.rate < 0 && endless && this.motion === undefined;
         this.anchorNow = start;
+        // Where it starts: a voice cued backward at its end, where it has one.
+        this.anchorElapsed = spec.seek ?? (this.rate < 0 && !endless ? this.span : 0);
         if (now >= start)
             this.state = 'live';
     }
@@ -432,6 +451,88 @@ export class Voice {
         const t = timeWith(this, elapsed);
         return this.owner === null ? t : mixTime(this.owner, t);
     }
+    /**
+     * Whether its clock runs back by its controls: at a rate below 0, or on a ramp between rates
+     * neither of which is above it. A ramp through 0 says neither way until it has turned.
+     */
+    get backs() {
+        const r = this.ramp;
+        return r === null ? this.rate < 0 : r.from <= 0 && r.to <= 0 && (r.from < 0 || r.to < 0);
+    }
+    /** Whether its ramp takes its rate through 0, which turns its clock around partway. */
+    get turns() {
+        const r = this.ramp;
+        return r !== null && r.from * r.to < 0;
+    }
+    /**
+     * The mix time its passes run out by its controls now: its last pass's end running forward, its
+     * first pass's start running back. Infinity where they never do, and while a ramp has yet to
+     * turn it around.
+     */
+    endsAt() {
+        if (this.turns)
+            return Number.POSITIVE_INFINITY;
+        const backs = this.backs;
+        let to;
+        if (backs !== (this.owner !== null && turnedBack(this))) {
+            if (this.beginless)
+                return Number.POSITIVE_INFINITY;
+            to = this.soonest;
+        }
+        else {
+            if (!Number.isFinite(this.span))
+                return Number.POSITIVE_INFINITY;
+            to = this.span + this.latest;
+        }
+        const t = backs ? backWith(this, to) : timeWith(this, to);
+        return this.owner === null ? t : mixTime(this.owner, t);
+    }
+    /**
+     * The mix time its clock ran back to `elapsed` by `now`, by its controls now: where a subject
+     * `elapsed` into it reached its start. NaN where it has not, and for a voice an owner holds.
+     */
+    ranBackTo(elapsed, now) {
+        if (this.beginless || !this.backs || this.owner !== null)
+            return Number.NaN;
+        const t = backWith(this, elapsed);
+        return t >= this.anchorNow && t <= now ? t : Number.NaN;
+    }
+    /** Whether it has yet to start at mix time `now`: pending, or fading out from before its start. */
+    unstarted(now) {
+        const state = this.state;
+        if (state === 'pending')
+            return true;
+        if (state !== 'fading')
+            return false;
+        return !((this.owner === null ? now : ownerReading(this.owner, now)) >= this.start);
+    }
+    /**
+     * A subject's voice time at mix time `now`, `delay` into the voice, before its freezes apply. A
+     * voice yet to start reads where it will: its clock is anchored there, and read at any time
+     * before would have a voice sought ahead, or running back, play before its start.
+     */
+    rawAt(now, delay) {
+        return (this.unstarted(now) ? this.anchorElapsed : this.elapsedAt(now)) - delay;
+    }
+    /**
+     * Whether a subject at `raw` is before its start at mix time `now`: it shows nothing, or its
+     * first frame frozen.
+     */
+    before(raw, now) {
+        // Not `raw < 0`: see `frozenTime` for the clock that reads NaN before its start.
+        return (!(raw >= 0) && !this.beginless) || this.unstarted(now);
+    }
+    /**
+     * Whether a subject before its start shows its first frame: the voice freezes before, or is
+     * fading out from where it ran back to its start, as one fading from its end shows its last.
+     */
+    get holdsFirst() {
+        return this.freezesBefore || this.out?.back === true;
+    }
+    /** 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);
+    }
     /** Records this voice's controls as they stand, from mix time `at` in frame `seq`. */
     note(at, seq, sync = false) {
         this.log?.push({

package/dist/warn.d.ts

@@ -0,0 +1,2 @@
+/** Warns outside production, once for each `about`. */
+export declare function warnOnce(about: object, message: string): void;

package/dist/warn.js

@@ -0,0 +1,17 @@
+/** Whether this is a production build: a bundler's `NODE_ENV`, or Node's; false where neither is. */
+function production() {
+    try {
+        return process.env.NODE_ENV === 'production';
+    }
+    catch {
+        return false;
+    }
+}
+const warned = new WeakSet();
+/** Warns outside production, once for each `about`. */
+export function warnOnce(about, message) {
+    if (warned.has(about) || production())
+        return;
+    warned.add(about);
+    console.warn(`blits: ${message}`);
+}

package/dist/weigh.js

@@ -6,6 +6,9 @@ import { reading } from './reading.js';
 export function prime(voice, held, now, elapsed, pass) {
     const setting = voice.setting;
     setting.timestamp = now;
+    // With no step to move it, `stepped` follows the call before this frame's.
+    if (voice.patch.step === undefined && held.probed < now)
+        held.stepped = held.probed;
     setting.dt = this.capped(now - held.stepped);
     setting.elapsed = elapsed;
     setting.pass = pass;
@@ -43,6 +46,8 @@ export function ownerBase(owner, subject) {
     if (held.probed === this.frame)
         return held.phase;
     const kept = reading.kept;
+    // An owner's record keeps a frame in `probed`, not a time, so `prime` leaves its `stepped` be.
+    held.probed = Number.NaN;
     this.prime(owner, held, now, owner.elapsedAt(now), 0);
     const base = this.base(owner, subject, now, held);
     reading.kept = kept;