@semalt-ai/code 1.8.1 → 1.8.4

package/lib/ui/input-field.js

@@ -4,6 +4,8 @@ const EventEmitter = require('events');
 const readline = require('readline');
 
 const { RST, DIM, FG_CYAN, FG_GREEN, FG_YELLOW } = require('./ansi');
+const { stripAnsi, termWidth } = require('./utils');
+const writer = require('./writer');
 
 const SLASH_CMDS = [
   '/help','/file','/new','/model','/models','/shell','/compact',
@@ -107,10 +109,15 @@ function parseKeySequence(buf) {
 // ─── InputField ───────────────────────────────────────────────────────────────
 
 class InputField extends EventEmitter {
-  constructor(layout, chatHistory) {
+  constructor(layout, chatHistory, onChange) {
     super();
     this._layout = layout;
     this._chatHistory = chatHistory;
+    this._onChange = typeof onChange === 'function' ? onChange : () => {};
+    // Cached render output — re-computed on every _render()/_renderHints()
+    // call. Consumed by the UI orchestrator to build the live region.
+    this._inputLines = [`${DIM}›${RST}`];
+    this._hintsText = '';
     this._chars = [];
     this._cursor = 0;
     this._disabled = false;
@@ -122,15 +129,15 @@ class InputField extends EventEmitter {
     this._historyIdx = -1;
     this._draft = '';
     this._selectCapture = null;
-    this._blink = true;
     this._idle = false;
     this._idleTimer = null;
-    this._cursorHidden = false;
-    this._blinkTimer = setInterval(() => {
-      if (this._idle || this._disabled) return;
-      this._blink = !this._blink;
-      if (!this._pasteMode) this._render();
-    }, 500);
+    // Caret position within the rendered input lines, consumed by the
+    // orchestrator to position the OS cursor after every live-region
+    // redraw. { line, col } in display columns, or null when the caret
+    // should stay hidden (disabled, navigation capture). The terminal's
+    // native blinking cursor IS the caret — no custom rendering effect
+    // is applied to the character under it.
+    this._caretPosition = null;
     this._escBuf = null;
     this._escTimer = null;
     this._utf8Buf = null;
@@ -152,13 +159,27 @@ class InputField extends EventEmitter {
     this._savedChars = null;
     this._savedCursor = 0;
 
+    // Bash-style exit-arm state: first Ctrl+C on empty input arms, second
+    // Ctrl+C within the window exits. Timer is unref'd so a lingering arm
+    // never keeps the process alive.
+    this._exitArmed = false;
+    this._exitArmTimer = null;
+
     this._onData = (chunk) => this._handleData(chunk);
     if (process.stdin.isTTY) {
       process.stdin.setRawMode(true);
       process.stdin.resume();
-      process.stdout.write('\x1b[?2004h');  // bracketed paste
-      process.stdout.write('\x1b[>4;2m');   // xterm modifyOtherKeys level 2
-      process.stdout.write('\x1b[>1u');     // kitty keyboard protocol
+      // Terminal-mode toggles go through the writer queue so they can't
+      // land inside another task's compound write. Each is a tiny escape
+      // that only toggles state — no display content.
+      writer.enqueue(() => {
+        // audit: allowed — terminal-mode raw escapes inside writer.enqueue (sanctioned escape hatch).
+        try {
+          process.stdout.write('\x1b[?2004h');  // bracketed paste
+          process.stdout.write('\x1b[>4;2m');   // xterm modifyOtherKeys level 2
+          process.stdout.write('\x1b[>1u');     // kitty keyboard protocol
+        } catch {}
+      });
       process.stdin.on('data', this._onData);
       this._idleTimer = setTimeout(() => this._goIdle(), 0);
     }
@@ -185,20 +206,6 @@ class InputField extends EventEmitter {
     });
   }
 
-  hideCursor() {
-    if (!this._cursorHidden) {
-      this._cursorHidden = true;
-      process.stdout.write('\x1b[?25l');
-    }
-  }
-
-  showCursor() {
-    if (this._cursorHidden) {
-      this._cursorHidden = false;
-      process.stdout.write('\x1b[?25h');
-    }
-  }
-
   captureNavigation(handler) {
     this._navCapture = handler;
     this._navSearchMode = false;
@@ -206,37 +213,33 @@ class InputField extends EventEmitter {
     this._deleteLine();
     this._renderHints();
     this._render();
-    this.hideCursor();
   }
 
   releaseNavigation() {
     this._navCapture = null;
     this._navSearchMode = false;
     this._navSearchQuery = '';
-    this.showCursor();
     this._renderHints();
     this._render();
   }
 
-  // Stop all periodic stdout writes so the terminal viewport can scroll freely.
+  // Pause status-bar ticking so the terminal viewport can scroll freely.
+  // The OS cursor is managed by the writer based on caret state, not here —
+  // it stays visible at the input caret whenever getCaretPosition() is
+  // non-null.
   _goIdle() {
     this._idle = true;
     clearTimeout(this._idleTimer);
     this._idleTimer = null;
-    this.hideCursor();
     this.emit('idle');
   }
 
-  // Resume periodic writes and restart the idle countdown.
   _goActive() {
     const wasIdle = this._idle;
     this._idle = false;
     clearTimeout(this._idleTimer);
     this._idleTimer = setTimeout(() => this._goIdle(), 0);
-    if (wasIdle) {
-      this.showCursor();
-      this.emit('active');
-    }
+    if (wasIdle) this.emit('active');
   }
 
   setSearchItems(items) {
@@ -752,6 +755,10 @@ class InputField extends EventEmitter {
 
     if (key !== 'tab') this._clearHint();
 
+    // Any non-Ctrl+C key cancels an armed exit — a letter, arrow, Tab,
+    // Backspace, or Enter all revert the hints row to normal.
+    if (key !== 'ctrl+c') this._clearExitArm();
+
     switch (key) {
       case 'shift+enter':  this._insertChar('\n'); this._render(); break;
       case 'enter': {
@@ -791,9 +798,9 @@ class InputField extends EventEmitter {
       case 'ctrl+l':       this._chatHistory.clearMessages(); break;
       case 'ctrl+r':       this._enterSearchMode(); break;
       case 'ctrl+o':       if (this._navCapture) this._navCapture('expand'); else this.emit('expand'); break;
-      case 'ctrl+g':
-      case 'ctrl+c':
-      case 'ctrl+d':       this.emit('interrupt'); break;
+      case 'ctrl+g':       this.emit('interrupt'); break;
+      case 'ctrl+c':       this._onCtrlC(); break;
+      case 'ctrl+d':       this._onCtrlD(); break;
       case 'ctrl+right':
       case 'alt+f':        this._jumpWordForward(); this._render(); break;
       case 'ctrl+left':
@@ -816,6 +823,58 @@ class InputField extends EventEmitter {
     }
   }
 
+  // ── Bash-style Ctrl+C / Ctrl+D ───────────────────────────────────────────────
+  //
+  // Ctrl+C is context-dependent. _handleKey is only reached when the agent is
+  // idle (agent-active Ctrl+C is handled directly in _handleData's disabled
+  // branch), so these helpers only cover the idle cases: clear a non-empty
+  // line, or arm/confirm exit on empty input. Ctrl+D mirrors readline: exit
+  // only when the line is empty, otherwise do nothing.
+  _onCtrlC() {
+    if (this._chars.length > 0) {
+      // Non-empty line: clear it and DO NOT arm. A subsequent Ctrl+C on the
+      // newly-empty line starts the arm sequence from scratch.
+      this._deleteLine();
+      this._clearExitArm();
+      this._render();
+      return;
+    }
+    if (this._exitArmed) {
+      this._clearExitArm();
+      this.emit('interrupt');
+      return;
+    }
+    this._armExit();
+  }
+
+  _onCtrlD() {
+    if (this._chars.length > 0) return;
+    this.emit('interrupt');
+  }
+
+  _armExit() {
+    this._exitArmed = true;
+    if (this._exitArmTimer) clearTimeout(this._exitArmTimer);
+    this._exitArmTimer = setTimeout(() => {
+      this._exitArmed = false;
+      this._exitArmTimer = null;
+      this._renderHints();
+    }, 2000);
+    // Don't let a pending arm keep the event loop alive.
+    if (this._exitArmTimer.unref) this._exitArmTimer.unref();
+    this._renderHints();
+  }
+
+  _clearExitArm() {
+    if (!this._exitArmed && !this._exitArmTimer) return;
+    this._exitArmed = false;
+    if (this._exitArmTimer) {
+      clearTimeout(this._exitArmTimer);
+      this._exitArmTimer = null;
+    }
+    this._renderHints();
+  }
+
   // ── Raw stdin byte handler ───────────────────────────────────────────────────
 
   _handleData(chunk) {
@@ -836,8 +895,13 @@ class InputField extends EventEmitter {
     if (this._selectCapture) { this._processBuf(buf, false); return; }
     if (this._navCapture) { this._processBuf(buf, false); return; }
     if (this._disabled) {
-      if (buf[0] === 0x03 || buf[0] === 0x04) {
-        this.emit('interrupt');
+      if (buf[0] === 0x03) {
+        // Ctrl+C while agent is active: interrupt the operation and reset
+        // any pending exit-arm so the next idle Ctrl+C starts a fresh arm.
+        this._clearExitArm();
+        this.emit('abort');
+      } else if (buf[0] === 0x04) {
+        // Ctrl+D while agent active: ignored (bash readline semantics).
       } else if (buf[0] === 0x0f) {
         this.emit('expand');
       } else if (buf[0] === 0x1b && buf.length === 1) {
@@ -974,6 +1038,10 @@ class InputField extends EventEmitter {
           if (cp !== undefined && cp >= 0x20) {
             const ch = String.fromCodePoint(cp);
             this._insertChar(ch);
+            // Printable chars bypass _handleKey — explicitly cancel an armed
+            // exit so typing a letter behaves like bash (any keystroke except
+            // a second Ctrl+C reverts the hint).
+            this._clearExitArm();
             if (!this._pasteMode) {
               this._clearHint();
               this._render();
@@ -995,18 +1063,18 @@ class InputField extends EventEmitter {
   }
 
   // ── Hints row ────────────────────────────────────────────────────────────────
+  //
+  // Build the hints-line string and publish the updated live region. No
+  // direct stdout writes here — the shared writer owns the terminal.
 
   _renderHints() {
-    const layout = this._layout;
-    if (!layout || !layout.hintsRow) return;
-    const row = layout.hintsRow;
-    const cols = layout.cols;
-
     let text;
-    if (this._searchMode) {
+    if (this._exitArmed) {
+      text = `${FG_YELLOW}Press Ctrl+C again to exit${RST}`;
+    } else if (this._searchMode) {
       text = `${FG_YELLOW}ctrl+r${RST}${DIM} next match  ${RST}${FG_YELLOW}esc${RST}${DIM} cancel search${RST}`;
     } else if (this._disabled) {
-      text = `${FG_YELLOW}esc${RST}${DIM} interrupt${RST}`;
+      text = `${FG_YELLOW}esc${RST}${DIM}/${RST}${FG_YELLOW}ctrl+c${RST}${DIM} interrupt${RST}`;
     } else if (this._navCapture) {
       if (this._navSearchMode) {
         text = `${FG_YELLOW}search:${RST} ${FG_CYAN}'${this._navSearchQuery}'${RST}  ${DIM}↑↓ navigate  enter select  esc clear${RST}`;
@@ -1017,42 +1085,46 @@ class InputField extends EventEmitter {
       text = `${DIM}↑↓ history  ${RST}${FG_CYAN}ctrl+r${RST}${DIM} search  ${RST}${FG_CYAN}ctrl+c${RST}${DIM} cancel${RST}`;
     }
 
-    // Use DECSC/DECRC so the cursor is restored after drawing (keeps streaming
-    // tokens anchored at historyRows when the blink timer calls this).
-    process.stdout.write(`\x1b7\x1b[${row};1H\x1b[2K${text}`);
-    const visLen = text.replace(/\x1b\[[^m]*m/g, '').length;
-    if (visLen < cols) process.stdout.write(' '.repeat(cols - visLen));
-    process.stdout.write('\x1b8');
+    this._hintsText = text;
+    this._notify();
   }
 
+  // Expose the last-computed hints line for the orchestrator.
+  renderHintsLine() { return this._hintsText || ''; }
+
   // ── Render ───────────────────────────────────────────────────────────────────
+  //
+  // Compute the rendered input rows and cache them in this._inputLines for
+  // the UI orchestrator. Then _notify() — the orchestrator pulls the lines
+  // and repaints the live region.
+  //
+  // The caret is the terminal's native blinking cursor, positioned by the
+  // writer after each redraw using this._caretPosition. Rendering here does
+  // not embed any visual cursor into the text — the inverted/underlined
+  // simulation was removed because it duplicated the native cursor and
+  // caused a phantom "below hints" blink when the OS cursor wasn't moved
+  // up to the input row after a frame.
 
   _render() {
-    const layout = this._layout;
-    const cols = layout.cols;
-
     if (this._disabled) {
       if (this._inputHeight !== 1) {
         this._inputHeight = 1;
-        layout.setInputHeight(1);
+        this._layout.setInputHeight(1);
       }
-      const baseRow = layout.inputRow;
-      // DECSC/DECRC keeps the cursor in the history scroll region so streaming
-      // tokens written after this blink-timer redraw land at the right row.
-      process.stdout.write(`\x1b7\x1b[${baseRow};1H\x1b[2K${DIM}›${RST}`);
-      process.stdout.write(' '.repeat(Math.max(0, cols - 1)));
-      process.stdout.write('\x1b8');
+      this._inputLines = [`${DIM}›${RST}`];
+      this._caretPosition = null;
+      this._notify();
       return;
     }
 
     if (this._navCapture) {
       if (this._inputHeight !== 1) {
         this._inputHeight = 1;
-        layout.setInputHeight(1);
+        this._layout.setInputHeight(1);
       }
-      const baseRow = layout.inputRow;
-      process.stdout.write(`\x1b[${baseRow};1H\x1b[2K${DIM}›${RST}`);
-      process.stdout.write(' '.repeat(Math.max(0, cols - 1)));
+      this._inputLines = [`${DIM}›${RST}`];
+      this._caretPosition = null;
+      this._notify();
       return;
     }
 
@@ -1060,20 +1132,17 @@ class InputField extends EventEmitter {
     if (this._searchMode) {
       if (this._inputHeight !== 1) {
         this._inputHeight = 1;
-        layout.setInputHeight(1);
+        this._layout.setInputHeight(1);
       }
-      const baseRow = layout.inputRow;
       const noMatch = this._searchQuery && this._searchMatchIdx === -1;
       const queryColor = noMatch ? '\x1b[38;5;203m' : FG_CYAN;
       const prefix = `${DIM}(search)${RST} ${queryColor}'${this._searchQuery}'${RST}${DIM}:${RST} `;
       const matched = this._chars.join('');
 
-      // Type label
       const typeLabel = this._searchMatchType
         ? `${DIM}[${this._searchMatchType}]${RST} `
         : '';
 
-      // Highlight the matching part (case-insensitive)
       let displayMatch;
       const matchedLow = matched.toLowerCase();
       const qLow = this._searchQuery.toLowerCase();
@@ -1087,10 +1156,14 @@ class InputField extends EventEmitter {
         displayMatch = matched;
       }
 
-      const line = prefix + typeLabel + displayMatch;
-      process.stdout.write(`\x1b[${baseRow};1H\x1b[2K${line}`);
-      const visLen = line.replace(/\x1b\[[^m]*m/g, '').length;
-      if (visLen < cols) process.stdout.write(' '.repeat(cols - visLen));
+      const rendered = prefix + typeLabel + displayMatch;
+      this._inputLines = [rendered];
+      // Put the OS cursor at the end of the visible text so the user sees
+      // where their next keystroke will land (they're editing _searchQuery
+      // in the prefix, but by design the row gets rewritten with the match
+      // on every keystroke; trailing position is the least surprising).
+      this._caretPosition = { line: 0, col: termWidth(stripAnsi(rendered)) };
+      this._notify();
       return;
     }
 
@@ -1101,13 +1174,7 @@ class InputField extends EventEmitter {
     const needed = Math.min(5, newlineCount + 1);
     if (needed !== this._inputHeight) {
       this._inputHeight = needed;
-      layout.setInputHeight(needed);
-    }
-
-    const baseRow = layout.inputRow;
-
-    for (let r = baseRow; r < baseRow + this._inputHeight; r++) {
-      process.stdout.write(`\x1b[${r};1H\x1b[2K`);
+      this._layout.setInputHeight(needed);
     }
 
     const PREFIX     = '\x1b[36m › \x1b[0m';
@@ -1129,45 +1196,71 @@ class InputField extends EventEmitter {
       pos += lines[li].length + 1;
     }
 
+    const out = [];
     const renderCount = Math.min(lines.length, this._inputHeight);
     for (let li = 0; li < renderCount; li++) {
-      const r         = baseRow + li;
       const lineChars = lines[li];
-
-      let lineStr;
-      if (li === cursorLine) {
-        const leftStr  = lineChars.slice(0, cursorCol).join('');
-        const cursorCh = cursorCol < lineChars.length ? lineChars[cursorCol] : ' ';
-        const afterStr = lineChars.slice(cursorCol + (cursorCol < lineChars.length ? 1 : 0)).join('');
-        const cursorEsc = this._blink
-          ? `\x1b[7m${cursorCh}\x1b[27m`
-          : `\x1b[4m${cursorCh}\x1b[24m`;
-        lineStr = leftStr + cursorEsc + afterStr;
-      } else {
-        lineStr = lineChars.join('');
-      }
-
+      const lineStr = lineChars.join('');
       const leadIn  = li === 0 ? PREFIX : ' '.repeat(PREFIX_LEN);
       const hintStr = (li === 0 && this._hint) ? `${DIM}${this._hint}${RST}` : '';
-      const visLen  = PREFIX_LEN + lineChars.length + (li === 0 ? this._hint.length : 0);
-      const pad     = visLen < cols ? ' '.repeat(cols - visLen) : '';
-
-      process.stdout.write(`\x1b[${r};1H` + leadIn + lineStr + hintStr + pad);
+      out.push(leadIn + lineStr + hintStr);
     }
+
+    if (out.length === 0) out.push(PREFIX);
+    this._inputLines = out;
+
+    // Caret sits at PREFIX_LEN + display-width of the chars on the caret
+    // line that precede it. termWidth handles double-width glyphs (CJK,
+    // emoji) so the column is correct even when the input contains them.
+    // If the caret row was dropped because _inputHeight clamped the render
+    // to fewer rows, keep the caret on the last rendered row at its end —
+    // the text that overflowed isn't visible anyway.
+    const caretLineIdx = Math.min(cursorLine, renderCount - 1);
+    const caretLineChars = lines[caretLineIdx] || [];
+    const beforeCaret = caretLineIdx === cursorLine
+      ? caretLineChars.slice(0, cursorCol).join('')
+      : caretLineChars.join('');
+    this._caretPosition = {
+      line: caretLineIdx,
+      col: PREFIX_LEN + termWidth(beforeCaret),
+    };
+    this._notify();
+  }
+
+  // Expose the last-computed input lines for the orchestrator.
+  renderInputLines() { return this._inputLines.slice(); }
+
+  // Expose the caret position inside the most recently rendered input rows:
+  // { line, col } — `line` is the 0-indexed input row and `col` is the
+  // 0-indexed display column (PREFIX width + termWidth of preceding chars).
+  // Returns null when no caret should appear (disabled / nav capture).
+  getCaretPosition() {
+    return this._caretPosition ? { ...this._caretPosition } : null;
+  }
+
+  _notify() {
+    try { this._onChange(); } catch {}
   }
 
   // ── Destroy ──────────────────────────────────────────────────────────────────
 
   destroy() {
-    if (this._blinkTimer) { clearInterval(this._blinkTimer); this._blinkTimer = null; }
-    if (this._escTimer)   { clearTimeout(this._escTimer);    this._escTimer = null; }
-    if (this._idleTimer)  { clearTimeout(this._idleTimer);   this._idleTimer = null; }
+    if (this._escTimer)     { clearTimeout(this._escTimer);    this._escTimer = null; }
+    if (this._idleTimer)    { clearTimeout(this._idleTimer);   this._idleTimer = null; }
+    if (this._exitArmTimer) { clearTimeout(this._exitArmTimer); this._exitArmTimer = null; }
     if (process.stdin.isTTY) {
       process.stdin.removeListener('data', this._onData);
-      this._cursorHidden = true; this.showCursor();   // restore cursor visibility
-      process.stdout.write('\x1b[<u');     // pop kitty keyboard protocol
-      process.stdout.write('\x1b[>4;0m'); // reset modifyOtherKeys
-      process.stdout.write('\x1b[?2004l'); // disable bracketed paste
+      // Terminal-mode pops must run in queue order so they don't race with
+      // a pending live-region redraw on shutdown.
+      writer.enqueue(() => {
+        // audit: allowed — terminal-mode raw escapes inside writer.enqueue (sanctioned escape hatch).
+        try {
+          process.stdout.write('\x1b[?25h');   // show cursor
+          process.stdout.write('\x1b[<u');     // pop kitty keyboard protocol
+          process.stdout.write('\x1b[>4;0m');  // reset modifyOtherKeys
+          process.stdout.write('\x1b[?2004l'); // disable bracketed paste
+        } catch {}
+      });
       process.stdin.setRawMode(false);    // restore cooked mode so mouse works again
     }
   }

package/lib/ui/layout.js

@@ -43,8 +43,6 @@ class LayoutManager {
     if (this._heightChangeCb) this._heightChangeCb();
   }
 
-  moveTo(row, col) { process.stdout.write(`\x1b[${row};${col || 1}H`); }
-
   destroy() {
     process.stdout.removeListener('resize', this._handler);
   }

package/lib/ui/messages.js

@@ -0,0 +1,44 @@
+'use strict';
+
+// Thin wrappers over writer.scrollback for the four primary error categories
+// and three neutral system-line glyphs. All composition + colour comes from
+// theme.js so the palette stays consistent with the rest of the chrome. Each
+// helper returns the writer.scrollback promise so callers can `await` if
+// they need the line flushed before exit.
+
+const { UI_THEME, UI_ICONS } = require('./theme');
+const { RST } = require('./ansi');
+const writer = require('./writer');
+
+const ICON_ERROR   = `${UI_THEME.error}${UI_ICONS.error}${RST}`;
+const ICON_SUCCESS = `${UI_THEME.success}${UI_ICONS.success}${RST}`;
+const ICON_WARN    = `${UI_THEME.warning}${UI_ICONS.warn}${RST}`;
+const ICON_INFO    = `${UI_THEME.muted}${UI_ICONS.bullet}${RST}`;
+const SEP          = `${UI_THEME.muted}·${RST}`;
+
+function _cat(name) { return `${UI_THEME.accent}${name}${RST}`; }
+
+function agentError(msg) {
+  return writer.scrollback(`${ICON_ERROR} ${_cat('agent')} ${SEP} ${msg}${RST}`);
+}
+
+function toolError(tag, msg) {
+  return writer.scrollback(`${ICON_ERROR} ${_cat('tool')} ${SEP} ${UI_THEME.accent}${tag}${RST} ${SEP} ${msg}${RST}`);
+}
+
+function netError(msg) {
+  return writer.scrollback(`${ICON_ERROR} ${_cat('net')} ${SEP} ${msg}${RST}`);
+}
+
+function configError(msg) {
+  return writer.scrollback(`${ICON_ERROR} ${_cat('config')} ${SEP} ${msg}${RST}`);
+}
+
+function sysInfo(msg)    { return writer.scrollback(`${ICON_INFO} ${msg}${RST}`); }
+function sysSuccess(msg) { return writer.scrollback(`${ICON_SUCCESS} ${msg}${RST}`); }
+function sysWarn(msg)    { return writer.scrollback(`${ICON_WARN} ${msg}${RST}`); }
+
+module.exports = {
+  agentError, toolError, netError, configError,
+  sysInfo, sysSuccess, sysWarn,
+};

package/lib/ui/select.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const writer = require('./writer');
+
+// Modal-region select menu. Each frame is published via writer.setModal so
+// the menu lives in the modal band above the status region — it redraws in
+// place on arrow-key input and never lands in scrollback. Resolves with the
+// selected index (or null on cancel); callers emit their own summary line
+// via writer.scrollback after the promise resolves.
+//
+// Two input paths:
+//   * TUI:     opts.captureNavigation(handler) → release fn. Mirrors the
+//              permission picker. The host (input-field) routes prev/next/
+//              select/cancel/expand actions to handler; release detaches.
+//   * Non-TUI: direct raw stdin. Used by cmdModels and the permission-
+//              prompt fallback in non-chat command flows.
+//
+// Returns null when stdout/stdin aren't TTY and no captureNavigation is
+// supplied — there's no surface to render onto.
+
+async function interactiveSelect(items, renderItem, options) {
+  const opts = options || {};
+  const initialIndex = Math.max(0, Math.min(opts.initialIndex || 0, items.length - 1));
+
+  if (!Array.isArray(items) || items.length === 0) return null;
+
+  const buildLines = (idx) => {
+    const out = [];
+    for (let i = 0; i < items.length; i++) {
+      out.push(renderItem(items[i], i === idx, false));
+    }
+    return out;
+  };
+
+  // ── TUI path ─────────────────────────────────────────────────────────────
+  // Host wires keystrokes through captureNavigation; rendering goes through
+  // the writer's modal region so the live region (status bar, input row)
+  // beneath stays untouched between frames.
+  if (typeof opts.captureNavigation === 'function') {
+    return new Promise((resolve) => {
+      let idx = initialIndex;
+      let done = false;
+      writer.setModal(buildLines(idx));
+      const releaseNav = opts.captureNavigation((action) => {
+        if (done) return;
+        if (action === 'prev') {
+          idx = (idx - 1 + items.length) % items.length;
+          writer.setModal(buildLines(idx));
+        } else if (action === 'next') {
+          idx = (idx + 1) % items.length;
+          writer.setModal(buildLines(idx));
+        } else if (action === 'select' || action === 'cancel') {
+          done = true;
+          // Order matters: clearModal first so the modal is erased while
+          // the host still has caret suppressed, then releaseNav so the
+          // host's render hooks fire setLive with the input caret
+          // restored. Reversing the two redraws the live region with the
+          // modal still in place for one frame, then nukes the caret.
+          writer.clearModal();
+          if (typeof releaseNav === 'function') releaseNav();
+          resolve(action === 'select' ? idx : null);
+        } else if (action === 'expand') {
+          if (typeof opts.onExpand === 'function') opts.onExpand();
+        }
+      });
+    });
+  }
+
+  // ── Non-TUI path ─────────────────────────────────────────────────────────
+  // Need a real terminal on both ends to read raw keys and draw a modal.
+  if (!process.stdout.isTTY || !process.stdin.isTTY) return null;
+
+  return new Promise((resolve) => {
+    let idx = initialIndex;
+    let done = false;
+    const wasRaw = typeof process.stdin.isRaw === 'boolean' ? process.stdin.isRaw : false;
+
+    writer.setModal(buildLines(idx));
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+
+    const finish = (result) => {
+      if (done) return;
+      done = true;
+      try { process.stdin.setRawMode(wasRaw); } catch {}
+      process.stdin.removeListener('data', onData);
+      process.stdin.pause();
+      writer.clearModal();
+      resolve(result);
+    };
+
+    const onData = (chunk) => {
+      if (done) return;
+      const data = chunk.toString('utf8');
+      if (data[0] === '\x0f') { if (typeof opts.onExpand === 'function') opts.onExpand(); return; }
+      if (data === '\x03' || data === '\x1b' || data === 'q') { finish(null); return; }
+      if (data === '\r' || data === '\n') { finish(idx); return; }
+      if (data === '\x1b[A' || data === 'k') {
+        idx = (idx - 1 + items.length) % items.length;
+        writer.setModal(buildLines(idx));
+        return;
+      }
+      if (data === '\x1b[B' || data === 'j') {
+        idx = (idx + 1) % items.length;
+        writer.setModal(buildLines(idx));
+        return;
+      }
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
+module.exports = { interactiveSelect };