@hraness/dawg 0.2.0 → 0.4.0

package/tui/drums.ts

@@ -3,6 +3,11 @@
  * (kick, snare, clap, rim, tom, hat, open hat) instead of by pitch.
  */
 import { DRUM_VOICES, drumLane, isDrumInstrument } from "../core/drums.ts";
+import {
+  isSamplerInstrument,
+  samplerVoiceSlots,
+  type Track,
+} from "../core/score.ts";
 import type { NoteSnapshot, TrackScoreSnapshot } from "./render.ts";
 
 export function drumSnapshotFields(
@@ -19,3 +24,42 @@ export function drumSnapshotFields(
     })),
   };
 }
+
+/**
+ * Sampler adapter: oneshot samplers stream one lane per voice (named, in
+ * pitch-slot order from 36); keyed samplers keep the pitch axis, labelled by
+ * note name like any melodic track.
+ */
+export function samplerSnapshotFields(
+  track: Pick<Track, "instrument" | "sampler"> | undefined,
+  notes: readonly NoteSnapshot[],
+): Partial<TrackScoreSnapshot> {
+  const lanes = samplerLanes(track);
+  if (!lanes) return {};
+  return {
+    laneCount: lanes.labels.length,
+    laneLabels: lanes.labels,
+    notes: notes.flatMap((note) => {
+      const lane = lanes.laneOf(note.pitch ?? -1);
+      return lane === undefined ? [] : [{ ...note, lane }];
+    }),
+  };
+}
+
+/** Oneshot sampler lanes, or undefined for keyed/non-sampler tracks. */
+export function samplerLanes(
+  track: Pick<Track, "instrument" | "sampler"> | undefined,
+):
+  | { labels: string[]; laneOf: (pitch: number) => number | undefined }
+  | undefined {
+  if (!track || !isSamplerInstrument(track.instrument) || !track.sampler)
+    return undefined;
+  if (track.sampler.mode !== "oneshot") return undefined;
+  const slots = [...samplerVoiceSlots(track.sampler)];
+  if (slots.length === 0) return undefined;
+  const byPitch = new Map(slots.map(([, slot], index) => [slot, index]));
+  return {
+    labels: slots.map(([voice]) => voice),
+    laneOf: (pitch) => byPitch.get(pitch),
+  };
+}

package/tui/grammar.ts

@@ -0,0 +1,281 @@
+/**
+ * The shared key grammar: one vocabulary for every picker, editor and menu,
+ * the one-line footer hint each screen shows, and the `?` panel listing the
+ * keys of the current screen.
+ *
+ *   ↑↓ (j k)        move              Enter   open or confirm
+ *   ←→ (h l, - +)   adjust a value    Space   audition or toggle
+ *   /               filter            Esc     back one level (filter first)
+ *   ?               keys for this screen
+ *   digits          type a value, only where a value is focused
+ *
+ * Play mode is the one exception (its letters are piano keys, by the
+ * GarageBand "Musical Typing" convention); its panel says so.
+ */
+import { displayWidth } from "./text.ts";
+
+/** A `key  action` pair for the `?` panel. */
+export type KeyRow = readonly [keys: string, action: string];
+export type KeySection = Readonly<{ title: string; rows: readonly KeyRow[] }>;
+
+/**
+ * Fit a ` a · b · esc back · ? keys ` hint into `width` columns by dropping
+ * parts from the middle: the way out (`esc …`) and `? keys` stay longest,
+ * since they are how a user leaves or learns the rest. Returns "" when not
+ * even `? keys` fits.
+ */
+export function fitHint(hint: string, width: number): string {
+  const key = `${width}\u0000${hint}`;
+  const cached = fitted.get(key);
+  if (cached !== undefined) return cached;
+  const text = fitHintUncached(hint, width);
+  if (fitted.size > 256) fitted.clear();
+  fitted.set(key, text);
+  return text;
+}
+
+/** Hints repeat every frame; fit each (hint, width) once. */
+const fitted = new Map<string, string>();
+
+function fitHintUncached(hint: string, width: number): string {
+  const parts = hint
+    .trim()
+    .split(" · ")
+    .filter((part) => part.length > 0);
+  if (parts.length === 0) return "";
+  const tailAt = parts.findIndex(
+    (part) => part.startsWith("esc ") || part.startsWith("? "),
+  );
+  const head = tailAt < 0 ? parts.slice(0, -1) : parts.slice(0, tailAt);
+  const tail = tailAt < 0 ? parts.slice(-1) : parts.slice(tailAt);
+  for (;;) {
+    const text = ` ${[...head, ...tail].join(" · ")} `;
+    if (displayWidth(text) <= width) return text;
+    if (head.length > 0) head.pop();
+    else if (tail.length > 1) tail.shift();
+    else return "";
+  }
+}
+
+/** The ASCII spelling of a hint, for terminals without Unicode arrows. */
+export function asciiHint(hint: string): string {
+  return hint
+    .replace(/↑↓/g, "up/dn")
+    .replace(/←→/g, "lt/rt")
+    .replace(/–/g, "-");
+}
+
+// ── footer hints, one per screen ──────────────────────────────────────
+
+export const HINTS = {
+  list: " ↑↓ move · enter choose · / filter · esc back · ? keys ",
+  preview: " ↑↓ preview · enter apply · / filter · esc back · ? keys ",
+  hover: " ↑↓ hear · enter choose · a A/B · c context · esc back · ? keys ",
+  audition:
+    " ↑↓ hear · enter keep · space loop · a A/B · c mix · / filter · esc back · ? keys ",
+  filtering: " type to filter · enter choose · esc clear · ? keys ",
+  menu: " ↑↓ move · enter open · / filter · esc back · ? keys ",
+  value: " ←→ adjust · enter type · x reset · esc back · ? keys ",
+  point: " ←→ adjust · enter type · x delete · esc back · ? keys ",
+  action: " ↑↓ move · enter apply · / filter · esc back · ? keys ",
+  typing: " type a value · enter apply · esc cancel ",
+  euclid:
+    " ↑↓ voice · ←→ adjust · tab field · space hear · x off · esc back · ? keys ",
+  text: " ↑↓ scroll · pgup pgdn page · esc back · ? keys ",
+  log: " ↑↓ scroll · / filter · esc back · ? keys ",
+  keys: " any key closes ",
+} as const;
+
+// ── the `?` panel ─────────────────────────────────────────────────────
+
+const LIST: readonly KeyRow[] = [
+  ["↑ ↓  j k", "move"],
+  ["pgup pgdn", "page"],
+  ["enter", "choose"],
+  ["/", "filter (type, then enter or esc)"],
+  ["esc", "clear the filter, then back"],
+];
+
+export const KEYS = {
+  prompt: [
+    {
+      title: "start here",
+      rows: [
+        ["type + enter", "ask for a change in plain words, or a command"],
+        ["ctrl-p", "play notes on the keyboard (chords: q)"],
+        ["ctrl-k", "menu: sound, effects, rhythm, chords, mix"],
+        ["space", "play / pause (empty prompt)"],
+        ["/help", "what dawg can do · /help <topic> for more"],
+      ],
+    },
+    {
+      title: "prompt",
+      rows: [
+        ["enter", "send"],
+        ["shift-enter ctrl-j", "new line"],
+        ["alt-enter ctrl-q", "queue after the current request"],
+        ["ctrl-z ctrl-y", "undo / redo"],
+        ["ctrl-o", "transcript"],
+        ["esc", "cancel the agent · close a panel"],
+        ["ctrl-c", "quit"],
+      ],
+    },
+  ],
+  list: [{ title: "list", rows: LIST }],
+  audition: [
+    {
+      title: "auditioning list",
+      rows: [
+        ["space", "loop the focused track · again stops"],
+        ["↑ ↓  j k", "move; while looping, hear the row on the loop"],
+        ["a", "A/B: before ↔ the highlighted row"],
+        ["c", "solo ↔ in context (the whole mix)"],
+        ["enter", "keep it (one undo step)"],
+        ["esc", "back; nothing changes"],
+        ["/", "filter (type, then enter or esc)"],
+      ],
+    },
+  ],
+  preview: [
+    {
+      title: "patterns",
+      rows: [
+        ["↑ ↓  j k", "move and hear the pattern"],
+        ["enter", "apply it to the focused track"],
+        ...LIST.slice(3),
+      ],
+    },
+  ],
+  menu: [
+    {
+      title: "menu",
+      rows: [
+        ["↑ ↓  j k", "move"],
+        ["enter → l", "open a section"],
+        ["esc ← h", "back one level"],
+        ["/", "filter this level"],
+      ],
+    },
+    {
+      title: "on a value",
+      rows: [
+        ["← →  h l  - +", "adjust"],
+        ["0-9", "type a value, enter applies"],
+        ["enter", "type a value · pick from a list"],
+        ["space", "toggle on/off (elsewhere: hear the track)"],
+        ["x  delete", "reset to default (deletes an automation point)"],
+      ],
+    },
+    {
+      title: "auditioning",
+      rows: [
+        ["space", "loop the focused track · again stops"],
+        ["c", "solo ↔ in context (the whole mix)"],
+        ["a", "A/B: committed ↔ staged"],
+        ["enter", "keep staged changes (one undo step)"],
+        ["esc", "revert staged changes"],
+      ],
+    },
+    {
+      title: "every change",
+      rows: [
+        ["", "while looping, stages; otherwise runs the command shown"],
+        ["ctrl-z", "undoes it"],
+      ],
+    },
+  ],
+  euclid: [
+    {
+      title: "rhythm editor",
+      rows: [
+        ["↑ ↓  j k", "voice"],
+        ["← →  h l  - +", "adjust the field"],
+        ["tab shift-tab  ] [", "next / previous field"],
+        ["0-9", "type a value, enter applies"],
+        ["enter", "add a row (or type a value)"],
+        ["space", "hear the voice"],
+        ["x", "turn the row off"],
+        ["f", "freeze into plain hits"],
+        ["esc", "back"],
+      ],
+    },
+  ],
+  text: [
+    {
+      title: "panel",
+      rows: [
+        ["↑ ↓  j k", "scroll"],
+        ["pgup pgdn home end", "page"],
+        ["esc", "close"],
+      ],
+    },
+  ],
+  log: [
+    {
+      title: "transcript",
+      rows: [
+        ["↑ ↓", "scroll"],
+        ["pgup pgdn home end", "page"],
+        ["/", "next filter: all, requests, ops, errors"],
+        ["esc ctrl-o", "close"],
+      ],
+    },
+  ],
+  play: [
+    {
+      title: "play mode · letters are piano keys",
+      rows: [
+        ["a s d f g h j k l ; '", "white keys"],
+        ["w e t y u o p", "black keys"],
+        ["z x", "octave down / up"],
+        ["c v", "velocity down / up"],
+        ["shift · tab", "sustain while held · sustain latch"],
+        ["space", "play / pause (with count-in)"],
+        ["r · R", "record · record replacing"],
+        ["m", "metronome click"],
+        ["q", "chord mode: auto ⇄ manual"],
+        ["/", "type a command, still in play mode"],
+        ["ctrl-k", "menu"],
+        ["esc", "leave play mode"],
+      ],
+    },
+  ],
+  chords: [
+    {
+      title: "chord mode · number row latches",
+      rows: [
+        ["1 2 3 4", "dim · min · maj · sus (two combine)"],
+        ["5 6 7 8", "add 6 · m7 · M7 · 9"],
+        ["0", "clear the latches"],
+        ["- =", "voicing down / up"],
+        ["9", "next perform mode (block, strum, arp…)"],
+        ["b", "next bass mode"],
+        ["n", "play the suggested next chord"],
+        ["q", "auto (chords fit the key) ⇄ manual"],
+      ],
+    },
+  ],
+} satisfies Record<string, readonly KeySection[]>;
+
+export type KeyScreen = keyof typeof KEYS;
+
+/** `?` panel lines: a heading per section, then aligned `keys  action`. */
+export function keyLines(sections: readonly KeySection[]): string[] {
+  const column =
+    Math.max(
+      0,
+      ...sections.flatMap((section) =>
+        section.rows.map(([keys]) => displayWidth(keys)),
+      ),
+    ) + 2;
+  const lines: string[] = [];
+  for (const section of sections) {
+    if (lines.length) lines.push("");
+    lines.push(`── ${section.title}`);
+    for (const [keys, action] of section.rows)
+      lines.push(
+        `${keys}${" ".repeat(Math.max(1, column - displayWidth(keys)))}${action}`,
+      );
+  }
+  return lines;
+}

package/tui/highway.ts

@@ -11,6 +11,7 @@
  */
 
 import { CellBuffer } from "./screen.ts";
+import { truncate } from "./text.ts";
 import {
   accentStyle,
   onBackground,
@@ -472,6 +473,11 @@ export function paintHighway(
   const rowBeat = (row: number): number => beat + (hitRow - row) / rowsPerBeat;
   const legendRow = layout.legendRow;
   const lastNoteRow = (legendRow ?? region.height) - 1;
+  // Nothing to label yet: bar numbers and the lane legend stay off and a
+  // centred hint says how to start. The hit line and grid still draw.
+  const empty =
+    score.notes.length === 0 &&
+    !(score.layers ?? []).some((layer) => layer.notes.length > 0);
 
   // Beat, bar, and loop rules of increasing strength.
   for (let row = 0; row <= lastNoteRow; row += 1) {
@@ -497,7 +503,7 @@ export function paintHighway(
       if (!isBar && !isLoop && (column - gutter) % 2 === 1) continue;
       painter.put(column, row, glyph, style);
     }
-    if (gutter > 0 && (isBar || isLoop)) {
+    if (gutter > 0 && (isBar || isLoop) && !empty) {
       const label = isLoop
         ? glyphs.loop
         : String(Math.floor(inLoop / beatsPerBar) + 1);
@@ -553,8 +559,24 @@ export function paintHighway(
     }
   }
 
+  if (empty) {
+    const name = score.trackName ?? score.trackId ?? "track";
+    const start = projection.kind === "pitch" ? "add C4 at 0" : "hit kick at 0";
+    // First run: name the three ways in (ask, play, menu); narrow
+    // windows fall back to one prompt command.
+    const full = `${name} · empty · type a request · ctrl-p play · ctrl-k menu`;
+    const text = truncate(
+      full.length <= areaWidth ? full : `${name} · empty · ${start} to start`,
+      areaWidth,
+    );
+    const x = gutter + Math.max(0, Math.floor((areaWidth - text.length) / 2));
+    const y = Math.max(0, Math.floor(hitRow / 2));
+    for (let index = 0; index < text.length; index += 1)
+      painter.put(x + index, y, text[index]!, roles.muted);
+  }
+
   // Legend for drum voices (or C-octave markers for pitch lanes).
-  if (legendRow !== undefined && projection.label) {
+  if (legendRow !== undefined && projection.label && !empty) {
     let nextFree = 0;
     for (let lane = 0; lane < layout.laneCount; lane += 1) {
       const label = projection.label(lane);

package/tui/layers.ts

@@ -9,6 +9,8 @@ import {
   MAX_LAYER_NOTES,
   type HighwayLayer,
 } from "./highway.ts";
+import { samplerLanes } from "./drums.ts";
+import type { Sampler } from "../core/score.ts";
 
 export interface LayerTrack {
   id: string;
@@ -16,6 +18,7 @@ export interface LayerTrack {
   instrument: string;
   muted: boolean;
   solo?: boolean | undefined;
+  sampler?: Sampler | undefined;
 }
 
 export interface LayerNote {
@@ -43,17 +46,24 @@ export function highwayLayers(
   let budget = MAX_LAYER_NOTES;
   return audible.map((track) => {
     const drum = isDrumInstrument(track.instrument);
+    const sampled = drum ? undefined : samplerLanes(track);
     const own = [];
     for (const note of notes) {
       if (note.trackId !== track.id) continue;
       if (budget <= 0) break;
+      const lane = drum
+        ? drumLane(note.pitch)
+        : sampled
+          ? sampled.laneOf(note.pitch)
+          : undefined;
+      if (sampled && lane === undefined) continue;
       budget -= 1;
       own.push({
         startBeat: note.startTick / tpb,
         durationBeats: note.durationTicks / tpb,
         pitch: note.pitch,
         velocity: note.velocity,
-        ...(drum ? { lane: drumLane(note.pitch) } : {}),
+        ...(lane !== undefined ? { lane } : {}),
       });
     }
     return {
@@ -62,7 +72,9 @@ export function highwayLayers(
       notes: own,
       projection: drum
         ? drumLaneProjection(DRUM_VOICES.map((info) => info.label))
-        : undefined,
+        : sampled
+          ? drumLaneProjection(sampled.labels)
+          : undefined,
     };
   });
 }

package/tui/play-strip.ts

@@ -0,0 +1,188 @@
+/**
+ * Play mode's two fixed rows: the header (`PLAY  C3–F4  vel 100  ● REC
+ * click ✓` plus a beat flash) and a one-line keyboard strip with the keys
+ * that are sounding lit. Both repaint in place every frame, so playing never
+ * scrolls the transcript.
+ */
+import type { CellBuffer } from "./screen.ts";
+import { displayWidth, truncate } from "./text.ts";
+import { onBackground, type Theme } from "./theme.ts";
+
+export type PlayStripKey = Readonly<{
+  key: string;
+  label: string;
+  black: boolean;
+  lit: boolean;
+}>;
+
+export type PlayHeaderView = Readonly<{
+  /** `C3–F4`. */
+  range: string;
+  velocity: number;
+  /** Record armed. */
+  armed: boolean;
+  /** Recording right now (armed and the transport is running). */
+  recording: boolean;
+  replace: boolean;
+  click: boolean;
+  sustain: boolean;
+  /** `count-in 3` while counting in. */
+  countIn?: string | undefined;
+  /** Beat within the bar (1-based) and whether it is the flash window. */
+  beat?: Readonly<{ index: number; of: number; flash: boolean }> | undefined;
+  /** `grid 1/16`. */
+  grid: string;
+  /** Chord mode: `AUTO C major · Dm (ii) → G · arp-up`, empty when off. */
+  chords?: string | undefined;
+  /** Short status (`octave C2`, `no audio`). */
+  status?: string | undefined;
+  keys: readonly PlayStripKey[];
+  /** Chord mode's number-row legend; latched entries are `on`. */
+  legend?: readonly ChordLegendCell[] | undefined;
+}>;
+
+/** One chord-mode key on the legend row: `1 dim`, `9 strum-up`. */
+export type ChordLegendCell = Readonly<{
+  key: string;
+  label: string;
+  on: boolean;
+}>;
+
+/** Text of the header row, for tests and narrow terminals. */
+export function playHeaderText(view: PlayHeaderView, unicode = true): string {
+  const parts = [
+    "PLAY",
+    view.range,
+    view.armed
+      ? `${unicode ? "●" : "*"} ${view.recording ? "REC" : "rec armed"}${view.replace ? " replace" : ""}`
+      : "",
+    view.click ? "click" : "",
+    view.sustain ? "SUSTAIN" : "",
+    view.chords ?? "",
+    view.countIn ?? "",
+    view.status ?? "",
+  ].filter(Boolean);
+  return parts.join("  ");
+}
+
+export function paintPlayHeader(
+  buffer: CellBuffer,
+  y: number,
+  width: number,
+  view: PlayHeaderView,
+  theme: Theme,
+  unicode: boolean,
+): void {
+  const roles = theme.roles;
+  const panel = roles.panel;
+  buffer.fill(0, y, width, 1, panel);
+  let x = 1;
+  const put = (text: string, style = roles.text) => {
+    if (x >= width - 1) return;
+    x += buffer.text(
+      x,
+      y,
+      truncate(text, Math.max(1, width - x - 1)),
+      onBackground(style, panel),
+    );
+    x += buffer.text(x, y, "  ", panel);
+  };
+  put(" PLAY ", roles.pillSteer);
+  put(view.range, { ...roles.text, bold: true });
+  if (view.armed)
+    put(
+      `${unicode ? "●" : "*"} ${view.recording ? "REC" : "rec armed"}${view.replace ? " replace" : ""}`,
+      view.recording ? roles.error : roles.warning,
+    );
+  // Velocity, grid and click details live in the `?` panel.
+  if (view.click) put("click", roles.success);
+  if (view.sustain) put("SUSTAIN", roles.pillQueue);
+  if (view.chords) put(view.chords, roles.hit);
+  if (view.countIn) put(view.countIn, roles.warning);
+  if (view.beat) {
+    const cells = Array.from({ length: view.beat.of }, (_, index) =>
+      index + 1 === view.beat!.index
+        ? unicode
+          ? "●"
+          : "o"
+        : unicode
+          ? "·"
+          : ".",
+    ).join("");
+    put(
+      cells,
+      view.beat.flash
+        ? view.beat.index === 1
+          ? roles.error
+          : roles.hit
+        : roles.muted,
+    );
+  }
+  // The way out and the way to learn more, always at the right edge.
+  const hint = "? keys · esc leave";
+  const right = width - 1 - displayWidth(hint);
+  // Status shows whole or by its first clause, never cut mid-word.
+  if (view.status) {
+    const room = right - 2 - x;
+    const first = view.status.split(" · ")[0]!;
+    const text =
+      displayWidth(view.status) <= room
+        ? view.status
+        : displayWidth(first) <= room
+          ? first
+          : "";
+    if (text) x += buffer.text(x, y, text, onBackground(roles.muted, panel));
+  }
+  if (right > x) buffer.text(right, y, hint, onBackground(roles.faint, panel));
+}
+
+/** Chord mode's number row: `1 dim  2 min … 9 block  b bass off  n next`. */
+export function paintChordLegend(
+  buffer: CellBuffer,
+  y: number,
+  width: number,
+  cells: readonly ChordLegendCell[],
+  theme: Theme,
+): void {
+  const roles = theme.roles;
+  buffer.fill(0, y, width, 1, roles.canvas);
+  let x = 1;
+  for (const cell of cells) {
+    const keyWidth = displayWidth(cell.key);
+    const cellWidth = keyWidth + 1 + displayWidth(cell.label) + 2;
+    if (x + cellWidth > width) break;
+    buffer.text(x, y, cell.key, { ...roles.text, bold: true });
+    buffer.text(
+      x + keyWidth + 1,
+      y,
+      cell.label,
+      cell.on ? { ...roles.hit, reverse: true } : roles.muted,
+    );
+    x += cellWidth;
+  }
+}
+
+/** `a C3 │ w C#3 …`: each key with its note; lit keys reversed. */
+export function paintPlayStrip(
+  buffer: CellBuffer,
+  y: number,
+  width: number,
+  keys: readonly PlayStripKey[],
+  theme: Theme,
+): void {
+  const roles = theme.roles;
+  buffer.fill(0, y, width, 1, roles.canvas);
+  let x = 1;
+  for (const key of keys) {
+    const cell = `${key.key.toUpperCase()} ${key.label}`;
+    const cellWidth = displayWidth(cell) + 1;
+    if (x + cellWidth > width - 1) break;
+    const style = key.lit
+      ? { ...(key.black ? roles.selected : roles.hit), reverse: true }
+      : key.black
+        ? roles.muted
+        : roles.text;
+    buffer.text(x, y, cell, style);
+    x += cellWidth;
+  }
+}