@msb235/blits 0.4.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,10 +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;
-export declare const noRevive: () => void;
-export declare const noTouch: () => void;
+/**
+ * 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.
@@ -57,17 +70,22 @@ 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
@@ -82,45 +100,67 @@ interface Shape<I> {
 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.
      */
-    frame: (subject: I) => number;
+    owner: MotionOwner | null;
+    ownerId: number;
+    /** Whether the channel it was cued on holds a number; undefined until it is cued. */
+    private holdsNumber;
+    private channel;
     /**
-     * Brings a subject its voice faded out back to it, so a change is not made for nothing. Set by
-     * the mix that cues the patch, and put back when its voice retires.
+     * 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.
      */
-    revive: (subject: I) => void;
+    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;
     /**
-     * Called with a subject's number whenever its 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, put back when its voice retires.
+     * 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.
      */
-    touched: (s: number) => void;
+    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
@@ -137,6 +177,11 @@ 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.
@@ -169,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. */