@hraness/dawg 0.6.1 → 0.8.0

package/tui/app.ts

@@ -12,21 +12,34 @@
  * injectable `TerminalIO`.
  */
 
+import { paintTape, type TapeView } from "./tape.ts";
 import {
   ActivityFeed,
+  ERROR_FADE_MS,
+  fail,
   revisionLabel,
   spinnerFrame,
   type ActivityCard,
+  type Receipt,
   type TranscriptEntry,
 } from "./activity.ts";
 import {
   paintHighway,
+  projectionFor,
   resolveBeat,
   type TrackScoreSnapshot,
 } from "./highway.ts";
+import { placeholderHint } from "./hints.ts";
+import {
+  Delight,
+  downbeatGlint,
+  FIRST_LOOP_CARD,
+  sweepProgress,
+} from "./delight.ts";
 import { asciiHint, fitHint, HINTS } from "./grammar.ts";
 import { GuideBrowser } from "./guide.ts";
 import { listGuides } from "../guides/index.ts";
+import { topicMiss } from "../src/lang/glossary.ts";
 import { classifyKey, overlayKey, type UiCommand } from "./keys.ts";
 import { PromptModel, type PromptAction, type PromptMode } from "./prompt.ts";
 import {
@@ -64,19 +77,29 @@ 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;
   /**
    * The line under the prompt: `$0.12 session · $0.48 today · opus-5.5 ·
-   * gateway`, or `no model · dawg login`. The caller sizes it to the width.
+   * gateway`, or `commands only`. The caller sizes it to the width.
    */
   spend?: string | undefined;
-  /** No agent provider: the placeholder teaches commands, no STEER pill. */
+  /** No agent provider: the placeholder teaches commands, no NOW pill. */
   agentOffline?: boolean | undefined;
+  /**
+   * Show-me: the command the agent is writing, as it streams (ghost text in
+   * an empty prompt bar), and the caption naming the human gesture.
+   */
+  showMe?:
+    { 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. */
@@ -136,6 +159,8 @@ export interface UiState {
   guide?: GuideBrowser | undefined;
   /** The fader drawer, docked over the bottom of the piano roll. */
   drawer?: DrawerView | undefined;
+  /** Downbeat glint, first-loop sweep and ghost-note lanes (delight.ts). */
+  delight?: Delight | undefined;
 }
 
 /**
@@ -247,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;
@@ -286,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)),
@@ -412,52 +469,135 @@ function syncSegment(
   return { text: `${glyph[sync]} ${sync}`, style: style[sync], priority: 4 };
 }
 
+/**
+ * The song header compressed for play mode's row: transport, tempo, the
+ * track and the revision (`▶ 120 BPM · drums · rev 1`).
+ */
+export function playContext(
+  score: TrackScoreSnapshot,
+  unicode: boolean,
+): string {
+  const playing = score.playing === true;
+  const glyph = playing ? (unicode ? "▶" : ">") : unicode ? "⏸" : "||";
+  const name = score.trackName ?? score.trackId ?? "track";
+  return [
+    `${glyph} ${score.bpm ?? 120} BPM`,
+    name,
+    ...(score.revision !== undefined ? [`rev ${score.revision}`] : []),
+  ].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,
   ui: UiState,
   width: number,
   hits?: HitMap,
+  beat = 0,
 ): void {
   const { theme, capabilities } = ui;
   const roles = theme.roles;
   const score = view.score;
   const unicode = capabilities.unicode;
   const playing = score.playing === true;
+  // The ▶ brightens for a moment on each bar's downbeat.
+  const glint = downbeatGlint({
+    playing,
+    beat,
+    bpm: score.bpm ?? 120,
+    beatsPerBar: score.beatsPerBar ?? 4,
+    barBeats: score.barBeats,
+    loopBeats: score.loopBeats,
+    reducedMotion: ui.reducedMotion,
+  });
   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 ? roles.transport : roles.paused,
+      style: playing
+        ? glint
+          ? { ...shade(roles.transport, 0.55), bold: true }
+          : roles.transport
+        : roles.paused,
       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,
@@ -471,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
@@ -527,7 +673,9 @@ function cardMarker(card: ActivityCard, unicode: boolean): string {
 }
 
 export function cardText(card: ActivityCard, unicode: boolean): string {
-  const parts = [`${cardMarker(card, unicode)} ${card.text}`];
+  const count =
+    card.count && card.count > 1 ? ` ${unicode ? "×" : "x"}${card.count}` : "";
+  const parts = [`${cardMarker(card, unicode)} ${card.text}${count}`];
   const revision = revisionLabel(
     card.baseRevision,
     card.resultRevision,
@@ -535,15 +683,46 @@ export function cardText(card: ActivityCard, unicode: boolean): string {
   );
   if (revision) parts.push(revision);
   if (card.hint) parts.push(card.hint);
+  if (card.suffix) parts.push(card.suffix);
   return parts.join(" · ");
 }
 
+/** How long each one-time note leads when they cannot all fit at once. */
+export const ONCE_ROTATE_MS = 3_000;
+
+/**
+ * The cards for the strip's width: when the one-time notes cannot all show
+ * whole beside the receipts, they take turns (one every `ONCE_ROTATE_MS`,
+ * on the frame clock), so each is read in full at least once.
+ */
+export function stripCards(
+  cards: readonly ActivityCard[],
+  room: number,
+  nowMs: number,
+  unicode: boolean,
+): ActivityCard[] {
+  const width = (list: readonly ActivityCard[]) =>
+    list.reduce(
+      (sum, card, index) =>
+        sum + (index > 0 ? 3 : 0) + displayWidth(cardText(card, unicode)),
+      0,
+    );
+  if (width(cards) <= room) return [...cards];
+  const steady = cards.filter((card) => !card.once);
+  const once = cards.filter((card) => card.once);
+  if (once.length < 2) return [...cards];
+  const turn =
+    once[Math.floor(Math.max(0, nowMs) / ONCE_ROTATE_MS) % once.length]!;
+  return [...steady, turn];
+}
+
 function paintActivity(
   buffer: CellBuffer,
   y: number,
   ui: UiState,
   width: number,
   nowMs: number,
+  agentOffline = false,
 ): void {
   const { theme, capabilities, activity } = ui;
   const roles = theme.roles;
@@ -567,9 +746,10 @@ function paintActivity(
       ...roles.agent,
       bold: true,
     });
-    if (activity.streaming && x < limit - 4) {
+    // The agent's latest sentence, faint: what it is doing, in its words.
+    if (activity.streamSentence && x < limit - 4) {
       x += buffer.text(x, y, " · ", roles.faint);
-      const tail = activity.streaming;
+      const tail = activity.streamSentence;
       const room = Math.max(0, limit - x);
       const shown =
         displayWidth(tail) > room
@@ -577,13 +757,24 @@ function paintActivity(
               .slice(-(room - 1))
               .join("")}`
           : tail;
-      x += buffer.text(x, y, truncate(shown, room), roles.muted);
+      x += buffer.text(x, y, truncate(shown, room), roles.faint);
     }
   } else {
-    const cards = [...activity.cards].reverse();
+    const cards = stripCards(
+      activity.visible(nowMs),
+      Math.max(0, limit - x),
+      nowMs,
+      capabilities.unicode,
+    );
     cards.forEach((card, index) => {
       if (x >= limit) return;
       const text = cardText(card, capabilities.unicode);
+      // A one-time note behind the first slot shows whole or not at all
+      // (it stays in ctrl-o); a cut note loses its key word.
+      if (index > 0 && card.once && x + 3 + displayWidth(text) > limit) {
+        x = limit;
+        return;
+      }
       if (index > 0) {
         if (x + 3 + Math.min(12, displayWidth(text)) > limit) {
           x = limit;
@@ -602,7 +793,14 @@ function paintActivity(
               : card.tone === "success"
                 ? roles.success
                 : roles.text;
-      if (index > 0) style = card.tone === "error" ? roles.error : roles.faint;
+      // Behind the first slot everything is faint; an error keeps its
+      // colour until it is old, then fades with the rest.
+      if (index > 0)
+        style =
+          card.tone === "error" && age < ERROR_FADE_MS
+            ? roles.error
+            : roles.faint;
+      else if (card.once) style = roles.faint;
       else if (!ui.reducedMotion && age >= 0 && age < CARD_GLOW_MS)
         style = { ...shade(style, 0.4 * (1 - age / CARD_GLOW_MS)), bold: true };
       x += buffer.text(x, y, truncate(text, Math.max(0, limit - x)), style);
@@ -612,7 +810,9 @@ function paintActivity(
         x,
         y,
         truncate(
-          "type a request · space plays on an empty prompt · /help",
+          agentOffline
+            ? "type a command · space plays on an empty prompt · /help"
+            : "type a request · space plays on an empty prompt · /help",
           limit - x,
         ),
         roles.faint,
@@ -626,7 +826,7 @@ function paintActivity(
 // Prompt panel
 
 function pill(mode: PromptMode): string {
-  return mode === "queue" ? " QUEUE " : " STEER ";
+  return mode === "queue" ? " NEXT " : " NOW ";
 }
 
 function paintPrompt(
@@ -661,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)
@@ -698,12 +899,27 @@ function paintPrompt(
     if (index === rows - 1 && layoutInfo.first + rows < layoutInfo.total)
       buffer.text(width - 3, y, capabilities.unicode ? "↓" : "v", faint);
   }
-  if (prompt.value.length === 0) {
-    const placeholder = view.agentOffline
-      ? "try: tempo 96 · add C4 at 0 · /help  (dawg login enables the agent)"
-      : mode === "queue"
-        ? "queue a request for after the current one…"
-        : "describe a change — “add a walking bass in A minor”";
+  const ghost = view.showMe?.ghost;
+  const caption = view.showMe?.caption;
+  if (prompt.value.length === 0 && (ghost || caption)) {
+    // The agent's command as it streams, then the gesture it stands for.
+    const typed = ghost ? `${ghost}${capabilities.unicode ? "▏" : "_"}` : "";
+    const line = typed && caption ? `${typed}  ${caption}` : typed || caption!;
+    buffer.text(5, top + 1, truncate(line, editorWidth - 1), faint);
+  } else if (prompt.value.length === 0) {
+    // Seeded per session (tui/hints.ts): the words stay put while you
+    // work and change between sessions, chosen by agent and song state.
+    const score = view.score;
+    const placeholder = placeholderHint({
+      seed: score.sessionId ?? "dawg",
+      agent: !view.agentOffline,
+      filled:
+        score.notes.length > 0 ||
+        (score.clips ?? []).length > 0 ||
+        (score.layers ?? []).some((layer) => layer.notes.length > 0),
+      drums: projectionFor(score).kind !== "pitch",
+      queue: mode === "queue",
+    });
     buffer.text(5, top + 1, truncate(placeholder, editorWidth - 1), faint);
   }
 
@@ -714,15 +930,17 @@ function paintPrompt(
     for (let column = 1; column < width - 1; column += 1)
       buffer.set(column, y, box.h, border);
     buffer.set(width - 1, y, box.br, border);
+    // One notation everywhere: ctrl-<key>, as /help and the menu spell it.
     const hints =
-      width >= 100
-        ? " enter send · shift+enter newline · ^q queue · ^z undo · ^o log · ^c quit "
-        : width >= 72
-          ? " enter send · ^j newline · ^q queue · ^z undo · ^o log "
-          : width >= 44
-            ? " enter · ^q queue · ^z undo · ^o log "
+      width >= 112
+        ? " enter send · shift-enter newline · ctrl-q now/next · ctrl-z undo · ctrl-o log · ctrl-c quit "
+        : width >= 80
+          ? " enter send · ctrl-j newline · ctrl-q now/next · ctrl-z undo · ctrl-o log "
+          : 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 =
@@ -773,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;
@@ -858,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, {
@@ -921,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, {
@@ -1002,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,
@@ -1118,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);
@@ -1132,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,
     );
   });
 }
@@ -1150,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,
@@ -1164,7 +1422,10 @@ export function composeFrame(
       buffer,
       layout.header,
       width,
-      view.play,
+      {
+        ...view.play,
+        context: playContext(view.score, ui.capabilities.unicode),
+      },
       ui.theme,
       ui.capabilities.unicode,
     );
@@ -1188,8 +1449,16 @@ export function composeFrame(
         height: layout.highway.height - 1,
       };
     }
-  } else paintHeader(buffer, view, ui, width, hits);
-  if (view.arrange && layout.highway.height > 4) {
+  } else
+    paintHeader(
+      buffer,
+      view,
+      ui,
+      width,
+      hits,
+      view.beat ?? resolveBeat(view.score, nowMs),
+    );
+  if (view.arrange && !view.tape && layout.highway.height > 4) {
     paintArrangeStrip(
       buffer,
       layout.highway.y,
@@ -1210,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)
@@ -1218,16 +1488,48 @@ 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,
         {
           theme: ui.theme,
           capabilities: ui.capabilities,
           reducedMotion: ui.reducedMotion,
+          hint: {
+            seed: view.score.sessionId ?? "dawg",
+            agent: !view.agentOffline,
+          },
+          sweep: sweepProgress(
+            ui.delight?.sweepStartedAtMs,
+            nowMs,
+            ui.reducedMotion,
+          ),
+          glows: ui.delight?.glows(nowMs, ui.reducedMotion),
         },
       );
     if (ui.drawer)
@@ -1236,7 +1538,11 @@ export function composeFrame(
         layout.highway,
         width,
         ui.drawer,
-        { theme: ui.theme, unicode: ui.capabilities.unicode },
+        {
+          theme: ui.theme,
+          unicode: ui.capabilities.unicode,
+          reducedMotion: ui.reducedMotion,
+        },
         hits,
       );
   }
@@ -1245,7 +1551,14 @@ export function composeFrame(
       text: ui.keys,
       hint: HINTS.keys,
     });
-  paintActivity(buffer, layout.activity, ui, width, nowMs);
+  paintActivity(
+    buffer,
+    layout.activity,
+    ui,
+    width,
+    nowMs,
+    view.agentOffline ?? false,
+  );
   const prompt = paintPrompt(buffer, view, ui, layout, width);
   return {
     buffer,
@@ -1260,8 +1573,15 @@ export function composeFrame(
 // ---------------------------------------------------------------------------
 // Mutable app
 
+/** The longest a lagging terminal waits between frames. */
+export const MAX_BACKOFF_MS = 250;
+
 export interface TerminalIO {
-  write(data: string): void;
+  /**
+   * Writes a frame. `false` means the terminal is not keeping up (the
+   * stream's buffer is full): frames back off until a write is accepted.
+   */
+  write(data: string): void | boolean;
   columns(): number;
   rows(): number;
 }
@@ -1314,8 +1634,19 @@ 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;
+  /**
+   * Extra spacing while the terminal lags: doubles on each refused write up
+   * to `MAX_BACKOFF_MS`, resets on the first accepted one.
+   */
+  backoffMs = 0;
+  /** Session-only delight; `heardLoop` comes from the session's metadata. */
+  readonly delight = new Delight();
+  /** The song wrapped for the first time: the host records it in meta. */
+  onFirstLoop: (() => void) | undefined;
 
   constructor(options: TuiAppOptions) {
     this.io = options.io;
@@ -1348,6 +1679,7 @@ export class TuiApp {
       keys: this.keys,
       guide: this.guide,
       drawer: this.drawer,
+      delight: this.delight,
     };
   }
 
@@ -1367,21 +1699,68 @@ export class TuiApp {
    */
   render(view: AppView, options: { force?: boolean } = {}): string {
     const now = this.clock();
-    if (!options.force && now - this.lastFrameAt < this.frameIntervalMs)
+    if (
+      !options.force &&
+      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);
-    if (out) this.io.write(out);
+    this.lastRenderMs = performance.now() - started;
+    if (out) {
+      const accepted = this.io.write(out);
+      this.backoffMs =
+        accepted === false
+          ? Math.min(
+              MAX_BACKOFF_MS,
+              Math.max(this.frameIntervalMs, this.backoffMs * 2),
+            )
+          : 0;
+    }
     return out;
   }
 
+  /**
+   * The first wrap of a song that never wrapped before: a one-shot sweep
+   * and the card `↻ first loop`. The card shows with motion off too (it is
+   * information); the sweep does not.
+   */
+  private watchFirstLoop(view: AppView, now: number): void {
+    const score = view.score;
+    const wrapped = this.delight.observe(
+      {
+        playing: score.playing === true,
+        beat: view.beat ?? resolveBeat(score, now),
+        loopBeats: score.loopBeats,
+        empty:
+          score.notes.length === 0 &&
+          (score.clips ?? []).length === 0 &&
+          !(score.layers ?? []).some((layer) => layer.notes.length > 0),
+      },
+      now,
+    );
+    if (!wrapped) return;
+    this.activity.pushCard(FIRST_LOOP_CARD, { tone: "info", once: true });
+    this.onFirstLoop?.();
+  }
+
   /** Decode one key sequence (from TerminalInputDecoder) into an input. */
   input(value: string | { type: "paste"; text: string }): AppInput {
     if (typeof value !== "string")
@@ -1485,7 +1864,7 @@ export class TuiApp {
     }
     if (this.overlay === "text" && this.text) {
       const nav = overlayKey(value);
-      const page = Math.max(1, this.io.rows() - 10);
+      const page = this.overlayRows();
       if (nav && nav !== "enter") {
         const step =
           nav === "down"
@@ -1497,19 +1876,25 @@ export class TuiApp {
                 : nav === "pgup"
                   ? -page
                   : 0;
-        const total = this.text.lines.length;
-        this.text.scroll =
+        // Clamp to the last full page, the same bound paintText uses, so
+        // 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);
+        const next =
           nav === "home"
             ? 0
             : nav === "end"
-              ? total
-              : Math.max(0, Math.min(total, this.text.scroll + step));
+              ? 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" };
       }
     }
     if (this.overlay === "log") {
       const nav = overlayKey(value);
-      const page = Math.max(1, this.io.rows() - 10);
+      const page = this.overlayRows();
       if (nav && nav !== "enter") {
         const step =
           nav === "up"
@@ -1525,12 +1910,15 @@ export class TuiApp {
           this.activity.transcript,
           this.log.filter,
         ).length;
+        // Scroll counts rows up from the newest; paintOverlay's bound.
+        const max = Math.max(0, total - page);
+        const from = Math.min(max, this.log.scroll);
         this.log.scroll =
           nav === "home"
-            ? total
+            ? max
             : nav === "end"
               ? 0
-              : Math.max(0, Math.min(total, this.log.scroll + step));
+              : Math.max(0, Math.min(max, from + step));
         return { type: "overlay" };
       }
       if (key.type === "text" && key.text === "/") {
@@ -1624,6 +2012,19 @@ export class TuiApp {
     if (this.overlay === "picker") this.overlay = undefined;
   }
 
+  /**
+   * Rows of text a panel over the highway shows (its height less the two
+   * borders), as last rendered; a guess from the terminal height before the
+   * first frame.
+   */
+  private overlayRows(): number {
+    const highway = this.lastFrame?.layout.highway.height;
+    return Math.max(
+      1,
+      highway !== undefined && highway > 2 ? highway - 2 : this.io.rows() - 10,
+    );
+  }
+
   /** Show static lines over the highway (`/help`, lists); replaces any overlay. */
   openText(title: string, lines: readonly string[]): void {
     this.text = { title, lines: lines.slice(0, 512), scroll: 0 };
@@ -1681,9 +2082,10 @@ export class TuiApp {
 
   /**
    * Handle TUI-local slash commands (`/log`, `/theme`, `/motion`, `/guide`).
-   * Returns a receipt, or undefined when the command is not a UI command.
+   * Returns a receipt (a structured one for a refusal), or undefined when
+   * the command is not a UI command.
    */
-  command(text: string): string | undefined {
+  command(text: string): string | Receipt | undefined {
     const command = text.trim();
     if (/^\/(log|transcript)$/i.test(command)) {
       this.overlay = this.overlay === "log" ? undefined : "log";
@@ -1708,7 +2110,12 @@ export class TuiApp {
     if (guide) {
       const topic = guide[1]?.trim();
       if (!this.openGuide(topic))
-        return `no guide named ${topic} · /guide lists them all`;
+        return fail(
+          topicMiss(
+            topic!,
+            (this.guide?.guides ?? listGuides()).map((g) => g.id),
+          ),
+        );
       return topic
         ? `guide · ${this.guide?.guides.find((g) => g.id === this.guide?.page)?.title ?? topic} · esc back`
         : "guides · → open · esc closes";