@audiofool/moondog 0.1.0 → 0.2.0-beta.3

package/src/surfaces/cli/brand-components.mjs

@@ -1,9 +1,14 @@
-import { CURSOR_MARKER, Editor, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, Editor, Text, getCellDimensions, getKeybindings, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { stripVTControlCharacters } from "node:util";
 import { sanitizeTerminalText } from "./format-output.mjs";
-import { LOGO_MOTION_FRAMES, renderLunarRecord, renderMoondogWordmark } from "./terminal-art.mjs";
+import { LOGO_MOTION_FRAMES, renderLunarRecordLayers, renderMoondogWordmark } from "./terminal-art.mjs";
+import { N_, screenTranslator } from "../../i18n/index.mjs";
 export { ListeningMenu } from "./listening-menu.mjs";
 
+// The TUI sets its live translator once; components read it while rendering.
+let tr = screenTranslator("en");
+export function setBrandText(translator) { tr = translator; }
+
 export function paintBrandLine(line, width, theme) {
   const clipped = truncateToWidth(line, Math.max(1, width), "");
   const padding = " ".repeat(Math.max(0, width - visibleWidth(clipped)));
@@ -25,7 +30,7 @@ export class BrandSurface {
   }
   handleInput(data) { this.component.handleInput?.(data); }
   invalidate() {
-    this.paintCache = undefined;
+    this.paintCache?.clear();
     this.component.invalidate?.();
   }
   render(width) {
@@ -58,22 +63,28 @@ export class ListeningHeader {
   invalidate() {}
   render(width) {
     const theme = this.getTheme();
-    const { profileReady, modelReady, spotifyReady, provider, model } = this.getStatus();
-    const title = theme.bold("MOONDOG") + (width >= 46 ? theme.muted("  /  your listening room") : "");
+    const { profileReady, modelReady, spotifyReady, provider, model, effort, place } = this.getStatus();
     const compact = width < 60;
     const clean = (value) => sanitizeTerminalText(stripVTControlCharacters(String(value ?? "")))
       .replace(/\s+/gu, " ").trim();
-    const modelName = clean(model);
+    const modelName = [clean(model), clean(effort)].filter(Boolean).join(" · ");
     const providerName = clean(provider);
+    const placeName = clean(place);
+    const lead = "  /  ";
+    const placeRoom = width - (1 + visibleWidth("MOONDOG") + visibleWidth(lead));
+    const suffix = placeName && placeRoom >= 12
+      ? theme.muted(lead + truncateToWidth(placeName, placeRoom, "…"))
+      : !placeName && width >= 46 ? theme.muted(`${lead}${tr("your listening room")}`) : "";
+    const title = theme.bold("MOONDOG") + suffix;
     const profileLabel = profileReady
-      ? compact ? "profile ready" : "local profile"
-      : compact ? "no history" : "bring your history";
-    const modelLabel = modelReady ? modelName || (compact ? "model ready" : "conversation ready") : "model offline";
+      ? compact ? tr("profile ready") : tr("local profile")
+      : compact ? tr("no history") : tr("bring your history");
+    const modelLabel = modelReady ? modelName || (compact ? tr("model ready") : tr("conversation ready")) : tr("model offline");
     const identity = modelReady && providerName ? `${providerName} / ${modelLabel}` : modelLabel;
     const available = Math.max(1, width - 1);
     // Keep the active model readable before spending space on optional status.
     const candidates = [
-      [profileLabel, identity, ...(spotifyReady && !compact ? ["Spotify connected"] : [])],
+      [profileLabel, identity, ...(spotifyReady && !compact ? [tr("Spotify connected")] : [])],
       [profileLabel, identity],
       [profileLabel, modelLabel],
       [identity],
@@ -88,14 +99,118 @@ export class ListeningHeader {
   }
 }
 
+/**
+ * Steps taken while answering. They stay on screen for this visit and are not saved.
+ */
+export class AgentWork {
+  constructor(getTheme, getPhase = () => 0) {
+    this.getTheme = getTheme;
+    this.getPhase = getPhase;
+    this.calls = [];
+    this.live = true;
+    this.settled = false;
+    this.elapsed = "";
+  }
+  invalidate() {}
+  note(key, label, state) {
+    const text = sanitizeTerminalText(label).replace(/\s+/gu, " ").trim() || tr("Music tool");
+    const existing = this.calls.find((call) => call.key === key);
+    if (existing) {
+      existing.label = text;
+      existing.state = state;
+    } else {
+      this.calls.push({ key, label: text, state });
+    }
+  }
+  quiet() {
+    this.live = false;
+  }
+  settle(elapsed) {
+    this.live = false;
+    this.settled = true;
+    this.elapsed = elapsed;
+  }
+  summary() {
+    const count = (state) => this.calls.filter((call) => call.state === state).length;
+    const parts = [];
+    const done = count("completed");
+    const failed = count("failed");
+    const open = count("running");
+    if (done) parts.push(tr("{count} done", { count: done }));
+    if (failed) parts.push(tr("{count} didn't work", { count: failed }));
+    if (open) parts.push(tr("{count} not confirmed", { count: open }));
+    return [parts.join(", "), this.elapsed].filter(Boolean).join(" · ");
+  }
+  render(width) {
+    const theme = this.getTheme();
+    const line = (text, ink) => new Text(ink(text), 3, 0).render(width);
+    if (!this.calls.length) return this.live ? line("…", theme.faint) : [];
+    const phase = this.getPhase() % 4;
+    const liveMarks = ["·", "•", "·", "∙"];
+    const shown = this.calls.slice(-8);
+    const earlier = this.calls.length - shown.length;
+    const lines = earlier ? line(`· ${tr("{count} earlier", { count: earlier })}`, theme.faint) : [];
+    lines.push(...shown.flatMap((call) => {
+      const settledOpen = this.settled && call.state === "running";
+      const mark = call.state === "failed" ? "×"
+        : call.state === "completed" ? "✓"
+        : settledOpen ? "·"
+        : liveMarks[phase];
+      const ink = call.state === "failed" ? theme.error : call.state === "completed" ? theme.muted : theme.faint;
+      return line(`${mark} ${call.label}`, ink);
+    }));
+    if (this.settled) lines.push(...line(this.summary(), theme.faint));
+    return lines;
+  }
+}
+
+/** Pi's editor, except Enter and Tab never apply suggestions made for older text. */
+export class FreshCompletionEditor extends Editor {
+  // Pi refreshes suggestions asynchronously. A key in the same input chunk as the
+  // last typed character still sees the list for the earlier text, and applying
+  // it with that shorter prefix garbles the line ("/theme pape" + "r" + Enter).
+  applyAutocompleteSuggestions(suggestions, state) {
+    super.applyAutocompleteSuggestions(suggestions, state);
+    this.suggestedFor = this.completionInput();
+  }
+  completionInput() {
+    return `${this.state.cursorLine}:${this.state.cursorCol}:${this.getText()}`;
+  }
+  handleInput(data) {
+    const keys = getKeybindings();
+    if (this.autocompleteState && this.suggestedFor !== this.completionInput()
+      && (keys.matches(data, "tui.select.confirm") || keys.matches(data, "tui.input.tab"))) {
+      // Enter then submits exactly what was typed; Tab asks for fresh suggestions.
+      this.cancelAutocomplete();
+    }
+    super.handleInput(data);
+  }
+}
+
 /** Keep Pi's editing, paste, IME, history, and autocomplete intact. */
-export class ListeningEditor extends Editor {
+export class ListeningEditor extends FreshCompletionEditor {
   constructor(tui, theme, getTheme, getState) {
     super(tui, theme, { paddingX: 1, autocompleteMaxVisible: 5 });
     this.getTheme = getTheme;
     this.getState = getState;
     this.rowCount = 3;
   }
+  recallEntries() {
+    return this.history.slice(0, 100);
+  }
+  replaceRecall(entries) {
+    const next = [];
+    for (const entry of entries ?? []) {
+      if (typeof entry !== "string") continue;
+      const text = entry.trim();
+      if (!text || next.at(-1) === text) continue;
+      next.push(text);
+      if (next.length === 100) break;
+    }
+    this.history = next;
+    this.exitHistoryBrowsing();
+    return next.slice();
+  }
   // The sleeve measures this during the same frame. The signature is taken again
   // after painting because the editor can adjust its own scroll while rendering.
   renderSignature() {
@@ -126,13 +241,13 @@ export class ListeningEditor extends Editor {
     const lines = super.render(width).map((line) => this.focused ? line : line.replace(/\x1b\[7m([\s\S]*?)\x1b\[0m/g, "$1"));
     const { busy, homeVisible, homeFocused } = this.getState();
     if (!/[↑↓]/u.test(lines[0])) {
-      const label = busy ? " DRAFT " : homeFocused ? " TAB TO TYPE " : " YOU ";
+      const label = ` ${busy ? tr("NEXT") : homeFocused ? tr("TAB TO TYPE") : tr("YOU")} `;
       lines[0] = width >= label.length + 4
         ? theme.faint("─ ") + theme.muted(label) + theme.faint("─".repeat(width - label.length - 2))
         : theme.faint("─".repeat(width));
     }
     if (!busy && !this.getText() && lines.length === 3 && width >= 28) {
-      const hint = homeFocused ? "Esc returns to your next thought." : homeVisible ? "What have you been listening to?" : "Keep the conversation going...";
+      const hint = homeFocused ? tr("Esc returns to your next thought.") : homeVisible ? tr("What have you been listening to?") : tr("A song, a playlist, or what to play next.");
       const text = truncateToWidth(hint, width - 2, "");
       lines[1] = " " + (this.focused ? CURSOR_MARKER + theme.inverse(text[0]) : theme.faint(text[0])) + theme.faint(text.slice(1));
     }
@@ -142,12 +257,22 @@ export class ListeningEditor extends Editor {
   }
 }
 
-export const homeActions = [
-  { command: "taste", label: "Listening profile", short: "Profile", description: "See what your listening reveals. Tell me what I missed." },
-  { command: "import", label: "Import your music", short: "Import music", description: "Bring songs, playlists or listening history." },
-  { command: "theme", label: "Appearance", short: "Appearance", description: "Paper, charcoal, or your terminal colors." },
-  { command: "help", label: "Help & commands", short: "Help", description: "Commands, connections and keyboard shortcuts." },
+// Text is marked English and translated as the sleeve renders, so /language applies at once.
+const homeActionText = [
+  { command: "taste", label: N_("Listening profile"), short: N_("Profile"), description: N_("See what your listening reveals. Tell me what I missed.") },
+  { command: "import", label: N_("Import your music"), short: N_("Import music"), description: N_("Bring songs, playlists or listening history.") },
+  { command: "theme", label: N_("Appearance"), short: N_("Appearance"), description: N_("Paper, charcoal, or your terminal colors.") },
+  { command: "help", label: N_("Help & commands"), short: N_("Help"), description: N_("Commands, connections and keyboard shortcuts.") },
 ];
+export const homeActions = homeActionText.map(({ command, label, short, description }) => ({
+  command,
+  get label() { return tr.marked(label); },
+  get short() { return tr.marked(short); },
+  get description() { return tr.marked(description); },
+}));
+
+// Rows of air between a stacked record and the title beneath it.
+const STACK_GAP = 2;
 
 const sleeveNotes = [
   // Welcome to the Machine: https://www.pinkfloyd.com/albums/wish-you-were-here/
@@ -195,11 +320,9 @@ export class RecordSleeve {
     this.lyricColumns = 0;
     this.canAnimate = false;
     this.cache = new Map();
-    this.colored = new Map();
   }
   invalidate() {
     this.cache.clear();
-    this.colored.clear();
     this.frame = undefined;
     this.colorTheme = undefined;
   }
@@ -230,8 +353,11 @@ export class RecordSleeve {
       motionEnabled = this.environment.MOONDOG_MOTION !== "off" } = this.getState();
     // Fill the viewport between the header and composer, independently of art size.
     const rows = Math.max(1, this.terminal.rows - 2 - editorRows - (this.terminal.rows >= 20 ? 2 : 1));
+    // Pi learns the real cell size from terminals that answer it; others keep the 1:2 default.
+    const { widthPx, heightPx } = getCellDimensions();
+    const cellAspect = heightPx / widthPx;
     const frameKey = [
-      width, rows, this.phase, this.lyricPosition, this.sleeveNote, focused ? 1 : 0, selected,
+      width, rows, cellAspect, this.phase, this.lyricPosition, this.sleeveNote, focused ? 1 : 0, selected,
       motionEnabled ? 1 : 0, this.artMode, this.environment.TERM ?? "", theme.plain ? 1 : 0,
     ].join("\0");
     if (this.frame?.key === frameKey && this.frame.theme === theme) {
@@ -246,145 +372,197 @@ export class RecordSleeve {
     const paint = (line) => paintBrandLine(line, width, theme);
     this.canAnimate = false;
     this.lyricColumns = 0;
-    const roomy = width >= 76 && rows >= 14;
-    const narrow = width < 54;
-    const available = Math.max(1, width - 4);
-    const artWidth = Math.min(50, Math.floor(available * (narrow ? 0.40 : 0.48)));
-    const rightWidth = Math.max(1, available - artWidth - 3);
-    const actionLines = homeActions.map((action, index) => {
-      const label = narrow ? action.short : action.label;
-      const active = focused && selected === index;
-      const prefix = active ? theme.accent("› ") : theme.faint(`${index + 1} `);
-      return prefix + (active ? theme.inverse(theme.bold(` ${label} `)) : theme.text(` ${label} `));
-    });
-    const pixelTitle = rightWidth >= 41 && rows >= 20 && !["ascii", "text"].includes(this.artMode) && this.environment.TERM !== "dumb";
-    const withNote = (lines, columns) => {
+    const withNote = (lines, columns, budget) => {
       const scrolling = motionEnabled && !theme.plain;
       const text = `"${this.sleeveNote}"`;
-      const noteLines = ["", ...(scrolling ? [scrollingLyric(text, columns, this.lyricPosition)] : wrapTextWithAnsi(text, columns)).map(theme.muted)];
-      if (lines.length + noteLines.length > rows) return lines;
+      const noteLines = ["", ...(scrolling ? [scrollingLyric(text, columns, this.lyricPosition)] : wrapTextWithAnsi(text, columns)).map((line) => hang(theme.muted(line)))];
+      if (lines.length + noteLines.length > budget) return lines;
       this.canAnimate ||= scrolling;
       this.lyricColumns = scrolling ? columns : 0;
       return [...lines, ...noteLines];
     };
-    const copy = withNote([
-      ...(pixelTitle ? renderMoondogWordmark().map(theme.text) : [theme.bold(roomy ? "M O O N D O G" : "MOONDOG")]),
-      ...(rows >= 12 ? [...wrapDescription("Your personal music agent.", rightWidth).map(theme.muted), ""] : [""]),
-      ...actionLines,
-      ...(roomy ? ["", ...wrapDescription(homeActions[selected].description, rightWidth).map(theme.muted)] : []),
-    ], rightWidth);
     if (rows < 7 || width < 34 || this.artMode === "off") {
-      this.canAnimate = false;
-      this.lyricColumns = 0;
-      const compact = withNote([theme.bold("MOONDOG  ◎"),
-        ...(rows >= 9 && width >= 30 ? [theme.muted("Your personal music agent."), ""] : []),
-        ...actionLines,
-      ], Math.max(1, width - 1)).map((line) => ` ${line}`);
+      const compact = withNote([hang(theme.bold("MOONDOG  ◎")),
+        ...(rows >= 9 && width >= 30 ? [hang(theme.muted(tr("Your personal music agent."))), ""] : []),
+        ...tracklist(theme, { focused, selected, columns: width }),
+      ], Math.max(1, width - 2), rows);
       const top = Math.max(0, Math.floor((rows - compact.length) / 2));
       return finish(Array.from({ length: rows }, (_, row) => paint(compact[row - top] ?? "")));
     }
-    const height = Math.min(22, rows - (roomy ? 2 : 0));
     const mode = this.artMode === "ascii" || this.artMode === "text" || this.environment.TERM === "dumb" ? "ascii" : "braille";
+    // Copy sits two columns in, so the tracklist's selection mark hangs in the gutter.
+    const title = (columns, budget, roomy) => columns >= 41 && budget >= 20 && mode === "braille"
+      ? renderMoondogWordmark().map(theme.text) : [theme.bold(roomy ? "M O O N D O G" : "MOONDOG")];
+    const copyBlock = (columns, budget, roomy, note = true, reserve = roomy) => (note ? withNote : (lines) => lines)([
+      ...title(columns, budget, roomy).map(hang),
+      ...(budget >= 12 ? [...wrapDescription(tr("Your personal music agent."), columns).map((line) => hang(theme.muted(line))), ""] : [""]),
+      ...tracklist(theme, { focused, selected, columns: columns + 2 }),
+      ...(reserve ? ["", ...actionNote(focused ? homeActions[selected].description : "", columns).map((line) => hang(theme.muted(line)))] : []),
+    ], columns, budget);
+    // Choose whichever arrangement gives the record the larger radius on this screen.
+    const stretch = cellAspect / 2;
+    const radius = (columns, height) => columns < 20 || height < 9 || mode === "ascii"
+      ? Math.min(columns, height * stretch * 2) / 4
+      : Math.min((columns * 2 - 4) / 2.35, (height * 4 - 4) * stretch / 2.24);
+    const available = Math.max(1, width - 4);
+    const sideArt = Math.min(64, Math.floor(available * (width < 54 ? 0.40 : 0.48)));
+    const sideCopyWidth = Math.max(1, available - sideArt - 3);
+    const sideRoomy = width >= 76 && rows >= 14;
+    // Side by side, the lyric runs beneath the whole group, so leave it a row and a gap.
+    const sideHeight = Math.min(30, rows - 3);
+    const stackCopyWidth = Math.min(41, width - 6);
+    const stackCopy = copyBlock(stackCopyWidth, Math.max(1, rows - 13), rows >= 34);
+    const stackArt = Math.min(64, width - 4);
+    const stackHeight = Math.min(30, rows - stackCopy.length - STACK_GAP);
+    const stacked = stackHeight >= 9 && radius(stackArt, stackHeight) > radius(sideArt, sideHeight);
+    const artWidth = stacked ? stackArt : sideArt;
+    const height = stacked ? stackHeight : sideHeight;
+    const copy = stacked ? stackCopy : copyBlock(sideCopyWidth, rows, sideRoomy, false);
     this.canAnimate ||= !theme.plain && artWidth >= 20 && height >= 9;
     const phase = theme.plain ? 0 : this.phase;
-    const key = `${artWidth}:${height}:${mode}:${phase}`;
+    const key = `${artWidth}:${height}:${mode}:${phase}:${cellAspect}`;
+    if (this.colorTheme !== theme) {
+      this.cache.clear();
+      this.colorTheme = theme;
+    }
     if (!this.cache.has(key)) {
       if (this.cache.size >= LOGO_MOTION_FRAMES * 2) this.cache.clear();
-      this.cache.set(key, renderLunarRecord({ columns: artWidth, rows: height, style: mode, phase }));
+      const layers = renderLunarRecordLayers({ columns: artWidth, rows: height, style: mode, phase, cellAspect });
+      this.cache.set(key, { ...layers, lines: toneRecord(layers, theme) });
     }
     const art = this.cache.get(key);
-    if (this.colorTheme !== theme) {
-      this.colored.clear();
-      this.colorTheme = theme;
+    // Everything aligns on the disc itself; the tonearm reaching up and right is left to hang free.
+    const [discColumn] = art.center;
+    if (stacked) {
+      // The record is width-bound here, so drop the empty rows its box leaves above and below.
+      const inked = art.lines.map((line) => stripVTControlCharacters(line).trim() !== "");
+      const record = art.lines.slice(inked.indexOf(true), inked.lastIndexOf(true) + 1);
+      const axis = width / 2;
+      const artLeft = Math.max(0, Math.min(width - artWidth, Math.round(axis - discColumn)));
+      // Center the copy's text on the same axis; the hanging selection mark sits outside it.
+      const textWidth = Math.max(...copy.map((line) => visibleWidth(line))) - 2;
+      const copyLeft = Math.max(0, Math.round(axis - textWidth / 2) - 2);
+      const stack = [
+        ...record.map((line) => " ".repeat(artLeft) + line),
+        ...Array(STACK_GAP).fill(""),
+        ...copy.map((line) => " ".repeat(copyLeft) + line),
+      ];
+      const top = Math.max(0, Math.floor((rows - stack.length) / 2));
+      return finish(Array.from({ length: rows }, (_, row) => paint(stack[row - top] ?? "")));
     }
-    let colored = this.colored.get(key);
-    if (!colored) {
-      colored = art.map((ink) => {
-        let run = "";
-        let foreground = false;
-        let left = "";
-        for (const character of ink) {
-          const mask = character.codePointAt(0) - 0x2800;
-          const density = mask >= 0 && mask <= 255 ? mask.toString(2).replaceAll("0", "").length : 1;
-          const next = density >= 4;
-          if (next !== foreground && run) {
-            left += (foreground ? theme.text : theme.muted)(run);
-            run = "";
-          }
-          foreground = next;
-          run += character;
-        }
-        return left + (foreground ? theme.text : theme.muted)(run);
-      });
-      if (this.colored.size > LOGO_MOTION_FRAMES * 4) this.colored.clear();
-      this.colored.set(key, colored);
+    // Side by side, positions start at the art box's top-left corner.
+    const inked = art.lines.map((line) => stripVTControlCharacters(line).trim() !== "");
+    const artRows = [inked.indexOf(true), inked.lastIndexOf(true)];
+    // The wordmark's middle row sits level with the dog's eye.
+    const titleRows = title(sideCopyWidth, rows, sideRoomy).length;
+    const eyeTop = Math.floor(art.eye[1]) - Math.floor((titleRows - 1) / 2);
+    const scrolling = motionEnabled && !theme.plain;
+    const note = `"${this.sleeveNote}"`;
+    const arrange = (lines, below) => {
+      // Keep the copy on screen even when the eye sits low in a short sleeve.
+      const top = Math.min(eyeTop, artRows[0] + rows - lines.length);
+      const bodyTop = Math.min(artRows[0], top);
+      const bodyBottom = Math.max(artRows[1], top + lines.length - 1);
+      const groupRight = artWidth + 1 + Math.max(...lines.map((line) => visibleWidth(line)));
+      return { copy: lines, copyTop: top, bodyTop, bodyBottom, groupRight, below };
+    };
+    // Center the group from the disc's left edge to the copy's right edge; the arm hangs free.
+    const groupLeft = Math.max(0, Math.floor(discColumn - art.radius[0]));
+    // Prefer the lyric beneath the whole group, entering at the title's right edge and leaving past
+    // the disc's left edge; a short sleeve keeps it in the copy column instead.
+    // The action note's reserved rows give way first, since they are blank until Tab.
+    const lean = sideRoomy ? copyBlock(sideCopyWidth, rows, sideRoomy, false, false) : copy;
+    const fits = (candidate, lyricRows) => candidate.bodyBottom - candidate.bodyTop + 2 + lyricRows <= rows;
+    let layout = arrange(copy, true);
+    let span = layout.groupRight - groupLeft;
+    const lyricLines = (columns) => (scrolling ? [scrollingLyric(note, columns, this.lyricPosition)] : wrapTextWithAnsi(note, columns)).map(theme.muted);
+    let lyric = lyricLines(span);
+    if (!fits(layout, lyric.length)) {
+      layout = arrange(lean, true);
+      span = layout.groupRight - groupLeft;
+      lyric = lyricLines(span);
+    }
+    if (fits(layout, lyric.length)) {
+      this.canAnimate ||= scrolling;
+      this.lyricColumns = scrolling ? span : 0;
+    } else {
+      layout = arrange(withNote(lean, sideCopyWidth, rows - Math.max(0, eyeTop - artRows[0])), false);
     }
-    const count = rows;
-    const copyTop = Math.max(0, Math.floor((count - copy.length) / 2));
-    const artTop = Math.max(0, Math.floor((count - colored.length) / 2));
-    const lines = Array.from({ length: count }, (_, row) => {
-      const left = colored[row - artTop] ?? "";
-      return `  ${pad(left, artWidth)}   ${copy[row - copyTop] ?? ""}`;
+    const { copyTop, bodyTop, bodyBottom, below } = layout;
+    // Center the record and copy on their own; the lyric then floats midway between the record's
+    // bottom and the input box, keeping a blank row above it when the sleeve is short.
+    const bodyHeight = bodyBottom - bodyTop + 1;
+    const needed = below ? lyric.length + 2 : 0;
+    const bodyRow = Math.max(0, Math.min(Math.floor((rows - bodyHeight) / 2), rows - bodyHeight - needed));
+    const originRow = bodyRow - bodyTop;
+    const space = rows - (bodyRow + bodyHeight);
+    const lyricRow = bodyRow + bodyHeight + Math.max(1, Math.floor((space - lyric.length) / 2));
+    const originColumn = Math.max(0, Math.floor((width - (layout.groupRight - groupLeft)) / 2) - groupLeft);
+    const lines = Array.from({ length: rows }, (_, row) => {
+      if (below && row >= lyricRow && row < lyricRow + lyric.length) return " ".repeat(originColumn + groupLeft) + lyric[row - lyricRow];
+      const at = row - originRow;
+      const left = art.lines[at] ?? "";
+      const right = layout.copy[at - copyTop] ?? "";
+      return " ".repeat(originColumn) + pad(left, artWidth) + " " + right;
     });
     return finish(lines.map(paint));
   }
 }
 
-function wrapDescription(text, width) {
-  const lines = [];
-  let line = "";
-  for (const word of text.split(" ")) {
-    if (line && visibleWidth(`${line} ${word}`) > width) { lines.push(line); line = ""; }
-    line += (line ? " " : "") + word;
-  }
-  if (line) lines.push(line);
-  return lines;
+/** Ink each record layer separately: faint grooves, a grey surface, and the dog at full strength. */
+function toneRecord({ lines, tones }, theme) {
+  const inks = [theme.faint, theme.faint, theme.muted, theme.accent];
+  return lines.map((line, row) => {
+    let result = "";
+    let run = "";
+    let current = 0;
+    Array.from(line).forEach((character, column) => {
+      const tone = character === " " ? current : tones[row][column] ?? 0;
+      if (tone !== current && run) {
+        result += inks[current](run);
+        run = "";
+      }
+      current = tone;
+      run += character;
+    });
+    return result + (run ? inks[current](run) : "");
+  });
 }
 
-export function listeningHelp() {
-  return `# Your listening room
-
-## 01 / Listen and discover
-
-Just type to talk about music, ask for a playlist, or go exploring.
-To talk, Moondog needs a model: \`/auth\` signs you in, then \`/model\` picks one.
-
-- \`/taste\` - your profile: open any song or artist to see why it's there
-- \`/taste report\` - the whole picture on one page
-- \`/import\` - bring in your history, your library, or a playlist
-- \`/lyrics\` - the lyrics on the sleeve; \`/lyrics sync\` finds more
-- \`/spotify\` - play, queue, and make playlists in Spotify
-- \`/web search <query>\` or \`/web read <url>\` - look things up on public music sites
-
-## 02 / Make it yours
+/** The home actions as a sleeve tracklist: each row names the command that opens it. */
+function tracklist(theme, { focused, selected, columns }) {
+  // Two columns hold the selection mark; the rest matches the pixel wordmark's width.
+  const width = Math.min(columns, 43);
+  const fits = (key) => homeActions.every((action) => visibleWidth(action[key]) + action.command.length + 8 <= width);
+  const key = fits("label") ? "label" : fits("short") ? "short" : null;
+  return homeActions.map((action, index) => {
+    const active = focused && selected === index;
+    const label = action[key ?? "short"];
+    const marker = active ? theme.accent("◉ ") : "  ";
+    const name = active ? theme.selected(label) : focused ? theme.muted(label) : theme.text(label);
+    if (!key) return marker + name;
+    const command = `/${action.command}`;
+    const leader = "·".repeat(width - 4 - visibleWidth(label) - command.length);
+    return `${marker}${name} ${(active ? theme.accent : theme.faint)(leader)} ${(active ? theme.accent : theme.muted)(command)}`;
+  });
+}
 
-- \`/profile\` - the same profile as \`/taste\`
-- \`/profile corrections\` - everything you've told me
-- \`/profile retract <id>\` - undo one of those
-- \`/profile help\` - the full set of profile commands
-- \`/remember <text>\`, \`/memory\`, \`/forget <id>\` - what I remember between conversations
+/** Hold the tallest note's rows so moving through the list never shifts the sleeve. */
+function actionNote(text, width) {
+  const rows = Math.max(...homeActions.map((action) => wrapDescription(action.description, width).length));
+  const lines = wrapDescription(text, width);
+  return [...lines, ...Array(rows - lines.length).fill("")];
+}
 
-## 03 / Around the room
+function hang(line) {
+  return `  ${line}`;
+}
 
-- \`/home\` - back to the record sleeve; the conversation stays
-- \`/theme paper|charcoal|terminal|auto\` - change the look
-- \`/art braille|ascii|off\` - change the artwork
-- \`/motion on|off\` - turn the animation on or off
-- \`/commands\` or Ctrl+P - search every command; your message stays put
-- Page Up and Page Down scroll the conversation. The header and your draft stay put
-- \`/resume\` - pick up a saved conversation (type to filter, Enter opens)
-- \`/new\` - start fresh; this conversation stays saved
-- \`/status\`, \`/sources\`, \`/tools\`, \`/doctor\` - see what's connected and working
-- \`/reload\` - reload model settings and sign-ins
-- \`/help all\` - every command, including the ones for the shell
-- \`/quit\` - leave
+function wrapDescription(text, width) {
+  // Pi wraps by word and breaks text without spaces, such as Chinese or Japanese.
+  return wrapTextWithAnsi(text, Math.max(1, width)).map((line) => line.trimEnd());
+}
 
-Tab moves to the menu on the home screen. Esc goes back to typing.
-Enter sends, and Shift+Enter starts a new line.
-Tab or Enter accepts a suggestion.
-Ctrl+C stops a model or web request, or leaves when nothing is running.
-In the profile, type to filter, Tab switches lists, and Enter shows what you can do.
-Ctrl+R refreshes it and Ctrl+O opens the full report.
-Your profile works without a model.
-Put quotes around paths, titles, and names that have spaces.`;
+export function listeningHelp() {
+  return tr("# Your listening room\n\n## 01 / Listen and discover\n\nJust type to talk about music, ask for a playlist, or go exploring.\nTo talk, Moondog needs a model: `/auth` signs you in, then `/model` picks one.\nWhile an answer is coming, each step shows in the conversation, and the footer names the one in progress.\n\n- `/taste` - your profile: open any song or artist to see why it's there\n- `/taste report` - the whole picture on one page\n- `/import` - bring in your history, your library, or a playlist\n- `/lyrics` - the lyrics on the sleeve; `/lyrics sync` finds more\n- `/spotify` - play, queue, and make playlists in Spotify\n- Ask to move playback onto your iPhone, computer, or another Spotify device by name\n- `/web search <query>` or `/web read <url>` - look things up on public music sites\n\n## 02 / Make it yours\n\n- `/profile` - the same profile as `/taste`\n- `/profile corrections` - everything you've told me\n- `/profile retract <id>` - undo one of those\n- `/profile help` - the full set of profile commands\n- `/remember <text>`, `/memory`, `/forget <id>` - what I remember between conversations\n\n## 03 / Around the room\n\n- `/home` - back to the record sleeve; the conversation stays\n- `/theme paper|charcoal|terminal|auto` - change the look\n- `/art braille|ascii|off` - change the artwork\n- `/motion on|off` - turn the animation on or off\n- `/commands` or Ctrl+P - search every command; your message stays put\n- Page Up and Page Down scroll the conversation. The header and your draft stay put\n- Up and Down in the draft recall what you typed in this conversation\n- `/resume` - pick up a saved conversation (type to filter, Enter opens)\n- `/new` - start fresh; this conversation stays saved\n- `/status`, `/sources`, `/tools`, `/doctor` - see what's connected and working\n- `/reload` - reload model settings and sign-ins\n- `/update [--check] [--channel latest|beta]` - check for a release, or close this room and install it\n- `/help all` - every command, including the ones for the shell\n- `/language` - choose the language Moondog uses\n- `/quit` - leave\n\nTab moves to the menu on the home screen. Esc goes back to typing.\nEnter sends, and Shift+Enter starts a new line.\nTab or Enter accepts a suggestion.\nCtrl+C stops a model or web request, or leaves when nothing is running.\nIn the profile, type to filter, Tab switches lists, and Enter shows what you can do.\nCtrl+R refreshes it and Ctrl+O opens the full report.\nYour profile works without a model.\nPut quotes around paths, titles, and names that have spaces.");
 }