@hraness/dawg 0.6.1 → 0.8.0

package/tui/input.ts

@@ -7,16 +7,42 @@
 export type TerminalInputEvent =
   string | Readonly<{ type: "paste"; text: string }>;
 
+/** A bracketed paste longer than this is emitted as it stands. */
+export const MAX_PASTE_CHARS = 1 << 20;
+
+/** A chunk marker the read loop yields when input went idle mid-sequence. */
+export const INPUT_FLUSH = "\u0000flush";
+
+/** Idle time after which a partial escape prefix is a key of its own. */
+export const ESCAPE_FLUSH_MS = 50;
+/** Idle time after which an unterminated bracketed paste is emitted. */
+export const PASTE_FLUSH_MS = 1_000;
+
 export class TerminalInputDecoder {
   private buffer = "";
 
+  /**
+   * What the decoder holds back: `escape` for a partial escape sequence,
+   * `paste` for an unterminated bracketed paste. The caller flushes after
+   * `ESCAPE_FLUSH_MS` or `PASTE_FLUSH_MS` with no further input.
+   */
+  pending(): "escape" | "paste" | undefined {
+    if (this.buffer.length === 0) return undefined;
+    return this.buffer.startsWith("\u001b[200~") ? "paste" : "escape";
+  }
+
   push(chunk: string): TerminalInputEvent[] {
     this.buffer += chunk;
     const events: TerminalInputEvent[] = [];
     while (this.buffer.length > 0) {
       if (this.buffer.startsWith("\u001b[200~")) {
         const end = this.buffer.indexOf("\u001b[201~", 6);
-        if (end < 0) break;
+        if (end < 0) {
+          if (this.buffer.length - 6 < MAX_PASTE_CHARS) break;
+          events.push({ type: "paste", text: this.buffer.slice(6) });
+          this.buffer = "";
+          break;
+        }
         events.push({ type: "paste", text: this.buffer.slice(6, end) });
         this.buffer = this.buffer.slice(end + 6);
         continue;
@@ -38,12 +64,27 @@ export class TerminalInputDecoder {
     return events;
   }
 
+  /**
+   * Emits whatever is held back, once no more input is coming: a cut-off
+   * bracketed paste as a paste, a lone ESC as Esc, and a partial prefix such
+   * as `ESC [` (Alt+[) or `ESC O` (Alt+O) as one Alt key, then decodes the
+   * rest normally.
+   */
   flush(): TerminalInputEvent[] {
-    if (this.buffer === "\u001b") {
+    const events: TerminalInputEvent[] = [];
+    while (this.buffer.length > 0) {
+      if (this.buffer.startsWith("\u001b[200~")) {
+        events.push({ type: "paste", text: this.buffer.slice(6) });
+        this.buffer = "";
+        break;
+      }
+      const head =
+        this.buffer.length === 1 ? "\u001b" : this.buffer.slice(0, 2);
+      const rest = this.buffer.slice(head.length);
       this.buffer = "";
-      return ["\u001b"];
+      events.push(head, ...this.push(rest));
     }
-    return [];
+    return events;
   }
 
   private readEscapeSequence(): string | undefined {
@@ -59,12 +100,22 @@ export class TerminalInputDecoder {
       return this.buffer.length >= 6 ? this.buffer.slice(0, 6) : undefined;
     const final = this.buffer.match(/^\u001b\[[\x20-?]*[\x40-~]/)?.[0];
     if (final !== undefined) return final;
-    // SS3: arrows in application mode and F1-F4 (`ESC O P` is F1).
-    const ss3 = this.buffer.match(/^\u001bO[A-DHFPQRS]/)?.[0];
-    if (ss3 !== undefined) return ss3;
+    // A byte that cannot continue a CSI ends it: the `ESC [` was Alt+[.
+    if (this.buffer.startsWith("\u001b[")) {
+      const partial = this.buffer.match(/^\u001b\[[\x20-?]*/)![0];
+      if (partial.length < this.buffer.length) return "\u001b[";
+    }
+    // SS3: arrows in application mode and F1-F4 (`ESC O P` is F1). A bare
+    // `ESC O` waits for its final byte, which a PTY may deliver separately;
+    // `flush` turns it into Alt+O if nothing follows.
+    if (this.buffer.startsWith("\u001bO")) {
+      if (this.buffer.length === 2) return undefined;
+      const ss3 = this.buffer.match(/^\u001bO[A-DHFPQRS]/)?.[0];
+      if (ss3 !== undefined) return ss3;
+      return "\u001bO";
+    }
     // An unrecognised Alt-prefixed character is still one complete event.
-    if (this.buffer.length >= 2 && this.buffer[1] !== "[")
-      return this.buffer.slice(0, 2);
+    if (this.buffer[1] !== "[") return this.buffer.slice(0, 2);
     return undefined;
   }
 }

package/tui/keys.ts

@@ -3,7 +3,7 @@
  *
  * The prompt is always focused, so printable keys always type.  Control
  * chords carry the global actions:
- *   Ctrl+C quit · Ctrl+Q toggle STEER/QUEUE · Ctrl+Z undo · Ctrl+Y redo
+ *   Ctrl+C quit · Ctrl+Q toggle NOW/NEXT · Ctrl+Z undo · Ctrl+Y redo
  *   Ctrl+O transcript overlay · Esc closes the overlay
  */
 

package/tui/knobs.ts

@@ -0,0 +1,268 @@
+/**
+ * The four knobs (design §7, the OP-1's four colour encoders adapted): one
+ * table names each knob's colour, shape glyph and meaning, and every screen
+ * that shows knobs (the fader drawer's front page, the mixer page, euclid,
+ * and later TAPE and PLAY) reads it, so a knob looks and means the same
+ * everywhere.
+ *
+ *   ● blue    moves   position, selection, which
+ *   ▲ green   sizes   length, range, amount of steps
+ *   ■ white   shapes  tone, time, character
+ *   ◆ orange  level   loudness, mix, velocity
+ *
+ * Colour is never the only cue: each knob has a shape glyph, which is all
+ * that is left under NO_COLOR and the mono theme.
+ *
+ * Keys, the same on every screen: ↑↓ picks a knob (skipping empty slots),
+ * ←→ turns it, ⇧←→ turns it coarse, x resets it, enter opens it big.
+ * Every turn is a typed command, so the receipt teaches the words.
+ *
+ * Pure: the reducer returns what to run; the caller runs it.
+ */
+import type { CellBuffer } from "./screen.ts";
+import { displayWidth, truncate } from "./text.ts";
+import type { SemanticRole, Style, Theme } from "./theme.ts";
+import {
+  KEY_COARSE_LEFT,
+  KEY_COARSE_RIGHT,
+  KEY_DOWN,
+  KEY_ENTER,
+  KEY_LEFT,
+  KEY_RESET,
+  KEY_RIGHT,
+  KEY_UP,
+} from "./grammar.ts";
+
+export type KnobIndex = 0 | 1 | 2 | 3;
+
+export type Knob = Readonly<{
+  index: KnobIndex;
+  colour: "blue" | "green" | "white" | "orange";
+  /** What this knob means on every screen. */
+  meaning: "moves" | "sizes" | "shapes" | "level";
+  role: Extract<SemanticRole, "knob1" | "knob2" | "knob3" | "knob4">;
+  /** Shape glyph (width 1), so colour is never the only cue. */
+  glyph: string;
+  /** The glyph where the terminal has no Unicode. */
+  ascii: string;
+}>;
+
+/** The one table: glyphs, colours and meanings of the four knobs. */
+export const KNOBS: readonly [Knob, Knob, Knob, Knob] = Object.freeze([
+  {
+    index: 0,
+    colour: "blue",
+    meaning: "moves",
+    role: "knob1",
+    glyph: "●",
+    ascii: "o",
+  },
+  {
+    index: 1,
+    colour: "green",
+    meaning: "sizes",
+    role: "knob2",
+    glyph: "▲",
+    ascii: "^",
+  },
+  {
+    index: 2,
+    colour: "white",
+    meaning: "shapes",
+    role: "knob3",
+    glyph: "■",
+    ascii: "#",
+  },
+  {
+    index: 3,
+    colour: "orange",
+    meaning: "level",
+    role: "knob4",
+    glyph: "◆",
+    ascii: "*",
+  },
+] as const);
+
+export function knobGlyph(index: KnobIndex, unicode: boolean): string {
+  const knob = KNOBS[index];
+  return unicode ? knob.glyph : knob.ascii;
+}
+
+export function knobStyle(index: KnobIndex, theme: Theme): Style {
+  return theme.roles[KNOBS[index].role];
+}
+
+/** The footer hint of a knob page, the same words on every screen. */
+export const KNOB_HINT =
+  "↑↓ knob · ←→ turn · ⇧ coarse · x reset · tab more · esc close";
+
+/** One knob slot as a screen shows and turns it. */
+export type KnobSlot = Readonly<{
+  label: string;
+  /** Formatted value: `1200 Hz`, `saw`, `−4.9 dB`. */
+  text: string;
+  /** 0…1 along the gauge; undefined while off or for a choice. */
+  position?: number | undefined;
+  /** The command one turn runs, or undefined at the end of the range. */
+  turn: (direction: 1 | -1, coarse: boolean) => string | undefined;
+  /** The command `x` runs, when the slot has a default. */
+  reset?: string | undefined;
+}>;
+
+/** Four slots; an undefined one draws as `·` and ↑↓ skips it. */
+export type KnobSlots = readonly [
+  KnobSlot | undefined,
+  KnobSlot | undefined,
+  KnobSlot | undefined,
+  KnobSlot | undefined,
+];
+
+export type KnobState = { selected: KnobIndex };
+
+export type KnobResult =
+  | { type: "handled" }
+  | { type: "pass" }
+  | { type: "run"; command: string }
+  | { type: "open"; knob: KnobIndex };
+
+/**
+ * The next knob from `from` in `direction`, wrapping blue → green → white →
+ * orange and skipping empty slots; `from` itself when every slot is empty.
+ */
+export function nextKnob(
+  from: KnobIndex,
+  direction: 1 | -1,
+  present: (index: KnobIndex) => boolean,
+): KnobIndex {
+  for (let step = 1; step <= 4; step += 1) {
+    const index = (((from + direction * step) % 4) + 4) % 4;
+    if (present(index as KnobIndex)) return index as KnobIndex;
+  }
+  return from;
+}
+
+/** The first non-empty slot, for opening on a page. */
+export function firstKnob(slots: KnobSlots): KnobIndex {
+  const at = slots.findIndex(Boolean);
+  return (at < 0 ? 0 : at) as KnobIndex;
+}
+
+/** One key on a knob strip. */
+export function knobKey(
+  state: KnobState,
+  slots: KnobSlots,
+  value: string,
+): KnobResult {
+  if (!slots[state.selected]) state.selected = firstKnob(slots);
+  const up = KEY_UP.has(value);
+  if (up || KEY_DOWN.has(value)) {
+    state.selected = nextKnob(state.selected, up ? -1 : 1, (index) =>
+      Boolean(slots[index]),
+    );
+    return { type: "handled" };
+  }
+  const slot = slots[state.selected];
+  if (!slot) return { type: "pass" };
+  const coarseLeft = KEY_COARSE_LEFT.has(value);
+  const coarseRight = KEY_COARSE_RIGHT.has(value);
+  if (
+    coarseLeft ||
+    coarseRight ||
+    KEY_LEFT.has(value) ||
+    KEY_RIGHT.has(value)
+  ) {
+    const direction = coarseRight || KEY_RIGHT.has(value) ? 1 : -1;
+    const command = slot.turn(direction, coarseLeft || coarseRight);
+    return command ? { type: "run", command } : { type: "handled" };
+  }
+  if (KEY_RESET.has(value))
+    return slot.reset
+      ? { type: "run", command: slot.reset }
+      : { type: "handled" };
+  if (KEY_ENTER.has(value)) return { type: "open", knob: state.selected };
+  return { type: "pass" };
+}
+
+/**
+ * `●›cutoff 1.2k ▲ q 0.7 ■ type lowpass ◆ mix 0.3`: the strip as plain
+ * text, for pickers and receipts. The selected knob carries `›` (`>`).
+ */
+export function knobStripText(
+  slots: KnobSlots,
+  selected: KnobIndex,
+  unicode: boolean,
+): string {
+  return slots
+    .map((slot, index) => {
+      const knob = index as KnobIndex;
+      const mark = knob === selected ? (unicode ? "›" : ">") : " ";
+      const glyph = knobGlyph(knob, unicode);
+      return slot ? `${glyph}${mark}${slot.label} ${slot.text}` : `${glyph} ·`;
+    })
+    .join("  ");
+}
+
+/**
+ * Paint a one-row knob strip at (x, y) within `width`: each slot is its
+ * glyph in its knob colour, the label, the value and a short gauge. The
+ * selected slot's label is reverse video. Returns the cells used.
+ */
+/** The widest one knob-strip slot gets (label, value and gauge). */
+export const KNOB_CELL_MAX = 40;
+
+export function paintKnobStrip(
+  buffer: CellBuffer,
+  x: number,
+  y: number,
+  width: number,
+  slots: KnobSlots,
+  selected: KnobIndex,
+  options: { theme: Theme; unicode: boolean; background?: Style },
+): number {
+  // Past KNOB_CELL_MAX a slot's gauge only stretches; the strip stays
+  // left-aligned and the rest of the row is free.
+  const cell = Math.min(KNOB_CELL_MAX, Math.floor(width / 4));
+  if (cell < 6) return 0;
+  const background = options.background ?? {};
+  const on = (style: Style): Style => ({ ...background, ...style });
+  slots.forEach((slot, index) => {
+    const knob = index as KnobIndex;
+    const left = x + cell * index;
+    const style = knobStyle(knob, options.theme);
+    buffer.text(left, y, knobGlyph(knob, options.unicode), on(style));
+    if (!slot) {
+      buffer.text(left + 2, y, "·", on(options.theme.roles.faint));
+      return;
+    }
+    const label = truncate(`${slot.label} ${slot.text}`, cell - 3);
+    buffer.text(
+      left + 2,
+      y,
+      label,
+      on(
+        knob === selected
+          ? { ...options.theme.roles.text, reverse: true }
+          : options.theme.roles.text,
+      ),
+    );
+    const gauge = cell - 3 - displayWidth(label) - 1;
+    if (slot.position !== undefined && gauge >= 3) {
+      const filled = Math.round(
+        Math.min(1, Math.max(0, slot.position)) * gauge,
+      );
+      buffer.text(
+        left + 3 + displayWidth(label),
+        y,
+        (options.unicode ? "█" : "=").repeat(filled),
+        on(style),
+      );
+      buffer.text(
+        left + 3 + displayWidth(label) + filled,
+        y,
+        (options.unicode ? "─" : "-").repeat(gauge - filled),
+        on(options.theme.roles.faint),
+      );
+    }
+  });
+  return cell * 4;
+}

package/tui/play-strip.ts

@@ -1,21 +1,31 @@
 /**
- * Play mode's two fixed rows: the header (`PLAY  C3–F4  vel 100  ● REC
+ * Play mode's two fixed rows: the header (`PLAY MODE  ▶ 120 BPM · lead ·
+ * rev 3  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";
+import { onBackground, type Style, type Theme } from "./theme.ts";
 
 export type PlayStripKey = Readonly<{
   key: string;
   label: string;
   black: boolean;
   lit: boolean;
+  /** Chord mode: the label names the chord this key plays. */
+  chord?: boolean | undefined;
+  /** That chord is built on a degree of the song's key. */
+  diatonic?: boolean | undefined;
 }>;
 
 export type PlayHeaderView = Readonly<{
+  /**
+   * The song header compressed to the left of the row while play mode
+   * covers it: `▶ 120 BPM · drums · rev 1`.
+   */
+  context?: string | undefined;
   /** `C3–F4`. */
   range: string;
   velocity: number;
@@ -24,6 +34,8 @@ export type PlayHeaderView = Readonly<{
   /** Recording right now (armed and the transport is running). */
   recording: boolean;
   replace: boolean;
+  /** Loop recording: `↻ 5–6 · pass 3`. */
+  pass?: string | undefined;
   click: boolean;
   sustain: boolean;
   /** `count-in 3` while counting in. */
@@ -51,11 +63,17 @@ export type ChordLegendCell = Readonly<{
 /** Text of the header row, for tests and narrow terminals. */
 export function playHeaderText(view: PlayHeaderView, unicode = true): string {
   const parts = [
-    "PLAY",
+    "PLAY MODE",
+    view.context ?? "",
     view.range,
     view.armed
       ? `${unicode ? "●" : "*"} ${view.recording ? "REC" : "rec armed"}${view.replace ? " replace" : ""}`
       : "",
+    view.pass
+      ? unicode
+        ? view.pass
+        : view.pass.replace("↻", "@").replace("–", "-")
+      : "",
     view.click ? "click" : "",
     view.sustain ? "SUSTAIN" : "",
     view.chords ?? "",
@@ -87,19 +105,29 @@ export function paintPlayHeader(
     );
     x += buffer.text(x, y, "  ", panel);
   };
-  put(" PLAY ", roles.pillSteer);
-  put(view.range, { ...roles.text, bold: true });
+  put(" PLAY MODE ", roles.pillSteer);
+  const context = fitContext(view, width, unicode);
+  if (context) put(context, roles.muted);
+  // A kit names its range by the track already in the context.
+  if (!context.includes(" · ") || view.range !== "drums")
+    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,
     );
+  if (view.pass)
+    put(
+      unicode ? view.pass : view.pass.replace("↻", "@").replace("–", "-"),
+      roles.knob2,
+    );
   // 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 hintWidth = displayWidth("? keys · esc leave");
+  if (view.beat && x + view.beat.of + 2 <= width - 1 - hintWidth) {
     const cells = Array.from({ length: view.beat.of }, (_, index) =>
       index + 1 === view.beat!.index
         ? unicode
@@ -136,6 +164,31 @@ export function paintPlayHeader(
   if (right > x) buffer.text(right, y, hint, onBackground(roles.faint, panel));
 }
 
+/**
+ * The compressed song header (`▶ 120 BPM · bass · rev 1`). It is reserved
+ * first: the beat dots and the status give way before it does, and only a
+ * terminal too narrow for it with the badge and the way out shortens it to
+ * its first clause.
+ */
+function fitContext(
+  view: PlayHeaderView,
+  width: number,
+  unicode: boolean,
+): string {
+  if (!view.context) return "";
+  const rest = displayWidth(
+    playHeaderText(
+      { ...view, context: undefined, status: undefined, beat: undefined },
+      unicode,
+    ),
+  );
+  // Badge padding, the right-hand hint and the gaps between parts.
+  const room = width - 2 - displayWidth("? keys · esc leave") - 4 - rest;
+  for (const candidate of [view.context, view.context.split(" · ")[0]!])
+    if (displayWidth(candidate) + 2 <= room) return candidate;
+  return "";
+}
+
 /** Chord mode's number row: `1 dim  2 min … 9 block  b bass off  n next`. */
 export function paintChordLegend(
   buffer: CellBuffer,
@@ -162,7 +215,11 @@ export function paintChordLegend(
   }
 }
 
-/** `a C3 │ w C#3 …`: each key with its note; lit keys reversed. */
+/**
+ * `A C3  W C#3 …`: each key with what it plays. The key letter is muted so
+ * the music reads first; a chord label is bold, and chords in the song's
+ * key are lit (they always fit). Sounding keys are reversed.
+ */
 export function paintPlayStrip(
   buffer: CellBuffer,
   y: number,
@@ -174,15 +231,24 @@ export function paintPlayStrip(
   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;
+    const letter = key.key.toUpperCase();
+    const cellWidth = displayWidth(letter) + 1 + displayWidth(key.label) + 1;
     if (x + cellWidth > width - 1) break;
-    const style = key.lit
+    const labelStyle: Style = key.lit
       ? { ...(key.black ? roles.selected : roles.hit), reverse: true }
+      : key.chord
+        ? { ...(key.diatonic ? roles.hit : roles.text), bold: true }
+        : key.black
+          ? roles.muted
+          : roles.text;
+    const letterStyle: Style = key.lit
+      ? labelStyle
       : key.black
-        ? roles.muted
-        : roles.text;
-    buffer.text(x, y, cell, style);
-    x += cellWidth;
+        ? roles.faint
+        : roles.muted;
+    x += buffer.text(x, y, letter, letterStyle);
+    x += buffer.text(x, y, " ", key.lit ? labelStyle : roles.canvas);
+    x += buffer.text(x, y, key.label, labelStyle);
+    x += 1;
   }
 }

package/tui/prompt.ts

@@ -316,7 +316,7 @@ export function applyPromptKey(
   }
   switch (keyInput.toUpperCase()) {
     case "ENTER":
-      // The mode pill decides what Enter does: STEER runs now, QUEUE waits.
+      // The mode pill decides what Enter does: NOW runs now, NEXT waits.
       return submit(state, state.mode === "queue" ? "queue" : "submit");
     case "ALT+ENTER":
       return submit(state, "queue");