@msb235/blits 0.14.0 → 0.15.0

package/dist/fit.d.ts

@@ -1,18 +1,18 @@
 /**
- * How hard a claim on time holds when it meets another: the weaker gives way.
+ * How hard a claim on time holds when it meets another. The weaker gives way.
  *
  * @category score
  */
 export type Strength = 'weak' | 'strong' | 'required';
 /**
- * How a span lays its children out: each after the one before has ended, partway through it, or
- * all at once.
+ * How a span lays its children out. Each after the one before has ended, partway through it, or all
+ * at once.
  *
  * @category score
  */
 export type Order = 'queue' | 'stagger' | 'together';
 /**
- * One child of a span as a fit sees it: what is left of it, and the ways it may give way.
+ * One child of a span as a fit sees it. What is left of it, and the ways it may give way.
  *
  * @category score
  */
@@ -25,13 +25,16 @@ export interface Claim {
     faster: number;
     /** How many times slower it may play; 1 for no slower. */
     slower: number;
-    /** Whether it may run alongside the one before it where the span's order would not have it. */
+    /**
+     * Whether it may run alongside the one before it. It may where the span's order would not have
+     * it.
+     */
     overlap: boolean;
     /** Whether it may jump to its end instead of playing. */
     ballast: boolean;
     priority: Strength;
     /**
-     * Span ms from now before which it may not start, from its `earliest`; absent for none. Below 0
+     * Span ms from now before which it may not start. From its `earliest`; absent for none. Below 0
      * where it has passed, which places the child there.
      */
     floor?: number;
@@ -52,9 +55,9 @@ export interface SpanClaim {
     share: number;
 }
 /**
- * What a fit decides, per child in the order given: a rate over its own, and whether it is
- * skipped. `share` is how far through the one before a child that may overlap starts, and `allow`
- * the span ms the span may run past its budget.
+ * What a fit decides for each child. A rate over its own, and whether it is skipped, per child in
+ * the order given. `share` is how far through the one before a child that may overlap starts, and
+ * `allow` the span ms the span may run past its budget.
  *
  * @category score
  */
@@ -65,7 +68,8 @@ export interface FitPlan {
     allow: number;
 }
 /**
- * A strategy for fitting a span's children into its budget: from the plan so far to a new one.
+ * A strategy for fitting a span's children into its budget. It goes from the plan so far to a new
+ * one.
  *
  * @category score
  */
@@ -73,23 +77,31 @@ export type Fit = (span: SpanClaim, kids: readonly Claim[], plan: FitPlan) => Fi
 /** How far through the one before a child starts under each order, before any fit. */
 export declare function shareOf(order: Order, stagger: number): number;
 /**
- * The plan before any fit: every child at its own rate, played, in the span's order.
+ * The plan before any fit. Every child at its own rate, played, in the span's order.
  *
  * @category score
  */
 export declare function plain(span: SpanClaim, kids: readonly Claim[]): FitPlan;
 /**
- * Where a plan puts each child, span ms from now, and how long they take together. A playing child
- * is where it is, at 0; each pending one starts its share through the one before it, or at its
- * floor where that is later. A floor already past places a child before now, so it starts partway
- * through; one without a floor starts no sooner than now.
+ * Where `layout` puts a span's children.
  *
  * @category score
  */
-export declare function layout(span: SpanClaim, kids: readonly Claim[], plan: FitPlan): {
+export interface Layout {
+    /** Where each child starts, span ms from now, in the order given. */
     at: number[];
+    /** How long they take together, span ms from now. */
     length: number;
-};
+}
+/**
+ * Where a plan puts each child, and how long they take together. Times are span ms from now. A
+ * playing child is where it is, at 0; each pending one starts its share through the one before it,
+ * or at its floor where that is later. A floor already past places a child before now, so it starts
+ * partway through; one without a floor starts no sooner than now.
+ *
+ * @category score
+ */
+export declare function layout(span: SpanClaim, kids: readonly Claim[], plan: FitPlan): Layout;
 /**
  * Moves every child's rate by one factor toward the budget, before the span's fit: faster where
  * they run past it, each no faster than its `faster` allows, and slower where they leave room in
@@ -97,8 +109,8 @@ export declare function layout(span: SpanClaim, kids: readonly Claim[], plan: Fi
  */
 export declare function rescale(span: SpanClaim, kids: readonly Claim[], plan: FitPlan): FitPlan;
 /**
- * Starts children that may overlap sooner after the one before, toward all at once, until they
- * fit.
+ * Starts children that may overlap sooner, until they fit. Each moves closer after the one before,
+ * toward all at once.
  *
  * @category score
  */
@@ -116,13 +128,20 @@ export declare function shed(): Fit;
  */
 export declare function conclude(): Fit;
 /**
- * Lets the span run past its budget: up to `cap` times it, or without limit.
+ * What `overrun` and `lax` take.
  *
  * @category score
  */
-export declare function overrun(opts?: {
+export interface OverrunOptions {
+    /** The most the span may run, as a multiple of its budget. Default: no limit. */
     cap?: number;
-}): Fit;
+}
+/**
+ * Lets the span run past its budget. Up to `cap` times it, or without limit.
+ *
+ * @category score
+ */
+export declare function overrun(opts?: OverrunOptions): Fit;
 /**
  * Tries each fit in turn, handing the plan on, and stops once the children fit.
  *
@@ -130,13 +149,12 @@ export declare function overrun(opts?: {
  */
 export declare function pipe(...fits_: readonly Fit[]): Fit;
 /**
- * Every way of giving way after the span's retiming, overrunning only once the rest are spent.
+ * Every way of giving way, overrunning only once the rest are spent. It applies after the span's
+ * retiming.
  *
  * @category score
  */
-export declare function lax(opts?: {
-    cap?: number;
-}): Fit;
+export declare function lax(opts?: OverrunOptions): Fit;
 /** The fit a span takes without one of its own. */
 export declare const defaultFit: Fit;
 /**

package/dist/fit.js

@@ -3,7 +3,7 @@ export function shareOf(order, stagger) {
     return order === 'queue' ? 1 : order === 'together' ? 0 : stagger;
 }
 /**
- * The plan before any fit: every child at its own rate, played, in the span's order.
+ * The plan before any fit. Every child at its own rate, played, in the span's order.
  *
  * @category score
  */
@@ -16,10 +16,10 @@ export function plain(span, kids) {
     };
 }
 /**
- * Where a plan puts each child, span ms from now, and how long they take together. A playing child
- * is where it is, at 0; each pending one starts its share through the one before it, or at its
- * floor where that is later. A floor already past places a child before now, so it starts partway
- * through; one without a floor starts no sooner than now.
+ * Where a plan puts each child, and how long they take together. Times are span ms from now. A
+ * playing child is where it is, at 0; each pending one starts its share through the one before it,
+ * or at its floor where that is later. A floor already past places a child before now, so it starts
+ * partway through; one without a floor starts no sooner than now.
  *
  * @category score
  */
@@ -87,8 +87,8 @@ export function rescale(span, kids, plan) {
     return fits(span, kids, at(f)) ? at(f) : at(Math.max(1, f - 1e-9));
 }
 /**
- * Starts children that may overlap sooner after the one before, toward all at once, until they
- * fit.
+ * Starts children that may overlap sooner, until they fit. Each moves closer after the one before,
+ * toward all at once.
  *
  * @category score
  */
@@ -130,7 +130,7 @@ export function conclude() {
     return (_span, kids, plan) => ({ ...plan, skip: kids.map(() => true) });
 }
 /**
- * Lets the span run past its budget: up to `cap` times it, or without limit.
+ * Lets the span run past its budget. Up to `cap` times it, or without limit.
  *
  * @category score
  */
@@ -158,7 +158,8 @@ export function pipe(...fits_) {
     };
 }
 /**
- * Every way of giving way after the span's retiming, overrunning only once the rest are spent.
+ * Every way of giving way, overrunning only once the rest are spent. It applies after the span's
+ * retiming.
  *
  * @category score
  */

package/dist/fold.d.ts

@@ -1,6 +1,7 @@
 import type { Mixer } from './mixer.js';
+import type { Subject } from './subject.js';
 import type { Channel } from './types.js';
-import { type Subject, type Voice } from './voice.js';
+import type { Voice } from './voice.js';
 export type Key<O> = keyof O & string;
 export declare function near(a: unknown, b: unknown): boolean;
 /**
@@ -10,31 +11,6 @@ export declare function near(a: unknown, b: unknown): boolean;
  */
 export declare function merged(channel: Channel<unknown>, acc: unknown, b: unknown): unknown;
 export type Values = Record<string, unknown>;
-/**
- * One live voice's delta for one subject this frame, through its record for the subject, or null
- * when it does not reach. Its weight is left in `w`.
- */
-export declare function contribution<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, now: number, held: Subject<unknown>): Record<string, unknown> | null;
-/** Reads a keys voice's stops at `held.phase` into the subject's delta, through the voice's scratch. */
-export declare function keyed<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, held: Subject<unknown>): Record<string, unknown>;
-/**
- * Runs `step` once per whole interval between where this subject last stopped and now, on a grid
- * counted from when its delay ran out, and leaves the remainder for the next sample. Counting
- * rather than adding keeps the grid where it is however many samples it is reached through.
- */
-export declare function tick<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, held: Subject<unknown>, tick: number, to: number): void;
-/**
- * Stop 0 for a retargeting voice: the subject's pose in the frame before this voice contributes.
- * With no such frame on record — a voice cued before the subject was ever probed, or a host that
- * samples into its own object — it is this frame's pose with every other voice folded in.
- */
-export declare function baseFor<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I): Record<string, unknown>;
-/**
- * How fast each numeric channel this voice writes was moving, from the subject's last two probed
- * poses, in units per ms. Undefined with fewer than two on record, which starts the voice at rest.
- */
-export declare function slopeFor<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I): Record<string, unknown> | undefined;
-export declare function isRest<I, O>(this: Mixer<I, O>, delta: Record<string, unknown>): boolean;
 /**
  * A record's band state once its voice is skipped at weight 0: off, as `passes` would have said, so
  * a weight that comes back inside the band does not find it still on.
@@ -48,11 +24,6 @@ export declare function apply<I, O>(this: Mixer<I, O>, pose: Record<string, unkn
 export declare function clamp<I, O>(this: Mixer<I, O>, pose: Record<string, unknown>): Record<string, unknown>;
 /** A folded value held to its channel's bounds: a number clamped, an array clamped in place. */
 export declare function bound(channel: Channel<unknown>, v: unknown): unknown;
-/**
- * Whether a fold's next voice is its chain's next record, `held`, and not the next voice sharing
- * one record, `sharers[q]`: the two lists are each in voice order, and a fold takes them as one.
- */
-export declare function chainFirst<I, O>(held: Subject<unknown> | null, sharers: readonly Voice<I, O>[], q: number): boolean;
 /**
  * After a fold read a sharing voice for the subject numbered `slot`: keeps the weight it gave and
  * what the read left on its record, and gives the fold's place in `sharers`, which moves back where
@@ -69,9 +40,9 @@ export declare function linked<I, O>(this: Mixer<I, O>, subject: I): Subject<unk
 /** The fold after a subject's chain is linked and its lanes asked whether it reads from them. */
 export declare function foldWith<I, O>(this: Mixer<I, O>, subject: I, out: O, head: Subject<unknown> | null, laned: boolean, dry: boolean, except?: number): O;
 /**
- * `foldWith`'s voices in a mix with a locus or a voice sharing one record in it. The chain is taken
+ * `foldWith`'s voices in a mix with a role or a voice sharing one record in it. The chain is taken
  * again where a voice stopped sharing since it was linked, as a patch call in this probe's fill can
- * make one do. With no locus, the chain's records fold in voice order, and each voice sharing one
+ * make one do. With no role, the chain's records fold in voice order, and each voice sharing one
  * record, which is in no chain, before the first chain record that comes after it.
  */
 export declare function foldDetour<I, O>(this: Mixer<I, O>, subject: I, pose: Record<string, unknown>, linkedHead: Subject<unknown>, laned: boolean, dry: boolean, except: number | undefined, owed: number): O;
@@ -82,7 +53,3 @@ export declare function foldDetour<I, O>(this: Mixer<I, O>, subject: I, pose: Re
 export declare function foldSharers<I, O>(this: Mixer<I, O>, pose: Record<string, unknown>, subject: I, head: Subject<unknown>, q: number, before: number, laned: boolean, dry: boolean, except: number | undefined, owed: number): number;
 /** Whether the subject numbered `owed` reads laned `voice` from the general path this fill. */
 export declare function owedBy<I, O>(this: Mixer<I, O>, owed: number, voice: Voice<I, O>): boolean;
-/** `foldWith`'s voices with a locus in play: each locus folds at its first member's place. */
-export declare function foldLoci<I, O>(this: Mixer<I, O>, subject: I, pose: Record<string, unknown>, head: Subject<unknown>, laned: boolean, dry: boolean, except: number | undefined, owed: number): O;
-/** `contribution`, or for a dry fold a subject already probed this frame, without advancing it. */
-export declare function read<I, O>(this: Mixer<I, O>, voice: Voice<I, O>, subject: I, now: number, dry: boolean, held: Subject<unknown>): Record<string, unknown> | null;