@hraness/dawg 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to dawg are recorded here. Versions follow [semantic version
 
 ## Unreleased
 
+## 0.4.1
+
+Sound previews now crossfade instead of clicking, reverb changes are heard in under 100 ms, and the rhythm editor and chord settings hold changes until you keep them. dawg.sh gains a security policy and security headers.
+
+### Previewing changes
+
+- **Edits crossfade instead of clicking.** When the loop (audition or song) swaps to a new render, the old and new buffers crossfade over 20 ms with equal-power gains at the same beat, so a change no longer steps the waveform. Playback only: renders and exports are byte-identical.
+- **`/euclid` and the chord settings stage while the loop plays.** `Space` in the rhythm editor or the menu's Chords section (`/menu chords`) starts the audition loop; changes are then staged and heard (`●`, `B staged N`, `E(5,16) ← E(4,16)`, `Db ← C`), `a` flips A/B, `Enter` keeps them as one undo step and `Esc` reverts with nothing written. In the Chords section the loop plays the track's chord phrase under the current settings. With the loop off, both commit at once as before; their key footers and `?` panels use the shared audition keys.
+- **Reverb changes are heard faster.** The stem cache keeps each track's reverb input and tail apart from its dry signal, so a reverb mix (or mix lane) change re-mixes the cached tail instead of re-rendering the voice and the room. Key to audio scheduled on a 4-track song: reverb mix on a wavetable pad in context 140 → 64 ms median (p90 151 → 68 ms); a filter change in context 100 → 74 ms. The bus mix loops also moved out of the large render function, which the JIT optimized late. Renders stay byte-identical (a new test checks cached re-mixes against cold renders and recorded digests).
+
+### Security
+
+- **A security policy.** `SECURITY.md` and `https://dawg.sh/.well-known/security.txt` say how to report a vulnerability privately.
+- **dawg.sh sends security headers** on every route: a Content Security Policy limited to the site's own origin and its analytics hosts, HSTS, `nosniff`, `DENY` framing, a strict referrer policy and a permissions policy that turns off camera, microphone and location.
+- Dependabot also watches the site's dependencies (minor and patch updates, grouped).
+
 ## 0.4.0
 
 dawg now has a full sound engine with Strudel's synth, effect and sample parameters, Strudel sample packs, wavetables (including ones made from your own audio), Euclidean drum rows and a pattern library, Orchid-style chords, sound previews with A/B, and one consistent set of keys across every screen. Projects from 0.3.0 open and sound the same, and the `dawg` SDK is 1.13.0 (every step additive within v1).

package/DAWG.md

@@ -678,10 +678,11 @@ Prompt grammar: `euclid kick 4 16`, `euclid hat 7 16 rotate 2`, `euclid hat swin
 | `← →` / `h l` / `- +`       | nudge the selected parameter                      |
 | `Tab` / `Shift-Tab` (`] [`) | next / previous parameter                         |
 | digits, `.`, `-`, Backspace | type a value, Enter applies                       |
-| Enter                       | add a row for a voice without one                 |
-| Space                       | audition the voice                                |
+| Enter                       | add a row for a voice without one; keep (looping) |
+| Space                       | start or stop the audition loop (staging)         |
+| `a` / `c`                   | A/B / solo ↔ in context, while the loop plays     |
 | `x` / Delete, `f`           | remove the row and its notes / freeze it to notes |
-| Esc                         | back (cancels typing, then closes)                |
+| Esc                         | cancel typing, revert staged changes, then close  |
 
 ## Chords
 
@@ -836,7 +837,7 @@ Hear a sound change before you keep it. In the edit menu (every section: Sound,
 
 The loop is the track's own notes over its loop region when that is four bars or shorter, otherwise the two bars under the playhead (or the track's first two bars with notes, if those are empty). A track with no notes plays a short phrase by role: a chord for pads and keys, a riff for bass and leads, a groove for kits and drums, and one held note for wavetables so position and envelope changes are audible. It plays solo by default; `c` switches to the whole mix with the track in it.
 
-While the loop plays, each change you make is **staged**, not committed. The loop re-renders only the changed track through the normal renderer and stem cache, in the render worker, and swaps it in within about 100 ms. Held keys are coalesced so only the latest value renders. The menu title shows `●` and `B staged N`, and each changed row shows the staged value beside the committed one (`mix  0.5 ← 0.3`).
+While the loop plays, each change you make is **staged**, not committed. The loop re-renders only the changed track through the normal renderer and stem cache, in the render worker, and swaps it in within about 100 ms (a reverb mix change re-mixes the cached tail and is heard in about 65 ms). Every swap, here and in the song player, crossfades old to new over 20 ms at the same beat, so changes never click; renders and exports never pass through the crossfade. Held keys are coalesced so only the latest value renders. The menu title shows `●` and `B staged N`, and each changed row shows the staged value beside the committed one (`mix  0.5 ← 0.3`).
 
 | Key     | While auditioning                                            |
 | ------- | ------------------------------------------------------------ |
@@ -850,6 +851,8 @@ While the loop plays, each change you make is **staged**, not committed. The loo
 
 Kept changes are one `ScoreOperation` (`preview.commit`, listing the commands), so `Ctrl-Z` takes them all back at once, and they sync to other windows and the project files like any edit. If the score changes underneath (another window, the agent, an undo), the staged commands are re-applied on top of the new score; any that no longer apply are dropped, with a notice. Leaving the menu reverts anything staged. With the loop off, the menu behaves as before: each change is committed right away.
 
+**The rhythm editor and the chord settings stage too.** `/euclid` and the chord settings (the menu's Chords section, `/menu chords`) use the same loop and keys. In `/euclid`, `Space` loops the drum track; pulses, steps, rotate, typed values, a new row, `off` and `freeze` are staged, the title shows `●` and `B staged N`, and a changed lane shows `E(5,16) ← E(4,16)`. Chord settings are window settings rather than score edits, so while the Chords section is open the loop plays the focused track's chord phrase (two bars of the song key's progression, voiced and performed by the current settings: inversion, spread, bass, sevenths, block/strum/arp, pattern); a staged setting changes the B phrase, and `a` flips back to the committed settings. `Enter` keeps every staged change as one undo step: rhythm edits as one `preview.commit` revision, and chord settings applied at once (a key change, the only one stored in the score, as one revision). `Esc` reverts with nothing written. With the loop off, both screens commit each change at once, as before.
+
 **Lists audition on hover.** With the loop on, moving the cursor through a list plays the highlighted item on the loop: the wavetable list (built-in, pack and project tables), instruments, drum kits and patterns, and every choice list (filter type, warp mode, presets). It is the browser-preview model of Ableton and Bitwig, applied to the loop you are already hearing. Each move replaces the previous hover, so the staged count stays at one, and fast moves skip straight to the latest item. A pack item that has to be fetched shows `fetching…` in the title; the cursor keeps moving and the item plays once it arrives. `Enter` chooses the item (it stays staged until you keep), `Esc` or `←` leaves the list and drops the hover. The `/kit` and `/pattern` pickers work the same way: `Space` starts the loop, moving hears each kit or groove, `Enter` keeps it, `Esc` cancels.
 
 | Key in a list | While auditioning                                   |

package/README.md

@@ -15,17 +15,17 @@ curl -fsSL https://dawg.sh/install | sh
 or install the release tarball from GitHub directly:
 
 ```sh
-bun add -g https://github.com/hraness/dawg/releases/download/v0.4.0/hraness-dawg-0.4.0.tgz
+bun add -g https://github.com/hraness/dawg/releases/download/v0.4.1/hraness-dawg-0.4.1.tgz
 dawg --help
 ```
 
 Each [release](https://github.com/hraness/dawg/releases) is immutable and ships the tarball, a `SHA256SUMS` file and a build provenance attestation. To check a download before installing it:
 
 ```sh
-gh release download v0.4.0 --repo hraness/dawg
+gh release download v0.4.1 --repo hraness/dawg
 shasum -a 256 -c SHA256SUMS
-gh attestation verify hraness-dawg-0.4.0.tgz --repo hraness/dawg
-bun add -g "$PWD/hraness-dawg-0.4.0.tgz"
+gh attestation verify hraness-dawg-0.4.1.tgz --repo hraness/dawg
+bun add -g "$PWD/hraness-dawg-0.4.1.tgz"
 ```
 
 dawg is also on npm as [`@hraness/dawg`](https://www.npmjs.com/package/@hraness/dawg):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/dawg",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/audio/effects/chain.ts

@@ -21,7 +21,15 @@ import {
 import { applyChorus, applyLeslie, applyPhaser } from "./modulation.ts";
 import { applyDelay, applyReverb } from "./space.ts";
 
-export { delayTailFor, reverbImpulse, reverbTailFor } from "./space.ts";
+export {
+  addReverbWet,
+  delayTailFor,
+  reverbActive,
+  reverbImpulse,
+  reverbTailFor,
+  reverbWet,
+  type ReverbWet,
+} from "./space.ts";
 export { interpolateAutomation, type EffectContext } from "./common.ts";
 
 type MonoStage = (
@@ -77,6 +85,7 @@ export function applyMonoChain(
 /**
  * Stereo stages, in chain order, after pan. A track on a shared orbit bus
  * (`sends: false`) skips delay and reverb: the bus applies them to the sum.
+ * `reverb: false` stops before the reverb (the stem cache runs it apart).
  */
 export function applyStereoChain(
   left: Float64Array,
@@ -84,12 +93,13 @@ export function applyStereoChain(
   track: Track,
   context: EffectContext,
   sends = true,
+  reverb = sends,
 ): void {
   for (const stage of FX_CHAIN.slice(PAN_INDEX + 1)) {
     if (stage === "delay") {
       if (sends) applyDelay(left, right, track, context);
     } else if (stage === "reverb") {
-      if (sends) applyReverb(left, right, track, context);
+      if (reverb) applyReverb(left, right, track, context);
     } else {
       const values = track.fx?.[stage as FxName];
       const apply = STEREO[stage as FxName];

package/src/audio/effects/convolution.ts

@@ -119,9 +119,48 @@ export function convolveStereo(
   gain: number,
   gainAt?: (index: number) => number,
 ): void {
+  const rawL = new Float64Array(input.length);
+  const rawR = new Float64Array(input.length);
+  const scale = convolveRaw(input, impulse, rawL, rawR);
+  if (scale === 0) return;
+  addConvolved(rawL, rawR, scale, outL, outR, gain, gainAt);
+}
+
+/**
+ * Adds the unscaled convolution from `convolveRaw` at `gain` (or `gainAt`
+ * per sample): `out += raw · (gain · scale)`, the order `convolveStereo`
+ * always used, so a cached raw signal mixes to the same samples.
+ */
+export function addConvolved(
+  rawL: Float64Array,
+  rawR: Float64Array,
+  scale: number,
+  outL: Float64Array,
+  outR: Float64Array,
+  gain: number,
+  gainAt?: (index: number) => number,
+): void {
+  for (let index = 0; index < rawL.length; index += 1) {
+    const g = (gainAt ? gainAt(index) : gain) * scale;
+    outL[index]! += rawL[index]! * g;
+    outR[index]! += rawR[index]! * g;
+  }
+}
+
+/**
+ * The convolution input ∗ impulse into `rawL`/`rawR` before its inverse-FFT
+ * scale, which it returns. Samples past the input are left as they were
+ * (zero for fresh arrays), as is everything when the impulse is empty.
+ */
+export function convolveRaw(
+  input: Float64Array,
+  impulse: Impulse,
+  rawL: Float64Array,
+  rawR: Float64Array,
+): number {
   const length = input.length;
   const irLength = impulse.left.length;
-  if (length === 0 || irLength === 0) return;
+  if (length === 0 || irLength === 0) return 0;
   const block = partitionSize(irLength);
   const n = block * 2;
   const partitions = Math.ceil(irLength / block);
@@ -179,12 +218,11 @@ export function convolveStereo(
     const outStart = k * block;
     const count = Math.min(block, length - outStart);
     for (let i = 0; i < count; i += 1) {
-      const index = outStart + i;
-      const g = (gainAt ? gainAt(index) : gain) * scale;
-      outL[index]! += accRe[block + i]! * g;
-      outR[index]! += accIm[block + i]! * g;
+      rawL[outStart + i] = accRe[block + i]!;
+      rawR[outStart + i] = accIm[block + i]!;
     }
   }
+  return scale;
 }
 
 /** Built-in impulse names (`builtin:<name>`). */

package/src/audio/effects/space.ts

@@ -5,8 +5,9 @@
 import type { Track } from "../../../core/score.ts";
 import type { DecodedSample } from "../samples.ts";
 import {
+  addConvolved,
   builtinImpulse,
-  convolveStereo,
+  convolveRaw,
   sampleImpulse,
   type Impulse,
 } from "./convolution.ts";
@@ -181,6 +182,10 @@ export function reverbTailFor(
  * feedback for an exact -60 dB decay time; `dim` sets the in-loop damping
  * frequency, `lowpass` filters the input and `predelay` delays it.
  * `wetOnly` (a shared orbit bus) replaces the input with the tail alone.
+ *
+ * It runs in two steps: `reverbWet` (the tail before its mix gain, which
+ * does not depend on `mix`) and `addReverbWet`. The stem cache keeps the
+ * first, so a mix-only edit skips the room entirely.
  */
 export function applyReverb(
   left: Float64Array,
@@ -189,28 +194,50 @@ export function applyReverb(
   context: EffectContext,
   wetOnly = false,
 ): void {
-  const reverb = track.reverb;
-  if (!reverb) return;
-  const mixParam = new Param(
-    reverb.mix,
+  const wet = reverbWet(left, right, track, context);
+  if (wet) addReverbWet(left, right, wet, track, context, wetOnly);
+}
+
+/** A reverb's tail before its mix gain (`scale` for an impulse response). */
+export type ReverbWet = Readonly<{
+  left: Float64Array;
+  right: Float64Array;
+  /** The convolution's inverse-FFT scale; absent for the algorithmic room. */
+  scale?: number;
+}>;
+
+function mixParamOf(track: Track, context: EffectContext): Param {
+  return new Param(
+    track.reverb?.mix ?? 0,
     track.fxAutomation?.["reverb-mix"],
     context.samplesPerTick,
   );
-  if (reverb.mix <= 0 && !mixParam.automated) return;
+}
+
+/** Whether the track's reverb sounds at all (a mix above 0, or a lane). */
+export function reverbActive(track: Track): boolean {
+  const reverb = track.reverb;
+  if (!reverb) return false;
+  return (
+    reverb.mix > 0 || (track.fxAutomation?.["reverb-mix"] ?? []).length > 0
+  );
+}
+
+/**
+ * The reverb tail of the pair, before the mix gain; `left`/`right` are
+ * read, not changed. Undefined when the reverb is off.
+ */
+export function reverbWet(
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  context: EffectContext,
+): ReverbWet | undefined {
+  const reverb = track.reverb;
+  if (!reverb || !reverbActive(track)) return undefined;
   const { sampleRate } = context;
   const impulse = reverbImpulse(track, sampleRate, context.irs);
-  if (impulse) {
-    applyConvolutionReverb(
-      left,
-      right,
-      track,
-      context,
-      impulse,
-      mixParam,
-      wetOnly,
-    );
-    return;
-  }
+  if (impulse) return convolutionWet(left, right, track, context, impulse);
   const scale = sampleRate / 44_100;
   const sizeFeedback = 0.7 + 0.28 * reverb.size;
   const damp =
@@ -219,7 +246,6 @@ export function applyReverb(
       : Math.exp(
           (-2 * Math.PI * Math.min(reverb.dim, sampleRate * 0.45)) / sampleRate,
         );
-  let wet = reverb.mix * REVERB_WET_SCALE;
   const channel = (spread: number) => ({
     combs: COMB_TUNING.map((tuning) => {
       const length = Math.max(1, Math.round((tuning + spread) * scale));
@@ -266,9 +292,9 @@ export function applyReverb(
   const predelaySamples = Math.round((reverb.predelay ?? 0) * sampleRate);
   const predelay =
     predelaySamples > 0 ? new Float64Array(predelaySamples) : undefined;
+  const wetL = new Float64Array(left.length);
+  const wetR = new Float64Array(left.length);
   for (let index = 0; index < left.length; index += 1) {
-    if (mixParam.automated && index % CONTROL_SAMPLES === 0)
-      wet = mixParam.at(index) * REVERB_WET_SCALE;
     let input = (left[index]! + right[index]!) * REVERB_INPUT_GAIN;
     if (inputFilter) input = inputFilter.process(input);
     if (predelay) {
@@ -277,12 +303,60 @@ export function applyReverb(
       predelay[slot] = input;
       input = delayed;
     }
+    wetL[index] = process(sides[0], input);
+    wetR[index] = process(sides[1], input);
+  }
+  return { left: wetL, right: wetR };
+}
+
+/**
+ * Add (or with `wetOnly`, write) a tail from `reverbWet` at the track's
+ * mix and mix lane, in the order the one-pass reverb always used, so a
+ * cached tail mixes to the same samples.
+ */
+export function addReverbWet(
+  left: Float64Array,
+  right: Float64Array,
+  tail: ReverbWet,
+  track: Track,
+  context: EffectContext,
+  wetOnly = false,
+): void {
+  const mixParam = mixParamOf(track, context);
+  if (tail.scale !== undefined) {
+    if (wetOnly) {
+      left.fill(0);
+      right.fill(0);
+    }
+    if (tail.scale === 0) return;
+    let wet = mixParam.fallback * IR_WET_SCALE;
+    addConvolved(
+      tail.left,
+      tail.right,
+      tail.scale,
+      left,
+      right,
+      wet,
+      mixParam.automated
+        ? (index) => {
+            if (index % CONTROL_SAMPLES === 0)
+              wet = mixParam.at(index) * IR_WET_SCALE;
+            return wet;
+          }
+        : undefined,
+    );
+    return;
+  }
+  let wet = mixParam.fallback * REVERB_WET_SCALE;
+  for (let index = 0; index < left.length; index += 1) {
+    if (mixParam.automated && index % CONTROL_SAMPLES === 0)
+      wet = mixParam.at(index) * REVERB_WET_SCALE;
     if (wetOnly) {
-      left[index] = process(sides[0], input) * wet;
-      right[index] = process(sides[1], input) * wet;
+      left[index] = tail.left[index]! * wet;
+      right[index] = tail.right[index]! * wet;
     } else {
-      left[index]! += process(sides[0], input) * wet;
-      right[index]! += process(sides[1], input) * wet;
+      left[index]! += tail.left[index]! * wet;
+      right[index]! += tail.right[index]! * wet;
     }
   }
 }
@@ -293,15 +367,13 @@ export function applyReverb(
  * `size`, `fade` and `dim` describe the algorithmic tail and do nothing
  * here: the impulse is the room.
  */
-function applyConvolutionReverb(
+function convolutionWet(
   left: Float64Array,
   right: Float64Array,
   track: Track,
   context: EffectContext,
   impulse: Impulse,
-  mixParam: Param,
-  wetOnly: boolean,
-): void {
+): ReverbWet {
   const reverb = track.reverb!;
   const { sampleRate } = context;
   const input = new Float64Array(left.length);
@@ -315,23 +387,8 @@ function applyConvolutionReverb(
     if (inputFilter) value = inputFilter.process(value);
     input[index + offset] = value;
   }
-  if (wetOnly) {
-    left.fill(0);
-    right.fill(0);
-  }
-  let wet = reverb.mix * IR_WET_SCALE;
-  convolveStereo(
-    input,
-    impulse,
-    left,
-    right,
-    wet,
-    mixParam.automated
-      ? (index) => {
-          if (index % CONTROL_SAMPLES === 0)
-            wet = mixParam.at(index) * IR_WET_SCALE;
-          return wet;
-        }
-      : undefined,
-  );
+  const wetL = new Float64Array(left.length);
+  const wetR = new Float64Array(left.length);
+  const scale = convolveRaw(input, impulse, wetL, wetR);
+  return { left: wetL, right: wetR, scale };
 }

package/src/audio/engine.ts

@@ -170,6 +170,17 @@ function parseCommand(value: string): string[] {
   return parts;
 }
 
+/**
+ * Swaps crossfade old to new over this window with equal-power gains
+ * (cos/sin), reading both loops at the same beat. 20 ms is long enough that
+ * the step a hard cut makes is spread below ~50 Hz (no click, even on a
+ * full-scale low bass), short enough to sit inside the transport's 30 ms
+ * resync tolerance and below the shortest audible echo (~30-50 ms), so an
+ * edit never sounds smeared or doubled. Playback only: renders, exports and
+ * the loop buffers themselves never pass through it.
+ */
+export const SWAP_FADE_SECONDS = 0.02;
+
 /** Swaps re-anchor to the transport only past this disagreement. */
 const RESYNC_SECONDS = 0.03;
 
@@ -228,6 +239,16 @@ type Loop = Readonly<{
   framesPerBeat: number;
 }>;
 
+/** A loop fading out after a swap, read on from where it was. */
+type FadeOut = {
+  loop: Loop;
+  cursor: number;
+  /** Its gain when the fade began (below 1 when swapped out mid-fade). */
+  from: number;
+  /** Frames of the fade already written. */
+  done: number;
+};
+
 /**
  * The click bus: the engine asks `beatAt` for the transport beat at a stream
  * frame's wall time (undefined while the transport is stopped; negative
@@ -293,6 +314,11 @@ export class AudioEngine {
   private child: PlayerProcess | undefined;
   private timer: ReturnType<typeof setInterval> | undefined;
   private loop: Loop | undefined;
+  /** Loops fading out after swaps (see `SWAP_FADE_SECONDS`). */
+  private fades: FadeOut[] = [];
+  /** Frames of the current loop's fade-in already written, while fading. */
+  private fadeIn: number | undefined;
+  private readonly fadeFrames: number;
   /** Monotonic ms that stream frame 0 belongs to. */
   private startMs = 0;
   /** Stream frames written since `startMs`. */
@@ -328,6 +354,10 @@ export class AudioEngine {
       ((options.leadMs ?? 200) * this.sampleRate) / 1000,
     );
     this.defaultLeadFrames = this.leadFrames;
+    this.fadeFrames = Math.max(
+      1,
+      Math.round(SWAP_FADE_SECONDS * this.sampleRate),
+    );
     this.tickMs = options.tickMs ?? 20;
     this.now = options.now ?? (() => performance.now());
     this.useTimer = options.timer ?? true;
@@ -603,6 +633,7 @@ export class AudioEngine {
     if (this.monitoring && this.child) {
       // Play mode: the transport stopped, the live player keeps running.
       this.loop = undefined;
+      this.endFades();
       return;
     }
     if (this.timer) clearInterval(this.timer);
@@ -610,6 +641,7 @@ export class AudioEngine {
     const child = this.child;
     this.child = undefined;
     this.loop = undefined;
+    this.endFades();
     if (child) {
       try {
         child.stdin.end?.();
@@ -646,6 +678,7 @@ export class AudioEngine {
     if (remaining > this.sampleRate) {
       const skipped = remaining - this.sampleRate;
       if (loop) this.cursor = (this.cursor + skipped) % loop.frames;
+      this.endFades();
       this.written += skipped;
       remaining = this.sampleRate;
     }
@@ -663,6 +696,7 @@ export class AudioEngine {
       offset += take;
       this.cursor = (this.cursor + take) % loop.frames;
     }
+    if (loop) this.crossfade(out, remaining);
     this.mixLive(out, this.written, remaining);
     this.written += remaining;
     try {
@@ -673,6 +707,49 @@ export class AudioEngine {
     }
   }
 
+  /** Equal-power gain of a fade-in `done` frames along (0 to 1). */
+  private rampGain(done: number): number {
+    return Math.sin((Math.PI / 2) * Math.min(1, done / this.fadeFrames));
+  }
+
+  /**
+   * Blend the start of a block (already the current loop) with the loops
+   * fading out: new·sin + old·cos over `fadeFrames`, both read at the same
+   * beat, so a swap never steps the waveform.
+   */
+  private crossfade(out: Int16Array, frames: number): void {
+    if (this.fadeIn === undefined) return;
+    const start = this.fadeIn;
+    const count = Math.min(frames, this.fadeFrames - start);
+    for (let index = 0; index < count; index += 1) {
+      const gain = this.rampGain(start + index);
+      const at = index * RENDER_CHANNELS;
+      let left = out[at]! * gain;
+      let right = out[at + 1]! * gain;
+      for (const fade of this.fades) {
+        if (fade.done >= this.fadeFrames) continue;
+        const g =
+          fade.from * Math.cos((Math.PI / 2) * (fade.done / this.fadeFrames));
+        const from = fade.cursor * RENDER_CHANNELS;
+        left += fade.loop.pcm[from]! * g;
+        right += fade.loop.pcm[from + 1]! * g;
+        fade.cursor = (fade.cursor + 1) % fade.loop.frames;
+        fade.done += 1;
+      }
+      out[at] = clamp16(left);
+      out[at + 1] = clamp16(right);
+    }
+    this.fadeIn = start + count;
+    // Older fades that began earlier finish before the newest fade-in does.
+    this.fades = this.fades.filter((fade) => fade.done < this.fadeFrames);
+    if (this.fadeIn >= this.fadeFrames) this.endFades();
+  }
+
+  private endFades(): void {
+    this.fades = [];
+    this.fadeIn = undefined;
+  }
+
   /** Wall time (monotonic ms) stream frame `frame` sounds at. */
   private frameMs(frame: number): number {
     return this.startMs + (frame * 1000) / this.sampleRate;
@@ -763,6 +840,13 @@ export class AudioEngine {
       if (!previous || wrapped > this.sampleRate * RESYNC_SECONDS)
         cursor = anchored;
     }
+    if (previous && this.child) {
+      // The outgoing loop keeps its current gain (below 1 when it was
+      // itself still fading in) and fades from there.
+      const from = this.fadeIn === undefined ? 1 : this.rampGain(this.fadeIn);
+      this.fades.push({ loop: previous, cursor: this.cursor, from, done: 0 });
+      this.fadeIn = 0;
+    }
     this.cursor = cursor;
     this.loop = next;
   }
@@ -784,6 +868,7 @@ export class AudioEngine {
     this.spawns += 1;
     this.child = child;
     this.loop = loop;
+    this.endFades();
     this.startMs = this.now();
     this.written = 0;
     this.cursor = loop ? this.frameForBeat(loop, beat) : 0;

package/src/audio/preview.ts

@@ -50,6 +50,12 @@ export type PreviewOptions = Readonly<{
   beat?: number;
   /** Overrides the region choice (tests, the agent tool). */
   region?: PreviewRegion;
+  /**
+   * Replaces the focused track's notes with this phrase (from tick 0 of the
+   * region). The chord settings screen plays a progression performed with
+   * the staged settings this way, so a voicing or arp change is audible.
+   */
+  phrase?: (score: TrackScore, track: Track, bars: number) => NoteInput[];
 }>;
 
 export type Preview = Readonly<{
@@ -288,17 +294,22 @@ export function previewScore(
         ...(context && anySolo ? { solo: true } : {}),
       };
     });
-  const own = score.notes.some((note) => note.trackId === trackId);
+  const replaced = options.phrase !== undefined;
+  const own = !replaced && score.notes.some((note) => note.trackId === trackId);
   const notes: NoteInput[] = score.notes
     .filter(
       (note) =>
         (context || note.trackId === trackId) &&
+        !(replaced && note.trackId === trackId) &&
         note.startTick >= start &&
         note.startTick < end,
     )
     .map((note) => ({ ...note, startTick: note.startTick - start }));
   let role: PhraseRole | undefined;
-  if (!own) {
+  if (options.phrase) {
+    role = "chord";
+    notes.push(...options.phrase(score, track, bars));
+  } else if (!own) {
     role = phraseRole(track);
     notes.push(...defaultPhrase(score, track, bars, role));
   }