@hyperfrontend/questions 0.2.1 → 0.3.1

package/index.cjs.js

@@ -2,14 +2,289 @@
 
 const index_cjs_js = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
 const node_readline = require('node:readline');
-const index_cjs_js$1 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
-const index_cjs_js$2 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.cjs.js');
+const node_string_decoder = require('node:string_decoder');
+const index_cjs_js$2 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
+const index_cjs_js$1 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.cjs.js');
+const index_cjs_js$3 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const index_cjs_js$4 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.cjs.js');
 
 /**
- * Terminal I/O utilities using Node.js readline.
+ * ANSI-aware text measurement helpers.
+ *
+ * Display width is measured in Unicode code points with ANSI escape
+ * sequences excluded. East-asian wide characters and grapheme clusters are
+ * counted as one column each; full terminal-accurate width is out of scope.
  *
  * @internal
  */
+/** Escape character introducing ANSI control sequences. */
+const Esc = '\x1B';
+/**
+ * Matches the ANSI escape sequence starting at `index`. The character at
+ * `index` must be the escape character (`\x1B`); callers check this before
+ * calling. Recognizes CSI (`ESC [ ... final`) and SS3 (`ESC O x`) sequences;
+ * any other escape is reported as a lone one-character escape.
+ *
+ * @param text - Text containing the sequence
+ * @param index - Position of the escape character
+ * @returns Sequence length and whether it is complete
+ *
+ * @example Matching an arrow-key sequence
+ * ```typescript
+ * matchAnsiSequence('\x1B[A', 0)
+ * // => { length: 3, complete: true }
+ * ```
+ */
+function matchAnsiSequence(text, index) {
+    if (index + 1 >= text.length) {
+        return index_cjs_js.freeze({ length: 1, complete: false });
+    }
+    const introducer = text.charAt(index + 1);
+    if (introducer === '[') {
+        return matchCsi(text, index);
+    }
+    if (introducer === 'O') {
+        if (index + 2 >= text.length) {
+            return index_cjs_js.freeze({ length: 2, complete: false });
+        }
+        return index_cjs_js.freeze({ length: 3, complete: true });
+    }
+    return index_cjs_js.freeze({ length: 1, complete: true });
+}
+/**
+ * Matches a CSI sequence (`ESC [` + parameter/intermediate bytes + final
+ * byte in `0x40`-`0x7E`). A byte outside the CSI ranges terminates the match
+ * without being consumed so malformed sequences cannot swallow input.
+ *
+ * @param text - Text containing the sequence
+ * @param index - Position of the escape character
+ * @returns Sequence length and whether it is complete
+ */
+function matchCsi(text, index) {
+    let i = index + 2;
+    while (i < text.length) {
+        const code = text.charCodeAt(i);
+        if (code >= 0x40 && code <= 0x7e) {
+            return index_cjs_js.freeze({ length: i - index + 1, complete: true });
+        }
+        if (code < 0x20 || code > 0x3f) {
+            return index_cjs_js.freeze({ length: i - index, complete: true });
+        }
+        i++;
+    }
+    return index_cjs_js.freeze({ length: text.length - index, complete: false });
+}
+/**
+ * Removes all ANSI escape sequences from a string.
+ *
+ * @param text - Text possibly containing escape sequences
+ * @returns Text with every escape sequence removed
+ *
+ * @example Stripping color codes
+ * ```typescript
+ * stripAnsi('\x1B[36mhello\x1B[0m')
+ * // => 'hello'
+ * ```
+ */
+function stripAnsi(text) {
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        if (text.charAt(i) === Esc) {
+            i += matchAnsiSequence(text, i).length;
+            continue;
+        }
+        out += text.charAt(i);
+        i++;
+    }
+    return out;
+}
+/**
+ * Measures the display width of a string in terminal columns: Unicode code
+ * points with ANSI escape sequences excluded. Wide east-asian characters
+ * count as one column (documented limitation).
+ *
+ * @param text - Text to measure
+ * @returns Number of display columns
+ *
+ * @example Measuring styled text
+ * ```typescript
+ * displayWidth('\x1B[1mhi\x1B[0m')
+ * // => 2
+ * ```
+ */
+function displayWidth(text) {
+    return [...stripAnsi(text)].length;
+}
+
+/**
+ * Incremental parser turning raw terminal input chunks into input tokens.
+ *
+ * Handles bracketed paste bodies (accumulated across chunks between
+ * `ESC[200~` and `ESC[201~`), escape-sequence keys, and printable runs.
+ * A multi-character printable run outside bracketed paste is treated as a
+ * paste from a terminal without bracketed-paste support, and the run's
+ * trailing line endings become Enter keys.
+ *
+ * @internal
+ */
+/** Control character sent by Ctrl+C in raw mode. */
+const CtrlC = '\x03';
+/** Carriage return, the character every prompt reads as Enter. */
+const Enter = '\r';
+/** Line feed, which a pipe sends where a terminal sends a carriage return. */
+const LineFeed = '\n';
+/** Sequence a bracketed-paste-aware terminal sends before pasted content. */
+const PasteStart = '\x1B[200~';
+/** Sequence a bracketed-paste-aware terminal sends after pasted content. */
+const PasteEnd = '\x1B[201~';
+/**
+ * Kinds of tokens produced while reading terminal input.
+ */
+const TokenType = index_cjs_js.freeze({
+    /** A single keypress (character or escape sequence) */
+    Key: 'key',
+    /** A block of pasted text */
+    Paste: 'paste',
+    /** The output terminal was resized */
+    Resize: 'resize',
+});
+/**
+ * Builds a key token.
+ *
+ * @param value - Key character or escape sequence
+ * @returns Frozen key token
+ */
+function keyToken(value) {
+    return index_cjs_js.freeze({ type: TokenType.Key, value });
+}
+/**
+ * Builds a paste token.
+ *
+ * @param value - Raw pasted text
+ * @returns Frozen paste token
+ */
+function pasteToken(value) {
+    return index_cjs_js.freeze({ type: TokenType.Paste, value });
+}
+/**
+ * Finds where a trailing partial occurrence of `marker` starts in `data`,
+ * scanning no earlier than `from`. Used to hold back a possible split
+ * bracketed-paste end marker until the next chunk arrives.
+ *
+ * @param data - Buffered input text
+ * @param from - First position that may be held back
+ * @param marker - Marker whose prefix may be split across chunks
+ * @returns Index where the partial marker starts, or `data.length` when the
+ *   text does not end with a marker prefix
+ */
+function partialMarkerStart(data, from, marker) {
+    const maxLength = index_cjs_js$1.min(marker.length - 1, data.length - from);
+    for (let k = maxLength; k >= 1; k--) {
+        if (data.endsWith(marker.slice(0, k))) {
+            return data.length - k;
+        }
+    }
+    return data.length;
+}
+/**
+ * Creates an incremental input tokenizer.
+ *
+ * Escape sequences split across chunks are buffered until complete; a lone
+ * trailing escape is likewise buffered (prompts do not act on a bare Escape
+ * key, so delaying it until the next chunk is unobservable). Ctrl+C outside
+ * a bracketed paste is always its own key token; inside a paste body it is
+ * plain data. Outside a bracketed paste, the trailing run of carriage
+ * returns and line feeds is split off a printable run and emitted as one
+ * Enter key per line ending (`\r\n` counts once), so a single chunk
+ * carrying typed text and Enter submits; line endings inside the run stay
+ * data.
+ *
+ * @returns Stateful token parser
+ *
+ * @example Parsing a paste split across two chunks
+ * ```typescript
+ * const parser = createTokenParser()
+ * parser.feed('\x1B[200~hello ')
+ * // => []
+ * parser.feed('world\x1B[201~')
+ * // => [{ type: 'paste', value: 'hello world' }]
+ * ```
+ */
+function createTokenParser() {
+    let carry = '';
+    let pasteBuffer;
+    const feed = (chunk) => {
+        const data = carry + chunk;
+        carry = '';
+        const tokens = [];
+        let pos = 0;
+        while (pos < data.length) {
+            if (pasteBuffer !== undefined) {
+                const endIndex = data.indexOf(PasteEnd, pos);
+                if (endIndex >= 0) {
+                    tokens.push(pasteToken(pasteBuffer + data.slice(pos, endIndex)));
+                    pasteBuffer = undefined;
+                    pos = endIndex + PasteEnd.length;
+                    continue;
+                }
+                const holdFrom = partialMarkerStart(data, pos, PasteEnd);
+                pasteBuffer += data.slice(pos, holdFrom);
+                carry = data.slice(holdFrom);
+                break;
+            }
+            const char = data.charAt(pos);
+            if (char === Esc) {
+                const match = matchAnsiSequence(data, pos);
+                if (!match.complete) {
+                    carry = data.slice(pos);
+                    break;
+                }
+                const sequence = data.slice(pos, pos + match.length);
+                pos += match.length;
+                if (sequence === PasteStart) {
+                    pasteBuffer = '';
+                    continue;
+                }
+                // why: a stray end marker without a matching start carries no content
+                if (sequence === PasteEnd)
+                    continue;
+                tokens.push(keyToken(sequence));
+                continue;
+            }
+            if (char === CtrlC) {
+                tokens.push(keyToken(char));
+                pos++;
+                continue;
+            }
+            let end = pos + 1;
+            while (end < data.length && data.charAt(end) !== Esc && data.charAt(end) !== CtrlC) {
+                end++;
+            }
+            const run = data.slice(pos, end);
+            pos = end;
+            let bodyEnd = run.length;
+            // why: a chunk that ends in newlines carries a submit, so the newline run is peeled off the body before the body is classified
+            while (bodyEnd > 0 && (run.charAt(bodyEnd - 1) === Enter || run.charAt(bodyEnd - 1) === LineFeed)) {
+                bodyEnd--;
+            }
+            const body = run.slice(0, bodyEnd);
+            if (body.length > 0) {
+                // why: raw mode delivers one keystroke per chunk, so a longer run means the terminal pasted without bracketed-paste support
+                tokens.push(body.length === 1 ? keyToken(body) : pasteToken(body));
+            }
+            for (let index = bodyEnd; index < run.length; index++) {
+                // why: CRLF is one Enter and a lone line feed is the Enter a pipe sends, matching how readline normalises line endings
+                if (run.charAt(index) === LineFeed && run.charAt(index - 1) === Enter)
+                    continue;
+                tokens.push(keyToken(Enter));
+            }
+        }
+        return index_cjs_js.freeze(tokens);
+    };
+    return index_cjs_js.freeze({ feed });
+}
+
 /**
  * Key codes for terminal navigation.
  */
@@ -55,6 +330,13 @@ const Ansi = index_cjs_js.freeze({
      * @returns ANSI escape sequence string
      */
     cursorLeft: (n) => `\x1B[${n}D`,
+    /**
+     * Generates ANSI escape code to move cursor right by specified columns.
+     *
+     * @param n - Number of columns to move right
+     * @returns ANSI escape sequence string
+     */
+    cursorRight: (n) => `\x1B[${n}C`,
     /** Escape code to hide cursor */
     HideCursor: '\x1B[?25l',
     /** Escape code to show cursor */
@@ -65,6 +347,10 @@ const Ansi = index_cjs_js.freeze({
     RestoreCursor: '\x1B8',
     /** Clear from cursor to end of screen */
     ClearToEnd: '\x1B[J',
+    /** Ask the terminal to wrap pasted text in ESC[200~ / ESC[201~ markers */
+    BracketedPasteOn: '\x1B[?2004h',
+    /** Stop wrapping pasted text in bracketed-paste markers */
+    BracketedPasteOff: '\x1B[?2004l',
     /** Escape code for bold text */
     Bold: '\x1B[1m',
     /** Escape code for dim text */
@@ -85,6 +371,14 @@ const Ansi = index_cjs_js.freeze({
 /**
  * Creates a terminal interface for interactive prompts.
  *
+ * The first `readToken`/`readKey` call opens a read session: the input is
+ * switched to raw mode for the whole session (restored on `close`),
+ * bracketed paste mode is enabled on TTY inputs, and resize events from the
+ * output surface as resize tokens. Input chunks are tokenized by a
+ * persistent listener so no chunk is lost between reads. When the input
+ * ends, the session cancels and delivers a Ctrl+C key so a waiting read
+ * resolves.
+ *
  * @param config - Terminal configuration options
  * @returns Terminal interface with read/write methods
  *
@@ -92,7 +386,7 @@ const Ansi = index_cjs_js.freeze({
  * ```typescript
  * const term = createTerminal()
  * term.write('Enter name: ')
- * const name = await term.readLine()
+ * const token = await term.readToken()
  * term.close()
  * ```
  */
@@ -100,7 +394,15 @@ function createTerminal(config = {}) {
     const input = config.input ?? process.stdin;
     const output = config.output ?? process.stdout;
     let cancelled = false;
+    let closed = false;
+    let sessionActive = false;
+    let savedRawMode = false;
     let rl;
+    let pendingWaiter;
+    const parser = createTokenParser();
+    // why: decoding through StringDecoder keeps multibyte characters intact when a large paste is split across stream chunks mid-code-point
+    const decoder = new node_string_decoder.StringDecoder('utf8');
+    const tokenQueue = [];
     const getReadline = () => {
         if (!rl) {
             rl = node_readline.createInterface({ input, output, terminal: true });
@@ -110,25 +412,84 @@ function createTerminal(config = {}) {
     const write = (text) => {
         output.write(text);
     };
-    const readKey = () => index_cjs_js$1.createPromise((resolve) => {
-        const wasRaw = input.isRaw;
+    const deliver = (tokens) => {
+        for (const token of tokens) {
+            if (token.type === TokenType.Key && token.value === Key.CtrlC) {
+                cancelled = true;
+            }
+            // why: a resize drag fires many events; consecutive notifications collapse into one so the prompt repaints once per drained batch
+            if (token.type === TokenType.Resize && tokenQueue[tokenQueue.length - 1]?.type === TokenType.Resize) {
+                continue;
+            }
+            tokenQueue.push(token);
+        }
+        if (pendingWaiter !== undefined) {
+            const token = tokenQueue.shift();
+            if (token !== undefined) {
+                const waiter = pendingWaiter;
+                pendingWaiter = undefined;
+                waiter(token);
+            }
+        }
+    };
+    const onData = (data) => {
+        const text = decoder.write(data);
+        if (text !== '') {
+            deliver(parser.feed(text));
+        }
+    };
+    const onResize = () => {
+        deliver(index_cjs_js.freeze([index_cjs_js.freeze({ type: TokenType.Resize })]));
+    };
+    const onEnd = () => {
+        // why: an ended input can never deliver another key, so a waiting prompt resolves through the cancellation branch instead of hanging
+        deliver(index_cjs_js.freeze([index_cjs_js.freeze({ type: TokenType.Key, value: Key.CtrlC })]));
+    };
+    const openSession = () => {
+        if (sessionActive)
+            return;
+        sessionActive = true;
+        savedRawMode = input.isRaw === true;
         if (input.setRawMode) {
             input.setRawMode(true);
+            write(Ansi.BracketedPasteOn);
         }
-        const onData = (data) => {
-            input.removeListener('data', onData);
-            if (input.setRawMode) {
-                input.setRawMode(wasRaw);
-            }
-            const key = data.toString();
-            if (key === Key.CtrlC) {
-                cancelled = true;
-            }
-            resolve(key);
-        };
-        input.once('data', onData);
-    });
-    const readLine = () => index_cjs_js$1.createPromise((resolve) => {
+        input.on('data', onData);
+        input.once('end', onEnd);
+        output.on('resize', onResize);
+        input.resume();
+    };
+    const closeSession = () => {
+        if (!sessionActive)
+            return;
+        sessionActive = false;
+        input.removeListener('data', onData);
+        input.removeListener('end', onEnd);
+        output.removeListener('resize', onResize);
+        if (input.setRawMode) {
+            write(Ansi.BracketedPasteOff);
+            input.setRawMode(savedRawMode);
+        }
+        input.pause();
+    };
+    const readToken = () => {
+        openSession();
+        const queued = tokenQueue.shift();
+        if (queued !== undefined) {
+            return index_cjs_js$2.promiseResolve(queued);
+        }
+        return index_cjs_js$2.createPromise((resolve) => {
+            pendingWaiter = resolve;
+        });
+    };
+    const readKey = async () => {
+        let token = await readToken();
+        while (token.type === TokenType.Resize) {
+            token = await readToken();
+        }
+        return token.value;
+    };
+    const readLine = () => index_cjs_js$2.createPromise((resolve) => {
         const readline = getReadline();
         readline.once('line', (line) => {
             resolve(line);
@@ -148,7 +509,15 @@ function createTerminal(config = {}) {
             }
         }
     };
+    const getSize = () => index_cjs_js.freeze({
+        columns: output.columns > 0 ? output.columns : 80,
+        rows: output.rows > 0 ? output.rows : 24,
+    });
     const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        closeSession();
         if (rl) {
             rl.close();
             rl = undefined;
@@ -158,8 +527,10 @@ function createTerminal(config = {}) {
     return index_cjs_js.freeze({
         write,
         readKey,
+        readToken,
         readLine,
         clearLines,
+        getSize,
         close,
         isCancelled: () => cancelled,
         cancel: () => {
@@ -286,6 +657,139 @@ function renderCancelled() {
     return style.dim('(cancelled)');
 }
 
+/**
+ * Hard-wraps one logical line into physical rows no wider than `width`
+ * display columns. ANSI escape sequences are zero-width and never split;
+ * surrogate pairs travel together.
+ *
+ * @param line - Logical line, possibly containing ANSI sequences
+ * @param width - Maximum display columns per row (at least 1)
+ * @returns Physical rows covering the line (always at least one row)
+ *
+ * @example Wrapping a long line
+ * ```typescript
+ * wrapLine('abcdefghij', 4)
+ * // => ['abcd', 'efgh', 'ij']
+ * ```
+ */
+function wrapLine(line, width) {
+    const rows = [];
+    let current = '';
+    let col = 0;
+    let i = 0;
+    while (i < line.length) {
+        if (line.charAt(i) === Esc) {
+            const { length } = matchAnsiSequence(line, i);
+            current += line.slice(i, i + length);
+            i += length;
+            continue;
+        }
+        if (col === width) {
+            rows.push(current);
+            current = '';
+            col = 0;
+        }
+        const charCode = line.charCodeAt(i);
+        // why: keep surrogate pairs on the same row so code points never split
+        const charLength = charCode >= 0xd800 && charCode <= 0xdbff ? 2 : 1;
+        current += line.slice(i, i + charLength);
+        col++;
+        i += charLength;
+    }
+    rows.push(current);
+    return index_cjs_js.freeze(rows);
+}
+/**
+ * Creates a frame renderer bound to a terminal.
+ *
+ * @param terminal - Terminal used for size queries and output
+ * @returns Screen renderer
+ *
+ * @example Repainting a prompt line with a parked cursor
+ * ```typescript
+ * const screen = createScreen(terminal)
+ * screen.render({ lines: ['? Name: Jo'], cursor: { line: 0, col: 10 } })
+ * screen.render({ lines: ['? Name: Joe'], cursor: { line: 0, col: 11 } })
+ * ```
+ */
+function createScreen(terminal) {
+    let lastRows = index_cjs_js.freeze([]);
+    let lastWidth = 0;
+    let lastCursorRow = 0;
+    let lastCursorCol = 0;
+    const reflowedCursorRow = (width) => {
+        let row = 0;
+        for (const paintedRow of lastRows.slice(0, lastCursorRow)) {
+            row += index_cjs_js$1.max(1, index_cjs_js$1.ceil(displayWidth(paintedRow) / width));
+        }
+        return row + index_cjs_js$1.floor(lastCursorCol / width);
+    };
+    const eraseLastFrame = (width, viewportRows) => {
+        if (lastRows.length === 0)
+            return;
+        // why: on a width change the terminal reflowed the old paint, so the cursor's row offset is recomputed against the new width
+        const cursorRow = width === lastWidth ? lastCursorRow : reflowedCursorRow(width);
+        // why: travel is capped at the viewport height so a reflow estimate can never climb past the frame into content above it
+        const travelRows = index_cjs_js$1.min(cursorRow, viewportRows - 1);
+        let travel = Ansi.CursorStart;
+        if (travelRows > 0)
+            travel += Ansi.cursorUp(travelRows);
+        terminal.write(travel + Ansi.ClearToEnd);
+    };
+    const resolveCursor = (frame, rowsPerLine, lastRowText, totalRows, width) => {
+        if (frame.cursor === undefined) {
+            return index_cjs_js.freeze({ row: totalRows - 1, col: displayWidth(lastRowText) });
+        }
+        let row = 0;
+        for (const count of rowsPerLine.slice(0, frame.cursor.line)) {
+            row += count;
+        }
+        let extraRows = index_cjs_js$1.floor(frame.cursor.col / width);
+        let col = frame.cursor.col - extraRows * width;
+        if (col === 0 && frame.cursor.col > 0) {
+            // why: a cursor at an exact wrap boundary parks at the end of the previous physical row rather than on an unpainted row
+            extraRows -= 1;
+            col = width;
+        }
+        return index_cjs_js.freeze({ row: row + extraRows, col });
+    };
+    const render = (frame) => {
+        const size = terminal.getSize();
+        const width = index_cjs_js$1.max(1, size.columns);
+        const viewportRows = index_cjs_js$1.max(1, size.rows);
+        eraseLastFrame(width, viewportRows);
+        const wrappedRows = [];
+        const rowsPerLine = [];
+        let lastRowText = '';
+        for (const line of frame.lines) {
+            const wrapped = wrapLine(line, width);
+            rowsPerLine.push(wrapped.length);
+            for (const row of wrapped) {
+                wrappedRows.push(row);
+                lastRowText = row;
+            }
+        }
+        // why: a frame taller than the viewport would scroll its own top off-screen and desync the erase math, so only the tail that fits is painted
+        const dropped = index_cjs_js$1.max(0, wrappedRows.length - viewportRows);
+        const physicalRows = dropped > 0 ? wrappedRows.slice(dropped) : wrappedRows;
+        terminal.write(physicalRows.join('\n'));
+        const rawCursor = resolveCursor(frame, rowsPerLine, lastRowText, wrappedRows.length, width);
+        const cursor = rawCursor.row >= dropped ? index_cjs_js.freeze({ row: rawCursor.row - dropped, col: rawCursor.col }) : index_cjs_js.freeze({ row: 0, col: 0 });
+        let travel = Ansi.CursorStart;
+        const rowsUp = physicalRows.length - 1 - cursor.row;
+        if (rowsUp > 0)
+            travel += Ansi.cursorUp(rowsUp);
+        if (cursor.col > 0)
+            travel += Ansi.cursorRight(cursor.col);
+        terminal.write(travel);
+        lastRows = index_cjs_js.freeze(physicalRows);
+        lastWidth = width;
+        lastCursorRow = cursor.row;
+        lastCursorCol = cursor.col;
+    };
+    return index_cjs_js.freeze({ render });
+}
+
 /**
  * Core types for terminal prompts.
  *
@@ -317,11 +821,36 @@ function renderOptions(initial) {
     }
     return style.dim('(y/n)');
 }
+/**
+ * Interprets a key or paste token as a yes/no answer. Keys accept `y`/`n`
+ * (any case); pastes accept a trimmed, lowercased `y`/`yes`/`n`/`no`.
+ *
+ * @internal
+ * @param token - Token to interpret
+ * @returns The boolean answer, or undefined when the token is not one
+ */
+function parseAnswer(token) {
+    const normalized = token.value.trim().toLowerCase();
+    if (token.type === TokenType.Paste) {
+        if (normalized === 'y' || normalized === 'yes')
+            return true;
+        if (normalized === 'n' || normalized === 'no')
+            return false;
+        return undefined;
+    }
+    if (normalized === 'y')
+        return true;
+    if (normalized === 'n')
+        return false;
+    return undefined;
+}
 /**
  * Prompts for yes/no confirmation.
  *
  * Pure functional prompt that asks a yes/no question and returns a boolean.
- * Supports default values and responds to y/Y/n/N keys.
+ * Supports default values and responds to y/Y/n/N keys. A pasted
+ * `y`/`yes`/`n`/`no` (trimmed, case-insensitive) is accepted; any other
+ * paste is ignored. The prompt repaints on terminal resize.
  *
  * @param config - Confirm prompt configuration
  * @returns Promise resolving to boolean value or cancellation
@@ -344,38 +873,143 @@ function renderOptions(initial) {
  */
 async function confirm(config) {
     const term = createTerminal({ input: config.input, output: config.output });
-    const drawPrompt = () => {
-        term.write(Ansi.CursorStart + Ansi.ClearLine);
-        term.write(renderMessage(config.message) + renderOptions(config.initial) + ' ');
+    const screen = createScreen(term);
+    const finish = (value) => {
+        screen.render(index_cjs_js.freeze({ lines: index_cjs_js.freeze([renderMessage(config.message) + renderSubmitted(value ? 'Yes' : 'No')]) }));
+        term.write('\n');
+        return index_cjs_js.freeze({ result: PromptResult.Submitted, value });
     };
-    const drawResult = (value) => {
-        term.write(Ansi.CursorStart + Ansi.ClearLine);
-        term.write(renderMessage(config.message) + renderSubmitted(value ? 'Yes' : 'No') + '\n');
+    const redraw = () => {
+        screen.render(index_cjs_js.freeze({ lines: index_cjs_js.freeze([renderMessage(config.message) + renderOptions(config.initial) + ' ']) }));
     };
-    drawPrompt();
-    while (true) {
-        const key = await term.readKey();
-        const lowerKey = key.toLowerCase();
-        if (term.isCancelled()) {
-            term.write(Ansi.CursorStart + Ansi.ClearLine);
-            term.write(renderMessage(config.message) + renderCancelled() + '\n');
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Cancelled, value: undefined });
+    try {
+        redraw();
+        while (true) {
+            const token = await term.readToken();
+            if (term.isCancelled()) {
+                screen.render(index_cjs_js.freeze({ lines: index_cjs_js.freeze([renderMessage(config.message) + renderCancelled()]) }));
+                term.write('\n');
+                return index_cjs_js.freeze({ result: PromptResult.Cancelled, value: undefined });
+            }
+            if (token.type === TokenType.Resize) {
+                redraw();
+                continue;
+            }
+            const answer = parseAnswer(token);
+            if (answer !== undefined) {
+                return finish(answer);
+            }
+            if (token.value === Key.Enter && config.initial !== undefined) {
+                return finish(config.initial);
+            }
         }
-        if (lowerKey === 'y') {
-            drawResult(true);
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Submitted, value: true });
+    }
+    finally {
+        term.close();
+    }
+}
+
+/**
+ * Sanitizers for pasted text before it enters prompt state.
+ *
+ * @internal
+ */
+/**
+ * Sanitizes pasted text for insertion into a single-line input: interior
+ * runs of `\r\n`, `\r`, or `\n` collapse into a single space, leading and
+ * trailing newline runs are dropped, and all other C0 control characters
+ * (plus DEL) are removed. Pasting therefore never submits or triggers
+ * prompt actions.
+ *
+ * @param raw - Raw pasted text
+ * @returns Sanitized single-line text (possibly empty)
+ *
+ * @example Collapsing a multi-line paste
+ * ```typescript
+ * sanitizePasteText('first\r\nsecond\n')
+ * // => 'first second'
+ * ```
+ */
+function sanitizePasteText(raw) {
+    let out = '';
+    let pendingBreak = false;
+    for (const char of raw) {
+        if (char === '\r' || char === '\n') {
+            pendingBreak = true;
+            continue;
         }
-        if (lowerKey === 'n') {
-            drawResult(false);
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Submitted, value: false });
+        const code = char.charCodeAt(0);
+        if (code < 0x20 || code === 0x7f)
+            continue;
+        if (pendingBreak && out.length > 0) {
+            out += ' ';
         }
-        if (key === Key.Enter && config.initial !== undefined) {
-            drawResult(config.initial);
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Submitted, value: config.initial });
+        pendingBreak = false;
+        out += char;
+    }
+    return out;
+}
+/**
+ * Extracts the first line of a paste for search-query style inputs: content
+ * is cut at the first `\r` or `\n`, then remaining C0 control characters
+ * (plus DEL) are removed.
+ *
+ * @param raw - Raw pasted text
+ * @returns Printable characters of the first pasted line
+ *
+ * @example Keeping only the first pasted line
+ * ```typescript
+ * firstPasteLine('query\nsecond line')
+ * // => 'query'
+ * ```
+ */
+function firstPasteLine(raw) {
+    let out = '';
+    for (const char of raw) {
+        if (char === '\r' || char === '\n')
+            break;
+        const code = char.charCodeAt(0);
+        if (code < 0x20 || code === 0x7f)
+            continue;
+        out += char;
+    }
+    return out;
+}
+
+/**
+ * Configuration guards shared by the choice-list prompts.
+ *
+ * @internal
+ */
+/**
+ * Rejects a choice-list configuration no keypress could ever resolve: an
+ * empty choice list, or a starting index that names no choice. Without the
+ * check the prompt paints a frame and waits forever.
+ *
+ * @param promptName - Prompt name quoted in the error message
+ * @param choices - Choices the prompt was configured with
+ * @param initial - Indices the prompt is asked to start on
+ * @throws {Error} When the choice list is empty, or an initial index is not a whole number inside the list
+ *
+ * @example Rejecting an empty choice list
+ * ```typescript
+ * assertResolvableChoices('select', [], [])
+ * // => throws Error: select requires at least one choice
+ * ```
+ *
+ * @example Rejecting an index past the end of the list
+ * ```typescript
+ * assertResolvableChoices('select', [{ label: 'Red', value: 'red' }], [7])
+ * // => throws Error: select initial must be an index between 0 and 0, received 7
+ * ```
+ */
+function assertResolvableChoices(promptName, choices, initial) {
+    if (choices.length === 0) {
+        throw index_cjs_js$3.createError(`${promptName} requires at least one choice`);
+    }
+    for (const index of initial) {
+        if (!index_cjs_js$4.isInteger(index) || index < 0 || index >= choices.length) {
+            throw index_cjs_js$3.createError(`${promptName} initial must be an index between 0 and ${choices.length - 1}, received ${index}`);
         }
     }
 }
@@ -484,72 +1118,75 @@ function renderChoice$1(choice, isSelected, isFocused) {
     return `${pointer} ${checkbox} ${label}${hint}`;
 }
 /**
- * Renders the multiselect prompt to the terminal.
+ * Builds the frame lines for the multiselect prompt.
  *
  * @internal
- * @param term - Terminal interface
  * @param config - Prompt configuration
  * @param state - Current prompt state
- * @param submitted - Whether the prompt has been submitted
- * @returns Number of lines rendered
+ * @param maxVisible - Maximum number of visible choices
+ * @returns Logical lines describing the prompt
  */
-function render$2(term, config, state, submitted) {
-    const maxVisible = config.maxVisible ?? 10;
+function buildLines$1(config, state, maxVisible) {
     const { indices: visibleIndices, startIndex } = getVisibleChoices$1(state, maxVisible);
-    let output = Ansi.CursorStart + Ansi.ClearLine + renderMessage(config.message);
-    if (submitted) {
-        const selectedLabels = state.selected.map((i) => state.choices[i]?.label ?? '').join(', ');
-        output += renderSubmitted(selectedLabels || 'none');
-        term.write(output);
-        return 1;
-    }
+    const lines = [];
+    let header = renderMessage(config.message);
     if (config.searchable && state.searchQuery) {
-        output += style.cyan(state.searchQuery) + style.dim(' (type to filter)');
+        header += style.cyan(state.searchQuery) + style.dim(' (type to filter)');
     }
     else if (config.searchable) {
-        output += style.dim('(type to filter, space to toggle, enter to submit)');
+        header += style.dim('(type to filter, space to toggle, enter to submit)');
     }
     else {
-        output += style.dim('(space to toggle, enter to submit)');
+        header += style.dim('(space to toggle, enter to submit)');
     }
-    term.write(output + '\n');
-    let lineCount = 1;
+    lines.push(header);
     const minMax = [];
     if (config.min !== undefined)
         minMax.push(`min: ${config.min}`);
     if (config.max !== undefined)
         minMax.push(`max: ${config.max}`);
     const countHint = minMax.length > 0 ? ` (${minMax.join(', ')})` : '';
-    term.write(Ansi.ClearLine + style.dim(`  ${state.selected.length} selected${countHint}`) + '\n');
-    lineCount++;
-    const showScrollUp = startIndex > 0;
-    const showScrollDown = startIndex + maxVisible < state.filteredIndices.length;
-    if (showScrollUp) {
-        term.write(Ansi.ClearLine + style.dim(`  ${Symbol.Ellipsis} (${startIndex} more above)`) + '\n');
-        lineCount++;
+    lines.push(style.dim(`  ${state.selected.length} selected${countHint}`));
+    if (startIndex > 0) {
+        lines.push(style.dim(`  ${Symbol.Ellipsis} (${startIndex} more above)`));
     }
     visibleIndices.forEach((actualIndex, i) => {
         const choice = state.choices[actualIndex];
-        /* istanbul ignore if -- @preserve defensive: actualIndex always valid from filteredIndices */
+        // why: actualIndex always comes from filteredIndices, so this guard is defensive and never taken.
         if (!choice)
             return;
-        const viewIndex = startIndex + i;
-        const isFocused = viewIndex === state.cursor;
+        const isFocused = startIndex + i === state.cursor;
         const isSelected = arrayIncludes(state.selected, actualIndex);
-        const line = renderChoice$1(choice, isSelected, isFocused);
-        term.write(Ansi.ClearLine + line + '\n');
-        lineCount++;
+        lines.push(renderChoice$1(choice, isSelected, isFocused));
     });
-    if (showScrollDown) {
+    if (startIndex + maxVisible < state.filteredIndices.length) {
         const remaining = state.filteredIndices.length - (startIndex + maxVisible);
-        term.write(Ansi.ClearLine + style.dim(`  ${Symbol.Ellipsis} (${remaining} more below)`) + '\n');
-        lineCount++;
+        lines.push(style.dim(`  ${Symbol.Ellipsis} (${remaining} more below)`));
     }
     if (state.filteredIndices.length === 0 && config.searchable) {
-        term.write(Ansi.ClearLine + style.dim('  No matches found') + '\n');
-        lineCount++;
+        lines.push(style.dim('  No matches found'));
     }
-    return lineCount;
+    return index_cjs_js.freeze(lines);
+}
+/**
+ * Appends text to the search query, re-filtering choices.
+ *
+ * @internal
+ * @param query - Text to append (a typed character or pasted line)
+ * @param state - Current prompt state
+ * @returns Updated state with the new query applied
+ */
+function appendSearch$1(query, state) {
+    if (query === '')
+        return state;
+    const newQuery = state.searchQuery + query;
+    return index_cjs_js.freeze({
+        ...state,
+        searchQuery: newQuery,
+        filteredIndices: filterChoices$1(state.choices, newQuery),
+        cursor: 0,
+        scrollOffset: 0,
+    });
 }
 /**
  * Processes a keypress and returns updated state.
@@ -558,10 +1195,10 @@ function render$2(term, config, state, submitted) {
  * @param key - The key that was pressed
  * @param state - Current prompt state
  * @param config - Prompt configuration
+ * @param maxVisible - Maximum number of visible choices
  * @returns Updated state after processing the key
  */
-function processKey$2(key, state, config) {
-    const maxVisible = config.maxVisible ?? 10;
+function processKey$2(key, state, config, maxVisible) {
     const total = state.filteredIndices.length;
     if (total === 0 && key !== Key.Backspace && key !== '\b')
         return state;
@@ -596,7 +1233,7 @@ function processKey$2(key, state, config) {
         if (actualIndex === undefined)
             return state;
         const choice = state.choices[actualIndex];
-        /* istanbul ignore if -- @preserve defensive: actualIndex validated above */
+        // why: actualIndex is validated above, so this guard is defensive and never taken.
         if (!choice || choice.disabled)
             return state;
         const isSelected = arrayIncludes(state.selected, actualIndex);
@@ -628,15 +1265,7 @@ function processKey$2(key, state, config) {
             return state;
         }
         if (key.length === 1 && key >= ' ' && key !== Key.Space) {
-            const newQuery = state.searchQuery + key;
-            const newFiltered = filterChoices$1(state.choices, newQuery);
-            return index_cjs_js.freeze({
-                ...state,
-                searchQuery: newQuery,
-                filteredIndices: newFiltered,
-                cursor: 0,
-                scrollOffset: 0,
-            });
+            return appendSearch$1(key, state);
         }
     }
     return state;
@@ -658,14 +1287,30 @@ function validateSelection(state, config) {
     }
     return undefined;
 }
+/**
+ * Resolves the visible-window size, capped so the frame fits the terminal
+ * height (header and scroll-indicator rows reserved).
+ *
+ * @internal
+ * @param term - Terminal used for size queries
+ * @param configured - Configured maximum visible choices
+ * @returns Effective maximum visible choices (at least 1)
+ */
+function effectiveMaxVisible$1(term, configured) {
+    return index_cjs_js$1.max(1, index_cjs_js$1.min(configured ?? 10, term.getSize().rows - 4));
+}
 /**
  * Prompts for multiple selections from a list of choices.
  *
  * Pure functional prompt with arrow key navigation, space to toggle,
- * scrolling support, min/max constraints, and optional type-to-filter search.
+ * scrolling support, min/max constraints, and optional type-to-filter
+ * search. In searchable mode, pasted text appends its first line to the
+ * filter query; pasting never toggles or submits. The prompt repaints on
+ * terminal resize, preserving cursor, selection, and scroll state.
  *
  * @param config - Multiselect prompt configuration
  * @returns Promise resolving to array of selected values or cancellation
+ * @throws {Error} When `choices` is empty, or an `initial` entry is not a whole number inside the choice list
  *
  * @example Basic multiselect
  * ```typescript
@@ -703,56 +1348,61 @@ function validateSelection(state, config) {
  * ```
  */
 async function multiselect(config) {
+    assertResolvableChoices('multiselect', config.choices, config.initial ?? []);
     const term = createTerminal({ input: config.input, output: config.output });
+    const screen = createScreen(term);
     let state = createInitialState$2(config);
-    let lineCount = 0;
     let errorMessage;
     term.write(Ansi.HideCursor);
-    const redraw = (submitted = false) => {
-        if (lineCount > 0) {
-            term.write(Ansi.cursorUp(lineCount) + Ansi.CursorStart);
-        }
-        term.write(Ansi.ClearToEnd);
-        lineCount = render$2(term, config, state, submitted);
-        if (errorMessage && !submitted) {
-            term.write(Ansi.ClearLine + style.yellow(`  ${errorMessage}`) + '\n');
-            lineCount++;
+    const redraw = () => {
+        const lines = [...buildLines$1(config, state, effectiveMaxVisible$1(term, config.maxVisible))];
+        if (errorMessage) {
+            lines.push(style.yellow(`  ${errorMessage}`));
         }
+        screen.render(index_cjs_js.freeze({ lines: index_cjs_js.freeze(lines) }));
     };
-    redraw();
-    while (true) {
-        const key = await term.readKey();
-        if (term.isCancelled()) {
-            if (lineCount > 0) {
-                term.write(Ansi.cursorUp(lineCount) + Ansi.CursorStart);
+    try {
+        redraw();
+        while (true) {
+            const token = await term.readToken();
+            if (term.isCancelled()) {
+                screen.render(index_cjs_js.freeze({ lines: index_cjs_js.freeze([renderMessage(config.message) + renderCancelled()]) }));
+                term.write('\n' + Ansi.ShowCursor);
+                return index_cjs_js.freeze({ result: PromptResult.Cancelled, value: undefined });
             }
-            term.write(Ansi.ClearToEnd);
-            term.write(renderMessage(config.message) + renderCancelled() + '\n');
-            term.write(Ansi.ShowCursor);
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Cancelled, value: undefined });
-        }
-        if (key === Key.Enter) {
-            const validationError = validateSelection(state, config);
-            if (validationError) {
-                errorMessage = validationError;
+            if (token.type === TokenType.Resize) {
                 redraw();
                 continue;
             }
-            const selectedValues = state.selected.map((i) => state.choices[i]?.value).filter((v) => v !== undefined);
-            if (lineCount > 0) {
-                term.write(Ansi.cursorUp(lineCount) + Ansi.CursorStart);
+            if (token.type === TokenType.Paste) {
+                if (config.searchable) {
+                    errorMessage = undefined;
+                    state = appendSearch$1(firstPasteLine(token.value), state);
+                    redraw();
+                }
+                continue;
+            }
+            if (token.value === Key.Enter) {
+                const validationError = validateSelection(state, config);
+                if (validationError) {
+                    errorMessage = validationError;
+                    redraw();
+                    continue;
+                }
+                const selectedValues = state.selected.map((i) => state.choices[i]?.value).filter((v) => v !== undefined);
+                const selectedLabels = state.selected.map((i) => state.choices[i]?.label ?? '').join(', ');
+                const submittedLine = renderMessage(config.message) + renderSubmitted(selectedLabels || 'none');
+                screen.render(index_cjs_js.freeze({ lines: index_cjs_js.freeze([submittedLine]) }));
+                term.write('\n' + Ansi.ShowCursor);
+                return index_cjs_js.freeze({ result: PromptResult.Submitted, value: index_cjs_js.freeze(selectedValues) });
             }
-            term.write(Ansi.ClearToEnd);
-            render$2(term, config, state, true);
-            term.write('\n');
-            term.write(Ansi.ShowCursor);
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Submitted, value: index_cjs_js.freeze(selectedValues) });
+            errorMessage = undefined;
+            state = processKey$2(token.value, state, config, effectiveMaxVisible$1(term, config.maxVisible));
+            redraw();
         }
-        errorMessage = undefined;
-        state = processKey$2(key, state, config);
-        redraw();
+    }
+    finally {
+        term.close();
     }
 }
 
@@ -839,65 +1489,66 @@ function renderChoice(choice, isFocused) {
     return `${pointer} ${label}${hint}`;
 }
 /**
- * Renders the select prompt to the terminal.
+ * Builds the frame lines for the select prompt.
  *
  * @internal
- * @param term - Terminal interface
  * @param config - Prompt configuration
  * @param state - Current prompt state
- * @param submitted - Whether the prompt has been submitted
- * @returns Number of lines rendered
+ * @param maxVisible - Maximum number of visible choices
+ * @returns Logical lines describing the prompt
  */
-function render$1(term, config, state, submitted) {
-    const maxVisible = config.maxVisible ?? 10;
+function buildLines(config, state, maxVisible) {
     const { indices: visibleIndices, startIndex } = getVisibleChoices(state, maxVisible);
-    let output = Ansi.CursorStart + Ansi.ClearLine + renderMessage(config.message);
-    if (submitted) {
-        const actualIndex = state.filteredIndices[state.cursor];
-        const selectedChoice = actualIndex !== undefined ? state.choices[actualIndex] : undefined;
-        /* istanbul ignore next -- @preserve defensive: cursor always within bounds */
-        output += renderSubmitted(selectedChoice?.label ?? '');
-        term.write(output);
-        return 1;
-    }
+    const lines = [];
+    let header = renderMessage(config.message);
     if (config.searchable && state.searchQuery) {
-        output += style.cyan(state.searchQuery) + style.dim(' (type to filter)');
+        header += style.cyan(state.searchQuery) + style.dim(' (type to filter)');
     }
     else if (config.searchable) {
-        output += style.dim('(type to filter, enter to select)');
+        header += style.dim('(type to filter, enter to select)');
     }
     else {
-        output += style.dim('(use arrows, enter to select)');
+        header += style.dim('(use arrows, enter to select)');
     }
-    term.write(output + '\n');
-    let lineCount = 1;
-    const showScrollUp = startIndex > 0;
-    const showScrollDown = startIndex + maxVisible < state.filteredIndices.length;
-    if (showScrollUp) {
-        term.write(Ansi.ClearLine + style.dim(`  ${Symbol.Ellipsis} (${startIndex} more above)`) + '\n');
-        lineCount++;
+    lines.push(header);
+    if (startIndex > 0) {
+        lines.push(style.dim(`  ${Symbol.Ellipsis} (${startIndex} more above)`));
     }
     visibleIndices.forEach((actualIndex, i) => {
         const choice = state.choices[actualIndex];
-        /* istanbul ignore if -- @preserve defensive: actualIndex always valid from filteredIndices */
+        // why: actualIndex always comes from filteredIndices, so this guard is defensive and never taken.
         if (!choice)
             return;
-        const viewIndex = startIndex + i;
-        const isFocused = viewIndex === state.cursor;
-        const line = renderChoice(choice, isFocused);
-        term.write(Ansi.ClearLine + line + '\n');
-        lineCount++;
+        lines.push(renderChoice(choice, startIndex + i === state.cursor));
     });
-    if (showScrollDown) {
+    if (startIndex + maxVisible < state.filteredIndices.length) {
         const remaining = state.filteredIndices.length - (startIndex + maxVisible);
-        term.write(Ansi.ClearLine + style.dim(`  ${Symbol.Ellipsis} (${remaining} more below)`) + '\n');
-        lineCount++;
+        lines.push(style.dim(`  ${Symbol.Ellipsis} (${remaining} more below)`));
     }
     if (state.filteredIndices.length === 0 && config.searchable) {
-        term.write(Ansi.ClearLine + style.dim('  No matches found') + '\n');
-        lineCount++;
+        lines.push(style.dim('  No matches found'));
     }
-    return lineCount;
+    return index_cjs_js.freeze(lines);
+}
+/**
+ * Appends text to the search query, re-filtering choices.
+ *
+ * @internal
+ * @param query - Text to append (a typed character or pasted line)
+ * @param state - Current prompt state
+ * @returns Updated state with the new query applied
+ */
+function appendSearch(query, state) {
+    if (query === '')
+        return state;
+    const newQuery = state.searchQuery + query;
+    return index_cjs_js.freeze({
+        ...state,
+        searchQuery: newQuery,
+        filteredIndices: filterChoices(state.choices, newQuery),
+        cursor: 0,
+        scrollOffset: 0,
+    });
 }
 /**
  * Processes a keypress and returns updated state.
@@ -906,10 +1557,10 @@ function render$1(term, config, state, submitted) {
  * @param key - The key that was pressed
  * @param state - Current prompt state
  * @param config - Prompt configuration
+ * @param maxVisible - Maximum number of visible choices
  * @returns Updated state after processing the key
  */
-function processKey$1(key, state, config) {
-    const maxVisible = config.maxVisible ?? 10;
+function processKey$1(key, state, config, maxVisible) {
     const total = state.filteredIndices.length;
     if (total === 0 && key !== Key.Backspace && key !== '\b')
         return state;
@@ -955,15 +1606,7 @@ function processKey$1(key, state, config) {
             return state;
         }
         if (key.length === 1 && key >= ' ') {
-            const newQuery = state.searchQuery + key;
-            const newFiltered = filterChoices(state.choices, newQuery);
-            return index_cjs_js.freeze({
-                ...state,
-                searchQuery: newQuery,
-                filteredIndices: newFiltered,
-                cursor: 0,
-                scrollOffset: 0,
-            });
+            return appendSearch(key, state);
         }
     }
     return state;
@@ -972,10 +1615,14 @@ function processKey$1(key, state, config) {
  * Prompts for single selection from a list of choices.
  *
  * Pure functional prompt with arrow key navigation, scrolling support,
- * optional disabled choices, and optional type-to-filter search.
+ * optional disabled choices, and optional type-to-filter search. In
+ * searchable mode, pasted text appends its first line to the filter query.
+ * The prompt repaints on terminal resize, preserving cursor and scroll
+ * state.
  *
  * @param config - Select prompt configuration
  * @returns Promise resolving to selected value or cancellation
+ * @throws {Error} When `choices` is empty, or `initial` is not a whole number inside the choice list
  *
  * @example Basic select
  * ```typescript
@@ -1015,52 +1662,67 @@ function processKey$1(key, state, config) {
  * ```
  */
 async function select(config) {
+    assertResolvableChoices('select', config.choices, config.initial === undefined ? [] : [config.initial]);
     const term = createTerminal({ input: config.input, output: config.output });
+    const screen = createScreen(term);
     let state = createInitialState$1(config);
-    let lineCount = 0;
     term.write(Ansi.HideCursor);
-    const redraw = (submitted = false) => {
-        if (lineCount > 0) {
-            term.write(Ansi.cursorUp(lineCount) + Ansi.CursorStart);
-        }
-        term.write(Ansi.ClearToEnd);
-        lineCount = render$1(term, config, state, submitted);
+    const redraw = () => {
+        screen.render(index_cjs_js.freeze({ lines: buildLines(config, state, effectiveMaxVisible(term, config.maxVisible)) }));
     };
-    redraw();
-    while (true) {
-        const key = await term.readKey();
-        if (term.isCancelled()) {
-            if (lineCount > 0) {
-                term.write(Ansi.cursorUp(lineCount) + Ansi.CursorStart);
+    try {
+        redraw();
+        while (true) {
+            const token = await term.readToken();
+            if (term.isCancelled()) {
+                screen.render(index_cjs_js.freeze({ lines: index_cjs_js.freeze([renderMessage(config.message) + renderCancelled()]) }));
+                term.write('\n' + Ansi.ShowCursor);
+                return index_cjs_js.freeze({ result: PromptResult.Cancelled, value: undefined });
             }
-            term.write(Ansi.ClearToEnd);
-            term.write(renderMessage(config.message) + renderCancelled() + '\n');
-            term.write(Ansi.ShowCursor);
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Cancelled, value: undefined });
-        }
-        if (key === Key.Enter) {
-            const actualIndex = state.filteredIndices[state.cursor];
-            if (actualIndex === undefined) {
+            if (token.type === TokenType.Resize) {
+                redraw();
                 continue;
             }
-            const selectedChoice = state.choices[actualIndex];
-            if (!selectedChoice || selectedChoice.disabled) {
+            if (token.type === TokenType.Paste) {
+                if (config.searchable) {
+                    state = appendSearch(firstPasteLine(token.value), state);
+                    redraw();
+                }
                 continue;
             }
-            if (lineCount > 0) {
-                term.write(Ansi.cursorUp(lineCount) + Ansi.CursorStart);
+            if (token.value === Key.Enter) {
+                const actualIndex = state.filteredIndices[state.cursor];
+                if (actualIndex === undefined) {
+                    continue;
+                }
+                const selectedChoice = state.choices[actualIndex];
+                if (!selectedChoice || selectedChoice.disabled) {
+                    continue;
+                }
+                const submittedLine = renderMessage(config.message) + renderSubmitted(selectedChoice.label);
+                screen.render(index_cjs_js.freeze({ lines: index_cjs_js.freeze([submittedLine]) }));
+                term.write('\n' + Ansi.ShowCursor);
+                return index_cjs_js.freeze({ result: PromptResult.Submitted, value: selectedChoice.value });
             }
-            term.write(Ansi.ClearToEnd);
-            render$1(term, config, state, true);
-            term.write('\n');
-            term.write(Ansi.ShowCursor);
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Submitted, value: selectedChoice.value });
+            state = processKey$1(token.value, state, config, effectiveMaxVisible(term, config.maxVisible));
+            redraw();
         }
-        state = processKey$1(key, state, config);
-        redraw();
     }
+    finally {
+        term.close();
+    }
+}
+/**
+ * Resolves the visible-window size, capped so the frame fits the terminal
+ * height (header and scroll-indicator rows reserved).
+ *
+ * @internal
+ * @param term - Terminal used for size queries
+ * @param configured - Configured maximum visible choices
+ * @returns Effective maximum visible choices (at least 1)
+ */
+function effectiveMaxVisible(term, configured) {
+    return index_cjs_js$1.max(1, index_cjs_js$1.min(configured ?? 10, term.getSize().rows - 4));
 }
 
 /**
@@ -1078,40 +1740,63 @@ function createInitialState(config) {
     };
 }
 /**
- * Renders the text prompt to the terminal.
+ * Builds the current prompt message text.
+ *
+ * @internal
+ * @param config - Prompt configuration
+ * @param value - Current input value
+ * @returns Message text for the current value
+ */
+function messageText(config, value) {
+    return config.renderMessage ? config.renderMessage(value) : config.message;
+}
+/**
+ * Builds the frame for the text prompt.
  *
  * @internal
- * @param term - Terminal interface for output
  * @param config - Prompt configuration
  * @param state - Current prompt state
  * @param submitted - Whether the prompt has been submitted
- * @returns Number of lines rendered
+ * @returns Frame describing lines and cursor position
  */
-function render(term, config, state, submitted) {
+function buildFrame(config, state, submitted) {
     const displayValue = config.format ? config.format(state.value) : state.value;
-    const messageText = config.renderMessage ? config.renderMessage(state.value) : config.message;
-    let output = renderMessage(messageText);
-    let trailingChars = 0;
+    let line = renderMessage(messageText(config, state.value));
     if (submitted) {
-        output += renderSubmitted(displayValue || config.initial || '');
+        line += renderSubmitted(displayValue || config.initial || '');
+        return index_cjs_js.freeze({ lines: index_cjs_js.freeze([line]) });
     }
-    else {
-        output += displayValue;
-        trailingChars = displayValue.length - state.cursorPos;
-        if (config.initial && !state.value) {
-            output += style.dim(config.initial);
-            trailingChars += config.initial.length;
-        }
+    line += displayValue;
+    let trailingWidth = displayWidth(state.value.slice(state.cursorPos));
+    if (config.initial && !state.value) {
+        line += style.dim(config.initial);
+        trailingWidth += displayWidth(config.initial);
     }
-    term.write(Ansi.CursorStart + Ansi.ClearLine + output);
+    const cursor = index_cjs_js.freeze({ line: 0, col: displayWidth(line) - trailingWidth });
     if (state.error) {
-        term.write('\n' + style.yellow(`  ${state.error}`));
-        return 2;
-    }
-    if (!submitted && trailingChars > 0) {
-        term.write(Ansi.cursorLeft(trailingChars));
+        return index_cjs_js.freeze({ lines: index_cjs_js.freeze([line, style.yellow(`  ${state.error}`)]), cursor });
     }
-    return 1;
+    return index_cjs_js.freeze({ lines: index_cjs_js.freeze([line]), cursor });
+}
+/**
+ * Inserts text at the cursor position, moving the cursor past it.
+ *
+ * @internal
+ * @param insert - Text to insert (already sanitized for pastes)
+ * @param state - Current prompt state
+ * @returns Updated state after insertion
+ */
+function insertText(insert, state) {
+    if (insert === '')
+        return state;
+    const before = state.value.slice(0, state.cursorPos);
+    const after = state.value.slice(state.cursorPos);
+    return {
+        ...state,
+        value: before + insert + after,
+        cursorPos: state.cursorPos + insert.length,
+        error: undefined,
+    };
 }
 /**
  * Processes a keypress and returns updated state.
@@ -1123,14 +1808,7 @@ function render(term, config, state, submitted) {
  */
 function processKey(key, state) {
     if (key.length === 1 && key >= ' ' && key !== Key.Backspace) {
-        const before = state.value.slice(0, state.cursorPos);
-        const after = state.value.slice(state.cursorPos);
-        return {
-            ...state,
-            value: before + key + after,
-            cursorPos: state.cursorPos + 1,
-            error: undefined,
-        };
+        return insertText(key, state);
     }
     if (key === Key.Backspace || key === '\b') {
         if (state.cursorPos > 0) {
@@ -1147,13 +1825,13 @@ function processKey(key, state) {
     if (key === Key.Left) {
         return {
             ...state,
-            cursorPos: index_cjs_js$2.max(0, state.cursorPos - 1),
+            cursorPos: index_cjs_js$1.max(0, state.cursorPos - 1),
         };
     }
     if (key === Key.Right) {
         return {
             ...state,
-            cursorPos: index_cjs_js$2.min(state.value.length, state.cursorPos + 1),
+            cursorPos: index_cjs_js$1.min(state.value.length, state.cursorPos + 1),
         };
     }
     return state;
@@ -1162,7 +1840,11 @@ function processKey(key, state) {
  * Prompts for text input with optional validation.
  *
  * Pure functional prompt that reads text from the user with support for
- * default values, input validation, and display formatting.
+ * default values, input validation, and display formatting. Pasted text is
+ * sanitized (newlines collapse to spaces, control characters are removed)
+ * and inserted at the cursor without ever auto-submitting. The prompt
+ * repaints on terminal resize, preserving value, cursor, and any
+ * validation error.
  *
  * @param config - Text prompt configuration
  * @returns Promise resolving to submitted value or cancellation
@@ -1196,40 +1878,49 @@ function processKey(key, state) {
  */
 async function text(config) {
     const term = createTerminal({ input: config.input, output: config.output });
+    const screen = createScreen(term);
     let state = createInitialState(config);
-    let lineCount = 0;
     const redraw = (submitted = false) => {
-        if (lineCount > 0) {
-            term.clearLines(lineCount);
-        }
-        lineCount = render(term, config, state, submitted);
+        screen.render(buildFrame(config, state, submitted));
     };
-    redraw();
-    while (true) {
-        const key = await term.readKey();
-        if (term.isCancelled()) {
-            redraw();
-            term.write(renderCancelled() + '\n');
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Cancelled, value: undefined });
-        }
-        if (key === Key.Enter) {
-            const value = state.value || config.initial || '';
-            if (config.validate) {
-                const errorMessage = config.validate(value);
-                if (errorMessage) {
-                    state = { ...state, error: errorMessage };
-                    redraw();
-                    continue;
+    try {
+        redraw();
+        while (true) {
+            const token = await term.readToken();
+            if (term.isCancelled()) {
+                screen.render(index_cjs_js.freeze({ lines: index_cjs_js.freeze([renderMessage(messageText(config, state.value)) + renderCancelled()]) }));
+                term.write('\n');
+                return index_cjs_js.freeze({ result: PromptResult.Cancelled, value: undefined });
+            }
+            if (token.type === TokenType.Resize) {
+                redraw();
+                continue;
+            }
+            if (token.type === TokenType.Paste) {
+                state = insertText(sanitizePasteText(token.value), state);
+                redraw();
+                continue;
+            }
+            if (token.value === Key.Enter) {
+                const value = state.value || config.initial || '';
+                if (config.validate) {
+                    const errorMessage = config.validate(value);
+                    if (errorMessage) {
+                        state = { ...state, error: errorMessage };
+                        redraw();
+                        continue;
+                    }
                 }
+                redraw(true);
+                term.write('\n');
+                return index_cjs_js.freeze({ result: PromptResult.Submitted, value });
             }
-            redraw(true);
-            term.write('\n');
-            term.close();
-            return index_cjs_js.freeze({ result: PromptResult.Submitted, value });
+            state = processKey(token.value, state);
+            redraw();
         }
-        state = processKey(key, state);
-        redraw();
+    }
+    finally {
+        term.close();
     }
 }