@aitherium/shell-cli 1.1.0 → 1.11.0

package/dist/tui/screen.js

@@ -0,0 +1,736 @@
+/**
+ * neo-blessed 3-pane surface for AitherShell.
+ *
+ *   ┌─ output (≈60%) ───────┬─ trace (≈40%) ─┐
+ *   │ answer streams here    │ live pipeline  │
+ *   │ (independently scroll) │ telemetry      │
+ *   ├────────────────────────┴────────────────┤
+ *   │ status line                             │
+ *   ├─────────────────────────────────────────┤
+ *   │ message > ▌                              │
+ *   └─────────────────────────────────────────┘
+ *
+ * OUTPUT and TRACE each own a real scroll buffer (mouse wheel + PageUp/Down),
+ * so long output is never "eaten" — the bug the old DECSTBM SteeringBar caused.
+ */
+import { createRequire } from 'node:module';
+import chalk from 'chalk';
+const nodeRequire = createRequire(import.meta.url);
+const blessed = nodeRequire('neo-blessed');
+export function createTuiScreen(opts) {
+    // Force SGR (1006) mouse reporting BEFORE the screen (and its lazy
+    // program.enableMouse()) initialises. neo-blessed picks the mouse mode purely
+    // from $TERM: for xterm-256color it enables vt200Mouse + utfMouse (1005) but
+    // NOT SGR. Windows Terminal doesn't implement UTF-8 mouse (1005), so the raw
+    // high bytes get UTF-8-decoded and the X10 coordinate parse corrupts/drops the
+    // event — which is why mouse-wheel scroll and click-to-toggle-thread did
+    // nothing. SGR is pure ASCII (no encoding ambiguity), universally supported,
+    // and the input parser already decodes it. BLESSED_FORCE_MODES is blessed's
+    // own escape hatch and is read at enableMouse() time. vt200Mouse(1000) reports
+    // button press/release + wheel — all we need; we skip cell/all-motion to avoid
+    // a mousemove event storm.
+    if (!process.env.BLESSED_FORCE_MODES) {
+        process.env.BLESSED_FORCE_MODES = 'SGRMOUSE=1,VT200MOUSE=1';
+    }
+    const screen = blessed.screen({
+        smartCSR: true, fullUnicode: true, mouse: true,
+        title: opts.title || 'AitherShell', autoPadding: true, warnings: false,
+    });
+    // Belt-and-suspenders: guarantee mouse reporting is on even if no element's
+    // newListener happened to trigger it first. Idempotent; re-reads the env modes.
+    try {
+        screen.program.enableMouse();
+    }
+    catch { /* terminal may not support it */ }
+    const paneBottom = 4;
+    const output = blessed.box({
+        parent: screen, top: 0, left: 0, width: '60%', bottom: paneBottom,
+        label: ' output ', border: 'line', tags: false,
+        scrollable: true, alwaysScroll: true, keys: true, mouse: true,
+        scrollbar: { ch: ' ', inverse: true }, wrap: true,
+        style: { border: { fg: 'cyan' }, label: { fg: 'cyan' } },
+    });
+    const traceTurns = [];
+    // Rendered-line-index → turn-index, for click-to-toggle on header rows.
+    let traceHeaderRows = new Map();
+    let userPinnedTrace = false;
+    const trace = blessed.box({
+        parent: screen, top: 0, left: '60%', right: 0, bottom: paneBottom,
+        label: ' trace ', border: 'line', tags: false,
+        scrollable: true, alwaysScroll: true, wrap: true, // wrap long trace lines (were truncated with …)
+        keys: true, mouse: true, scrollbar: { ch: ' ', inverse: true },
+        style: { border: { fg: 'gray' }, label: { fg: 'gray' } },
+    });
+    const status = blessed.box({
+        parent: screen, bottom: 3, left: 0, right: 0, height: 1, tags: false,
+        // A solid inverse bar so the status line is always clearly visible (the dim
+        // gray-on-black was nearly invisible except when the terminal selection hit it).
+        style: { fg: 'black', bg: 'cyan' },
+    });
+    // Display-only box — input is driven manually (see onKey below), NOT via
+    // blessed's readInput, which double-delivers keys to the element on this terminal.
+    const input = blessed.box({
+        parent: screen, bottom: 0, left: 0, right: 0, height: 3,
+        label: ' message ', border: 'line', tags: false,
+        style: { border: { fg: 'yellow' }, label: { fg: 'yellow' } },
+    });
+    // ── OUTPUT streaming buffer + scroll pinning ───────────────────
+    let outputBuf = '';
+    let userPinnedOutput = false;
+    let dirty = false;
+    let renderTimer = null;
+    function atBottom(el) {
+        try {
+            return el.getScrollPerc() >= 99;
+        }
+        catch {
+            return true;
+        }
+    }
+    function atTop(el) {
+        try {
+            return el.getScrollPerc() <= 1;
+        }
+        catch {
+            return false;
+        }
+    }
+    function flush() {
+        renderTimer = null;
+        // NOTE: flush() runs in a setTimeout (timer) context — it is NOT inside the
+        // stream for-await try/catch. A throw from any blessed call here would escape
+        // as an uncaughtException → the global crash reporter calls process.exit(1) →
+        // the whole TUI dies mid-turn (observed: long grounded follow-up renders
+        // intermittently throw under fullUnicode). Swallow render faults so a single
+        // bad repaint never tears the session down; the next scheduleRender recovers.
+        try {
+            if (dirty) {
+                // Preserve the user's scroll position across streamed appends: setContent
+                // resets the view, so when the user has scrolled up (pinned) we restore
+                // their top line instead of yanking them to the bottom on every token.
+                const base = output.childBase || 0;
+                output.setContent(outputBuf);
+                if (!userPinnedOutput)
+                    output.setScrollPerc(100);
+                else {
+                    try {
+                        output.scrollTo(base);
+                    }
+                    catch { /* */ }
+                }
+                dirty = false;
+            }
+            screen.render();
+        }
+        catch { /* transient blessed repaint fault — recovered on next render */ }
+    }
+    function scheduleRender() { if (!renderTimer)
+        renderTimer = setTimeout(flush, 1000 / 30); }
+    function appendOutput(text) {
+        if (!text)
+            return;
+        outputBuf += text;
+        dirty = true;
+        scheduleRender();
+    }
+    function outputLine(line) {
+        appendOutput((outputBuf && !outputBuf.endsWith('\n') ? '\n' : '') + line + '\n');
+    }
+    /** Prepend text to the TOP of the output (relay scrollback). Keeps the viewport
+     *  anchored by shifting scroll down by the number of added lines, so older
+     *  history loading-in doesn't make the visible content jump. */
+    function prependOutput(text) {
+        if (!text)
+            return;
+        const t = text.endsWith('\n') ? text : text + '\n';
+        const addedLines = (t.match(/\n/g) || []).length;
+        outputBuf = t + outputBuf;
+        dirty = true;
+        try {
+            output.setContent(outputBuf);
+            output.scrollTo((output.childBase || 0) + addedLines);
+            userPinnedOutput = !atBottom(output);
+        }
+        catch { /* */ }
+        scheduleRender();
+    }
+    function markCheckpoint() { return outputBuf.length; }
+    function replaceOutputFrom(offset, text) {
+        if (offset < 0 || offset > outputBuf.length)
+            return;
+        outputBuf = outputBuf.slice(0, offset) + text;
+        dirty = true;
+        clearRegion(output); // markdown render may be shorter than the streamed text — blank stale tail
+        scheduleRender();
+    }
+    function _turnHeader(t) {
+        const arrow = t.collapsed ? '▸' : '▾';
+        const icon = t.status === 'done' ? chalk.green('✓')
+            : t.status === 'error' ? chalk.red('✗') : chalk.yellow('⚡');
+        const dur = t.durationMs != null ? chalk.dim(`  ${(t.durationMs / 1000).toFixed(1)}s`)
+            : t.collapsed && t.lines.length ? chalk.dim(`  (${t.lines.length})`) : '';
+        return `${chalk.cyan(arrow)} ${icon} ${chalk.cyan(t.label)}${dur}`;
+    }
+    // Blank a pane's inner content rectangle in the screen buffer before a repaint.
+    // Under fullUnicode, blessed's box render miscounts wide chars (emoji) in
+    // wrapped lines and skips some cells, so when content SHRINKS (a turn collapses,
+    // markdown replaces a longer stream) the old glyphs are left behind as
+    // "character bleed". clearRegion writes spaces + marks those cells dirty so the
+    // next render redraws them clean. Cheap (buffer-only, no terminal clear → no
+    // flicker); the box border is preserved by insetting 1 cell. lpos exists only
+    // after the first render — the very first paint can't ghost, so skipping is safe.
+    function clearRegion(el) {
+        const p = el.lpos;
+        if (!p)
+            return;
+        try {
+            screen.clearRegion(p.xi + 1, p.xl - 1, p.yi + 1, p.yl - 1);
+        }
+        catch { /* */ }
+    }
+    function renderTrace() {
+        clearRegion(trace);
+        const out = [];
+        traceHeaderRows = new Map();
+        traceTurns.forEach((t, ti) => {
+            traceHeaderRows.set(out.length, ti);
+            out.push(_turnHeader(t));
+            if (!t.collapsed)
+                for (const l of t.lines)
+                    out.push(l);
+        });
+        const base = trace.childBase || 0;
+        try {
+            trace.setContent(out.join('\n'));
+            if (!userPinnedTrace)
+                trace.setScrollPerc(100);
+            else {
+                try {
+                    trace.scrollTo(base);
+                }
+                catch { /* */ }
+            }
+        }
+        catch { /* transient blessed fault — recovered on next render */ }
+        scheduleRender();
+    }
+    /** Begin a new trace thread; collapse prior threads into the running history. */
+    function startTraceTurn(label) {
+        for (const t of traceTurns)
+            t.collapsed = true;
+        traceTurns.push({ label, lines: [], collapsed: false, status: 'running', startedAt: Date.now() });
+        renderTrace();
+    }
+    /** Mark the current thread done/error + stamp its duration (shown in header). */
+    function finishTraceTurn(status) {
+        const t = traceTurns[traceTurns.length - 1];
+        if (!t || t.status !== 'running')
+            return;
+        t.status = status;
+        t.durationMs = Date.now() - t.startedAt;
+        renderTrace();
+    }
+    function traceLine(line) {
+        if (!traceTurns.length)
+            traceTurns.push({ label: 'session', lines: [], collapsed: false, status: 'running', startedAt: Date.now() });
+        traceTurns[traceTurns.length - 1].lines.push(line);
+        renderTrace();
+    }
+    /** Toggle collapse on the turn whose header is at rendered content row `row`. */
+    function toggleTurnAtRow(row) {
+        const ti = traceHeaderRows.get(row);
+        if (ti == null)
+            return;
+        traceTurns[ti].collapsed = !traceTurns[ti].collapsed;
+        renderTrace();
+    }
+    /** Collapse-all ⇄ expand-all (Ctrl+E). */
+    function toggleAllTurns() {
+        const anyOpen = traceTurns.some(t => !t.collapsed);
+        for (const t of traceTurns)
+            t.collapsed = anyOpen;
+        renderTrace();
+    }
+    // Click a turn header to expand/collapse it.
+    trace.on('click', (data) => {
+        try {
+            const row = (data.y - trace.atop - trace.itop) + (trace.childBase || 0);
+            toggleTurnAtRow(row);
+        }
+        catch { /* */ }
+    });
+    function setStatus(text) { status.setContent('  ' + (text || '')); scheduleRender(); }
+    function setTracePanel(label, lines) {
+        clearRegion(trace);
+        try {
+            trace.setLabel(` ${label} `);
+        }
+        catch { /* */ }
+        const base = trace.childBase || 0;
+        trace.setContent(lines.join('\n'));
+        if (!userPinnedTrace)
+            trace.setScrollPerc(100);
+        else {
+            try {
+                trace.scrollTo(base);
+            }
+            catch { /* */ }
+        }
+        scheduleRender();
+    }
+    function setOutputLabel(label) {
+        try {
+            output.setLabel(` ${label} `);
+        }
+        catch { /* */ }
+        scheduleRender();
+    }
+    function clearPanes() {
+        outputBuf = '';
+        dirty = true;
+        output.setContent('');
+        traceTurns.length = 0;
+        traceHeaderRows = new Map();
+        trace.setContent('');
+        scheduleRender();
+    }
+    let traceVisible = true;
+    let splitPct = 60; // OUTPUT pane width %; the rest is the trace pane.
+    function applySplit() {
+        if (traceVisible) {
+            output.width = `${splitPct}%`;
+            trace.left = `${splitPct}%`;
+        }
+    }
+    function toggleTrace() {
+        traceVisible = !traceVisible;
+        if (traceVisible) {
+            trace.show();
+            applySplit();
+        }
+        else {
+            trace.hide();
+            output.width = '100%';
+        }
+        screen.render();
+    }
+    // Mouse capture vs terminal text selection. While blessed owns the mouse (the
+    // default — needed for wheel scroll + click-to-toggle-thread) the terminal's
+    // own click-drag selection is intercepted, so you can't highlight to copy.
+    // Ctrl+G releases the mouse back to the terminal (select/copy freely); Ctrl+G
+    // again re-grabs it for scroll. (Tip: most terminals also do Shift+drag while
+    // captured.)
+    let mouseCaptured = true;
+    function toggleMouse() {
+        mouseCaptured = !mouseCaptured;
+        try {
+            if (mouseCaptured)
+                screen.program.enableMouse();
+            else
+                screen.program.disableMouse();
+        }
+        catch { /* terminal may not support it */ }
+        setStatus(mouseCaptured
+            ? 'mouse: captured (wheel scroll on) — Ctrl+G to release for copy/paste'
+            : 'mouse: released — drag to select/copy · Ctrl+G to re-enable scroll');
+        screen.render();
+    }
+    /** Adjust the output/trace split (Ctrl+←/→). +delta widens output. */
+    function resizeSplit(delta) {
+        if (!traceVisible)
+            return;
+        splitPct = Math.max(30, Math.min(85, splitPct + delta));
+        applySplit();
+        screen.render();
+    }
+    function scrollOutput(amount) {
+        try {
+            output.scroll(amount);
+            userPinnedOutput = !atBottom(output);
+            screen.render();
+        }
+        catch { /* */ }
+    }
+    function scrollTrace(amount) {
+        try {
+            trace.scroll(amount);
+            userPinnedTrace = !atBottom(trace);
+            screen.render();
+        }
+        catch { /* */ }
+    }
+    output.on('scroll', () => {
+        userPinnedOutput = !atBottom(output);
+        if (atTop(output))
+            opts.onScrollTop?.(); // relay scrollback (caller guards re-entrancy)
+    });
+    trace.on('scroll', () => { userPinnedTrace = !atBottom(trace); });
+    // Mouse wheel scrolls whichever pane is under the cursor — independently, and
+    // without needing focus. (blessed's built-in wheel scroll doesn't update our
+    // pin state, so route through scrollOutput/scrollTrace which do.)
+    output.on('wheelup', () => scrollOutput(-3));
+    output.on('wheeldown', () => scrollOutput(3));
+    trace.on('wheelup', () => scrollTrace(-3));
+    trace.on('wheeldown', () => scrollTrace(3));
+    /** Snap the OUTPUT pane back to the live bottom (un-pin). */
+    function outputToBottom() {
+        userPinnedOutput = false;
+        try {
+            output.setScrollPerc(100);
+            screen.render();
+        }
+        catch { /* */ }
+    }
+    // ── Manual input handling (do NOT use blessed's textbox readInput) ──
+    // Verified on this terminal: stdin emits EXACTLY ONE keypress per physical key,
+    // but blessed's textbox element-keypress path delivers each key to the textbox
+    // TWICE ("hheeyy"). So we drive the input value ourselves from the PROGRAM-level
+    // keypress stream — `program.emit('keypress')` fires once per physical key
+    // (Program.instances == 1) — and use the `input` box purely as a display.
+    // Input is an array of CODE POINTS (emoji-safe caret math), not a JS string.
+    let inputChars = [];
+    let _pickerOpen = false;
+    let inputCursor = 0; // caret index into inputChars
+    function inputStr() { return inputChars.join(''); }
+    function setInput(val, cur) {
+        inputChars = Array.from(val ?? '');
+        inputCursor = cur == null ? inputChars.length : Math.max(0, Math.min(cur, inputChars.length));
+        renderInput();
+    }
+    function renderInput() {
+        // Horizontally WINDOW long lines so the caret stays visible inside the
+        // single-line box (was overflowing before). '‹' marks a scrolled-off head.
+        const innerW = Math.max(8, input.width - 3);
+        let start = 0;
+        if (inputCursor > innerW - 2)
+            start = inputCursor - (innerW - 2);
+        const win = inputChars.slice(start, start + innerW);
+        const rel = inputCursor - start;
+        const before = win.slice(0, rel).join('');
+        const at = win[rel] ?? ' ';
+        const after = win.slice(rel + 1).join('');
+        const lead = start > 0 ? chalk.dim('‹') : ' ';
+        input.setContent(lead + before + chalk.inverse(at) + after);
+        scheduleRender();
+    }
+    const page = () => Math.max(1, output.height - 4);
+    function onKey(ch, key) {
+        if (_pickerOpen)
+            return; // the picker (blessed.list) handles its own keys
+        const name = (key && key.name) || '';
+        const ctrl = !!(key && key.ctrl);
+        if (ctrl && name === 'c') {
+            opts.onInterrupt();
+            return;
+        }
+        if (ctrl && name === 't') {
+            toggleTrace();
+            return;
+        }
+        if (ctrl && name === 'g') {
+            toggleMouse();
+            return;
+        } // release/grab mouse for copy-paste
+        if (ctrl && name === 'e' && !inputChars.length) {
+            toggleAllTurns();
+            return;
+        } // expand threads only on empty line
+        // ── Pane controls ──
+        if (name === 'pageup') {
+            (key && key.shift) ? scrollTrace(-8) : scrollOutput(-page());
+            return;
+        }
+        if (name === 'pagedown') {
+            (key && key.shift) ? scrollTrace(8) : scrollOutput(page());
+            return;
+        }
+        if (ctrl && name === 'up') {
+            scrollOutput(-1);
+            return;
+        }
+        if (ctrl && name === 'down') {
+            scrollOutput(1);
+            return;
+        }
+        if (ctrl && name === 'left') {
+            resizeSplit(-5);
+            return;
+        } // give the trace pane more room
+        if (ctrl && name === 'right') {
+            resizeSplit(5);
+            return;
+        } // give the output pane more room
+        // Home/End scroll output (Shift = trace) ONLY on an empty line; otherwise
+        // they move the input caret (so editing a typed line works as expected).
+        if (name === 'home') {
+            if (inputChars.length) {
+                inputCursor = 0;
+                renderInput();
+            }
+            else
+                (key && key.shift) ? scrollTrace(-99999) : scrollOutput(-99999);
+            return;
+        }
+        if (name === 'end') {
+            if (inputChars.length) {
+                inputCursor = inputChars.length;
+                renderInput();
+            }
+            else
+                (key && key.shift) ? scrollTrace(99999) : outputToBottom();
+            return;
+        }
+        // ── Input line editing (operates on code points) ──
+        if (name === 'enter' || name === 'return' || name === 'linefeed') {
+            const line = inputStr().trim();
+            setInput('');
+            if (line === '/' && opts.onSlash) {
+                opts.onSlash();
+                return;
+            }
+            if (line)
+                opts.onSubmit(line);
+            return;
+        }
+        if (name === 'left') {
+            if (inputCursor > 0) {
+                inputCursor--;
+                renderInput();
+            }
+            return;
+        }
+        if (name === 'right') {
+            if (inputCursor < inputChars.length) {
+                inputCursor++;
+                renderInput();
+            }
+            return;
+        }
+        if (ctrl && name === 'a') {
+            inputCursor = 0;
+            renderInput();
+            return;
+        } // line start (readline)
+        if (ctrl && name === 'e') {
+            inputCursor = inputChars.length;
+            renderInput();
+            return;
+        } // line end
+        if (ctrl && name === 'u') {
+            setInput(inputChars.slice(inputCursor).join(''), 0);
+            return;
+        } // kill to start
+        if (ctrl && name === 'k') {
+            setInput(inputChars.slice(0, inputCursor).join(''), inputCursor);
+            return;
+        } // kill to end
+        if (ctrl && name === 'w') { // delete word before caret
+            const left = Array.from(inputChars.slice(0, inputCursor).join('').replace(/\s*\S+\s*$/, ''));
+            setInput(left.join('') + inputChars.slice(inputCursor).join(''), left.length);
+            return;
+        }
+        if (name === 'backspace') {
+            if (inputCursor > 0)
+                setInput(inputChars.slice(0, inputCursor - 1).concat(inputChars.slice(inputCursor)).join(''), inputCursor - 1);
+            return;
+        }
+        if (name === 'delete') {
+            if (inputCursor < inputChars.length)
+                setInput(inputChars.slice(0, inputCursor).concat(inputChars.slice(inputCursor + 1)).join(''), inputCursor);
+            return;
+        }
+        if (name === 'up' && opts.onHistory) {
+            const v = opts.onHistory('up');
+            if (v != null)
+                setInput(v);
+            return;
+        }
+        if (name === 'down' && opts.onHistory) {
+            const v = opts.onHistory('down');
+            if (v != null)
+                setInput(v);
+            return;
+        }
+        if (name === 'tab' && opts.onTab) {
+            const v = opts.onTab(inputStr());
+            if (v != null)
+                setInput(v);
+            return;
+        }
+        // Printable character — insert at the caret. Ignore control/meta combos.
+        if (ch && typeof ch === 'string' && ch.length >= 1 && ch >= ' ' && !(key && (key.ctrl || key.meta))) {
+            const ins = Array.from(ch); // paste may deliver multiple chars at once
+            inputChars = inputChars.slice(0, inputCursor).concat(ins, inputChars.slice(inputCursor));
+            inputCursor += ins.length;
+            renderInput();
+            opts.onType?.();
+        }
+    }
+    screen.program.on('keypress', onKey);
+    function render() { scheduleRender(); }
+    function focusInput() { renderInput(); }
+    function destroy() {
+        if (renderTimer) {
+            clearTimeout(renderTimer);
+            renderTimer = null;
+        }
+        try {
+            screen.destroy();
+        }
+        catch { /* */ }
+    }
+    // Suspend blessed → run on the real terminal → restore. Mirrors the readline
+    // REPL's stdin-listener save/restore so handler ora/inquirer/console all work.
+    async function runDetached(label, fn) {
+        const program = screen.program;
+        const stdin = process.stdin;
+        const dataL = stdin.rawListeners('data').slice();
+        const keyL = stdin.rawListeners('keypress').slice();
+        stdin.removeAllListeners('data');
+        stdin.removeAllListeners('keypress');
+        try {
+            program.disableMouse();
+        }
+        catch { /* */ }
+        program.normalBuffer(); // leave the alt screen → normal terminal (output visible)
+        program.showCursor();
+        if (stdin.setRawMode)
+            try {
+                stdin.setRawMode(false);
+            }
+            catch { /* */ }
+        stdin.resume();
+        process.stdout.write('\n' + chalk.cyan(`── /${label} ──`) + '\n\n');
+        try {
+            await fn();
+        }
+        catch (e) {
+            process.stdout.write('\n' + chalk.red(`  Error: ${e?.message || e}`) + '\n');
+        }
+        process.stdout.write(chalk.dim('\n  ── press Enter to return to AitherShell ──'));
+        // fn() may have been an @inquirer prompt flow (interactive commands), which on
+        // completion can leave stdin in raw mode AND paused with its own listeners
+        // detached — so a plain Enter never produces a 'data' event and the wait hangs
+        // (and Ctrl+C, being a raw byte rather than a signal, can't break out either).
+        // Re-establish flowing, non-raw, listener-free stdin before waiting so Enter
+        // delivers a newline and Ctrl+C raises SIGINT normally.
+        stdin.removeAllListeners('data');
+        stdin.removeAllListeners('keypress');
+        if (stdin.setRawMode)
+            try {
+                stdin.setRawMode(false);
+            }
+            catch { /* */ }
+        stdin.resume();
+        await new Promise((resolve) => {
+            const done = () => {
+                stdin.removeListener('data', onData);
+                process.removeListener('SIGINT', onSig);
+                resolve();
+            };
+            const onData = () => done();
+            const onSig = () => done(); // Ctrl+C returns to the shell instead of killing it
+            stdin.on('data', onData);
+            process.once('SIGINT', onSig);
+        });
+        // Restore blessed ownership of the terminal.
+        stdin.removeAllListeners('data');
+        stdin.removeAllListeners('keypress');
+        for (const l of dataL)
+            stdin.on('data', l);
+        for (const l of keyL)
+            stdin.on('keypress', l);
+        if (stdin.setRawMode)
+            try {
+                stdin.setRawMode(true);
+            }
+            catch { /* */ }
+        program.alternateBuffer();
+        try {
+            program.enableMouse();
+        }
+        catch { /* */ }
+        try {
+            screen.alloc();
+        }
+        catch { /* */ }
+        screen.render();
+        focusInput();
+    }
+    // ── Command picker overlay (native blessed.list — no inquirer) ──
+    function pickerOpen() { return _pickerOpen; }
+    function showPicker(title, items, initialFilter = '') {
+        return new Promise((resolve) => {
+            _pickerOpen = true;
+            let filter = initialFilter;
+            const box = blessed.list({
+                parent: screen, label: ` ${title} `, border: 'line',
+                top: 'center', left: 'center', width: '70%', height: '80%',
+                keys: true, mouse: true, tags: false, // no vi: letters are for type-to-filter
+                scrollbar: { ch: ' ', inverse: true },
+                style: { selected: { bg: 'cyan', fg: 'black' }, border: { fg: 'cyan' }, label: { fg: 'cyan' }, item: { fg: 'white' } },
+            });
+            let view = [];
+            function refresh() {
+                const term = filter.trim().toLowerCase();
+                view = items.filter(it => {
+                    if (it.separator)
+                        return !term; // hide separators while filtering
+                    if (!term)
+                        return true;
+                    return it.value.toLowerCase().includes(term)
+                        || it.label.toLowerCase().includes(term)
+                        || (it.description || '').toLowerCase().includes(term);
+                });
+                box.setItems(view.map(it => it.separator
+                    ? `  ${it.label}`
+                    : `  ${it.label}${it.description ? '  —  ' + it.description : ''}`));
+                box.setLabel(` ${title}${filter ? '  /' + filter : ''} `);
+                // Select the first non-separator row.
+                const firstReal = view.findIndex(it => !it.separator);
+                if (firstReal >= 0)
+                    box.select(firstReal);
+                screen.render();
+            }
+            function close(result) {
+                _pickerOpen = false;
+                try {
+                    box.destroy();
+                }
+                catch { /* */ }
+                screen.render();
+                focusInput();
+                resolve(result);
+            }
+            box.on('select', (_item, idx) => {
+                const it = view[idx];
+                if (it && !it.separator)
+                    close(it.value);
+            });
+            box.key(['escape', 'C-c'], () => close(null));
+            box.key(['backspace'], () => { filter = filter.slice(0, -1); refresh(); });
+            box.on('keypress', (ch, key) => {
+                if (!key)
+                    return;
+                if (key.name === 'enter' || key.name === 'return' || key.name === 'up' || key.name === 'down'
+                    || key.name === 'pageup' || key.name === 'pagedown' || key.name === 'escape'
+                    || key.name === 'backspace' || key.name === 'tab')
+                    return;
+                if (ch && ch.length === 1 && ch >= ' ') {
+                    filter += ch;
+                    refresh();
+                }
+            });
+            refresh();
+            box.focus();
+            screen.render();
+        });
+    }
+    renderInput();
+    screen.render();
+    return {
+        screen, input, appendOutput, outputLine, markCheckpoint, replaceOutputFrom, prependOutput,
+        traceLine, startTraceTurn, finishTraceTurn, setStatus, setTracePanel, setOutputLabel, clearPanes, toggleTrace, render, focusInput, destroy,
+        pickerOpen, showPicker, runDetached,
+    };
+}