@hraness/dawg 0.7.0 → 0.8.0

package/tui/app.ts

@@ -12,6 +12,7 @@
  * injectable `TerminalIO`.
  */
 
+import { paintTape, type TapeView } from "./tape.ts";
 import {
   ActivityFeed,
   ERROR_FADE_MS,
@@ -76,8 +77,10 @@ export interface AppView {
   sync?: SyncState | undefined;
   /** Human session name; replaces the short id in the header when set. */
   sessionName?: string | undefined;
-  /** Live windows on this session (presence); shown when more than one. */
+  /** Live panes on this session (presence); shown when more than one. */
   windows?: number | undefined;
+  /** This pane's letter (dawgd), shown beside the count: `B ⧉3` (`B 3 panes` in ASCII). */
+  pane?: string | undefined;
   /** Project typecheck result; `types ✓` or `types ✗ N` beside sync. */
   types?: TypesIndicator | undefined;
   /**
@@ -95,6 +98,8 @@ export interface AppView {
     { ghost?: string | undefined; caption?: string | undefined } | undefined;
   /** Play mode: replaces the header and adds the keyboard strip row. */
   play?: PlayHeaderView | undefined;
+  /** TAPE (op1-ux §6): replaces the highway and the arrange strip. */
+  tape?: TapeView | 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. */
@@ -267,8 +272,40 @@ export interface FrameLayout {
   tooSmall: boolean;
 }
 
-export const MIN_WIDTH = 24;
-export const MIN_HEIGHT = 8;
+/**
+ * The smallest terminal the real UI draws in (DAWG.md "Terminal
+ * sizes"). Measured with `bun run sizes`: below 60 columns the play-mode
+ * key strip and the header's bar position drop out and the prompt's spend
+ * line clips; below 16 rows the prompt loses its footer and the drawer its
+ * last knob. 80x24 stays the design target.
+ */
+export const MIN_WIDTH = 60;
+export const MIN_HEIGHT = 16;
+
+/** True when a terminal of this size shows the too-small screen instead. */
+export function isTooSmall(size: FrameSize): boolean {
+  return !(size.width >= MIN_WIDTH && size.height >= MIN_HEIGHT);
+}
+/**
+ * The longest line a text panel (help, guides, the transcript, menus) sets:
+ * past about 100 columns prose stops being readable and a command table's
+ * two columns drift apart, so on a wide terminal the panel holds this
+ * measure, left-aligned, and the song keeps drawing beside it (see
+ * `SIDE_MIN_WIDTH`).
+ */
+export const TEXT_MEASURE = 100;
+/** The fewest columns beside a capped panel worth drawing the view into. */
+export const SIDE_MIN_WIDTH = 36;
+
+/** Where a text panel sits in a terminal `width` columns wide. */
+export function panelRect(
+  width: number,
+  measure = TEXT_MEASURE,
+): { left: number; boxWidth: number } {
+  const left = width >= 60 ? 2 : 0;
+  return { left, boxWidth: Math.min(width - left * 2, measure + 4) };
+}
+
 export const MAX_PROMPT_ROWS = 8;
 /** New cards glow for this long before settling. */
 export const CARD_GLOW_MS = 700;
@@ -306,7 +343,7 @@ export function computeLayout(
   size: FrameSize,
   promptWrappedRows: number,
 ): FrameLayout {
-  const tooSmall = size.width < MIN_WIDTH || size.height < MIN_HEIGHT;
+  const tooSmall = isTooSmall(size);
   const rows = Math.max(
     1,
     Math.min(promptWrappedRows, promptRowCap(size.height)),
@@ -450,6 +487,54 @@ export function playContext(
   ].join(" · ");
 }
 
+/** `5.3`: the 1-based bar and beat of a song beat. */
+export function barBeatLabel(
+  beat: number,
+  beatsPerBar: number,
+  barBeats?: readonly number[],
+): string {
+  const at = Number.isFinite(beat) ? Math.max(0, beat) : 0;
+  if (barBeats && barBeats.length > 0) {
+    let bar = 0;
+    while (bar + 1 < barBeats.length && barBeats[bar + 1]! <= at + 1e-9)
+      bar += 1;
+    return `${bar + 1}.${Math.floor(at - barBeats[bar]! + 1e-9) + 1}`;
+  }
+  const per = Math.max(1, beatsPerBar);
+  const bar = Math.floor(at / per + 1e-9);
+  return `${bar + 1}.${Math.floor(at - bar * per + 1e-9) + 1}`;
+}
+
+/** `↻ 5–6` (`loop 5-6` without Unicode): the loop range, 1-based bars. */
+export function loopRangeLabel(
+  range: Readonly<{ startBar: number; bars: number }>,
+  unicode: boolean,
+): string {
+  const first = range.startBar + 1;
+  const last = range.startBar + range.bars;
+  const bars =
+    first === last ? `${first}` : `${first}${unicode ? "–" : "-"}${last}`;
+  return unicode ? `↻ ${bars}` : `loop ${bars}`;
+}
+
+/** `B ⧉3`: this pane's letter and how many panes are live. */
+export function paneLabel(
+  windows: number,
+  pane: string | undefined,
+  unicode: boolean,
+): string {
+  const count = unicode ? `⧉${windows}` : `${windows} panes`;
+  return pane ? `${pane} ${count}` : count;
+}
+
+/** The footer's right side: the session name, then the spend line. */
+export function footerStatus(view: AppView, sessionId?: string): string {
+  const session =
+    view.sessionName ??
+    (sessionId ? `session ${sessionId.slice(0, 8)}` : undefined);
+  return [session, view.spend].filter(Boolean).join(" · ");
+}
+
 function paintHeader(
   buffer: CellBuffer,
   view: AppView,
@@ -475,14 +560,11 @@ function paintHeader(
   });
   const transport = `${playing ? (unicode ? "▶" : ">") : unicode ? "⏸" : "||"} ${score.bpm ?? 120} BPM`;
   const name = score.trackName ?? score.trackId ?? "track";
+  // dawg · ▶ BPM · bar.beat · ↻ loop · track ··· key · model · rev · pane
+  // (design §8.2): where you are in the song reads first; the session name
+  // lives in the footer.
   const left: Segment[] = [
     { text: "dawg", style: { ...roles.muted, bold: true }, priority: 6 },
-    {
-      text: name,
-      style: { ...accentStyle(theme, score.trackId ?? name), bold: true },
-      priority: 0,
-      target: { kind: "tracks" },
-    },
     {
       text: transport,
       style: playing
@@ -493,24 +575,29 @@ function paintHeader(
       priority: 0,
       target: { kind: "transport" },
     },
+    {
+      text: barBeatLabel(beat, score.beatsPerBar ?? 4, score.barBeats),
+      style: roles.text,
+      priority: 2,
+    },
   ];
-  if (score.key)
-    left.push({ text: score.key, style: roles.muted, priority: 5 });
-  if (view.sessionName)
-    left.push({ text: view.sessionName, style: roles.muted, priority: 3 });
-  else if (score.sessionId)
+  if (score.loopRange)
     left.push({
-      text: `session ${score.sessionId.slice(0, 8)}`,
-      style: roles.muted,
+      text: loopRangeLabel(score.loopRange, unicode),
+      // The loop is the green knob's (§8.1): it wears that colour.
+      style: roles.knob2,
       priority: 3,
     });
-  if (view.windows !== undefined && view.windows > 1)
-    left.push({
-      text: `${view.windows} windows`,
-      style: roles.muted,
-      priority: 4,
-    });
+  left.push({
+    text: name,
+    style: { ...accentStyle(theme, score.trackId ?? name), bold: true },
+    priority: 0,
+    target: { kind: "tracks" },
+  });
   const right: Segment[] = [];
+  // The key never drops before the model, rev or sync at 80 columns.
+  if (score.key)
+    right.push({ text: score.key, style: roles.muted, priority: 1 });
   if (view.model)
     right.push({
       text: view.model,
@@ -524,6 +611,12 @@ function paintHeader(
       style: roles.text,
       priority: 1,
     });
+  if (view.windows !== undefined && view.windows > 1)
+    right.push({
+      text: paneLabel(view.windows, view.pane, unicode),
+      style: roles.muted,
+      priority: 4,
+    });
   if (view.types)
     right.push({
       text: view.types.ok
@@ -768,6 +861,7 @@ function paintPrompt(
   if (view.spend) {
     if (!layout.footer) status.push(view.spend);
   } else if (view.model) status.push(view.model);
+  if (!layout.footer && view.sessionName) status.unshift(view.sessionName);
   if (activity.queueDepth > 0) status.push(`queue ${activity.queueDepth}`);
   const layoutInfo = prompt.layout(rows);
   if (layoutInfo.total > rows)
@@ -845,7 +939,8 @@ function paintPrompt(
           : width >= 52
             ? " enter · ctrl-q now/next · ctrl-z undo · ctrl-o log "
             : "";
-    const spend = view.spend ? ` ${view.spend} ` : "";
+    const right = footerStatus(view, view.score.sessionId);
+    const spend = right ? ` ${right} ` : "";
     const spendWidth = displayWidth(spend);
     // Spend wins over hints when both do not fit.
     const shown =
@@ -896,8 +991,7 @@ function paintOverlay(
   const box = capabilities.unicode ? UNICODE_BOX : ASCII_BOX;
   const panel = roles.panel;
   const border = onBackground(roles.border, panel);
-  const left = width >= 60 ? 2 : 0;
-  const boxWidth = width - left * 2;
+  const { left, boxWidth } = panelRect(width);
   const top = region.y;
   const height = region.height;
   if (height < 3 || boxWidth < 10) return;
@@ -981,8 +1075,7 @@ function paintText(
   const text = options.text ?? ui.text;
   if (!text) return;
   const roles = ui.theme.roles;
-  const left = width >= 60 ? 2 : 0;
-  const boxWidth = width - left * 2;
+  const { left, boxWidth } = panelRect(width);
   const height = region.height;
   if (height < 3 || boxWidth < 10) return;
   const panel = paintBox(buffer, ui, {
@@ -1044,8 +1137,7 @@ function paintGuide(
   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 { left, boxWidth } = panelRect(width);
   const height = region.height;
   if (height < 3 || boxWidth < 10) return;
   const panel = paintBox(buffer, ui, {
@@ -1125,8 +1217,7 @@ function paintPicker(
   const picker = ui.picker;
   if (!picker) return;
   const roles = ui.theme.roles;
-  const left = width >= 60 ? 2 : 0;
-  const boxWidth = width - left * 2;
+  const { left, boxWidth } = panelRect(width);
   const noteRows = picker.note && region.height >= 6 ? 1 : 0;
   const height = Math.min(
     region.height,
@@ -1241,12 +1332,56 @@ export function footerHint(
 
 // ---------------------------------------------------------------------------
 
-function paintTooSmall(buffer: CellBuffer, ui: UiState, size: FrameSize): void {
-  const roles = ui.theme.roles;
-  const lines = [
-    "resize terminal",
-    `${size.width}x${size.height} · need ${MIN_WIDTH}x${MIN_HEIGHT}`,
+/**
+ * The too-small screen's lines, widest layout that fits first: one line
+ * (`terminal too small · 58×14 · need ≥ 60×16`), then stacked, then bare
+ * numbers. The last line is the keys that still work.
+ */
+export function tooSmallLines(
+  size: FrameSize,
+  unicode: boolean,
+  playing: boolean,
+): string[] {
+  const x = unicode ? "×" : "x";
+  const dot = unicode ? " · " : " - ";
+  const now = `${size.width}${x}${size.height}`;
+  const need = `need ${unicode ? "≥" : ">="} ${MIN_WIDTH}${x}${MIN_HEIGHT}`;
+  const keys = `space ${playing ? "stop" : "play"}${dot}q quit`;
+  const fits = (lines: string[]) =>
+    lines.length <= size.height &&
+    lines.every((line) => displayWidth(line) <= size.width);
+  const layouts = [
+    [`terminal too small${dot}${now}${dot}${need}`, "", keys],
+    ["terminal too small", `${now}${dot}${need}`, "", keys],
+    ["terminal too small", now, need, "", keys],
+    ["terminal too small", now, need],
+    ["too small", now, need],
+    [now, need],
+    [`${now} ${unicode ? "≥" : ">="}${MIN_WIDTH}${x}${MIN_HEIGHT}`],
+    [now],
   ];
+  return layouts.find(fits) ?? [now];
+}
+
+/**
+ * What a key does while the too-small screen is up: ctrl-c and q quit,
+ * space starts or stops playback, everything else (typing, mouse, menu
+ * keys) is dropped so the hidden UI's state is untouched.
+ */
+export function tooSmallKey(value: unknown): "quit" | "play" | "ignore" {
+  if (value === "\u0003" || value === "q" || value === "Q") return "quit";
+  if (value === " ") return "play";
+  return "ignore";
+}
+
+function paintTooSmall(
+  buffer: CellBuffer,
+  ui: UiState,
+  size: FrameSize,
+  playing: boolean,
+): void {
+  const roles = ui.theme.roles;
+  const lines = tooSmallLines(size, ui.capabilities.unicode, playing);
   const top = Math.max(0, Math.floor((size.height - lines.length) / 2));
   lines.forEach((line, index) => {
     const text = truncate(line, size.width);
@@ -1255,7 +1390,7 @@ function paintTooSmall(buffer: CellBuffer, ui: UiState, size: FrameSize): void {
       x,
       top + index,
       text,
-      index === 0 ? roles.warning : roles.muted,
+      index === 0 ? { ...roles.warning, bold: true } : roles.muted,
     );
   });
 }
@@ -1273,7 +1408,7 @@ export function composeFrame(
   const layout = computeLayout({ width, height }, ui.prompt.wrappedRows);
   const hits = new HitMap();
   if (layout.tooSmall) {
-    paintTooSmall(buffer, ui, { width, height });
+    paintTooSmall(buffer, ui, { width, height }, view.score.playing === true);
     return {
       buffer,
       cursor: undefined,
@@ -1323,7 +1458,7 @@ export function composeFrame(
       hits,
       view.beat ?? resolveBeat(view.score, nowMs),
     );
-  if (view.arrange && layout.highway.height > 4) {
+  if (view.arrange && !view.tape && layout.highway.height > 4) {
     paintArrangeStrip(
       buffer,
       layout.highway.y,
@@ -1344,6 +1479,7 @@ export function composeFrame(
       kind: ui.overlay && !ui.drawer ? "text" : "highway",
     });
     // The drawer replaces the menu's list: the piano roll shows above it.
+    let panel: number | undefined = TEXT_MEASURE;
     if (ui.overlay === "log" && !ui.drawer)
       paintOverlay(buffer, ui, layout.highway, width);
     else if (ui.overlay === "picker" && ui.picker && !ui.drawer)
@@ -1352,10 +1488,32 @@ export function composeFrame(
       paintText(buffer, ui, layout.highway, width);
     else if (ui.overlay === "guide" && ui.guide)
       paintGuide(buffer, ui, layout.highway, width);
-    else
+    else panel = undefined;
+    // A text panel holds its measure; on a wide terminal the song keeps
+    // drawing beside it instead of an empty margin.
+    const { left: panelLeft, boxWidth } = panelRect(width, panel);
+    const sideX = panelLeft + boxWidth + 1;
+    const side =
+      panel !== undefined
+        ? width - sideX >= SIDE_MIN_WIDTH
+          ? { x: sideX, width: width - sideX }
+          : undefined
+        : { x: 0, width };
+    if (side && view.tape)
+      paintTape(
+        buffer,
+        { ...side, y: layout.highway.y, height: layout.highway.height },
+        view.tape,
+        {
+          theme: ui.theme,
+          unicode: ui.capabilities.unicode,
+          ...(panel !== undefined ? {} : { hits }),
+        },
+      );
+    else if (side)
       paintHighway(
         buffer,
-        { x: 0, y: layout.highway.y, width, height: layout.highway.height },
+        { ...side, y: layout.highway.y, height: layout.highway.height },
         view.score,
         beat,
         {
@@ -1476,6 +1634,8 @@ export class TuiApp {
   private writer: ScreenWriter;
   private lastFrame: Frame | undefined;
   private lastFrameAt = Number.NEGATIVE_INFINITY;
+  /** Compose plus encode time of the last rendered frame, in ms. */
+  lastRenderMs = 0;
   /** Minimum interval between frames (~30 fps). */
   frameIntervalMs = 33;
   /**
@@ -1544,16 +1704,26 @@ export class TuiApp {
       now - this.lastFrameAt < this.frameIntervalMs + this.backoffMs
     )
       return "";
+    // A zero-size (or unknown) terminal has no cell to draw in; any write
+    // would wrap. Draw again in full once it has one.
+    const columns = Math.floor(this.io.columns() || 0);
+    const rows = Math.floor(this.io.rows() || 0);
+    if (columns < 1 || rows < 1) {
+      this.writer.invalidate();
+      return "";
+    }
     this.lastFrameAt = now;
     this.watchFirstLoop(view, now);
+    const started = performance.now();
     const frame = composeFrame(
       view,
       this.ui,
-      { width: this.io.columns(), height: this.io.rows() },
+      { width: columns, height: rows },
       now,
     );
     this.lastFrame = frame;
     const out = this.writer.frame(frame.buffer, frame.cursor);
+    this.lastRenderMs = performance.now() - started;
     if (out) {
       const accepted = this.io.write(out);
       this.backoffMs =
@@ -1710,12 +1880,15 @@ export class TuiApp {
         // End then ↑ moves the view on the first press.
         const max = Math.max(0, this.text.lines.length - page);
         const from = Math.min(max, this.text.scroll);
-        this.text.scroll =
+        const next =
           nav === "home"
             ? 0
             : nav === "end"
               ? max
               : Math.max(0, Math.min(max, from + step));
+        // At the last page the panel pins to the end: a resize keeps the
+        // last line in view (paintText clamps Infinity to the new bound).
+        this.text.scroll = max > 0 && next === max ? Infinity : next;
         return { type: "overlay" };
       }
     }

package/tui/delight.ts

@@ -62,6 +62,55 @@ export function sweepProgress(
   return age / SWEEP_MS;
 }
 
+/** The TAPE reels, one step per beat (op1-ux §9.1). */
+export const REELS = "◐◓◑◒";
+/** ASCII reels for terminals without unicode. */
+export const ASCII_REELS = "|/-\\";
+/** How long the loop brackets stay bright after each wrap (§9.3). */
+export const LOOP_FLASH_MS = 150;
+
+/**
+ * The TAPE reel glyph: turns one step per transport beat while playing,
+ * stands still when stopped or with `/motion off`. A pure function of the
+ * beat, so two panes on one transport turn together.
+ */
+export function reelGlyph(
+  input: Readonly<{
+    playing: boolean;
+    beat: number;
+    reducedMotion: boolean;
+    unicode: boolean;
+  }>,
+): string {
+  const reels = input.unicode ? REELS : ASCII_REELS;
+  if (!input.playing || input.reducedMotion || !Number.isFinite(input.beat))
+    return reels[0]!;
+  const step = Math.floor(Math.max(0, input.beat));
+  return reels[step % reels.length]!;
+}
+
+/**
+ * Whether the loop brackets flash now: within `LOOP_FLASH_MS` after the
+ * transport wraps the loop (each recording pass closes there). Never on
+ * the very first pass, never stopped, never with `/motion off`.
+ */
+export function loopFlash(
+  input: Readonly<{
+    playing: boolean;
+    /** Transport beat, unwrapped. */
+    beat: number;
+    loopBeats?: number | undefined;
+    bpm: number;
+    reducedMotion: boolean;
+  }>,
+): boolean {
+  const loop = input.loopBeats;
+  if (!input.playing || input.reducedMotion || !loop || loop <= 0) return false;
+  if (!Number.isFinite(input.beat) || input.beat < loop) return false;
+  const since = input.beat % loop;
+  return (since * 60_000) / Math.max(1, input.bpm) < LOOP_FLASH_MS;
+}
+
 /** A glowing lane: its pitch and strength (1 at the press, fading to 0). */
 export type LaneGlow = Readonly<{ pitch: number; strength: number }>;