@aitherium/shell-cli 1.11.1 → 1.12.1

package/dist/tui/screen.d.ts

@@ -33,6 +33,11 @@ export interface TuiSurface {
     clearPanes(): void;
     /** Show/hide the TRACE pane (OUTPUT widens to fill). */
     toggleTrace(): void;
+    /** Stash the suggested follow-ups from the last turn so a bare digit in the
+     *  input box can expand to "send the Nth follow-up". Cleared when consumed. */
+    setPendingFollowups(items: string[]): void;
+    /** The currently-stashed follow-ups (empty if none / already consumed). */
+    getPendingFollowups(): string[];
     /** Coalesced repaint. */
     render(): void;
     /** Focus the input box for typing. */
@@ -43,6 +48,13 @@ export interface TuiSurface {
     pickerOpen(): boolean;
     /** Show a filterable command picker; resolves with the chosen value or null. */
     showPicker(title: string, items: PickerItem[], initialFilter?: string): Promise<string | null>;
+    /** Show a full-screen scrollable document viewer over pre-rendered lines
+     *  (markdown/code/text). Resolves when the user closes it (q/Esc). */
+    showViewer(title: string, lines: string[]): Promise<void>;
+    /** Show a full-screen multi-line text editor seeded with `initialText`.
+     *  `onSave(text)` persists and returns an error string (or null on success).
+     *  Resolves when the user closes the editor (Esc/Ctrl+Q). */
+    showEditor(title: string, initialText: string, onSave: (text: string) => Promise<string | null>): Promise<void>;
     /**
      * Suspend the blessed screen, run `fn` on the REAL terminal (so command
      * handlers' console.log / ora spinners / @inquirer prompts all work and don't

package/dist/tui/screen.js

@@ -155,6 +155,9 @@ export function createTuiScreen(opts) {
         scheduleRender();
     }
     function markCheckpoint() { return outputBuf.length; }
+    let pendingFollowups = [];
+    function setPendingFollowups(items) { pendingFollowups = Array.isArray(items) ? items.slice(0, 9) : []; }
+    function getPendingFollowups() { return pendingFollowups; }
     function replaceOutputFrom(offset, text) {
         if (offset < 0 || offset > outputBuf.length)
             return;
@@ -199,6 +202,18 @@ export function createTuiScreen(opts) {
                 for (const l of t.lines)
                     out.push(l);
         });
+        // Belt-and-suspenders against blessed "character bleed": when the trace
+        // SHRINKS (a long turn collapses into a short new one) blessed's wide-char
+        // (emoji) miscount in wrapped lines leaves stale glyphs in the now-uncovered
+        // rows. clearRegion alone proved unreliable for this, so when the content is
+        // shorter than the pane, pad with blank lines so setContent paints over every
+        // visible row. Skip when the user has scrolled up (don't perturb their view)
+        // or when content already fills/overflows the pane (no uncovered rows).
+        if (!userPinnedTrace) {
+            const innerH = (typeof trace.height === 'number' ? trace.height : 0) - 2;
+            while (innerH > out.length)
+                out.push('');
+        }
         const base = trace.childBase || 0;
         try {
             trace.setContent(out.join('\n'));
@@ -726,11 +741,321 @@ export function createTuiScreen(opts) {
             screen.render();
         });
     }
+    // ── Document viewer overlay (full-screen scrollable box) ──────
+    // Reuses the _pickerOpen guard so the main keypress handler stands down while
+    // the viewer owns the keyboard. Content is pre-rendered (markdown/code/text +
+    // chalk ANSI); blessed parses the SGR colour codes itself. Images do NOT come
+    // through here — they render via runDetached so 24-bit colour isn't downsampled.
+    function showViewer(title, lines) {
+        return new Promise((resolve) => {
+            _pickerOpen = true;
+            const box = blessed.box({
+                parent: screen, label: ` ${title}  —  ↑↓/PgUp/PgDn scroll · g/G top/bottom · q/Esc close `,
+                border: 'line', top: 0, left: 0, width: '100%', height: '100%',
+                tags: false, scrollable: true, alwaysScroll: true, keys: true, mouse: true,
+                scrollbar: { ch: ' ', inverse: true }, wrap: true,
+                style: { border: { fg: 'cyan' }, label: { fg: 'cyan' } },
+            });
+            box.setContent(lines.join('\n'));
+            function close() {
+                _pickerOpen = false;
+                try {
+                    box.destroy();
+                }
+                catch { /* */ }
+                screen.render();
+                focusInput();
+                resolve();
+            }
+            const vpage = () => Math.max(1, box.height - 3);
+            box.key(['q', 'escape', 'C-c'], () => close());
+            box.key(['up', 'k'], () => { box.scroll(-1); screen.render(); });
+            box.key(['down', 'j'], () => { box.scroll(1); screen.render(); });
+            box.key(['pageup'], () => { box.scroll(-vpage()); screen.render(); });
+            box.key(['pagedown', 'space'], () => { box.scroll(vpage()); screen.render(); });
+            box.key(['g', 'home'], () => { box.scrollTo(0); screen.render(); });
+            box.key(['G', 'end'], () => { box.setScrollPerc(100); screen.render(); });
+            box.on('wheelup', () => { box.scroll(-3); screen.render(); });
+            box.on('wheeldown', () => { box.scroll(3); screen.render(); });
+            box.focus();
+            screen.render();
+        });
+    }
+    // ── Document editor overlay (notepad/vim-lite, manual keypresses) ─────
+    // A real multi-line editor. We drive it from the PROGRAM keypress stream (same
+    // reason as the main input box: blessed's textarea double-delivers keys on this
+    // terminal). Lines are stored as code-point arrays so emoji/CJK caret maths is
+    // correct. While open, _pickerOpen suppresses the main onKey handler and a
+    // dedicated keypress listener owns the keyboard until the user quits.
+    function showEditor(title, initialText, onSave) {
+        return new Promise((resolve) => {
+            _pickerOpen = true;
+            const lines = (initialText.length ? initialText.replace(/\r\n/g, '\n').split('\n') : [''])
+                .map((l) => Array.from(l));
+            let cr = 0; // cursor row
+            let cc = 0; // cursor col (code-point index)
+            let top = 0; // first visible row (vertical scroll)
+            let dirty = false;
+            let msg = ''; // transient status message
+            let confirmingQuit = false;
+            const box = blessed.box({
+                parent: screen, border: 'line', top: 0, left: 0, width: '100%', height: '100%',
+                tags: false, style: { border: { fg: 'yellow' }, label: { fg: 'yellow' } },
+            });
+            const innerH = () => Math.max(1, box.height - 2);
+            const innerW = () => Math.max(20, box.width - 2);
+            const gutterW = () => String(lines.length).length;
+            function setLabel() {
+                const flag = dirty ? chalk.red(' ●') : '';
+                const pos = `${cr + 1}:${cc + 1}`;
+                const hint = confirmingQuit
+                    ? chalk.red('unsaved — ^Q again to discard, ^S to save')
+                    : chalk.dim('^S save · ^Q/Esc quit · arrows move · Enter newline');
+                const note = msg ? '  ' + chalk.green(msg) : '';
+                try {
+                    box.setLabel(` ${title}${flag}  ${chalk.dim(pos)}  ${hint}${note} `);
+                }
+                catch { /* */ }
+            }
+            function clampView() {
+                if (cr < top)
+                    top = cr;
+                if (cr >= top + innerH())
+                    top = cr - innerH() + 1;
+                if (top < 0)
+                    top = 0;
+            }
+            function render() {
+                clampView();
+                const g = gutterW();
+                const avail = innerW() - (g + 3); // gutter "NNN │ "
+                const out = [];
+                for (let r = top; r < Math.min(lines.length, top + innerH()); r++) {
+                    const isCur = r === cr;
+                    const cps = lines[r];
+                    // Horizontal window so the caret stays visible on long lines.
+                    let start = 0;
+                    if (isCur && cc > avail - 1)
+                        start = cc - (avail - 1);
+                    const slice = cps.slice(start, start + avail);
+                    const gutter = chalk.dim(String(r + 1).padStart(g, ' ') + ' │ ');
+                    if (isCur) {
+                        const rel = cc - start;
+                        const before = slice.slice(0, rel).join('');
+                        const atCh = slice[rel] ?? ' ';
+                        const after = slice.slice(rel + 1).join('');
+                        const lead = start > 0 ? chalk.dim('‹') : '';
+                        out.push(gutter + lead + before + chalk.inverse(atCh) + after);
+                    }
+                    else {
+                        out.push(gutter + slice.join(''));
+                    }
+                }
+                try {
+                    box.setContent(out.join('\n'));
+                }
+                catch { /* */ }
+                setLabel();
+                scheduleRender();
+            }
+            function curLine() { return lines[cr]; }
+            async function doSave() {
+                const text = lines.map((l) => l.join('')).join('\n');
+                const err = await onSave(text);
+                if (err) {
+                    msg = '';
+                    setLabel();
+                    try {
+                        box.setLabel(` ${title}  ${chalk.red('save failed: ' + err)} `);
+                    }
+                    catch { /* */ }
+                    scheduleRender();
+                }
+                else {
+                    dirty = false;
+                    confirmingQuit = false;
+                    msg = 'saved';
+                    render();
+                    setTimeout(() => { msg = ''; setLabel(); scheduleRender(); }, 1500);
+                }
+            }
+            function close() {
+                screen.program.removeListener('keypress', editorKey);
+                _pickerOpen = false;
+                try {
+                    box.destroy();
+                }
+                catch { /* */ }
+                screen.render();
+                focusInput();
+                resolve();
+            }
+            function editorKey(ch, key) {
+                const name = (key && key.name) || '';
+                const ctrl = !!(key && key.ctrl);
+                // Save / quit.
+                if (ctrl && name === 's') {
+                    void doSave();
+                    return;
+                }
+                if ((ctrl && name === 'q') || name === 'escape') {
+                    if (dirty && !confirmingQuit) {
+                        confirmingQuit = true;
+                        setLabel();
+                        scheduleRender();
+                        return;
+                    }
+                    close();
+                    return;
+                }
+                confirmingQuit = false;
+                // Navigation.
+                if (name === 'up') {
+                    if (cr > 0) {
+                        cr--;
+                        cc = Math.min(cc, curLine().length);
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'down') {
+                    if (cr < lines.length - 1) {
+                        cr++;
+                        cc = Math.min(cc, curLine().length);
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'left') {
+                    if (cc > 0)
+                        cc--;
+                    else if (cr > 0) {
+                        cr--;
+                        cc = curLine().length;
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'right') {
+                    if (cc < curLine().length)
+                        cc++;
+                    else if (cr < lines.length - 1) {
+                        cr++;
+                        cc = 0;
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'home') {
+                    cc = 0;
+                    render();
+                    return;
+                }
+                if (name === 'end') {
+                    cc = curLine().length;
+                    render();
+                    return;
+                }
+                if (name === 'pageup') {
+                    cr = Math.max(0, cr - innerH());
+                    cc = Math.min(cc, curLine().length);
+                    render();
+                    return;
+                }
+                if (name === 'pagedown') {
+                    cr = Math.min(lines.length - 1, cr + innerH());
+                    cc = Math.min(cc, curLine().length);
+                    render();
+                    return;
+                }
+                // Editing.
+                if (name === 'enter' || name === 'return' || name === 'linefeed') {
+                    const cur = curLine();
+                    const tail = cur.slice(cc);
+                    lines[cr] = cur.slice(0, cc);
+                    lines.splice(cr + 1, 0, tail);
+                    cr++;
+                    cc = 0;
+                    dirty = true;
+                    render();
+                    return;
+                }
+                if (name === 'backspace') {
+                    if (cc > 0) {
+                        curLine().splice(cc - 1, 1);
+                        cc--;
+                        dirty = true;
+                    }
+                    else if (cr > 0) {
+                        const cur = lines.splice(cr, 1)[0];
+                        cc = lines[cr - 1].length;
+                        lines[cr - 1] = lines[cr - 1].concat(cur);
+                        cr--;
+                        dirty = true;
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'delete') {
+                    if (cc < curLine().length) {
+                        curLine().splice(cc, 1);
+                        dirty = true;
+                    }
+                    else if (cr < lines.length - 1) {
+                        const next = lines.splice(cr + 1, 1)[0];
+                        lines[cr] = curLine().concat(next);
+                        dirty = true;
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'tab') {
+                    curLine().splice(cc, 0, ' ', ' ');
+                    cc += 2;
+                    dirty = true;
+                    render();
+                    return;
+                }
+                // Printable insert (paste may deliver several chars; respects newlines).
+                if (ch && typeof ch === 'string' && ch.length >= 1 && ch >= ' ' && !(key && (key.ctrl || key.meta))) {
+                    for (const c of Array.from(ch)) {
+                        curLine().splice(cc, 0, c);
+                        cc++;
+                    }
+                    dirty = true;
+                    render();
+                    return;
+                }
+                // Multi-line paste arriving as a chunk with embedded newlines.
+                if (ch && typeof ch === 'string' && ch.includes('\n')) {
+                    for (const c of Array.from(ch)) {
+                        if (c === '\n') {
+                            const tail = curLine().slice(cc);
+                            lines[cr] = curLine().slice(0, cc);
+                            lines.splice(cr + 1, 0, tail);
+                            cr++;
+                            cc = 0;
+                        }
+                        else if (c >= ' ') {
+                            curLine().splice(cc, 0, c);
+                            cc++;
+                        }
+                    }
+                    dirty = true;
+                    render();
+                    return;
+                }
+            }
+            screen.program.on('keypress', editorKey);
+            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,
+        setPendingFollowups, getPendingFollowups,
+        pickerOpen, showPicker, showViewer, showEditor, runDetached,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aitherium/shell-cli",
-  "version": "1.11.1",
+  "version": "1.12.1",
   "description": "Interactive terminal for AitherOS and ADK agents",
   "license": "BUSL-1.1",
   "type": "module",