@msb235/blits 0.4.0 → 0.5.0

package/dist/mixer.d.ts

@@ -1,212 +1,260 @@
-import { type Curve } from './easing.js';
-import { type Motions } from './motion.js';
-import { type Built, intosOf, type Scratch } from './patch.js';
+import { blended, laneRead, shareKept } from './blend.js';
+import type { Book } from './book.js';
+import { aims, chain, linkable } from './chain.js';
+import { type LerpInto } from './channels.js';
+import type { Due } from './due.js';
+import { parting } from './fade.js';
+import { apply, baseFor, clamp, fold, folded, foldLoci, foldWith, influence, isRest, type Key, keyed, linked, owedBy, passes, read, slopeFor, tick } from './fold.js';
+import type { HandleHost } from './handle.js';
+import { held, shownOf, sinceOf, unreachedOf } from './held.js';
+import { Lanes } from './lanes.js';
+import { foldLocus, type LocusScratch } from './locus.js';
+import type { MotionOwner, Motions } from './motion.js';
+import { Pace } from './pace.js';
+import { keep } from './pull.js';
+import { Steps } from './relink.js';
 import { Store } from './store.js';
-import type { Channel, Engine, FadeSpec, Kit, Mix, MixOptions, Patch, Setting, VoiceSpec } from './types.js';
-/** 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. */
-    reaches: boolean;
-    /** The voice's `stagger` answer in voice ms, fixed on first sight. */
-    delay: number;
-    /** The mix timestamp this subject's delay ran out at, which its step grid counts from. */
-    since: number;
-    /** The mix timestamp its fade in counts from: `since`, or earlier for a voice holding before. */
-    shown: number;
-    /** The weight this voice gave this subject the last frame it was probed, 0 where it gave none. */
-    weight: number;
-    /** Left at rest during a handover, so it stops contributing. */
-    rested: boolean;
-    /** Per written channel, whether a rest-less influence is on: 0 unknown, 1 on, 2 off. */
-    bands: Uint8Array;
-    state: S;
-    /** The `now` this subject last caught up to, for this voice. */
-    stepped: number;
-    /** Under `stepMs`, how many intervals have run since `since`; `stepped` is where that lands. */
-    ticks: number;
-    /** The `now` this subject was last probed at, so twelve probes in a frame step once. */
-    probed: number;
-    /** The last delta computed this frame, handed back to a repeat probe unchanged. */
-    delta: Record<string, unknown> | null;
-    /** The phase `delta` was read at, to read it again once its voice's scratch has moved on. */
-    phase: number;
-    /** The voice's `seeks` when `delta` was read, so a seek later in the frame reads it again. */
-    seeks: number;
-    /** 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. */
-    slope?: Record<string, unknown>;
-    /** What each stateful signal on this voice keeps for this subject, by the signal. */
-    kept: Map<object, unknown>;
-    keep: Setting['keep'];
-    /** Under `history`, copies of this record by the mix time they were taken, oldest first. */
-    snaps?: {
+import type { Booker, BookOptions, Channel, Columns, Engine, Handle, Kit, Marked, Mix, MixOptions, OwnerSpec, Patch, Projection, Sent, Signal, VoiceSpec } from './types.js';
+import { type Subject, type Voice } from './voice.js';
+import { base, capped, fadeOf, horizonFor, ownedBy, ownerBase, prime, weigh, weighOwned } from './weigh.js';
+export declare class Mixer<I, O> implements Mix<I, O> {
+    readonly kit: Kit<O>;
+    readonly opts: MixOptions;
+    cued: Voice<I, O>[];
+    /** Under `history`, voices that have left but that a read back may still reach. */
+    gone: Voice<I, O>[];
+    /** Set on a projection's own mixer: it sends nothing, keeps no history, and reads without committing. */
+    projecting: boolean;
+    /** Set on a projection reading back: a subject it has nothing on starts from its voice's start. */
+    backward: boolean;
+    /** True during a sync, so a control change it makes is recorded as showing in that frame. */
+    moving: boolean;
+    /**
+     * Under `history` with `inputs`, the host fields patches read, copied each frame they changed. In
+     * a projection reading back, the copy in force then.
+     */
+    hostLog: {
         at: number;
-        held: Subject<S>;
+        fields: Record<string, unknown>;
     }[];
-    /** In a projection: where this record started from, and whether nothing known could be. */
-    from?: number;
-    unknown?: boolean;
-    /** Under `history` with `inputs`, what an input weight signal read for this subject, when it changed. */
-    inputs?: {
+    /**
+     * Marks the host announced on a score: `at` in host time, so the mix's rate never moves one, and
+     * NaN until the next sync for one announced as now before any sync; `made` is the mix time it was
+     * announced, for a read back to know what was known.
+     */
+    announced: {
+        name: string;
+        score: string | undefined;
+        tags: readonly string[];
         at: number;
-        value: number;
+        made: number;
+        order: number;
     }[];
-    /** In a projection reading back: that record, to read in place of the signal. */
-    replay?: {
+    hostThen: {
+        fields: Record<string, unknown>;
+    } | undefined;
+    /** Each subject's last two poses and when they were probed, for `from: 'current'`. */
+    pose: Store<I, {
+        pose: O;
         at: number;
-        value: number;
-    }[];
-    /** The voice this is the record of; null on a subject's stub. */
-    voice: object | null;
-    /** The next voice's record for this subject, in voice order, among those that reach it. */
-    next: Subject<unknown> | null;
+        prev: O | undefined;
+        prevAt: number;
+    }>;
+    nextId: number;
     /**
-     * On the first record, which the mix keeps per subject so a probe makes one lookup: the `version`
-     * the chain was linked at, and per locus and channel whether a rest-less influence is on.
+     * The mix clock: host time at the mix's rate. Host time is the host's timestamp less every gap
+     * `rebase` has taken out, `u` at the last sync.
      */
-    version: number;
-    loci: Map<string, boolean> | null;
-    /** On the first record: the number lanes index this subject by, -1 without one. */
-    slot: number;
-}
-/** What sets a voice's clock: its rate, and where it was last anchored. */
-interface Clock {
-    anchorNow: number;
-    anchorElapsed: number;
-    rate: number;
-    ramp: {
-        from: number;
-        to: number;
-        over: number;
-    } | null;
-}
-/** A voice's clock, weight and fade from one mix time on, kept under `history`. */
-interface Controls extends Clock {
-    at: number;
-    weight: number;
-    out: Ramp | null;
-    /** Where its anchors had placed it then: start, and the start of an anchored fade out. */
-    start: number;
-    outAt: number;
-    /** Made by a sync, so it shows in that frame; a host's change between frames shows from the next. */
-    sync: boolean;
-}
-interface Ramp {
-    from: number;
-    at: number;
-    over: number;
-    rest: boolean;
-    deadline?: number;
-}
-export declare class Voice<I, O> {
-    readonly id: number;
-    readonly spec: VoiceSpec<I, O>;
-    readonly patch: Patch<I, O, unknown>;
-    readonly fade: FadeSpec;
-    start: number;
-    state: 'pending' | 'live' | 'held' | 'fading' | 'done';
-    rate: number;
-    weight: number;
+    now: number;
+    u: number;
+    /** This mix's frame among every mix's: moved by a sync, and by a control change or drop within one. */
+    frame: number;
+    offset: number;
+    /** The mix's own rate; null while it has never been set, when mix time is host time. */
+    pace: Pace | null;
+    /** Pending voices whose start the host gave, by its host time, kept where the rate puts it. */
+    pins: Map<Voice<I, O>, number> | null;
+    last: number;
+    rebasing: boolean;
+    wantsPose: boolean;
+    /** The pose `pull` folds a subject into where it cannot read straight from the lanes. */
+    scratch: O | undefined;
+    /** The last array `pull` read, by position, with each subject's chain head, to skip the lookup. */
+    /** Live voices by the earliest mix time `moveTo` would change each, a binary heap. */
+    due: Due<I, O>[];
+    /** Voices retired since `moveTo` last pruned them, in the order they retired. */
+    retired: Voice<I, O>[];
+    /** Visit every voice each sync, as before the due queue; for tests that compare the two. */
+    walkAll: boolean;
+    pulled: I[];
+    pulledHeads: (Subject<unknown> | undefined)[];
+    /** Each remembered head's lane slot, and the `version` and `relinks` they were all current at. */
+    pulledSlots: Int32Array<ArrayBuffer>;
+    pulledVersion: number;
+    pulledRelinks: number;
+    /** Counts chains made stale one subject at a time, which `version` does not. */
+    relinks: number;
+    /** Read once a sync, so a `reduce` function is not called per voice per subject. */
+    reducedNow: boolean;
+    /** Something was changed since the last sync, so the next frame may differ from this one. */
+    stirred: boolean;
+    /** Counts the changes `stir` records, which a frame's record of a probe is current only before. */
+    stirs: number;
+    /** Records a change to the mix's voices or controls. */
+    stir(): void;
     /**
-     * elapsed = anchorElapsed + the rate integrated from anchorNow, rebased on a rate change or a seek.
-     * Without a ramp the rate is constant; with one it moves linearly from `from` to `to` over `over`
-     * mix ms starting at the anchor, and holds `to` after.
+     * Per subject, the first record of the chain through every live voice that reaches it, or a stub
+     * where none does. Relinked when `version` moves, which is whenever the list or a voice's pending
+     * state changes.
      */
-    anchorNow: number;
-    anchorElapsed: number;
-    ramp: {
-        from: number;
-        to: number;
-        over: number;
-    } | null;
-    out: Ramp | null;
-    readonly subjects: Store<I, Subject<unknown>>;
-    /** The subjects its spec names, or null where it names none. */
-    readonly named: ReadonlySet<I> | null;
-    /** Kit slot of each channel the patch writes, in `writes` order. */
-    readonly slots: number[];
-    /** The stops built ahead of time, for a `keys` patch. */
-    readonly built: Built | null;
-    /** The kit's `lerp` for each channel the patch writes, which keyed stops interpolate through. */
-    readonly lerps: Channel<unknown>['lerp'][];
-    /** Per keyed channel, the in-place form of the lerp its stops take, where it has one. */
-    readonly intos: ReturnType<typeof intosOf> | undefined;
+    readonly chains: Store<I, Subject<unknown>>;
+    version: number;
+    readonly steps: Steps<Voice<I, O>>;
+    /** Per subject, the voices whose `subjects` name it, in voice order. */
+    named: Store<I, Voice<I, O>[]>;
+    /** Voices a subject has been faded out of, which `drop` looks in besides those that reach it. */
+    readonly parters: Set<Voice<I, O>>;
     /**
-     * The arrays keyed reads interpolate into: one set for the voice, not one per subject, since 10k
-     * subjects' worth of long-lived arrays costs more in cache misses than allocating them did.
+     * Motion patches that may hold state for a subject no voice still reaching it plays, which `drop`
+     * frees besides those voices' own: per subject, a patch a voice naming it left while another
+     * voice plays on, or that the host retargeted it on; and any patch a voice over every subject
+     * left while another plays on. How many live voices play each motion patch says which.
      */
-    scratch: Scratch;
-    /** The record whose delta holds `scratch`'s arrays; any other's must be read again to be handed out. */
-    holder: Subject<unknown> | null;
-    /** Whether its channels run as lanes this frame, so the general fold passes it by. */
-    laned: boolean;
-    /** How many times it has been sought, so a delta read before a seek is not handed out after it. */
-    seeks: number;
-    /** Whether its patch has kept state on a record through `setting.keep`, which makes it stateful. */
-    keeping: boolean;
-    /** For a motion patch, the hook it was given to ask the mix for its subjects' voice time. */
-    frame: ((subject: I) => number) | null;
-    /** For a motion patch, the hook it was given to bring a subject faded out of this voice back. */
-    revive: ((subject: I) => void) | null;
-    /** Subjects fading out of this voice alone, by the ramp each started; null while none are. */
-    parts: Map<I, {
-        at: number;
-        over: number;
-    }> | null;
-    /** Subjects faded out of this voice, by the mix time each left at; null while none have. */
-    parted: Map<I, number> | null;
-    readonly ease: Curve | undefined;
-    /** How many passes its `loop` plays, worked out once. */
-    readonly passes: number;
-    /** Voice ms its passes last, Infinity for an aperiodic patch or a loop for good. */
-    readonly span: number;
-    /** The state behind a motion patch, undefined for any other. */
-    readonly motion: Motions<I> | undefined;
-    /** Its `hold`, for a patch it applies to: motion holds its target already. */
-    readonly holdsBefore: boolean;
-    readonly holdsAfter: boolean;
-    /** The mix time it first showed: when it was cued, or the first sync after. */
-    opened: number;
-    /** Which of its entries in the mix's due queue is current; older ones are skipped when popped. */
-    dueToken: number;
-    /** Records made while it was pending, whose `since` its start may since have moved. */
-    early: Subject<unknown>[] | null;
-    /** Reused for every call this voice makes, so it is valid only during the call. */
-    readonly setting: Setting<unknown>;
-    /** Every subject this voice has been asked about, so a handover knows when it is finished. */
-    seen: number;
-    /** The longest stagger of any subject seen, so a finite loop waits for the last of them. */
-    latest: number;
-    restedCount: number;
-    /** The mix time it was cued at; -Infinity before the first sync. */
-    cuedAt: number;
-    /** The mix time it left at. */
-    doneAt: number;
-    /** Under `history`, its controls after each change, oldest first. */
-    log: Controls[] | null;
-    /** Where an anchored `out` or `end` puts its fade's start, mix time; Infinity until known. */
-    outAt: number;
-    /** Whether its start is still to be fixed by an anchor, so it waits pending. */
-    placing: boolean;
-    resolve: () => void;
-    readonly done: Promise<void>;
-    play: (played: boolean) => void;
-    readonly played: Promise<boolean>;
-    constructor(id: number, spec: VoiceSpec<I, O>, patch: Patch<I, O, unknown>, fade: FadeSpec, now: number, start: number, slotOf: Map<string, number>, channels: readonly Channel<unknown>[], host: unknown, send: (event: unknown) => void);
-    elapsedAt(now: number): number;
-    /** The mix time its clock reads `elapsed`, inverting `elapsedAt`; Infinity where it never will. */
-    timeAt(elapsed: number): number;
-    /** Records this voice's controls as they stand, from mix time `at`. */
-    note(at: number, sync?: boolean): void;
+    readonly strays: Store<I, Motions<I>[]>;
+    readonly strayAll: Set<Motions<I>>;
+    readonly playing: Map<Motions<I>, number>;
+    /** How many voices in the list carry `subjects`. */
+    naming: number;
+    /** The voices in the list that name no subjects, in voice order. */
+    general: Voice<I, O>[];
+    /** How many voices in the list carry a locus; with none, a fold allocates nothing. */
+    loci: number;
+    /** What every motion patch it plays asks for its voice's time, holding this mix weakly. */
+    owner: MotionOwner | null;
+    /** How many voices in the list are anchored, so a sync with none skips placing them. */
+    anchored: number;
+    /** Events sent since the last drain, and who is being probed, so `send` knows whose they are. */
+    sent: Sent<I, unknown>[];
+    sending: {
+        voice: Voice<I, O> | null;
+        subject: I;
+    };
+    readonly send: (event: unknown) => void;
+    /** The weight `influence` found besides the delta, read by the caller at once. */
+    w: number;
+    readonly names: Key<O>[];
+    readonly channels: Channel<unknown>[];
+    /** Slots of the channels that declare bounds, clamped after every fold. */
+    readonly bounded: number[];
+    /** By slot, a stock array channel's in-place `lerp`. */
+    readonly lerpsInto: (LerpInto | undefined)[];
+    /** What a fold with a locus in play gathers into, one per depth of folds under way. */
+    readonly locusScratch: LocusScratch<I, O>[];
+    locusDepth: number;
+    readonly slotOf: Map<string, number>;
+    readonly lanes: Lanes<I, O> | null;
+    handles: HandleHost<I, O> | null;
+    /** What `book` made, still booking; null while there is none. */
+    bookers: Book<I, O>[] | null;
+    /** Every owner still in the mix, null until one is cued. */
+    owners: Voice<I, O>[] | null;
+    constructor(kit: Kit<O>, opts: MixOptions);
+    get reduced(): boolean;
+    get band(): {
+        on: number;
+        off: number;
+    };
+    cue(spec: VoiceSpec<I, O>): Handle<I>;
+    blend(patches: readonly Patch<I, O, unknown>[], by: Signal<I>, spec?: Omit<VoiceSpec<I, O>, 'patch' | 'weight' | 'locus'>): Handle<I>[];
+    owns(spec: OwnerSpec<I>): Handle<I>;
+    sync(timestamp: number): void;
+    book(opts: BookOptions): Booker;
+    probe(subject: I, out?: O): O;
+    pull(subjects: Iterable<I>, into: Columns<O>): void;
+    project(timestamp: number): Projection<I, O>;
+    announce(name: string, opts?: {
+        at?: number;
+        score?: string;
+        tags?: readonly string[];
+    }): void;
+    marks(from: number, to: number): Marked[];
+    atRest(subject: I): boolean;
+    rests(pose: O): boolean;
+    rebase(): void;
+    voices(tag?: string): Handle<I>[];
+    get live(): boolean;
+    get inert(): boolean;
+    get rate(): number;
+    set rate(r: number);
+    ramp(rate: number, over: number): void;
+    /** Whether a voice will change no pose from `now` on, short of a change made to it. */
+    still(voice: Voice<I, O>, now: number): boolean;
+    mute(opts?: {
+        over?: number;
+    }): void;
+    drop(subject: I): void;
+    drain<E = unknown>(tag?: string): Sent<I, E>[];
+    /** Voices whose stop 0 is mid-computation, so a fold for one cannot re-enter itself. */
+    readonly folding: Set<number>;
+    linkedLaned: boolean;
     /**
-     * A copy for a projection: its own setting, which sends nothing, and its own per-subject records,
-     * filled from `fill`. With `controls` it takes those, as the voice stood at an earlier time.
+     * Per subject, twice `restsKey` at its last probe plus 1 if the pose rested; null until `atRest`
+     * is first asked, when probes start writing it.
      */
-    copy(fill: (subject: I) => Subject<unknown> | undefined, controls?: Controls): Voice<I, O>;
-    rateAt(now: number): number;
-    /** Moves the anchor to `now`, carrying what is left of a ramp. */
-    rebase(now: number): void;
+    restStamps: Store<I, number> | null;
+    /** What a probe's record of rest is good for: moved by a new frame, version or relink. */
+    private restsEpoch;
+    private restsFrame;
+    private restsVersion;
+    private restsRelinks;
+    private restsStirs;
+    /** The pose `atRest` folds into where no probe this frame answers. */
+    private restScratch;
+    private restsLaned;
+    private restsKey;
+}
+declare const methods: {
+    fold: typeof fold;
+    folded: typeof folded;
+    linked: typeof linked;
+    foldWith: typeof foldWith;
+    owedBy: typeof owedBy;
+    foldLoci: typeof foldLoci;
+    read: typeof read;
+    influence: typeof influence;
+    keyed: typeof keyed;
+    tick: typeof tick;
+    apply: typeof apply;
+    clamp: typeof clamp;
+    passes: typeof passes;
+    isRest: typeof isRest;
+    baseFor: typeof baseFor;
+    slopeFor: typeof slopeFor;
+    prime: typeof prime;
+    capped: typeof capped;
+    horizonFor: typeof horizonFor;
+    weigh: typeof weigh;
+    weighOwned: typeof weighOwned;
+    base: typeof base;
+    envelope: typeof fadeOf;
+    ownedBy: typeof ownedBy;
+    ownerBase: typeof ownerBase;
+    blended: typeof blended;
+    laneRead: typeof laneRead;
+    shareKept: typeof shareKept;
+    parting: typeof parting;
+    chain: typeof chain;
+    linkable: typeof linkable;
+    aims: typeof aims;
+    held: typeof held;
+    unreachedOf: typeof unreachedOf;
+    sinceOf: typeof sinceOf;
+    shownOf: typeof shownOf;
+    keep: typeof keep;
+    foldLocus: typeof foldLocus;
+};
+type Methods = typeof methods;
+export interface Mixer<I, O> extends Methods {
 }
 /**
  * The one that ships: every form on the CPU, probed per subject on demand.
@@ -219,5 +267,5 @@ export declare const mixer: Engine;
  *
  * @category mix
  */
-export declare function mix<I, O>(kit: Kit<O>, opts?: MixOptions): Mix<I, O>;
+export declare function mix<I, O, H = unknown>(kit: Kit<O>, opts?: MixOptions<H>): Mix<I, O, H>;
 export {};