@hraness/dawg 0.7.0 → 0.8.0

package/tui/drawer.ts

@@ -24,6 +24,7 @@ import type { HitMap } from "./hits.ts";
 import { onBackground, type Style, type Theme } from "./theme.ts";
 import { displayWidth, truncate } from "./text.ts";
 import { asciiHint, fitHint } from "./grammar.ts";
+import { knobGlyph, knobStyle, type KnobIndex } from "./knobs.ts";
 
 export type DrawerField =
   | Readonly<{
@@ -41,6 +42,10 @@ export type DrawerField =
       maxText: string;
       /** Just caught by a detent: the bar brightens for one frame. */
       flash?: string | undefined;
+      /** Other panes with this parameter open (`B C`), dim at the right. */
+      peers?: string | undefined;
+      /** The knob this row is (front page): its glyph and colour. */
+      knob?: KnobIndex | undefined;
     }>
   | Readonly<{
       kind: "choice";
@@ -48,6 +53,8 @@ export type DrawerField =
       options: readonly string[];
       index: number;
       committedIndex?: number | undefined;
+      peers?: string | undefined;
+      knob?: KnobIndex | undefined;
     }>;
 
 export type DrawerView = Readonly<{
@@ -63,8 +70,35 @@ export type DrawerView = Readonly<{
   /** `♪ solo · B` while the audition loop plays. */
   status?: string | undefined;
   hint: string;
+  /**
+   * Every param on the page behind Tab, while the drawer shows the four
+   * knobs: a wide drawer lists them beside the knobs (`DRAWER_MEASURE`).
+   */
+  aside?: readonly DrawerAside[] | undefined;
 }>;
 
+/** One row of the drawer's side list: a param and its value. */
+export type DrawerAside = Readonly<{
+  label: string;
+  text: string;
+  knob?: KnobIndex | undefined;
+}>;
+
+/**
+ * The widest a drawer row (label, value, bar, range) runs: a fader bar past
+ * this is no easier to read or aim. Room right of it lists the page's other
+ * params when the view has an aside, else stays panel.
+ */
+export const DRAWER_MEASURE = 96;
+/** The fewest columns the side list needs beside the rows. */
+export const ASIDE_MIN_WIDTH = 28;
+
+/** Columns the side list gets in a drawer `width` wide (0: none). */
+export function asideWidth(width: number): number {
+  const room = width - 4 - DRAWER_MEASURE - 3;
+  return room >= ASIDE_MIN_WIDTH ? Math.min(room, 48) : 0;
+}
+
 export type DrawerMode = "full" | "compact" | "line";
 
 export interface DrawerLayout {
@@ -89,12 +123,20 @@ export function keepAbove(regionHeight: number): number {
  * its bottom, as tall as its fields need within the budget.
  */
 export function drawerLayout(
-  view: Pick<DrawerView, "fields" | "focus">,
+  view: Pick<DrawerView, "fields" | "focus"> &
+    Partial<Pick<DrawerView, "aside">>,
   region: { y: number; height: number },
+  width = 0,
 ): DrawerLayout {
   const total = Math.max(1, view.fields.length);
   const bottom = region.y + region.height;
   const budget = region.height - keepAbove(region.height);
+  // A side list beside the knobs may make a full drawer taller, never
+  // past half the region.
+  const aside =
+    view.aside && asideWidth(width) > 0
+      ? Math.min(view.aside.length + 1, Math.floor(region.height / 2) - 2)
+      : 0;
   const window = (rows: number): { first: number; count: number } => {
     const count = Math.max(1, Math.min(total, rows));
     const focus = Math.min(Math.max(0, view.focus), total - 1);
@@ -102,7 +144,7 @@ export function drawerLayout(
     return { first, count };
   };
   if (2 + 2 * total <= Math.floor(region.height / 2)) {
-    const height = 2 + 2 * total;
+    const height = 2 + Math.max(2 * total, aside);
     return {
       mode: "full",
       top: bottom - height,
@@ -197,7 +239,7 @@ export function paintDrawer(
 ): DrawerLayout | undefined {
   if (region.height <= 0 || width < 16 || view.fields.length === 0)
     return undefined;
-  const layout = drawerLayout(view, region);
+  const layout = drawerLayout(view, region, width);
   const flashing = !options.reducedMotion && !flashed.has(view);
   if (view.fields.some((field) => field.kind === "number" && field.flash))
     flashed.add(view);
@@ -290,6 +332,19 @@ export function paintDrawer(
         on(roles.muted),
       );
   }
+  const outer = inner;
+  inner = {
+    left: inner.left,
+    right: Math.min(inner.right, inner.left + DRAWER_MEASURE),
+  };
+  if (layout.bordered && view.aside)
+    paintAside(buffer, layout, outer.right, view.aside, {
+      glyphs,
+      roles,
+      on,
+      theme: options.theme,
+      unicode: options.unicode,
+    });
   const labelWidth = Math.min(
     layout.mode === "full" ? 22 : 16,
     Math.max(...view.fields.map((field) => displayWidth(field.label))),
@@ -308,12 +363,25 @@ export function paintDrawer(
     const labelStyle = focused
       ? on({ ...roles.borderFocus, bold: true })
       : on(roles.text);
-    buffer.text(inner.left, y, marker, labelStyle);
+    if (field.knob !== undefined) {
+      // A knob row: its shape glyph in its colour, then the marker, so
+      // colour is never the only cue (NO_COLOR keeps the shape).
+      buffer.text(
+        inner.left,
+        y,
+        knobGlyph(field.knob, options.unicode),
+        on(knobStyle(field.knob, options.theme)),
+      );
+      buffer.text(inner.left + 1, y, focused ? glyphs.marker : " ", labelStyle);
+    } else buffer.text(inner.left, y, marker, labelStyle);
     buffer.text(
       inner.left + 2,
       y,
       truncate(field.label, labelWidth),
-      labelStyle,
+      // The selected knob's label is reverse video (§7.2).
+      field.knob !== undefined && focused
+        ? on({ ...roles.text, bold: true, reverse: true })
+        : labelStyle,
     );
     const valueX = inner.left + 2 + labelWidth + 2;
     const typing = focused && view.typing !== undefined;
@@ -353,6 +421,7 @@ export function paintDrawer(
           flashing,
           roles,
           on,
+          knob: knobFill(field, options.theme),
           ...(hits ? { hits } : {}),
         });
       } else {
@@ -373,7 +442,15 @@ export function paintDrawer(
           inner.right,
           field,
           index,
-          { glyphs, focused, flashing, roles, on, ...(hits ? { hits } : {}) },
+          {
+            glyphs,
+            focused,
+            flashing,
+            roles,
+            on,
+            knob: knobFill(field, options.theme),
+            ...(hits ? { hits } : {}),
+          },
         );
       }
     } else {
@@ -395,10 +472,87 @@ export function paintDrawer(
           );
       }
     }
+    // Other panes with this parameter open: their letters, dim, at the
+    // row's right edge (design §12.7).
+    if (field.peers) {
+      const peers = ` ${field.peers}`;
+      buffer.text(
+        Math.max(valueX, inner.right - displayWidth(peers)),
+        y,
+        peers,
+        on(roles.muted),
+      );
+    }
   }
   return layout;
 }
 
+/**
+ * `all params · tab` and every param on the page, one per row, beside the
+ * knobs: what Tab would show, without leaving the knobs.
+ */
+function paintAside(
+  buffer: CellBuffer,
+  layout: DrawerLayout,
+  right: number,
+  aside: readonly DrawerAside[],
+  paint: {
+    glyphs: Glyphs;
+    roles: Theme["roles"];
+    on: (style: Style) => Style;
+    theme: Theme;
+    unicode: boolean;
+  },
+): void {
+  const width = asideWidth(right + 2);
+  if (width === 0) return;
+  const { roles, on } = paint;
+  const left = right - width;
+  const rows = layout.height - 2;
+  if (rows < 2) return;
+  const top = layout.top + 1;
+  const rule = paint.unicode ? "│" : "|";
+  for (let y = top; y < top + rows; y += 1)
+    buffer.set(left - 2, y, rule, on(roles.faint));
+  buffer.text(left, top, truncate("all params · tab", width), on(roles.muted));
+  const room = rows - 1;
+  const shown =
+    aside.length > room ? aside.slice(0, Math.max(0, room - 1)) : aside;
+  const labelWidth = Math.min(
+    Math.floor(width / 2),
+    Math.max(0, ...shown.map((row) => displayWidth(row.label))),
+  );
+  shown.forEach((row, index) => {
+    const y = top + 1 + index;
+    if (row.knob !== undefined)
+      buffer.text(
+        left,
+        y,
+        knobGlyph(row.knob, paint.unicode),
+        on(knobStyle(row.knob, paint.theme)),
+      );
+    buffer.text(left + 2, y, truncate(row.label, labelWidth), on(roles.text));
+    const valueX = left + 2 + labelWidth + 1;
+    buffer.text(
+      valueX,
+      y,
+      truncate(row.text, Math.max(0, right - valueX)),
+      on(roles.muted),
+    );
+  });
+  if (shown.length < aside.length)
+    buffer.text(
+      left + 2,
+      top + room,
+      truncate(`+${aside.length - shown.length} more · tab`, width - 2),
+      on(roles.faint),
+    );
+}
+
+function knobFill(field: DrawerField, theme: Theme): Style | undefined {
+  return field.knob === undefined ? undefined : knobStyle(field.knob, theme);
+}
+
 interface RowPaint {
   glyphs: Glyphs;
   focused: boolean;
@@ -407,6 +561,8 @@ interface RowPaint {
   roles: Theme["roles"];
   on: (style: Style) => Style;
   hits?: HitMap;
+  /** A knob row's bar fills in its knob colour. */
+  knob?: Style | undefined;
 }
 
 /** `[−] ━━━━━●─────── [+]` from `left` to `right`, with its hit regions. */
@@ -457,9 +613,11 @@ function paintBar(
   const filled = on(
     flash
       ? { ...roles.success, bold: true }
-      : paint.focused
-        ? roles.borderFocus
-        : roles.text,
+      : paint.knob
+        ? paint.knob
+        : paint.focused
+          ? roles.borderFocus
+          : roles.text,
   );
   const empty = on(roles.faint);
   for (let column = 0; column < barWidth; column += 1) {

package/tui/grammar.ts

@@ -126,7 +126,7 @@ export const HINTS = {
   action: " ↑↓ move · enter apply · / filter · esc back · ? keys ",
   typing: " type a value · enter apply · esc clear ",
   euclid:
-    " ↑↓ drum · ←→ adjust · tab field · space loop · x off · esc back · ? keys ",
+    " ↑↓ knob · ←→ turn · tab field · space loop · x off · esc back · ? keys ",
   text: " ↑↓ scroll · pgup pgdn page · esc back · ? keys ",
   log: " ↑↓ scroll · / filter · esc back · ? keys ",
   keys: " esc or ? closes ",
@@ -289,9 +289,9 @@ export const KEYS = {
     {
       title: "rhythm editor",
       rows: [
-        ["↑ ↓  j k", "drum"],
-        ["← →  h l  - +", "adjust the field"],
-        ["tab shift-tab  ] [", "next / previous field"],
+        ["↑ ↓  j k", "knob: ● drum ▲ pulses ■ rotate ◆ velocity"],
+        ["← →  h l  - +", "turn it (● picks the drum row)"],
+        ["tab shift-tab  ] [", "next / previous field, every field"],
         ["0-9", "type a value, enter applies"],
         ["enter", "add a row (or type a value) · staged: keep"],
         ["x d delete", "turn the row off"],
@@ -347,7 +347,7 @@ export const KEYS = {
         ["shift", "sustain while held"],
         ["tab", "sustain latch (play mode only)"],
         ["space", "play / pause (with count-in)"],
-        ["r R", "record · record replacing"],
+        ["r R", "record · replace · keys record (a pass an undo)"],
         ["m", "metronome click"],
         ["i", "scale degrees ⇄ chromatic (home row in key)"],
         ["q", "chord mode: auto ⇄ manual"],
@@ -357,6 +357,35 @@ export const KEYS = {
       ],
     },
   ],
+  tape: [
+    {
+      title: "tape · every track across the bars (each key echoes its command)",
+      rows: [
+        ["space", "play / pause from the playhead"],
+        ["↑ ↓", "pick a knob: ● playhead ▲ loop ■ tempo ◆ volume"],
+        ["← → ⇧", "turn it (⇧ coarse) · jump 5.3 · loop 5-7 · tempo 96"],
+        [", .", "previous / next section · jump chorus"],
+        ["< >", "slide the loop by its length · loop 7-8"],
+        ["[ ]", "loop end a bar shorter / longer · loop 5-7"],
+        ["{ }", "loop start a bar earlier / later · loop 4-7"],
+        ["\\", "loop the section here; again: off · loop chorus"],
+        ["1-9 tab", "focus a track row; tab: the next · track drums"],
+        ["c C", "copy the range (track / all) · copy bass 5-6"],
+        ["x X", "cut: copy, then clear · clear bass 5-6"],
+        ["v V", "paste at the playhead (V inserts) · copy bass 5-6 to 7"],
+        ["delete", "clear the range · clear bass 5-6"],
+        ["~", "reverse the range · reverse bass 5-6"],
+        ["s S", "split / join the section here · section split verse at 3"],
+        ["h H", "mute / solo the track · mute bass · solo"],
+        ["r R", "record the loop in play, a pass an undo · keys record"],
+        ["m b", "click · stop"],
+        ["- =", "zoom out / in (bar, beat, half beat a cell)"],
+        ["enter", "the knob big in the drawer (reset there: x)"],
+        ["/", "type a command, staying on tape"],
+        ["esc ctrl-t", "back home · tape"],
+      ],
+    },
+  ],
   chords: [
     {
       title: "chord mode · number row latches",

package/tui/guide.ts

@@ -119,6 +119,8 @@ export class GuideBrowser {
   /** The guide open as a page, or undefined in the tree. */
   page: string | undefined;
   scroll = 0;
+  /** At the last page: resizes keep the end in view. */
+  private atEnd = false;
 
   constructor(guides: readonly Guide[], open?: string) {
     this.guides = guides;
@@ -146,6 +148,7 @@ export class GuideBrowser {
     this.selected = guide.id;
     this.page = guide.id;
     this.scroll = 0;
+    this.atEnd = false;
     return true;
   }
 
@@ -212,6 +215,7 @@ export class GuideBrowser {
     if (this.visible().some((row) => row.guide.id === this.selected)) {
       this.page = this.selected;
       this.scroll = 0;
+      this.atEnd = false;
     }
   }
 
@@ -244,11 +248,13 @@ export class GuideBrowser {
                     : 0;
       if (step !== 0) {
         this.scroll = Math.max(0, Math.min(max, this.scroll + step));
+        this.atEnd = max > 0 && this.scroll === max;
         return "handled";
       }
       if (esc || left || value === "h" || value === "\u007f") {
         this.page = undefined;
         this.scroll = 0;
+        this.atEnd = false;
         return "handled";
       }
       return "handled";
@@ -339,7 +345,8 @@ export class GuideBrowser {
     if (page) {
       const rows = wrapRows(guideLines(page.body, unicode), width);
       const max = Math.max(0, rows.length - height);
-      this.scroll = Math.max(0, Math.min(max, this.scroll));
+      // Pinned to the end at the last page: a resize keeps the end in view.
+      this.scroll = this.atEnd ? max : Math.max(0, Math.min(max, this.scroll));
       const crumb = page.parent ? `${this.byId(page.parent)?.title} › ` : "";
       return {
         title: `guide · ${crumb}${page.title}`.replace(

package/tui/highway.ts

@@ -80,6 +80,8 @@ export interface TrackScoreSnapshot {
    */
   barBeats?: readonly number[] | undefined;
   loopBeats?: number | undefined;
+  /** The score's loop range (0-based start bar), for the header's `↻ 5–6`. */
+  loopRange?: Readonly<{ startBar: number; bars: number }> | undefined;
   laneCount?: number | undefined;
   /** Optional lane legend (drum voices) drawn just below the hit line. */
   laneLabels?: readonly string[] | undefined;
@@ -278,7 +280,10 @@ export function pitchProjection(
 }
 
 /** Choose the projection a snapshot implies. */
-export function projectionFor(score: TrackScoreSnapshot): LaneProjection {
+export function projectionFor(
+  score: TrackScoreSnapshot,
+  minimumSpan = 12,
+): LaneProjection {
   if (score.projection) return score.projection;
   const explicit =
     score.laneLabels !== undefined ||
@@ -295,7 +300,7 @@ export function projectionFor(score: TrackScoreSnapshot): LaneProjection {
     .flatMap((layer) => layer.notes);
   return pitchProjection(
     melodic.length ? [...score.notes, ...melodic] : score.notes,
-    12,
+    minimumSpan,
     score.tuningPeriod,
   );
 }
@@ -494,6 +499,28 @@ export interface HighwayLayout {
   legendRow: number | undefined;
 }
 
+/**
+ * The widest a lane gets. A wider terminal shows more pitches (up to
+ * `MAX_PITCH_SPAN`) instead of fatter tiles, and past that the lanes stay
+ * this wide, centred.
+ */
+export const MAX_LANE_WIDTH = 10;
+/** The most semitones a melodic highway spreads across on a wide terminal. */
+export const MAX_PITCH_SPAN = 36;
+/**
+ * The tallest a beat gets. A taller terminal looks further ahead (more bars
+ * coming) instead of stretching each note.
+ */
+export const MAX_ROWS_PER_BEAT = 4;
+
+/** The pitch span a highway `width` columns wide fits: one to three octaves. */
+export function pitchSpanFor(width: number): number {
+  return Math.max(
+    12,
+    Math.min(MAX_PITCH_SPAN, Math.floor((width - 3) / MAX_LANE_WIDTH)),
+  );
+}
+
 export function highwayLayout(
   region: HighwayRegion,
   projection: LaneProjection,
@@ -505,13 +532,21 @@ export function highwayLayout(
   const gutter = region.width >= 40 ? 3 : 0;
   const area = Math.max(1, region.width - gutter);
   const laneCount = projection.laneCount;
-  const laneWidth = laneCount <= area ? Math.floor(area / laneCount) : 0;
+  const laneWidth =
+    laneCount <= area
+      ? Math.min(MAX_LANE_WIDTH, Math.floor(area / laneCount))
+      : 0;
   const used = laneWidth > 0 ? laneWidth * laneCount : area;
   const laneLeft = gutter + Math.floor((area - used) / 2);
   const tileWidth =
     laneWidth >= 4 ? laneWidth - 1 : Math.max(1, laneWidth || 1);
   const lookahead =
-    lookaheadBeats ?? Math.max(2, Math.min(8, Math.round(hitRow / 2.5)));
+    lookaheadBeats ??
+    Math.max(
+      2,
+      Math.min(8, Math.round(hitRow / 2.5)),
+      Math.floor(hitRow / MAX_ROWS_PER_BEAT),
+    );
   return {
     hitRow,
     gutter,
@@ -561,7 +596,7 @@ export function paintHighway(
   const glyphs = glyphsFor(capabilities);
   const background = options.background ?? roles.canvas;
   const bg = (style: Style): Style => onBackground(style, background);
-  const projection = projectionFor(score);
+  const projection = projectionFor(score, pitchSpanFor(region.width));
   const layout = highwayLayout(region, projection, options.lookaheadBeats);
   const { hitRow, rowsPerBeat, gutter } = layout;
   const areaWidth = Math.max(1, region.width - gutter);

package/tui/hints.ts

@@ -80,6 +80,11 @@ const TYPE_FILLED = [
   "try: style again · ctrl-z undo",
   "try: add G4 at 2 · bars 8 · space play",
   "try: volume 0.6 · pan -0.2 · /help",
+  "try: ctrl-t tape · loop 1-2 · space play",
+  "try: copy all 1-4 to 5 · loop 5-8",
+  "try: knobs · mix · /help mix",
+  "try: panes · pane tape · /help panes",
+  "try: loop 1-2 · keys record · ctrl-z takes back a pass",
 ] as const;
 
 const TYPE_DRUMS = [

package/tui/hits.ts

@@ -27,7 +27,13 @@ export type HitTarget =
   /** The piano roll / highway area. */
   | { kind: "highway" }
   /** Scrollable text (`/help`, the transcript, the `?` panel). */
-  | { kind: "text" };
+  | { kind: "text" }
+  /** TAPE's ruler: column `x - left + firstCell` is a cell (jump, loop drag). */
+  | { kind: "tape-ruler"; left: number; firstCell: number }
+  /** A TAPE track row (focus; shift-drag sets the loop). */
+  | { kind: "tape-row"; row: number; left: number; firstCell: number }
+  /** TAPE's clipboard chip (click pastes). */
+  | { kind: "tape-clipboard" };
 
 export interface HitRegion {
   x: number;