@hraness/dawg 0.3.0 → 0.4.1

package/src/tui/play-session.ts

@@ -9,6 +9,11 @@
  * (`addNote`, plus `removeNote` when replacing), committed once per bar as
  * the playhead leaves it: one undo entry per recorded bar, synced to other
  * windows and the project files like any other edit.
+ *
+ * Chord mode (play-chords.ts) turns a note key into a voiced chord: every
+ * voice sounds through the same live path, strums and arpeggios are paced by
+ * `tick()`, and a recorded chord is laid out with core/chords.ts `perform`
+ * so the score holds exactly what an agent's `write_chords` would write.
  */
 import {
   applyScoreOperation,
@@ -23,9 +28,25 @@ import {
   type LiveNotePcm,
 } from "../audio/live.ts";
 import type { SampleBank } from "../audio/samples.ts";
+import {
+  DEFAULT_STRUM,
+  perform,
+  type PerformMode,
+  type PerformedNote,
+} from "../../core/chords.ts";
+import {
+  ChordPad,
+  chordCapable,
+  defaultChordSettings,
+  songKey,
+  type ChordSettings,
+  type PlayedChord,
+} from "./play-chords.ts";
 import type { PlayHeaderView, PlayStripKey } from "../../tui/play-strip.ts";
 import {
+  NOTE_KEYS,
   PlayKeyboard,
+  REPEAT_DELAY_MS,
   playLayoutFor,
   stripCells,
   type PlayAction,
@@ -101,8 +122,41 @@ type Pending = {
   /** Unwrapped transport beat of the press. */
   beat: number;
   releaseAtMs: number;
+  /** Set when the key played a chord: laid out with `perform` on flush. */
+  chord?: RecordedChord;
+};
+
+/** What a recorded chord press expands to. */
+export type RecordedChord = Readonly<{
+  pitches: readonly number[];
+  bass?: number | undefined;
+  mode: PerformMode;
+  /** Arp step in beats. */
+  rate: number;
+  octaves: number;
+  seed: number;
+  /** CHORD_PATTERNS name when `mode` is `pattern`. */
+  pattern?: string;
+}>;
+
+/** A chord sounding live: its voices start and stop from `tick()`. */
+type LiveChord = {
+  played: PlayedChord;
+  velocity: number;
+  startMs: number;
+  releaseAtMs: number;
+  /** Voices in beats from the press, sorted by start. */
+  plan: PerformedNote[];
+  next: number;
+  /** Live voice id → its plan index, start and own end (Infinity: the key's). */
+  sounding: Map<number, { index: number; atMs: number; endMs: number }>;
 };
 
+/** Beats a held live chord's plan covers (arps keep stepping this long). */
+const LIVE_PLAN_BEATS = 64;
+/** Live chord voices use ids far above the keyboard's. */
+const VOICE_ID_BASE = 1_000_000_000;
+
 type CountIn = { startMs: number; beats: number; startBeat: number };
 
 export type PlayKeyResult =
@@ -133,6 +187,12 @@ export class PlaySession {
   /** Most recent key-to-sound schedule, ms (lead before device latency). */
   public lastLatencyMs: number | undefined;
   private readonly trackId: string;
+  public readonly chords: ChordPad;
+  private readonly liveChords = new Map<number, LiveChord>();
+  private nextVoiceId = VOICE_ID_BASE;
+  /** The `n` key's last route, so its auto-repeats hold one chord. */
+  private nRoute:
+    { key: string; chord: PlayedChord["chord"]; atMs: number } | undefined;
 
   /** The track this session plays and records into. */
   public get track(): string {
@@ -141,10 +201,20 @@ export class PlaySession {
 
   public constructor(
     private readonly host: PlayHost,
-    options: Readonly<{ clickOn?: boolean; clickVolume?: number }> = {},
+    options: Readonly<{
+      clickOn?: boolean;
+      clickVolume?: number;
+      chords?: ChordSettings;
+    }> = {},
   ) {
     this.trackId = host.trackId();
-    this.layout = playLayoutFor(this.trackData());
+    const track = this.trackData();
+    this.layout = playLayoutFor(track);
+    const settings = options.chords ?? defaultChordSettings();
+    // Auto chords by default on chord-capable tracks, until chosen by hand.
+    if (!settings.explicit)
+      settings.mode = chordCapable(track) ? "auto" : "manual";
+    this.chords = new ChordPad(settings, () => this.host.score().key);
     this.keyboard = new PlayKeyboard({ base: this.layout.base });
     this.clickOn = options.clickOn ?? false;
     this.clickVolume = options.clickVolume ?? DEFAULT_CLICK_VOLUME;
@@ -250,10 +320,39 @@ export class PlaySession {
   /** Handle one decoded key; mode commands return to the caller. */
   public press(value: string): PlayKeyResult {
     const now = this.host.now();
-    const action = this.keyboard.press(value, now, this.gateMs());
+    let key = value;
+    if (this.chords.on && value === "n") {
+      // Route the suggestion through the note key of its root, so holding
+      // `n` sustains it like any held key.
+      const route =
+        this.nRoute && now - this.nRoute.atMs <= REPEAT_DELAY_MS
+          ? this.nRoute
+          : { ...this.nextRoute(), atMs: now };
+      route.atMs = now;
+      this.nRoute = route;
+      this.chords.force(route.chord);
+      key = route.key;
+    } else {
+      const pad = this.chords.press(value);
+      if (pad.type === "status") {
+        this.status = pad.status;
+        return { type: "handled" };
+      }
+    }
+    const action = this.keyboard.press(key, now, this.gateMs());
     return this.apply(action, now);
   }
 
+  /** The suggested next chord and the lowest note key on its root. */
+  private nextRoute(): { key: string; chord: PlayedChord["chord"] } {
+    const chord = this.chords.next();
+    const keys = Object.entries(NOTE_KEYS).sort((a, b) => a[1] - b[1]);
+    const found = keys.find(
+      ([, offset]) => (this.keyboard.base + offset - chord.root) % 12 === 0,
+    );
+    return { key: found?.[0] ?? "a", chord };
+  }
+
   private apply(action: PlayAction, now: number): PlayKeyResult {
     switch (action.type) {
       case "unmapped":
@@ -272,18 +371,44 @@ export class PlaySession {
         this.release(action.released, action.atMs);
         this.status = action.on ? "sustain latched" : "sustain off";
         return { type: "handled" };
-      case "note":
+      case "note": {
         this.release(action.released, now);
+        const chord = this.chords.chordFor(action.note.pitch);
+        if (chord) {
+          const played = this.chords.voice(chord, action.note.pitch);
+          this.startChord(action.note, played);
+          this.record(action.note, this.recordedChord(played, action.note.id));
+          this.status = played.name;
+          return { type: "handled" };
+        }
+        // Bass modes that sound bass under single notes (unison, single, solo).
+        const single = this.chords.single(action.note.pitch);
+        if (single) {
+          this.startChord(action.note, single, "block");
+          this.record(
+            action.note,
+            this.recordedChord(single, action.note.id, "block"),
+          );
+          return { type: "handled" };
+        }
         this.sound(action.note.id, action.note);
         this.record(action.note);
         return { type: "handled" };
+      }
       case "extend": {
         const pending = this.pending.get(action.id);
         if (action.absorbed !== undefined) {
           this.host.engine()?.noteOff(action.absorbed);
+          this.stopChord(action.absorbed);
           this.pending.delete(action.absorbed);
         }
         if (pending) pending.releaseAtMs = action.releaseAtMs;
+        const live = this.liveChords.get(action.id);
+        if (live) {
+          live.releaseAtMs = action.releaseAtMs;
+          this.resoundChord(live);
+          return { type: "handled" };
+        }
         const pitch = this.keyboard.pitchFor(action.key);
         if (pitch !== undefined)
           this.sound(action.id, {
@@ -347,6 +472,8 @@ export class PlaySession {
     const engine = this.host.engine();
     for (const id of ids) {
       engine?.noteOff(id);
+      const live = this.liveChords.get(id);
+      if (live) live.releaseAtMs = Math.min(live.releaseAtMs, atMs);
       const pending = this.pending.get(id);
       if (pending) pending.releaseAtMs = atMs;
     }
@@ -356,7 +483,7 @@ export class PlaySession {
     return this.armed && this.host.playing() && this.countIn === undefined;
   }
 
-  private record(note: PlayedNote): void {
+  private record(note: PlayedNote, chord?: RecordedChord): void {
     if (!this.recording) return;
     this.pending.set(note.id, {
       id: note.id,
@@ -365,6 +492,142 @@ export class PlaySession {
       atMs: note.atMs,
       beat: this.host.beatAt(note.atMs),
       releaseAtMs: note.releaseAtMs,
+      ...(chord ? { chord } : {}),
+    });
+  }
+
+  private recordedChord(
+    played: PlayedChord,
+    seed: number,
+    mode: PerformMode = this.chords.settings.perform,
+  ): RecordedChord {
+    const settings = this.chords.settings;
+    return {
+      pitches: played.pitches,
+      bass: played.bass,
+      mode,
+      rate: this.chords.rateBeats(this.gridStep),
+      octaves: settings.octaves,
+      seed,
+      ...(mode === "pattern" ? { pattern: settings.pattern } : {}),
+    };
+  }
+
+  // ── live chords ──────────────────────────────────────────────────────
+
+  private startChord(
+    note: PlayedNote,
+    played: PlayedChord,
+    mode: PerformMode = this.chords.settings.perform,
+  ): void {
+    const settings = this.chords.settings;
+    // Velocity 1: pattern hits carry their own accents, scaled by the press.
+    const plan = perform(played.pitches, 0, LIVE_PLAN_BEATS, {
+      mode,
+      rate: this.chords.rateBeats(this.gridStep),
+      octaves: settings.octaves,
+      strum: mode === "harp" ? DEFAULT_STRUM * 2 : DEFAULT_STRUM,
+      seed: note.id,
+      pattern: settings.pattern,
+      velocity: 1,
+    });
+    if (played.bass !== undefined)
+      plan.push({
+        pitch: played.bass,
+        start: 0,
+        length: LIVE_PLAN_BEATS,
+        velocity: 1,
+      });
+    plan.sort((a, b) => a.start - b.start);
+    this.liveChords.set(note.id, {
+      played,
+      velocity: note.velocity,
+      startMs: note.atMs,
+      releaseAtMs: note.releaseAtMs,
+      plan,
+      next: 0,
+      sounding: new Map(),
+    });
+    this.pumpChords(this.host.now());
+  }
+
+  private stopChord(id: number): void {
+    const live = this.liveChords.get(id);
+    if (!live) return;
+    const engine = this.host.engine();
+    for (const voice of live.sounding.keys()) engine?.noteOff(voice);
+    this.liveChords.delete(id);
+  }
+
+  private beatMs(): number {
+    return 60_000 / this.host.score().tempoBpm;
+  }
+
+  /** Start due voices, end finished ones, drop released chords. */
+  private pumpChords(now: number): void {
+    if (this.liveChords.size === 0) return;
+    const engine = this.host.engine();
+    const beatMs = this.beatMs();
+    for (const [id, live] of this.liveChords) {
+      for (const [voice, state] of live.sounding)
+        if (state.endMs <= now || live.releaseAtMs <= now) {
+          engine?.noteOff(voice);
+          live.sounding.delete(voice);
+        }
+      while (live.next < live.plan.length) {
+        const planned = live.plan[live.next]!;
+        const atMs = live.startMs + planned.start * beatMs;
+        if (atMs > now || atMs >= live.releaseAtMs) break;
+        live.next += 1;
+        const endMs = live.startMs + (planned.start + planned.length) * beatMs;
+        // Notes that ring to the end of the plan follow the key instead.
+        const own = planned.start + planned.length < LIVE_PLAN_BEATS - 1e-6;
+        const voice = this.nextVoiceId++;
+        live.sounding.set(voice, {
+          index: live.next - 1,
+          atMs,
+          endMs: own ? endMs : Infinity,
+        });
+        this.soundVoice(
+          voice,
+          live,
+          planned,
+          atMs,
+          own ? endMs : live.releaseAtMs,
+        );
+      }
+      const exhausted =
+        live.next >= live.plan.length ||
+        live.startMs + live.plan[live.next]!.start * beatMs >= live.releaseAtMs;
+      if (live.releaseAtMs <= now || (exhausted && live.sounding.size === 0))
+        this.stopChord(id);
+    }
+  }
+
+  /** A held chord's release moved: re-render the voices that follow it. */
+  private resoundChord(live: LiveChord): void {
+    for (const [voice, state] of live.sounding)
+      if (!Number.isFinite(state.endMs)) {
+        const planned = live.plan[state.index]!;
+        this.soundVoice(voice, live, planned, state.atMs, live.releaseAtMs);
+      }
+  }
+
+  private soundVoice(
+    voice: number,
+    live: LiveChord,
+    planned: Readonly<{ pitch: number; velocity: number }>,
+    atMs: number,
+    endMs: number,
+  ): void {
+    this.sound(voice, {
+      id: voice,
+      key: "",
+      pitch: planned.pitch,
+      velocity: scaleVelocity(live.velocity, planned.velocity),
+      atMs,
+      releaseAtMs: endMs,
+      sustain: !Number.isFinite(endMs),
     });
   }
 
@@ -396,6 +659,7 @@ export class PlaySession {
   public tick(): void {
     if (!this.active) return;
     const now = this.host.now();
+    this.pumpChords(now);
     const count = this.countIn;
     if (count) {
       const beatMs = 60_000 / this.host.score().tempoBpm;
@@ -468,15 +732,27 @@ export class PlaySession {
     for (const pending of ready) this.pending.delete(pending.id);
     const operations = recordOperations(score, {
       trackId: this.trackId,
-      notes: ready.map((pending) => ({
-        pitch: pending.pitch,
-        velocity: pending.velocity,
-        beat: pending.beat,
-        beats:
+      notes: ready.flatMap((pending) => {
+        const beats =
           ((Math.min(pending.releaseAtMs, now) - pending.atMs) *
             score.tempoBpm) /
-          60_000,
-      })),
+          60_000;
+        return pending.chord
+          ? chordNotes(pending.chord, {
+              beat: pending.beat,
+              beats,
+              velocity: pending.velocity,
+              grid: this.gridStep,
+            })
+          : [
+              {
+                pitch: pending.pitch,
+                velocity: pending.velocity,
+                beat: pending.beat,
+                beats,
+              },
+            ];
+      }),
       grid: this.gridStep,
       eraseBars: erase,
       keep: this.recordedIds,
@@ -535,17 +811,37 @@ export class PlaySession {
       countIn,
       beat,
       grid: `grid ${this.grid}`,
+      chords: this.chords.glance(songKey(this.host.score().key).set),
       status: this.status,
       keys: this.strip(now),
+      legend: this.chords.on ? this.chords.legend() : undefined,
     };
   }
 
+  /** Secondary state for the `?` panel (kept out of the header). */
+  public details(): string[] {
+    const keySet = songKey(this.host.score().key).set;
+    return [
+      `velocity ${this.keyboard.velocity} · grid ${this.grid} · click ${this.clickOn ? "on" : "off"} · count-in ${this.countInBars} bar${this.countInBars === 1 ? "" : "s"}`,
+      ...(this.chords.on ? [`chords ${this.chords.headerText(keySet)}`] : []),
+    ];
+  }
+
   public strip(now = this.host.now()): PlayStripKey[] {
     return stripCells(
       this.keyboard,
       this.keyboard.litKeys(now),
       this.layout.labels,
-    ).map((cell) => ({
+    ).map((cell) => {
+      const chord = this.keyboard.pitchFor(cell.key);
+      const name =
+        chord === undefined ? undefined : this.chords.keyLabel(chord);
+      return name ? { ...cell, label: name } : this.noteCell(cell);
+    });
+  }
+
+  private noteCell(cell: PlayStripKey): PlayStripKey {
+    return {
       ...cell,
       // Octave digits only on C keep 18 keys inside 80 columns.
       label:
@@ -553,7 +849,7 @@ export class PlaySession {
         (cell.label.startsWith("C") && !cell.label.startsWith("C#"))
           ? cell.label
           : cell.label.replace(/-?\d+$/, ""),
-    }));
+    };
   }
 }
 
@@ -565,8 +861,57 @@ export type RecordedNote = Readonly<{
   beat: number;
   /** Held length in beats. */
   beats: number;
+  /** Already on the grid (a laid-out chord voice): keep beat and length. */
+  exact?: boolean;
 }>;
 
+/** A press velocity (1..127) times a pattern accent (0..1), at least 1. */
+function scaleVelocity(velocity: number, accent: number): number {
+  return accent >= 1 ? velocity : Math.max(1, Math.round(velocity * accent));
+}
+
+/**
+ * A recorded chord press as notes: the press snaps to `grid`, its held
+ * length rounds to whole grid steps (at least one), and `perform` lays the
+ * voices out inside it; the bass holds the whole length.
+ */
+export function chordNotes(
+  chord: RecordedChord,
+  press: Readonly<{
+    beat: number;
+    beats: number;
+    velocity: number;
+    grid: number;
+  }>,
+): RecordedNote[] {
+  const start = quantize(press.beat, press.grid);
+  const length = Math.max(press.grid, quantize(press.beats, press.grid));
+  const notes = perform(chord.pitches, start, length, {
+    mode: chord.mode,
+    rate: chord.rate,
+    octaves: chord.octaves,
+    strum: chord.mode === "harp" ? DEFAULT_STRUM * 2 : DEFAULT_STRUM,
+    seed: chord.seed,
+    ...(chord.pattern !== undefined ? { pattern: chord.pattern } : {}),
+    velocity: 1,
+  }).map((note) => ({
+    pitch: note.pitch,
+    velocity: scaleVelocity(press.velocity, note.velocity),
+    beat: note.start,
+    beats: note.length,
+    exact: true,
+  }));
+  if (chord.bass !== undefined)
+    notes.push({
+      pitch: chord.bass,
+      velocity: press.velocity,
+      beat: start,
+      beats: length,
+      exact: true,
+    });
+  return notes;
+}
+
 /**
  * The ScoreOperations one recorded bar commits: notes quantized to `grid`
  * and wrapped into the loop (overdub), plus removals of existing notes that
@@ -608,9 +953,12 @@ export function recordOperations(
       .map((note) => `${note.pitch}:${note.startTick}`),
   );
   for (const note of options.notes) {
-    let start = quantize(note.beat, options.grid) % loopBeats;
+    let start =
+      (note.exact ? note.beat : quantize(note.beat, options.grid)) % loopBeats;
     if (start < 0) start += loopBeats;
-    const beats = Math.max(options.grid, quantize(note.beats, options.grid));
+    const beats = note.exact
+      ? note.beats
+      : Math.max(options.grid, quantize(note.beats, options.grid));
     const startTick = Math.round(start * tpb);
     const durationTicks = Math.max(
       1,

package/src/tui/sketch.ts

@@ -0,0 +1,108 @@
+/**
+ * One-line response sketches for the focused menu row: a filter curve for
+ * a cutoff, the envelope shape for attack/decay/sustain/release, and the
+ * position inside a wavetable. Sixteen cells, so they sit beside the row's
+ * note at 80 columns. Pure and cheap: they run once per menu view.
+ */
+
+const CELLS = 16;
+const LEVELS = "▁▂▃▄▅▆▇█";
+
+/** The parameter a menu command sets: `fx filter cutoff 800` → cutoff. */
+export function commandParam(command: string): string | undefined {
+  const words = command.trim().split(/\s+/);
+  if (words.length < 2) return undefined;
+  const key = words.at(-2)!.toLowerCase();
+  return /^[a-z][a-z0-9]*$/.test(key) ? key : undefined;
+}
+
+/** Low- or high-pass response over 20 Hz..20 kHz on a log axis. */
+export function filterSketch(hz: number, highpass = false): string {
+  const at = Math.round(
+    ((CELLS - 1) * Math.log(Math.max(20, Math.min(20_000, hz)) / 20)) /
+      Math.log(1000),
+  );
+  let out = "";
+  for (let cell = 0; cell < CELLS; cell += 1) {
+    const past = highpass ? at - cell : cell - at;
+    out += past < 0 ? "▇" : past === 0 ? "▅" : past === 1 ? "▂" : "▁";
+  }
+  return out;
+}
+
+/** ADSR amplitude over time; sustain is held for a quarter of the rest. */
+export function envelopeSketch(
+  attack: number,
+  decay: number,
+  sustain: number,
+  release: number,
+): string {
+  const a = Math.max(0, attack);
+  const d = Math.max(0, decay);
+  const r = Math.max(0, release);
+  const s = Math.max(0, Math.min(1, sustain));
+  const hold = Math.max(0.05, 0.25 * (a + d + r));
+  const total = a + d + hold + r;
+  let out = "";
+  for (let cell = 0; cell < CELLS; cell += 1) {
+    const t = ((cell + 0.5) / CELLS) * total;
+    const amp =
+      t < a
+        ? t / a
+        : t < a + d
+          ? 1 - ((t - a) / d) * (1 - s)
+          : t < a + d + hold
+            ? s
+            : r > 0
+              ? s * (1 - (t - a - d - hold) / r)
+              : 0;
+    out += LEVELS[Math.round(Math.max(0, Math.min(1, amp)) * 7)]!;
+  }
+  return out;
+}
+
+/** A marker at `value` in min..max. */
+export function positionSketch(value: number, min = 0, max = 1): string {
+  const span = max - min || 1;
+  const at = Math.round(
+    (CELLS - 1) * Math.max(0, Math.min(1, (value - min) / span)),
+  );
+  return "─".repeat(at) + "●" + "─".repeat(CELLS - 1 - at);
+}
+
+const ENVELOPE = new Set(["attack", "decay", "sustain", "release"]);
+
+/**
+ * The sketch for a focused number row, or undefined when it has none.
+ * `valueOf` reads sibling rows by parameter (the other envelope stages);
+ * `filterType` is the filter's type row (a band-pass draws no sketch).
+ */
+export function sketchFor(
+  command: string,
+  value: number,
+  valueOf: (param: string) => number | undefined,
+  filterType = "lpf",
+): string | undefined {
+  const param = commandParam(command);
+  if (!param) return undefined;
+  if (param === "cutoff")
+    return filterType === "hpf"
+      ? filterSketch(value, true)
+      : filterType === "lpf"
+        ? filterSketch(value)
+        : undefined;
+  if (param === "lpf") return filterSketch(value);
+  if (param === "hpf") return filterSketch(value, true);
+  if (param === "wt") return positionSketch(value);
+  if (ENVELOPE.has(param)) {
+    const stage = (name: string, fallback: number) =>
+      name === param ? value : (valueOf(name) ?? fallback);
+    return envelopeSketch(
+      stage("attack", 0.01),
+      stage("decay", 0.1),
+      stage("sustain", 0.7),
+      stage("release", 0.2),
+    );
+  }
+  return undefined;
+}

package/src/web/search.ts

@@ -400,7 +400,10 @@ async function gatewaySearch(
   options.onSpend?.({
     provider: "gateway",
     tool,
-    usd: round(SEARCH_TOOL_USD[tool] + reportedCost(json)),
+    // The gateway's reported cost already includes the search tool fee
+    // (captured 2026-10-07: cost 0.013273 = inference 0.006273 + exa 0.007),
+    // so the fee is only an estimate when no cost is reported.
+    usd: round(reportedCost(json) || SEARCH_TOOL_USD[tool]),
   });
   return { provider: "gateway", tool, results };
 }