subrouter-cli 0.0.0-stage → 0.1.0

package/src/lineinput.ts

@@ -0,0 +1,726 @@
+// lineinput.ts — raw-mode line editor for the REPL (macOS Terminal).
+// Bracketed paste submits multi-line pastes as one turn; Ctrl+C interrupts, Ctrl+D
+// exits, arrows walk history, Ctrl+A/E and left/right move the cursor. Piped stdin
+// falls back to plain readline so `echo "…" | sub` keeps working.
+
+import readline from 'node:readline';
+import { StringDecoder } from 'node:string_decoder';
+import { ui, violet, bold, dim } from './ui.ts';
+import { matchingCommands } from './commands.ts';
+
+export interface LineInputHandlers {
+  onLine(line: string): void;
+  onInterrupt(): void;
+  onEof(): void;
+  onPasteImage?(): void;
+  onClearImages?(): void;
+}
+
+const PASTE_START = '\x1b[200~';
+const PASTE_END = '\x1b[201~';
+/** Visible rows in the picker menu; the list scrolls under this window when longer. */
+const MENU_HEIGHT = 15;
+
+/** Pure key-to-action core — separated so the editor logic stays testable. */
+export function editLine(
+  chars: string,
+  state: { buffer: string; cursor: number },
+): { buffer: string; cursor: number; submit?: string; interrupt?: boolean } {
+  const out = { ...state };
+  for (const c of chars) {
+    if (c === '\r' || c === '\n') {
+      return { ...out, submit: out.buffer };
+    }
+    if (c === '\x03') {
+      return { buffer: '', cursor: 0, interrupt: true };
+    }
+    if (c === '\x7f' || c === '\b') {
+      if (out.cursor > 0) {
+        out.buffer = out.buffer.slice(0, out.cursor - 1) + out.buffer.slice(out.cursor);
+        out.cursor--;
+      }
+      continue;
+    }
+    if (c === '\x01') {
+      out.cursor = 0; // Ctrl+A home
+      continue;
+    }
+    if (c === '\x05') {
+      out.cursor = out.buffer.length; // Ctrl+E end
+      continue;
+    }
+    if (c === '\x15') {
+      out.buffer = ''; // Ctrl+U kill line
+      out.cursor = 0;
+      continue;
+    }
+    if (c === '\x0b') {
+      out.buffer = out.buffer.slice(0, out.cursor); // Ctrl+K kill to end
+      continue;
+    }
+    if (c >= ' ') {
+      out.buffer = out.buffer.slice(0, out.cursor) + c + out.buffer.slice(out.cursor);
+      out.cursor++;
+    }
+    // other control chars are ignored
+  }
+  return out;
+}
+
+export class LineInput {
+  private handlers: LineInputHandlers;
+  private prompt = violet('❯ ');
+  private model = '';
+  private buffer = '';
+  private cursor = 0;
+  private history: string[] = [];
+  private histIndex = 0;
+  private pasting = false;
+  private pasteBuf = '';
+  private esc = '';
+  private decoder = new StringDecoder('utf8');
+  private fallback: readline.Interface | null = null;
+  private questionResolve: ((answer: string) => void) | null = null;
+  private echoQuestion = true;
+  private stopped = false;
+  private paused = false;
+  private working = false;
+  private questionDraft: { buffer: string; cursor: number; histIndex: number; prompt: string } | null = null;
+  private selectItems: string[] | null = null;
+  private selectIndex = 0;
+  private selectTop = 0;
+  private selectResolve: ((index: number | null) => void) | null = null;
+  private selectEsc = '';
+  private menuShown = false;
+  private dockMenu = false;
+  private selectEscapeTimer: NodeJS.Timeout | null = null;
+  private paletteOpen = false;
+  private paletteIndex = 0;
+  private paletteText = '';
+  private paletteDismissed = false;
+  private viewResolve: (() => void) | null = null;
+  private viewRefresh: (() => Promise<string[]>) | null = null;
+  private viewEsc = '';
+  private viewRefreshing = false;
+  private navigation = '';
+  private navigationTimer: NodeJS.Timeout | null = null;
+
+  /** Live read-only command panel; arrows scroll, r refreshes, Enter/Esc dismisses. */
+  view(lines: string[], refresh: () => Promise<string[]>): Promise<void> {
+    this.closePalette();
+    if (!ui.panel(lines, () => this.closeView())) {
+      lines.forEach((line) => ui.say(line));
+      return Promise.resolve();
+    }
+    this.viewRefresh = refresh;
+    return new Promise((resolve) => { this.viewResolve = resolve; });
+  }
+
+  updateView(lines: string[]): void {
+    if (this.viewResolve) ui.panel(lines);
+  }
+
+  private closeView(): void {
+    const resolve = this.viewResolve;
+    this.viewResolve = null;
+    this.viewRefresh = null;
+    this.viewEsc = '';
+    this.viewRefreshing = false;
+    if (this.selectEscapeTimer) clearTimeout(this.selectEscapeTimer);
+    this.selectEscapeTimer = null;
+    ui.closePanel();
+    resolve?.();
+  }
+
+  private closePalette(): void {
+    if (this.paletteOpen) ui.closeMenu();
+    this.paletteOpen = false;
+    if (this.selectEscapeTimer) clearTimeout(this.selectEscapeTimer);
+    this.selectEscapeTimer = null;
+    this.esc = '';
+  }
+
+  constructor(handlers: LineInputHandlers) {
+    this.handlers = handlers;
+  }
+
+  /** Enable the editor; piped stdin falls back to plain readline. */
+  start(): void {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      this.fallback = readline.createInterface({ input: process.stdin, output: process.stdout });
+      this.fallback.on('line', (line) => {
+        if (this.questionResolve) {
+          this.answerQuestion(line);
+          return;
+        }
+        this.handlers.onLine(line);
+      });
+      this.fallback.on('SIGINT', () => {
+        if (this.questionResolve) this.answerQuestion('n');
+        this.handlers.onInterrupt();
+      });
+      this.fallback.on('close', () => {
+        if (this.questionResolve) this.answerQuestion('n');
+        this.handlers.onEof();
+      });
+      return;
+    }
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('data', this.onData);
+    process.on('SIGTERM', this.onSigterm);
+    this.redraw();
+  }
+
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    if (this.navigationTimer) clearTimeout(this.navigationTimer);
+    this.navigationTimer = null;
+    this.navigation = '';
+    this.closePalette();
+    if (this.viewResolve) this.closeView();
+    ui.clearComposer();
+    if (this.selectResolve) this.selectFinish(null);
+    ui.closeDock();
+    if (this.fallback) {
+      this.fallback.close();
+      return;
+    }
+    process.stdin.off('data', this.onData);
+    process.off('SIGTERM', this.onSigterm);
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    process.stdin.pause();
+  }
+
+  /** Stop and fire onEof exactly once (the /exit and Ctrl+D path). */
+  close(): void {
+    if (this.stopped) return;
+    if (this.fallback) {
+      this.fallback.close(); // its 'close' handler fires onEof
+      return;
+    }
+    this.stop();
+    this.handlers.onEof();
+  }
+
+  /** Pause normal editing during command/clipboard loading; interrupts stay responsive. */
+  pause(): void {
+    this.paused = true;
+    ui.clearComposer();
+  }
+
+  resume(): void {
+    this.paused = false;
+    this.redraw();
+  }
+
+  /** Live drafting during agent turns; submitted steering renders at a safe boundary. */
+  setWorking(working: boolean): void {
+    this.working = working;
+    this.redraw();
+  }
+
+  /** Release an open command panel/picker before an agent permission question. */
+  cancelControls(): void {
+    if (this.viewResolve) this.closeView();
+    if (this.selectResolve) this.selectFinish(null);
+    if (this.questionResolve) this.answerQuestion('n');
+    this.closePalette();
+  }
+
+  /** Put unsent steering back in the editor after cancellation/error/round limit. */
+  restoreDraft(lines: string[]): void {
+    if (!lines.length) return;
+    const prefix = lines.join(' ') + (this.buffer ? ' ' : '');
+    this.buffer = prefix + this.buffer;
+    this.cursor += prefix.length;
+    this.redraw();
+  }
+
+  private answerQuestion(answer: string): void {
+    const resolve = this.questionResolve;
+    this.questionResolve = null;
+    ui.closeApproval();
+    this.echoQuestion = true;
+    if (this.questionDraft) {
+      const draft = this.questionDraft;
+      this.buffer = draft.buffer;
+      this.cursor = draft.cursor;
+      this.histIndex = draft.histIndex;
+      this.prompt = draft.prompt;
+      this.questionDraft = null;
+    }
+    this.redraw();
+    resolve?.(answer);
+  }
+
+  /** One-shot question mode temporarily replaces, then restores, the current draft. */
+  question(prompt: string, echoAnswer = true): Promise<string> {
+    this.questionDraft = { buffer: this.buffer, cursor: this.cursor, histIndex: this.histIndex, prompt: this.prompt };
+    this.echoQuestion = echoAnswer;
+    this.prompt = prompt;
+    this.buffer = '';
+    this.cursor = 0;
+    return new Promise((resolve) => {
+      this.questionResolve = resolve;
+      this.redraw();
+    });
+  }
+
+  /** Interactive picker: arrow-key menu in a TTY, numbered list in a pipe. Resolves to
+   *  the chosen index (0-based) or null when cancelled. `current` pre-highlights a row. */
+  select(items: string[], current = 0): Promise<number | null> {
+    if (items.length === 0) return Promise.resolve(null);
+    if (this.fallback) {
+      const width = String(items.length).length;
+      items.forEach((label, i) => ui.say(`${String(i + 1).padStart(width)}. ${label}`));
+      return this.question('pick a number (Enter to cancel): ').then((answer) => {
+        const n = Number(answer);
+        return Number.isInteger(n) && n >= 1 && n <= items.length ? n - 1 : null;
+      });
+    }
+    this.closePalette();
+    this.selectItems = items;
+    this.selectIndex = Math.max(0, Math.min(current, items.length - 1));
+    this.selectTop = 0;
+    this.selectEsc = '';
+    ui.clearLine(); // the menu replaces the prompt line
+    this.menuShown = false;
+    this.renderMenu();
+    return new Promise((resolve) => {
+      this.selectResolve = resolve;
+    });
+  }
+
+  setModel(model: string): void {
+    this.model = model;
+  }
+
+  /** Re-render prompt + buffer (called after output lands on the terminal). */
+  redraw(): void {
+    if (this.stopped || this.paused || this.fallback || this.selectItems || this.viewResolve) return;
+    if (this.questionResolve) {
+      if (!ui.setApprovalChoice(this.buffer, this.cursor)) ui.line(this.prompt, this.buffer, this.cursor);
+    }
+    else {
+      if (this.buffer !== this.paletteText) {
+        this.paletteText = this.buffer;
+        this.paletteIndex = 0;
+        this.paletteDismissed = false;
+      }
+      const commands = this.paletteDismissed ? [] : matchingCommands(this.buffer);
+      if (commands.length) {
+        this.paletteIndex = Math.min(this.paletteIndex, commands.length - 1);
+        this.paletteOpen = ui.menu(commands.map((c) => `${c.id.padEnd(9)} ${c.description}`), this.paletteIndex, 0,
+          () => { this.paletteDismissed = true; this.closePalette(); },
+          '↑/↓ choose · tab complete · enter run · esc close');
+      } else this.closePalette();
+      ui.composer(this.model, this.prompt, this.buffer, this.cursor);
+    }
+  }
+
+  private setLine(text: string): void {
+    this.buffer = text;
+    this.cursor = text.length;
+  }
+
+  private submit(text: string): void {
+    this.closePalette();
+    if (this.working && !this.questionResolve) ui.clearComposer(); // queued steering renders at the next safe boundary
+    else if (text.trimStart().startsWith('/') && !this.questionResolve && process.stdout.isTTY) ui.clearComposer();
+    else if ((!this.questionResolve || this.echoQuestion) && !ui.hasApproval()) ui.submitInput(this.prompt, text);
+    this.buffer = '';
+    this.cursor = 0;
+    this.prompt = violet('❯ ');
+    if (this.questionResolve) {
+      this.answerQuestion(text);
+      return;
+    }
+    if (text !== '' && this.history.at(-1) !== text) {
+      this.history.push(text);
+    }
+    this.histIndex = this.history.length;
+    this.handlers.onLine(text);
+  }
+
+  private onData = (chunk: Buffer): void => {
+    for (const c of this.decoder.write(chunk)) {
+      if (this.stopped) return;
+      if (this.pasting) {
+        this.pasteBuf += c;
+        if (this.pasteBuf.endsWith(PASTE_END)) {
+          this.pasteBuf = this.pasteBuf.slice(0, -PASTE_END.length);
+          this.deliver(PASTE_END);
+        }
+        continue;
+      }
+      if (c === '\x03' || c === '\x04') {
+        if (this.navigationTimer) clearTimeout(this.navigationTimer);
+        this.navigationTimer = null;
+        this.navigation = '';
+        this.deliver(c);
+        continue;
+      }
+      if (this.navigation || c === '\x1b') {
+        this.navigation += c;
+        if (this.navigationTimer) clearTimeout(this.navigationTimer);
+        this.navigationTimer = null;
+        if (/^\x1b\[[\d;<?]*[A-Za-z~]$/.test(this.navigation) || this.navigation.length > 80 ||
+          this.navigation.length > 1 && !this.navigation.startsWith('\x1b[')) {
+          const sequence = this.navigation;
+          this.navigation = '';
+          if (!this.scrollKey(sequence)) this.deliver(sequence);
+        } else {
+          this.navigationTimer = setTimeout(() => {
+            const sequence = this.navigation;
+            this.navigation = '';
+            this.navigationTimer = null;
+            if (sequence === '\x1b' && !this.paused) {
+              if (this.viewResolve) this.closeView();
+              else if (this.selectResolve) this.selectFinish(null);
+              else if (this.questionResolve) this.answerQuestion('n');
+              else {
+                this.paletteDismissed = true;
+                this.closePalette();
+                this.redraw();
+              }
+            }
+          }, 100);
+        }
+        continue;
+      }
+      this.deliver(c);
+    }
+  };
+
+  private deliver(chars: string): void {
+    if (this.stopped) return;
+    if (this.paused) {
+      if (chars.includes('\x04')) this.close();
+      else if (chars.includes('\x03')) this.handlers.onInterrupt();
+    } else this.handle(chars);
+  }
+
+  private scrollKey(sequence: string): boolean {
+    const mouse = /^\x1b\[<(\d+);\d+;\d+[Mm]$/.exec(sequence);
+    const page = sequence === '\x1b[5~' ? -1 : sequence === '\x1b[6~' ? 1 : 0;
+    if (!mouse && !page) return false;
+    const button = mouse ? Number(mouse[1]) : 0;
+    if (mouse && (button & 64) === 0) return true; // discard click reports
+    const direction = page || ((button & 1) === 0 ? -1 : 1);
+    const delta = direction * (page ? 8 : 3);
+    if (this.viewResolve) ui.scrollPanel(delta);
+    else if (this.selectItems) this.selectMove(delta);
+    else if (this.paletteOpen) {
+      this.paletteIndex = Math.max(0, Math.min(matchingCommands(this.buffer).length - 1, this.paletteIndex + direction));
+      this.redraw();
+    } else if (this.questionResolve && ui.hasApproval()) ui.scrollApproval(delta);
+    else ui.scrollChat(-delta);
+    return true;
+  }
+
+  private onSigterm = (): void => {
+    this.stop();
+    process.exit(0);
+  };
+
+  private handle(chars: string): void {
+    if (this.viewResolve) {
+      this.handleView(chars);
+      return;
+    }
+    if (this.selectResolve) {
+      this.handleSelect(chars);
+      return;
+    }
+    let i = 0;
+    while (i < chars.length) {
+      const c = chars[i];
+      if (this.pasting) {
+        const end = chars.indexOf(PASTE_END, i);
+        if (end === -1) {
+          this.pasteBuf += chars.slice(i);
+          return;
+        }
+        this.pasteBuf += chars.slice(i, end);
+        i = end + PASTE_END.length;
+        this.pasting = false;
+        const pasted = this.pasteBuf;
+        this.pasteBuf = '';
+        if (pasted.includes('\n')) {
+          if (pasted.trimEnd() !== '') this.setLine(pasted.replace(/\n/g, ' ').trimEnd());
+          // A trailing-newline paste submits as one turn (bracketed-paste contract).
+          if (pasted.endsWith('\n')) {
+            this.submit(this.buffer);
+            this.redraw();
+            return;
+          }
+          this.redraw();
+          continue;
+        }
+        this.insert(pasted);
+        this.redraw();
+        continue;
+      }
+      if (this.esc) {
+        if (this.selectEscapeTimer) clearTimeout(this.selectEscapeTimer);
+        this.selectEscapeTimer = null;
+        this.esc += c;
+        if (this.escIsComplete()) {
+          this.handleEscape(this.esc);
+          this.esc = '';
+        }
+        i++;
+        continue;
+      }
+      if (c === '\x1b') {
+        this.esc = c;
+        if (this.paletteOpen) {
+          this.selectEscapeTimer = setTimeout(() => {
+            this.esc = '';
+            this.paletteDismissed = true;
+            this.closePalette();
+            this.redraw();
+          }, 100);
+        }
+        i++;
+        continue;
+      }
+      if (!this.questionResolve && (c === '\x16' || c === '\x18')) {
+        this.closePalette();
+        this.paletteDismissed = true;
+        if (c === '\x16') this.handlers.onPasteImage?.();
+        else this.handlers.onClearImages?.();
+        i++;
+        continue;
+      }
+      if (c === '\t' && this.paletteOpen) {
+        const chosen = matchingCommands(this.buffer)[this.paletteIndex];
+        if (chosen) this.setLine(chosen.id + ' ');
+        this.redraw();
+        i++;
+        continue;
+      }
+      if (c === '\r' || c === '\n') {
+        const chosen = this.paletteOpen ? matchingCommands(this.buffer)[this.paletteIndex] : undefined;
+        this.submit(chosen?.id ?? this.buffer);
+        i++;
+        continue;
+      }
+      if (c === '\x03') {
+        if (!this.working || this.questionResolve) this.setLine('');
+        this.redraw();
+        if (this.questionResolve) this.answerQuestion('n'); // cancellation must never approve a write
+        this.handlers.onInterrupt();
+        i++;
+        continue;
+      }
+      if (c === '\x04') {
+        if (this.buffer === '' || this.questionResolve) {
+          if (this.questionResolve) this.answerQuestion('n');
+          this.close();
+        }
+        i++;
+        continue;
+      }
+      const result = editLine(c, { buffer: this.buffer, cursor: this.cursor });
+      this.buffer = result.buffer;
+      this.cursor = result.cursor;
+      if (result.submit !== undefined) this.submit(result.submit);
+      else this.redraw();
+      i++;
+    }
+  }
+
+  private insert(text: string): void {
+    this.buffer = this.buffer.slice(0, this.cursor) + text + this.buffer.slice(this.cursor);
+    this.cursor += text.length;
+  }
+
+  private escIsComplete(): boolean {
+    const e = this.esc;
+    if (e === PASTE_START || e === PASTE_END) return true;
+    if (!e.startsWith('\x1b[')) return e.length >= 2;
+    const last = e.at(-1);
+    return last === '~' || last === 'A' || last === 'B' || last === 'C' || last === 'D' || last === 'H' || last === 'F';
+  }
+
+  private handleEscape(seq: string): void {
+    if (this.paletteOpen && (seq === '\x1b[A' || seq === '\x1b[B')) {
+      const delta = seq === '\x1b[A' ? -1 : 1;
+      this.paletteIndex = Math.max(0, Math.min(matchingCommands(this.buffer).length - 1, this.paletteIndex + delta));
+      this.redraw();
+      return;
+    }
+    if (seq === PASTE_START) {
+      this.pasting = true;
+      this.pasteBuf = '';
+      return;
+    }
+    if (seq === PASTE_END) {
+      this.pasting = false;
+      return;
+    }
+    switch (seq) {
+      case '\x1b[A': // up — history
+        if (this.history.length > 0) {
+          this.histIndex = Math.max(0, this.histIndex - 1);
+          this.setLine(this.history[this.histIndex] ?? '');
+          this.redraw();
+        }
+        break;
+      case '\x1b[B': // down — history
+        if (this.histIndex < this.history.length) {
+          this.histIndex = Math.min(this.history.length, this.histIndex + 1);
+          this.setLine(this.history[this.histIndex] ?? '');
+          this.redraw();
+        }
+        break;
+      case '\x1b[C': // right
+        if (this.cursor < this.buffer.length) {
+          this.cursor++;
+          this.redraw();
+        }
+        break;
+      case '\x1b[D': // left
+        if (this.cursor > 0) {
+          this.cursor--;
+          this.redraw();
+        }
+        break;
+      case '\x1b[H': // home
+        this.cursor = 0;
+        this.redraw();
+        break;
+      case '\x1b[F': // end
+        this.cursor = this.buffer.length;
+        this.redraw();
+        break;
+      default:
+        break; // unknown sequences ignored
+    }
+  }
+
+  private handleView(chars: string): void {
+    for (const c of chars) {
+      if (this.viewEsc) {
+        if (this.selectEscapeTimer) clearTimeout(this.selectEscapeTimer);
+        this.selectEscapeTimer = null;
+        this.viewEsc += c;
+        if (this.viewEsc === '\x1b[A' || this.viewEsc === '\x1b[B') {
+          ui.scrollPanel(this.viewEsc === '\x1b[A' ? -1 : 1);
+          this.viewEsc = '';
+        } else if (!this.viewEsc.startsWith('\x1b[') || this.viewEsc.length > 3) this.viewEsc = '';
+        continue;
+      }
+      if (c === '\x1b') {
+        this.viewEsc = c;
+        this.selectEscapeTimer = setTimeout(() => this.closeView(), 100);
+      } else if (c === '\r' || c === '\n' || c === '\x03') {
+        this.closeView();
+        return;
+      } else if (c === '\x04') {
+        this.close();
+        return;
+      } else if (c.toLowerCase() === 'r' && this.viewRefresh && !this.viewRefreshing) {
+        this.viewRefreshing = true;
+        const view = this.viewResolve;
+        void this.viewRefresh()
+          .then((lines) => { if (this.viewResolve === view) this.updateView(lines); })
+          .catch(() => { if (this.viewResolve === view) this.updateView(['Usage unavailable — r to retry']); })
+          .finally(() => { if (this.viewResolve === view) this.viewRefreshing = false; });
+      }
+    }
+  }
+
+  /** Select-mode keys: ↑/↓ (and j/k) move, Enter confirms, Ctrl+C cancels. */
+  private handleSelect(chars: string): void {
+    for (const c of chars) {
+      if (this.selectEsc) {
+        if (this.selectEscapeTimer) clearTimeout(this.selectEscapeTimer);
+        this.selectEscapeTimer = null;
+        this.selectEsc += c;
+        if (this.selectEsc === '\x1b[A') {
+          this.selectMove(-1);
+          this.selectEsc = '';
+        } else if (this.selectEsc === '\x1b[B') {
+          this.selectMove(1);
+          this.selectEsc = '';
+        } else if (!this.selectEsc.startsWith('\x1b[') || this.selectEsc.length > 3) {
+          this.selectEsc = ''; // stray escape — ignore
+        }
+        continue;
+      }
+      if (c === '\x1b') {
+        this.selectEsc = c;
+        this.selectEscapeTimer = setTimeout(() => this.selectFinish(null), 100);
+        continue;
+      }
+      if (c === '\r' || c === '\n') {
+        this.selectFinish(this.selectIndex);
+        return;
+      }
+      if (c === '\x03' || c === '\x04') {
+        this.selectFinish(null);
+        return;
+      }
+      if (c === 'j' || c === 'J') this.selectMove(1);
+      else if (c === 'k' || c === 'K') this.selectMove(-1);
+      // other keys are ignored while the menu is open
+    }
+  }
+
+  private selectMove(delta: number): void {
+    if (this.selectItems === null) return;
+    const n = this.selectItems.length;
+    this.selectIndex = Math.max(0, Math.min(n - 1, this.selectIndex + delta));
+    this.renderMenu();
+  }
+
+  private selectFinish(result: number | null): void {
+    const resolve = this.selectResolve;
+    const n = this.selectItems?.length ?? 0;
+    this.selectResolve = null;
+    this.selectItems = null;
+    this.selectEsc = '';
+    this.selectIndex = 0;
+    this.selectTop = 0;
+    if (this.selectEscapeTimer) clearTimeout(this.selectEscapeTimer);
+    this.selectEscapeTimer = null;
+    if (this.dockMenu) ui.closeMenu();
+    if (this.menuShown && !this.dockMenu && n > 0) {
+      const total = Math.min(n, MENU_HEIGHT) + 1; // items + hint line
+      process.stdout.write(`\x1b[${total}A\r\x1b[J`); // erase the menu in place
+    }
+    this.menuShown = false;
+    this.dockMenu = false;
+    resolve?.(result);
+  }
+
+  /** Draw the menu; re-renders in place by rewinding `total` lines when already shown. */
+  private renderMenu(): void {
+    if (this.selectItems === null) return;
+    const n = this.selectItems.length;
+    if (ui.menu(this.selectItems, this.selectIndex, this.selectTop, () => this.selectFinish(null))) {
+      this.dockMenu = true;
+      this.menuShown = true;
+      return;
+    }
+    const height = Math.min(n, MENU_HEIGHT);
+    if (this.selectIndex < this.selectTop) this.selectTop = this.selectIndex;
+    if (this.selectIndex >= this.selectTop + height) this.selectTop = this.selectIndex - height + 1;
+    const total = height + 1;
+    if (this.menuShown) process.stdout.write(`\x1b[${total}A`);
+    for (let i = 0; i < height; i++) {
+      process.stdout.write('\r\x1b[K' + this.renderMenuItem(this.selectTop + i) + '\n');
+    }
+    process.stdout.write('\r\x1b[K' + dim(`↑/↓ move · enter select · ctrl+c cancel  (${n} options)`) + '\n');
+    this.menuShown = true;
+  }
+
+  private renderMenuItem(i: number): string {
+    const label = this.selectItems![i];
+    return i === this.selectIndex ? `${violet('›')} ${bold(label)}` : `${dim('  ' + label)}`;
+  }
+}