@hraness/dawg 0.4.0 → 0.5.0

package/tui/app.ts

@@ -25,6 +25,8 @@ import {
   type TrackScoreSnapshot,
 } from "./highway.ts";
 import { asciiHint, fitHint, HINTS } from "./grammar.ts";
+import { GuideBrowser } from "./guide.ts";
+import { listGuides } from "../guides/index.ts";
 import { classifyKey, overlayKey, type UiCommand } from "./keys.ts";
 import { PromptModel, type PromptAction, type PromptMode } from "./prompt.ts";
 import {
@@ -33,7 +35,10 @@ import {
   paintPlayStrip,
   type PlayHeaderView,
 } from "./play-strip.ts";
+import { paintArrangeStrip, type ArrangeStripView } from "./arrange-strip.ts";
 import { CellBuffer, ScreenWriter, type CursorPosition } from "./screen.ts";
+import { paintDrawer, type DrawerLayout, type DrawerView } from "./drawer.ts";
+import { HitMap, type HitTarget } from "./hits.ts";
 import { displayWidth, truncate } from "./text.ts";
 import {
   accentStyle,
@@ -72,6 +77,44 @@ export interface AppView {
   agentOffline?: boolean | undefined;
   /** Play mode: replaces the header and adds the keyboard strip row. */
   play?: PlayHeaderView | undefined;
+  /** Song master meter: integrated LUFS and true peak of the playing loop. */
+  loudness?: LoudnessView | undefined;
+  /** Song sections over the timeline (0.5); no row when absent. */
+  arrange?: ArrangeStripView | undefined;
+}
+
+export type LoudnessView = Readonly<{
+  /** Integrated loudness, LUFS. */
+  integrated: number;
+  /** True peak, dBTP. */
+  truePeak: number;
+  /** The master's loudness target, when one is set. */
+  target?: number | undefined;
+  /** The limiter's ceiling, dBTP, when the limiter is on. */
+  ceiling?: number | undefined;
+  /** A monitor-rate reading shown until the export-rate one is in (`~`). */
+  estimate?: boolean | undefined;
+}>;
+
+/**
+ * `-14.1 LUFS (-14) · TP -1.0`: the compact loudness meter, with the
+ * master's target in brackets when one is set and `~` before a monitor-rate
+ * estimate. Loudness below -70 LUFS (silence) reads `-∞`.
+ */
+export function loudnessMeter(view: LoudnessView): string {
+  const lufs = view.integrated <= -70 ? "-∞" : view.integrated.toFixed(1);
+  const peak = view.truePeak <= -119 ? "-∞" : view.truePeak.toFixed(1);
+  const target = view.target === undefined ? "" : ` (${view.target})`;
+  return `${view.estimate ? "~" : ""}${lufs} LUFS${target} · TP ${peak}`;
+}
+
+/** Whether the meter's reading is off target by more than 0.5 LU. */
+export function loudnessOffTarget(view: LoudnessView): boolean {
+  return (
+    view.target !== undefined &&
+    view.integrated > -70 &&
+    Math.abs(view.integrated - view.target) > 0.5
+  );
 }
 
 export type TypesIndicator = Readonly<{ ok: boolean; errors: number }>;
@@ -89,10 +132,17 @@ export interface UiState {
   text?: TextView | undefined;
   /** The `?` panel: keys for the screen underneath, drawn over it. */
   keys?: TextView | undefined;
+  /** The `/guide` tree and pages. */
+  guide?: GuideBrowser | undefined;
+  /** The fader drawer, docked over the bottom of the piano roll. */
+  drawer?: DrawerView | undefined;
 }
 
-/** `log` is the transcript, `picker` an arrow-key list, `text` static lines. */
-export type Overlay = "log" | "picker" | "text" | undefined;
+/**
+ * `log` is the transcript, `picker` an arrow-key list, `text` static lines,
+ * `guide` the user guides.
+ */
+export type Overlay = "log" | "picker" | "text" | "guide" | undefined;
 
 /** A scrollable read-only panel (`/help`, `/sessions`, `/tracks`). */
 export interface TextView {
@@ -179,6 +229,10 @@ export interface Frame {
   /** Rows used by the prompt editor (excluding borders). */
   promptRows: number;
   layout: FrameLayout;
+  /** Click targets, recorded while painting (topmost last). */
+  hits: HitMap;
+  /** Where the fader drawer landed, when one is open. */
+  drawer?: DrawerLayout | undefined;
 }
 
 export interface FrameLayout {
@@ -261,6 +315,8 @@ interface Segment {
   style: Style;
   /** Lower numbers survive longer when space is short. */
   priority: number;
+  /** What a click on it does. */
+  target?: HitTarget | undefined;
 }
 
 function paintSegments(
@@ -272,6 +328,7 @@ function paintSegments(
   separatorStyle: Style,
   background: Style,
   rightSegments: Segment[] = [],
+  hits?: HitMap,
 ): void {
   const sepWidth = displayWidth(separator);
   const total = (list: Segment[]) =>
@@ -298,12 +355,14 @@ function paintSegments(
         separator,
         onBackground(separatorStyle, background),
       );
-    x += buffer.text(
+    const used = buffer.text(
       x,
       y,
       truncate(segment.text, Math.max(1, width - x - 1)),
       onBackground(segment.style, background),
     );
+    if (segment.target) hits?.add(x, y, used, 1, segment.target);
+    x += used;
   });
   if (right.length) {
     let rx = width - 1 - total(right);
@@ -316,12 +375,14 @@ function paintSegments(
           separator,
           onBackground(separatorStyle, background),
         );
-      rx += buffer.text(
+      const used = buffer.text(
         rx,
         y,
         segment.text,
         onBackground(segment.style, background),
       );
+      if (segment.target) hits?.add(rx, y, used, 1, segment.target);
+      rx += used;
     });
   }
 }
@@ -356,6 +417,7 @@ function paintHeader(
   view: AppView,
   ui: UiState,
   width: number,
+  hits?: HitMap,
 ): void {
   const { theme, capabilities } = ui;
   const roles = theme.roles;
@@ -370,11 +432,13 @@ function paintHeader(
       text: name,
       style: { ...accentStyle(theme, score.trackId ?? name), bold: true },
       priority: 0,
+      target: { kind: "tracks" },
     },
     {
       text: transport,
       style: playing ? roles.transport : roles.paused,
       priority: 0,
+      target: { kind: "transport" },
     },
   ];
   if (score.key)
@@ -395,7 +459,12 @@ function paintHeader(
     });
   const right: Segment[] = [];
   if (view.model)
-    right.push({ text: view.model, style: roles.agent, priority: 2 });
+    right.push({
+      text: view.model,
+      style: roles.agent,
+      priority: 2,
+      target: { kind: "model" },
+    });
   if (score.revision !== undefined)
     right.push({
       text: `rev ${score.revision}`,
@@ -410,9 +479,33 @@ function paintHeader(
       style: view.types.ok ? roles.success : roles.error,
       priority: 4,
     });
+  if (view.loudness)
+    right.push({
+      text: loudnessMeter(view.loudness),
+      // Over full scale is an error; above the limiter's ceiling (-1 dBTP
+      // without one) or off the target by more than 0.5 LU a warning.
+      style:
+        view.loudness.truePeak > 0
+          ? roles.error
+          : view.loudness.truePeak > (view.loudness.ceiling ?? -1) + 0.1 ||
+              loudnessOffTarget(view.loudness)
+            ? roles.warning
+            : roles.muted,
+      priority: 3,
+    });
   const sync = syncSegment(view.sync, theme, unicode);
   if (sync) right.push(sync);
-  paintSegments(buffer, 0, left, width, " · ", roles.faint, roles.panel, right);
+  paintSegments(
+    buffer,
+    0,
+    left,
+    width,
+    " · ",
+    roles.faint,
+    roles.panel,
+    right,
+    hits,
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -818,6 +911,61 @@ function paintText(
   });
 }
 
+function paintGuide(
+  buffer: CellBuffer,
+  ui: UiState,
+  region: { y: number; height: number },
+  width: number,
+): void {
+  const guide = ui.guide;
+  if (!guide) return;
+  const roles = ui.theme.roles;
+  const unicode = ui.capabilities.unicode;
+  const left = width >= 60 ? 2 : 0;
+  const boxWidth = width - left * 2;
+  const height = region.height;
+  if (height < 3 || boxWidth < 10) return;
+  const panel = paintBox(buffer, ui, {
+    left,
+    top: region.y,
+    width: boxWidth,
+    height,
+  });
+  const view = guide.view(boxWidth - 4, height - 2, unicode);
+  buffer.text(
+    left + 2,
+    region.y,
+    ` ${view.title} `,
+    onBackground({ ...roles.text, bold: true }, panel),
+    boxWidth - 4,
+  );
+  const hint = footerHint(view.hint, boxWidth - 4, unicode);
+  if (hint)
+    buffer.text(
+      left + boxWidth - 2 - displayWidth(hint),
+      region.y + height - 1,
+      hint,
+      onBackground(roles.muted, panel),
+    );
+  view.rows.forEach((row, index) => {
+    const style = row.selected
+      ? { ...roles.borderFocus, bold: true }
+      : row.heading
+        ? { ...roles.borderFocus, bold: true }
+        : row.muted
+          ? roles.muted
+          : roles.text;
+    const marker = row.selected ? (unicode ? "›" : ">") : " ";
+    const text = guide.page === undefined ? `${marker}${row.text}` : row.text;
+    buffer.text(
+      left + 2,
+      region.y + 1 + index,
+      truncate(text, boxWidth - 4),
+      onBackground(style, panel),
+    );
+  });
+}
+
 function paintBox(
   buffer: CellBuffer,
   ui: UiState,
@@ -849,6 +997,7 @@ function paintPicker(
   ui: UiState,
   region: { y: number; height: number },
   width: number,
+  hits?: HitMap,
 ): void {
   const picker = ui.picker;
   if (!picker) return;
@@ -916,6 +1065,7 @@ function paintPicker(
   picker.items.slice(first, first + inner).forEach((item, offset) => {
     const index = first + offset;
     const y = region.y + 1 + offset;
+    hits?.add(left + 1, y, boxWidth - 2, 1, { kind: "picker-row", index });
     const selected = index === picker.index;
     const marker = selected ? (ui.capabilities.unicode ? "›" : ">") : " ";
     const style = selected
@@ -998,9 +1148,16 @@ export function composeFrame(
   const buffer = new CellBuffer(width, height, ui.theme.roles.canvas);
   ui.prompt.setWidth(promptEditorWidth(width));
   const layout = computeLayout({ width, height }, ui.prompt.wrappedRows);
+  const hits = new HitMap();
   if (layout.tooSmall) {
     paintTooSmall(buffer, ui, { width, height });
-    return { buffer, cursor: undefined, promptRows: 0, layout };
+    return {
+      buffer,
+      cursor: undefined,
+      promptRows: 0,
+      layout,
+      hits: new HitMap(),
+    };
   }
   if (view.play) {
     paintPlayHeader(
@@ -1031,14 +1188,36 @@ export function composeFrame(
         height: layout.highway.height - 1,
       };
     }
-  } else paintHeader(buffer, view, ui, width);
+  } else paintHeader(buffer, view, ui, width, hits);
+  if (view.arrange && layout.highway.height > 4) {
+    paintArrangeStrip(
+      buffer,
+      layout.highway.y,
+      width,
+      view.arrange,
+      ui.theme,
+      ui.capabilities.unicode,
+    );
+    layout.highway = {
+      y: layout.highway.y + 1,
+      height: layout.highway.height - 1,
+    };
+  }
   const beat = view.beat ?? resolveBeat(view.score, nowMs);
+  let drawer: DrawerLayout | undefined;
   if (layout.highway.height > 0) {
-    if (ui.overlay === "log") paintOverlay(buffer, ui, layout.highway, width);
-    else if (ui.overlay === "picker" && ui.picker)
-      paintPicker(buffer, ui, layout.highway, width);
+    hits.add(0, layout.highway.y, width, layout.highway.height, {
+      kind: ui.overlay && !ui.drawer ? "text" : "highway",
+    });
+    // The drawer replaces the menu's list: the piano roll shows above it.
+    if (ui.overlay === "log" && !ui.drawer)
+      paintOverlay(buffer, ui, layout.highway, width);
+    else if (ui.overlay === "picker" && ui.picker && !ui.drawer)
+      paintPicker(buffer, ui, layout.highway, width, hits);
     else if (ui.overlay === "text" && ui.text)
       paintText(buffer, ui, layout.highway, width);
+    else if (ui.overlay === "guide" && ui.guide)
+      paintGuide(buffer, ui, layout.highway, width);
     else
       paintHighway(
         buffer,
@@ -1051,6 +1230,15 @@ export function composeFrame(
           reducedMotion: ui.reducedMotion,
         },
       );
+    if (ui.drawer)
+      drawer = paintDrawer(
+        buffer,
+        layout.highway,
+        width,
+        ui.drawer,
+        { theme: ui.theme, unicode: ui.capabilities.unicode },
+        hits,
+      );
   }
   if (ui.keys && layout.highway.height > 0)
     paintText(buffer, ui, keysRegion(layout.highway, ui.keys), width, {
@@ -1059,7 +1247,14 @@ export function composeFrame(
     });
   paintActivity(buffer, layout.activity, ui, width, nowMs);
   const prompt = paintPrompt(buffer, view, ui, layout, width);
-  return { buffer, cursor: prompt.cursor, promptRows: prompt.rows, layout };
+  return {
+    buffer,
+    cursor: prompt.cursor,
+    promptRows: prompt.rows,
+    layout,
+    hits,
+    drawer,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -1112,6 +1307,8 @@ export class TuiApp {
   log: LogView = { scroll: 0, filter: "all" };
   picker: PickerState | undefined;
   text: TextView | undefined;
+  /** The fader drawer's paint model while one is open. */
+  drawer: DrawerView | undefined;
   /** `/view all` overlays every unmuted track; `/view focus` shows one. */
   highwayView: "all" | "focus" = "all";
   private writer: ScreenWriter;
@@ -1149,6 +1346,8 @@ export class TuiApp {
       picker: this.picker,
       text: this.text,
       keys: this.keys,
+      guide: this.guide,
+      drawer: this.drawer,
     };
   }
 
@@ -1272,6 +1471,18 @@ export class TuiApp {
       }
       return { type: "overlay" };
     }
+    if (this.overlay === "guide" && this.guide) {
+      if (
+        key.type === "ui" &&
+        (key.command === "quit" || key.command === "redraw")
+      ) {
+        if (key.command === "redraw") this.invalidate();
+        return { type: "ui", command: key.command };
+      }
+      const result = this.guide.key(value, Math.max(1, this.io.rows() - 10));
+      if (result === "close") this.closeGuide();
+      return { type: "overlay" };
+    }
     if (this.overlay === "text" && this.text) {
       const nav = overlayKey(value);
       const page = Math.max(1, this.io.rows() - 10);
@@ -1434,13 +1645,42 @@ export class TuiApp {
     return this.overlay === "picker" && this.picker?.filtering === true;
   }
 
+  /** The `/guide` pane; built on first use from `guides/*.md`. */
+  guide: GuideBrowser | undefined;
+
+  /**
+   * Open the guides at the tree, or at one guide (`chords`). Returns false
+   * (and opens nothing) when `topic` names no guide.
+   */
+  openGuide(topic?: string): boolean {
+    const browser = this.guide ?? new GuideBrowser(listGuides());
+    if (topic && !browser.open(topic)) return false;
+    if (!topic) {
+      browser.page = undefined;
+      browser.query = "";
+      browser.filtering = false;
+    }
+    this.guide = browser;
+    this.overlay = "guide";
+    return true;
+  }
+
+  closeGuide(): void {
+    if (this.overlay === "guide") this.overlay = undefined;
+  }
+
+  /** True while the guide filter takes typed text (so `?` is a letter). */
+  get guideTyping(): boolean {
+    return this.overlay === "guide" && this.guide?.typing === true;
+  }
+
   closeText(): void {
     this.text = undefined;
     if (this.overlay === "text") this.overlay = undefined;
   }
 
   /**
-   * Handle TUI-local slash commands (`/log`, `/theme`, `/motion`).
+   * Handle TUI-local slash commands (`/log`, `/theme`, `/motion`, `/guide`).
    * Returns a receipt, or undefined when the command is not a UI command.
    */
   command(text: string): string | undefined {
@@ -1464,6 +1704,15 @@ export class TuiApp {
         ? `theme ${name} · terminal has no color, showing mono`
         : `theme ${name}`;
     }
+    const guide = command.match(/^\/guides?(?:\s+(.+))?$/i);
+    if (guide) {
+      const topic = guide[1]?.trim();
+      if (!this.openGuide(topic))
+        return `no guide named ${topic} · /guide lists them all`;
+      return topic
+        ? `guide · ${this.guide?.guides.find((g) => g.id === this.guide?.page)?.title ?? topic} · esc back`
+        : "guides · → open · esc closes";
+    }
     const view = command.match(/^\/view(?:\s+(\S+))?$/i);
     if (view) {
       const value = view[1]?.toLowerCase();

package/tui/arrange-strip.ts

@@ -0,0 +1,174 @@
+/**
+ * The arrangement strip (0.5): one row under the header that shows the
+ * song's sections over the bar timeline, like the arranger track in Logic,
+ * Cubase or Studio One. Each section is a block with its name; the looped
+ * section is reversed, the one under the playhead is bold, and the playhead
+ * is a caret. Bars with no section are a faint rule. The strip is absent
+ * when the song has no sections, so a 0.4 screen keeps every row it had.
+ *
+ * The shape is structural so the TUI does not depend on core.
+ */
+import type { CellBuffer } from "./screen.ts";
+import { displayWidth, truncate } from "./text.ts";
+import { accentStyle, onBackground, type Style, type Theme } from "./theme.ts";
+
+export type ArrangeStripSection = Readonly<{
+  name: string;
+  /** 0-based first bar. */
+  startBar: number;
+  bars: number;
+}>;
+
+export type ArrangeStripView = Readonly<{
+  /** Bars on the timeline (the score's `bars`). */
+  bars: number;
+  sections: readonly ArrangeStripSection[];
+  /** The looped section's name, if any. */
+  loop?: string | undefined;
+  /** Playhead in bars (fractional), score time. */
+  playheadBar?: number | undefined;
+  /** `intro verse chorus×2`, shown at the right edge when it fits. */
+  form?: string | undefined;
+}>;
+
+/** One painted cell of the strip, for tests and narrow terminals. */
+export type ArrangeStripCell = Readonly<{
+  ch: string;
+  /** Index into `view.sections`, or -1 for an unmarked bar. */
+  section: number;
+  playhead: boolean;
+}>;
+
+/**
+ * Lay the strip out over `width` cells: each cell covers `bars / width`
+ * bars and shows the section that starts latest at or before it (a later
+ * marker wins where sections overlap). Names start at a section's first
+ * cell and are cut at the next boundary.
+ */
+export function arrangeStripCells(
+  view: ArrangeStripView,
+  width: number,
+  unicode = true,
+): ArrangeStripCell[] {
+  const cells: ArrangeStripCell[] = [];
+  const bars = Math.max(1, view.bars);
+  const span = Math.max(1, Math.floor(width));
+  const owner = (bar: number): number => {
+    let found = -1;
+    let start = -1;
+    view.sections.forEach((section, index) => {
+      if (
+        bar >= section.startBar &&
+        bar < section.startBar + section.bars &&
+        section.startBar >= start
+      ) {
+        found = index;
+        start = section.startBar;
+      }
+    });
+    return found;
+  };
+  const playCell =
+    view.playheadBar === undefined
+      ? -1
+      : Math.min(span - 1, Math.floor((view.playheadBar / bars) * span));
+  for (let x = 0; x < span; x++) {
+    const bar = Math.floor((x / span) * bars);
+    const section = owner(bar);
+    cells.push({
+      ch: section < 0 ? (unicode ? "─" : "-") : " ",
+      section,
+      playhead: x === playCell,
+    });
+  }
+  // Names: from each run's first cell; a run is consecutive cells of one
+  // section. A run too short for the name gets its first letters.
+  let x = 0;
+  while (x < span) {
+    const section = cells[x]!.section;
+    let end = x;
+    while (end < span && cells[end]!.section === section) end++;
+    if (section >= 0) {
+      const name = view.sections[section]!.name;
+      const room = end - x - (end - x > 2 ? 1 : 0);
+      const label = room > 0 ? truncate(name, room, unicode ? "…" : "~") : "";
+      // A boundary bar: one cell gap between neighbours when there is room.
+      let at = x + (end - x > 2 ? 1 : 0);
+      for (const ch of label) {
+        if (at >= end) break;
+        cells[at] = { ...cells[at]!, ch };
+        at += Math.max(1, displayWidth(ch));
+      }
+      if (end - x > 2) cells[x] = { ...cells[x]!, ch: unicode ? "▏" : "|" };
+    }
+    x = end;
+  }
+  return cells;
+}
+
+/** Plain text of the strip, for tests. */
+export function arrangeStripText(
+  view: ArrangeStripView,
+  width: number,
+  unicode = true,
+): string {
+  return arrangeStripCells(view, width, unicode)
+    .map((cell) => (cell.playhead ? (unicode ? "▼" : "v") : cell.ch))
+    .join("");
+}
+
+export function paintArrangeStrip(
+  buffer: CellBuffer,
+  y: number,
+  width: number,
+  view: ArrangeStripView,
+  theme: Theme,
+  unicode: boolean,
+): void {
+  const roles = theme.roles;
+  buffer.fill(0, y, width, 1, roles.canvas);
+  const form = view.form ? `form ${view.form}` : "";
+  const formWidth = displayWidth(form);
+  // The form goes right when the timeline keeps at least 24 cells.
+  const showForm = form !== "" && width - formWidth - 3 >= 24;
+  const stripWidth = Math.max(1, width - 2 - (showForm ? formWidth + 2 : 0));
+  const cells = arrangeStripCells(view, stripWidth, unicode);
+  const playSection =
+    view.playheadBar === undefined
+      ? -1
+      : (cells.find((cell) => cell.playhead)?.section ?? -1);
+  cells.forEach((cell, index) => {
+    const x = 1 + index;
+    if (cell.section < 0) {
+      buffer.set(
+        x,
+        y,
+        cell.playhead ? (unicode ? "▼" : "v") : cell.ch,
+        cell.playhead ? { ...roles.hit, bold: true } : roles.faint,
+      );
+      return;
+    }
+    const section = view.sections[cell.section]!;
+    const accent = accentStyle(theme, section.name);
+    const looped = view.loop === section.name;
+    const style: Style = {
+      ...accent,
+      reverse: true,
+      bold: looped || cell.section === playSection,
+      ...(looped ? {} : { dim: cell.section !== playSection }),
+    };
+    buffer.set(
+      x,
+      y,
+      cell.playhead ? (unicode ? "▼" : "v") : cell.ch,
+      cell.playhead ? { ...roles.hit, reverse: true, bold: true } : style,
+    );
+  });
+  if (showForm)
+    buffer.text(
+      width - 1 - formWidth,
+      y,
+      form,
+      onBackground(roles.muted, roles.canvas),
+    );
+}