@hyperfrontend/questions 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.1](https://github.com/AndrewRedican/hyperfrontend/compare/135d10985b6f139f816af06c6e3996abf338d21d...adf0a4f77dece2be855e7ab88185a4fe84e7b16b) - 2026-09-14
+
+### Bug Fixes
+
+- reject a choice prompt no keypress could resolve
+- submit the text before a trailing line ending in the same chunk
+- cancel a waiting prompt when the input ends
+
 ## [0.3.0](https://github.com/AndrewRedican/hyperfrontend/compare/5f116abb8ba6355dfb283fa03b7481e5eb029480...7e783d3d9e6b6b3a42d226b44256b943958a5813) - 2026-08-04
 
 ### Features

package/FUNDING.md

@@ -38,7 +38,7 @@ GitHub Sponsors benefits:
 
 You can also make a one-time contribution:
 
-**[Donate via hyperfrontend.dev](https://hyperfrontend.dev/sponsor)**
+**[Make a one-time donation via GitHub Sponsors](https://github.com/sponsors/AndrewRedican)**
 
 ### 🏢 Corporate Sponsorship
 

package/README.md

@@ -1,4 +1,8 @@
-# @hyperfrontend/questions
+<p align="center">
+  <a href="https://www.hyperfrontend.dev/docs/libraries/questions/">
+    <img width="640" height="180" src="https://www.hyperfrontend.dev/media/banner-questions/banner.gif" alt="@hyperfrontend/questions">
+  </a>
+</p>
 
 <p align="center">
   <a href="https://github.com/AndrewRedican/hyperfrontend/actions/workflows/ci-lib-questions.yml">
@@ -33,9 +37,16 @@
   <img src="https://img.shields.io/badge/tree%20shakeable-%E2%9C%93-success?style=flat-square" alt="Tree Shakeable">
 </p>
 
+<p align="center">
+  <a href="https://www.hyperfrontend.dev/docs/libraries/questions/">
+    <img width="640" height="360" src="https://www.hyperfrontend.dev/media/questions-prompt/hero.gif" alt="A multiselect prompt being programmed on the left and answered on the right, ending in a submitted result object">
+  </a>
+</p>
+
 Terminal prompting library with composable, functional API for text, select, confirm, and multiselect prompts
 
 • 👉 See [**documentation**](https://www.hyperfrontend.dev/docs/libraries/questions/)
+• 👉 See [**guides & tutorials**](https://www.hyperfrontend.dev/docs/guides/?package=%40hyperfrontend%2Fquestions)
 
 ## What is @hyperfrontend/questions?
 
@@ -43,32 +54,30 @@ A terminal prompting library built on functional programming principles. Create
 
 ### Key Features
 
-- **Pure Functions** — Every prompt is a pure function returning `Promise<PromptOutcome<T>>`, making results predictable and easily testable
-- **Composable API** — Build complex interactive flows by combining simple prompt functions
-- **Type-Safe** — Full TypeScript support with discriminated unions for prompt outcomes
-- **Zero External Dependencies** — Uses only Node.js built-ins and `@hyperfrontend` utilities
-- **Searchable Multiselect** — Type-to-filter functionality for large option lists
-- **Clipboard Paste** — Bracketed paste mode on TTYs (with a multi-character-chunk fallback elsewhere); pasted text is sanitized and never auto-submits
-- **Resize-Aware Rendering** — Prompts hard-wrap to the terminal width and repaint on resize, preserving value, cursor, selection, and validation state
+- **Pure Functions**: Every prompt is a pure function returning `Promise<PromptOutcome<T>>`, making results predictable and easily testable
+- **[Composable API](https://www.hyperfrontend.dev/docs/guides/build-a-setup-wizard-for-your-cli/)**: Build complex interactive flows by combining simple prompt functions
+- **[Type-Safe](https://www.hyperfrontend.dev/docs/libraries/questions/#api-PromptOutcome)**: Full TypeScript support with discriminated unions for prompt outcomes
+- **Zero External Dependencies**: Uses only Node.js built-ins and `@hyperfrontend` utilities
+- **[Searchable Multiselect](https://www.hyperfrontend.dev/docs/libraries/questions/#api-multiselect)**: Type-to-filter functionality for large option lists
+- **Clipboard Paste**: Bracketed paste mode on TTYs (with a multi-character-chunk fallback elsewhere); pasted text is sanitized, and a bracketed paste never auto-submits
+- **End of input is a cancellation**: when the input stream ends, a waiting prompt resolves as cancelled instead of waiting for a key that can never arrive
+- **Unanswerable configurations throw**: a choice prompt with no choices, or a starting index outside its list, rejects with an error rather than painting a frame nothing can answer
+- **Resize-Aware Rendering**: Prompts hard-wrap to the terminal width and repaint on resize, preserving value, cursor, selection, and validation state
 
 ### Architecture Highlights
 
-Each prompt follows a functional state machine pattern:
-
-- **Immutable State** — All prompt state is frozen; updates create new state objects
-- **Explicit Outcomes** — Prompts return either `{ result: 'submitted', value: T }` or `{ result: 'cancelled', value: undefined }`
-- **Terminal Abstraction** — Low-level I/O is encapsulated in a `Terminal` interface for testability
-- **Token Input Stream** — Raw input is tokenized into keys, pastes, and resize notifications by a persistent listener, with raw mode held for the whole prompt session and restored on close
-- **Frame Renderer** — A width-aware screen helper erases and repaints exact frames; on resize it recomputes the previous frame's height at the new width (assumes a reflowing terminal; display width is code-point based, east-asian double width out of scope)
+- **Explicit outcomes**: prompts resolve to either `{ result: 'submitted', value: T }` or `{ result: 'cancelled', value: undefined }`, so Ctrl+C is an ordinary branch to handle rather than a rejection to catch
+- **Terminal state is restored**: raw mode is taken once for the whole prompt session and given back when it closes, on cancel as well as on submit
+- **Rendering assumptions**: repainting on resize assumes a reflowing terminal, and display width is counted in code points, so east-asian double-width characters are out of scope
 
 ## Why Use @hyperfrontend/questions?
 
 When building CLI tools, you need interactive prompts that are:
 
-1. **Predictable** — Know exactly what a prompt returns, always
-2. **Composable** — Chain prompts without callback hell
-3. **Cancellable** — Handle Ctrl+C gracefully with structured cancellation
-4. **Lightweight** — No large dependency trees for simple prompts
+1. **Predictable**: Know exactly what a prompt returns, always
+2. **Composable**: Chain prompts without callback hell
+3. **Cancellable**: Handle Ctrl+C gracefully with structured cancellation
+4. **Lightweight**: No large dependency trees for simple prompts
 
 This library provides all four while staying true to functional programming principles.
 
@@ -93,7 +102,7 @@ if (nameResult.result === PromptResult.Submitted) {
   console.log(`Hello, ${nameResult.value}!`)
 }
 
-// Text input with a live label — `renderMessage` is recomputed on every keystroke
+// Text input with a live label; `renderMessage` is recomputed on every keystroke
 import { style } from '@hyperfrontend/questions'
 
 await text({
@@ -135,33 +144,34 @@ const featuresResult = await multiselect({
 
 ## API Overview
 
-| Function       | Description                                                                   |
-| -------------- | ----------------------------------------------------------------------------- |
-| `text`         | Free-form text input with optional validation and live-updating labels        |
-| `confirm`      | Yes/no confirmation prompt                                                    |
-| `select`       | Single selection from a list of choices                                       |
-| `multiselect`  | Multiple selections with optional search                                      |
-| `style`        | ANSI colour helpers (`green`, `yellow`, `red`, `cyan`, `bold`, `dim`, `gray`) |
-| `PromptResult` | Discriminated union: `'submitted' \| 'cancelled'`                             |
-
-All prompts return `Promise<PromptOutcome<T>>` where:
+Four prompts, one shape. [`text`](https://www.hyperfrontend.dev/docs/libraries/questions/#api-text), [`confirm`](https://www.hyperfrontend.dev/docs/libraries/questions/#api-confirm), [`select`](https://www.hyperfrontend.dev/docs/libraries/questions/#api-select) and [`multiselect`](https://www.hyperfrontend.dev/docs/libraries/questions/#api-multiselect) each take a config object and resolve to the same discriminated union, so the code that reads an answer is the same code whichever question asked it:
 
 ```typescript
 type PromptOutcome<T> = { result: 'submitted'; value: T } | { result: 'cancelled'; value: undefined }
 ```
 
+Two things sit beside them. [`style`](https://www.hyperfrontend.dev/docs/libraries/questions/#api-style) is the ANSI colour helper the prompts use on their own labels, exposed so yours can match. And every config takes [`input`](https://www.hyperfrontend.dev/docs/libraries/questions/#api-PromptConfig-prop-input) and [`output`](https://www.hyperfrontend.dev/docs/libraries/questions/#api-PromptConfig-prop-output) streams, which is what makes a prompt testable without a TTY: hand it a pair of `PassThrough`s, write keystrokes into one and read frames out of the other.
+
+Every config, option and outcome type is in the [API reference](https://www.hyperfrontend.dev/docs/libraries/questions/#api-reference).
+
 ## Compatibility
 
-| Environment                    | Supported |
-| ------------------------------ | --------- |
-| Node.js >= 18                  | ✅        |
-| TTY Terminal                   | ✅        |
-| Bracketed paste (TTY)          | ✅        |
-| Resize redraw (SIGWINCH)       | ✅        |
-| Non-TTY streams (tests, pipes) | ✅        |
-| Tree Shakeable                 | ✅        |
+<p align="center">
+  <a href="https://www.hyperfrontend.dev/docs/libraries/questions/#compatibility">
+    <img width="640" height="150" src="https://www.hyperfrontend.dev/media/runtimes-questions/runtimes.png" alt="Runs in Node.js 18 or later; not a target for evergreen browsers and web workers">
+  </a>
+</p>
+
+Prompts run on a TTY, where the session redraws when the terminal is resized, and on non-TTY streams such as tests and pipes. On TTY inputs a prompt session enables bracketed paste mode (`ESC[?2004h`) and restores it on close; terminals without bracketed paste still paste correctly because multi-character input chunks are treated as pastes. Single-line prompts collapse pasted newlines into spaces, so a bracketed paste can never submit a value. Where bracketed paste is unavailable, a chunk that ends in a line ending submits the text before it, which is how a line-buffered reader behaves and is what makes piped input work; line endings in the middle of such a chunk stay data.
+
+### Output Formats
+
+| Format | File           | Tree-Shakeable |
+| ------ | -------------- | :------------: |
+| ESM    | `index.esm.js` |       ✅       |
+| CJS    | `index.cjs.js` |       ❌       |
 
-On TTY inputs a prompt session enables bracketed paste mode (`ESC[?2004h`) and restores it on close; terminals without bracketed paste still paste correctly because multi-character input chunks are treated as pastes. Single-line prompts collapse pasted newlines into spaces, so pasting can never submit a value.
+No browser bundle is published: the library drives a terminal, so an IIFE or UMD build would have nothing to run against.
 
 ## License
 

package/SECURITY.md

@@ -7,18 +7,18 @@ Before reporting or reviewing, read the model this project is built on:
 statement of what hyperfrontend defends against and what it does not, and it is the reference every
 other security claim in these docs points back to. In short:
 
-- **The named adversary is co-resident script** — an analytics snippet, tag manager, compromised
+- **The named adversary is co-resident script**: an analytics snippet, tag manager, compromised
   dependency, or unknown page that embeds a feature URL. A host that deliberately installs a feature
   is trusting it, the way it trusts any dependency; the controls exist to bound a trusted
   feature's bad day, not to treat its authors as hostile.
 - **Origin checks authenticate rooms, not speakers.** Once arbitrary script runs inside a page, no
   message check distinguishes it from the application. Threats inside a page need Content Security
-  Policy, Trusted Types, dependency provenance, and server-side authorisation — a different
+  Policy, Trusted Types, dependency provenance, and server-side authorisation. That is a different
   treatment, deliberately outside this model.
 - **Three parties carry the security of an integration.** The browser enforces document isolation
   and the frame's capability attributes; the protocol enforces the relationship (pinned
   counterparts, gated handshake, validated payloads, versioned contracts, an optional encrypted
-  envelope); and **you** decide authorisation — `frame-ancestors`, backend checks, HTTPS, the
+  envelope); and **you** decide authorisation: `frame-ancestors`, backend checks, HTTPS, the
   envelope you choose, and the containment posture you set.
 
 A vulnerability report is most useful when it names which of those three the issue defeats.
@@ -93,7 +93,7 @@ ends — is on by default and is not something you should be re-implementing by
    Protected work needs credentials the feature's own backend validates.
 3. **Choose the envelope deliberately.** `v2` with a pre-shared key is the confidentiality control;
    `v1` is time-window obfuscation and buys deterrence only. Provision and rotate the `v2` key
-   yourself — a key is never baked into a built artifact. A handshake that cannot agree on an
+   yourself; a key is never baked into a built artifact. A handshake that cannot agree on an
    encrypted transport falls back to plaintext; where that would be unacceptable, drive
    `@hyperfrontend/nexus` directly and set `security.mode: 'fail-closed'` on the channel so the
    connection is denied instead.

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const _Error = globalThis.Error;
+const _Reflect = globalThis.Reflect;
+const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
+exports.createError = createError;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js

@@ -0,0 +1,5 @@
+const _Error = globalThis.Error;
+const _Reflect = globalThis.Reflect;
+const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
+
+export { createError };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.cjs.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const _Number = globalThis.Number;
+const isInteger = _Number.isInteger;
+exports.isInteger = isInteger;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js

@@ -0,0 +1,4 @@
+const _Number = globalThis.Number;
+const isInteger = _Number.isInteger;
+
+export { isInteger };

package/index.cjs.js

@@ -5,6 +5,8 @@ const node_readline = require('node:readline');
 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');
 
 /**
  * ANSI-aware text measurement helpers.
@@ -121,12 +123,17 @@ function displayWidth(text) {
  * 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.
+ * 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. */
@@ -187,7 +194,11 @@ function partialMarkerStart(data, from, marker) {
  * 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.
+ * 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
  *
@@ -251,9 +262,23 @@ function createTokenParser() {
                 end++;
             }
             const run = data.slice(pos, end);
-            // why: raw mode delivers one keystroke per chunk, so a longer run means the terminal pasted without bracketed-paste support
-            tokens.push(run.length === 1 ? keyToken(run) : pasteToken(run));
             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);
     };
@@ -350,7 +375,9 @@ const Ansi = index_cjs_js.freeze({
  * 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.
+ * 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
@@ -414,6 +441,10 @@ function createTerminal(config = {}) {
     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;
@@ -424,6 +455,7 @@ function createTerminal(config = {}) {
             write(Ansi.BracketedPasteOn);
         }
         input.on('data', onData);
+        input.once('end', onEnd);
         output.on('resize', onResize);
         input.resume();
     };
@@ -432,6 +464,7 @@ function createTerminal(config = {}) {
             return;
         sessionActive = false;
         input.removeListener('data', onData);
+        input.removeListener('end', onEnd);
         output.removeListener('resize', onResize);
         if (input.setRawMode) {
             write(Ansi.BracketedPasteOff);
@@ -943,6 +976,44 @@ function firstPasteLine(raw) {
     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}`);
+        }
+    }
+}
+
 /**
  * Checks if an array includes a value.
  *
@@ -1081,7 +1152,7 @@ function buildLines$1(config, state, maxVisible) {
     }
     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 isFocused = startIndex + i === state.cursor;
@@ -1162,7 +1233,7 @@ function processKey$2(key, state, config, maxVisible) {
         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);
@@ -1239,6 +1310,7 @@ function effectiveMaxVisible$1(term, configured) {
  *
  * @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
@@ -1276,6 +1348,7 @@ function effectiveMaxVisible$1(term, configured) {
  * ```
  */
 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);
@@ -1443,7 +1516,7 @@ function buildLines(config, state, maxVisible) {
     }
     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;
         lines.push(renderChoice(choice, startIndex + i === state.cursor));
@@ -1549,6 +1622,7 @@ function processKey$1(key, state, config, maxVisible) {
  *
  * @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
@@ -1588,6 +1662,7 @@ function processKey$1(key, state, config, maxVisible) {
  * ```
  */
 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);

package/index.d.ts

@@ -150,6 +150,7 @@ declare function confirm(config: ConfirmConfig): Promise<PromptOutcome<boolean>>
  *
  * @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
@@ -199,6 +200,7 @@ declare function multiselect<T = string>(config: MultiselectConfig<T>): Promise<
  *
  * @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

package/index.esm.js

@@ -3,6 +3,8 @@ import { createInterface } from 'node:readline';
 import { StringDecoder } from 'node:string_decoder';
 import { createPromise, promiseResolve } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
 import { min, max, floor, ceil } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js';
+import { createError } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { isInteger } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js';
 
 /**
  * ANSI-aware text measurement helpers.
@@ -119,12 +121,17 @@ function displayWidth(text) {
  * 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.
+ * 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. */
@@ -185,7 +192,11 @@ function partialMarkerStart(data, from, marker) {
  * 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.
+ * 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
  *
@@ -249,9 +260,23 @@ function createTokenParser() {
                 end++;
             }
             const run = data.slice(pos, end);
-            // why: raw mode delivers one keystroke per chunk, so a longer run means the terminal pasted without bracketed-paste support
-            tokens.push(run.length === 1 ? keyToken(run) : pasteToken(run));
             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 freeze(tokens);
     };
@@ -348,7 +373,9 @@ const Ansi = freeze({
  * 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.
+ * 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
@@ -412,6 +439,10 @@ function createTerminal(config = {}) {
     const onResize = () => {
         deliver(freeze([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(freeze([freeze({ type: TokenType.Key, value: Key.CtrlC })]));
+    };
     const openSession = () => {
         if (sessionActive)
             return;
@@ -422,6 +453,7 @@ function createTerminal(config = {}) {
             write(Ansi.BracketedPasteOn);
         }
         input.on('data', onData);
+        input.once('end', onEnd);
         output.on('resize', onResize);
         input.resume();
     };
@@ -430,6 +462,7 @@ function createTerminal(config = {}) {
             return;
         sessionActive = false;
         input.removeListener('data', onData);
+        input.removeListener('end', onEnd);
         output.removeListener('resize', onResize);
         if (input.setRawMode) {
             write(Ansi.BracketedPasteOff);
@@ -941,6 +974,44 @@ function firstPasteLine(raw) {
     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 createError(`${promptName} requires at least one choice`);
+    }
+    for (const index of initial) {
+        if (!isInteger(index) || index < 0 || index >= choices.length) {
+            throw createError(`${promptName} initial must be an index between 0 and ${choices.length - 1}, received ${index}`);
+        }
+    }
+}
+
 /**
  * Checks if an array includes a value.
  *
@@ -1079,7 +1150,7 @@ function buildLines$1(config, state, maxVisible) {
     }
     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 isFocused = startIndex + i === state.cursor;
@@ -1160,7 +1231,7 @@ function processKey$2(key, state, config, maxVisible) {
         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);
@@ -1237,6 +1308,7 @@ function effectiveMaxVisible$1(term, configured) {
  *
  * @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
@@ -1274,6 +1346,7 @@ function effectiveMaxVisible$1(term, configured) {
  * ```
  */
 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);
@@ -1441,7 +1514,7 @@ function buildLines(config, state, maxVisible) {
     }
     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;
         lines.push(renderChoice(choice, startIndex + i === state.cursor));
@@ -1547,6 +1620,7 @@ function processKey$1(key, state, config, maxVisible) {
  *
  * @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
@@ -1586,6 +1660,7 @@ function processKey$1(key, state, config, maxVisible) {
  * ```
  */
 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfrontend/questions",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Terminal prompting library with composable, functional API for text, select, confirm, and multiselect prompts",
   "license": "MIT",
   "exports": {