@msb235/blits 0.3.0 → 0.5.0

package/dist/motion.d.ts

@@ -1,5 +1,5 @@
 import { type Curve } from './easing.js';
-import type { Easing, Patch } from './types.js';
+import type { Easing, MotionSpec, Patch } from './types.js';
 /**
  * A number, or one number per axis.
  *
@@ -31,8 +31,23 @@ interface Change {
     to?: number[];
     v?: number[];
 }
-/** A motion patch's `frame` while no mix plays it: no subject has a latest frame. */
-export declare const noFrame: () => number;
+/**
+ * The mix playing a patch, asked with its voice's id: an owner and an id, where a pair of closures
+ * cost two functions, their contexts and a weak reference per voice.
+ */
+export interface MotionOwner {
+    /** The subject's voice time at the mix's latest frame; NaN where no frame of the voice met it. */
+    frame(id: number, subject: unknown): number;
+    /** Brings a subject the voice faded out back to it, so a change is not made for nothing. */
+    revive(id: number, subject: unknown): void;
+}
+/**
+ * What a mix keeping copies of a patch's stretches is told, with its id and the subject's number,
+ * before one changes.
+ */
+export interface Watcher {
+    stretchChanged(id: number, s: number): void;
+}
 /**
  * A patch whose motion is a closed form per subject, so it lands in the same place at any frame
  * rate, and whose changes mid-flight start from where the subject is and how fast it moves.
@@ -55,54 +70,103 @@ export type Moving<I, O, V extends Value> = Patch<I, O, void> & {
 };
 interface Shape<I> {
     from: (subject: I) => number[];
-    velocity: (subject: I) => number[];
+    /** How fast each axis starts moving, given where it starts: still unless the options say. */
+    velocity: (subject: I, x: number[]) => number[];
     /** Where it heads when released from `x` at `v`, given where it was heading. */
     aim: (x: number[], v: number[], was: number[] | null, subject: I) => number[];
     /** `[form, settle, k1, k2, k3]`. */
     law: readonly number[];
     /** Whether a subject's value is a number rather than an array. */
     scalar: (subject: I) => boolean;
+    /** Whether every subject's value is a number; undefined where that depends on the subject. */
+    scalarEvery(): boolean | undefined;
     /** A tween's easing, which its law cannot hold; undefined, but present, on every other shape. */
     ease: Curve | undefined;
+    /** A tween's seconds for a stretch the subject starts now; undefined, but present, on the rest. */
+    ms: ((subject: I) => number) | undefined;
+    /** The patch's kind and constants, as `Patch.motion` reports them. */
+    spec(): MotionSpec;
 }
 /**
  * A motion patch's subjects: the stretch each is playing, in one flat array by a number the patch
  * gives it, with earlier stretches a read back may reach and changes not yet applied beside them.
  * The one copy, read by `at` and by a mix's lane alike.
  *
- * After the law, each subject's run of `stride` numbers is its release time, its flags, then `x0`,
- * `v0` and `to` per axis. A live sample reads this one buffer and nothing else the patch owns: at
+ * After the law, each subject's run of `stride` numbers is its release time, its flags, a tween's
+ * seconds for the stretch, then `x0`, `v0` and `to` per axis. A live sample reads this one buffer and nothing else the patch owns: at
  * 10k springs of one subject each, a buffer per field, a map lookup per sample and the law in an
  * object of its own took a call from 130 ns to 490.
  */
 export declare class Motions<I> {
     private readonly shape;
     private readonly numbers;
+    /** Numbers by subject once a second is numbered: till then the one subject is found by `numbers`. */
     private readonly slots;
     /** Axes per subject; -1 until the first subject sets it. */
     n: number;
     private cap;
     private stride;
-    private runs;
+    /**
+     * The law, then each subject's run; empty until the first subject, the law read from `shape`.
+     * Read outside, at `bareAt`, and written only here.
+     */
+    runs: Float64Array<ArrayBuffer>;
     /**
      * Where `sample` leaves a subject's position and velocity, per axis. Shared by every patch, so
      * read it before the next sample.
      */
     xs: Float64Array<ArrayBuffer>;
     vs: Float64Array<ArrayBuffer>;
-    private readonly pending;
-    private readonly older;
     /**
-     * The subject's voice time at the mix's latest frame, which an untimed change and a `read` with
-     * no time take; NaN where no frame of the patch's voice has met the subject. Set by the mix that
-     * cues the patch, and put back when its voice retires.
+     * By subject number, changes not yet applied and earlier stretches a read back may reach: null
+     * until a subject first has one, since many patches are never changed. Each starts with room for
+     * one: an empty array written at 0 reserves 17, and most patches have one subject.
+     */
+    private pending;
+    private older;
+    /**
+     * The mix playing the patch and its voice's id, which an untimed change and a `read` with no time
+     * ask for the latest frame. Set by the mix that cues the patch, and cleared when its voice retires.
+     */
+    owner: MotionOwner | null;
+    ownerId: number;
+    /** Whether the channel it was cued on holds a number; undefined until it is cued. */
+    private holdsNumber;
+    private channel;
+    /**
+     * Records what the channel the patch is cued on holds, refusing a value of the other kind: at once
+     * where every subject's value is one kind, else on the first sample of a subject whose value is not.
      */
-    frame: (subject: I) => number;
+    cuedOn(channel: string, holdsNumber: boolean): void;
+    private frame;
     constructor(shape: Shape<I>);
     /** The patch's number for `subject`, made with its first stretch on first ask. */
     slot(subject: I): number;
+    /** The patch's number for `subject`, undefined where it has none. */
+    private known;
     /** Forgets a subject, so a later ask starts it afresh from `from`. */
     release(subject: I): void;
+    /**
+     * Told, with `watchId`, whenever a subject's stretch or what is pending for it changes, so a mix
+     * keeping a copy of it knows to read it again. Set by the mix, cleared when its voice retires. An
+     * owner and an id, where a callback cost a closure and its context per patch.
+     */
+    watcher: Watcher | null;
+    watchId: number;
+    /** The easing a tween's stretches follow; undefined for every other shape. */
+    get ease(): Curve | undefined;
+    /** The patch's kind and constants. */
+    spec(): MotionSpec;
+    /** A copy of the patch's law, `[form, settle, k1, k2, k3]`. */
+    law(): Float64Array;
+    /** Whether `law` holds this patch's law, number for number, as `Object.is` compares them. */
+    hasLaw(law: Float64Array): boolean;
+    /**
+     * Copies subject `s`'s current stretch into `out` from `o` as its release time, its seconds, then
+     * `x0`, `v0` and `to` per axis; false, copying nothing, while it has a change pending or an
+     * earlier stretch kept, which only `sample` handles.
+     */
+    stretchInto(s: number, out: Float64Array, o: number): boolean;
     /** Whether subject `s`'s value is a number rather than an array. */
     scalar(s: number): boolean;
     /** The value `at` hands the mix: the first axis for a number, a fresh array otherwise. */
@@ -113,6 +177,21 @@ export declare class Motions<I> {
      * a projection's read applies the timed ones to a copy and commits nothing.
      */
     sample(s: number, t: number, xo: Float64Array, vo: Float64Array): void;
+    /**
+     * Where subject `s`'s run starts in `runs` (its release time, then flags, seconds, `x0`, `v0`
+     * and `to`) while it has nothing pending and no earlier stretch kept; -1 for any other.
+     */
+    bareAt(s: number): number;
+    /**
+     * A live `sample` at `t` for a subject with nothing pending and no earlier stretch kept, true
+     * then; false, writing nothing, for any other, which `quiet` and `sample` take instead.
+     */
+    sampleBare(s: number, t: number, xo: Float64Array, vo: Float64Array): boolean;
+    /**
+     * Whether every subject has landed on its target at its voice time at the latest frame, as a
+     * sample there would find; one with a change waiting has not. Commits nothing.
+     */
+    landed(): boolean;
     /**
      * Whether a live `sample` at `t` would leave the subject's state as it is: nothing to stamp or
      * commit by then, and nothing older than `reading.horizon` to let go of.
@@ -135,9 +214,9 @@ export declare class Motions<I> {
     private peek;
     private check;
     private flag;
-    private forget;
+    forget(s: number): void;
     /** Where subject `s`'s run starts in `runs`. */
-    private base;
+    base(s: number): number;
     private grow;
     private write;
     /** The stretch subject `s` is playing now, as an object. */
@@ -151,9 +230,15 @@ export declare class Motions<I> {
     private prune;
     private evaluateSegment;
     private evaluate;
-    /** A tween's stretch, `dt` seconds after release, kept out of `evaluate` so a spring's stays small. */
-    private eased;
 }
+/**
+ * A stretch `t` voice ms into it, released at `at` from `x0` moving at `v0` toward `to` (each read
+ * from its offset), into `xo` and `vo`: the one copy of the closed forms, which `law` (a patch's
+ * `[form, settle, k1, k2, k3]`, the head of a patch's buffer or a copy of it) picks between. A tween reads `ease` and
+ * `ms`, the stretch's length, dividing in milliseconds so a boundary lands exactly; every other
+ * form ignores them.
+ */
+export declare function closed(law: Float64Array, ease: Curve | undefined, n: number, at: number, ms: number, x0: ArrayLike<number>, x: number, v0: ArrayLike<number>, v: number, to: ArrayLike<number>, g: number, t: number, xo: Float64Array, vo: Float64Array): boolean;
 /** The state behind a `'motion'` patch, for an engine that reads it directly. */
 export declare function motionOf<I>(p: object): Motions<I> | undefined;
 interface Common<I, V extends Value> {
@@ -217,8 +302,8 @@ export declare function tween<I, O, V extends Value = number>(writes: keyof O, o
     from: PerSubject<I, V>;
     /** Where each subject ends. */
     to: PerSubject<I, V>;
-    /** How long a stretch takes, ms. */
-    ms: number;
+    /** How long a stretch takes, ms: asked per subject each time one of its stretches starts. */
+    ms: PerSubject<I, number>;
     /** The curve from `from` to `to`. Default `'ease'`, as CSS's. */
     ease?: Easing;
 }): Omit<Moving<I, O, V>, 'push'> & {