@crouton-kit/humanloop 0.3.22 → 0.3.23

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,18 +1,26 @@
 import type { TuiState, Interaction, InteractionResponse } from '../types.js';
-export declare function sanitize(text: string): string;
-/**
- * ANSI-aware clip: truncate a line's *visible* width to `maxWidth`, passing
- * escape sequences through untouched. Every line written to the terminal must
- * fit within the columns, or it physically wraps onto the next row — which
- * breaks diffFrame's one-logical-line-per-row model and strands spillover text
- * on rows the differ believes are empty (so it never erases them).
- */
-export declare function clipLine(line: string, maxWidth: number): string;
 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;

package/dist/tui/render.js

@@ -1,184 +1,6 @@
-import stringWidth from 'string-width';
 import { renderMarkdown } from '../render/termrender.js';
-// ── ANSI helpers ─────────────────────────────────────────────────────────────
-const ESC = '\x1b[';
-const RESET = `${ESC}0m`;
-const BOLD = `${ESC}1m`;
-const DIM = `${ESC}2m`;
-const ITALIC = `${ESC}3m`;
-const GREEN = `${ESC}32m`;
-const YELLOW = `${ESC}33m`;
-const CYAN = `${ESC}36m`;
-const CONTROL_CHARS_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]|[\x00-\x08\x0B\x0E-\x1F\x7F-\x9F]/g;
-export function sanitize(text) {
-    if (typeof text !== 'string')
-        return '';
-    return text.replace(CONTROL_CHARS_RE, '');
-}
-function singleLine(text) {
-    return sanitize(text).replace(/\s+/g, ' ').trim();
-}
-function truncate(text, maxWidth) {
-    if (maxWidth < 1)
-        return '';
-    if (stringWidth(text) <= maxWidth)
-        return text;
-    const chars = [...text];
-    let w = 0;
-    let out = '';
-    for (const ch of chars) {
-        const cw = stringWidth(ch);
-        if (w + cw + 1 > maxWidth)
-            break;
-        out += ch;
-        w += cw;
-    }
-    return out + '…';
-}
-function padRight(text, width) {
-    const w = stringWidth(text);
-    if (w >= width)
-        return text;
-    return text + ' '.repeat(width - w);
-}
-function hline(width, char = '─') {
-    if (width < 1)
-        return '';
-    return char.repeat(width);
-}
-function wrap(text, maxWidth) {
-    if (maxWidth < 1)
-        return [text];
-    const out = [];
-    const paragraphs = text.split('\n');
-    for (let p = 0; p < paragraphs.length; p++) {
-        const para = paragraphs[p];
-        if (para === '') {
-            out.push('');
-            continue;
-        }
-        const words = para.split(/[ \t]+/).filter(Boolean);
-        let current = '';
-        for (let word of words) {
-            while (stringWidth(word) > maxWidth) {
-                if (current) {
-                    out.push(current);
-                    current = '';
-                }
-                const piece = sliceByWidth(word, maxWidth);
-                out.push(piece);
-                word = word.slice(piece.length);
-            }
-            const candidate = current ? `${current} ${word}` : word;
-            if (stringWidth(candidate) <= maxWidth) {
-                current = candidate;
-            }
-            else {
-                if (current)
-                    out.push(current);
-                current = word;
-            }
-        }
-        if (current)
-            out.push(current);
-    }
-    return out.length > 0 ? out : [''];
-}
-function sliceByWidth(s, maxWidth) {
-    let w = 0;
-    let out = '';
-    for (const ch of s) {
-        const cw = stringWidth(ch);
-        if (w + cw > maxWidth)
-            break;
-        out += ch;
-        w += cw;
-    }
-    if (out === '' && s.length > 0)
-        out = [...s][0];
-    return out;
-}
-function hardWrap(text, maxWidth) {
-    if (maxWidth < 1)
-        return [text];
-    const segments = text.split('\n');
-    const out = [];
-    for (const seg of segments) {
-        if (seg.length === 0) {
-            out.push('');
-            continue;
-        }
-        let current = '';
-        let currentW = 0;
-        for (const ch of [...seg]) {
-            const cw = stringWidth(ch);
-            if (currentW + cw > maxWidth) {
-                out.push(current);
-                current = ch;
-                currentW = cw;
-            }
-            else {
-                current += ch;
-                currentW += cw;
-            }
-        }
-        out.push(current);
-    }
-    return out;
-}
-// ── Horizontal centering ─────────────────────────────────────────────────────
-/**
- * Pad each non-empty line with leading spaces to horizontally center the
- * `contentWidth`-wide block within `cols`. Wide terminals (dashboard, full
- * screen) get visual breathing room; narrow panes (split tmux pane next to a
- * spawning agent) skip centering because there's nothing to center.
- *
- * Empty lines stay empty so frame diffing can keep them as cheap no-ops.
- */
-function centerHorizontal(lines, cols, contentWidth) {
-    const extraPad = Math.max(0, Math.floor((cols - contentWidth) / 2));
-    if (extraPad === 0)
-        return lines;
-    const pad = ' '.repeat(extraPad);
-    return lines.map((line) => (line === '' ? '' : pad + line));
-}
+import { ESC, RESET, BOLD, DIM, ITALIC, GREEN, YELLOW, CYAN, REVERSE, sanitize, singleLine, truncate, hline, wrap, hardWrap, centerHorizontal, clipLine, } from './ansi.js';
 // ── Frame buffer ─────────────────────────────────────────────────────────────
-/**
- * ANSI-aware clip: truncate a line's *visible* width to `maxWidth`, passing
- * escape sequences through untouched. Every line written to the terminal must
- * fit within the columns, or it physically wraps onto the next row — which
- * breaks diffFrame's one-logical-line-per-row model and strands spillover text
- * on rows the differ believes are empty (so it never erases them).
- */
-export function clipLine(line, maxWidth) {
-    if (maxWidth < 1)
-        return '';
-    if (stringWidth(line) <= maxWidth)
-        return line; // string-width ignores ANSI
-    let out = '';
-    let w = 0;
-    let i = 0;
-    let sawAnsi = false;
-    while (i < line.length) {
-        if (line[i] === '\x1b') {
-            const m = /^\x1b\[[0-9;?]*[a-zA-Z]|^\x1b[@-_]/.exec(line.slice(i));
-            if (m !== null) {
-                out += m[0];
-                i += m[0].length;
-                sawAnsi = true;
-                continue;
-            }
-        }
-        const ch = String.fromCodePoint(line.codePointAt(i));
-        const cw = stringWidth(ch);
-        if (w + cw > maxWidth)
-            break;
-        out += ch;
-        w += cw;
-        i += ch.length;
-    }
-    return sawAnsi ? out + RESET : out;
-}
 export function diffFrame(prevFrame, nextLines, rows, cols) {
     const clipped = cols !== undefined
         ? nextLines.map((l) => clipLine(l, cols))
@@ -260,7 +82,29 @@ export function renderOverview(state, cols, rows) {
     const centered = centerHorizontal(lines.slice(0, rows), cols, Math.min(cols, 60) + 2);
     return centered;
 }
-export function renderItemReview(state, cols, rows) {
+/**
+ * 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 function renderInputBuffer(buffer, cursor, maxWidth) {
+    const chars = [...buffer];
+    const at = Math.max(0, Math.min(cursor, chars.length));
+    const withCaret = [...chars.slice(0, at), '\uE000', ...chars.slice(at)].join('');
+    const wrapped = hardWrap(withCaret, maxWidth);
+    return wrapped.map((line) => (line.includes('\uE000') ? line.replace('\uE000', `${REVERSE} ${RESET}`) : line));
+}
+/**
+ * Build the item-review frame parts (pre/body/post) and derive the body's
+ * scroll bounds. Pure: reads state, mutates nothing. Both `renderItemReview`
+ * and the pre-render `clampItemReviewScroll` go through this, so the layout
+ * math has a single source of truth.
+ */
+function buildItemReviewLayout(state, cols, rows) {
     const interaction = state.interactions[state.currentIndex];
     const visual = state.visuals.get(interaction.id);
     const response = state.responses.get(interaction.id);
@@ -348,17 +192,15 @@ export function renderItemReview(state, cols, rows) {
         for (const labelLine of wrap(`${singleLine(label)}:`, maxW)) {
             postLines.push(`  ${YELLOW}${labelLine}${RESET}`);
         }
-        const bufLines = hardWrap(state.inputMode.buffer, maxW - 1);
-        for (let i = 0; i < bufLines.length; i++) {
-            const isLast = i === bufLines.length - 1;
-            postLines.push(`  ${bufLines[i]}${isLast ? '█' : ''}`);
-        }
+        const bufLines = renderInputBuffer(state.inputMode.buffer, state.inputMode.cursor, maxW - 1);
+        for (const line of bufLines)
+            postLines.push(`  ${line}`);
         if (attachedLine !== undefined) {
             postLines.push('');
             postLines.push(attachedLine);
         }
         postLines.push('');
-        postLines.push(`  ${DIM}enter${RESET} submit  ${DIM}esc${RESET} cancel`);
+        postLines.push(`  ${DIM}enter${RESET} submit  ${DIM}^J/⌥⏎${RESET} newline  ${DIM}^O${RESET} editor  ${DIM}esc${RESET} cancel`);
     }
     else {
         postLines.push(...renderActions(interaction, state.selectedAction, maxW, response));
@@ -371,14 +213,31 @@ export function renderItemReview(state, cols, rows) {
             postLines.push(`  ${YELLOW}${hintLine}${RESET}`);
         }
     }
-    // Window the body
+    // Derive the scroll window bounds. This builder never writes back into state
+    // — the host clamps state.scrollOffset via clampItemReviewScroll before render.
     const reservedRows = preLines.length + postLines.length + 1; // +1 for footer
     const bodyHeight = Math.max(1, rows - reservedRows);
-    const overflows = bodyLines.length > bodyHeight;
-    let scroll = state.scrollOffset || 0;
     const maxScroll = Math.max(0, bodyLines.length - bodyHeight);
-    scroll = Math.max(0, Math.min(scroll, maxScroll));
-    state.scrollOffset = scroll;
+    return {
+        interaction, preLines, bodyLines, postLines,
+        maxW, bodyHeight, maxScroll, overflows: bodyLines.length > bodyHeight,
+    };
+}
+/**
+ * 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 function clampItemReviewScroll(state, cols, rows) {
+    const { maxScroll } = buildItemReviewLayout(state, cols, rows);
+    state.scrollOffset = Math.max(0, Math.min(state.scrollOffset || 0, maxScroll));
+}
+export function renderItemReview(state, cols, rows) {
+    const { interaction, preLines, bodyLines, postLines, maxW, bodyHeight, maxScroll, overflows } = buildItemReviewLayout(state, cols, rows);
+    // Read-only clamp: renderer never mutates state (clampItemReviewScroll, run
+    // pre-render, keeps state.scrollOffset itself in bounds).
+    const scroll = Math.max(0, Math.min(state.scrollOffset || 0, maxScroll));
     let visibleBody;
     if (overflows) {
         visibleBody = bodyLines.slice(scroll, scroll + bodyHeight);

package/dist/tui/terminal.d.ts

@@ -1,7 +1,18 @@
 export interface Key {
     upArrow: boolean;
     downArrow: boolean;
+    leftArrow: boolean;
+    rightArrow: boolean;
+    /** Word-wise cursor motion (ctrl/alt + arrow, or readline alt-b / alt-f). */
+    wordLeft: boolean;
+    wordRight: boolean;
+    home: boolean;
+    end: boolean;
+    /** Forward delete (the Del key / \x1b[3~). */
+    del: boolean;
     return: boolean;
+    /** Newline-insert chord (ctrl+j / alt+enter) — distinct from return=submit. */
+    newline: boolean;
     escape: boolean;
     ctrl: boolean;
     meta: boolean;

package/dist/tui/terminal.js

@@ -2,7 +2,15 @@ function emptyKey() {
     return {
         upArrow: false,
         downArrow: false,
+        leftArrow: false,
+        rightArrow: false,
+        wordLeft: false,
+        wordRight: false,
+        home: false,
+        end: false,
+        del: false,
         return: false,
+        newline: false,
         escape: false,
         ctrl: false,
         meta: false,
@@ -21,10 +29,54 @@ export function parseKeypress(data) {
         key.downArrow = true;
         return { input: '', key };
     }
-    if (str === '\r' || str === '\n') {
+    if (str === '\x1b[C') {
+        key.rightArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[D') {
+        key.leftArrow = true;
+        return { input: '', key };
+    }
+    // Word-wise motion: ctrl/alt + left/right (xterm modifier encodings) and the
+    // readline alt-b / alt-f bindings. Must precede the bare-ESC checks below.
+    if (str === '\x1b[1;5C' || str === '\x1b[1;3C' || str === '\x1bf') {
+        key.wordRight = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[1;5D' || str === '\x1b[1;3D' || str === '\x1bb') {
+        key.wordLeft = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[H' || str === '\x1b[1~') {
+        key.home = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[F' || str === '\x1b[4~') {
+        key.end = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[3~') {
+        key.del = 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.
+    if (str === '\x1b\r' || str === '\x1b\n') {
+        key.newline = true;
+        return { input: '', key };
+    }
+    // Enter (submit) is CR; ctrl+j (LF) inserts a newline. Splitting them lets
+    // freetext use ctrl+j for a hard newline while Enter still submits. In a raw
+    // TTY the Enter key sends CR, so this split is safe.
+    if (str === '\r') {
         key.return = true;
         return { input: '', key };
     }
+    if (str === '\n') {
+        key.newline = true;
+        return { input: '', key };
+    }
     // Alt+Backspace: terminals send ESC followed by DEL/BS. Must precede the
     // bare-ESC check so the two-byte sequence isn't swallowed as plain escape.
     // iTerm2 (and many readline configs) instead map Option/Alt+Backspace to a

package/dist/types.d.ts

@@ -102,10 +102,12 @@ export type Phase = 'overview' | 'item-review' | 'final';
 export type InputMode = null | {
     kind: 'comment';
     buffer: string;
+    cursor: number;
     selectedOptionId?: string;
 } | {
     kind: 'freetext';
     buffer: string;
+    cursor: number;
 };
 export interface TuiState {
     phase: Phase;
@@ -181,6 +183,11 @@ export interface MountedPanelOpts {
     onProgress?: (responses: InteractionResponse[]) => void;
     onComplete?: (responses: InteractionResponse[]) => void;
     onExit?: () => void;
+    /** Fired when panel state changes outside a keypress — currently when an
+     *  async visual finishes loading. Hosts wire this to a repaint so
+     *  "loading context..." is replaced the moment context arrives, rather than
+     *  sticking until the next keystroke. Optional / backward-compatible. */
+    onDirty?: () => void;
 }
 export interface MountedPanel {
     handleKey(input: string, key: Key): void;
@@ -197,4 +204,15 @@ export interface MountedPanel {
      * whether Esc should step back inside the deck (false) or tear it down (true).
      */
     atDeckTop(): boolean;
+    /**
+     * Live comment/freetext buffer, or undefined when not in input mode. Lets a
+     * host implement the $EDITOR escape hatch (ctrl+o) without reaching into
+     * panel-internal state: read the buffer here before spawning the editor.
+     */
+    getInputBuffer(): string | undefined;
+    /**
+     * Replace the input-mode buffer (e.g. after an $EDITOR round-trip) and move
+     * the cursor to the end. No-op when not in input mode.
+     */
+    setInputBuffer(text: string): void;
 }