subrouter-cli 0.0.0-stage → 0.1.0

package/src/ui.ts

@@ -0,0 +1,813 @@
+// ui.ts — sole terminal writer. The chat scrolls above a bottom-anchored composer;
+// pipes and very small terminals retain the simple line-oriented interface.
+
+import { stripVTControlCharacters } from 'node:util';
+import { ChatViewport, type ChatPosition } from './chatviewport.ts';
+
+const colorEnabled = (): boolean => process.stdout.isTTY === true && !process.env.NO_COLOR;
+const animated = colorEnabled;
+function wrap(text: string, code: string): string {
+  return colorEnabled() ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+export const dim = (t: string): string => wrap(t, '2');
+export const yellow = (t: string): string => wrap(t, '93');
+export const red = (t: string): string => wrap(t, '91');
+export const green = (t: string): string => wrap(t, '92');
+export const bold = (t: string): string => wrap(t, '1');
+// Subrouter accents: periwinkle blue (#8fa7ff) and violet (#a674ff).
+export const accent = (t: string): string => wrap(t, '38;2;143;167;255');
+export const violet = (t: string): string => wrap(t, '38;2;166;116;255');
+
+function usageStyle(text: string): string {
+  return text
+    .replace(/\b([a-z][\w-]*):/g, (label, name) => ['account', 'usage', 'quota'].includes(name) ? dim(label) : accent(bold(label)))
+    .replace(/([\d,]+) in \/ ([\d,]+) out/, (_, input, output) => `${accent(input)} ${dim('in')} / ${violet(output)} ${dim('out')}`)
+    .replace(/\b(\d+)%/g, (percent, value) => Number(value) < 15 ? red(bold(percent)) : Number(value) < 40 ? yellow(bold(percent)) : accent(bold(percent)))
+    .replace(/([\d,]+) rpm/, (_, value) => `${accent(value)} ${dim('rpm')}`)
+    .replace(/\b(day|week)\b/g, (label) => dim(label))
+    .replace(/\bunlimited\b/g, (value) => green(value))
+    .replace(/\$[\d,.]+/g, (value) => accent(value))
+    .replace(/\b(unknown|not reported)\b/g, (value) => yellow(value))
+    .replace(/ · /g, dim(' · '));
+}
+
+// Dock labels must stay on one physical row, even with wide model names/paths.
+function cells(c: string): number {
+  if (/\p{Mark}/u.test(c)) return 0;
+  const cp = c.codePointAt(0)!;
+  return cp >= 0x1100 && (cp <= 0x115f || cp >= 0x2e80 && cp <= 0xa4cf ||
+    cp >= 0xac00 && cp <= 0xd7a3 || cp >= 0xf900 && cp <= 0xfaff ||
+    cp >= 0xfe10 && cp <= 0xfe6f || cp >= 0xff00 && cp <= 0xff60 || cp >= 0x1f300) ? 2 : 1;
+}
+function clean(text: string): string {
+  return stripVTControlCharacters(text).replace(/[\x00-\x1f\x7f]/g, ' ');
+}
+function width(text: string): number {
+  return [...clean(text)].reduce((n, c) => n + cells(c), 0);
+}
+function fit(text: string, limit: number): string {
+  let out = '';
+  let used = 0;
+  for (const c of clean(text)) {
+    if (used + cells(c) > limit) break;
+    used += cells(c);
+    out += c;
+  }
+  return out;
+}
+
+export interface UiSink {
+  streamText(text: string): void;
+  streamReasoning(text: string): void;
+  endTurn(): void;
+  say(line: string): void;
+  warn(line: string): void;
+  error(line: string): void;
+  info(line: string): void;
+}
+
+class UiImpl implements UiSink {
+  private lineOpen = false;
+  private composerVisible = false;
+  private dock = false;
+  private dockRows = new Map<number, string>();
+  private chatRows = 0;
+  private chatRow = 1;
+  private chatColumn = 1;
+  private restoredWrap = false;
+  private viewport = new ChatViewport();
+  private model = '';
+  private prompt = '❯ ';
+  private text = '';
+  private cursor = 0;
+  private mode = 'ask before writes';
+  private effort = 'auto';
+  private attachmentNames: string[] = [];
+  private status = 'ready';
+  private queuedSteering: number | null = null;
+  private steeringMessages: string[] = [];
+  private usage = 'usage unavailable';
+  private menuItems: string[] | null = null;
+  private menuIndex = 0;
+  private menuTop = 0;
+  private menuCancel: (() => void) | null = null;
+  private menuHint = '↑/↓ move · enter select · esc/ctrl+c cancel';
+  private panelLines: string[] | null = null;
+  private panelTop = 0;
+  private panelCancel: (() => void) | null = null;
+  private limits = '';
+  private notice = '';
+  private commandMode = false;
+  private approvalTitle = '';
+  private approvalLines: string[] = [];
+  private approvalHint = '';
+  private approvalChoice = '';
+  private approvalCursor = 0;
+  private approvalTop = 0;
+  private agentActivity = '';
+  private thinkingText = '';
+  private toolCount = 0;
+  private previewTitle = '';
+  private previewLines: string[] = [];
+  private cardStart: ChatPosition | null = null;
+  private cardEnd: ChatPosition | null = null;
+
+  private approvalRows(): string[] {
+    const limit = Math.max(1, (process.stdout.columns || 80) - 5);
+    return this.approvalLines.flatMap((line) => {
+      const rows: string[] = [];
+      let part = '', used = 0;
+      for (const char of line) {
+        if (part && used + cells(char) > limit) { rows.push(part); part = ''; used = 0; }
+        part += char;
+        used += cells(char);
+      }
+      rows.push(part);
+      return rows;
+    });
+  }
+
+  private approvalHeight(): number {
+    if (!this.approvalTitle) return 0;
+    const base = this.menuItems || this.panelLines ? 3 : this.commandMode ? 4 : this.limits ? 6 : 5;
+    return Math.min(this.approvalRows().length + 3, Math.max(3, (process.stdout.rows || 24) - base - 2));
+  }
+  private approvalPageSize(): number {
+    const height = this.approvalHeight();
+    return height - (height > 3 ? 3 : 2);
+  }
+  private steeringHeight(): number {
+    if (!this.steeringMessages.length || this.menuItems || this.panelLines || this.commandMode) return 0;
+    const room = (process.stdout.rows || 24) - (this.limits ? 6 : 5) - this.approvalHeight() - 3;
+    return Math.min(4, this.steeringMessages.length + 1, Math.max(0, room));
+  }
+  private dockHeight(): number { return (this.menuItems || this.panelLines ? 3 : this.commandMode ? 4 : this.limits ? 6 : 5) + this.approvalHeight() + this.steeringHeight(); }
+
+  setCommandMode(active: boolean): void {
+    this.commandMode = active;
+    if (!this.dock) return;
+    this.reflow();
+    this.drawDock();
+  }
+
+  startTool(name: string, preview?: { title: string; lines: string[] }): void {
+    this.previewTitle = preview ? clean(preview.title) : '';
+    this.previewLines = preview ? preview.lines.map(clean) : [];
+    this.setAgentActivity(`● ${this.previewTitle || name}`);
+  }
+
+  preview(title: string, lines: string[]): void {
+    this.previewTitle = clean(title);
+    this.previewLines = lines.map(clean);
+    this.setAgentActivity(`● ${this.previewTitle} · generating`);
+  }
+
+  beginTurn(): void {
+    if (this.viewport.offset) this.scrollChat(-Infinity);
+    this.toolCount = 0;
+    if (this.cardStart && this.cardEnd) this.viewport.release(this.cardStart, this.cardEnd);
+    this.cardStart = this.cardEnd = null;
+    this.clearThinking();
+    this.previewTitle = '';
+    this.previewLines = [];
+    this.setAgentActivity('');
+  }
+
+  private setAgentActivity(text: string): void {
+    this.agentActivity = text;
+    if (!this.dock || !text) return;
+    const columns = Math.max(4, (process.stdout.columns || 80) - 1);
+    const title = clean(text);
+    const styled = title.includes('✓') ? green(bold(title)) : title.includes('⊘') ? yellow(title)
+      : title.includes(':') && /^\d+ tools? · /.test(title) ? red(title) : accent(bold(title));
+    const lines = [dim('  ') + styled, ...this.previewLines.map((line) =>
+      dim('  │ ') + (line.startsWith('+ ') ? green(line) : line.startsWith('− ') ? red(line) : dim(line)))];
+    const card = lines.join('\n') + '\n';
+    if (this.cardStart && this.cardEnd) {
+      this.viewport.replace(this.cardStart, this.cardEnd, card, columns);
+      this.paintChat();
+    } else {
+      this.endTurn();
+      this.cardStart = this.viewport.position();
+      this.writeChat(card);
+      this.cardEnd = this.viewport.position();
+    }
+  }
+
+  activity(label: string, text: string): boolean {
+    if (!this.dock) return false;
+    if (label === 'thinking') {
+      this.thinkingText = text === label ? '● thinking' : text;
+      this.drawThinking();
+      this.drawDock();
+    } else this.setAgentActivity(this.previewTitle ? `${text === label ? '●' : text.split(' ')[0]} ${this.previewTitle}` : text);
+    return true;
+  }
+
+  stopActivity(note: string): void {
+    if (!this.agentActivity || this.agentActivity.includes('✓') || this.agentActivity.includes('⊘')) return;
+    this.setAgentActivity(`⊘ ${this.previewTitle || 'tool'} · ${note}`);
+    if (this.cardStart && this.cardEnd) this.viewport.release(this.cardStart, this.cardEnd);
+    this.cardStart = this.cardEnd = null;
+  }
+
+  finishActivity(label: string, final: string): void {
+    if (label === 'thinking') {
+      this.clearThinking();
+      if (this.dock) this.drawDock();
+    } else {
+      if (final) this.toolCount++;
+      const result = this.previewTitle ? clean(final).replace(/\b(write_file|edit_file|make_dir|copy_path|move_path|remove_path|restore_file|run_command)\b/, () => this.previewTitle) : clean(final);
+      this.setAgentActivity(final ? `${this.toolCount} tool${this.toolCount === 1 ? '' : 's'} · ${result}` : '');
+      if (this.cardStart && this.cardEnd) this.viewport.release(this.cardStart, this.cardEnd);
+      this.cardStart = this.cardEnd = null;
+    }
+  }
+
+  commandNotice(text: string): void {
+    if (!this.dock) { this.info(text); return; }
+    this.notice = text;
+    this.drawDock();
+  }
+
+  openApproval(title: string, lines: string[], hint: string): void {
+    this.approvalTitle = clean(title);
+    this.approvalLines = lines.map(clean);
+    this.approvalHint = clean(hint);
+    this.approvalChoice = '';
+    this.approvalCursor = 0;
+    this.approvalTop = 0;
+    if (!this.dock) return;
+    this.reflow();
+    this.drawDock();
+  }
+
+  hasApproval(): boolean { return this.dock && !!this.approvalTitle; }
+
+  setApprovalChoice(text: string, cursor: number): boolean {
+    if (!this.hasApproval()) return false;
+    this.approvalChoice = clean(text);
+    this.approvalCursor = cursor;
+    this.drawDock();
+    return true;
+  }
+
+  scrollApproval(delta: number): void {
+    if (!this.hasApproval()) return;
+    const visible = this.approvalPageSize();
+    this.approvalTop = Math.max(0, Math.min(Math.max(0, this.approvalRows().length - visible), this.approvalTop + delta));
+    this.drawDock();
+  }
+
+  closeApproval(): void {
+    if (!this.approvalTitle) return;
+    this.approvalTitle = '';
+    this.approvalLines = [];
+    this.approvalHint = '';
+    this.approvalChoice = '';
+    this.approvalCursor = 0;
+    this.approvalTop = 0;
+    if (!this.dock) return;
+    this.reflow();
+    this.drawDock();
+  }
+
+  panel(lines: string[], cancel?: () => void): boolean {
+    if (!this.dock) return false;
+    if (cancel) this.panelCancel = cancel;
+    const columns = Math.max(4, (process.stdout.columns || 80) - 1);
+    this.panelLines = lines.flatMap((line) => {
+      const rows: string[] = [];
+      let text = clean(line);
+      while (width(text) > columns) {
+        const part = fit(text, columns);
+        rows.push(part);
+        text = text.slice(part.length);
+      }
+      rows.push(text);
+      return rows;
+    });
+    this.reflow();
+    this.drawDock();
+    return true;
+  }
+
+  scrollPanel(delta: number): void {
+    if (!this.panelLines) return;
+    this.panelTop = Math.max(0, Math.min(this.panelLines.length - 1, this.panelTop + delta));
+    this.drawDock();
+  }
+
+  closePanel(): void {
+    if (!this.panelLines) return;
+    this.panelLines = null;
+    this.panelCancel = null;
+    this.panelTop = 0;
+    this.reflow();
+    this.drawDock();
+  }
+
+  welcome(model: string, cwd: string): void {
+    if (!process.stdout.isTTY) {
+      this.say(`sub · model ${model} · cwd ${cwd} · type / for commands`);
+      return;
+    }
+    this.model = model;
+    this.openDock();
+    this.say(`  ${accent(bold('sub'))}  ${dim(cwd)}`);
+    this.say(`  ${dim('What are we building?  / commands · ctrl+v image')}`);
+    this.say('');
+  }
+
+  /** Reserve five bottom rows; keep shell history in scrollback (no alternate screen). */
+  private openDock(): void {
+    if (this.dock || !process.stdin.isTTY || !process.stdout.isTTY || (process.stdout.rows || 24) < 10) return;
+    this.dock = true;
+    this.dockRows.clear();
+    process.stdout.write('\n'.repeat(process.stdout.rows || 24));
+    this.chatRows = (process.stdout.rows || 24) - this.dockHeight();
+    this.chatRow = 1;
+    this.chatColumn = 1;
+    process.stdout.write(`\x1b[?1000h\x1b[?1006h\x1b[1;${this.chatRows}r\x1b[1;1H\x1b7`);
+    process.stdout.off('resize', this.onResize);
+    process.stdout.on('resize', this.onResize);
+    process.once('exit', this.onExit);
+    this.drawDock();
+  }
+
+  closeDock(): void {
+    process.stdout.off('resize', this.onResize);
+    process.off('exit', this.onExit);
+    if (!this.dock) return;
+    this.clearThinking();
+    this.dock = false;
+    this.dockRows.clear();
+    process.stdout.write(`\x1b[?1000l\x1b[?1006l\x1b[${this.chatRows + 1};1H\x1b[J\x1b[r\x1b[${process.stdout.rows || 24};1H\x1b[?25h`);
+    this.menuItems = null;
+    this.menuCancel = null;
+    this.panelLines = null;
+    this.panelCancel = null;
+  }
+
+  private onExit = (): void => this.closeDock();
+  private onResize = (): void => {
+    this.dockRows.clear();
+    if ((process.stdout.rows || 24) < 10) {
+      if (this.dock) {
+        const cancel = this.menuCancel ?? this.panelCancel;
+        this.closeDock();
+        cancel?.();
+        process.stdout.on('resize', this.onResize);
+        process.once('exit', this.onExit);
+      }
+      this.composer(this.model, this.prompt, this.text, this.cursor);
+      return;
+    }
+    if (!this.dock) {
+      this.clearComposer();
+      this.openDock();
+      this.paintChat();
+      return;
+    }
+    this.reflow();
+    this.paintChat();
+  };
+
+  private menuHeight(): number {
+    const lines = this.menuItems ?? this.panelLines;
+    return lines ? Math.min(lines.length, 8, Math.max(1, (process.stdout.rows || 24) - this.dockHeight() - 3)) + 1 : 0;
+  }
+
+  /** Scroll output clear of a newly opened popup before reducing its region. */
+  private reflow(): void {
+    const next = Math.max(2, (process.stdout.rows || 24) - this.dockHeight() - this.menuHeight());
+    if (next === this.chatRows) return; // width-only resize preserves the saved cursor
+    this.dockRows.clear();
+    process.stdout.write(`\x1b[${Math.min(this.chatRows + 1, process.stdout.rows || 24)};1H\x1b[J`);
+    if (this.chatRow > next) {
+      const shift = this.chatRow - next;
+      process.stdout.write(`\x1b[${this.chatRows};1H` + '\n'.repeat(shift));
+      this.chatRow -= shift;
+    }
+    this.chatRows = next;
+    this.chatRow = Math.min(next, this.chatRow);
+    this.chatColumn = Math.min(process.stdout.columns || 80, this.chatColumn);
+    process.stdout.write(`\x1b[1;${next}r\x1b[${this.chatRow};${this.chatColumn}H\x1b7`);
+    this.paintChat();
+  }
+
+  setStatus(status: string): void {
+    if (status !== 'ready') this.notice = '';
+    if (this.status === status) return;
+    this.status = status;
+    if (this.dock) this.drawDock();
+  }
+  setMode(mode: string): void {
+    this.mode = mode;
+    if (this.dock) this.drawDock();
+  }
+  setEffort(effort: string): void {
+    this.effort = effort;
+    if (this.dock) this.drawDock();
+  }
+  setSteering(queued: number | null, messages: string[] = []): void {
+    const oldHeight = this.dockHeight();
+    this.queuedSteering = queued;
+    this.steeringMessages = queued ? messages.map(clean) : [];
+    if (this.dock) {
+      if (oldHeight !== this.dockHeight()) this.reflow();
+      this.drawDock();
+    }
+  }
+  setAttachments(names: string[]): void {
+    this.attachmentNames = names.map(clean);
+    if (this.dock) this.drawDock();
+  }
+  setUsage(usage: string, limits = ''): void {
+    const oldHeight = this.dockHeight();
+    this.usage = usage;
+    this.limits = limits;
+    if (this.dock) {
+      if (oldHeight !== this.dockHeight()) this.reflow();
+      this.drawDock();
+    }
+  }
+
+  composer(model: string, prompt: string, text: string, cursor: number): void {
+    if (text !== this.text && text) this.notice = '';
+    this.model = model;
+    this.prompt = prompt;
+    this.text = text;
+    this.cursor = cursor;
+    if (this.dock) {
+      this.drawDock();
+      return;
+    }
+    this.clearComposer();
+    const columns = Math.max(8, (process.stdout.columns || 80) - 1);
+    const status = fit(`─ ${model} `, columns);
+    this.say(dim(status + '─'.repeat(Math.max(0, columns - width(status)))));
+    const available = Math.max(1, columns - 2);
+    const start = Math.max(0, cursor - available + 1);
+    const visible = text.slice(start, start + available);
+    this.line(prompt, visible, cursor - start);
+    this.composerVisible = true;
+  }
+
+  clearComposer(): void {
+    if (this.dock) {
+      this.text = '';
+      this.cursor = 0;
+      this.drawDock();
+      return;
+    }
+    if (!this.composerVisible) return;
+    process.stdout.write('\r\x1b[1A\x1b[J');
+    this.composerVisible = false;
+    this.lineOpen = false;
+  }
+
+  submitInput(prompt: string, text: string): void {
+    if (this.viewport.offset) this.scrollChat(-Infinity);
+    this.clearComposer();
+    this.say(prompt + text);
+  }
+
+  /** Command controls live below the input, outside the scrolling conversation. */
+  menu(items: string[], index: number, top: number, cancel?: () => void, hint = '↑/↓ move · enter select · esc/ctrl+c cancel'): boolean {
+    if (!this.dock) return false;
+    this.menuItems = items;
+    this.menuCancel = cancel ?? null;
+    this.menuHint = hint;
+    this.menuIndex = index;
+    this.menuTop = top;
+    this.reflow();
+    this.drawDock();
+    return true;
+  }
+  closeMenu(): void {
+    if (!this.dock || !this.menuItems) return;
+    this.dockRows.clear();
+    process.stdout.write(`\x1b[${this.chatRows + 1};1H\x1b[J`);
+    this.menuItems = null;
+    this.menuCancel = null;
+    this.reflow();
+    this.drawDock();
+  }
+
+  private drawDock(): void {
+    const columns = Math.max(4, (process.stdout.columns || 80) - 1);
+    let output = '';
+    const put = (row: number, text: string): void => {
+      if (this.dockRows.get(row) === text) return;
+      this.dockRows.set(row, text);
+      output += `\x1b[${row};1H` + text + '\x1b[K';
+    };
+    let row = this.chatRows + 1;
+    let approvalInputRow = 0;
+    if (this.approvalTitle) {
+      const available = Math.max(1, columns - 4);
+      const title = fit(` ${this.approvalTitle} `, Math.max(1, columns - 4));
+      put(row++, yellow('╭─') + yellow(bold(title)) + dim('─'.repeat(Math.max(0, columns - width(title) - 3))) + yellow('╮'));
+      const body = (text: string, marker = '│'): string => yellow('│ ') + text + ' '.repeat(Math.max(0, columns - width(text) - 3)) + yellow(marker);
+      const details = this.approvalRows();
+      const pageSize = this.approvalPageSize();
+      this.approvalTop = Math.min(this.approvalTop, Math.max(0, details.length - pageSize));
+      const visible = details.slice(this.approvalTop, this.approvalTop + pageSize);
+      for (let i = 0; i < visible.length; i++) {
+        const above = i === 0 && this.approvalTop > 0;
+        const below = i === visible.length - 1 && this.approvalTop + pageSize < details.length;
+        const marker = above && below ? '↕' : above ? '↑' : below ? '↓' : '│';
+        put(row++, body(fit(visible[i], available), marker));
+      }
+      if (this.approvalHeight() > 3) {
+        const hint = details.length > pageSize ? `${this.approvalHint} · PgUp/PgDn details` : this.approvalHint;
+        put(row++, body(dim(fit(hint, available))));
+      }
+      approvalInputRow = row;
+      const choice = fit(this.approvalChoice, Math.max(1, columns - 6));
+      put(row++, yellow('╰─ ') + accent('› ') + choice + ' '.repeat(Math.max(0, columns - width(choice) - 6)) + yellow('╯'));
+    }
+    const pendingRows = this.steeringHeight();
+    if (pendingRows) {
+      const count = pendingRows === 1 ? 1 : pendingRows - 1;
+      for (const message of this.steeringMessages.slice(-count)) {
+        const raw = '› ' + message;
+        const text = width(raw) > columns ? fit(raw, columns - 1) + '…' : raw;
+        put(row++, wrap(text + ' '.repeat(Math.max(0, columns - width(text))), '48;2;56;56;56;38;2;160;160;160'));
+      }
+      if (pendingRows > 1) {
+        const hidden = this.steeringMessages.length - count;
+        put(row++, dim(fit(`  ${hidden ? `${hidden} earlier · ` : ''}pending · sent at next model call`, columns)));
+      }
+    }
+    const absolute = this.mode === 'ABSOLUTE — NO APPROVALS';
+    const label = fit(absolute ? ` ABSOLUTE — NO APPROVALS · ${this.model} ─` : ` ${this.model} ─`, Math.max(0, columns - 2));
+    put(row++, dim('─'.repeat(Math.max(1, columns - width(label)))) + (absolute ? red(bold(label)) : accent(bold(label))));
+    const inputRow = row;
+    const prefix = fit(this.prompt, Math.max(2, columns - 8));
+    const available = Math.max(1, columns - width(prefix));
+    // Slice by cells around the caret, preserving the editor's UTF-16 cursor contract.
+    let start = this.cursor;
+    let before = '';
+    for (const c of [...this.text.slice(0, this.cursor)].reverse()) {
+      if (width(c + before) >= available) break;
+      before = c + before;
+      start -= c.length;
+    }
+    const visible = fit(this.text.slice(start), available);
+    put(row++, violet(prefix) + visible);
+    put(row++, dim('─'.repeat(columns)));
+    if (this.menuItems) {
+      const count = this.menuHeight() - 1;
+      if (this.menuIndex < this.menuTop) this.menuTop = this.menuIndex;
+      if (this.menuIndex >= this.menuTop + count) this.menuTop = this.menuIndex - count + 1;
+      for (let i = 0; i < count; i++) {
+        const index = this.menuTop + i;
+        const label = fit(this.menuItems[index] ?? '', columns - 2);
+        const styled = label.replace(/^(\/\w+)(\s+)(.*)$/, (_, command, gap, description) => accent(command) + gap + dim(description));
+        put(row++, index === this.menuIndex ? violet('› ') + accent(bold(label)) : '  ' + styled);
+      }
+      put(row++, dim(fit(this.menuHint, columns)));
+    } else if (this.panelLines) {
+      const count = this.menuHeight() - 1;
+      this.panelTop = Math.min(this.panelTop, Math.max(0, this.panelLines.length - count));
+      for (let i = 0; i < count; i++) {
+        const index = this.panelTop + i;
+        const text = fit(this.panelLines[index] ?? '', columns);
+        put(row++, index === 0 ? accent(bold(text)) : text.startsWith('  ') ? text : usageStyle(text));
+      }
+      put(row++, dim(fit('↑/↓ scroll · r refresh · enter/esc close', columns)));
+    }
+    if (this.menuItems || this.panelLines) {
+      const caretRow = approvalInputRow || inputRow;
+      const caretColumn = approvalInputRow ? Math.min(columns, 5 + Math.min(this.approvalCursor, width(this.approvalChoice)) + 1)
+        : Math.min(columns, width(prefix) + width(before) + 1);
+      process.stdout.write(output + `\x1b[${caretRow};${caretColumn}H`);
+      return;
+    }
+    const footerStatus = this.status.startsWith('thinking') ? 'ctrl+c stop' : this.status;
+    const activity = this.viewport.offset ? 'history · PgDn to live' : footerStatus;
+    const attachments = this.attachmentNames.length ? `${this.attachmentNames.length} image${this.attachmentNames.length === 1 ? '' : 's'} attached · ${this.attachmentNames.join(' · ')}` : '';
+    const steering = this.queuedSteering === null ? '' : `${this.queuedSteering ? `${this.queuedSteering} steering queued` : 'Enter to steer'} · ${activity}`;
+    const status = this.notice || (this.commandMode ? this.status : attachments || steering || `${this.mode} · effort ${this.effort} · ${activity}`);
+    const statusText = fit(status, columns);
+    put(row++, this.notice || attachments && !this.commandMode ? accent(statusText) : statusText
+      .replace(this.mode, absolute ? red(bold(this.mode)) : this.mode === 'guarded auto' || this.mode === 'auto mode on' ? yellow(this.mode) : dim(this.mode))
+      .replace(`effort ${this.effort}`, violet(`effort ${this.effort}`))
+      .replace(/\d+ steering queued|Enter to steer/, (label) => violet(label))
+      .replace(this.status, this.status === 'ready' ? green(this.status) : yellow(this.status))
+      .replace(/ · /g, dim(' · ')));
+    if (!this.commandMode) {
+      put(row++, usageStyle(fit(this.usage, columns)));
+      if (this.limits) put(row, usageStyle(fit(this.limits, columns)));
+    }
+    const caretRow = approvalInputRow || inputRow;
+    const caretColumn = approvalInputRow ? Math.min(columns, 5 + Math.min(this.approvalCursor, width(this.approvalChoice)) + 1)
+      : Math.min(columns, width(prefix) + width(before) + 1);
+    process.stdout.write(output + `\x1b[${caretRow};${caretColumn}H`);
+  }
+
+  scrollChat(delta: number): void {
+    if (!this.dock) return;
+    this.viewport.scroll(delta, process.stdout.columns || 80, this.chatRows);
+    this.paintChat();
+  }
+
+  private drawThinking(): void {
+    if (!this.dock || this.viewport.offset || !this.thinkingText || this.chatColumn !== 1) return;
+    const columns = Math.max(1, (process.stdout.columns || 80) - 1);
+    const text = fit(this.thinkingText, columns);
+    const space = text.indexOf(' ');
+    const styled = space < 0 ? dim(text) : violet(text.slice(0, space)) + dim(text.slice(space));
+    // Transient overlay: never enters history or consumes a line on each frame.
+    process.stdout.write(`\x1b[${this.chatRow};1H\x1b[K` + styled);
+  }
+
+  private clearThinking(): void {
+    if (this.thinkingText && this.dock && !this.viewport.offset && this.chatColumn === 1) {
+      process.stdout.write(`\x1b[${this.chatRow};1H\x1b[K`);
+    }
+    this.thinkingText = '';
+  }
+
+  private paintChat(): void {
+    if (!this.dock) return;
+    const columns = process.stdout.columns || 80;
+    const lines = this.viewport.visible(columns, this.chatRows);
+    for (let row = 1; row <= this.chatRows; row++)
+      process.stdout.write(`\x1b[${row};1H\x1b[2K` + (lines[row - 1] ?? ''));
+    const caret = this.viewport.caret(columns, this.chatRows);
+    this.chatRow = caret.row;
+    this.chatColumn = caret.column;
+    this.restoredWrap = caret.column > columns;
+    process.stdout.write(`\x1b[${this.chatRow};${Math.min(columns, this.chatColumn)}H\x1b7`);
+    this.drawThinking();
+    this.drawDock();
+  }
+
+  chatPosition(): ChatPosition { return this.viewport.position(); }
+
+  removeChat(start: ChatPosition, end: ChatPosition): void {
+    this.clearThinking();
+    this.viewport.remove(start, end);
+    this.viewport.release(start, end);
+    if (this.dock) this.paintChat();
+  }
+
+  clearChat(): void {
+    this.clearThinking();
+    this.cardStart = this.cardEnd = null;
+    this.agentActivity = '';
+    this.viewport.clear();
+    if (!this.dock) return;
+    for (let row = 1; row <= this.chatRows; row++) process.stdout.write(`\x1b[${row};1H\x1b[2K`);
+    this.chatRow = this.chatColumn = 1;
+    this.restoredWrap = false;
+    this.lineOpen = false;
+    process.stdout.write('\x1b[1;1H\x1b7');
+    this.drawDock();
+  }
+
+  /** DEC save/restore tracks the chat cursor independently of the input caret. */
+  private writeChat(text: string): void {
+    this.clearThinking();
+    this.viewport.append(text, process.stdout.columns || 80);
+    if (this.dock && this.viewport.offset) {
+      this.paintChat();
+      return;
+    }
+    if (!this.dock) {
+      process.stdout.write(text);
+      return;
+    }
+    const first = stripVTControlCharacters(text)[0];
+    const wrap = this.restoredWrap && first && first !== '\n' && first !== '\r' ? '\r\n' : '';
+    if (first) this.restoredWrap = false;
+    process.stdout.write('\x1b8' + wrap + text + '\x1b7');
+    const columns = process.stdout.columns || 80;
+    for (const c of stripVTControlCharacters(wrap + text)) {
+      if (c === '\r') this.chatColumn = 1;
+      else if (c === '\n') { this.chatRow = Math.min(this.chatRows, this.chatRow + 1); this.chatColumn = 1; }
+      else if (c >= ' ') {
+        if (this.chatColumn > columns) { this.chatRow = Math.min(this.chatRows, this.chatRow + 1); this.chatColumn = 1; }
+        this.chatColumn += cells(c);
+      }
+    }
+    this.drawDock();
+  }
+
+  streamText(text: string): void {
+    this.writeChat(text);
+    this.lineOpen = true;
+  }
+  streamReasoning(text: string): void {
+    this.writeChat(dim(text));
+    this.lineOpen = true;
+  }
+  endTurn(): void {
+    if (this.lineOpen) this.writeChat('\n');
+    this.lineOpen = false;
+  }
+  clearLine(): void {
+    if (!this.dock) this.clearComposer();
+    this.writeChat('\r\x1b[K');
+    this.lineOpen = false;
+  }
+  rewrite(text: string): void {
+    this.clearLine();
+    this.writeChat(text);
+    this.lineOpen = !text.endsWith('\n');
+  }
+  line(prompt: string, text: string, cursor: number): void {
+    if (this.dock) {
+      this.prompt = prompt;
+      this.text = text;
+      this.cursor = cursor;
+      this.drawDock();
+      return;
+    }
+    this.clearLine();
+    process.stdout.write(prompt + text);
+    const back = text.length - cursor;
+    if (back > 0) process.stdout.write(`\x1b[${back}D`);
+  }
+  say(line: string): void {
+    if (!this.dock) this.clearComposer();
+    this.writeChat(line + '\n');
+    this.lineOpen = false;
+  }
+  warn(line: string): void { this.say(yellow('! ') + line); }
+  error(line: string): void { this.say(red('× ') + line); }
+  info(line: string): void { this.say(dim('· ') + line); }
+  spinner(text: string): Spinner { return new Spinner(text, this); }
+}
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/** Delayed activity indicator; never animates in pipes or under NO_COLOR. */
+export class Spinner {
+  private text: string;
+  private sink: UiImpl;
+  private timer: NodeJS.Timeout | null = null;
+  private frame = 0;
+  private shown = false;
+  private done = false;
+  private live = false;
+
+  constructor(text: string, sink: UiImpl) {
+    this.text = text;
+    this.sink = sink;
+  }
+  start(delayMs = 300): this {
+    this.live = this.sink.activity(this.text, this.text);
+    if (!animated()) {
+      if (this.text && !this.live) this.sink.info(this.text);
+      return this;
+    }
+    this.arm(delayMs);
+    return this;
+  }
+  pause(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  resume(): void {
+    if (!animated() || this.done || this.timer) return;
+    this.arm(150);
+  }
+  private arm(delayMs: number): void {
+    this.timer = setTimeout(() => {
+      this.shown = true;
+      this.tick();
+      this.timer = setInterval(() => this.tick(), 100);
+    }, delayMs);
+  }
+  private tick(): void {
+    const text = SPINNER_FRAMES[this.frame++ % SPINNER_FRAMES.length] + ' ' + this.text;
+    if (this.live) this.sink.activity(this.text, text);
+    else this.sink.rewrite(text);
+  }
+  stop(final: string, keepActivity = false): void {
+    if (this.done) return;
+    this.done = true;
+    this.pause();
+    if (keepActivity) return;
+    if (this.live) {
+      this.sink.finishActivity(this.text, final);
+      return;
+    }
+    if (!animated()) {
+      if (final !== '') this.sink.say(final);
+      return;
+    }
+    if (final === '') this.sink.clearLine();
+    else if (this.shown) this.sink.rewrite(final + '\n');
+    else this.sink.say(final);
+  }
+}
+
+export const ui: UiImpl = new UiImpl();