@crouton-kit/humanloop 0.3.38 → 0.3.39

package/dist/tui/app.js

@@ -1,13 +1,12 @@
 import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync } from 'fs';
-import { dirname, resolve as resolvePath, join } from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { tmpdir } from 'node:os';
-import { randomUUID } from 'node:crypto';
+import { dirname, resolve as resolvePath } from 'node:path';
 import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize } from './terminal.js';
 import { diffFrame, renderOverview, renderItemReview, renderFinal, renderHandoff, clampItemReviewScroll } from './render.js';
 import { handleKeypress, assignShortcuts } from './input.js';
-import { readConversation } from '../conversation/reader.js';
-import { defaultGenerateVisual } from '../visuals/generate.js';
+import { visualGeneratorForConversationSession } from '../visuals/conversation.js';
+import { visualRenderWidth } from '../visuals/generate.js';
+import { renderMarkdown } from '../render/termrender.js';
+import { editBufferInEditor } from '../editor/roundtrip.js';
 import { validateDeck } from '../inbox/deck-schema.js';
 import { progressPath as progressPathFor, deckPath as deckPathFor, writeResponse, clearProgress } from '../inbox/convention.js';
 import { startWebServer } from '../browser/server.js';
@@ -19,7 +18,7 @@ export function validateInput(parsed) {
     return validateDeck(parsed);
 }
 // ── Internal helpers ──────────────────────────────────────────────────────────
-function buildInitialState(deck) {
+function buildInitialState(deck, editorAvailable = false, followUpAvailable = false) {
     // Single-question decks skip the overview list — there's nothing to overview,
     // and overview hides the option hotkeys so users press 'y' and nothing happens.
     const initialPhase = deck.interactions.length === 1 ? 'item-review' : 'overview';
@@ -55,8 +54,12 @@ function buildInitialState(deck) {
         preAnsweredIds,
         inputMode: null,
         selectedAction: 0,
-        detailExpanded: false,
+        bodyMode: 'question',
         scrollOffset: 0,
+        bodyScrollOffsets: { question: 0, visual: 0 },
+        editorAvailable,
+        followUpAvailable,
+        followUp: undefined,
     };
 }
 function collectResponses(state) {
@@ -104,23 +107,36 @@ function rebindPersist(internals) {
         internals.callbacks.onProgress?.(responses);
     };
 }
+function renderVisualMarkdown(markdown, cols) {
+    return renderMarkdown(markdown, visualRenderWidth(cols)).join('\n');
+}
+/** Reflow ready visual context locally; resizing must never invoke the model. */
+function rerenderVisuals(internals) {
+    for (const [id, visual] of internals.state.visuals) {
+        if (visual.status !== 'ready' || visual.markdown === undefined)
+            continue;
+        internals.state.visuals.set(id, { ...visual, content: renderVisualMarkdown(visual.markdown, internals.cols) });
+    }
+}
 function fireVisuals(internals, interactions) {
     if (internals.generateVisual === undefined)
         return;
     const gen = internals.generateVisual;
+    const generation = ++internals.visualGeneration;
     for (const interaction of interactions) {
+        const generationCols = internals.cols;
         internals.state.visuals.set(interaction.id, { questionId: interaction.id, content: '', status: 'loading' });
-        gen(interaction).then((r) => {
-            if (!internals.mounted)
+        gen(interaction, generationCols).then((r) => {
+            if (!internals.mounted || generation !== internals.visualGeneration)
                 return;
             if (!internals.state.interactions.some((x) => x.id === interaction.id))
                 return;
             internals.state.visuals.set(interaction.id, r.ok
-                ? { questionId: interaction.id, content: r.ansi, status: 'ready' }
+                ? { questionId: interaction.id, content: internals.cols === generationCols ? r.ansi : renderVisualMarkdown(r.markdown, internals.cols), markdown: r.markdown, status: 'ready' }
                 : { questionId: interaction.id, content: '', status: 'error' });
             internals.callbacks.onDirty?.();
         }).catch(() => {
-            if (!internals.mounted)
+            if (!internals.mounted || generation !== internals.visualGeneration)
                 return;
             if (!internals.state.interactions.some((x) => x.id === interaction.id))
                 return;
@@ -130,14 +146,23 @@ function fireVisuals(internals, interactions) {
     }
 }
 export function mountPanel(opts) {
+    const followUpAvailable = opts.followUpAvailable !== false
+        && opts.onFollowUpRequest !== undefined
+        && opts.onFollowUpCancel !== undefined;
     const internals = {
-        state: buildInitialState(opts.deck),
+        state: buildInitialState(opts.deck, opts.onEditorRequest !== undefined, followUpAvailable),
         cols: opts.cols,
         rows: opts.rows,
         mounted: true,
         generateVisual: opts.generateVisual,
+        visualGeneration: 0,
         progressPath: opts.progressPath,
-        callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit, onDirty: opts.onDirty },
+        followUpAvailable,
+        callbacks: {
+            onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit,
+            onDirty: opts.onDirty, onEditorRequest: opts.onEditorRequest,
+            onFollowUpRequest: opts.onFollowUpRequest, onFollowUpCancel: opts.onFollowUpCancel,
+        },
     };
     assignShortcuts(internals.state.interactions);
     rebindPersist(internals);
@@ -156,6 +181,10 @@ export function mountPanel(opts) {
         handleKey(input, key) {
             if (!internals.mounted)
                 return;
+            if (key.ctrl && input === 'o' && internals.state.inputMode !== null && internals.callbacks.onEditorRequest !== undefined) {
+                internals.callbacks.onEditorRequest();
+                return;
+            }
             const onAutoComplete = () => {
                 const responses = collectResponses(internals.state);
                 if (internals.progressPath !== undefined) {
@@ -174,6 +203,9 @@ export function mountPanel(opts) {
                 else {
                     internals.callbacks.onExit?.();
                 }
+            }, {
+                request: (question) => internals.callbacks.onFollowUpRequest?.(question),
+                cancel: () => internals.callbacks.onFollowUpCancel?.(),
             });
             // Pre-render clamp (input layer): keep scrollOffset within the current
             // body's bounds so u/d stay responsive. The renderer itself is pure.
@@ -189,7 +221,9 @@ export function mountPanel(opts) {
         handleResize(cols, rows) {
             internals.cols = cols;
             internals.rows = rows;
-            // New dimensions change the scroll bounds — re-clamp before laying out.
+            // Width changes reflow saved visual markdown, so clamp against the new
+            // content and geometry rather than the stale pre-resize wrapping.
+            rerenderVisuals(internals);
             if (internals.state.phase === 'item-review') {
                 clampItemReviewScroll(internals.state, cols, rows);
             }
@@ -204,7 +238,7 @@ export function mountPanel(opts) {
             if (!internals.mounted)
                 return;
             const prior = collectResponses(internals.state);
-            internals.state = buildInitialState(deck);
+            internals.state = buildInitialState(deck, internals.callbacks.onEditorRequest !== undefined, internals.followUpAvailable);
             if (loadOpts !== undefined && loadOpts.progressPath !== undefined) {
                 internals.progressPath = loadOpts.progressPath;
             }
@@ -227,6 +261,25 @@ export function mountPanel(opts) {
             }
             fireVisuals(internals, deck.interactions);
         },
+        setFollowUpHandlers(available, onRequest, onCancel) {
+            if (!internals.mounted)
+                return;
+            internals.callbacks.onFollowUpRequest = onRequest;
+            internals.callbacks.onFollowUpCancel = onCancel;
+            const enabled = available && onRequest !== undefined && onCancel !== undefined;
+            internals.followUpAvailable = enabled;
+            internals.state.followUpAvailable = enabled;
+            if (!enabled) {
+                internals.state.followUp = undefined;
+                if (internals.state.inputMode?.kind === 'follow-up')
+                    internals.state.inputMode = null;
+            }
+        },
+        setFollowUpState(state) {
+            if (!internals.mounted || !internals.state.followUpAvailable)
+                return;
+            internals.state.followUp = state;
+        },
         canAcceptHostKeys() {
             if (!internals.mounted)
                 return false;
@@ -264,24 +317,11 @@ export function mountPanel(opts) {
  * returned `deck` is the one actually answered (post-reload).
  */
 export async function resolveInteractionDir(dir, deck, opts = {}) {
-    let conversationContext = '';
-    if (opts.sessionId !== undefined) {
-        try {
-            const conv = readConversation(opts.sessionId);
-            conversationContext = conv.map((m) => `${m.role}: ${m.content}`).join('\n\n');
-        }
-        catch {
-            // empty context — proceed without visuals context
-        }
-    }
     setupTerminal();
     const term = getTerminalSize();
     const cols = opts.cols ?? term.cols;
     const rows = opts.rows ?? term.rows;
-    const generateVisual = opts.generateVisual ??
-        (opts.sessionId !== undefined
-            ? (interaction) => defaultGenerateVisual(interaction, conversationContext)
-            : undefined);
+    const generateVisual = opts.generateVisual ?? (opts.sessionId === undefined ? undefined : visualGeneratorForConversationSession(opts.sessionId));
     return new Promise((resolve) => {
         let panel = null;
         let prevFrameLocal = [];
@@ -369,6 +409,11 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             cols,
             rows,
             generateVisual,
+            onEditorRequest: () => {
+                const buffer = panel?.getInputBuffer();
+                if (buffer !== undefined)
+                    runEditorEscapeHatch(buffer);
+            },
             onProgress: (responses) => {
                 lastResponses = responses;
                 if (panel !== null)
@@ -444,68 +489,22 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
                 return;
             process.stdin.removeListener('data', onData);
             process.stdout.removeListener('resize', onResize);
-            const tmpFile = join(tmpdir(), `hl-input-${randomUUID()}.txt`);
-            const editor = process.env.EDITOR || 'vi';
-            let next = buffer;
-            let errorMessage = null;
-            // Everything from suspending the TUI through the editor round-trip can
-            // throw (tmpfile write, spawn, readback) — a tmpdir write failure alone
-            // (e.g. /tmp full) used to escape with the listeners detached and the
-            // real terminal never restored. The try/finally below guarantees the
-            // finally branch — tmpfile cleanup, TUI restore, listener re-attach,
-            // resize-aware redraw — runs on every path, success or failure.
+            let result = { text: buffer };
             try {
                 restoreTerminal();
-                writeFileSync(tmpFile, buffer);
-                // $EDITOR is conventionally a shell fragment, not a bare binary —
-                // "code --wait", "emacsclient -t" — so run it through the shell (as
-                // git does) with the filename passed safely as a positional arg.
-                const result = spawnSync('/bin/sh', ['-c', `${editor} "$1"`, 'sh', tmpFile], { stdio: 'inherit' });
-                if (result.error) {
-                    errorMessage = `$EDITOR ("${editor}") failed to launch: ${result.error.message}`;
-                }
-                else if (result.signal !== null) {
-                    errorMessage = `$EDITOR ("${editor}") was killed by signal ${result.signal}`;
-                }
-                else if (result.status === 127 || result.status === 126) {
-                    // Shell couldn't exec the editor: 127 = not found, 126 = not executable.
-                    errorMessage = `$EDITOR ("${editor}") failed to launch (shell exit ${result.status})`;
-                }
-                else if (result.status !== 0) {
-                    errorMessage = `$EDITOR ("${editor}") exited with status ${result.status}`;
-                }
-                else {
-                    let read = readFileSync(tmpFile, 'utf8');
-                    // Editors conventionally append a trailing newline on save; strip
-                    // exactly one so a round-trip that added nothing doesn't grow the
-                    // buffer by a blank line.
-                    if (read.endsWith('\n') && !buffer.endsWith('\n'))
-                        read = read.slice(0, -1);
-                    next = read;
-                }
-            }
-            catch (err) {
-                errorMessage = `$EDITOR round-trip failed: ${err instanceof Error ? err.message : String(err)}`;
+                result = editBufferInEditor(buffer);
             }
             finally {
-                try {
-                    unlinkSync(tmpFile);
-                }
-                catch { /* best-effort cleanup — may never have been created */ }
                 setupTerminal();
                 process.stdin.on('data', onData);
                 process.stdout.on('resize', onResize);
-                // On any failure the original buffer is kept untouched. Re-sample the
-                // terminal size (it may have changed while the editor had it) so the
-                // post-editor redraw lays out for the CURRENT dimensions rather than
-                // the panel's stale cols/rows, same as the live resize listener does.
-                panel.setInputBuffer(errorMessage === null ? next : buffer);
+                panel.setInputBuffer(result.text);
                 const { cols: c, rows: r } = getTerminalSize();
                 const lines = panel.handleResize(c, r);
-                if (errorMessage !== null) {
+                if (result.error !== undefined) {
                     while (lines.length < r)
                         lines.push('');
-                    lines[r - 1] = `  ${errorMessage}`.slice(0, c);
+                    lines[r - 1] = `  ${result.error}`.slice(0, c);
                 }
                 prevFrameLocal = [];
                 process.stdout.write('\x1b[2J\x1b[H');
@@ -583,13 +582,6 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
                 }
                 return;
             }
-            if (key.ctrl && inp === 'o') {
-                const buf = panel.getInputBuffer();
-                if (buf !== undefined) {
-                    runEditorEscapeHatch(buf);
-                    return;
-                }
-            }
             // 'w' hands the current interaction off to the browser. Gated on
             // canAcceptHostKeys() (not mid comment/freetext) so it never shadows a
             // literal 'w' typed into a buffer; 'w' is also reserved from option

package/dist/tui/input.d.ts

@@ -2,5 +2,9 @@ import type { TuiState, Interaction } from '../types.js';
 import type { Key } from './terminal.js';
 export type RenderFn = () => void;
 export type ExitFn = () => void;
+export interface FollowUpActions {
+    request(question: string): void;
+    cancel(): void;
+}
 export declare function assignShortcuts(interactions: Interaction[]): void;
-export declare function handleKeypress(input: string, key: Key, state: TuiState, render: RenderFn, exit: ExitFn): void;
+export declare function handleKeypress(input: string, key: Key, state: TuiState, render: RenderFn, exit: ExitFn, followUp?: FollowUpActions): void;

package/dist/tui/input.js

@@ -1,7 +1,7 @@
 // 'w' is reserved for the host-level "open in browser" handoff (see
 // tui/app.ts resolveInteractionDir) — never auto-assignable as an option
 // shortcut, or pressing it would race the handoff against picking that option.
-const RESERVED = new Set(['c', 'r', 'n', 'p', 'q', 'j', 'k', 'u', 'd', 'w', ' ']);
+const RESERVED = new Set(['c', 'r', 'n', 'p', 'q', 'j', 'k', 'u', 'd', 'w', ' ', '?']);
 export function assignShortcuts(interactions) {
     for (const it of interactions) {
         const used = new Set(it.options.map((o) => o.shortcut).filter((s) => s !== undefined));
@@ -32,7 +32,14 @@ export function assignShortcuts(interactions) {
         }
     }
 }
-export function handleKeypress(input, key, state, render, exit) {
+export function handleKeypress(input, key, state, render, exit, followUp) {
+    if (key.backTab) {
+        state.bodyScrollOffsets[state.bodyMode] = state.scrollOffset;
+        state.bodyMode = state.bodyMode === 'question' ? 'visual' : 'question';
+        state.scrollOffset = state.bodyScrollOffsets[state.bodyMode];
+        render();
+        return;
+    }
     if (key.ctrl && input === 'c') {
         exit();
         return;
@@ -42,7 +49,7 @@ export function handleKeypress(input, key, state, render, exit) {
     // render cycle.
     state.hint = undefined;
     if (state.inputMode) {
-        handleInputMode(input, key, state, render);
+        handleInputMode(input, key, state, render, followUp);
         checkAutoExit(state, exit);
         return;
     }
@@ -51,7 +58,7 @@ export function handleKeypress(input, key, state, render, exit) {
             handleOverview(input, key, state, render, exit);
             break;
         case 'item-review':
-            handleItemReview(input, key, state, render);
+            handleItemReview(input, key, state, render, followUp);
             checkAutoExit(state, exit);
             break;
         case 'final':
@@ -91,7 +98,8 @@ function handleOverview(input, key, state, render, exit) {
     if (key.return || input === ' ') {
         state.phase = 'item-review';
         state.selectedAction = 0;
-        state.detailExpanded = false;
+        state.bodyMode = 'question';
+        state.scrollOffset = state.bodyScrollOffsets.question;
         render();
         return;
     }
@@ -124,7 +132,15 @@ function handleOverview(input, key, state, render, exit) {
     }
 }
 // ── Item Review ──────────────────────────────────────────────────────────────
-function handleItemReview(input, key, state, render) {
+function handleItemReview(input, key, state, render, followUp) {
+    if (input === '?' && state.followUpAvailable) {
+        if (state.followUp?.status === 'running')
+            followUp?.cancel();
+        else
+            state.inputMode = { kind: 'follow-up', buffer: '', cursor: 0 };
+        render();
+        return;
+    }
     const interaction = state.interactions[state.currentIndex];
     if (input === 'n') {
         advanceItem(state, 1);
@@ -138,22 +154,18 @@ function handleItemReview(input, key, state, render) {
     }
     // q / Esc step back to the deck overview (one level up from a card).
     if (input === 'q' || key.escape) {
+        state.bodyScrollOffsets[state.bodyMode] = state.scrollOffset;
         state.phase = 'overview';
         render();
         return;
     }
-    // Space toggles the focused option for multi-select; otherwise expand context.
+    // Space toggles the focused option for multi-select.
     if (input === ' ' && interaction.multiSelect
         && state.selectedAction < interaction.options.length) {
         toggleMulti(state, interaction, interaction.options[state.selectedAction].id);
         render();
         return;
     }
-    if (input === ' ') {
-        state.detailExpanded = !state.detailExpanded;
-        render();
-        return;
-    }
     // Body scroll: u/d, PageUp/PageDown, or Ctrl+D / Ctrl+U (half-page), Ctrl+E / Ctrl+Y (line).
     // Plain u/d exists because tmux configs commonly bind C-d/C-u for pane scroll
     // and intercept them before they reach the app. Render clamps state.scrollOffset,
@@ -273,8 +285,20 @@ function handleInteractionAction(input, key, state, interaction, render) {
     }
 }
 // ── Input Mode ───────────────────────────────────────────────────────────────
-function handleInputMode(input, key, state, render) {
+function handleInputMode(input, key, state, render, followUp) {
     const mode = state.inputMode;
+    if (mode.kind === 'follow-up' && key.return) {
+        const question = mode.buffer.trim();
+        if (question.length === 0) {
+            state.hint = 'Enter a question, or esc to cancel';
+            render();
+            return;
+        }
+        followUp?.request(question);
+        state.inputMode = null;
+        render();
+        return;
+    }
     if (key.escape) {
         state.inputMode = null;
         render();
@@ -549,8 +573,9 @@ function advanceItem(state, direction) {
     }
     state.currentIndex = next;
     state.selectedAction = 0;
-    state.detailExpanded = false;
+    state.bodyMode = 'question';
     state.scrollOffset = 0;
+    state.bodyScrollOffsets = { question: 0, visual: 0 };
 }
 /**
  * Move to the next interaction WITHOUT a response, falling through to the
@@ -570,8 +595,9 @@ function advanceToNextUnanswered(state) {
     }
     state.currentIndex = next;
     state.selectedAction = 0;
-    state.detailExpanded = false;
+    state.bodyMode = 'question';
     state.scrollOffset = 0;
+    state.bodyScrollOffsets = { question: 0, visual: 0 };
 }
 function actionCount(interaction) {
     return interaction.options.length + (interaction.allowFreetext && interaction.options.length > 0 ? 1 : 0);

package/dist/tui/log.d.ts

@@ -0,0 +1,2 @@
+export declare function popupLogPath(): string;
+export declare function logPopupEvent(event: string, fields?: Record<string, unknown>): void;

package/dist/tui/log.js

@@ -0,0 +1,53 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const MAX_BYTES = 5 * 1024 * 1024;
+const ROTATIONS = 2;
+function stateHome() {
+    return process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state');
+}
+export function popupLogPath() {
+    return join(stateHome(), 'humanloop', 'inbox-popup.log');
+}
+function rotateIfNeeded(path, nextLineBytes) {
+    if (!existsSync(path))
+        return;
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return;
+    }
+    if (size + nextLineBytes < MAX_BYTES)
+        return;
+    try {
+        rmSync(`${path}.${ROTATIONS}`, { force: true });
+    }
+    catch { /* best-effort */ }
+    for (let index = ROTATIONS - 1; index >= 1; index -= 1) {
+        const source = `${path}.${index}`;
+        const target = `${path}.${index + 1}`;
+        try {
+            if (existsSync(source))
+                renameSync(source, target);
+        }
+        catch { /* best-effort */ }
+    }
+    try {
+        renameSync(path, `${path}.1`);
+    }
+    catch { /* best-effort */ }
+}
+export function logPopupEvent(event, fields = {}) {
+    const path = popupLogPath();
+    const line = JSON.stringify({ ts: new Date().toISOString(), component: 'inbox-popup', event, ...fields });
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        rotateIfNeeded(path, Buffer.byteLength(`${line}\n`, 'utf8'));
+        appendFileSync(path, `${line}\n`, 'utf8');
+    }
+    catch {
+        /* Logging is best-effort so the inbox shortcut remains available. */
+    }
+}

package/dist/tui/render.js

@@ -134,30 +134,46 @@ function buildItemReviewLayout(state, cols, rows) {
     // and live in the scrollable region so long content never overflows the fixed
     // header — agents put rich prose in either field, so both must render markdown.
     const bodyLines = [];
-    if (interaction.subtitle) {
-        bodyLines.push('');
-        for (const line of renderMarkdown(interaction.subtitle, maxW)) {
-            bodyLines.push(`  ${line}`);
+    if (state.bodyMode === 'question') {
+        if (interaction.subtitle) {
+            bodyLines.push('');
+            for (const line of renderMarkdown(interaction.subtitle, maxW)) {
+                bodyLines.push(`  ${line}`);
+            }
         }
-    }
-    if (interaction.body) {
-        bodyLines.push('');
-        for (const line of renderMarkdown(interaction.body, maxW)) {
-            bodyLines.push(`  ${line}`);
+        if (interaction.body) {
+            bodyLines.push('');
+            for (const line of renderMarkdown(interaction.body, maxW)) {
+                bodyLines.push(`  ${line}`);
+            }
         }
     }
-    if (visual && visual.status === 'ready' && state.detailExpanded) {
-        bodyLines.push('');
-        bodyLines.push(`  ${DIM}── context ${hline(maxW - 12)}${RESET}`);
-        for (const vl of visual.content.split('\n')) {
-            bodyLines.push(`  ${vl}`);
+    if (state.bodyMode === 'visual') {
+        if (visual?.status === 'ready') {
+            bodyLines.push('');
+            bodyLines.push(`  ${DIM}── context ${hline(maxW - 12)}${RESET}`);
+            for (const vl of visual.content.split('\n')) {
+                bodyLines.push(`  ${vl}`);
+            }
+            bodyLines.push(`  ${DIM}${hline(maxW)}${RESET}`);
+        }
+        if (state.followUp !== undefined && state.followUp.status !== 'idle') {
+            bodyLines.push('');
+            bodyLines.push(`  ${DIM}── follow-up ${hline(Math.max(0, maxW - 14))}${RESET}`);
+            if (state.followUp.status === 'running')
+                bodyLines.push(`  ${DIM}consulting…${RESET}`);
+            else if (state.followUp.status === 'ready') {
+                for (const line of renderMarkdown(state.followUp.markdown, maxW))
+                    bodyLines.push(`  ${line}`);
+            }
+            else
+                bodyLines.push(`  ${YELLOW}${state.followUp.error}${RESET}`);
         }
-        bodyLines.push(`  ${DIM}${hline(maxW)}${RESET}`);
     }
     // Post-body: visual status hint, input buffer or actions, footer (always visible)
     const postLines = [];
     postLines.push('');
-    if (visual) {
+    if (state.bodyMode === 'visual' && visual) {
         if (visual.status === 'loading') {
             postLines.push(`  ${DIM}loading context...${RESET}`);
             postLines.push('');
@@ -166,10 +182,6 @@ function buildItemReviewLayout(state, cols, rows) {
             postLines.push(`  ${YELLOW}visual context unavailable${RESET}`);
             postLines.push('');
         }
-        else if (!state.detailExpanded) {
-            postLines.push(`  ${DIM}[space] expand context${RESET}`);
-            postLines.push('');
-        }
     }
     if (state.inputMode) {
         postLines.push(`  ${DIM}${hline(maxW)}${RESET}`);
@@ -204,7 +216,7 @@ function buildItemReviewLayout(state, cols, rows) {
             postLines.push(attachedLine);
         }
         postLines.push('');
-        postLines.push(`  ${DIM}enter${RESET} submit  ${DIM}^J/⌥⏎${RESET} newline  ${DIM}^O${RESET} editor  ${DIM}esc${RESET} cancel`);
+        postLines.push(`  ${DIM}enter${RESET} submit  ${DIM}^J/⌥⏎${RESET} newline${state.editorAvailable ? `  ${DIM}^O${RESET} editor` : ''}  ${DIM}esc${RESET} cancel`);
     }
     else {
         postLines.push(...renderActions(interaction, state.selectedAction, maxW, response));
@@ -236,6 +248,7 @@ function buildItemReviewLayout(state, cols, rows) {
 export function clampItemReviewScroll(state, cols, rows) {
     const { maxScroll } = buildItemReviewLayout(state, cols, rows);
     state.scrollOffset = Math.max(0, Math.min(state.scrollOffset || 0, maxScroll));
+    state.bodyScrollOffsets[state.bodyMode] = state.scrollOffset;
 }
 export function renderItemReview(state, cols, rows) {
     const { interaction, preLines, bodyLines, postLines, maxW, bodyHeight, maxScroll, overflows } = buildItemReviewLayout(state, cols, rows);
@@ -262,18 +275,22 @@ export function renderItemReview(state, cols, rows) {
             `${DIM}n/p${RESET} prev/next`,
             `${DIM}space${RESET} toggle`,
             `${DIM}enter${RESET} confirm`,
+            `${DIM}shift-tab${RESET} ${state.bodyMode === 'question' ? 'visual' : 'question'}`,
             `${DIM}q${RESET} overview`,
         ]
         : [
             `${DIM}n/p${RESET} prev/next`,
-            `${DIM}space${RESET} expand`,
+            `${DIM}shift-tab${RESET} ${state.bodyMode === 'question' ? 'visual' : 'question'}`,
             `${DIM}q${RESET} overview`,
         ];
     if (overflows) {
         footerParts.unshift(state.inputMode ? `${DIM}pgup/pgdn${RESET} scroll` : `${DIM}u/d${RESET} scroll`);
     }
-    if (state.inputMode === null)
+    if (state.inputMode === null) {
+        if (state.followUpAvailable)
+            footerParts.push(`${DIM}?${RESET} follow-up`);
         footerParts.push(`${DIM}w${RESET} browser`);
+    }
     const footer = `  ${footerParts.join('  ')}`;
     // Assemble — pad to fill rows so post-body sits at the bottom
     const lines = [...preLines, ...visibleBody, ...postLines];

package/dist/tui/terminal.d.ts

@@ -19,6 +19,7 @@ export interface Key {
     ctrl: boolean;
     meta: boolean;
     tab: boolean;
+    backTab: boolean;
     backspace: boolean;
 }
 export type KeypressHandler = (input: string, key: Key) => void;

package/dist/tui/terminal.js

@@ -17,6 +17,7 @@ function emptyKey() {
         ctrl: false,
         meta: false,
         tab: false,
+        backTab: false,
         backspace: false,
     };
 }
@@ -69,6 +70,10 @@ export function parseKeypress(data) {
         key.del = true;
         return { input: '', key };
     }
+    if (str === '\x1b[Z') {
+        key.backTab = true;
+        return { input: '', key };
+    }
     // Alt+Enter inserts a newline in freetext (distinct from Enter=submit). Must
     // precede the bare-ESC and meta-backspace checks so the two-byte sequence
     // isn't swallowed as a lone escape.