@msb235/blits 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,254 @@ This package follows [semver](https://semver.org). Below 1.0.0, a breaking chang
 version and everything else the patch. Each release lists its changes as **Breaking**, **Added** and
 **Fixed**, and the release workflow refuses a tag with no section here.
 
+## 0.12.0
+
+### Added
+
+- `curve(easing)` and `Curve`: the function an easing stands for, from a CSS name, a `bezier`, a
+  `steps` or a function, for a host shaping its own ramps with the curves patches use.
+- `mix.arc(spec)`: an owner holding three parts that hand over in order on its clock, `enter`,
+  `active` for the `hold` and `exit`, each a voice's spec or several layered, with a `blend`
+  crossfading across each boundary. Its marks are its own: `in` as the enter ends, `coast` and
+  `out` as the hold ends and the exit begins, `end` as the exit ends, where it leaves and `done`
+  resolves. `hold: 'open'` holds until `release()` on its handle, which a seek replays; `fade`
+  takes it out with no exit. An arc with a finite hold sits in a span. It is klieg's `fire` as a
+  blits primitive, under the same part names. The schema page's "Arcs" says what each part does.
+- A span child's `earliest` and `rank`. `earliest` is the soonest it may start, a time on the
+  span's clock or an anchor; the fit never places it sooner, and the children after it are laid
+  out from where it starts. One already past when it is cued places it there, partway through, so a
+  span made afresh after a seek plays as it did. One whose anchor has no answer yet waits, with every child
+  after it under `queue` or `stagger`, and the span fits again once the anchor answers. `rank` orders the
+  children still to start, lower first, ties as cued. Together they replace astv's own change
+  order, which sorts its changes by line and starts each no sooner than its orb lands.
+- `watched()`: every mix on the page, for a debugger, in one registry that all copies of blits
+  share. Each entry can:
+  - `watch` what the host reads each frame
+  - `read` a subject the host never probes, now or back in history, through `project`
+  - `label` a subject
+  - list its kit's `channels`, and the `name` and `tags` a voice was cued with
+  - `hold` the mix's clock to pause, step and seek it, without writing to the tape, then `free`
+    it
+  
+  A mix nobody watches runs the same code as before, and one a debugger has let go of runs as fast
+  as one it never watched. `watched().history` gives history to mixes
+  made later that name none. `MixOptions.labelOf` names subjects for it.
+
+### Fixed
+
+- Replacing a voice makes less garbage again: a one-subject tween voice retargeted as it is cued,
+  while another leaves and its subject is dropped, allocates 11.4–11.7 KB, from 13.0–13.4
+  (`bench/churnwho.mjs`, 5,000 voices, teitou, three passes a side). Frame time is unchanged.
+- A voice over every subject that plays more than 60 frames costs less a frame: it now keeps a
+  record for each subject, where it kept one for them all that every read had to point at its
+  subject and back. Three `fn` voices over 1,000 subjects (`fn`) take 0.212 ms a frame against
+  0.226, eight 0.468 against 0.526 (teitou, medians of nine alternated runs of 1,500 frames against
+  `a77c5c9`). A voice cued and gone within a few frames still shares one record, which is what it
+  was for.
+- A crowd of `fn` voices writing arrays, one voice per subject, costs about a tenth less a frame
+  where nothing else writes its channels: it runs off lanes, where its subjects are walked once
+  instead of twice. A `fn` voice writing a vec for each of 10,000 subjects (`fns`) takes 1.348 ms
+  a frame against 1.519 (msb-uai, medians of nine alternated runs of one build with lanes kept
+  for it and not). So does a single `fn` voice over many subjects writing a vec, where no other
+  voice writes it: weasel's animator written as one (`weaselfn`) takes 1.734 ms against 1.823,
+  and one writing a position from each subject's own numbers (`tweenfn`) 1.163 against 1.410.
+- A mix with lanes on whose voices all run off lanes costs a probe less bookkeeping: `tweenfn`
+  takes 1.097 ms a frame against 1.172 and `weaselfn` 1.644 against 1.723 (msb-uai, medians of
+  thirteen alternated runs of one build with the change switched on and off).
+- A voice on a lane costs a call less a subject each frame: since 0.11.0 the check for a voice
+  hiding past its end left its clock read out of line. A glow weighted by a signal over 10,000
+  subjects (`glow`) takes 1.636 ms a frame against 1.696 (teitou, medians of fifteen alternated runs
+  against `11a1471`).
+- A mix keeping history costs about a fifth less a frame and allocates a third less: the copy of a
+  record that falls out of the window is written over as the next one kept, only a motion voice
+  works out how far back a read may still reach, and a stock `sum`, `mul` or `max` channel folds a
+  voice's number without calling the channel. Three voices over 10,000 subjects with 5 s of history
+  (`kept`) take 5.33 ms a frame against 6.56 and allocate 5.7 MB against 8.5; sought back and
+  returned before every sync (`seek`), 5.90 ms against 6.76; at 1,000 subjects, 0.412 against
+  0.500 and 0.540 against 0.598 (teitou, medians of nine alternated runs of 1,500 frames against
+  `00ad148`, each in its own process).
+- A `seek` back and a return to where the mix was cost about a third of what they did: a record put
+  back takes up the state of the record the seek replaced instead of stepping again from its copy,
+  is written over that record instead of copied anew, and the copy its next probe keeps is written
+  over one the seek cut; subjects keep their numbers across the seek. Three voices over 10,000
+  subjects with 5 s of history, sought 300 ms back and returned before every sync (`seek`), take
+  9.83 ms a frame against 28.60, and allocate 8.6 MB a frame against 35.2; 1,000 subjects take 0.86
+  ms against 1.88 (msb-uai, medians of nine alternated runs against `4374f34`, each in its own
+  process). The same mix never sought (`kept`) reads 7.41 ms against 7.33 at 10,000 subjects and
+  0.645 against 0.676 at 1,000. A `step` that reads `setting.weight`, `elapsed` or `pass` now shows,
+  after a seek back and return, what a mix never sought shows. A seek no longer boxes its moment
+  once per record it puts back: the `seek` row at 10,000 subjects allocates 7.9 MB a frame against
+  8.8, and takes 10.44 ms against 9.88, inside its runs' spread (msb-uai, medians of nine
+  alternated runs against `1077ab4`). A seek's relink takes each voice's record from the subject's
+  old chain where its store can tell the record is still its own, instead of looking it up by
+  subject: the `seek` row at 10,000 subjects takes 9.42 ms a frame against 9.95, and 1,000 subjects
+  0.864 against 0.884 (msb-uai, medians of nine alternated runs against `c3fe7a8`).
+- A mix sought back often no longer grows without bound: each voice kept a little for every seek
+  back to a later moment than the last, and the records subjects left with after each seek, and
+  let go of neither. Three voices sought back and returned every frame held 2.26 MB more after
+  12,000 frames; they now hold what their live records need.
+- A lane fill no longer boxes numbers it hands between its own calls, which it did for 3 to 5
+  numbers a subject in some processes and none in others, by the order V8 happened to compile in.
+  10k subjects under a `fn` voice and a signal-weighted glow over 200 of them, with 200 subjects
+  leaving the glow and 200 entering each frame (bench/reach.mjs `part:200`), allocate 1.27 MB a
+  frame against 1.89 and take 1.924 ms against 2.037 read by `probe`, and 1.255 against 1.405 by
+  `pull`; with nothing moving by `pull`, 1.108 against 1.221 (keiei). `probed` allocates 1.02 MB a
+  frame against 1.65. No steady row moves past its spread: `fn` 2.942 against 2.903, `fn^` 2.323
+  against 2.390, `keys` 1.355 against 1.342 (msb-uai); `signal` reads 3.820 against 3.578, inside
+  its spread but slower in each of three such comparisons. Medians of six alternated runs, each in
+  its own process, `bench/ab.sh` against `main` at `4374f34`.
+
+## 0.11.0
+
+### Breaking
+
+- A voice plays one pass unless told otherwise: `loop` defaults to `false`, where it defaulted to
+  `true`. A `cue` that left `loop` out and relied on looping for good now needs `loop: true`. A
+  patch with no duration, and a motion patch, have no passes and play as before.
+- `Marked.mark` and an anchor's `mark` are a `MarkName`, one of a voice's five or a name it placed
+  inside itself, where they were a `Mark`. Code that reads `mark` as one of the five, such as an
+  exhaustive `switch`, needs a case for the rest.
+
+### Added
+
+- `marks` on a voice's, an owner's and a span's spec: named marks inside it beside its five, each
+  at voice ms into a pass, `marks: { drop: 340 }`. An anchor names one as it names the five,
+  `{ of: 'lead', mark: 'drop' }`; `marks` lists it, `book` books it under its name, and a read
+  ahead stops at it. Each is reached once, on the first pass that reaches it from where the voice
+  starts, while its clock runs forward and before it ends. A name of one of the five, and a time
+  outside a pass, are refused at `cue`.
+- `@msb235/blits/lean`: the package with a `mix` that leaves lanes out, for a host whose scenes
+  are too small to need them. It gives the same poses, and a bundle of `mix`, `kit`, `sum` and
+  `patch` is 44.5 kB gzipped against 59.9 from the main entry (esbuild, minified). `lanes: true`
+  is refused there. Its engine is exported as `lean`.
+- A read ahead after a seek back plays the calls the tape holds: `project(t)` past a recorded
+  call threw, and now makes the call on its copies as a seek there makes it on the mix. It still
+  throws for a `drop` of a subject a motion patch holds, and for a retarget or push made before
+  its voice had met the subject. The tape moves forward and back while the read is made.
+- `stepMs` on a voice's spec: the interval its `step` runs at, in place of the mix's. 0 steps it
+  once a frame by the frame's gap.
+- `share(by, i, n)`: member `i` of `n`'s share of a signal, as `mix.blend` weighs it, to weight a
+  voice outside the blend as that member, such as one member played alone.
+- `mix.blend` takes a `BlendMember`, `{ patch, name?, tags?, hits? }`, in place of a bare patch, so
+  a member answers to its own name in an anchor and carries its own tags and hits. Bare patches
+  take the spec's as before.
+- A mix warns, once per patch and outside production, when the first delta a voice's `at` returns
+  holds a key outside the patch's `writes`, naming the voice and the key. The mix still drops the
+  key, as it always has; `checkPatch` in `@msb235/blits/testing` still finds one returned only on
+  some subjects or phases.
+- `hits` and `seek` on an owner's and a span's spec. A hit is an event at a time on the owner's
+  clock, booked once while the owner plays, with its `score` and `tags`; a seek is where that clock
+  starts, so an owner cued at a rate below 0 with a seek plays its children back from there.
+- `seek({ frame })` and `project({ frame })`, on a mix and a transport, reach a frame by its
+  number, which `mix.seq` and `transport.seq` read. Rate 0 can hold mix time still across several
+  frames, and a seek or read by time lands on the last of them; by number it lands on any one
+  history still holds.
+- `catchUp: 'fresh'` on a voice's spec: a stateful subject first probed after its delay ran out
+  starts stepping from that probe with fresh state, where the default, `exact`, steps it from its
+  origin. The `stepMs` grid still counts from the origin, the fade-in is unchanged, and a handle
+  `seek` still rebuilds from the voice's start. Its state depends on when the host first looked,
+  so a read that meets such a subject late assesses it `held`.
+- A read ahead stops at each known event between now and the time read: each call the tape holds,
+  and each mark `marks` would list. A subject asked about is read at every stop, so a patch that
+  steps takes one step per stretch and a signal that keeps state sees each boundary: a voice
+  starting on the way meets its subject at its start, where it met it at the time read. `assess`
+  says `exact` for a stateful signal a read ahead fed, where it said `stepped`. The stops are made
+  only while a voice has a `step` or a signal weight; otherwise a read ahead crosses the gap in
+  one go as before.
+
+### Fixed
+
+- A seek ahead, or a read ahead, to the mix time rate 0 is holding stays at the host's own time.
+  It took the earliest host time the mix read that time at, behind calls already on the tape, so
+  a later seek back cued a voice still playing a second time and the next probe never returned.
+- `weightOf` on lanes reports the weight a voice over every subject gave a subject before a
+  subject fade made it keep a record per subject, until the next read. It said 0, where the
+  general path said the weight.
+- A seek or read back to before a `drop` finds a subject's fade out of a voice as it stood: mid
+  ramp, or faded out. It found the subject at full weight, and one faded out of a voice that had
+  not met it stayed out even before the fade. A subject a motion's retarget brought back after a
+  fade out is found faded out between the two.
+- `rise` on a voice faded before its start leaves it `pending`, to start on time and follow its
+  anchor again, as a seek back finds it. It went `live` at once and played from where its clock
+  would have read 0, ahead of its start, so a seek back played on differently from playing
+  straight through.
+- A read back to the frame a `drop` was made in, before anything read the mix that frame, shows
+  the subject met afresh, as the frame did. It showed the record the subject had before the drop,
+  a slewed weight's state included, in `project(t)` and `project({ frame })`.
+- `assess` after a seek back says `stepped` for a stateful signal the seek put back from a copy
+  history kept and stepped on, where a read at the mix's own time said `exact`. It goes on saying
+  so for that record as the mix plays on, since the state carries on from the step.
+- A voice running back from past its end shows nothing until it reaches its passes, unless it
+  freezes after, as a voice playing forward shows nothing before its start unless it freezes
+  before. It showed its last frame: `rate: -1, seek: 600` on a 300 ms pass showed it for its
+  first 300 ms, and so did a child its owner, turned back, had put past its end.
+- An owner's `out` and `end` marks are known while it plays, at its last child's end, once every
+  child's end is. They were fixed only when it left, so `marks` listed them only then and only
+  under `history`, a booker took them a frame late, an anchor to an owner's end waited until it
+  left, and without `history` they were never booked. Its `coast` stays listed once it has left,
+  where it went with its last child.
+- `pull` reads `undefined` at a position its list has gained. A list read as `[undefined]` and
+  then as `[undefined, undefined]` threw, reading the new position as the subject it read there
+  last time.
+- A spring, glide or tween made by another copy of blits of the same release, loaded beside this
+  one, runs as a motion on this copy's mix: on lanes, and retargeted, pushed and read through its
+  handle, which refused it. It played through `at` off the lanes. Copies of different releases
+  still keep apart.
+- `mix.span` refuses a rate below 0. A span cued backward placed none of its children, which
+  waited for good, and never left. Its handle's `rate` still turns one that plays.
+- A voice whose patch has no duration books no hits while its clock runs back, as every other
+  voice does. One cued backward booked each hit ahead of it.
+- A fade set for a time after a voice's passes run out no longer begins in place of the voice
+  ending, where one frame crossed both: `fade({ at })` on a voice with no `freeze` that ended
+  before `at` played on, held at its last frame, until the fade finished.
+- A seek forward to the time of a recorded call lands that frame once. It landed it again after
+  the call, so a `rise` played there on a voice past its end began the voice's fade over.
+- A voice cued with `seek`, or sought while pending, keeps its count of rebuilds with its
+  controls when it starts. A seek back to after its start, then a handle `seek` played again
+  before the subject was read, left the subject's state as it was rather than rebuilding it.
+- A mix sought back time after time no longer steps a subject from the same copy of its state,
+  further each time. A seek lets go of the copies made after the moment it sought, so a mix
+  sought 300 ms back and to where it was before every frame stepped each subject from the copy
+  before its first seek: 70 steps at the first frame and 1069 at the 300th, at `stepMs` 5. The
+  copy a record is put back from now keeps its state stepped ahead to near the moment sought,
+  and the next record put back from it steps on from there: 67 to 74 steps at every frame. It
+  shows the same values. Under `maxDt`, without `stepMs`, or for a patch that `reads` a host
+  field, a record steps from the copy as before.
+- Replacing a voice makes less garbage. A one-subject tween voice retargeted as it is cued, while
+  another leaves and its subject is dropped, allocates about 13 KB, from 21.5
+  (`bench/churnwho.mjs`, 5,000 voices), and a `pull` keeps what it knows of a channel between
+  calls, about 1.2 KB a call for four channels. Frame time is unchanged.
+- A seek back, or a read back, places a subject whose start had moved while it waited where the
+  move put it. A copy of a record kept while its `stagger` delay was running, on a voice with
+  `freeze: 'before'`, holds the start as it was then; a rate, a ramp, a `seek` with
+  `state: 'keep'`, an owner's rate or the mix's rate then moved that start, and a record put back
+  from the copy to a moment past the old start kept the old one, so its `step` ran on from the
+  wrong time. A seek lets go of the later copies, so a mix sought back before every frame showed
+  it at every frame from then on; `project(t)` showed it for `t` up to one copy's interval past
+  the move.
+- A seek back to before a subject faded out of a voice finds the voice reaching it again, where
+  the voice had not met the subject before the fade. The subject stayed out of the voice with
+  `lanes: false`, and with lanes on for a voice naming its `subjects`; otherwise lanes brought it
+  back, so the two paths read differently. A read back to before the fade, `project(t)`, left
+  it out on both, and reaches it now.
+- A seek or a read back into a subject's ramp out of a voice, `fade({ subject, over })`, finds
+  the ramp once it has ended. The subject read at full weight there, and after a seek it stayed
+  in the voice at full weight for good.
+- `weightOf` reads 0 after a seek back until the subject is probed again. What a subject's last
+  probe by then read is not kept, and it reported a weight from after the moment sought, or one
+  older than its last probe for a voice on a lane, so the two paths read differently.
+- A write to the handle of a voice waiting for its cue after a seek back changes nothing, and the
+  tape does not record it. It put the voice on the mix's schedule, so the voice started at its
+  start time outside the mix, folded in but missing from `voices()`, and it branched the tape,
+  which left the voice's cue in the old future.
+- Dropping a subject no longer costs time in step with how many subjects the mix holds. With a
+  tween voice per subject, stopping one voice and dropping its subject cost 2.2 µs among 1,000
+  subjects and 15.6 among 10,000; it costs 0.9 and 2.6 (`bench/restart.mjs`).
+- The first `pull` after a voice naming a subject comes or goes, or a subject is dropped, no
+  longer reads every subject's chain to find the ones that changed, and a retargeted tween copies
+  its stretch without an iterator. The frame after 100 voices are replaced among 10,000 took
+  about 2.1 ms and takes about 1.35.
+
 ## 0.10.0
 
 ### Breaking

package/README.md

@@ -28,7 +28,7 @@ const flicker = patch<Part, PartPose>(
 );
 
 const m = mix<Part, PartPose>(PART);
-const handle = m.cue({ patch: flicker, fade: { in: 300, out: 300 } });
+const handle = m.cue({ patch: flicker, loop: true, fade: { in: 300, out: 300 } });
 
 // Once a frame: tell the mix what time it is, then ask for the parts you are about to draw.
 function frame(timestamp: number) {
@@ -48,12 +48,12 @@ In order, on the same mix:
 
 ```ts
 // Place a voice at a time on the host's clock, or against another voice's marks.
-m.cue({ patch: typeIn, name: 'title', start: 1000, loop: false });
-m.cue({ patch: tint, loop: false, anchor: { start: { after: 'title', by: 200 } } });
+m.cue({ patch: typeIn, name: 'title', start: 1000 });
+m.cue({ patch: tint, anchor: { start: { after: 'title', by: 200 } } });
 
 // A span fits the voices it holds into a budget, one after another by default.
 const intro = m.span({ duration: 2000 });
-for (const line of lines) m.cue({ patch: typeIn, loop: false, owner: intro });
+for (const line of lines) m.cue({ patch: typeIn, owner: intro });
 
 // Read the mix half a second ahead without moving it, or move it: a scrubber.
 const next = m.project(m.now + 500).probe(part);
@@ -91,6 +91,17 @@ npm run site:smoke   # build, then load every page headless and fail on any erro
 
 `.github/workflows/site.yml` deploys it to GitHub Pages on every push to `main`, and by hand.
 
+## A smaller bundle
+
+Lanes, which work a channel out for every subject at once, are about a quarter of the package. A
+host with tens of subjects does not need them:
+
+```ts
+import { kit, mix, patch, sum } from '@msb235/blits/lean';
+```
+
+Everything else is the same and so are the poses. `lanes: true` is refused there.
+
 ## Writing patches for blits in another library
 
 A library that ships patches exports them with the channels they write, as a `Kit` of its own

package/dist/arcs.d.ts

@@ -0,0 +1,40 @@
+import type { Mixer } from './mixer.js';
+import type { ArcHandle, ArcSpec } from './types.js';
+import type { Voice } from './voice.js';
+/** What an arc keeps beside its owner: how long its enter and exit last, which parts it has, its blend. */
+export declare class Arc {
+    readonly enter: number;
+    readonly exit: number;
+    readonly blend: number;
+    /** By part, whether it has one. */
+    readonly has: readonly boolean[];
+    /** How long its hold lasts as cued; Infinity for one held open. */
+    readonly hold: number;
+    constructor(enter: number, exit: number, blend: number, 
+    /** By part, whether it has one. */
+    has: readonly boolean[], 
+    /** How long its hold lasts as cued; Infinity for one held open. */
+    hold: number);
+}
+/** Where an arc ends on its own clock: Infinity while its hold is open. */
+export declare function arcEnd<I, O>(voice: Voice<I, O>): number;
+/**
+ * What an arc multiplies into the weight of a voice it holds at mix time `now`: its part's ramp,
+ * scaled down where a hold shorter than the blend leaves all three ramps up at once and their sum
+ * would pass 1.
+ */
+export declare function arcShare<I, O>(arcVoice: Voice<I, O>, child: Voice<I, O>, now: number, reduced: boolean): number;
+/** Cues an arc: its owner, then each part's voices on its clock. */
+export declare function cueArc<I, O>(mix: Mixer<I, O>, spec: ArcSpec<I, O>): ArcHandle<I>;
+/**
+ * Ends an arc's hold at mix time now, so its exit begins half a blend later and its blend starts
+ * now; where the enter is still playing, the exit follows it. Nothing where the exit has begun.
+ */
+export declare function release<I, O>(mix: Mixer<I, O>, voice: Voice<I, O>): void;
+/**
+ * Lets each arc's parts leave once the blend after them is over, and the arc itself at its end:
+ * played, as a voice that ran its passes is.
+ */
+export declare function settleArcs<I, O>(mix: Mixer<I, O>, now: number): void;
+/** An arc's marks: when its enter ends, its hold ends and its exit begins and ends. */
+export declare function arcMark<I, O>(voice: Voice<I, O>, start: number, mark: 'in' | 'coast' | 'out' | 'end'): number | undefined;

package/dist/arcs.js

@@ -0,0 +1,239 @@
+import { retire } from './fade.js';
+import { noted } from './history.js';
+import { ownerReading } from './owner.js';
+import { startAt } from './place.js';
+import { refit } from './spans.js';
+/** An arc's parts in the order they play: its enter, its active and its exit. */
+const PARTS = ['enter', 'active', 'exit'];
+/** What an arc keeps beside its owner: how long its enter and exit last, which parts it has, its blend. */
+export class Arc {
+    enter;
+    exit;
+    blend;
+    has;
+    hold;
+    constructor(enter, exit, blend, 
+    /** By part, whether it has one. */
+    has, 
+    /** How long its hold lasts as cued; Infinity for one held open. */
+    hold) {
+        this.enter = enter;
+        this.exit = exit;
+        this.blend = blend;
+        this.has = has;
+        this.hold = hold;
+    }
+}
+/** Where each part an arc has starts and ends on its clock, for a hold of `hold`; null for a part it lacks. */
+function segments(arc, hold) {
+    const bounds = [0, arc.enter, arc.enter + hold, arc.enter + hold + arc.exit];
+    const end = bounds[3];
+    const out = [null, null, null];
+    for (let p = 0; p < 3; p++) {
+        if (!arc.has[p])
+            continue;
+        let next = p + 1;
+        while (next < 3 && !arc.has[next])
+            next++;
+        out[p] = [bounds[p], next < 3 ? bounds[next] : end];
+    }
+    return out;
+}
+/** Where an arc ends on its own clock: Infinity while its hold is open. */
+export function arcEnd(voice) {
+    const arc = voice.arc;
+    return arc.enter + voice.hold + arc.exit;
+}
+/**
+ * A part's weight at `t` on its arc's clock, klieg's: up over the blend centered on where it
+ * starts and down over the one where it ends, except at the arc's own start and end, where it
+ * holds full weight.
+ */
+function rampOf(s, e, end, blend, t) {
+    if (e <= s)
+        return 0;
+    const half = blend / 2;
+    const first = s === 0;
+    const last = e === end;
+    if ((!first && t < s - half) || (!last && t >= e + half))
+        return 0;
+    const up = first ? 1 : blend > 0 ? Math.min(1, (t - s + half) / blend) : 1;
+    const down = last ? 1 : blend > 0 ? Math.min(1, (e + half - t) / blend) : 1;
+    return Math.min(up, down);
+}
+/**
+ * What an arc multiplies into the weight of a voice it holds at mix time `now`: its part's ramp,
+ * scaled down where a hold shorter than the blend leaves all three ramps up at once and their sum
+ * would pass 1.
+ */
+export function arcShare(arcVoice, child, now, reduced) {
+    const arc = arcVoice.arc;
+    const read = ownerReading(arcVoice, now);
+    const t = read > 0 ? read : 0;
+    const segs = segments(arc, arcVoice.hold);
+    const end = arc.enter + arcVoice.hold + arc.exit;
+    const blend = reduced ? 0 : arc.blend;
+    const mine = segs[child.part];
+    if (mine == null)
+        return 0;
+    const own = rampOf(mine[0], mine[1], end, blend, t);
+    if (own <= 0)
+        return 0;
+    let total = 0;
+    for (const s of segs)
+        if (s !== null)
+            total += rampOf(s[0], s[1], end, blend, t);
+    return total > 1 ? own / total : own;
+}
+/** How long a part lasts: its longest voice's `duration`, or patch duration times passes. */
+function lengthOf(part) {
+    let most = 0;
+    for (const v of part) {
+        const loop = v.loop;
+        const passes = loop === undefined || loop === false ? 1 : loop === true ? Infinity : loop;
+        const own = v.duration ?? (v.patch.duration > 0 ? v.patch.duration * passes : 0);
+        if (!(own >= 0))
+            throw new RangeError(`blits: an arc's part lasts 0 ms or more, not ${own}`);
+        if (own > most)
+            most = own;
+    }
+    return most;
+}
+const listOf = (part) => part === undefined ? undefined : Array.isArray(part) ? part : [part];
+/** Cues an arc: its owner, then each part's voices on its clock. */
+export function cueArc(mix, spec) {
+    if ((spec.rate ?? 1) < 0)
+        throw new Error('blits: an arc plays its parts forward from its start, so it is not cued backward');
+    if (spec.freeze !== undefined)
+        throw new Error('blits: an arc holds each part’s first and last frames itself, so it takes no freeze');
+    const { enter, active, exit, hold, blend, ...own } = spec;
+    const parts = [listOf(enter), listOf(active), listOf(exit)];
+    const lengths = parts.map((p) => (p === undefined ? 0 : lengthOf(p)));
+    for (const p of [0, 2])
+        if (!Number.isFinite(lengths[p]))
+            throw new Error(`blits: an arc's ${PARTS[p]} has to end, so it cannot loop for good`);
+    const held = hold === 'open' ? Number.POSITIVE_INFINITY : (hold ?? lengths[1] ?? 0);
+    if (!(held >= 0))
+        throw new RangeError(`blits: an arc holds for 0 ms or more, not ${hold}`);
+    const fade = blend ?? 0;
+    if (!(fade >= 0 && Number.isFinite(fade)))
+        throw new RangeError(`blits: an arc blends over 0 ms or more, not ${blend}`);
+    const arc = new Arc(lengths[0], lengths[2], fade, parts.map((p) => p !== undefined), held);
+    mix.arcing = arc;
+    let handle;
+    try {
+        handle = mix.owns(own);
+    }
+    finally {
+        mix.arcing = null;
+    }
+    const starts = [0, arc.enter, arc.enter + held];
+    parts.forEach((part, p) => {
+        for (const v of part ?? []) {
+            const { duration: _, ...rest } = v;
+            const child = {
+                ...rest,
+                owner: handle,
+                start: starts[p],
+                freeze: 'both',
+            };
+            // The hold, not the patch, says how long the active plays, so it loops unless told otherwise.
+            if (p === 1 && hold !== undefined && v.loop === undefined)
+                child.loop = true;
+            mix.cue(child);
+            mix.cued[mix.cued.length - 1].part = p;
+        }
+    });
+    return handle;
+}
+/**
+ * Ends an arc's hold at mix time now, so its exit begins half a blend later and its blend starts
+ * now; where the enter is still playing, the exit follows it. Nothing where the exit has begun.
+ */
+export function release(mix, voice) {
+    const arc = voice.arc;
+    if (arc === null)
+        throw new Error('blits: release ends an arc’s hold, and this is no arc');
+    if (voice.state === 'done' || voice.state === 'fading')
+        return;
+    const local = ownerReading(voice, mix.now);
+    const lead = arc.exit > 0 && !mix.reduced ? arc.blend / 2 : 0;
+    const at = Math.max(arc.enter, local + lead);
+    if (!(at < arc.enter + voice.hold))
+        return;
+    voice.hold = at - arc.enter;
+    for (const child of voice.holding?.children ?? [])
+        if (child.part === 2 && child.state === 'pending')
+            startAt(mix, child, at);
+    noteArc(mix, voice);
+}
+/** Records an arc's new hold, and has the span holding it fit again. */
+function noteArc(mix, voice) {
+    noted(mix, voice);
+    if (voice.owner?.fitting)
+        refit(mix, voice.owner);
+    mix.lanes?.refill();
+}
+/**
+ * Lets each arc's parts leave once the blend after them is over, and the arc itself at its end:
+ * played, as a voice that ran its passes is.
+ */
+export function settleArcs(mix, now) {
+    for (const voice of mix.owners ?? []) {
+        const arc = voice.arc;
+        if (arc === null || voice.state === 'done' || voice.state === 'pending')
+            continue;
+        const local = ownerReading(voice, now);
+        if (!Number.isFinite(local))
+            continue;
+        const end = arcEnd(voice);
+        if (local >= end) {
+            const at = voice.timeAt(end);
+            voice.play(true, at, mix.transport.seq);
+            retire(mix, voice, at);
+            continue;
+        }
+        const segs = segments(arc, voice.hold);
+        const half = mix.reduced ? 0 : arc.blend / 2;
+        for (const child of [...(voice.holding?.children ?? [])]) {
+            const s = segs[child.part];
+            if (s == null || s[1] === end || child.state === 'done')
+                continue;
+            if (local >= s[1] + half)
+                retire(mix, child, voice.timeAt(s[1] + half));
+        }
+    }
+}
+/** An arc's marks: when its enter ends, its hold ends and its exit begins and ends. */
+export function arcMark(voice, start, mark) {
+    const arc = voice.arc;
+    const at = (t) => {
+        const u = voice.timeAt(t);
+        return Number.isFinite(u) ? Math.max(start, u) : undefined;
+    };
+    if (mark === 'in') {
+        const t = at(arc.enter);
+        return t === undefined ? t : Math.max(t, start + (voice.fade.in ?? 0));
+    }
+    const coast = at(arc.enter + voice.hold);
+    // Faded, or set to fade, before its hold ended: it left with no exit.
+    const out = voice.out;
+    const cut = out !== null ? out.at : Number.isFinite(voice.outAt) ? voice.outAt : undefined;
+    const cutShort = cut !== undefined && (coast === undefined || cut < coast);
+    if (mark === 'coast')
+        return cutShort ? undefined : coast;
+    if (mark === 'out') {
+        if (cutShort)
+            return cut;
+        return voice.state === 'done' && coast === undefined ? voice.doneAt : coast;
+    }
+    if (voice.state === 'done')
+        return voice.doneAt;
+    if (cutShort) {
+        if (out !== null)
+            return out.at + out.over;
+        const over = Number.isNaN(voice.outOver) ? (voice.fade.out ?? 0) : voice.outOver;
+        return cut + over;
+    }
+    return at(arcEnd(voice));
+}

package/dist/blend.js

@@ -1,5 +1,6 @@
 import { stateful } from './hosts.js';
 import { reading } from './reading.js';
+import { shareOf } from './signals.js';
 import { Store } from './store.js';
 export function blendOf(by, stops) {
     return {
@@ -29,11 +30,6 @@ export function ownBlends(voices) {
         of.members.push(v);
     }
 }
-/** A blend member's weight for its signal's read `k`: the members' stops sit evenly along 0..1. */
-function shareOf(k, i, stops) {
-    const d = stops === 0 ? 0 : Math.abs(k * stops - i);
-    return d >= 1 ? 0 : 1 - d;
-}
 /** A blend member's share of its signal's read for this subject this frame, made by the first to ask. */
 export function blended(voice, subject, held, slot) {
     const { of, i } = voice.blend;

package/dist/book.d.ts

@@ -22,6 +22,8 @@ export interface BookHost<I, O> {
     /** The booker canceled: forget it. */
     unhook(booker: Book<I, O>): void;
 }
+/** Whether voice ms `at` falls in a pass of a patch `duration` long: 0 up to it, or 0 on for none. */
+export declare function inPass(at: number, duration: number): boolean;
 /** Refuses hits a voice could never play. */
 export declare function checkHits(hits: readonly Hit[], duration: number): void;
 /** One `book` call: maps host time onto the outside clock and takes each item once. */

package/dist/book.js

@@ -5,10 +5,14 @@ const SLEW = 0.05;
 /** A booking whose time moves by more than this is canceled and taken again. */
 const RETIME_MS = 1;
 const none = [];
+/** Whether voice ms `at` falls in a pass of a patch `duration` long: 0 up to it, or 0 on for none. */
+export function inPass(at, duration) {
+    return at >= 0 && (duration > 0 ? at < duration : Number.isFinite(at));
+}
 /** Refuses hits a voice could never play. */
 export function checkHits(hits, duration) {
     for (const h of hits)
-        if (!(h.at >= 0) || (duration > 0 ? !(h.at < duration) : !Number.isFinite(h.at)))
+        if (!inPass(h.at, duration))
             throw new RangeError(duration > 0
                 ? `blits: a hit's at is voice ms into a pass, 0 up to ${duration}, not ${h.at}`
                 : `blits: a hit's at is voice ms, 0 or more, not ${h.at}`);
@@ -198,6 +202,11 @@ export class Book {
             if (!(hi > t.seenTo))
                 continue;
             const lo = Math.max(t.seenTo, voice.elapsedAt(loAt));
+            // Its clock runs back: hits come only as it runs forward.
+            if (!(lo <= hi)) {
+                t.seenTo = hi;
+                continue;
+            }
             const d = voice.duration;
             const last = d > 0 ? Math.min(voice.passes - 1, Math.floor(hi / d)) : 0;
             for (let pass = d > 0 ? Math.max(0, Math.floor(lo / d)) : 0; pass <= last; pass++) {
@@ -246,8 +255,23 @@ export class Book {
         return this.host.hostOf(t);
     }
 }
-const markIndex = { start: 1, in: 2, coast: 3, out: 4, end: 5 };
 /** A mark's identity: its voice and which of its marks, or the announcement. */
 function keyOf(m) {
-    return m.order * 6 + (m.mark === undefined ? 0 : markIndex[m.mark]);
+    const k = m.order * 6;
+    switch (m.mark) {
+        case undefined:
+            return k;
+        case 'start':
+            return k + 1;
+        case 'in':
+            return k + 2;
+        case 'coast':
+            return k + 3;
+        case 'out':
+            return k + 4;
+        case 'end':
+            return k + 5;
+        default:
+            return `${m.order}\u0000${m.mark}`;
+    }
 }