@crouton-kit/humanloop 0.3.21 → 0.3.23

package/dist/tui/app.js

@@ -1,7 +1,10 @@
 import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync } from 'fs';
-import { dirname, resolve as resolvePath } from 'node:path';
+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 { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize } from './terminal.js';
-import { diffFrame, renderOverview, renderItemReview, renderFinal } from './render.js';
+import { diffFrame, renderOverview, renderItemReview, renderFinal, clampItemReviewScroll } from './render.js';
 import { handleKeypress, assignShortcuts } from './input.js';
 import { readConversation } from '../conversation/reader.js';
 import { defaultGenerateVisual } from '../visuals/generate.js';
@@ -113,12 +116,14 @@ function fireVisuals(internals, interactions) {
             internals.state.visuals.set(interaction.id, r.ok
                 ? { questionId: interaction.id, content: r.ansi, status: 'ready' }
                 : { questionId: interaction.id, content: '', status: 'error' });
+            internals.callbacks.onDirty?.();
         }).catch(() => {
             if (!internals.mounted)
                 return;
             if (!internals.state.interactions.some((x) => x.id === interaction.id))
                 return;
             internals.state.visuals.set(interaction.id, { questionId: interaction.id, content: '', status: 'error' });
+            internals.callbacks.onDirty?.();
         });
     }
 }
@@ -130,7 +135,7 @@ export function mountPanel(opts) {
         mounted: true,
         generateVisual: opts.generateVisual,
         progressPath: opts.progressPath,
-        callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit },
+        callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit, onDirty: opts.onDirty },
     };
     assignShortcuts(internals.state.interactions);
     rebindPersist(internals);
@@ -168,6 +173,11 @@ export function mountPanel(opts) {
                     internals.callbacks.onExit?.();
                 }
             });
+            // Pre-render clamp (input layer): keep scrollOffset within the current
+            // body's bounds so u/d stay responsive. The renderer itself is pure.
+            if (internals.state.phase === 'item-review') {
+                clampItemReviewScroll(internals.state, internals.cols, internals.rows);
+            }
         },
         render() {
             if (!internals.mounted)
@@ -177,6 +187,10 @@ export function mountPanel(opts) {
         handleResize(cols, rows) {
             internals.cols = cols;
             internals.rows = rows;
+            // New dimensions change the scroll bounds — re-clamp before laying out.
+            if (internals.state.phase === 'item-review') {
+                clampItemReviewScroll(internals.state, cols, rows);
+            }
             return renderLines();
         },
         unmount() {
@@ -208,6 +222,17 @@ export function mountPanel(opts) {
                 return true;
             return internals.state.phase === 'overview' && internals.state.inputMode === null;
         },
+        getInputBuffer() {
+            if (!internals.mounted || internals.state.inputMode === null)
+                return undefined;
+            return internals.state.inputMode.buffer;
+        },
+        setInputBuffer(text) {
+            if (!internals.mounted || internals.state.inputMode === null)
+                return;
+            internals.state.inputMode.buffer = text;
+            internals.state.inputMode.cursor = [...text].length;
+        },
     };
 }
 /**
@@ -254,14 +279,26 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
         let currentDeck = deck;
         let deckWatch = null;
         const flushHost = (lines) => {
-            const { rows: currentRows } = getTerminalSize();
-            const { writes, nextPrevFrame } = diffFrame(prevFrameLocal, lines, currentRows);
+            const { cols: currentCols, rows: currentRows } = getTerminalSize();
+            const { writes, nextPrevFrame } = diffFrame(prevFrameLocal, lines, currentRows, currentCols);
             process.stdout.write('\x1b[?2026h');
             for (const w of writes)
                 process.stdout.write(w);
             process.stdout.write('\x1b[?2026l');
             prevFrameLocal = nextPrevFrame;
         };
+        // On resize the terminal reflows/scrolls existing content, so the diff
+        // model no longer matches the screen: re-layout at the new size, clear
+        // everything, and redraw from scratch.
+        const onResize = () => {
+            if (panel === null)
+                return;
+            const { cols: c, rows: r } = getTerminalSize();
+            const lines = panel.handleResize(c, r);
+            prevFrameLocal = [];
+            process.stdout.write('\x1b[2J\x1b[H');
+            flushHost(lines);
+        };
         const finalize = (responses) => {
             if (deckWatch !== null) {
                 clearInterval(deckWatch);
@@ -269,10 +306,11 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             }
             restoreTerminal();
             process.stdin.removeListener('data', onData);
+            process.stdout.removeListener('resize', onResize);
             panel?.unmount();
             const completedAt = new Date().toISOString();
             // Resolved supersedes in-progress: write response.json, drop progress.json.
-            const rp = writeResponse(dir, responses, completedAt);
+            const rp = writeResponse(dir, responses, completedAt, currentDeck);
             clearProgress(dir);
             resolve({ responses, completedAt, responsePath: rp, deck: currentDeck });
         };
@@ -291,6 +329,12 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             onExit: () => {
                 finalize(lastResponses);
             },
+            // Async visual finished loading between keystrokes — repaint so the
+            // "loading context..." placeholder is replaced immediately.
+            onDirty: () => {
+                if (panel !== null)
+                    flushHost(panel.render());
+            },
         });
         flushHost(panel.render());
         // ── Live deck reload ──────────────────────────────────────────────────
@@ -336,12 +380,90 @@ export async function resolveInteractionDir(dir, deck, opts = {}) {
             panel.loadDeck(nextDeck, { progressPath: progressPathFor(dir) });
             flushHost(panel.render());
         }, 500);
+        // $EDITOR escape hatch (ctrl+o): the host owns the stdin listener + raw
+        // mode, so it — not handleInputMode — is where the editor round-trip has
+        // to live. Detected here before delegating to the panel; only acts while
+        // an input-mode buffer exists (panel.getInputBuffer() undefined otherwise).
+        const runEditorEscapeHatch = (buffer) => {
+            if (panel === null)
+                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.
+            try {
+                restoreTerminal();
+                writeFileSync(tmpFile, buffer);
+                const result = spawnSync(editor, [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 !== 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)}`;
+            }
+            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);
+                const { cols: c, rows: r } = getTerminalSize();
+                const lines = panel.handleResize(c, r);
+                if (errorMessage !== null) {
+                    while (lines.length < r)
+                        lines.push('');
+                    lines[r - 1] = `  ${errorMessage}`.slice(0, c);
+                }
+                prevFrameLocal = [];
+                process.stdout.write('\x1b[2J\x1b[H');
+                flushHost(lines);
+            }
+        };
         onData = (data) => {
             const { input: inp, key } = parseKeypress(data);
+            if (key.ctrl && inp === 'o') {
+                const buf = panel.getInputBuffer();
+                if (buf !== undefined) {
+                    runEditorEscapeHatch(buf);
+                    return;
+                }
+            }
             panel.handleKey(inp, key);
             flushHost(panel.render());
         };
         process.stdin.on('data', onData);
+        process.stdout.on('resize', onResize);
     });
 }
 // ── launchTui — file-path entry over the dir resolver (a kept public export

package/dist/tui/input.js

@@ -211,7 +211,7 @@ function handleInteractionAction(input, key, state, interaction, render) {
                 if (typeof prior === 'string')
                     prefill = prior;
             }
-            state.inputMode = { kind: 'comment', buffer: prefill, selectedOptionId: optId };
+            state.inputMode = { kind: 'comment', buffer: prefill, cursor: [...prefill].length, selectedOptionId: optId };
         }
         else {
             // On the [c] row in multi-select: pre-fill from existing overall freetext.
@@ -222,7 +222,7 @@ function handleInteractionAction(input, key, state, interaction, render) {
                     prefill = existing.freetext;
                 }
             }
-            state.inputMode = { kind: 'comment', buffer: prefill };
+            state.inputMode = { kind: 'comment', buffer: prefill, cursor: [...prefill].length };
         }
         render();
         return;
@@ -232,7 +232,7 @@ function handleInteractionAction(input, key, state, interaction, render) {
         if (input === 'r' || key.return) {
             const existing = state.responses.get(interaction.id);
             const prefill = existing !== undefined && existing.freetext !== undefined ? existing.freetext : '';
-            state.inputMode = { kind: 'freetext', buffer: prefill };
+            state.inputMode = { kind: 'freetext', buffer: prefill, cursor: [...prefill].length };
             render();
             return;
         }
@@ -264,7 +264,7 @@ function handleInteractionAction(input, key, state, interaction, render) {
     // Enter on the [c] row (allowFreetext + options exist)
     if (key.return && state.selectedAction === opts.length
         && interaction.allowFreetext && opts.length > 0) {
-        state.inputMode = { kind: 'comment', buffer: '' };
+        state.inputMode = { kind: 'comment', buffer: '', cursor: 0 };
         render();
         return;
     }
@@ -321,43 +321,155 @@ function handleInputMode(input, key, state, render) {
         render();
         return;
     }
+    // Newline-insert chord (ctrl+j / alt+enter) — distinct from key.return
+    // (submit), handled above.
+    if (key.newline) {
+        insertAtCursor(mode, '\n');
+        render();
+        return;
+    }
+    // ── Cursor motion ──────────────────────────────────────────────────────
+    if (key.leftArrow) {
+        mode.cursor = Math.max(0, mode.cursor - 1);
+        render();
+        return;
+    }
+    if (key.rightArrow) {
+        mode.cursor = Math.min([...mode.buffer].length, mode.cursor + 1);
+        render();
+        return;
+    }
+    if (key.wordLeft) {
+        mode.cursor = wordLeftIndex(mode.buffer, mode.cursor);
+        render();
+        return;
+    }
+    if (key.wordRight) {
+        mode.cursor = wordRightIndex(mode.buffer, mode.cursor);
+        render();
+        return;
+    }
+    if (key.home || (key.ctrl && input === 'a')) {
+        mode.cursor = lineStart(mode.buffer, mode.cursor);
+        render();
+        return;
+    }
+    if (key.end || (key.ctrl && input === 'e')) {
+        mode.cursor = lineEnd(mode.buffer, mode.cursor);
+        render();
+        return;
+    }
+    // ── Edits ───────────────────────────────────────────────────────────────
     if (key.backspace && key.meta) {
-        mode.buffer = deleteWordBack(mode.buffer);
+        deleteWordAtCursor(mode);
         render();
         return;
     }
-    // Ctrl-U: delete to the start of the line (readline "unix-line-discard").
+    // Ctrl-U: delete from line start to cursor (readline "unix-line-discard").
     // iTerm2 maps Cmd+Backspace to a bare 0x15, which arrives here as ctrl+'u'.
-    // The buffer is end-anchored (no mid-string cursor), so "to line start" is
-    // the entire buffer.
     if (key.ctrl && input === 'u') {
-        mode.buffer = '';
+        deleteToLineStart(mode);
+        render();
+        return;
+    }
+    if (key.del) {
+        deleteAtCursor(mode);
         render();
         return;
     }
     if (key.backspace) {
-        const chars = [...mode.buffer];
-        chars.pop();
-        mode.buffer = chars.join('');
+        backspaceAtCursor(mode);
         render();
         return;
     }
+    // Typed input / paste. Bracketed-paste markers and other control chars are
+    // stripped, but \n (0x0A) is preserved so pasted newlines land as real
+    // newlines in the buffer instead of vanishing (CRLF is normalized to LF).
     const cleaned = input
         .replace(/\x1b\[20[01]~/g, '')
         .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
-        .replace(/[\x00-\x1F\x7F]/g, '');
+        .replace(/\r\n?/g, '\n')
+        .replace(/[\x00-\x09\x0B-\x1F\x7F]/g, '');
     if (cleaned.length > 0) {
-        mode.buffer += cleaned;
+        insertAtCursor(mode, cleaned);
         render();
     }
 }
-function deleteWordBack(buffer) {
+function insertAtCursor(mode, text) {
+    const chars = [...mode.buffer];
+    const insert = [...text];
+    chars.splice(mode.cursor, 0, ...insert);
+    mode.buffer = chars.join('');
+    mode.cursor += insert.length;
+}
+function backspaceAtCursor(mode) {
+    if (mode.cursor <= 0)
+        return;
+    const chars = [...mode.buffer];
+    chars.splice(mode.cursor - 1, 1);
+    mode.buffer = chars.join('');
+    mode.cursor -= 1;
+}
+function deleteAtCursor(mode) {
+    const chars = [...mode.buffer];
+    if (mode.cursor >= chars.length)
+        return;
+    chars.splice(mode.cursor, 1);
+    mode.buffer = chars.join('');
+}
+function deleteWordAtCursor(mode) {
+    const start = wordLeftIndex(mode.buffer, mode.cursor);
+    const chars = [...mode.buffer];
+    chars.splice(start, mode.cursor - start);
+    mode.buffer = chars.join('');
+    mode.cursor = start;
+}
+function deleteToLineStart(mode) {
+    const start = lineStart(mode.buffer, mode.cursor);
+    const chars = [...mode.buffer];
+    chars.splice(start, mode.cursor - start);
+    mode.buffer = chars.join('');
+    mode.cursor = start;
+}
+/** Skip whitespace backward from `cursor`, then skip the non-whitespace word
+ *  before it — lands on the word's start (readline alt-b / ctrl+left). */
+function wordLeftIndex(buffer, cursor) {
+    const chars = [...buffer];
+    let i = Math.min(cursor, chars.length);
+    while (i > 0 && /\s/.test(chars[i - 1]))
+        i--;
+    while (i > 0 && !/\s/.test(chars[i - 1]))
+        i--;
+    return i;
+}
+/** Skip whitespace forward from `cursor`, then skip the non-whitespace word
+ *  after it — lands just past the word's end (readline alt-f / ctrl+right). */
+function wordRightIndex(buffer, cursor) {
+    const chars = [...buffer];
+    let i = Math.min(cursor, chars.length);
+    while (i < chars.length && /\s/.test(chars[i]))
+        i++;
+    while (i < chars.length && !/\s/.test(chars[i]))
+        i++;
+    return i;
+}
+/** Index just after the previous `\n` (or 0), i.e. the start of the current
+ *  visual line — the multiline analog of ctrl+a/home. */
+function lineStart(buffer, cursor) {
+    const chars = [...buffer];
+    let i = Math.min(cursor, chars.length);
+    while (i > 0 && chars[i - 1] !== '\n')
+        i--;
+    return i;
+}
+/** Index at the next `\n` (or end of buffer) — the multiline analog of
+ *  ctrl+e/end. */
+function lineEnd(buffer, cursor) {
     const chars = [...buffer];
-    while (chars.length > 0 && /\s/.test(chars[chars.length - 1]))
-        chars.pop();
-    while (chars.length > 0 && !/\s/.test(chars[chars.length - 1]))
-        chars.pop();
-    return chars.join('');
+    let i = Math.min(cursor, chars.length);
+    while (i < chars.length && chars[i] !== '\n')
+        i++;
+    return i;
 }
 // ── Final ────────────────────────────────────────────────────────────────────
 function handleFinal(input, key, state, render, exit) {

package/dist/tui/render.d.ts

@@ -1,10 +1,26 @@
 import type { TuiState, Interaction, InteractionResponse } from '../types.js';
-export declare function sanitize(text: string): string;
-export declare function diffFrame(prevFrame: string[], nextLines: string[], rows: number): {
+export declare function diffFrame(prevFrame: string[], nextLines: string[], rows: number, cols?: number): {
     writes: string[];
     nextPrevFrame: string[];
 };
 export declare function renderOverview(state: TuiState, cols: number, rows: number): string[];
+/**
+ * Render a (possibly multiline) input buffer with a visible cursor at
+ * `cursor` (a code-point index). A private-use sentinel is inserted at the
+ * cursor position, the result is hard-wrapped (so `\n` and width-wrapping
+ * behave exactly as they would without a cursor), then the sentinel is
+ * swapped for a reverse-video block on whichever wrapped line it landed on.
+ * `stringWidth('\uE000') === 1`, so it occupies exactly one column and never
+ * throws off the wrap math.
+ */
+export declare function renderInputBuffer(buffer: string, cursor: number, maxWidth: number): string[];
+/**
+ * Clamp state.scrollOffset to the current body's scroll bounds. The host runs
+ * this as a pre-render step (from the input path) so `renderItemReview` stays a
+ * pure function of state — the clamp keeps u/d scrolling responsive without the
+ * renderer mutating state mid-frame.
+ */
+export declare function clampItemReviewScroll(state: TuiState, cols: number, rows: number): void;
 export declare function renderItemReview(state: TuiState, cols: number, rows: number): string[];
 export declare function renderFinal(state: TuiState, cols: number, rows: number): string[];
 export declare function responseSummary(r: InteractionResponse, interaction: Interaction): string;