@hyperfrontend/questions 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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
+
+- support clipboard paste and resize-aware redraw
+
 ## [0.2.1](https://github.com/AndrewRedican/hyperfrontend/compare/926d40cab470e589fc30a1ef3a61ca764ff047bd...466c0388c4cd516b9c704214140b4df1004098e6) - 2026-06-23
 
 ### Other

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,28 +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
+- **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
+- **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.
 
@@ -89,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({
@@ -131,28 +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   | ✅        |
-| 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` |       ❌       |
+
+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

@@ -1,5 +1,28 @@
 # Security Policy
 
+## The Security Model
+
+Before reporting or reviewing, read the model this project is built on:
+**[Security Model](https://www.hyperfrontend.dev/docs/core-concepts/security)**. It is the canonical
+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
+  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. 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 you choose, and the containment posture you set.
+
+A vulnerability report is most useful when it names which of those three the issue defeats.
+
 ## Reporting a Vulnerability
 
 We take the security of hyperfrontend seriously. If you discover a security vulnerability, please help us protect our users by following responsible disclosure practices.
@@ -58,14 +81,30 @@ Thank you for helping keep hyperfrontend and its users safe!
 
 ## Security Best Practices
 
-When using hyperfrontend in your applications:
-
-1. **Keep Dependencies Updated**: Regularly update to the latest version to receive security patches
-2. **Content Security Policy**: Implement appropriate CSP headers when embedding features
-3. **Input Validation**: Validate and sanitize all data passed between features
-4. **Origin Verification**: Always verify the origin of messages in cross-frame communication
-5. **Authentication**: Implement proper authentication and authorization for sensitive features
-6. **HTTPS**: Always serve hyperfrontend features over HTTPS in production
+These are the decisions the SDK cannot make for you. Everything the protocol already enforces —
+origin pinning, window binding, instance identity, the gated handshake, payload validation on both
+ends — is on by default and is not something you should be re-implementing by hand.
+
+1. **Restrict who may embed the feature.** Send
+   `Content-Security-Policy: frame-ancestors <hosts>` on the response that serves the feature
+   document. Origin pinning keeps a conversation consistent; only `frame-ancestors` decides whether
+   a page was ever allowed to frame you.
+2. **Authorise on the server.** A message that crossed the boundary is not an authorised operation.
+   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
+   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.
+4. **Declare schemas and a contract version.** Actions without a schema pass unvalidated, and a side
+   without a version always passes the compatibility gate. Both are how drift is caught early.
+5. **Grant capability narrowly.** Delegate only the Permissions-Policy features the integration
+   needs, and price a `sandbox` posture against what the product actually requires.
+6. **Serve everything over HTTPS**, host and feature alike.
+7. **Keep dependencies updated** on both sides of the boundary, and pair that with the page-integrity
+   controls this model deliberately leaves to you: Content Security Policy, Trusted Types,
+   Subresource Integrity, and dependency provenance.
 
 ## Security Updates
 
@@ -73,10 +112,6 @@ Security updates will be released as patch versions and documented in the [CHANG
 
 ## Supported Versions
 
-We currently provide security updates for:
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.0.x   | :white_check_mark: |
-
-As the project matures, we will update this table to reflect our long-term support policy.
+Security updates are provided for the latest published version of each `@hyperfrontend/*` package.
+Older releases receive no backports. A long-term support policy will replace this section once the
+packages settle on a stable release cadence.

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/math/index.cjs.js

@@ -1,7 +1,11 @@
 'use strict';
 
 const _Math = globalThis.Math;
+const ceil = _Math.ceil;
+const floor = _Math.floor;
 const max = _Math.max;
 const min = _Math.min;
+exports.ceil = ceil;
+exports.floor = floor;
 exports.max = max;
 exports.min = min;

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

@@ -1,5 +1,7 @@
 const _Math = globalThis.Math;
+const ceil = _Math.ceil;
+const floor = _Math.floor;
 const max = _Math.max;
 const min = _Math.min;
 
-export { max, min };
+export { ceil, floor, max, min };

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/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js

@@ -3,4 +3,6 @@
 const _Promise = globalThis.Promise;
 const _Reflect = globalThis.Reflect;
 const createPromise = (executor) => _Reflect.construct(_Promise, [executor]);
+const promiseResolve = _Promise.resolve.bind(_Promise);
 exports.createPromise = createPromise;
+exports.promiseResolve = promiseResolve;

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

@@ -1,5 +1,6 @@
 const _Promise = globalThis.Promise;
 const _Reflect = globalThis.Reflect;
 const createPromise = (executor) => _Reflect.construct(_Promise, [executor]);
+const promiseResolve = _Promise.resolve.bind(_Promise);
 
-export { createPromise };
+export { createPromise, promiseResolve };