@hraness/dawg 0.3.0 → 0.4.0

package/tui/app.ts

@@ -24,9 +24,11 @@ import {
   resolveBeat,
   type TrackScoreSnapshot,
 } from "./highway.ts";
+import { asciiHint, fitHint, HINTS } from "./grammar.ts";
 import { classifyKey, overlayKey, type UiCommand } from "./keys.ts";
 import { PromptModel, type PromptAction, type PromptMode } from "./prompt.ts";
 import {
+  paintChordLegend,
   paintPlayHeader,
   paintPlayStrip,
   type PlayHeaderView,
@@ -85,6 +87,8 @@ export interface UiState {
   log?: LogView | undefined;
   picker?: PickerState | undefined;
   text?: TextView | undefined;
+  /** The `?` panel: keys for the screen underneath, drawn over it. */
+  keys?: TextView | undefined;
 }
 
 /** `log` is the transcript, `picker` an arrow-key list, `text` static lines. */
@@ -122,9 +126,18 @@ export interface PickerState {
   filterable?: boolean | undefined;
   /** Current filter text; `items` is then the matching subset of `all`. */
   query?: string | undefined;
+  /** `/` was pressed: printable keys type into the filter. */
+  filtering?: boolean | undefined;
   all?: readonly PickerItem[] | undefined;
   /** Footer keys, replacing the default move/choose/cancel hint. */
   hint?: string | undefined;
+  /** A dim line under the rows: what the focused row does. */
+  note?: string | undefined;
+  /**
+   * Hosts the audition loop (src/tui/audition.ts): Space, `a` and `c` are
+   * returned as `pick-audition` instead of being swallowed.
+   */
+  audition?: boolean | undefined;
 }
 
 export interface PickerItem {
@@ -701,11 +714,10 @@ function paintOverlay(
     onBackground({ ...roles.text, bold: true }, panel),
     boxWidth - 4,
   );
-  const hint = " ↑↓ pgup pgdn scroll · / filter · esc close ";
-  const hintText = capabilities.unicode ? hint : hint.replace("↑↓", "up dn");
-  if (boxWidth > hintText.length + 4)
+  const hintText = footerHint(HINTS.log, boxWidth - 4, capabilities.unicode);
+  if (hintText)
     buffer.text(
-      left + boxWidth - 2 - hintText.length,
+      left + boxWidth - 2 - displayWidth(hintText),
       top + height - 1,
       hintText,
       onBackground(roles.muted, panel),
@@ -748,8 +760,9 @@ function paintText(
   ui: UiState,
   region: { y: number; height: number },
   width: number,
+  options: { text?: TextView | undefined; hint?: string } = {},
 ): void {
-  const text = ui.text;
+  const text = options.text ?? ui.text;
   if (!text) return;
   const roles = ui.theme.roles;
   const left = width >= 60 ? 2 : 0;
@@ -776,12 +789,14 @@ function paintText(
     onBackground({ ...roles.text, bold: true }, panel),
     boxWidth - 4,
   );
-  const hint = ui.capabilities.unicode
-    ? " ↑↓ pgup pgdn scroll · esc close "
-    : " up dn pgup pgdn scroll · esc close ";
-  if (boxWidth > hint.length + 4)
+  const hint = footerHint(
+    options.hint ?? HINTS.text,
+    boxWidth - 4,
+    ui.capabilities.unicode,
+  );
+  if (hint)
     buffer.text(
-      left + boxWidth - 2 - hint.length,
+      left + boxWidth - 2 - displayWidth(hint),
       region.y + height - 1,
       hint,
       onBackground(roles.muted, panel),
@@ -840,7 +855,11 @@ function paintPicker(
   const roles = ui.theme.roles;
   const left = width >= 60 ? 2 : 0;
   const boxWidth = width - left * 2;
-  const height = Math.min(region.height, Math.max(1, picker.items.length) + 2);
+  const noteRows = picker.note && region.height >= 6 ? 1 : 0;
+  const height = Math.min(
+    region.height,
+    Math.max(1, picker.items.length) + 2 + noteRows,
+  );
   if (height < 3 || boxWidth < 10) return;
   const panel = paintBox(buffer, ui, {
     left,
@@ -851,23 +870,35 @@ function paintPicker(
   buffer.text(
     left + 2,
     region.y,
-    ` ${picker.title}${picker.query ? ` · ${picker.query}` : picker.filterable ? " · type to filter" : ""} `,
+    ` ${picker.title}${picker.filtering || picker.query ? ` · /${picker.query ?? ""}${picker.filtering ? "▏" : ""}` : ""} `,
     onBackground({ ...roles.text, bold: true }, panel),
     boxWidth - 4,
   );
-  const hint =
-    picker.hint ??
-    (ui.capabilities.unicode
-      ? " ↑↓ move · enter choose · esc cancel "
-      : " up/dn move · enter choose · esc cancel ");
-  if (boxWidth > hint.length + 4)
+  const hint = footerHint(
+    picker.filtering
+      ? HINTS.filtering
+      : (picker.hint ??
+          (picker.filterable
+            ? HINTS.list
+            : HINTS.list.replace(" · / filter", ""))),
+    boxWidth - 4,
+    ui.capabilities.unicode,
+  );
+  if (hint)
     buffer.text(
-      left + boxWidth - 2 - hint.length,
+      left + boxWidth - 2 - displayWidth(hint),
       region.y + height - 1,
       hint,
       onBackground(roles.muted, panel),
     );
-  const inner = height - 2;
+  const inner = height - 2 - noteRows;
+  if (noteRows && picker.note)
+    buffer.text(
+      left + 2,
+      region.y + height - 2,
+      truncate(picker.note, boxWidth - 4),
+      onBackground(roles.muted, panel),
+    );
   const first = Math.max(
     0,
     Math.min(picker.items.length - inner, picker.index - inner + 1),
@@ -917,6 +948,24 @@ function paintPicker(
   });
 }
 
+/** The `?` panel sits at the bottom of the highway, as tall as it needs. */
+function keysRegion(
+  region: { y: number; height: number },
+  keys: TextView,
+): { y: number; height: number } {
+  const height = Math.min(region.height, keys.lines.length + 2);
+  return { y: region.y + region.height - height, height };
+}
+
+/** A footer hint fitted to `width`, spelled in ASCII when needed. */
+export function footerHint(
+  hint: string,
+  width: number,
+  unicode: boolean,
+): string {
+  return fitHint(unicode ? hint : asciiHint(hint), width);
+}
+
 // ---------------------------------------------------------------------------
 
 function paintTooSmall(buffer: CellBuffer, ui: UiState, size: FrameSize): void {
@@ -969,6 +1018,19 @@ export function composeFrame(
         height: layout.highway.height - 1,
       };
     }
+    if (view.play.legend && layout.highway.height > 4) {
+      paintChordLegend(
+        buffer,
+        layout.highway.y,
+        width,
+        view.play.legend,
+        ui.theme,
+      );
+      layout.highway = {
+        y: layout.highway.y + 1,
+        height: layout.highway.height - 1,
+      };
+    }
   } else paintHeader(buffer, view, ui, width);
   const beat = view.beat ?? resolveBeat(view.score, nowMs);
   if (layout.highway.height > 0) {
@@ -990,6 +1052,11 @@ export function composeFrame(
         },
       );
   }
+  if (ui.keys && layout.highway.height > 0)
+    paintText(buffer, ui, keysRegion(layout.highway, ui.keys), width, {
+      text: ui.keys,
+      hint: HINTS.keys,
+    });
   paintActivity(buffer, layout.activity, ui, width, nowMs);
   const prompt = paintPrompt(buffer, view, ui, layout, width);
   return { buffer, cursor: prompt.cursor, promptRows: prompt.rows, layout };
@@ -1021,6 +1088,14 @@ export type AppInput =
   | { type: "pick"; picker: string; value: string }
   /** Esc on a picker. */
   | { type: "pick-cancel"; picker: string }
+  /**
+   * The highlighted row changed (move, page, filter): the hook for live
+   * previews (/pattern today; an audition controller can listen here too).
+   * Pickers raise `pick-move` → `pick` (commit) or `pick-cancel` (cancel).
+   */
+  | { type: "pick-move"; picker: string; value: string }
+  /** Space, `a` or `c` on a picker that hosts the audition loop. */
+  | { type: "pick-audition"; picker: string; key: "loop" | "ab" | "context" }
   /** Consumed by an overlay (scroll, filter, move). */
   | { type: "overlay" }
   | { type: "none" };
@@ -1073,6 +1148,7 @@ export class TuiApp {
       log: this.log,
       picker: this.picker,
       text: this.text,
+      keys: this.keys,
     };
   }
 
@@ -1121,15 +1197,17 @@ export class TuiApp {
       if (nav === "up" || nav === "down" || nav === "pgup" || nav === "pgdn") {
         const step =
           nav === "up" ? -1 : nav === "down" ? 1 : nav === "pgup" ? -8 : 8;
+        // Moving ends typing into the filter; the filter itself stays.
+        picker.filtering = false;
         picker.index = Math.max(
           0,
           Math.min(picker.items.length - 1, picker.index + step),
         );
-        return { type: "overlay" };
+        return this.pickerMoved(picker);
       }
       if (nav === "home" || nav === "end") {
         picker.index = nav === "home" ? 0 : picker.items.length - 1;
-        return { type: "overlay" };
+        return this.pickerMoved(picker);
       }
       if (nav === "enter") {
         const item = picker.items[picker.index];
@@ -1139,30 +1217,51 @@ export class TuiApp {
           : { type: "pick-cancel", picker: picker.id };
       }
       if (key.type === "ui" && key.command === "close-overlay") {
+        // Esc clears the filter first, then closes.
+        if (picker.query || picker.filtering) {
+          this.filterPicker("");
+          if (this.picker) this.picker.filtering = false;
+          return { type: "overlay" };
+        }
         this.closePicker();
         return { type: "pick-cancel", picker: picker.id };
       }
-      if (picker.filterable && (value === "\u007f" || value === "\b")) {
-        this.filterPicker((picker.query ?? "").slice(0, -1));
-        return { type: "overlay" };
+      if (picker.filterable && picker.filtering) {
+        if (value === "\u007f" || value === "\b") {
+          const query = (picker.query ?? "").slice(0, -1);
+          this.filterPicker(query);
+          if (!query && this.picker) this.picker.filtering = false;
+          return { type: "overlay" };
+        }
+        if (key.type === "text") {
+          this.filterPicker(((picker.query ?? "") + key.text).slice(0, 40));
+          return { type: "overlay" };
+        }
       }
-      if (
-        picker.filterable &&
-        key.type === "text" &&
-        (picker.query || !/^[1-9]$/.test(key.text))
-      ) {
-        this.filterPicker(((picker.query ?? "") + key.text).slice(0, 40));
-        return { type: "overlay" };
+      if (picker.audition && !picker.filtering) {
+        const audition =
+          value === " "
+            ? "loop"
+            : value === "a"
+              ? "ab"
+              : value === "c"
+                ? "context"
+                : undefined;
+        if (audition)
+          return { type: "pick-audition", picker: picker.id, key: audition };
       }
-      if (key.type === "text" && /^[1-9]$/.test(key.text)) {
-        const index = Number(key.text) - 1;
-        if (index < picker.items.length) {
-          const item = picker.items[index]!;
-          this.closePicker();
-          return { type: "pick", picker: picker.id, value: item.value };
-        }
+      if (picker.filterable && key.type === "text" && key.text === "/") {
+        picker.filtering = true;
         return { type: "overlay" };
       }
+      if (key.type === "text" && (key.text === "j" || key.text === "k")) {
+        const step = key.text === "k" ? -1 : 1;
+        picker.index = Math.max(
+          0,
+          Math.min(picker.items.length - 1, picker.index + step),
+        );
+        return this.pickerMoved(picker);
+      }
       // Quit and redraw still work; everything else is swallowed.
       if (
         key.type === "ui" &&
@@ -1270,6 +1369,14 @@ export class TuiApp {
   }
 
   /** Show an arrow-key picker over the highway; replaces any overlay. */
+  /** `pick-move` for the row now highlighted, or a plain overlay input. */
+  private pickerMoved(picker: PickerState): AppInput {
+    const item = picker.items[picker.index];
+    return item
+      ? { type: "pick-move", picker: picker.id, value: item.value }
+      : { type: "overlay" };
+  }
+
   openPicker(picker: Omit<PickerState, "index"> & { index?: number }): void {
     const items = picker.items.slice(0, MAX_PICKER_ITEMS);
     if (items.length === 0) return;
@@ -1312,6 +1419,21 @@ export class TuiApp {
     this.overlay = "text";
   }
 
+  /** The `?` panel over the current screen; any key closes it. */
+  keys: TextView | undefined;
+  showKeys(title: string, lines: readonly string[]): void {
+    this.keys = { title, lines, scroll: 0 };
+  }
+
+  closeKeys(): void {
+    this.keys = undefined;
+  }
+
+  /** True while a picker's `/` filter is taking typed text. */
+  get pickerTyping(): boolean {
+    return this.overlay === "picker" && this.picker?.filtering === true;
+  }
+
   closeText(): void {
     this.text = undefined;
     if (this.overlay === "text") this.overlay = undefined;

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

@@ -562,7 +562,13 @@ 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";
-    const text = truncate(`${name} · empty · ${start} to start`, areaWidth);
+    // 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)