@hraness/dawg 0.3.0 → 0.4.0

package/src/main.ts

@@ -30,15 +30,37 @@ import { AutoNamer, providerNameGenerator } from "./session/naming.ts";
 import { normalizeSessionName } from "./session/meta.ts";
 import { parsePrompt } from "./agent/ops.ts";
 import { applyMusicCommand, parseMusicCommand } from "./commands/music.ts";
+import { applyRhythmCommand, parseRhythmCommand } from "./commands/rhythm.ts";
+import {
+  applyDrumPattern,
+  applySynthKit,
+  DRUM_PATTERNS,
+  isSynthKitName,
+  parsePatternCommand,
+  patternLine,
+  type PatternCommand,
+} from "./commands/drums.ts";
+import { kitCatalog } from "./audio/kits.ts";
 import { applyEditCommand, parseEditCommand } from "./commands/edit.ts";
-import { helpLines, helpText, usageHint } from "./commands/help.ts";
+import { applyFxCommand, parseFxCommand } from "./commands/fx.ts";
+import { applySynthCommand, parseSynthCommand } from "./commands/synth.ts";
+import {
+  HELP_TOPICS,
+  helpText,
+  helpTopicLines,
+  nearestCommand,
+  typoFix,
+  usageHint,
+} from "./commands/help.ts";
 import { historyTarget, REDO_KIND, UNDO_KIND } from "./commands/history.ts";
+
 import {
   SamplePlacementError,
   addSampleVoice,
   freeVoiceName,
   listSampleVoices,
   parseSampleCommand,
+  setSampleControls,
   placeSampleFile,
   samplerTarget,
   voiceNameFrom,
@@ -89,19 +111,60 @@ import { AudioEngine } from "./audio/engine.ts";
 import {
   DEFAULT_GRID,
   GRIDS,
+  PLAY_LEAD_MS,
   PlaySession,
   type LiveEngine,
 } from "./tui/play-session.ts";
 import { EditMenu, MENU_SECTIONS, type MenuContext } from "./tui/menu.ts";
+import { Audition, SUPERSEDED, isStageable } from "./tui/audition.ts";
+import { EuclidEditor } from "./tui/euclid.ts";
+import { HINTS, KEYS, keyLines, type KeySection } from "../tui/grammar.ts";
+import { renderAudition } from "./audio/audition.ts";
+import { renderScorePcm } from "./audio/wav.ts";
+import type { PreviewHost } from "./agent/preview-tool.ts";
+import { rhythmVoicePitch } from "../core/rhythm.ts";
+import { applyChordsCommand, defaultChordSettings } from "./tui/play-chords.ts";
+import {
+  cacheLines,
+  kitListLines,
+  kitTarget,
+  packListLines,
+  parseKitCommand,
+  parsePackCommand,
+  useKit,
+  useSound,
+  type KitCommand,
+  type PackCommand,
+} from "./commands/pack.ts";
+import {
+  describeWavetable,
+  parseWavetableCommand,
+  pickWavetable,
+  wavetableListLines,
+  wavetableParamEdit,
+  type WavetableCommand,
+} from "./commands/wavetable.ts";
+import {
+  ALIASED_PACK,
+  DEFAULT_KITS,
+  PackError,
+  PackStore,
+  banksOf,
+  packCredits,
+  writeCredits,
+} from "./audio/packs.ts";
 import {
   addNote,
   applyScoreOperation,
   createScore,
+  PACK_PREFIX,
   scoreFromJSON,
   SCORE_LIMITS,
+  type SampleRef,
   type TrackScore,
   type ScoreOperation,
 } from "../core/score.ts";
+import { reconcileRhythm } from "../core/rhythm.ts";
 import { decodeLoop, encodeLoop } from "../core/loop.ts";
 import type { TrackScoreSnapshot } from "../tui/render.ts";
 import { PromptModel } from "../tui/prompt.ts";
@@ -127,6 +190,23 @@ import {
   type SyncHost,
 } from "./project/sync.ts";
 
+/** Whether a bare command parses (no side effects): for typo suggestions. */
+function parsesLocally(text: string): boolean {
+  return [
+    parsePrompt,
+    parseMusicCommand,
+    parseEditCommand,
+    parseRhythmCommand,
+    parseFxCommand,
+    parseSynthCommand,
+    parsePatternCommand,
+    parseKitCommand,
+    parsePackCommand,
+    parseSampleCommand,
+    parseWavetableCommand,
+  ].some((parse) => parse(text) !== undefined);
+}
+
 const ESC = "\u001b[";
 /** `/sessions` rows shown in the overlay. */
 const MAX_LISTED_SESSIONS = 64;
@@ -351,6 +431,9 @@ let syncState: SyncState = port.sync;
 let windowCount = 1;
 /** Project file sync when `dawg.json` is in the working directory. */
 let projectSync: ProjectSync | undefined;
+let packStore: PackStore | undefined;
+let reportedSampleProblems = "";
+let sampleLibrary: SampleLibrary | undefined;
 let typesIndicator: TypesIndicator | undefined;
 let announcedName = record.meta.name;
 let namer = makeNamer();
@@ -358,10 +441,37 @@ let namer = makeNamer();
 let rebindPort: () => void = () => undefined;
 /** Play mode's controller; kept across entries so settings persist. */
 let play: PlaySession | undefined;
+/** Chord-mode settings, shared by every track's play session. */
+const chordSettings = defaultChordSettings();
 /** The hand-editing menu (`/menu`, Ctrl-K), drawn as the picker overlay. */
 const menu = new EditMenu();
+/** The Euclidean rhythm editor (`/euclid`, Rhythm in `/menu`). */
+const euclid = new EuclidEditor();
+/** Live voice id for auditions (play-mode voices use small positive ids). */
+const AUDITION_VOICE = 0x7fff_0001;
+/** A voice to audition once the editor's queued command lands. */
+let pendingAudition: string | undefined;
+/** The pattern the /pattern picker last previewed. */
+let patternPreview: string | undefined;
 /** Daemon windows play no loop; play mode monitors through its own engine. */
 let monitorEngine: AudioEngine | undefined;
+/** The audition loop and staged edits (src/tui/audition.ts), made lazily. */
+let auditionLoop: Audition | undefined;
+/** Pickers that host the audition loop (Space, `a`, `c`, hover). */
+const AUDITION_PICKERS = new Set(["kit", "pattern", "try"]);
+const TRY_USAGE =
+  "/try <sound command> · /try fx reverb mix 0.6 · /try agent on|off";
+/** Whether the agent's preview_sound plays its snippet in this window. */
+let agentPreviewPlays = process.env.DAWG_AGENT_PREVIEW !== "off";
+const AGENT_PREVIEW_VOICE = 0x7fff_0002;
+/**
+ * Set while a staged command runs: `commitScore` hands its result here
+ * instead of appending, and a remote revision that lands meanwhile waits in
+ * `committed` (the window's `score` is the staged base until it finishes).
+ */
+let stageCapture: { next?: TrackScore; committed?: TrackScore } | undefined;
+/** Redraw soon (the audition reports renders between frames). */
+let requestFrame: () => void = () => undefined;
 /** The decoded sampler voices, for play mode's live voices. */
 let liveSampleBank: SampleBank | undefined;
 /** The in-flight agent turn: Esc aborts it, Enter steers it. */
@@ -698,6 +808,11 @@ async function runInteractive(): Promise<void> {
         const nextPrompt = queuedPrompts.shift()!;
         tui.activity.setQueueDepth(queuedPrompts.length);
         await runPrompt(nextPrompt);
+        if (pendingAudition && queuedPrompts.length === 0) {
+          const voice = pendingAudition;
+          pendingAudition = undefined;
+          audition(voice);
+        }
         tick(true);
       }
     } finally {
@@ -707,11 +822,15 @@ async function runInteractive(): Promise<void> {
   };
   const tick = (force = false) => {
     if (screenSuspended) return;
+    followCommitted();
     play?.tick();
     // Values in the menu follow the score as edits land.
     if (menu.open) refreshMenu();
+    if (euclid.open) refreshEuclid();
+    refreshAuditionPicker();
     tui.render(appView(score, clock.beatAt()), { force });
   };
+  requestFrame = () => tick(true);
   reportAgentActivity = () => {
     tui.activity.applyAgentEvent({ type: "start", model: providerName });
   };
@@ -735,7 +854,9 @@ async function runInteractive(): Promise<void> {
       if (latest.revision > record.revision) {
         const previousRevision = record.revision;
         record = latest;
-        score = scoreFromJSON(record.composition);
+        if (stageCapture)
+          stageCapture.committed = scoreFromJSON(record.composition);
+        else score = scoreFromJSON(record.composition);
         clock.setTempo(score.tempoBpm);
         if (clock.playing) void audio.play(score);
         // Connected windows follow dawgd's transport frames instead.
@@ -889,17 +1010,72 @@ async function runInteractive(): Promise<void> {
         ...(text === "\u001b" ? inputDecoder.flush() : []),
       ];
       for (const value of values) {
+        // The `?` panel closes on any key (Ctrl-C still quits).
+        if (tui.ui.keys && typeof value === "string" && value !== "\u0003") {
+          tui.closeKeys();
+          tick(true);
+          continue;
+        }
+        if (value === "?" && keysScreen()) {
+          showKeys();
+          tick(true);
+          continue;
+        }
+        // The rhythm editor owns every key while it is up (Esc backs out).
+        if (typeof value === "string" && euclid.open) {
+          if (tui.ui.overlay !== "picker" || tui.ui.picker?.id !== "euclid")
+            euclid.close();
+          else {
+            const result = euclid.key(value, euclidContext());
+            if (result.type === "close") {
+              const back = euclid.returnTo;
+              euclid.close();
+              tui.closePicker();
+              if (back === "menu") openMenu();
+            } else if (result.type === "run") {
+              queuedPrompts.unshift(result.command);
+              if (result.audition) pendingAudition = result.audition;
+              void drainQueue();
+            } else if (result.type === "audition") audition(result.voice);
+            if (result.type !== "pass") {
+              refreshEuclid();
+              tick(true);
+              continue;
+            }
+          }
+        }
         // The edit menu owns every key while it is up (Esc backs out).
         if (typeof value === "string" && menu.open) {
           if (tui.ui.overlay !== "picker" || tui.ui.picker?.id !== "menu")
             menu.close();
           else {
             const result = menu.key(value, menuContext());
-            if (result.type === "close") tui.closePicker();
-            else if (result.type === "run") {
-              queuedPrompts.unshift(result.command);
-              void drainQueue();
-            }
+            if (result.type === "close") {
+              tui.closePicker();
+              leaveAuditionScreen();
+            } else if (result.type === "run") {
+              if (!stageIfAuditioning(result.command)) {
+                queuedPrompts.unshift(result.command);
+                void drainQueue();
+              }
+            } else if (result.type === "audition")
+              auditionKeyPressed(result.key);
+            else if (result.type === "revert") revertStaged();
+            else if (result.type === "hover")
+              hoverItem(result.command, result.key);
+            else if (result.type === "unhover")
+              void auditionLoop
+                ?.unhover(result.key)
+                .finally(() => requestFrame());
+            else if (result.type === "choose")
+              chooseItem(result.command, result.key);
+            else if (result.type === "keep")
+              void keepStaged()
+                .then((outcome) => receipt(outcome))
+                .catch((error) =>
+                  tui.activity.pushError(describeError("keep", error)),
+                )
+                .finally(() => tick(true));
             if (result.type !== "pass") {
               refreshMenu();
               tick(true);
@@ -935,7 +1111,11 @@ async function runInteractive(): Promise<void> {
         // shell exit key; Ctrl-Q is reserved for prompt mode switching.
         // Keep the empty-prompt space shortcut for transport, while allowing
         // ordinary spaces once a request is being composed.
-        if (value === " " && prompt.value.length === 0) {
+        if (
+          value === " " &&
+          prompt.value.length === 0 &&
+          !(tui.ui.overlay === "picker" && tui.ui.picker?.audition)
+        ) {
           // Never await a daemon round trip here: the key loop must stay
           // live for Esc, quit and redraws while the toggle is in flight.
           void toggleTransport()
@@ -967,6 +1147,52 @@ async function runInteractive(): Promise<void> {
                 })
                 .finally(() => tick(true));
             }
+          } else if (input.type === "pick-move") {
+            // Moving through a list auditions the row under the cursor on
+            // the loop; with the loop off, /pattern plays one bar of it.
+            if (auditionLoop?.looping && isStageable(input.value))
+              hoverItem(input.value, `picker:${input.picker}`);
+            else if (input.picker === "pattern")
+              previewPattern(input.value.replace(/^\/pattern\s+/, ""));
+          } else if (input.type === "pick-audition") {
+            pickerAuditionKey(input.key);
+          } else if (input.type === "pick-cancel") {
+            if (AUDITION_PICKERS.has(input.picker)) leaveAuditionScreen();
+          } else if (input.type === "pick" && input.picker === "try") {
+            if (input.value === "keep")
+              void keepStaged()
+                .then((outcome) => receipt(outcome))
+                .catch((error) =>
+                  tui.activity.pushError(describeError("keep", error)),
+                )
+                .finally(() => {
+                  stopAuditionLoop();
+                  tick(true);
+                });
+            else leaveAuditionScreen();
+          } else if (
+            input.type === "pick" &&
+            AUDITION_PICKERS.has(input.picker) &&
+            auditionLoop?.staging
+          ) {
+            // Enter in an auditioning list keeps what you hear.
+            const loop = auditionLoop;
+            const key = `picker:${input.picker}`;
+            void (
+              isStageable(input.value)
+                ? loop.hover(input.value, key)
+                : Promise.resolve()
+            )
+              .then(() => loop.settle(key))
+              .then(() => keepStaged())
+              .then((outcome) => receipt(outcome))
+              .catch((error) =>
+                tui.activity.pushError(describeError("keep", error)),
+              )
+              .finally(() => {
+                stopAuditionLoop();
+                tick(true);
+              });
           } else if (input.type === "pick") {
             // Picker choices run as the command they stand for.
             queuedPrompts.unshift(
@@ -1023,11 +1249,34 @@ async function runInteractive(): Promise<void> {
   }
 }
 
+/** `unknown command /clik · did you mean /click? · /help`. */
+function unknownCommand(command: string): string {
+  const word = command.split(/\s+/)[0] ?? command;
+  const near = nearestCommand(command);
+  return near
+    ? `unknown command ${word} · did you mean ${near}? · /help`
+    : `unknown command ${word} · /help`;
+}
+
 async function submit(prompt: string): Promise<string | Receipt> {
   const command = prompt.trim();
-  if (/^\/?help$|^\/?\?$/.test(command.toLowerCase())) {
-    tui.openText("help", helpLines(Math.max(40, (stdout.columns ?? 80) - 8)));
-    return ok("help · esc closes");
+  const helpCommand = command.match(/^\/?(?:help|\?)(?:\s+(\S+))?$/i);
+  if (helpCommand) {
+    const topic = helpCommand[1];
+    const lines = helpTopicLines(
+      topic,
+      Math.max(40, (stdout.columns ?? 80) - 10),
+    );
+    if (!lines)
+      return fail(
+        `no help topic ${topic} · /help all · ${HELP_TOPICS.join(" ")}`,
+      );
+    tui.openText(topic ? `help · ${topic.toLowerCase()}` : "help", lines);
+    return ok(
+      topic
+        ? `help · ${topic.toLowerCase()}`
+        : "help · /help all for every command",
+    );
   }
   if (/^\/?tracks$/i.test(command)) {
     const problems = await sampleProblems(score);
@@ -1044,9 +1293,7 @@ async function submit(prompt: string): Promise<string | Receipt> {
       return `${track.id === requestedTrack ? "*" : " "} ${track.id} · ${track.instrument}${samples}${track.muted ? " · muted" : ""}${track.solo ? " · solo" : ""}`;
     });
     tui.openText("tracks · * focused", lines);
-    return ok(
-      `${lines.length} track${lines.length === 1 ? "" : "s"} · esc closes`,
-    );
+    return ok(`${lines.length} track${lines.length === 1 ? "" : "s"}`);
   }
   const playCommand = command.match(/^\/play(?:\s+(on|off))?$/i);
   if (playCommand) {
@@ -1062,15 +1309,32 @@ async function submit(prompt: string): Promise<string | Receipt> {
       ? fail(message)
       : ok(message);
   }
+  const chordsCommand = command.match(/^\/chords(?:\s+(.+))?$/i);
+  if (chordsCommand) {
+    const result = applyChordsCommand(chordSettings, chordsCommand[1] ?? "");
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const countIn = command.match(/^\/count-?in\s+([0-2])$/i);
   if (countIn) return ok(playSession().setCountIn(Number(countIn[1])));
+  const euclidCommand = command.match(/^\/euclid(?:\s+(\S+))?$/i);
+  if (euclidCommand) {
+    const from = menu.open ? "menu" : undefined;
+    if (menu.open) {
+      menu.close();
+      tui.closePicker();
+    }
+    openEuclid(euclidCommand[1]?.toLowerCase(), from);
+    return ok("rhythm editor");
+  }
+  const tryCommand = command.match(/^\/try(?:\s+(.+))?$/i);
+  if (tryCommand) return tryPrompt(tryCommand[1]?.trim() ?? "");
   const menuCommand = command.match(/^\/menu(?:\s+(\S+))?$/i);
   if (menuCommand) {
     const section = menuCommand[1]?.toLowerCase();
     if (section && !(MENU_SECTIONS as readonly string[]).includes(section))
       return fail(`/menu [${MENU_SECTIONS.join("|")}]`);
     openMenu(section);
-    return ok("menu · esc closes");
+    return ok("menu");
   }
   const gridCommand = command.match(/^\/grid\s+(\S+)$/i);
   if (gridCommand) {
@@ -1091,6 +1355,14 @@ async function submit(prompt: string): Promise<string | Receipt> {
   if (trackCommand) return focusTrack(trackCommand[1]!.toLowerCase());
   const sample = parseSampleCommand(command);
   if (sample) return sampleCommand(sample);
+  const pack = parsePackCommand(command);
+  if (pack) return packCommand(pack);
+  const pattern = parsePatternCommand(command);
+  if (pattern) return patternCommand(pattern);
+  const kit = parseKitCommand(command);
+  if (kit) return kitCommand(kit, /^\/kit\s*$/i.test(command.trim()));
+  const wavetable = parseWavetableCommand(command);
+  if (wavetable) return wavetableCommand(wavetable);
   const sessionReply = await sessionCommand(command);
   if (sessionReply !== undefined) return sessionReply;
   const edit = parseEditCommand(command);
@@ -1101,6 +1373,41 @@ async function submit(prompt: string): Promise<string | Receipt> {
       await commitScore(result.next, result.kind, result.payload);
     return result.ok ? ok(result.message) : fail(result.message);
   }
+  const rhythm = parseRhythmCommand(command);
+  if (rhythm) {
+    await materializeDraft();
+    const result = applyRhythmCommand(score, requestedTrack, rhythm);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const fx = parseFxCommand(command);
+  if (fx) {
+    if (fx.type !== "fx-list") await materializeDraft();
+    // A pack impulse is pinned (sha256 + url) once, as wavetable tables are.
+    let pinnedIr: SampleRef | undefined;
+    if (fx.type === "fx-ir" && fx.ir?.startsWith(PACK_PREFIX)) {
+      try {
+        pinnedIr = await packs().pin(fx.ir);
+      } catch (error) {
+        if (error instanceof PackError)
+          return fail(`reverb ir · ${error.message}`);
+        throw error;
+      }
+    }
+    const result = applyFxCommand(score, requestedTrack, fx, pinnedIr);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const synth = parseSynthCommand(command);
+  if (synth) {
+    if (synth.type !== "synth-list") await materializeDraft();
+    const result = applySynthCommand(score, requestedTrack, synth);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const music = parseMusicCommand(command);
   if (music) {
     await materializeDraft();
@@ -1188,9 +1495,7 @@ async function submit(prompt: string): Promise<string | Receipt> {
   if (command.startsWith("/") && !/^\/model\b/i.test(command)) {
     const hint = usageHint(command);
     return fail(
-      hint
-        ? `${truncateForCard(command)} · ${hint}`
-        : `unknown command ${command.split(/\s+/)[0]} · /help`,
+      hint ? `${truncateForCard(command)} · ${hint}` : unknownCommand(command),
     );
   }
   const parsed = parsePrompt(prompt);
@@ -1198,6 +1503,9 @@ async function submit(prompt: string): Promise<string | Receipt> {
     // A known verb with bad arguments gets usage, not a model call.
     const hint = usageHint(command);
     if (hint) return fail(`${truncateForCard(command)} · ${hint}`);
+    // A one-letter slip on a command whose arguments parse stays local.
+    const fix = typoFix(command, parsesLocally);
+    if (fix) return fail(`${truncateForCard(command)} · did you mean ${fix}?`);
     if (process.env.DAWG_AI === "0")
       return fail(`unrecognized · ${truncateForCard(command)} · /help`);
     await materializeDraft();
@@ -1405,15 +1713,15 @@ async function focusTrack(trackId: string): Promise<Receipt> {
   return ok(exists ? `track · ${trackId}` : `track created · ${trackId}`);
 }
 
-let sampleLibrary: SampleLibrary | undefined;
-let reportedSampleProblems = "";
-
 /** Decode every sampler voice (cached) and return what failed to load. */
 async function sampleProblems(
   value: TrackScore,
 ): Promise<readonly SampleProblem[]> {
   if (!hasSamplerTracks(value)) return [];
-  sampleLibrary ??= new SampleLibrary({ projectRoot: process.cwd() });
+  sampleLibrary ??= new SampleLibrary({
+    projectRoot: process.cwd(),
+    packs: packs(),
+  });
   try {
     const bank = await sampleLibrary.load(value);
     liveSampleBank = bank;
@@ -1465,9 +1773,22 @@ async function sampleCommand(
         `sample · ${requestedTrack} has no samples · /sample <path> [as <voice>]`,
       );
     tui.openText(`samples · ${requestedTrack}`, lines);
-    return ok(
-      `${lines.length} sample${lines.length === 1 ? "" : "s"} · esc closes`,
+    return ok(`${lines.length} sample${lines.length === 1 ? "" : "s"}`);
+  }
+  if (command.kind === "set") {
+    const result = setSampleControls(
+      score,
+      requestedTrack,
+      command.voice,
+      command.values,
     );
+    if (!result.ok) return fail(result.message);
+    await commitScore(result.next, "sample.set", {
+      trackId: requestedTrack,
+      voice: command.voice,
+    });
+    await projectSync?.flushScore();
+    return ok(result.message);
   }
   await materializeDraft();
   const trackId = samplerTarget(score, requestedTrack);
@@ -1515,6 +1836,326 @@ async function sampleCommand(
   );
 }
 
+function packs(): PackStore {
+  packStore ??= new PackStore();
+  return packStore;
+}
+
+/** Keeps CREDITS.md in step with the CC-BY packs the score uses (quietly). */
+async function updateCredits(value: TrackScore): Promise<void> {
+  const refs = value.tracks.flatMap((track) =>
+    Object.values(track.sampler?.voices ?? {}),
+  );
+  if (!refs.some((ref) => ref.src.startsWith("pack:"))) return;
+  // Only a dawg project gets CREDITS.md; a bare session directory does not.
+  if (!projectSync) return;
+  try {
+    await writeCredits(process.cwd(), packCredits(refs, await packs().list()));
+  } catch {
+    /* credits are best effort; render metadata carries them too */
+  }
+}
+
+/** Applies a pack edit as one undo step and focuses its track. */
+async function commitPackEdit(
+  operations: readonly ScoreOperation[],
+  trackId: string,
+  kind: string,
+  payload: Record<string, unknown>,
+): Promise<Receipt | undefined> {
+  let next = score;
+  for (const operation of operations)
+    next = applyScoreOperation(next, operation);
+  const problems = (await sampleProblems(next)).filter(
+    (problem) => problem.trackId === trackId && problem.level === "error",
+  );
+  if (problems.length > 0) return fail(`sound · ${problems[0]!.message}`);
+  await commitScore(next, kind, payload);
+  if (stageCapture) return undefined;
+  if (trackId !== requestedTrack) {
+    await port.focus(trackId);
+    requestedTrack = trackId;
+    draftTrack = false;
+  }
+  await projectSync?.flushScore();
+  return undefined;
+}
+
+async function packCommand(command: PackCommand): Promise<Receipt> {
+  try {
+    if (command.kind === "usage") return warn(command.message);
+    if (command.kind === "list") {
+      const lines = packListLines(await packs().list());
+      tui.openText("packs", lines);
+      return ok(`${lines.length} packs · /pack info <name>`);
+    }
+    if (command.kind === "cache") {
+      const library = (sampleLibrary ??= new SampleLibrary({
+        projectRoot: process.cwd(),
+        packs: packs(),
+      }));
+      let freed: { files: number; bytes: number } | undefined;
+      if (command.pruneTo !== undefined) {
+        const to = (cap: number) =>
+          command.pruneTo === "cap" ? cap : (command.pruneTo as number);
+        const store = packs();
+        const a = await store.pruneCache(to(store.maxFileCacheBytes));
+        const b = await library.pruneCache(to(library.maxCacheBytes));
+        freed = { files: a.removed + b.removed, bytes: a.freed + b.freed };
+      }
+      const lines = cacheLines({
+        packs: await packs().cacheStatus(),
+        assets: await library.cacheStatus(),
+        ...(freed ? { freed } : {}),
+      });
+      tui.openText("cache", lines);
+      return ok(lines[0]!);
+    }
+    if (command.kind === "add") {
+      const added = await packs().add(
+        command.source,
+        command.name ? { name: command.name } : {},
+      );
+      return ok(
+        `pack added · ${added.pack.name} · ${added.sounds} sounds · /pack info ${added.pack.name}`,
+      );
+    }
+    if (command.kind === "info") {
+      const info = await packs().info(command.name);
+      if (!info)
+        return fail(
+          `pack · no pack named ${command.name.slice(0, 40)} · /pack list`,
+        );
+      const manifest = await packs().manifest(info.name);
+      const banks = banksOf(manifest);
+      const names = [...manifest.sounds.keys()];
+      const lines = [
+        `${info.name} · ${info.title}`,
+        `license · ${info.license}${info.attribution ? ` · ${info.attribution}` : ""}`,
+        `manifest · ${info.manifestUrl}`,
+        ...(info.homepage ? [`home · ${info.homepage}`] : []),
+        `${names.length} sounds${banks.length ? ` · ${banks.length} kits` : ""}`,
+        ...(banks.length ? [`kits · ${banks.join(" ")}`] : []),
+        ...names.slice(0, 400).map((name) => {
+          const sound = manifest.sounds.get(name)!;
+          return `${name} · ${sound.kind === "zones" ? `${sound.zones.length} notes (keyed)` : `${sound.files.length} file${sound.files.length === 1 ? "" : "s"}`}`;
+        }),
+      ];
+      tui.openText(`pack · ${info.name}`, lines);
+      return ok(
+        `${info.name} · ${names.length} sounds · /pack use ${info.name}/<sound>`,
+      );
+    }
+    if (command.kind === "remove") {
+      const known = await packs().remove(command.name);
+      return known
+        ? ok(`pack removed · ${command.name}`)
+        : fail(
+            `pack · no pack named ${command.name.slice(0, 40)} · /pack list`,
+          );
+    }
+    await materializeDraft();
+    const result = await useSound(
+      packs(),
+      score,
+      requestedTrack,
+      command.sound,
+      {
+        ...(command.voice ? { voice: command.voice } : {}),
+      },
+    );
+    const failed = await commitPackEdit(
+      result.operations,
+      result.trackId,
+      "pack.use",
+      {
+        trackId: result.trackId,
+        sound: command.sound,
+      },
+    );
+    return failed ?? ok(`sound · ${result.summary}`);
+  } catch (error) {
+    if (error instanceof PackError) return fail(`pack · ${error.message}`);
+    throw error;
+  }
+}
+
+async function patternCommand(command: PatternCommand): Promise<Receipt> {
+  if (command.kind === "list") {
+    tui.openText("patterns", DRUM_PATTERNS.map(patternLine));
+    return ok(`patterns · ${DRUM_PATTERNS.length} · /pattern <name>`);
+  }
+  if (command.kind === "browse") {
+    tui.openPicker({
+      id: "pattern",
+      title: "drum patterns",
+      hint: HINTS.audition,
+      audition: true,
+      items: DRUM_PATTERNS.map((entry) => ({
+        label: `${entry.label.padEnd(22)} ${entry.tempo.bpm} BPM · ${entry.tags.join(", ")}`,
+        value: `/pattern ${entry.name}`,
+      })),
+      filterable: true,
+      index: 0,
+    });
+    patternPreview = undefined;
+    previewPattern(DRUM_PATTERNS[0]?.name);
+    return ok("patterns · ↑/↓ preview · Enter applies on the focused track");
+  }
+  await materializeDraft();
+  const result = applyDrumPattern(
+    score,
+    requestedTrack,
+    command.name,
+    command.tempo,
+  );
+  if (result.next && result.kind)
+    await commitScore(result.next, result.kind, result.payload);
+  return result.ok ? ok(result.message) : fail(result.message);
+}
+
+/**
+ * Play one bar of the pattern under the picker cursor, on a scratch copy
+ * of the focused track (or a fresh kit track when the focus is melodic).
+ * Silent while the loop plays, like the Euclidean editor's audition.
+ */
+function previewPattern(name: string | undefined): void {
+  if (!name || name === patternPreview) return;
+  patternPreview = name;
+  if (clock.playing) return;
+  const entry = DRUM_PATTERNS.find((candidate) => candidate.name === name);
+  if (!entry) return;
+  let result = applyDrumPattern(score, requestedTrack, entry.name, "set");
+  let trackId = requestedTrack;
+  if (!result.next) {
+    trackId = "pattern-preview";
+    result = applyDrumPattern(score, trackId, entry.name, "set");
+  }
+  if (!result.next) return;
+  const engine = liveEngine();
+  if (!engine?.canMonitor) return;
+  const pcm = renderAudition({
+    score: result.next,
+    trackId,
+    bars: 1,
+    sampleRate: engine.sampleRate,
+    ...(liveSampleBank ? { samples: liveSampleBank } : {}),
+  });
+  if (!pcm) return;
+  void engine
+    .monitor(true)
+    .then(() => engine.noteOn(AUDITION_VOICE, pcm))
+    .catch(() => undefined);
+}
+
+/** `/kit` with no name: one picker with the synth kits and the sample kits. */
+function openKitPicker(): Receipt {
+  const current = score.tracks.find((track) => track.id === requestedTrack);
+  const items = kitCatalog().map((entry) => ({
+    label: `${entry.kind === "synth" ? "synth " : "sample"}  ${entry.label.padEnd(18)} ${entry.detail}`,
+    value: entry.command,
+    current:
+      entry.kind === "synth" &&
+      isDrumInstrumentTrack(current) &&
+      (current?.kit ?? "default") === entry.name,
+  }));
+  tui.openPicker({
+    id: "kit",
+    title: "drum kits",
+    hint: HINTS.audition,
+    audition: true,
+    items,
+    filterable: true,
+    index: Math.max(
+      0,
+      items.findIndex((item) => item.current),
+    ),
+  });
+  return ok("kits · synth kits work offline · sample kits are fetched once");
+}
+
+function isDrumInstrumentTrack(track: { instrument: string } | undefined) {
+  return track !== undefined && isDrumInstrument(track.instrument);
+}
+
+async function kitCommand(command: KitCommand, bare = false): Promise<Receipt> {
+  if (bare) return openKitPicker();
+  if (command.kind === "set" && isSynthKitName(command.bank)) {
+    await materializeDraft();
+    const result = applySynthKit(score, requestedTrack, command.bank);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  if (command.kind === "list") {
+    const lines = kitCatalog()
+      .filter((entry) => entry.kind === "synth")
+      .map((entry) => `${entry.name} · synth · ${entry.detail}`);
+    lines.push(...kitListLines(await packs().bankAliases(ALIASED_PACK)));
+    tui.openText("kits", lines);
+    return ok("kits · /kit <name or nickname> on the focused drum track");
+  }
+  await materializeDraft();
+  const trackId = kitTarget(score, requestedTrack);
+  if (!trackId)
+    return fail(
+      `kit · ${requestedTrack} is a melodic track · focus a drum track (/track drums) and retry`,
+    );
+  try {
+    const result = await useKit(packs(), score, trackId, command.bank);
+    const failed = await commitPackEdit(
+      result.operations,
+      trackId,
+      "pack.kit",
+      {
+        trackId,
+        bank: command.bank,
+      },
+    );
+    return failed ?? ok(result.summary);
+  } catch (error) {
+    if (error instanceof PackError) return fail(`kit · ${error.message}`);
+    throw error;
+  }
+}
+
+async function wavetableCommand(command: WavetableCommand): Promise<Receipt> {
+  if (command.kind === "usage") return warn(command.message);
+  if (command.kind === "show")
+    return ok(describeWavetable(score, requestedTrack));
+  if (command.kind === "list") {
+    tui.openText(
+      "wavetables",
+      await wavetableListLines(packs(), process.cwd()),
+    );
+    return ok("wavetables · wt <table> sets the focused track");
+  }
+  await materializeDraft();
+  const trackId = requestedTrack;
+  try {
+    const edit =
+      command.kind === "table"
+        ? await pickWavetable(
+            packs(),
+            score,
+            trackId,
+            command.table,
+            process.cwd(),
+          )
+        : wavetableParamEdit(score, trackId, command);
+    const failed = await commitPackEdit(
+      [edit.operation],
+      trackId,
+      "track.wavetable",
+      { trackId, ...command },
+    );
+    return failed ?? ok(edit.summary);
+  } catch (error) {
+    if (error instanceof PackError) return fail(`wavetable · ${error.message}`);
+    throw error;
+  }
+}
+
 async function readLoopFile(path: string): Promise<string> {
   const contents = await readFile(resolve(path));
   if (contents.byteLength > 512 * 1024)
@@ -1627,7 +2268,7 @@ async function sessionCommand(
     );
     tui.openPicker({
       id: "resume",
-      title: "resume session · ↑/↓ Enter · Esc",
+      title: "resume a session",
       items: readable.map((session) => ({
         label: `${session.sessionId === record.sessionId ? "* " : "  "}${formatSessionLine(session, sessions)}`,
         value: session.sessionId,
@@ -1644,9 +2285,7 @@ async function sessionCommand(
       MAX_LISTED_SESSIONS,
     );
     tui.openText("sessions · * current · /resume <n>", lines);
-    return ok(
-      `${lines.length} session${lines.length === 1 ? "" : "s"} · esc closes`,
-    );
+    return ok(`${lines.length} session${lines.length === 1 ? "" : "s"}`);
   }
   if (agentTurn) return warn("agent busy · finish or Esc first");
   if (verb === "fork") {
@@ -1707,6 +2346,11 @@ async function switchSession(sessionId: string): Promise<void> {
 }
 
 function liveEngine(): LiveEngine | undefined {
+  return previewEngine();
+}
+
+/** The engine this window hears itself through (its own in daemon mode). */
+function previewEngine(): AudioEngine {
   if (audio instanceof AudioEngine) return audio;
   monitorEngine ??= new AudioEngine({ projectRoot: process.cwd() });
   return monitorEngine;
@@ -1715,27 +2359,424 @@ function liveEngine(): LiveEngine | undefined {
 /** The play session for the focused track (re-made when focus moves). */
 function menuContext(): MenuContext {
   const session = play;
+  const loop = auditionController();
+  loop.focus(requestedTrack);
   return {
-    score,
+    score: loop.staging ? loop.score : score,
+    audition: {
+      looping: loop.looping,
+      dirty: loop.dirtyEdits,
+      committed: score,
+      hint: loop.hint(),
+      status: loop.status(),
+    },
     trackId: requestedTrack,
     playing: clock.playing,
     grid: session?.grid ?? DEFAULT_GRID,
     grids: GRIDS.map((grid) => grid.label),
     clickOn: session?.clickOn ?? false,
     countInBars: session?.countInBars ?? 1,
+    chords: session?.chords.settings ?? chordSettings,
+    projectRoot: process.cwd(),
   };
 }
 
+/** The screen `?` describes, or undefined while `?` is typed text. */
+function keysScreen(): readonly KeySection[] | undefined {
+  if (euclid.open) return euclid.typing ? undefined : KEYS.euclid;
+  if (menu.open) return menu.typing ? undefined : KEYS.menu;
+  const overlay = tui.ui.overlay;
+  if (overlay === "picker")
+    return tui.pickerTyping
+      ? undefined
+      : AUDITION_PICKERS.has(tui.ui.picker?.id ?? "")
+        ? KEYS.audition
+        : KEYS.list;
+  if (overlay === "text") return KEYS.text;
+  if (overlay === "log") return KEYS.log;
+  if (prompt.value.length > 0) return undefined;
+  if (play?.on)
+    return play.chords.on ? [...KEYS.play, ...KEYS.chords] : KEYS.play;
+  return KEYS.prompt;
+}
+
+function showKeys(): void {
+  const sections = keysScreen();
+  if (!sections) return;
+  const lines = keyLines(sections);
+  // Play mode's secondary state lives here instead of the header.
+  if (play?.on && !tui.ui.overlay && !menu.open)
+    lines.unshift(...play.details(), "");
+  tui.showKeys("keys", lines);
+}
+
 function openMenu(section?: string): void {
   menu.show(menuContext(), section);
   refreshMenu();
 }
 
+function euclidContext() {
+  return { score, trackId: requestedTrack };
+}
+
+function openEuclid(voice?: string, origin?: string): void {
+  euclid.show(euclidContext(), voice, origin);
+  refreshEuclid();
+}
+
+function refreshEuclid(): void {
+  if (!euclid.open) return;
+  if (tui.ui.overlay !== undefined && tui.ui.picker?.id !== "euclid") {
+    euclid.close();
+    return;
+  }
+  const view = euclid.view(euclidContext());
+  tui.openPicker({
+    id: "euclid",
+    title: view.title,
+    items: view.items,
+    index: view.index,
+    hint: view.hint,
+  });
+}
+
+/**
+ * Play one bar of `voice` on the focused track over silence. While the loop
+ * is playing the edit is already audible, so nothing extra sounds.
+ */
+function audition(voice: string): void {
+  if (clock.playing) return;
+  const track = score.tracks.find(
+    (candidate) => candidate.id === requestedTrack,
+  );
+  if (!track) return;
+  const pitch = rhythmVoicePitch(track, voice);
+  if (pitch === undefined) return;
+  const engine = liveEngine();
+  if (!engine?.canMonitor) return;
+  const pcm = renderAudition({
+    score,
+    trackId: track.id,
+    pitches: new Set([pitch]),
+    bars: 1,
+    sampleRate: engine.sampleRate,
+    ...(liveSampleBank ? { samples: liveSampleBank } : {}),
+  });
+  if (!pcm) return;
+  void engine
+    .monitor(true)
+    .then(() => engine.noteOn(AUDITION_VOICE, pcm))
+    .catch(() => undefined);
+}
+
+/**
+ * The window's audition controller. Its loop plays through the ordinary
+ * engine (the render worker and stem cache), so a preview sounds exactly
+ * like the same bars of the song; staged commands run through `submit`
+ * with `commitScore` captured, so a staged edit is made by the same code
+ * as a committed one.
+ */
+function auditionController(): Audition {
+  auditionLoop ??= new Audition(
+    {
+      apply: applyStaged,
+      play: (preview) => previewEngine().play(preview),
+      stop() {
+        const engine = previewEngine();
+        engine.stop();
+        if (!play?.on) engine.setLeadMs(undefined);
+      },
+      leadMs: () => previewEngine().leadMs,
+      now: () => performance.now(),
+      beat: () => clock.beatAt(),
+      setTimer: (callback, ms) => setTimeout(callback, ms),
+      clearTimer: (handle) => clearTimeout(handle as Timer),
+      changed: () => requestFrame(),
+      level: () => previewEngine().level,
+    },
+    score,
+    requestedTrack,
+  );
+  return auditionLoop;
+}
+
+/**
+ * Warm the pack cache for a staged command before it runs, so a lazy fetch
+ * (a sample kit, a pack sound or table) happens outside the capture and the
+ * window's score is swapped only for the instant the command takes.
+ */
+async function prefetchStaged(
+  base: TrackScore,
+  command: string,
+): Promise<void> {
+  try {
+    const kit = parseKitCommand(command);
+    if (kit?.kind === "set" && !isSynthKitName(kit.bank)) {
+      const trackId = kitTarget(base, requestedTrack);
+      if (trackId) await useKit(packs(), base, trackId, kit.bank);
+      return;
+    }
+    const pack = parsePackCommand(command);
+    if (pack?.kind === "use") {
+      await useSound(packs(), base, requestedTrack, pack.sound, {
+        ...(pack.voice ? { voice: pack.voice } : {}),
+      });
+      return;
+    }
+    const wavetable = parseWavetableCommand(command);
+    if (wavetable?.kind === "table")
+      await pickWavetable(
+        packs(),
+        base,
+        requestedTrack,
+        wavetable.table,
+        process.cwd(),
+      );
+  } catch {
+    // The command itself reports the failure.
+  }
+}
+
+/** Apply one prompt command to `base` without committing (see stageCapture). */
+async function applyStaged(
+  base: TrackScore,
+  command: string,
+): Promise<{ next?: TrackScore; ok: boolean; message: string }> {
+  await prefetchStaged(base, command);
+  // Staged commands run one at a time, between queued prompts.
+  while (stageCapture) await Bun.sleep(1);
+  const committed = score;
+  stageCapture = {};
+  score = base;
+  try {
+    const result = await submit(command);
+    const text = typeof result === "string" ? result : result.text;
+    const good = toneOf(result) !== "error";
+    return { next: stageCapture.next, ok: good, message: text };
+  } catch (error) {
+    return { ok: false, message: describeError(command, error) };
+  } finally {
+    score = stageCapture?.committed ?? committed;
+    stageCapture = undefined;
+  }
+}
+
+/** Keep the controller on the committed score (remote edits, undo, agent). */
+function followCommitted(): void {
+  const loop = auditionLoop;
+  if (!loop || stageCapture || loop.committed === score) return;
+  if (!loop.dirtyEdits) {
+    loop.committedNow(score);
+    return;
+  }
+  void loop.rebase(score).then(({ dropped }) => {
+    tui.activity.pushCard(
+      dropped.length
+        ? `score changed · dropped staged ${dropped.join(", ")}`
+        : "score changed · staged edits re-applied on top",
+      { tone: "warning" },
+    );
+    requestFrame();
+  });
+}
+
+async function startAuditionLoop(): Promise<void> {
+  const loop = auditionController();
+  await materializeDraft();
+  loop.committedNow(score);
+  loop.focus(requestedTrack);
+  // One sound at a time: the song stops while the loop plays.
+  if (clock.playing) await setTransport("pause");
+  previewEngine().setLeadMs(PLAY_LEAD_MS);
+  loop.start();
+}
+
+function stopAuditionLoop(): void {
+  auditionLoop?.stop();
+}
+
+/** A menu or picker audition key: Space, `a` (A/B) or `c` (context). */
+function auditionKeyPressed(
+  key: "loop" | "ab" | "context",
+): Promise<void> | undefined {
+  const loop = auditionController();
+  if (key === "loop") {
+    if (loop.looping) stopAuditionLoop();
+    else return startAuditionLoop().finally(() => requestFrame());
+  } else if (key === "ab") {
+    if (!loop.dirtyEdits) {
+      tui.activity.pushCard("A/B · nothing staged yet · ←→ to change a value", {
+        tone: "info",
+      });
+      return;
+    }
+    loop.toggleAB();
+  } else loop.toggleContext();
+  return undefined;
+}
+
+/** An auditioning picker's title carries the loop status (`♪ solo · B`). */
+function refreshAuditionPicker(): void {
+  const picker = tui.ui.picker as
+    (NonNullable<typeof tui.ui.picker> & { baseTitle?: string }) | undefined;
+  if (tui.ui.overlay !== "picker" || !picker?.audition) return;
+  // Kept on the picker so a filter's copy of it keeps the plain title too.
+  const base = (picker.baseTitle ??= picker.title);
+  const status = auditionLoop?.status();
+  const dirty = auditionLoop?.dirtyEdits ? "● " : "";
+  picker.title = status ? `${dirty}${base} · ${status}` : base;
+}
+
+/**
+ * `/try <command>`: hear a sound command on the audition loop before it
+ * lands. A small picker offers keep (one undo step) or revert; Space, `a`
+ * and `c` work as in the menu.
+ */
+async function tryPrompt(command: string): Promise<Receipt> {
+  if (!command) return fail(TRY_USAGE);
+  const agentToggle = command.match(/^agent\s+(on|off)$/i);
+  if (agentToggle) {
+    agentPreviewPlays = agentToggle[1]!.toLowerCase() === "on";
+    return ok(
+      `try · agent previews ${agentPreviewPlays ? "play once here" : "stay silent (numbers only)"}`,
+    );
+  }
+  if (!isStageable(command))
+    return fail(`try · only sound changes can be tried · ${TRY_USAGE}`);
+  if (menu.open || euclid.open)
+    return fail("try · close the open screen first");
+  const loop = auditionController();
+  if (!loop.looping) await startAuditionLoop();
+  const result = await loop.stage(command);
+  if (!result.ok) {
+    if (!loop.dirtyEdits) stopAuditionLoop();
+    return fail(`try · ${result.message}`);
+  }
+  tui.openPicker({
+    id: "try",
+    title: `try · ${command.slice(0, 48)}`,
+    hint: HINTS.audition,
+    audition: true,
+    items: [
+      { label: "keep", value: "keep", detail: "commit it · one undo step" },
+      { label: "revert", value: "revert", detail: "drop it" },
+    ],
+  });
+  return ok(`trying · ${command} · a A/B · enter keep · esc revert`);
+}
+
+/** Audition a list's highlighted item in place of its previous hover. */
+function hoverItem(command: string, key: string): void {
+  const loop = auditionLoop;
+  if (!loop?.looping) return;
+  requestFrame();
+  void loop.hover(command, key).then((result) => {
+    if (!result.ok && result.message !== SUPERSEDED)
+      tui.activity.pushCard(result.message, { tone: "warning" });
+    requestFrame();
+  });
+}
+
+/** Enter on a list item while auditioning: it stays staged for good. */
+function chooseItem(command: string, key: string): void {
+  const loop = auditionLoop;
+  if (!loop) return;
+  void loop
+    .hover(command, key)
+    .then((result) => {
+      if (!result.ok && result.message !== SUPERSEDED)
+        tui.activity.pushCard(result.message, { tone: "warning" });
+      loop.settle(key);
+    })
+    .finally(() => requestFrame());
+}
+
+/** Space, `a` or `c` in a picker: starting the loop hovers the cursor row. */
+function pickerAuditionKey(key: "loop" | "ab" | "context"): void {
+  const started = auditionKeyPressed(key);
+  if (!started) return;
+  const picker = tui.ui.picker;
+  const item = picker?.items[picker.index];
+  if (!picker || !item || !isStageable(item.value)) return;
+  void started.then(() => {
+    const now = tui.ui.picker;
+    const current = now?.id === picker.id ? now.items[now.index] : undefined;
+    if (current && isStageable(current.value))
+      hoverItem(current.value, `picker:${picker.id}`);
+  });
+}
+
+/** Stage a menu command while auditioning; undefined when it should run. */
+function stageIfAuditioning(command: string): boolean {
+  const loop = auditionLoop;
+  if (!loop?.staging || !isStageable(command)) return false;
+  void loop.stage(command).then((result) => {
+    if (!result.ok)
+      tui.activity.pushCard(result.message, {
+        tone: result.message.includes("failed") ? "error" : "warning",
+      });
+    requestFrame();
+  });
+  return true;
+}
+
+/** Enter: every staged edit becomes ONE revision (one undo step). */
+async function keepStaged(): Promise<Receipt> {
+  const loop = auditionLoop;
+  await loop?.settled();
+  const taken = loop?.take();
+  if (!loop || !taken) return warn("nothing staged");
+  await materializeDraft();
+  let next = taken.score;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await commitScore(next, "preview.commit", {
+        trackId: loop.trackId,
+        commands: taken.commands,
+      });
+      break;
+    } catch (error) {
+      if (!(error instanceof SessionConflictError) || attempt > 0) throw error;
+      // Another window committed first: replay the staged commands on it.
+      record = await port.load();
+      score = scoreFromJSON(record.composition);
+      next = score;
+      for (const command of taken.commands) {
+        const result = await applyStaged(next, command);
+        if (result.next) next = result.next;
+      }
+    }
+  }
+  loop.committedNow(score);
+  await projectSync?.flushScore();
+  return ok(
+    `kept ${taken.commands.length} change${taken.commands.length === 1 ? "" : "s"} · one undo step`,
+  );
+}
+
+function revertStaged(): void {
+  const loop = auditionLoop;
+  if (!loop?.dirtyEdits) return;
+  const count = loop.commands.length;
+  loop.revert();
+  tui.activity.pushCard(
+    `reverted ${count} staged change${count === 1 ? "" : "s"}`,
+    { tone: "info" },
+  );
+}
+
+/** Leaving an auditioning screen stops the loop and drops staged edits. */
+function leaveAuditionScreen(): void {
+  if (auditionLoop?.dirtyEdits) revertStaged();
+  stopAuditionLoop();
+}
+
 function refreshMenu(): void {
   if (!menu.open) return;
   if (tui.ui.overlay !== undefined && tui.ui.picker?.id !== "menu") {
     // Another overlay (help, a picker) replaced the menu.
     menu.close();
+    leaveAuditionScreen();
     return;
   }
   const view = menu.view(menuContext());
@@ -1747,6 +2788,7 @@ function refreshMenu(): void {
       : [{ label: "no matches", value: "none" }],
     index: view.index,
     hint: view.hint,
+    note: view.note,
   });
 }
 
@@ -1756,6 +2798,7 @@ function playSession(): PlaySession {
   play = new PlaySession(playHost(), {
     clickOn: previous?.clickOn,
     clickVolume: previous?.clickVolume,
+    chords: chordSettings,
   });
   if (previous) {
     play.countInBars = previous.countInBars;
@@ -1771,7 +2814,7 @@ async function enterPlay(): Promise<Receipt> {
   await session.enter();
   if (hasSamplerTracks(score)) void sampleProblems(score);
   return ok(
-    `play · ${session.track} · ${session.keyboard.range} · z/x octave · r record · m click · esc leaves`,
+    `play · ${session.track} · ${session.keyboard.range} · ? keys · esc leaves`,
   );
 }
 
@@ -1883,11 +2926,21 @@ async function commitScore(
   payload: Record<string, unknown> = {},
 ): Promise<void> {
   if (next === score) return;
+  // Rhythm rows regenerate after a loop resize and freeze when their lane
+  // is hand-edited, so rows and notes never disagree.
+  next = reconcileRhythm(score, next);
+  if (stageCapture) {
+    // A staged edit: the audition plays it; nothing is written yet.
+    stageCapture.next = next;
+    score = next;
+    return;
+  }
   record = await port.append(record, { kind, payload }, next.toJSON());
   score = next;
   if (clock.playing) void audio.play(score);
   projectSync?.scoreChanged(score);
   reportSampleProblems(score);
+  void updateCredits(score);
 }
 
 /** The window's side of the project file sync (see src/project/sync.ts). */
@@ -1992,6 +3045,8 @@ async function toggleTransport(): Promise<void> {
 async function setTransport(
   action: "play" | "pause" | "toggle",
 ): Promise<void> {
+  // One sound at a time: starting the song stops an audition loop.
+  if (action !== "pause" && auditionLoop?.looping) stopAuditionLoop();
   if (port.mode === "daemon") {
     // dawgd owns the only transport; its broadcast updates `clock`.
     await port.transport(action);
@@ -2116,6 +3171,39 @@ function mediaServices(): MediaServices {
   return { runner: systemRunner, env: process.env };
 }
 
+/**
+ * How the agent's preview_sound renders (with this window's decoded
+ * samples, at the engine's rate) and plays: once, over silence, unless the
+ * song or the audition loop is already sounding or `/try agent off`.
+ */
+function agentPreviewHost(): PreviewHost {
+  return {
+    render: async (value) => {
+      await sampleProblems(value);
+      return renderScorePcm(value, {
+        sampleRate: previewEngine().sampleRate,
+        ...(liveSampleBank ? { samples: liveSampleBank } : {}),
+      });
+    },
+    play: async (rendered) => {
+      if (!agentPreviewPlays || clock.playing || auditionLoop?.looping)
+        return false;
+      const engine = liveEngine();
+      if (!engine?.canMonitor || rendered.frames === 0) return false;
+      try {
+        await engine.monitor(true);
+        engine.noteOn(AGENT_PREVIEW_VOICE, {
+          pcm: rendered.pcm,
+          frames: rendered.frames,
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
 function agentHost(
   turn: { steering: string[] },
   selection: ProviderSelection,
@@ -2133,6 +3221,7 @@ function agentHost(
       }),
     }),
     media: mediaServices(),
+    preview: agentPreviewHost(),
     async commit(change) {
       // dawgd rebases operation intents onto newer revisions when nothing
       // they touch changed; the file port keeps the strict base check.