@hraness/dawg 0.4.1 → 0.5.0

package/src/main.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { randomUUID } from "node:crypto";
+import { readFileSync, writeSync } from "node:fs";
 import { readFile, stat, writeFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { stdin, stdout } from "node:process";
@@ -42,8 +43,36 @@ import {
 } from "./commands/drums.ts";
 import { kitCatalog } from "./audio/kits.ts";
 import { applyEditCommand, parseEditCommand } from "./commands/edit.ts";
+import { applyTimeCommand, parseTimeCommand } from "./commands/time.ts";
+import {
+  barStartTick,
+  bpmAtTick,
+  hasMeterChanges,
+  loopTicksOf,
+} from "../core/tempo.ts";
+import {
+  applyExpressionCommand,
+  parseExpressionCommand,
+} from "./commands/expression.ts";
 import { applyFxCommand, parseFxCommand } from "./commands/fx.ts";
 import { applySynthCommand, parseSynthCommand } from "./commands/synth.ts";
+import {
+  applyTuningCommand,
+  importTuningFile,
+  parseTuningCommand,
+  type TuningCommand,
+} from "./commands/tuning.ts";
+import { TuningError, displayTag, resolveTuning } from "../core/tuning.ts";
+import {
+  applyMasterCommand,
+  measurementLine,
+  parseMasterCommand,
+} from "./commands/master.ts";
+import { exportSampleRate, measureScoreOffThread } from "./audio/measure.ts";
+import {
+  applySectionCommand,
+  parseSectionCommand,
+} from "./commands/arrange.ts";
 import {
   HELP_TOPICS,
   helpText,
@@ -106,7 +135,7 @@ import {
   tuiLoginArgs,
   tuiSetModel,
 } from "./auth/tui.ts";
-import { TransportClock } from "./audio/clock.ts";
+import { TransportClock, transportMapFor } from "./audio/clock.ts";
 import { AudioEngine } from "./audio/engine.ts";
 import {
   DEFAULT_GRID,
@@ -116,6 +145,23 @@ import {
   type LiveEngine,
 } from "./tui/play-session.ts";
 import { EditMenu, MENU_SECTIONS, type MenuContext } from "./tui/menu.ts";
+import {
+  drawerView,
+  faderChoose,
+  faderKeyPress,
+  faderSetPosition,
+  faderStep,
+  focusIndex,
+  type FaderResult,
+  type FaderState,
+} from "./tui/fader.ts";
+import {
+  isMouseSequence,
+  MOUSE_OFF,
+  MOUSE_ON,
+  parseMouse,
+  type MouseEvent,
+} from "../tui/keys.ts";
 import {
   Audition,
   SUPERSEDED,
@@ -125,6 +171,9 @@ import {
 import { EuclidEditor, type EuclidContext } from "./tui/euclid.ts";
 import { HINTS, KEYS, keyLines, type KeySection } from "../tui/grammar.ts";
 import { renderAudition } from "./audio/audition.ts";
+import { exportScore, playbackTime, scoreBeatAt } from "./audio/arrange.ts";
+import { formatForm } from "../core/sections.ts";
+import type { ArrangeStripView } from "../tui/arrange-strip.ts";
 import { renderScorePcm } from "./audio/wav.ts";
 import type { PreviewHost } from "./agent/preview-tool.ts";
 import { rhythmVoicePitch } from "../core/rhythm.ts";
@@ -176,6 +225,7 @@ import {
 } from "../core/score.ts";
 import { reconcileRhythm } from "../core/rhythm.ts";
 import { decodeLoop, encodeLoop } from "../core/loop.ts";
+import { scoreToMidi } from "../core/midi.ts";
 import type { TrackScoreSnapshot } from "../tui/render.ts";
 import { PromptModel } from "../tui/prompt.ts";
 import { TerminalInputDecoder } from "../tui/input.ts";
@@ -183,6 +233,7 @@ import {
   composeFrame,
   TuiApp,
   type AppView,
+  type LoudnessView,
   type SyncState,
   type TypesIndicator,
 } from "../tui/app.ts";
@@ -209,11 +260,16 @@ function parsesLocally(text: string): boolean {
     parseRhythmCommand,
     parseFxCommand,
     parseSynthCommand,
+    parseExpressionCommand,
+    parseMasterCommand,
+    (value: string) => parseSectionCommand(value, score),
     parsePatternCommand,
     parseKitCommand,
     parsePackCommand,
     parseSampleCommand,
     parseWavetableCommand,
+    parseTimeCommand,
+    parseTuningCommand,
   ].some((parse) => parse(text) !== undefined);
 }
 
@@ -240,6 +296,7 @@ const FLAGS = [
   "--version",
   "-v",
   "--reduce-motion",
+  "--no-mouse",
 ];
 const HELP_TEXT = `dawg · local-first terminal music workstation
 
@@ -247,7 +304,8 @@ Usage:
   dawg [--new] [--session <name|id>] [--track <name>]
   dawg --import <file> --export <file>
   dawg sessions
-  dawg render <out.wav> [--session <name|id>] [--import <file>]
+  dawg render <out.wav|out.mid> [--session <name|id>] [--import <file>]
+               [--normalize <lufs|streaming|club|loud|…>] [--measure]
   dawg init [dir]      project files: song.ts, tracks/<slug>/track.ts, .dawg/sdk
   dawg check           typecheck + evaluate the project; exit 1 on problems
   dawg media doctor|download|stems|analyze|notes|sample|lyrics …  (dawg media --help)
@@ -256,6 +314,7 @@ Usage:
 Usage flags:
   --reduce-motion   static hit/sustain states (also DAWG_REDUCE_MOTION=1)
   --theme <name>    default | high-contrast | mono (NO_COLOR forces mono)
+  --no-mouse        keys only; no click/wheel reporting (also DAWG_MOUSE=0)
 
 Prompt:
   Enter submit · Shift-Enter newline · Alt-Enter queue · Ctrl-Q toggle queue
@@ -486,6 +545,18 @@ let chordScreenWas = false;
 let stageCapture: { next?: TrackScore; committed?: TrackScore } | undefined;
 /** Redraw soon (the audition reports renders between frames). */
 let requestFrame: () => void = () => undefined;
+/** Queue a prompt to run as if typed (set by the interactive loop). */
+let runPromptLater: (command: string) => void = () => undefined;
+/** The fader drawer's focus and typing, while one is open over the menu. */
+let fader: FaderState | undefined;
+const KEY_UP = "\u001b[A";
+const KEY_DOWN = "\u001b[B";
+/** The fader bar a left-button drag started on. */
+let dragging: { field: number; left: number; width: number } | undefined;
+/** The open drawer came from a command, not the menu. */
+let faderStandalone = false;
+/** Per-field sequence: a drag drops stale stages that would land late. */
+const faderSeq = new Map<string, number>();
 /** 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. */
@@ -645,16 +716,29 @@ function snapshot(
   beat: number,
   activity?: string,
 ): TrackScoreSnapshot {
+  const focused = value.tracks.find((track) => track.id === requestedTrack);
+  const table =
+    focused && !isDrumInstrument(focused.instrument)
+      ? resolveTuning(value.tuning, focused.tuning, value.key)
+      : undefined;
   const notes = value.notes
     .filter((note) => note.trackId === requestedTrack)
-    .map((note) => ({
-      id: note.id,
-      startBeat: note.startTick / value.ticksPerBeat,
-      durationBeats: note.durationTicks / value.ticksPerBeat,
-      pitch: note.pitch,
-      velocity: note.velocity,
-      muted: value.tracks.find((track) => track.id === requestedTrack)?.muted,
-    }));
+    .map((note) => {
+      const tag =
+        focused && !isDrumInstrument(focused.instrument)
+          ? displayTag(table, note.pitch, note.cents)
+          : undefined;
+      return {
+        id: note.id,
+        startBeat: note.startTick / value.ticksPerBeat,
+        durationBeats: note.durationTicks / value.ticksPerBeat,
+        pitch: note.pitch,
+        velocity: note.velocity,
+        muted: focused?.muted,
+        ...(tag?.cents !== undefined ? { cents: tag.cents } : {}),
+        ...(tag?.name !== undefined ? { centsFrom: tag.name } : {}),
+      };
+    });
   return {
     notes,
     trackName:
@@ -663,12 +747,22 @@ function snapshot(
     trackId: requestedTrack,
     sessionId: record.sessionId,
     revision: record.revision,
-    bpm: value.tempoBpm,
+    bpm: value.time?.tempo
+      ? bpmAtTick(value, beat * value.ticksPerBeat)
+      : value.tempoBpm,
     key: value.key ?? undefined,
-    loopBeats: value.bars * value.beatsPerBar,
+    loopBeats: loopTicksOf(value) / value.ticksPerBeat,
     beatsPerBar: value.beatsPerBar,
+    ...(hasMeterChanges(value)
+      ? {
+          barBeats: Array.from(
+            { length: value.bars },
+            (_, bar) => barStartTick(value, bar) / value.ticksPerBeat,
+          ),
+        }
+      : {}),
     laneCount: 24,
-    currentBeat: beat,
+    currentBeat: scoreBeatAt(value, beat),
     playing: clock.playing,
     activity,
     ...drumSnapshotFields(
@@ -679,6 +773,9 @@ function snapshot(
       value.tracks.find((track) => track.id === requestedTrack),
       notes,
     ),
+    ...(table && table.linear && table.size !== 12
+      ? { tuningPeriod: { size: table.size, root: table.root } }
+      : {}),
     layers:
       tui.highwayView === "all"
         ? highwayLayers(
@@ -712,7 +809,9 @@ function renderOnce(
 function appView(value: TrackScore, beat: number): AppView {
   return {
     score: snapshot(value, beat),
-    beat,
+    // The highway shows score time: inside the looped section or form pass.
+    beat: scoreBeatAt(value, beat),
+    arrange: arrangeStripView(value, beat),
     // `opus-5.5 · gateway`, `sonnet · claude`; hidden when offline.
     model:
       providerName && providerName !== "offline" ? providerName : undefined,
@@ -723,6 +822,79 @@ function appView(value: TrackScore, beat: number): AppView {
     windows: windowCount,
     types: typesIndicator,
     play: play?.on ? play.header() : undefined,
+    loudness: masterLoudness(value),
+  };
+}
+
+/**
+ * The 48 kHz reading of the mastered song (what `master measure` and the
+ * export read), for the score it measured; one measurement at a time, in a
+ * worker, started when the loop plays a mastered score it has not read.
+ */
+let exportMeter:
+  { score: TrackScore; view?: LoudnessView; running: boolean } | undefined;
+
+/**
+ * The header meter: loudness of the loop the local engine is playing. With
+ * a master the engine monitors at its own rate, so the meter shows the
+ * export-rate reading once it is in and the monitor's (marked as an
+ * estimate) until then.
+ */
+function masterLoudness(value: TrackScore): LoudnessView | undefined {
+  const engine = audio instanceof AudioEngine ? audio : monitorEngine;
+  const report = engine?.loudness;
+  if (!report) return undefined;
+  const ceiling =
+    typeof value.master?.limiter?.ceiling === "number"
+      ? value.master.limiter.ceiling
+      : value.master?.limiter
+        ? -1
+        : undefined;
+  const target =
+    typeof value.master?.target === "number" ? value.master.target : undefined;
+  const monitor: LoudnessView = {
+    integrated: report.integrated,
+    truePeak: report.truePeak,
+    target,
+    ceiling,
+  };
+  if (!value.master || exportSampleRate(value) === engine.sampleRate)
+    return monitor;
+  if (exportMeter?.score === value && exportMeter.view) return exportMeter.view;
+  if (!exportMeter?.running) {
+    const measuring = { score: value, running: true } as NonNullable<
+      typeof exportMeter
+    >;
+    exportMeter = measuring;
+    void measureScoreOffThread(value, { projectRoot: process.cwd() })
+      .then((measured) => {
+        measuring.view = {
+          integrated: measured.mix.loudness.integrated,
+          truePeak: measured.mix.loudness.truePeak,
+          target,
+          ceiling,
+        };
+      })
+      .catch(() => undefined)
+      .finally(() => {
+        measuring.running = false;
+      });
+  }
+  return { ...monitor, estimate: true };
+}
+
+/** The arrangement strip over the timeline; absent without sections. */
+function arrangeStripView(
+  value: TrackScore,
+  beat: number,
+): ArrangeStripView | undefined {
+  if (value.sections.length === 0) return undefined;
+  return {
+    bars: value.bars,
+    sections: value.sections,
+    loop: value.loopSection,
+    playheadBar: scoreBeatAt(value, beat) / value.beatsPerBar,
+    form: value.form.length ? formatForm(value.form) : undefined,
   };
 }
 
@@ -779,11 +951,46 @@ function truncateForCard(value: string): string {
   return line.length > 32 ? `${line.slice(0, 31)}…` : line;
 }
 
+/**
+ * Mouse reporting is on unless `--no-mouse` or `DAWG_MOUSE=0` (or a dumb
+ * terminal) says otherwise. A terminal without mouse support ignores the
+ * modes and every key still works.
+ */
+function mouseEnabled(): boolean {
+  return (
+    !process.argv.includes("--no-mouse") &&
+    process.env.DAWG_MOUSE !== "0" &&
+    process.env.TERM !== "dumb"
+  );
+}
+
+function mouseOn(): string {
+  return mouseEnabled() ? MOUSE_ON : "";
+}
+
 async function runInteractive(): Promise<void> {
+  // A crash or a stray process.exit must not leave the terminal reporting
+  // mouse events into the shell.
+  process.once("exit", () => {
+    if (mouseEnabled()) writeSync(1, MOUSE_OFF);
+  });
+  // Nor may a kill or a closed terminal: restore it, then exit as killed.
+  for (const [signal, code] of [
+    ["SIGTERM", 143],
+    ["SIGHUP", 129],
+  ] as const)
+    process.once(signal, () => {
+      try {
+        writeSync(1, `${MOUSE_OFF}${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`);
+      } catch {
+        // The terminal may already be gone (SIGHUP).
+      }
+      process.exit(code);
+    });
   stdin.setRawMode?.(true);
   stdin.resume();
   // Alternate screen, hidden cursor, bracketed paste.
-  stdout.write(`${ESC}?1049h${ESC}?25l${ESC}?2004h${ESC}2J`);
+  stdout.write(`${ESC}?1049h${ESC}?25l${ESC}?2004h${ESC}2J${mouseOn()}`);
   const inputDecoder = new TerminalInputDecoder();
   const queuedPrompts: string[] = [];
   let processingQueue = false;
@@ -845,6 +1052,10 @@ async function runInteractive(): Promise<void> {
     tui.render(appView(score, clock.beatAt()), { force });
   };
   requestFrame = () => tick(true);
+  runPromptLater = (command) => {
+    queuedPrompts.unshift(command);
+    void drainQueue();
+  };
   reportAgentActivity = () => {
     tui.activity.applyAgentEvent({ type: "start", model: providerName });
   };
@@ -871,7 +1082,7 @@ async function runInteractive(): Promise<void> {
         if (stageCapture)
           stageCapture.committed = scoreFromJSON(record.composition);
         else score = scoreFromJSON(record.composition);
-        clock.setTempo(score.tempoBpm);
+        clock.follow(score);
         if (clock.playing) void audio.play(score);
         // Connected windows follow dawgd's transport frames instead.
         const replay =
@@ -924,6 +1135,7 @@ async function runInteractive(): Promise<void> {
       // Every window renders the same hit line from dawgd's timestamp.
       const { playing, beat, bpm, atMs } = update.transport;
       clock.setTempo(bpm);
+      clock.setTimeMap(transportMapFor(playbackTime(score)));
       clock.sync(beat, playing, atMs, monotonicEpochMs());
     } else if (update.type === "status") {
       syncState = port.sync;
@@ -1000,11 +1212,11 @@ async function runInteractive(): Promise<void> {
     stdin.pause();
     stdin.setRawMode?.(false);
     // Leave the alternate screen; restore the cursor and plain paste.
-    stdout.write(`${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`);
+    stdout.write(`${MOUSE_OFF}${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`);
     try {
       return await flow();
     } finally {
-      stdout.write(`${ESC}?1049h${ESC}?25l${ESC}?2004h${ESC}2J`);
+      stdout.write(`${ESC}?1049h${ESC}?25l${ESC}?2004h${ESC}2J${mouseOn()}`);
       stdin.setRawMode?.(true);
       stdin.on("data", onData);
       stdin.resume();
@@ -1023,7 +1235,31 @@ async function runInteractive(): Promise<void> {
         ...inputDecoder.push(text),
         ...(text === "\u001b" ? inputDecoder.flush() : []),
       ];
-      for (const value of values) {
+      while (values.length) {
+        const value = values.shift()!;
+        // A mouse report acts on what the last frame painted under it; some
+        // become keys (a list row, a wheel notch) and run through below.
+        if (typeof value === "string" && isMouseSequence(value)) {
+          const event = parseMouse(value);
+          if (event) values.unshift(...mouseInput(event));
+          tick(true);
+          continue;
+        }
+        // The fader drawer owns every key while it is up.
+        if (typeof value === "string" && fader && menu.open) {
+          const result = faderKeyPress(
+            fader,
+            menu.faderFields(menuContext()),
+            value,
+            faderKeyOptions(),
+          );
+          if (result.type !== "pass") {
+            faderOutcome(result);
+            refreshMenu();
+            tick(true);
+            continue;
+          }
+        }
         // The `?` panel closes on any key (Ctrl-C still quits).
         if (tui.ui.keys && typeof value === "string" && value !== "\u0003") {
           tui.closeKeys();
@@ -1086,6 +1322,7 @@ async function runInteractive(): Promise<void> {
               }
             } else if (result.type === "audition")
               auditionKeyPressed(result.key);
+            else if (result.type === "fader") openFader(result.label);
             else if (result.type === "revert") revertStaged();
             else if (result.type === "hover")
               hoverItem(result.command, result.key);
@@ -1109,6 +1346,16 @@ async function runInteractive(): Promise<void> {
             }
           }
         }
+        // F1 opens the guides from anywhere the prompt has focus.
+        if (
+          (value === "\u001bOP" || value === "\u001b[11~") &&
+          (tui.ui.overlay === undefined || tui.ui.overlay === "guide")
+        ) {
+          if (tui.ui.overlay === "guide") tui.closeGuide();
+          else tui.openGuide();
+          tick(true);
+          continue;
+        }
         // Ctrl-K opens the menu on an empty prompt (in play mode too); with
         // text it keeps its kill-to-end-of-line meaning.
         if (
@@ -1140,7 +1387,8 @@ async function runInteractive(): Promise<void> {
         if (
           value === " " &&
           prompt.value.length === 0 &&
-          !(tui.ui.overlay === "picker" && tui.ui.picker?.audition)
+          !(tui.ui.overlay === "picker" && tui.ui.picker?.audition) &&
+          tui.ui.overlay !== "guide"
         ) {
           // Never await a daemon round trip here: the key loop must stay
           // live for Esc, quit and redraws while the toggle is in flight.
@@ -1271,7 +1519,7 @@ async function runInteractive(): Promise<void> {
     await port.close();
     stdin.setRawMode?.(false);
     stdin.pause();
-    stdout.write(`${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`);
+    stdout.write(`${MOUSE_OFF}${ESC}0m${ESC}?2004l${ESC}?25h${ESC}?1049l`);
   }
 }
 
@@ -1306,7 +1554,7 @@ async function submit(prompt: string): Promise<string | Receipt> {
   }
   if (/^\/?tracks$/i.test(command)) {
     const problems = await sampleProblems(score);
-    const lines = score.tracks.map((track) => {
+    const items = score.tracks.map((track) => {
       const voices = track.sampler
         ? Object.keys(track.sampler.voices).length
         : 0;
@@ -1316,16 +1564,39 @@ async function submit(prompt: string): Promise<string | Receipt> {
       const samples = track.sampler
         ? ` · ${voices} sample${voices === 1 ? "" : "s"}${missing ? ` · ${missing} missing` : ""}`
         : "";
-      return `${track.id === requestedTrack ? "*" : " "} ${track.id} · ${track.instrument}${samples}${track.muted ? " · muted" : ""}${track.solo ? " · solo" : ""}`;
+      return {
+        label: track.id,
+        value: `/track ${track.id}`,
+        detail: `${track.instrument}${samples}${track.muted ? " · muted" : ""}${track.solo ? " · solo" : ""}`,
+        current: track.id === requestedTrack,
+      };
+    });
+    // A picker: Enter (or a click) focuses the track; Esc closes.
+    tui.openPicker({
+      id: "tracks",
+      title: "tracks · ● focused",
+      items,
+      filterable: items.length > 8,
+      index: Math.max(
+        0,
+        items.findIndex((item) => item.current),
+      ),
     });
-    tui.openText("tracks · * focused", lines);
-    return ok(`${lines.length} track${lines.length === 1 ? "" : "s"}`);
+    return ok(`${items.length} track${items.length === 1 ? "" : "s"}`);
   }
-  const playCommand = command.match(/^\/play(?:\s+(on|off))?$/i);
+  const playCommand = command.match(
+    /^\/play(?:\s+(on|off|degrees|in-key|chromatic))?$/i,
+  );
   if (playCommand) {
     const wanted = playCommand[1]?.toLowerCase();
     if (wanted === "off" || (wanted === undefined && play?.on))
       return exitPlay();
+    if (wanted && wanted !== "on") {
+      const message = playSession().toggleDegrees(wanted !== "chromatic");
+      if (message.startsWith("scale degrees need")) return fail(message);
+      const entered = await enterPlay();
+      return entered.ok ? ok(message) : entered;
+    }
     return enterPlay();
   }
   const clickCommand = command.match(/^\/click(?:\s+(.+))?$/i);
@@ -1354,6 +1625,16 @@ async function submit(prompt: string): Promise<string | Receipt> {
   }
   const tryCommand = command.match(/^\/try(?:\s+(.+))?$/i);
   if (tryCommand) return tryPrompt(tryCommand[1]?.trim() ?? "");
+  // A bare parameter (`volume`, `pan`, `fx filter`, `fx reverb mix`)
+  // opens the fader drawer on it, with its related params stacked below.
+  if (/^\/?(?:volume|pan|fx\s+\S+(?:\s+\S+)?)$/i.test(command)) {
+    const label = menu.showFader(menuContext(), command);
+    if (label) {
+      openFader(label, true);
+      refreshMenu();
+      return ok(`${label} · ←→ adjust · enter keep · esc revert`);
+    }
+  }
   const menuCommand = command.match(/^\/menu(?:\s+(\S+))?$/i);
   if (menuCommand) {
     const section = menuCommand[1]?.toLowerCase();
@@ -1379,6 +1660,16 @@ async function submit(prompt: string): Promise<string | Receipt> {
     /^\/?(?:add\s+)?track\s+([a-z0-9._-]{1,64})$/i,
   );
   if (trackCommand) return focusTrack(trackCommand[1]!.toLowerCase());
+  // `/track piano b`: a name with spaces focuses the track of that name, or
+  // creates `piano-b` named "piano b".
+  const namedTrack = command.match(/^\/track\s+([a-z0-9._ -]{1,64})$/i);
+  if (namedTrack) {
+    const name = namedTrack[1]!.trim().replace(/\s+/g, " ");
+    const found = score.tracks.find(
+      (track) => (track.name ?? track.id).toLowerCase() === name.toLowerCase(),
+    );
+    return focusTrack(found?.id ?? name.toLowerCase().replace(/ /g, "-"));
+  }
   const sample = parseSampleCommand(command);
   if (sample) return sampleCommand(sample);
   const pack = parsePackCommand(command);
@@ -1391,6 +1682,14 @@ async function submit(prompt: string): Promise<string | Receipt> {
   if (wavetable) return wavetableCommand(wavetable);
   const sessionReply = await sessionCommand(command);
   if (sessionReply !== undefined) return sessionReply;
+  const time = parseTimeCommand(command);
+  if (time) {
+    if (time.type !== "tempo-map") await materializeDraft();
+    const result = applyTimeCommand(score, requestedTrack, time);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const edit = parseEditCommand(command);
   if (edit) {
     await materializeDraft();
@@ -1426,6 +1725,17 @@ 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 expression = parseExpressionCommand(command);
+  if (expression) {
+    if (expression.type !== "show" && expression.type !== "invalid")
+      await materializeDraft();
+    const result = applyExpressionCommand(score, requestedTrack, expression);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const tuning = parseTuningCommand(command);
+  if (tuning) return tuningCommand(tuning);
   const synth = parseSynthCommand(command);
   if (synth) {
     if (synth.type !== "synth-list") await materializeDraft();
@@ -1434,6 +1744,34 @@ 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 masterCommand = parseMasterCommand(command);
+  if (masterCommand) {
+    if (masterCommand.type === "master-measure")
+      return ok(await measureLine(score));
+    if (
+      masterCommand.type !== "master-list" &&
+      masterCommand.type !== "master-show"
+    )
+      await materializeDraft();
+    const result = applyMasterCommand(score, masterCommand);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
+  const arrange = parseSectionCommand(command, score);
+  if (arrange) {
+    const reads =
+      arrange.type === "section-list" ||
+      arrange.type === "section-unknown" ||
+      arrange.type === "form-show" ||
+      arrange.type === "section-jump";
+    if (!reads) await materializeDraft();
+    const result = applySectionCommand(score, requestedTrack, arrange);
+    if (result.next && result.kind)
+      await commitScore(result.next, result.kind, result.payload);
+    if (result.seekBeat !== undefined) await seekTransport(result.seekBeat);
+    return result.ok ? ok(result.message) : fail(result.message);
+  }
   const music = parseMusicCommand(command);
   if (music) {
     await materializeDraft();
@@ -1447,6 +1785,15 @@ async function submit(prompt: string): Promise<string | Receipt> {
   const exportCommand = command.match(/^\/?export\s+([^\s]+)$/i);
   if (exportCommand) {
     const path = resolve(exportCommand[1]!);
+    if (/\.midi?$/i.test(path)) {
+      await writeFile(path, scoreToMidi(exportScore(score)));
+      return `exported midi · ${exportCommand[1]}`;
+    }
+    // Audio comes from the offline renderer, never JSON under an audio name.
+    if (/\.(wav|aiff?|flac|mp3|ogg|m4a)$/i.test(path))
+      return fail(
+        `/export writes .track.json or .mid · render audio with: dawg render ${exportCommand[1]}`,
+      );
     await writeFile(path, encodeLoop(score), "utf8");
     return `exported · ${exportCommand[1]}`;
   }
@@ -1563,7 +1910,7 @@ async function submit(prompt: string): Promise<string | Receipt> {
   if (parsed.type === "set-tempo") {
     const next = score.withTempo(parsed.tempoBpm);
     await commitScore(next, "score.tempo", { tempoBpm: parsed.tempoBpm });
-    clock.setTempo?.(next.tempoBpm);
+    clock.follow(next);
     return `tempo · ${next.tempoBpm} BPM`;
   }
   if (parsed.type === "add-track") return focusTrack(parsed.trackId);
@@ -1658,6 +2005,9 @@ async function submit(prompt: string): Promise<string | Receipt> {
       ...(typeof parsed.patch.velocity === "number"
         ? { velocity: parsed.patch.velocity }
         : {}),
+      ...(typeof parsed.patch.cents === "number"
+        ? { cents: parsed.patch.cents }
+        : {}),
     };
     const next = applyScoreOperation(score, {
       type: "updateNote",
@@ -1683,6 +2033,7 @@ async function submit(prompt: string): Promise<string | Receipt> {
       ),
       pitch: parsed.pitch,
       velocity: parsed.velocity,
+      ...(parsed.cents ? { cents: parsed.cents } : {}),
     };
     const operation: ScoreOperation = { type: "addNote", note };
     const next = applyScoreOperation(latestScore, operation);
@@ -1788,6 +2139,40 @@ function reportSampleProblems(value: TrackScore): void {
   });
 }
 
+/** `/tuning …` and `/scale …` (src/commands/tuning.ts). */
+async function tuningCommand(command: TuningCommand): Promise<Receipt> {
+  const projectRoot = process.cwd();
+  if (command.type === "tuning-set") {
+    // Scala files outside the project are copied into tunings/ first.
+    try {
+      const patch = { ...command.patch };
+      if (patch.scl)
+        patch.scl = await importTuningFile(projectRoot, projectRoot, patch.scl);
+      if (patch.kbm)
+        patch.kbm = await importTuningFile(projectRoot, projectRoot, patch.kbm);
+      command = { ...command, patch };
+    } catch (error) {
+      if (error instanceof TuningError)
+        return fail(`tuning · ${error.message}`);
+      throw error;
+    }
+  }
+  if (command.type === "tuning-set" || command.type === "tuning-off")
+    if (command.target === "track") await materializeDraft();
+  const read = (path: string): string | undefined => {
+    try {
+      return readFileSync(join(projectRoot, path), "utf8");
+    } catch {
+      return undefined;
+    }
+  };
+  const result = applyTuningCommand(score, requestedTrack, command, read);
+  if (result.panel) tui.openText(result.panel.title, result.panel.lines);
+  if (result.next && result.kind)
+    await commitScore(result.next, result.kind, result.payload);
+  return result.ok ? ok(result.message) : fail(result.message);
+}
+
 async function sampleCommand(
   command: NonNullable<ReturnType<typeof parseSampleCommand>>,
 ): Promise<Receipt> {
@@ -2357,7 +2742,7 @@ async function switchSession(sessionId: string): Promise<void> {
   audio = port.player;
   record = port.mode === "daemon" ? await port.load() : next.record;
   score = scoreFromJSON(record.composition);
-  clock.setTempo(score.tempoBpm);
+  clock.follow(score);
   const attached = await attachTrack(port, score, undefined);
   requestedTrack = attached.trackId;
   draftTrack = attached.draft;
@@ -2412,6 +2797,8 @@ function menuContext(): MenuContext {
 /** The screen `?` describes, or undefined while `?` is typed text. */
 function keysScreen(): readonly KeySection[] | undefined {
   if (euclid.open) return euclid.typing ? undefined : KEYS.euclid;
+  if (fader && menu.open)
+    return fader.typing !== undefined ? undefined : KEYS.fader;
   if (menu.open) return menu.typing ? undefined : KEYS.menu;
   const overlay = tui.ui.overlay;
   if (overlay === "picker")
@@ -2422,6 +2809,7 @@ function keysScreen(): readonly KeySection[] | undefined {
         : KEYS.list;
   if (overlay === "text") return KEYS.text;
   if (overlay === "log") return KEYS.log;
+  if (overlay === "guide") return tui.guideTyping ? undefined : KEYS.guide;
   if (prompt.value.length > 0) return undefined;
   if (play?.on)
     return play.chords.on ? [...KEYS.play, ...KEYS.chords] : KEYS.play;
@@ -2533,6 +2921,11 @@ function auditionController(): Audition {
       clearTimer: (handle) => clearTimeout(handle as Timer),
       changed: () => requestFrame(),
       level: () => previewEngine().level,
+      // The last loop the engine played is the song's when a loop starts.
+      masterGainDb: () =>
+        score.master?.target === undefined
+          ? undefined
+          : previewEngine().loudness?.gainDb,
       // The chord settings screen loops a progression with its settings.
       phrase: (showing) => {
         if (!chordScreenOpen()) return undefined;
@@ -2875,14 +3268,28 @@ function leaveAuditionScreen(): void {
 
 function refreshMenu(): void {
   noteChordScreen();
-  if (!menu.open) return;
+  if (!menu.open) {
+    closeFader();
+    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());
+  const context = menuContext();
+  if (fader) {
+    const fields = menu.faderFields(context);
+    if (fields.length === 0) closeFader();
+    else
+      tui.drawer = drawerView(fader, fields, menu.faderCommitted(context), {
+        title: menu.crumbs,
+        dirty: context.audition?.dirty ?? false,
+        status: context.audition?.status,
+      });
+  }
+  const view = menu.view(context);
   tui.openPicker({
     id: "menu",
     title: view.title,
@@ -2895,6 +3302,216 @@ function refreshMenu(): void {
   });
 }
 
+// ── the fader drawer ─────────────────────────────────────────────────
+
+/** Enter on a number row (or a bare `volume`, `fx filter`): the drawer. */
+/**
+ * Open the drawer on `label`. `standalone` drawers came from a command or a
+ * click, not from inside the menu, so closing one closes the menu too.
+ */
+function openFader(label: string, standalone = false): void {
+  fader = { label };
+  faderStandalone = standalone;
+  const loop = auditionController();
+  if (!loop.dirtyEdits) loop.committedNow(score);
+}
+
+function closeFader(): void {
+  fader = undefined;
+  tui.drawer = undefined;
+  if (faderStandalone && menu.open) {
+    faderStandalone = false;
+    menu.close();
+    tui.closePicker();
+    stopAuditionLoop();
+  }
+  faderStandalone = false;
+}
+
+function faderKeyOptions(): { dirty: boolean; audition: boolean } {
+  return { dirty: auditionLoop?.dirtyEdits ?? false, audition: true };
+}
+
+/**
+ * Act on a drawer result. A set stages on the audition loop, filed under
+ * its field so every nudge replaces the last: the piano roll (and the loop,
+ * when it plays) follows at once, and Enter keeps them all as one revision.
+ * A setting the loop cannot stage (tempo, loop length) applies directly.
+ */
+function faderOutcome(result: FaderResult): void {
+  if (result.type === "set") {
+    if (!stageableNow(result.command)) {
+      runPromptLater(result.command);
+      return;
+    }
+    const loop = auditionController();
+    if (!loop.dirtyEdits) loop.committedNow(score);
+    const seq = (faderSeq.get(result.key) ?? 0) + 1;
+    faderSeq.set(result.key, seq);
+    void loop
+      .stage(result.command, {
+        replaceKey: result.key,
+        superseded: () => faderSeq.get(result.key) !== seq,
+      })
+      .then((outcome) => {
+        if (!outcome.ok && outcome.message !== SUPERSEDED)
+          tui.activity.pushCard(outcome.message, {
+            tone: outcome.message.includes("failed") ? "error" : "warning",
+          });
+        requestFrame();
+      });
+  } else if (result.type === "keep") {
+    closeFader();
+    void keepStaged()
+      .then((outcome) => receipt(outcome))
+      .catch((error) => tui.activity.pushError(describeError("keep", error)))
+      .finally(() => requestFrame());
+  } else if (result.type === "revert") {
+    revertStaged();
+    closeFader();
+  } else if (result.type === "close") closeFader();
+  else if (result.type === "audition") auditionKeyPressed(result.key);
+}
+
+// ── the mouse ────────────────────────────────────────────────────────
+
+/**
+ * One mouse report, hit-tested against the regions the last frame painted.
+ * Acts directly (a fader, the transport) or returns keys to run through the
+ * ordinary key path (a list row is Enter, a wheel notch is an arrow).
+ */
+function mouseInput(event: MouseEvent): string[] {
+  const frame = tui.frame;
+  if (!frame) return [];
+  const target = frame.hits.at(event.x, event.y)?.target;
+  if (event.kind === "wheel") {
+    const fields = fader && menu.open ? menu.faderFields(menuContext()) : [];
+    if (
+      fader &&
+      target &&
+      (target.kind === "fader-bar" ||
+        target.kind === "fader-row" ||
+        target.kind === "fader-step" ||
+        target.kind === "fader-option")
+    ) {
+      // Wheel up raises the value under the pointer.
+      faderOutcome(
+        faderStep(
+          fader,
+          fields[target.field],
+          event.delta < 0 ? 1 : -1,
+          event.shift ? "coarse" : "normal",
+        ),
+      );
+      refreshMenu();
+      return [];
+    }
+    if (fader) return [];
+    if (tui.ui.overlay) return [event.delta < 0 ? KEY_UP : KEY_DOWN];
+    return [];
+  }
+  // A drag keeps moving the fader it started on, even past the bar's ends.
+  if (event.kind === "drag" && event.button === "left" && fader && dragging) {
+    const fields = menu.faderFields(menuContext());
+    faderOutcome(
+      faderSetPosition(
+        fader,
+        fields[dragging.field],
+        (event.x - dragging.left) / Math.max(1, dragging.width - 1),
+      ),
+    );
+    refreshMenu();
+    return [];
+  }
+  if (event.kind === "up") {
+    dragging = undefined;
+    return [];
+  }
+  if (event.kind !== "down" || event.button !== "left" || !target) return [];
+  if (fader && menu.open) {
+    const fields = menu.faderFields(menuContext());
+    let result: FaderResult | undefined;
+    switch (target.kind) {
+      case "fader-step":
+        result = faderStep(
+          fader,
+          fields[target.field],
+          target.direction,
+          event.shift ? "coarse" : "normal",
+        );
+        break;
+      case "fader-bar":
+        dragging = target;
+        result = faderSetPosition(
+          fader,
+          fields[target.field],
+          (event.x - target.left) / Math.max(1, target.width - 1),
+        );
+        break;
+      case "fader-option":
+        result = faderChoose(fader, fields[target.field], target.option);
+        break;
+      case "fader-row": {
+        const field = fields[target.field];
+        if (field) {
+          fader.label = field.label;
+          fader.typing = undefined;
+        }
+        result = { type: "handled" };
+        break;
+      }
+      case "fader-keep":
+        result = auditionLoop?.dirtyEdits
+          ? { type: "keep" }
+          : { type: "close" };
+        break;
+      case "fader-revert":
+        result = auditionLoop?.dirtyEdits
+          ? { type: "revert" }
+          : { type: "close" };
+        break;
+      default:
+        break;
+    }
+    if (result) {
+      faderOutcome(result);
+      refreshMenu();
+      return [];
+    }
+  }
+  switch (target.kind) {
+    case "picker-row": {
+      const picker = tui.ui.picker;
+      if (!picker) return [];
+      if (picker.id === "menu" && menu.open) {
+        // The first click selects a row; a click on the selected row opens it.
+        const again = menu.index === target.index;
+        menu.select(menuContext(), target.index);
+        refreshMenu();
+        return again ? ["\r"] : [];
+      }
+      const again = picker.index === target.index;
+      picker.index = target.index;
+      picker.filtering = false;
+      return again ? ["\r"] : [];
+    }
+    case "transport":
+      if (tui.ui.overlay) return [];
+      void toggleTransport().finally(() => requestFrame());
+      return [];
+    case "tracks":
+      if (tui.ui.overlay) return [];
+      runPromptLater("/tracks");
+      return [];
+    case "model":
+      if (tui.ui.overlay) return [];
+      runPromptLater("/model");
+      return [];
+    default:
+      return [];
+  }
+}
+
 function playSession(): PlaySession {
   if (play && play.track === requestedTrack) return play;
   const previous = play;
@@ -2966,6 +3583,7 @@ function playHost() {
     now: () => performance.now(),
     playing: () => clock.playing,
     beatAt: (ms: number) => clock.beatAt(ms),
+    scoreBeat: (beat: number) => scoreBeatAt(score, beat),
     engine: liveEngine,
     samples: () => liveSampleBank,
     async commit(
@@ -3032,20 +3650,33 @@ async function commitScore(
   // 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);
+  const retimed = timingChanged(score, next);
   if (stageCapture) {
     // A staged edit: the audition plays it; nothing is written yet.
     stageCapture.next = next;
     score = next;
+    if (retimed) clock.follow(score);
     return;
   }
   record = await port.append(record, { kind, payload }, next.toJSON());
   score = next;
+  if (retimed) clock.follow(score);
   if (clock.playing) void audio.play(score);
   projectSync?.scoreChanged(score);
   reportSampleProblems(score);
   void updateCredits(score);
 }
 
+/** True when the transport clock must follow `next` (tempo, meter, loop). */
+function timingChanged(previous: TrackScore, next: TrackScore): boolean {
+  return (
+    previous.time !== next.time ||
+    previous.tempoBpm !== next.tempoBpm ||
+    previous.beatsPerBar !== next.beatsPerBar ||
+    previous.bars !== next.bars
+  );
+}
+
 /** The window's side of the project file sync (see src/project/sync.ts). */
 function syncHost(): SyncHost {
   return {
@@ -3063,7 +3694,7 @@ function syncHost(): SyncHost {
         plan.next.toJSON(),
       );
       score = scoreFromJSON(record.composition);
-      clock.setTempo(score.tempoBpm);
+      clock.follow(score);
       if (clock.playing) void audio.play(score);
       reportSampleProblems(score);
       void baseRevision;
@@ -3170,6 +3801,17 @@ async function setTransport(
   }
 }
 
+/** Move the playhead to transport `beat`, playing or not (section jump). */
+async function seekTransport(beat: number): Promise<void> {
+  if (port.mode === "daemon") {
+    await port.transport("seek", { beat });
+    return;
+  }
+  const now = Date.now();
+  clock.sync(beat, clock.playing, now, now);
+  if (clock.playing) await audio.play(score, clock.beatAt());
+}
+
 /**
  * Run one streaming tool-calling turn. Each validated tool call commits its
  * own revision through `agentHost`, so cancelling keeps every accepted change
@@ -3274,6 +3916,25 @@ function mediaServices(): MediaServices {
   return { runner: systemRunner, env: process.env };
 }
 
+/**
+ * `master measure`: render the song as the loop that plays and measure
+ * loudness, peaks and balance at the export rate. The render, master and
+ * meter run in a worker (`measureScoreOffThread`), so the header, input and
+ * playback keep going on a long loop.
+ */
+async function measureLine(value: TrackScore): Promise<string> {
+  await sampleProblems(value);
+  tui.activity.setSpinner("measuring");
+  try {
+    const measured = await measureScoreOffThread(value, {
+      projectRoot: process.cwd(),
+    });
+    return `master measure · ${measurementLine(measured.mix, measured.master)} · ${measured.sampleRate / 1000} kHz`;
+  } finally {
+    tui.activity.setSpinner(undefined);
+  }
+}
+
 /**
  * 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
@@ -3288,6 +3949,16 @@ function agentPreviewHost(): PreviewHost {
         ...(liveSampleBank ? { samples: liveSampleBank } : {}),
       });
     },
+    // Off the UI thread, at the export rate (see measureLine).
+    measure: async (value, options) => {
+      await sampleProblems(value);
+      return measureScoreOffThread(value, {
+        projectRoot: process.cwd(),
+        ...(options?.sampleRate === undefined
+          ? {}
+          : { sampleRate: options.sampleRate }),
+      });
+    },
     play: async (rendered) => {
       if (!agentPreviewPlays || clock.playing || auditionLoop?.looping)
         return false;
@@ -3356,8 +4027,13 @@ function agentHost(
           );
         throw error;
       }
-      if (change.operations.some((operation) => operation.type === "setTempo"))
-        clock.setTempo(score.tempoBpm);
+      if (
+        change.operations.some(
+          (operation) =>
+            operation.type === "setTempo" || operation.type === "setTime",
+        )
+      )
+        clock.follow(score);
       return { revision: record.revision };
     },
     async transport(action) {