@msb235/blits 0.14.0 → 0.15.0

package/dist/motion.d.ts

@@ -1,69 +1,11 @@
 import { Motions } from './motions.js';
-import type { Easing, Patch } from './types.js';
-/**
- * A number, or one number per axis.
- *
- * @category patch
- */
-export type Value = number | readonly number[];
-/**
- * One value for every subject, or one per subject.
- *
- * @category patch
- */
-export type PerSubject<I, V> = V | ((subject: I) => V);
-/**
- * Where a subject is and how fast it is moving, at one moment of voice time.
- *
- * @category patch
- */
-export interface Motion<V extends Value = number> {
-    value: V;
-    /** Units per second. */
-    velocity: V;
-}
-/**
- * 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.
- *
- * @category patch
- */
-export type Moving<I, O, V extends Value> = Patch<I, O, void> & {
-    /**
-     * Where `subject` is and how fast it moves at voice time `at`, default the mix's latest frame,
-     * counting every change due by then. With no time given, undefined until a frame of its voice
-     * has met the subject, while the subject is still inside its stagger, and once that voice is gone.
-     * At any time, undefined for a subject the patch has never met or changed, or that the mix
-     * dropped.
-     */
-    read(subject: I, at?: number): Motion<V> | undefined;
-    /**
-     * Sets `subject` moving at `velocity`, units per second, from voice time `at`, default the mix's
-     * latest frame; for a subject no frame of its voice has met yet, or still inside its stagger, its
-     * first read, after any change with a time due by then. A subject faded out of the voice comes
-     * back at the latest frame too, however long it is before it is next read.
-     */
-    push(subject: I, velocity: V, at?: number): void;
-    /**
-     * Puts `subject` at `value` from voice time `at`, keeping its velocity, with `at` defaulting as
-     * `push`'s does: a spring or tween heads for its target from there, a glide coasts on from there.
-     */
-    set(subject: I, value: V, at?: number): void;
-};
+import type { Glide, GlideOptions, Spring, SpringOptions, Tween, TweenOptions, Value } from './types/motion.js';
+export type { Glide, GlideOptions, Motion, MotionOptions, Moving, PerSubject, Spring, SpringOptions, Tween, TweenOptions, Value, } from './types/motion.js';
 /**
  * The state behind a `'motion'` patch, for an engine that reads it directly; a patch another copy
  * of the same release made counts.
  */
 export declare function motionOf<I>(p: object): Motions<I> | undefined;
-interface Common<I, V extends Value> {
-    /** Units per second each subject starts moving at. Default 0. */
-    velocity?: PerSubject<I, V>;
-    /**
-     * Within this distance of where it heads, and this slow, a subject lands there exactly, so a mix
-     * can see it at rest. Default 1e-4; 0 keeps the curve exact.
-     */
-    settle?: number;
-}
 /**
  * A damped spring toward a target, solved in closed form. `to(subject, target)` retargets one
  * subject mid-flight, and the new stretch starts from where it is and how fast it moves, so there is
@@ -72,28 +14,12 @@ interface Common<I, V extends Value> {
  *
  * @category patch
  */
-export declare function spring<I, O, V extends Value = number>(writes: keyof O, opts: Common<I, V> & {
-    to: PerSubject<I, V>;
-    /** Where each subject starts. Default: `to`, at rest. */
-    from?: PerSubject<I, V>;
-    /** Per second squared. Default 170. */
-    stiffness?: number;
-    /** Per second. Default 26, just short of critical at the default stiffness. */
-    damping?: number;
-    mass?: number;
-}): Moving<I, O, V> & {
-    /**
-     * Heads `subject` for `target` from voice time `at`, keeping its velocity: by default the mix's
-     * latest frame, or for a subject no frame of its voice has met yet, or still inside its stagger,
-     * its first read, after any change with a time due by then. A subject faded out of the voice
-     * comes back at the latest frame too, however long it is before it is next read.
-     */
-    to(subject: I, target: V, at?: number): void;
-};
+export declare function spring<I, O, V extends Value = number>(writes: keyof O, opts: SpringOptions<I, V>): Spring<I, O, V>;
 /**
- * Coasting under friction, a fling: a subject keeps its velocity, which falls by a factor of e every
- * `ms`, and comes to rest `velocity · ms / 1000` past where it was released. `push` sets it moving
- * again from wherever it is. Closed form, so frame rate does not change where it stops.
+ * A patch that coasts each subject to a stop under friction, as after a fling. A subject keeps its
+ * velocity, which falls by a factor of e every `ms`, and comes to rest `velocity · ms / 1000` past
+ * where it was released. `push` sets it moving again from wherever it is. Closed form, so frame
+ * rate does not change where it stops.
  *
  * With `bounds`, a coast that would stop past an edge springs back to it from where it crosses, at
  * the speed it crosses at, on a critically damped spring of `stiffness`; one let go past an edge
@@ -102,44 +28,14 @@ export declare function spring<I, O, V extends Value = number>(writes: keyof O,
  *
  * @category patch
  */
-export declare function glide<I, O, V extends Value = number>(writes: keyof O, opts: Common<I, V> & {
-    /** Where each subject starts. */
-    from: PerSubject<I, V>;
-    /** The friction's time constant, ms. Default 325, a touch scroll's. */
-    ms?: number;
-    /** The least and greatest value a coast comes to rest at, per axis. Default none. */
-    bounds?: PerSubject<I, readonly [min: V, max: V]>;
-    /** The spring back's, per second squared, with `bounds`. Default 170, as a spring's. */
-    stiffness?: number;
-}): Moving<I, O, V> & {
-    /** `subject`'s bounds, undefined for a glide without them. */
-    bounds(subject: I): readonly [min: V, max: V] | undefined;
-};
+export declare function glide<I, O, V extends Value = number>(writes: keyof O, opts: GlideOptions<I, V>): Glide<I, O, V>;
 /**
- * From one value to another over `ms` along an easing, solved in closed form, so frame rate does not
- * change where a subject is. `to(subject, target)` retargets one subject mid-flight: the new stretch
- * starts from where it is and takes the full `ms` again, so its velocity jumps where a spring's
- * would not. Time is the voice's, so `rate` and `seek` apply, and a voice's `loop` does not repeat
- * it. Cue each tween on one voice. Every subject moves on the same number of axes.
+ * From one value to another over `ms` along an easing. Solved in closed form, so frame rate does
+ * not change where a subject is. `to(subject, target)` retargets one subject mid-flight: the new
+ * stretch starts from where it is and takes the full `ms` again, so its velocity jumps where a
+ * spring's would not. Time is the voice's, so `rate` and `seek` apply, and a voice's `loop` does
+ * not repeat it. Cue each tween on one voice. Every subject moves on the same number of axes.
  *
  * @category patch
  */
-export declare function tween<I, O, V extends Value = number>(writes: keyof O, opts: {
-    /** Where each subject starts. */
-    from: PerSubject<I, V>;
-    /** Where each subject ends. */
-    to: PerSubject<I, V>;
-    /** 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'> & {
-    /**
-     * Heads `subject` for `target` from voice time `at`, over a full `ms` from where it is: by default
-     * the mix's latest frame, or for a subject no frame of its voice has met yet, or still inside its
-     * stagger, its first read, after any change with a time due by then. A subject faded out of the
-     * voice comes back at the latest frame too, however long it is before it is next read.
-     */
-    to(subject: I, target: V, at?: number): void;
-};
-export {};
+export declare function tween<I, O, V extends Value = number>(writes: keyof O, opts: TweenOptions<I, V>): Tween<I, O, V>;

package/dist/motion.js

@@ -1,7 +1,9 @@
 import { BOUND, COAST, CRITICAL, EASED, OVER, UNDER } from './closed.js';
 import { curve } from './easing.js';
 import { Motions } from './motions.js';
+import { reading } from './reading.js';
 import { release } from './shared.js';
+import { sampleThen } from './then.js';
 const axes = (v) => (typeof v === 'number' ? [v] : [...v]);
 /** Zero on every axis `x` has: a motion's velocity where its options give none. */
 const still = (x) => new Array(x.length).fill(0);
@@ -40,6 +42,11 @@ class MotionPatch {
     }
     at(_phase, subject, setting) {
         const state = this.motions;
+        const back = reading.back;
+        if (back !== null) {
+            const flags = sampleThen(state, subject, setting.elapsed, back);
+            return { [this.writes[0]]: state.valueOf(flags, state.xs) };
+        }
         const s = state.slot(subject);
         state.sample(s, setting.elapsed, state.xs, state.vs);
         return { [this.writes[0]]: state.value(s, state.xs) };
@@ -252,9 +259,10 @@ export function spring(writes, opts) {
     return new SpringPatch(writes, new Motions(new SpringShape(law, motion, opts)));
 }
 /**
- * Coasting under friction, a fling: a subject keeps its velocity, which falls by a factor of e every
- * `ms`, and comes to rest `velocity · ms / 1000` past where it was released. `push` sets it moving
- * again from wherever it is. Closed form, so frame rate does not change where it stops.
+ * A patch that coasts each subject to a stop under friction, as after a fling. A subject keeps its
+ * velocity, which falls by a factor of e every `ms`, and comes to rest `velocity · ms / 1000` past
+ * where it was released. `push` sets it moving again from wherever it is. Closed form, so frame
+ * rate does not change where it stops.
  *
  * With `bounds`, a coast that would stop past an edge springs back to it from where it crosses, at
  * the speed it crosses at, on a critically damped spring of `stiffness`; one let go past an edge
@@ -277,11 +285,11 @@ export function glide(writes, opts) {
     return new GlidePatch(writes, new Motions(shape), opts.bounds);
 }
 /**
- * From one value to another over `ms` along an easing, solved in closed form, so frame rate does not
- * change where a subject is. `to(subject, target)` retargets one subject mid-flight: the new stretch
- * starts from where it is and takes the full `ms` again, so its velocity jumps where a spring's
- * would not. Time is the voice's, so `rate` and `seek` apply, and a voice's `loop` does not repeat
- * it. Cue each tween on one voice. Every subject moves on the same number of axes.
+ * From one value to another over `ms` along an easing. Solved in closed form, so frame rate does
+ * not change where a subject is. `to(subject, target)` retargets one subject mid-flight: the new
+ * stretch starts from where it is and takes the full `ms` again, so its velocity jumps where a
+ * spring's would not. Time is the voice's, so `rate` and `seek` apply, and a voice's `loop` does
+ * not repeat it. Cue each tween on one voice. Every subject moves on the same number of axes.
  *
  * @category patch
  */

package/dist/motions.d.ts

@@ -1,97 +1,17 @@
+import { applied, change, commit, cut, dueTo, insert, peek, queue, rewind } from './changes.js';
 import type { Curve } from './easing.js';
+import { made, pack, prune, type Released, reclaim, release, restretch, runAt, runThen, unpack, unrelease } from './lives.js';
+import { Numbers } from './numbers.js';
+import { Store } from './store.js';
+import { type Change, type MotionOwner, type Run, type Segment, type Shape, type Watcher } from './stretch.js';
 import type { MotionSpec } from './types.js';
 /**
- * One closed-form stretch: released at `at` (voice ms) from `x0` moving at `v0`, toward `to`, over
- * `ms` for a tween (0 for any other shape).
+ * A patch's law, `[form, settle, k1, k2, k3]`: which closed form its stretches follow, its `settle`,
+ * and up to three constants that form reads. It heads the patch's `runs`, so `solve` finds them in
+ * the buffer a sample already reads rather than in an object of their own.
  */
-export interface Segment {
-    at: number;
-    ms: number;
-    x0: number[];
-    v0: number[];
-    to: number[];
-    /** The change that released it; undefined for a subject's first stretch. */
-    change?: Change;
-}
-export interface Change {
-    /**
-     * Voice ms it takes effect at; absent, until the subject's next read stamps it with that read's
-     * time, for one made while no frame had met the subject.
-     */
-    at?: number;
-    to?: number[];
-    /** Where it moves from, in place of where its stretch has it then. */
-    x?: number[];
-    v?: number[];
-    /** The mix clock when it was made, NaN where no mix was playing the patch. */
-    made?: number;
-    /** The frame it was made in, which a rewind partitions by; NaN where no mix was playing the patch. */
-    seq?: 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: its
-     * voice time now, which a change bringing it back is made at; NaN for any other subject.
-     */
-    revive(id: number, subject: unknown): number;
-    /** The mix clock at its latest frame; NaN before the first. */
-    now(): number;
-    /** The number of the frame the mix is playing. */
-    seq(): number;
-    /**
-     * The host made a change, already given its time, which a seek makes again on the patch its
-     * voice plays then: a voice a history store paged out comes back with a patch of its own.
-     */
-    changed<I>(id: number, motion: Motions<I>, subject: I, change: Change): void;
-    /** History leaving memory for a subject, which a mix with a history store pages out. */
-    page(id: number, stream: 'released' | 'stretch', subject: unknown, out: Paging[]): void;
-}
-/** A record of a motion patch's history leaving memory, at a mix time and frame. */
-export interface Paging {
-    at: number;
-    seq: number;
-    data: unknown;
-}
-/** A subject's run as plain data: its flags, its stretches oldest first, and changes still to apply. */
-export interface Run {
-    flags: number;
-    stretches: Segment[];
-    pending: Change[] | undefined;
-}
-/**
- * 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;
-}
-export interface Shape<I> {
-    from: (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; `put` for a stretch a
-     * `set` released.
-     */
-    aim: (x: number[], v: number[], was: number[] | null, subject: I, put: boolean) => 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 ms 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;
+export declare const enum Law {
+    HEAD = 5
 }
 /**
  * A motion patch's subjects: the stretch each is playing, in one flat array by a number the patch
@@ -104,16 +24,17 @@ export interface Shape<I> {
  * object of its own took a call from 130 ns to 490.
  */
 export declare class Motions<I> {
-    private readonly shape;
-    private readonly numbers;
+    readonly shape: Shape<I>;
+    readonly numbers: Numbers<I>;
     /** Numbers by subject once a second is numbered: till then the one subject is found by `numbers`. */
-    private readonly slots;
+    readonly slots: Store<I, number>;
     /** How many numbers have been given up, so a number kept elsewhere can tell it is stale. */
     freed: number;
     /** Axes per subject; -1 until the first subject sets it. */
     n: number;
     private cap;
-    private stride;
+    /** Numbers in each subject's run; a run starts at `base`. Written only here. */
+    stride: number;
     /**
      * 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.
@@ -130,10 +51,10 @@ export declare class Motions<I> {
      * 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;
+    pending: (Change[] | undefined)[] | null;
+    older: (Segment[] | undefined)[] | null;
     /** By subject number, the change that released the stretch it is playing; null until one has. */
-    private causes;
+    causes: (Change | undefined)[] | null;
     /**
      * 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.
@@ -148,43 +69,29 @@ export declare class Motions<I> {
      * where every subject's value is one kind, else on the first sample of a subject whose value is not.
      */
     cuedOn(channel: string, holdsNumber: boolean): void;
-    private frame;
+    frame(subject: I): number;
     constructor(shape: Shape<I>);
     /** The patch's number for `subject`, made with its first stretch on first ask. */
     slot(subject: I): number;
+    /** The flags of the run `fresh` last started. */
+    private freshFlags;
+    /** The stretch a subject met afresh starts with, its axes and the law set up for it, numbering no one. */
+    fresh(subject: I): Segment;
+    /** The run `fresh` starts, as plain data. */
+    freshRun(subject: I): Run;
     /** Sets the axes every subject moves on, at the first. */
-    private size;
+    size(n: number): void;
     /** Numbers `subject`, with room for its run. */
-    private take;
+    take(subject: I): number;
     /** The patch's number for `subject`, undefined where it has none. */
-    private known;
+    known(subject: I): number | undefined;
     /**
      * Subjects released at a mix time a rewind may still reach, with their run as it stood, so a
      * rewind before the release plays them on from there. Empty without history.
      */
-    private released;
-    /**
-     * Forgets a subject, so a later ask starts it afresh from `from`. Given the mix time `at` and frame
-     * `seq`, under history, its run is kept for a rewind before then, until `reach` passes it.
-     */
-    release(subject: I, at?: number, reach?: number, seq?: number): void;
-    /** Puts back each subject released after frame `seq`, as it stood when released. */
-    private unrelease;
-    /** Subject `s`'s run as it stands. */
-    private runAt;
+    released: Released<I>[];
     /** Whether the patch holds a run for `subject`. */
     holds(subject: I): boolean;
-    /** A subject's run as plain data, for a voice leaving memory; undefined where it has none. */
-    pack(subject: I): Run | undefined;
-    /** Puts a subject's run back as `pack` or a release left it, replacing any it has now. */
-    unpack(subject: I, run: Run): void;
-    /** A released run a history store gave back, for a rewind to before its release. */
-    reclaim(subject: I, at: number, seq: number, run: Run): void;
-    /**
-     * Stretches a history store gave back, each by the frame it was in force by: each life of the
-     * subject, ended by a release, takes those from its own, ahead of the earliest it still keeps.
-     */
-    restretch(subject: I, back: readonly Paging[]): 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
@@ -210,6 +117,8 @@ export declare class Motions<I> {
     scalar(s: number): boolean;
     /** The value `at` hands the mix: the first axis for a number, a fresh array otherwise. */
     value(s: number, xs: Float64Array): number | number[];
+    /** The value `at` hands the mix for a run with `flags`. */
+    valueOf(flags: number, xs: Float64Array): number | number[];
     /**
      * Position and velocity at voice time `t` into `xo` and `vo`, a tween's velocity left at 0. A live
      * read stamps every untimed change with `t` and commits every change due by then, in time order;
@@ -242,44 +151,42 @@ export declare class Motions<I> {
         v: Float64Array;
         s: number;
     } | undefined;
-    /**
-     * Queues a retarget, set or push, untimed at the latest frame, for `subject`'s next read past its time.
-     * The queue keeps the changes with a time in time order, ahead of any still waiting for one.
-     */
-    change(subject: I, c: Change): void;
-    /** Files a change with a time after every one due by then, ahead of those still waiting for one. */
-    private queue;
-    /** Every change due by `t` applied to a copy of the stretch playing then, committing nothing. */
-    private peek;
-    /** Subject `s`'s changes waiting, with those a read ahead's tape made filed among them by time. */
-    private dueTo;
-    private check;
-    private flag;
+    check(a: readonly number[] | undefined, n: number): void;
+    flag(s: number, bit: number, on: boolean): void;
     forget(s: number): void;
-    /**
-     * Takes back every change made after frame `seq`: each subject plays from its earliest stretch
-     * kept, with the changes made by then queued to be applied again.
-     */
-    rewind(seq: number): void;
-    private cut;
     /** Where subject `s`'s run starts in `runs`. */
     base(s: number): number;
     private grow;
-    private write;
+    write(s: number, seg: Segment): void;
     /** The stretch subject `s` is playing now, as an object. */
-    private latest;
+    latest(s: number): Segment;
     /** The stretch playing at voice time `t`: the latest released by then, else the first. */
-    private playing;
-    private applied;
-    private commit;
-    private insert;
-    /**
-     * The mix time and frame a stretch was in force by, which a store keys it under: when the change
-     * that ended it was made, which falls in the same life of the subject.
-     */
-    private made;
-    /** Lets go of stretches older than the one in force at `reading.horizon`. */
-    private prune;
-    private evaluateSegment;
+    playing(s: number, t: number): Segment;
+    evaluateSegment(seg: Segment, t: number, xo: Float64Array, vo: Float64Array): void;
     private evaluate;
 }
+declare const methods: {
+    release: typeof release;
+    unrelease: typeof unrelease;
+    runAt: typeof runAt;
+    pack: typeof pack;
+    unpack: typeof unpack;
+    reclaim: typeof reclaim;
+    runThen: typeof runThen;
+    restretch: typeof restretch;
+    made: typeof made;
+    prune: typeof prune;
+    change: typeof change;
+    queue: typeof queue;
+    peek: typeof peek;
+    dueTo: typeof dueTo;
+    rewind: typeof rewind;
+    cut: typeof cut;
+    applied: typeof applied;
+    commit: typeof commit;
+    insert: typeof insert;
+};
+type Methods = typeof methods;
+export interface Motions<I> extends Methods {
+}
+export {};