tmux-ide 2.6.1 → 2.7.0

package/packages/daemon/src/tui/mirror/blit.ts

@@ -0,0 +1,186 @@
+/**
+ * Pure cell → framebuffer writers for the framebuffer pane-blit path (M21.3).
+ *
+ * These map a mirror grid straight into an OpenTUI `OptimizedBuffer`'s typed
+ * arrays — no `StyledRun[]` intermediary, no per-run `RGBA` allocation, no Solid
+ * subtree. One packed cell is `char[i]` (a codepoint), four `fg`/`bg` channels
+ * (`r,g,b,a`, 0–255) at `i*4`, and one `attributes[i]` bitmask — the exact layout
+ * `OptimizedBuffer.buffers` exposes.
+ *
+ * Kept dependency-free (plain typed arrays) so the packing is unit-testable
+ * without the native render lib; {@link PaneMirror.blit} does the xterm walk and
+ * feeds these.
+ */
+
+/** The spacer (second) half of a wide glyph: char `0`. The native renderer knows
+ *  a cell is wide by MEASURING the lead cell's codepoint width and skips the
+ *  spacer, so the spacer's char just needs to be empty — this is exactly what
+ *  `OptimizedBuffer.setCell` writes for the trailing half (verified: a wide
+ *  glyph → `char[i]=codepoint, char[i+1]=0`). NB the `0xC0000000`
+ *  `CHAR_FLAG_CONTINUATION` seen in OptimizedBuffer is a DIFFERENT consumer (the
+ *  JS `getSpanLines`/`getRealCharBytes` text reader, off our render path);
+ *  writing it here blanks wide glyphs on screen (measured). */
+export const CHAR_CONTINUATION = 0;
+
+/** The space codepoint — the fill for blank / out-of-range cells. */
+export const SPACE_CODE = 0x20;
+
+/**
+ * INVERSE is rendered by SWAPPING fg/bg, not by the OpenTUI INVERSE attribute
+ * bit: a framebuffer cell carrying that bit composites (drawFrameBuffer preserves
+ * it) but does NOT flush as reverse-video — the direct `<text>` path does, the
+ * framebuffer path doesn't (measured). Swapping colors always renders (truecolor
+ * channels propagate cleanly), and covers app-driven reverse (vim status line),
+ * the cursor cell, and the drag selection uniformly. Swaps compose like the old
+ * XOR: two swaps on a cell (selection over the cursor) return it to normal.
+ */
+
+/** The four packed arrays behind an `OptimizedBuffer` (or a plain-array stand-in
+ *  for tests). `fg`/`bg` hold four `u16` channels (0–255) per cell at `i*4`. */
+export interface CellArrays {
+  char: Uint32Array;
+  fg: Uint16Array;
+  bg: Uint16Array;
+  attributes: Uint32Array;
+}
+
+/**
+ * A cell whose grapheme is more than one codepoint (ZWJ/flag emoji, combining
+ * marks) — a single `char[i]` u32 can't hold it. The fast blit writes its base
+ * codepoint; the caller (which owns the native `OptimizedBuffer`) re-writes these
+ * few cells with the full string via `setCell`, keeping full parity for the rare
+ * case without an allocation on the common path.
+ */
+export interface GraphemeOverride {
+  x: number;
+  y: number;
+  chars: string;
+  /** Packed `0xRRGGBB` or null (terminal default). */
+  fg: number | null;
+  bg: number | null;
+  attrs: number;
+}
+
+/**
+ * Write one styled cell at flat index `idx`. `fg`/`bg` are packed `0xRRGGBB` or
+ * `null` for the terminal default (→ the supplied `d*` channels); alpha is always
+ * opaque (panes never blend). No allocation — just eight typed-array stores.
+ */
+export function writeCell(
+  buf: CellArrays,
+  idx: number,
+  codepoint: number,
+  fg: number | null,
+  bg: number | null,
+  attrs: number,
+  dfR: number,
+  dfG: number,
+  dfB: number,
+  dbR: number,
+  dbG: number,
+  dbB: number,
+): void {
+  buf.char[idx] = codepoint;
+  const o = idx * 4;
+  if (fg === null) {
+    buf.fg[o] = dfR;
+    buf.fg[o + 1] = dfG;
+    buf.fg[o + 2] = dfB;
+  } else {
+    buf.fg[o] = (fg >> 16) & 0xff;
+    buf.fg[o + 1] = (fg >> 8) & 0xff;
+    buf.fg[o + 2] = fg & 0xff;
+  }
+  buf.fg[o + 3] = 255;
+  if (bg === null) {
+    buf.bg[o] = dbR;
+    buf.bg[o + 1] = dbG;
+    buf.bg[o + 2] = dbB;
+  } else {
+    buf.bg[o] = (bg >> 16) & 0xff;
+    buf.bg[o + 1] = (bg >> 8) & 0xff;
+    buf.bg[o + 2] = bg & 0xff;
+  }
+  buf.bg[o + 3] = 255;
+  buf.attributes[idx] = attrs;
+}
+
+/**
+ * Mark cell `idx` as the continuation (spacer) half of the wide glyph at `idx-1`,
+ * inheriting the glyph's colors so a colored wide glyph's background spans both
+ * cells. The renderer emits nothing for a continuation cell but still paints its
+ * background.
+ */
+export function writeContinuation(buf: CellArrays, idx: number): void {
+  buf.char[idx] = CHAR_CONTINUATION;
+  const o = idx * 4;
+  const p = (idx - 1) * 4;
+  buf.fg[o] = buf.fg[p]!;
+  buf.fg[o + 1] = buf.fg[p + 1]!;
+  buf.fg[o + 2] = buf.fg[p + 2]!;
+  buf.fg[o + 3] = buf.fg[p + 3]!;
+  buf.bg[o] = buf.bg[p]!;
+  buf.bg[o + 1] = buf.bg[p + 1]!;
+  buf.bg[o + 2] = buf.bg[p + 2]!;
+  buf.bg[o + 3] = buf.bg[p + 3]!;
+  buf.attributes[idx] = buf.attributes[idx - 1]!;
+}
+
+/**
+ * Swap fg/bg across cells `[from,to]` (inclusive, clamped to the row) of row `y`
+ * — the drag-selection reverse-video post-pass. A swap over the cursor cell (also
+ * swapped in the blit) returns it to normal, matching the run path's XOR.
+ */
+export function swapCells(
+  buf: CellArrays,
+  width: number,
+  y: number,
+  from: number,
+  to: number,
+): void {
+  const lo = Math.max(0, from);
+  const hi = Math.min(width - 1, to);
+  const base = y * width;
+  for (let x = lo; x <= hi; x++) {
+    const o = (base + x) * 4;
+    const r = buf.fg[o]!;
+    const g = buf.fg[o + 1]!;
+    const b = buf.fg[o + 2]!;
+    const a = buf.fg[o + 3]!;
+    buf.fg[o] = buf.bg[o]!;
+    buf.fg[o + 1] = buf.bg[o + 1]!;
+    buf.fg[o + 2] = buf.bg[o + 2]!;
+    buf.fg[o + 3] = buf.bg[o + 3]!;
+    buf.bg[o] = r;
+    buf.bg[o + 1] = g;
+    buf.bg[o + 2] = b;
+    buf.bg[o + 3] = a;
+  }
+}
+
+/**
+ * Paint the background of cells `[from,to]` (inclusive, clamped) of row `y` to
+ * packed `bg` — the scrollback-search highlight post-pass (the twin of
+ * {@link invertCells}; distinct treatment so a match and the selection coexist).
+ */
+export function paintBg(
+  buf: CellArrays,
+  width: number,
+  y: number,
+  from: number,
+  to: number,
+  bg: number,
+): void {
+  const lo = Math.max(0, from);
+  const hi = Math.min(width - 1, to);
+  const r = (bg >> 16) & 0xff;
+  const g = (bg >> 8) & 0xff;
+  const b = bg & 0xff;
+  for (let x = lo; x <= hi; x++) {
+    const o = (y * width + x) * 4;
+    buf.bg[o] = r;
+    buf.bg[o + 1] = g;
+    buf.bg[o + 2] = b;
+    buf.bg[o + 3] = 255;
+  }
+}

package/packages/daemon/src/tui/mirror/control-client.ts

@@ -12,14 +12,29 @@
  * intact; `parseControlLine`/`decodeControlBytes` do the pure protocol work.
  */
 import { spawn, type ChildProcess } from "node:child_process";
+import { appendFileSync } from "node:fs";
 import { parseControlLine, textToHexKeys } from "./control.ts";
 
 interface PendingReply {
+  discard?: false;
   resolve: (lines: string[]) => void;
   reject: (err: Error) => void;
   lines: string[];
 }
 
+/** A fire-and-forget command's FIFO placeholder: its reply block is consumed
+ *  and dropped (errors counted). `lines` collects the error body only when
+ *  TMUX_IDE_MIRROR_DEBUG asks for it. */
+interface DiscardedReply {
+  discard: true;
+  lines?: string[];
+}
+
+type Pending = PendingReply | DiscardedReply;
+
+/** The shared no-debug placeholder — fire-and-forget input allocates NOTHING. */
+const DISCARDED: DiscardedReply = { discard: true };
+
 export interface ControlClientOptions {
   /** Session (or other tmux target) to attach the control client to. */
   attachTarget: string;
@@ -33,9 +48,10 @@ export interface ControlClientOptions {
 
 export class ControlModeClient {
   private proc: ChildProcess | null = null;
-  private readonly pending: PendingReply[] = [];
+  private readonly pending: Pending[] = [];
   private inReply = false;
   private buffer = "";
+  private discardedErrors = 0;
   private readonly opts: ControlClientOptions;
 
   constructor(opts: ControlClientOptions) {
@@ -72,14 +88,38 @@ export class ControlModeClient {
     });
   }
 
-  /** Type literal text into a pane (UTF-8, sent as hex bytes — quote-proof). */
-  sendText(pane: string, text: string): Promise<string[]> {
-    return this.command(`send-keys -t ${pane} -H ${textToHexKeys(text).join(" ")}`);
+  /**
+   * The INPUT FAST PATH (M21.5): write a command fire-and-forget. The bytes
+   * hit tmux's stdin exactly as immediately as `command()`'s do, but no
+   * Promise/resolver is allocated and nothing ever waits on the reply. Every
+   * control-mode command still produces exactly one `%begin/%end` block, so a
+   * placeholder is pushed onto the SAME pending FIFO — reply matching for
+   * reply-carrying commands (list-panes, capture-pane, …) stays aligned by
+   * construction. Errors are swallowed but counted ({@link inputErrorCount});
+   * with TMUX_IDE_MIRROR_DEBUG set the error body is appended to
+   * /tmp/zz-input-errors.log.
+   */
+  send(cmd: string): void {
+    const proc = this.proc;
+    if (!proc?.stdin?.writable) return;
+    this.pending.push(process.env.TMUX_IDE_MIRROR_DEBUG ? { discard: true, lines: [] } : DISCARDED);
+    proc.stdin.write(`${cmd}\n`);
+  }
+
+  /** Type literal text into a pane (UTF-8, sent as hex bytes — quote-proof).
+   *  Fire-and-forget: input never queues behind a slow structural reply. */
+  sendText(pane: string, text: string): void {
+    this.send(`send-keys -t ${pane} -H ${textToHexKeys(text).join(" ")}`);
   }
 
-  /** Send a named tmux key (Enter, Escape, Up, C-c, …) to a pane. */
-  sendKey(pane: string, key: string): Promise<string[]> {
-    return this.command(`send-keys -t ${pane} ${key}`);
+  /** Send a named tmux key (Enter, Escape, Up, C-c, …) to a pane. Fire-and-forget. */
+  sendKey(pane: string, key: string): void {
+    this.send(`send-keys -t ${pane} ${key}`);
+  }
+
+  /** How many fire-and-forget commands came back `%error` (debug/tests). */
+  get inputErrorCount(): number {
+    return this.discardedErrors;
   }
 
   dispose(): void {
@@ -97,6 +137,7 @@ export class ControlModeClient {
   }
 
   private feed(chunk: string): void {
+    const t0 = process.env.TMUX_IDE_ZZ_PERF ? performance.now() : 0;
     this.buffer += chunk;
     let nl: number;
     while ((nl = this.buffer.indexOf("\n")) !== -1) {
@@ -106,6 +147,16 @@ export class ControlModeClient {
       this.buffer = this.buffer.slice(nl + 1);
       this.handleLine(line);
     }
+    if (t0) {
+      try {
+        appendFileSync(
+          "/tmp/zz-feed.log",
+          `${chunk.length} ${(performance.now() - t0).toFixed(2)}\n`,
+        );
+      } catch {
+        /* perf tap */
+      }
+    }
   }
 
   private handleLine(line: string): void {
@@ -114,14 +165,34 @@ export class ControlModeClient {
       case "begin":
         this.inReply = true;
         break;
-      case "reply-line":
-        this.pending[0]?.lines.push(event.line);
+      case "reply-line": {
+        const head = this.pending[0];
+        // Discarded (fire-and-forget) replies skip body collection entirely —
+        // unless the debug placeholder brought its own lines buffer.
+        if (head) head.lines?.push(event.line);
         break;
+      }
       case "end":
       case "error": {
         this.inReply = false;
         const reply = this.pending.shift();
         if (!reply) break; // unsolicited block (e.g. greeting after a race)
+        if (reply.discard) {
+          if (event.kind === "error") {
+            this.discardedErrors++;
+            if (process.env.TMUX_IDE_MIRROR_DEBUG) {
+              try {
+                appendFileSync(
+                  "/tmp/zz-input-errors.log",
+                  `#${this.discardedErrors} ${reply.lines?.join(" | ") ?? ""}\n`,
+                );
+              } catch {
+                // debug tap only
+              }
+            }
+          }
+          break;
+        }
         if (event.kind === "error") {
           reply.reject(new Error(reply.lines.join("\n") || "tmux command failed"));
         } else {

package/packages/daemon/src/tui/mirror/dialog-model.ts

@@ -0,0 +1,298 @@
+/**
+ * Dialog primitives — the PURE model (M22.4). Types + geometry + filtering for
+ * the three dialogs every setting is built from: {@link DialogSelectSpec} (a
+ * filterable list with a ● current-value marker and per-row key actions),
+ * {@link DialogPromptSpec} (one text input with validation), and
+ * {@link DialogConfirmSpec} (two options). The STACK that runs them lives in
+ * {@link ./dialog-stack.ts}; app.tsx mounts ONE overlay for whatever is on top.
+ *
+ * Geometry follows the palette's law (M21.9): the overlay is app-rendered, so
+ * its full geometry is knowable by pure math shared between the RENDER
+ * (placement) and the central mouse ROUTER (row hit-test / inside-vs-outside)
+ * — a click can never land where a row isn't drawn. Layout, in screen rows
+ * from `top`:
+ *   border (top+0) · title (top+1) · [filter input, select only] · rule ·
+ *   body rows (confirm only) · list/content rows … · footer hints · border.
+ * Rows span the box interior in x: [left+1, left+width-1).
+ */
+import { fuzzyFilter } from "../team/fuzzy.ts";
+
+// ── Specs ────────────────────────────────────────────────────────────────────
+
+/** One row of a select dialog. */
+export interface DialogSelectItem {
+  /** Stable id the caller dispatches on. */
+  id: string;
+  /** What the list shows and the fuzzy filter scores. */
+  label: string;
+  /** Dim, right-aligned annotation (current value, key name, …). */
+  detail?: string;
+  /** The current value — rendered with the ● marker. */
+  current?: boolean;
+  /** Destructive — enter/click arms an inline "press again to confirm" first. */
+  danger?: boolean;
+  /** Optional RGB swatch rendered as a colored ● before the label (theme rows). */
+  swatch?: [number, number, number];
+}
+
+/** A per-row action bound to a ctrl+key chord, shown in the footer. */
+export interface DialogRowAction {
+  /** The letter — triggered as ctrl+<key> so it never collides with filter typing. */
+  key: string;
+  /** Footer label, e.g. `^d delete`. */
+  label: string;
+}
+
+export interface DialogSelectSpec {
+  kind: "select";
+  title: string;
+  items: DialogSelectItem[];
+  /** Type-to-filter (default true). Read-only viewers keep it on for search. */
+  filterable?: boolean;
+  /** Plain-language footer note (e.g. "applies after re-adopt — run tmux-ide adopt <session>"). */
+  footerHint?: string;
+  /** Per-row key-bound actions listed in the footer. */
+  actions?: DialogRowAction[];
+  /** Live-preview hook — fired by the stack whenever the SELECTION lands on a
+   *  different item (keyboard and mouse both), never on open. */
+  onMove?: (item: DialogSelectItem) => void;
+  /** Start the selection here (defaults to the `current` item, else 0). */
+  initialSel?: number;
+}
+
+export interface DialogPromptSpec {
+  kind: "prompt";
+  title: string;
+  /** Dim example shown while the input is empty. */
+  placeholder?: string;
+  /** Pre-filled input. */
+  initial?: string;
+  /** Plain-language footer note shown while there is no error. */
+  footerHint?: string;
+  /** Return an error message to reject, null to accept. */
+  validate?: (value: string) => string | null;
+}
+
+export interface DialogConfirmSpec {
+  kind: "confirm";
+  title: string;
+  /** Optional explanation line(s) — wrapped to the box width. */
+  body?: string;
+  /** First option (the affirmative). Default "Yes". */
+  yesLabel?: string;
+  /** Second option. Default "No". */
+  noLabel?: string;
+  /** Start on the second option (the safe default for destructive asks). */
+  defaultNo?: boolean;
+}
+
+export type DialogSpec = DialogSelectSpec | DialogPromptSpec | DialogConfirmSpec;
+
+/** What a select resolves with: the chosen item, plus the action key when a
+ *  per-row ctrl+key action (not enter/click) triggered it. */
+export interface DialogSelectResult {
+  item: DialogSelectItem;
+  action?: string;
+}
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+/** Box width — matches the palette so the two overlays read as one family. */
+export const DIALOG_W = 60;
+/** Visible list rows before the wheel/follow-scroll windows the slice. */
+export const DIALOG_ROWS = 10;
+/** The inline destructive re-arm suffix (plain language, no modal). */
+export const DIALOG_CONFIRM_SUFFIX = " — press again to confirm";
+/** The current-value marker. */
+export const DIALOG_CURRENT_MARK = "●";
+
+// ── Filtering / selection ────────────────────────────────────────────────────
+
+/** PURE — the visible rows for a query: fuzzy-filtered + score-sorted (the
+ *  palette's idiom); an empty query returns every item in natural order. */
+export function filterDialogItems(
+  query: string,
+  items: readonly DialogSelectItem[],
+): DialogSelectItem[] {
+  const q = query.trim();
+  if (q.length === 0) return [...items];
+  return fuzzyFilter(q, [...items], (i) => i.label).map((m) => m.item);
+}
+
+/** PURE — where the selection starts: `initialSel` when valid, else the
+ *  `current` item, else 0. */
+export function initialSelIndex(spec: DialogSelectSpec): number {
+  if (
+    spec.initialSel !== undefined &&
+    spec.initialSel >= 0 &&
+    spec.initialSel < spec.items.length
+  ) {
+    return spec.initialSel;
+  }
+  const cur = spec.items.findIndex((i) => i.current);
+  return cur >= 0 ? cur : 0;
+}
+
+/** PURE — keep `sel` visible: the window `top` that contains it, moving as
+ *  little as possible (keyboard follow-scroll; the wheel moves `top` alone). */
+export function followTop(sel: number, top: number, pageRows: number): number {
+  if (sel < top) return sel;
+  if (sel > top + pageRows - 1) return sel - pageRows + 1;
+  return top;
+}
+
+/** PURE — clamp a wheel-scrolled list top into [0, count - pageRows]. */
+export function clampDialogTop(top: number, count: number, pageRows: number): number {
+  return Math.max(0, Math.min(top, count - pageRows));
+}
+
+// ── Geometry ─────────────────────────────────────────────────────────────────
+
+/** The placed box + the row bands the router hit-tests. */
+export interface DialogGeom {
+  left: number;
+  top: number;
+  width: number;
+  /** Chrome rows above the first hit-testable row: top border + title +
+   *  (filter input) + rule + (confirm body). */
+  headerRows: number;
+  /** Hit-testable rows on screen right now (select window / confirm options /
+   *  the prompt's input row). 0 renders one non-hittable placeholder row. */
+  visibleRows: number;
+  /** Footer hint rows (always 1 — hints/errors live there). */
+  footerRows: number;
+}
+
+/** PURE — placement: horizontally centered, top at a sixth of the height
+ *  (min 1 — below the surface tab bar). Same law as the palette. */
+export function dialogPos(
+  termW: number,
+  termH: number,
+  width: number,
+): { left: number; top: number } {
+  return {
+    left: Math.max(0, Math.floor((termW - width) / 2)),
+    top: Math.max(1, Math.floor(termH / 6)),
+  };
+}
+
+/** PURE — greedy word-wrap for the confirm body (never returns empty for
+ *  non-empty text; words longer than the width hard-break). */
+export function wrapText(text: string, width: number): string[] {
+  if (width <= 0) return [text];
+  const out: string[] = [];
+  for (const para of text.split("\n")) {
+    let line = "";
+    for (const word of para.split(/\s+/).filter(Boolean)) {
+      if (line.length === 0) {
+        let w = word;
+        while (w.length > width) {
+          out.push(w.slice(0, width));
+          w = w.slice(width);
+        }
+        line = w;
+      } else if (line.length + 1 + word.length <= width) {
+        line += ` ${word}`;
+      } else {
+        out.push(line);
+        let w = word;
+        while (w.length > width) {
+          out.push(w.slice(0, width));
+          w = w.slice(width);
+        }
+        line = w;
+      }
+    }
+    if (line.length > 0 || para.length === 0) out.push(line);
+  }
+  return out.length > 0 ? out : [""];
+}
+
+/** PURE — the interior text width of the box (borders + 1-cell padding each side). */
+export function dialogInnerW(width: number): number {
+  return width - 4;
+}
+
+/** PURE — chrome rows above the first hit-testable row, per kind. */
+export function dialogHeaderRows(spec: DialogSpec): number {
+  // top border + title + rule = 3 …
+  if (spec.kind === "select") return spec.filterable === false ? 3 : 4; // … + filter input
+  if (spec.kind === "prompt") return 3;
+  return 3 + (spec.body ? wrapText(spec.body, dialogInnerW(DIALOG_W)).length : 0);
+}
+
+/** PURE — total box height for a geometry (empty lists still show one
+ *  placeholder row) — used for inside/outside containment. */
+export function dialogHeight(g: DialogGeom): number {
+  return g.headerRows + Math.max(1, g.visibleRows) + g.footerRows + 1;
+}
+
+/** PURE — the VISIBLE hit-testable row index under (x, y), or -1. x must be
+ *  inside the box interior (borders excluded); only real rows hit. */
+export function dialogRowAt(g: DialogGeom, x: number, y: number): number {
+  if (x < g.left + 1 || x >= g.left + g.width - 1) return -1;
+  const row = y - (g.top + g.headerRows);
+  return row >= 0 && row < g.visibleRows ? row : -1;
+}
+
+/** PURE — whether (x, y) falls anywhere on the box (border included). A press
+ *  outside pops ONE stack level; inside-but-not-a-row is a no-op. */
+export function dialogContains(g: DialogGeom, x: number, y: number): boolean {
+  return x >= g.left && x < g.left + g.width && y >= g.top && y < g.top + dialogHeight(g);
+}
+
+// ── Row / footer text ────────────────────────────────────────────────────────
+
+/** PURE — a select row's leading marker: `● ` on the current value (kept even
+ *  while selected — the value marker is the point), else `› `/2 spaces. */
+export function dialogMarker(item: { current?: boolean }, selected: boolean): string {
+  if (item.current) return `${DIALOG_CURRENT_MARK} `;
+  return selected ? "› " : "  ";
+}
+
+/** PURE — a select row's body text: marker + label (+ the inline destructive
+ *  re-arm suffix when armed), with `detail` right-aligned in the interior
+ *  width; overlong labels truncate before the detail. */
+export function dialogRowText(
+  item: DialogSelectItem,
+  opts: { selected: boolean; armed: boolean; innerW: number },
+): string {
+  const marker = dialogMarker(item, opts.selected);
+  const label = opts.armed ? `${item.label}${DIALOG_CONFIRM_SUFFIX}` : item.label;
+  const detail = opts.armed ? "" : (item.detail ?? "");
+  const bodyW = opts.innerW - marker.length;
+  if (detail.length === 0) return marker + label.slice(0, bodyW).padEnd(bodyW);
+  const labelW = Math.max(1, bodyW - detail.length - 2);
+  return `${marker}${label.slice(0, labelW).padEnd(labelW)}  ${detail}`.slice(0, opts.innerW);
+}
+
+/** PURE — the select footer: key hints first, then the per-row actions, then
+ *  the caller's plain-language note. */
+export function selectFooter(spec: DialogSelectSpec): string {
+  const parts = ["enter select", "esc cancel"];
+  for (const a of spec.actions ?? []) parts.push(`^${a.key} ${a.label}`);
+  if (spec.footerHint) parts.push(spec.footerHint);
+  return parts.join(" · ");
+}
+
+/** PURE — the prompt footer: a busy note wins, then the validation error, then
+ *  the hint, then the default keys line. The `error` flag tells the render to
+ *  tint it as a problem. */
+export function promptFooter(
+  spec: DialogPromptSpec,
+  state: { error: string | null; busy: boolean },
+): { text: string; error: boolean } {
+  if (state.busy) return { text: "saving…", error: false };
+  if (state.error) return { text: state.error, error: true };
+  return { text: spec.footerHint ?? "enter save · esc cancel", error: false };
+}
+
+/** PURE — the confirm footer. */
+export function confirmFooter(): string {
+  return "enter choose · y/n · esc cancel";
+}
+
+/** PURE — the confirm option labels in row order (affirmative first). */
+export function confirmOptions(spec: DialogConfirmSpec): [string, string] {
+  return [spec.yesLabel ?? "Yes", spec.noLabel ?? "No"];
+}