caique 0.1.1 → 0.3.0

package/README.md

@@ -14,7 +14,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/caique"><img src="https://img.shields.io/npm/v/caique?style=flat-square&color=0a6b47" alt="npm version" /></a>
   <img src="https://img.shields.io/badge/status-pre--release-a84c17?style=flat-square" alt="Status: pre-release" />
-  <img src="https://img.shields.io/badge/runtime%20dependencies-0-0a6b47?style=flat-square" alt="Zero runtime dependencies" />
+  <img src="https://img.shields.io/badge/dependencies-closeout-0a6b47?style=flat-square" alt="One dependency: closeout" />
   <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" />
 </p>
 
@@ -35,12 +35,13 @@ flags in, a verdict out.
 
 ```js
 import { decide } from 'caique/decide';
+import { processRuntime } from 'caique';
 
 decide({
   value: undefined,                                  // nothing was passed
   spec: { kind: 'text', message: 'Where should it go?' },
   option: 'output-dir',
-  runtime: { env: process.env, isTTY: { stdin: process.stdin.isTTY } },
+  runtime: processRuntime(),                         // or your own { env, isTTY: { stdin } }
   required: true,
 });
 // no terminal -> { action: 'error', code: 'USAGE',
@@ -101,7 +102,7 @@ import { resolvePrompts } from 'caique/binding';
 const { values, failure } = await resolvePrompts({
   options,            // { name: { required: true, prompt: { kind: 'text', message: 'Project name?' } } }
   values,             // what every other source resolved
-  runtime: { env: process.env, isTTY: { stdin: process.stdin.isTTY } },
+  runtime: processRuntime(),
   flags: { json, yes, interactive },
   io: { reader, writer },
 });
@@ -125,7 +126,7 @@ that touches a terminal:
 import { createIo } from 'caique/terminal';
 import { ask } from 'caique/ask';
 
-const io = createIo({ input: process.stdin, output: process.stdout });
+const io = createIo();   // the terminal the program was started in
 await ask({ kind: 'password', message: 'Token?' }, io);
 io.close();
 ```
@@ -144,9 +145,11 @@ not a second implementation:
 
 ```js
 import { askList, canRender } from 'caique/raw';
-import { createIo } from 'caique/terminal';
+import { createIo, streamsOf } from 'caique/terminal';
+import { processRuntime } from 'caique';
 
-const io = { ...createIo({ input: process.stdin, output: process.stdout }), keys: process.stdin };
+const rt = processRuntime();
+const io = { ...createIo(streamsOf(rt)), keys: rt.stdin };
 const spec = { kind: 'select', message: 'Which host?', choices: [{ value: 'ora' }, { value: 'chalk' }] };
 const answer = canRender(io.keys) ? await askList(spec, io) : await ask(spec, io);
 ```
@@ -190,7 +193,37 @@ counted whole across its own resolved tree.
 - **`--interactive`** asks for every missing required option in one pass; **`--yes`** accepts
   every confirmation; cancellation exits `CANCELLED` and restores the terminal.
 - **Accessible mode** falls back to line input with no live redraw.
-- **Drop-in paths** for inquirer and clack, graded by their own suites.
+- **A migration path from `@inquirer/prompts` and `@clack/prompts`**, graded by their own
+  suites. See below for what that is graded at today, which is zero.
+
+## Which incumbents this is measured against
+
+**`@inquirer/prompts`** (28.8 M/wk) and **`@clack/prompts`**. Those two, and not the
+package whose download count is larger:
+
+- **`inquirer` (34.3 M/wk) is out of scope, deliberately.** Its 34 million are the *legacy*
+  `inquirer.prompt([...])` façade, an API its own maintainer moved off; a new CLI written
+  today writes `@inquirer/prompts`. Reproducing the legacy object API would be work spent
+  on a shape nobody new adopts, and it is not on this package's roadmap.
+- **`@inquirer/core`** is what the compatibility oracle grades, because it is where the
+  prompt *loop* — the keypress state machine both façades sit on — is actually tested.
+  `inquirer`'s own npm tarball ships **no tests at all**, so there is nothing there to grade.
+
+| Incumbent's suite | Cases | Their own package | `caique` |
+| :-- | --: | --: | --: |
+| [`@inquirer/core` 12.0.3](https://github.com/SBoudrias/Inquirer.js) | 41 | 41 (100%) | **0 (0.0%)** |
+| [`@clack/prompts` 1.8.1](https://github.com/bombshell-dev/clack) | 606 | 576 (95.0%) | **0 (0.0%)** |
+
+Measured 2026-09-14 by `npm run compat`, which runs each incumbent's own unedited suite
+twice: once against the incumbent (the control — the column that proves the gate works)
+and once against caique. **Both caique columns are zero, and they are zero because no
+façade exists yet** — `caique` exports `ask`, `decide` and `spec`, not `createPrompt` or
+`text` in their spelling. The row is here because a claimed replacement with no number
+beside it is a claim; this is the number, and it can only go up from here.
+
+The 30 cases `@clack/prompts` fails against itself are `path.test.ts`, which mocks
+`node:fs` in a way this repository's vitest does not reproduce — a harness divergence,
+recorded with its reason in `packages/compat-oracle/src/hosts.ts` rather than rounded away.
 
 ## Following along
 
@@ -207,7 +240,27 @@ and argue with it — before it exists:
 Part of the [burgee](https://github.com/ofri-peretz/burgee) family: a CLI on
 [burgee](https://www.npmjs.com/package/burgee) declares what it is,
 [roundel](https://www.npmjs.com/package/roundel) carries its colours,
-[flagstaff](https://www.npmjs.com/package/flagstaff) flies it, and caique answers back. Each
-is an independent package; none requires the others.
+[flagstaff](https://www.npmjs.com/package/flagstaff) flies it, and caique answers back.
+caique installs one of them: [closeout](https://www.npmjs.com/package/closeout), because a
+prompt hides the cursor and owes it back however the process dies, and there is exactly one
+correct implementation of that. Nothing outside this repository is installed.
 
 MIT © Ofri Peretz — see [LICENSE](./LICENSE).
+
+## Benchmarks
+
+Every number here is produced by `npm run bench` and published at [/docs/benchmarks](/docs/benchmarks).
+
+Graded by the incumbent's own test suite:
+
+| suite | passing |
+| :-- | --: |
+| `clack` | 14 / 17 |
+| `inquirer-core` | 41 / 41 |
+
+Weight, installed and tree-inclusive: **84,740 bytes** against **182,219** for the incumbents it replaces — a ratio of **0.4650** (@inquirer/core not installed here, so the ceiling is understated).
+## Where it sits
+
+Plugins register under the `widgets` key, against the one schema the whole family shares.
+
+Nothing in this family builds on it yet, and it builds on `closeout` and `linegauge`.

package/dist/ask.js

@@ -1,44 +1,21 @@
-/**
- * The six widgets, in line mode (R5) — and line mode is not a fallback, it is the floor.
- *
- * Every widget here works by writing a question and reading a line. No raw mode, no cursor
- * movement, no escape sequence, no redraw. That makes it the accessible mode by
- * construction rather than by a second implementation kept in step by hand: a screen
- * reader gets the same bytes a terminal does, and `select` is a numbered list because a
- * numbered list is what a person can answer without seeing a highlight move.
- *
- * It is also what makes the widgets testable without a PTY. A `Reader` is one method that
- * returns the next line, so the whole suite is strings in and strings out; the raw-mode
- * renderer that arrows and highlights will come later sits *on top* of this and answers
- * the same questions, which is how it stays honest.
- *
- * Nothing here reads `process`, and nothing decides *whether* to ask — that is `decide()`,
- * which runs first and refuses when there is no one to ask.
- */
-import {} from './spec.js';
 const CANCELLED = { ok: false, reason: 'cancelled' };
-/** Re-asking forever on invalid input is a hang with extra steps. */
 const MAX_ATTEMPTS = 5;
 const DECIMAL = 10;
 const YES = new Set(['y', 'yes', 'true', '1']);
 const NO = new Set(['n', 'no', 'false', '0']);
-/** `Overwrite it? (y/N)` — the default in capitals, the convention every CLI already uses. */
 function confirmSuffix(initial) {
     return initial === true ? ' (Y/n) ' : ' (y/N) ';
 }
 function textSuffix(initial) {
     return typeof initial === 'string' && initial !== '' ? ` (${initial}) ` : ' ';
 }
-/** The numbered list R5 asks for. One-based, because a person is reading it. */
 function listChoices(choices) {
     return choices.map((choice, index) => `  ${index + 1}) ${choice.label ?? choice.value}${choice.hint === undefined ? '' : ` — ${choice.hint}`}`).join('\n');
 }
-/** A 1-based index into `choices`, or nothing when the answer names no choice. */
 function pick(answer, choices) {
     const index = Number.parseInt(answer, DECIMAL);
     if (Number.isInteger(index) && index >= 1 && index <= choices.length)
         return choices[index - 1];
-    // A person who types the label rather than its number has answered the question.
     return choices.find((choice) => choice.value === answer || choice.label === answer);
 }
 function confirmAttempt(spec, label) {
@@ -83,11 +60,6 @@ function multiselectAttempt(choices, label) {
         },
     };
 }
-/**
- * text, password and path all read a line. `password` differs only in that the caller must
- * not echo it, which is the reader's business — this module never sees a terminal, so
- * hiding the input cannot be got wrong here.
- */
 function lineAttempt(spec, label) {
     return {
         question: label + textSuffix(spec.initial),
@@ -108,23 +80,11 @@ function attemptFor(spec, label) {
         return multiselectAttempt(choices, label);
     return lineAttempt(spec, label);
 }
-/**
- * Ask one prompt and return its answer.
- *
- * A stream that ends is a cancellation, not an empty answer: `Ctrl-D` and a closed pipe
- * both mean nobody is going to type, and treating that as `''` is how a program ends up
- * writing to a path the user never chose. Invalid input is re-asked, bounded — after
- * `MAX_ATTEMPTS` it gives up rather than looping, because a loop against a stream that
- * keeps answering wrongly is the hang this package exists to prevent, wearing a hat.
- */
 export async function ask(prompt, io) {
     const label = prompt.message;
     for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
         const { question, parse } = attemptFor(prompt, label);
         io.writer.write(question);
-        // A prompt is a conversation: the next question depends on the last answer, which is
-        // what sequential means. Promise.all() would ask all five at once and read none.
-        // eslint-disable-next-line reliability/no-await-in-loop -- see above
         const line = await io.reader.line({ hidden: prompt.kind === 'password' });
         if (line === undefined)
             return CANCELLED;
@@ -136,13 +96,7 @@ export async function ask(prompt, io) {
     io.writer.write(`  giving up after ${MAX_ATTEMPTS} attempts\n`);
     return CANCELLED;
 }
-/**
- * What a widget would have written, without reading anything — the static projection (U3).
- * The docs gallery, `--help` and a transcript in an issue all want the question without
- * the conversation, and every other package in this family can answer that; so does this.
- */
 export function projection(spec) {
     const { question } = attemptFor(spec, spec.message);
     return question.trimEnd();
 }
-//# sourceMappingURL=ask.js.map

package/dist/binding.js

@@ -1,25 +1,6 @@
-/**
- * Resolving a whole command's prompts in one pass (R2, R3) — the piece a framework calls
- * from its `preAction` hook, after the environment and config layers have had their turn.
- *
- * The design sketched this as `caique/burgee`, one binding per host. It is one binding for
- * all of them instead, and that is the better answer: what a host actually supplies is a
- * record of options, the values parsed so far, and a runtime. None of that needs burgee's
- * types, so nothing here imports them — which keeps the family's rule that no package
- * requires another, and means `burgee`, `burgee/commander` and `burgee/yargs` share one
- * implementation rather than three that drift.
- *
- * The order is the declaration order, because `--interactive` asks for several things at
- * once and a person answering them needs the sequence to match the help they just read.
- */
 import { ask } from './ask.js';
 import { decide } from './decide.js';
 import { problemWith } from './spec.js';
-/**
- * One option's verdict, before any terminal is consulted. A spec that cannot be drawn is
- * caught here rather than in the widget: better to say so than to draw an empty list and
- * wait, which is the hang this package exists to prevent.
- */
 function verdictFor({ option, prompt, required, value, runtime, flags }) {
     const malformed = problemWith(prompt);
     if (malformed !== undefined)
@@ -30,13 +11,6 @@ function verdictFor({ option, prompt, required, value, runtime, flags }) {
     return verdict;
 }
 const isFailure = (v) => !('action' in v);
-/**
- * Walk the command's options in order, asking only what has to be asked.
- *
- * Stops at the first refusal: the caller is about to exit, and a person told about six
- * missing flags — one of which they would have answered interactively — has been given a
- * worse message than one told about the first.
- */
 export async function resolvePrompts({ options, values, runtime, flags, io }) {
     const out = { ...values };
     for (const [option, spec] of Object.entries(options)) {
@@ -52,9 +26,6 @@ export async function resolvePrompts({ options, values, runtime, flags, io }) {
             out[option] = verdict.value;
             continue;
         }
-        // Asked one at a time on purpose: a person answers in sequence, and asking the second
-        // question before the first is answered would interleave two prompts on one terminal.
-        // eslint-disable-next-line reliability/no-await-in-loop -- see above
         const answer = await ask(prompt, io);
         if (!answer.ok) {
             return { values: out, failure: { option, code: 'CANCELLED', message: `cancelled at --${option}`, fix: `pass --${option} to skip the question` } };
@@ -63,4 +34,3 @@ export async function resolvePrompts({ options, values, runtime, flags, io }) {
     }
     return { values: out };
 }
-//# sourceMappingURL=binding.js.map

package/dist/clack.d.ts

@@ -0,0 +1,44 @@
+/** A stream a list can measure itself against. Anything with a size, including a test double. */
+export interface SizedOutput {
+    columns?: number;
+    rows?: number;
+}
+/** The streams and settings every clack call accepts. */
+export interface CommonOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream & SizedOutput;
+    signal?: AbortSignal;
+    withGuide?: boolean;
+}
+/** What `limitOptions` takes. Named as the incumbent names it, because callers import it. */
+export interface LimitOptionsParams<TOption> extends CommonOptions {
+    /** The list to display. */
+    options: TOption[];
+    /** The index of the active option. */
+    cursor: number;
+    /** Renders one option, told whether it is the active one. */
+    style: (option: TOption, active: boolean) => string;
+    /** The most options to show, before the terminal's own height is taken into account. */
+    maxItems?: number | undefined;
+    /** Columns taken by something else on the line — a bar, an indent. */
+    columnPadding?: number | undefined;
+    /** Rows taken by something else on the screen — a message, a footer. */
+    rowPadding?: number | undefined;
+}
+/**
+ * The window of options a list should draw, as lines, with `...` where it was cut.
+ *
+ * The order of the four decisions is the behaviour, and every one of them is a graded case:
+ *
+ * 1. **How many options may show at all** — the smaller of `maxItems` and the rows left
+ *    after `rowPadding`, but never fewer than five. "clamps to 5 rows minimum" is that
+ *    floor, and it is why a list in a seven-row terminal still shows something.
+ * 2. **Where the window starts** — it only slides once the cursor comes within three of the
+ *    bottom, and it stops at the end of the list rather than running past it.
+ * 3. **Which ends get an ellipsis** — each `...` costs a line, so it is counted before the
+ *    options are, not after.
+ * 4. **What to give up when the options wrapped** — options are dropped whole, away from the
+ *    cursor first, and an ellipsis appears wherever something was dropped. The three
+ *    "multi-line item clamping" cases are start, middle and end of that.
+ */
+export declare function limitOptions<TOption>({ cursor, options, style, output, maxItems, columnPadding, rowPadding, }: LimitOptionsParams<TOption>): string[];

package/dist/clack.js

@@ -0,0 +1,97 @@
+import { styleText } from 'node:util';
+import { wrap } from 'linegauge/wrap';
+import { processRuntime } from './runtime.js';
+const DEFAULT_COLUMNS = 80;
+const DEFAULT_ROWS = 20;
+const DEFAULT_ROW_PADDING = 4;
+const MINIMUM_VISIBLE = 5;
+const SCROLL_MARGIN = 3;
+const columnsOf = (output) => (typeof output.columns === 'number' ? output.columns : DEFAULT_COLUMNS);
+const rowsOf = (output) => (typeof output.rows === 'number' ? output.rows : DEFAULT_ROWS);
+function shrink({ rendered, lines, from, to, budget, fromEnd = false }) {
+    let lineCount = lines;
+    let removals = 0;
+    const order = fromEnd ? [...Array.from({ length: Math.max(to - from, 0) }, (_unused, n) => to - 1 - n)] : [...Array.from({ length: Math.max(to - from, 0) }, (_unused, n) => from + n)];
+    for (const i of order) {
+        lineCount -= rendered[i]?.length ?? 0;
+        removals++;
+        if (lineCount <= budget)
+            break;
+    }
+    return { lineCount, removals };
+}
+function draw({ options, style, cursor, from, to, columns }) {
+    const rendered = [];
+    for (let i = from; i < to; i++) {
+        const option = options[i];
+        const styled = option === undefined ? '' : style(option, i === cursor);
+        rendered.push(wrap(styled, columns, { hard: true, trim: false }).split('\n'));
+    }
+    return rendered;
+}
+function fitToScreen(fit) {
+    const { rendered, cursorIndex } = fit;
+    let remaining = fit.lineCount;
+    let budget = fit.budget;
+    let ellipsisAbove = fit.ellipsisAbove;
+    let ellipsisBelow = fit.ellipsisBelow;
+    let removedAbove = 0;
+    let removedBelow = 0;
+    const above = () => shrink({ rendered, lines: remaining, from: 0, to: cursorIndex, budget });
+    const below = () => shrink({ rendered, lines: remaining, from: cursorIndex + 1, to: rendered.length, budget, fromEnd: true });
+    const fromAbove = () => {
+        ({ lineCount: remaining, removals: removedAbove } = above());
+        if (remaining <= budget)
+            return;
+        if (!ellipsisBelow)
+            budget -= 1;
+        ({ lineCount: remaining, removals: removedBelow } = below());
+    };
+    const fromBelow = () => {
+        if (!ellipsisBelow)
+            budget -= 1;
+        ({ lineCount: remaining, removals: removedBelow } = below());
+        if (remaining <= budget)
+            return;
+        budget -= 1;
+        ({ lineCount: remaining, removals: removedAbove } = above());
+    };
+    (ellipsisAbove ? fromAbove : fromBelow)();
+    if (removedAbove > 0) {
+        ellipsisAbove = true;
+        rendered.splice(0, removedAbove);
+    }
+    if (removedBelow > 0) {
+        ellipsisBelow = true;
+        rendered.splice(rendered.length - removedBelow, removedBelow);
+    }
+    return { ellipsisAbove, ellipsisBelow };
+}
+export function limitOptions({ cursor, options, style, output = processRuntime().stdout, maxItems = Number.POSITIVE_INFINITY, columnPadding = 0, rowPadding = DEFAULT_ROW_PADDING, }) {
+    const columns = columnsOf(output) - columnPadding;
+    const ellipsis = styleText('dim', '...');
+    const availableRows = Math.max(rowsOf(output) - rowPadding, 0);
+    const visible = Math.max(Math.min(maxItems, availableRows), MINIMUM_VISIBLE);
+    let windowStart = 0;
+    if (cursor >= visible - SCROLL_MARGIN)
+        windowStart = Math.max(Math.min(cursor - visible + SCROLL_MARGIN, options.length - visible), 0);
+    let ellipsisAbove = visible < options.length && windowStart > 0;
+    let ellipsisBelow = visible < options.length && windowStart + visible < options.length;
+    const windowEnd = Math.min(windowStart + visible, options.length);
+    const first = windowStart + (ellipsisAbove ? 1 : 0);
+    const last = windowEnd - (ellipsisBelow ? 1 : 0);
+    const rendered = draw({ options, style, cursor, from: first, to: last, columns });
+    let lineCount = (ellipsisAbove ? 1 : 0) + (ellipsisBelow ? 1 : 0) + rendered.reduce((total, lines) => total + lines.length, 0);
+    if (lineCount > availableRows) {
+        ({ ellipsisAbove, ellipsisBelow } = fitToScreen({ rendered, lineCount, cursorIndex: cursor - first, budget: availableRows, ellipsisAbove, ellipsisBelow }));
+    }
+    const out = [];
+    if (ellipsisAbove)
+        out.push(ellipsis);
+    for (const lines of rendered)
+        for (const line of lines)
+            out.push(line);
+    if (ellipsisBelow)
+        out.push(ellipsis);
+    return out;
+}

package/dist/decide.js

@@ -1,40 +1,10 @@
-/**
- * Whether to prompt at all (R2, R3, R6) — the one decision this package exists to get
- * right, and the only one that has to be correct before a single character is drawn.
- *
- * **An agent asked to type is an agent that hangs.** Every prompt library assumes a person
- * is there; when one is not, the process waits on a stdin that will never produce a line,
- * and the caller sees a timeout with no output and no clue. That is the failure this
- * function refuses to allow: with no terminal, a missing value is an *error naming the
- * flag*, immediately, in words the caller can act on.
- *
- * It is pure — a value, a runtime slice and the flags in, a verdict out — so the whole
- * truth table is a unit test rather than a PTY. `decide.test.ts` walks all of it.
- */
 import { flagOf } from './spec.js';
 const SKIP = { action: 'skip' };
 const PROMPT = { action: 'prompt' };
-/** Present and not empty — the same convention roundel's policy applies to every switch. */
 const set = (value) => value !== undefined && value !== '';
-/** A value from any source at all: a flag, an env var, a config file, a default. */
 function alreadyAnswered(value) {
-    // `false` and `0` and `''` are answers. Only "nothing was supplied" is not.
     return value !== undefined && value !== null;
 }
-/**
- * The rule, in order, and the order is the argument:
- *
- *  1. A value from any source wins. Prompting for something already answered is how a
- *     script that sets an env var still ends up waiting for input.
- *  2. `--json` never prompts. It means "a machine is reading this", and there is no
- *     answer a machine can type.
- *  3. `--yes` answers a `confirm`, and only a `confirm` — it is not a licence to invent
- *     a path or a password.
- *  4. No terminal on stdin, or `CI` set, means nobody is there: refuse, naming the flag.
- *  5. `--interactive` reaches past 4 only when there *is* a terminal; it is an override
- *     for "you would not have asked", never for "there is no one to ask".
- *  6. Otherwise, if it is required or `--interactive` was asked for, prompt.
- */
 export function decide({ value, spec, option, runtime, flags = {}, required = false }) {
     if (alreadyAnswered(value))
         return SKIP;
@@ -52,8 +22,6 @@ export function decide({ value, spec, option, runtime, flags = {}, required = fa
         return { action: 'answer', value: true };
     const nobodyThere = !runtime.isTTY.stdin || set(runtime.env['CI']);
     if (nobodyThere) {
-        // `--interactive` cannot conjure a person. Saying so is the difference between a
-        // useful refusal and a flag that looks like it did nothing.
         const because = interactive ? ' (--interactive needs a terminal on stdin)' : '';
         return {
             action: 'error',
@@ -66,4 +34,3 @@ export function decide({ value, spec, option, runtime, flags = {}, required = fa
         return PROMPT;
     return SKIP;
 }
-//# sourceMappingURL=decide.js.map

package/dist/index.d.ts

@@ -10,3 +10,9 @@ export * from './decide.js';
 export * from './raw.js';
 export * from './spec.js';
 export * from './terminal.js';
+/**
+ * Named, not starred: `runtime.ts` and `decide.ts` both call their slice `Runtime`, and two
+ * star exports of one name is an ambiguity TypeScript resolves by dropping it. The root
+ * keeps `decide`'s — the one a caller of `decide()` constructs — and takes the function.
+ */
+export { processRuntime } from './runtime.js';

package/dist/index.js

@@ -1,13 +1,7 @@
-/**
- * caique — prompts that are flags first. The first working slice is `decide()`: the pure
- * rule that decides whether a person can be asked at all, which is what keeps a CLI built
- * on this from hanging when an agent runs it. Widgets and the two façades follow; see
- * `.sdlc/intents/caique/`.
- */
 export * from './ask.js';
 export * from './binding.js';
 export * from './decide.js';
 export * from './raw.js';
 export * from './spec.js';
 export * from './terminal.js';
-//# sourceMappingURL=index.js.map
+export { processRuntime } from './runtime.js';

package/dist/inquirer-errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `@inquirer/core`'s five error classes, re-stated.
+ *
+ * They are part of the façade's *identity*, not its decoration: `core.test.ts` asserts
+ * `rejects.toThrow(AbortPromptError)` and `rejects.toBeInstanceOf(ValidationError)`, so a
+ * caller that catches by class has to catch ours by the same class. Each carries the name
+ * and the default message the incumbent gives it, because `toThrowErrorMatchingInlineSnapshot`
+ * prints `[HookError: …]` — the class name and the message, together.
+ *
+ * caique's own error envelope (`CliError`, `CANCELLED`, `USAGE`) is unchanged and lives in
+ * `binding.ts`. This file is the incumbent's vocabulary, spoken at the compatibility subpath
+ * and nowhere else.
+ */
+/** Thrown when the `AbortSignal` handed to a prompt aborts. */
+export declare class AbortPromptError extends Error {
+    name: string;
+    message: string;
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when a caller calls `.cancel()` on the returned promise. */
+export declare class CancelPromptError extends Error {
+    name: string;
+    message: string;
+}
+/** Thrown when the process is going away under the prompt — Ctrl-C, or a signalled exit. */
+export declare class ExitPromptError extends Error {
+    name: string;
+}
+/** Thrown when a hook is called outside a prompt render, where there is no store to read. */
+export declare class HookError extends Error {
+    name: string;
+}
+/** Thrown when a hook is called correctly but handed something it cannot use. */
+export declare class ValidationError extends Error {
+    name: string;
+}

package/dist/inquirer-errors.js

@@ -0,0 +1,21 @@
+export class AbortPromptError extends Error {
+    name = 'AbortPromptError';
+    message = 'Prompt was aborted';
+    constructor(options) {
+        super();
+        this.cause = options?.cause;
+    }
+}
+export class CancelPromptError extends Error {
+    name = 'CancelPromptError';
+    message = 'Prompt was canceled';
+}
+export class ExitPromptError extends Error {
+    name = 'ExitPromptError';
+}
+export class HookError extends Error {
+    name = 'HookError';
+}
+export class ValidationError extends Error {
+    name = 'ValidationError';
+}

package/dist/inquirer-hooks.d.ts

@@ -0,0 +1,86 @@
+import { type Interface } from 'node:readline';
+/** The readline interface a prompt renders over. The engine only ever reads `input`. */
+export type PromptReadline = Interface & {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+};
+/** A cleanup returned by an effect, or nothing. */
+type Cleanup = (() => void) | undefined | void;
+/**
+ * Run `cb` with a fresh hook store bound to `rl`.
+ *
+ * `cb` is handed a `cycle` function rather than being called after one: the store's
+ * `handleChange` has to *be* "render again", and only the caller knows how to render.
+ */
+export declare function withHooks<T>(rl: PromptReadline, cb: (cycle: (render: () => void) => void) => T): T;
+/** The readline interface of the prompt currently rendering. Throws outside one. */
+export declare function readline(): PromptReadline;
+/**
+ * Wrap a function so every state change it makes collapses into a single re-render, and so
+ * it stays reachable from whatever async context later calls it.
+ */
+export declare function withUpdates<Args extends unknown[], R>(fn: (...args: Args) => R): (...args: Args) => R;
+/** One hook's slot in the store, addressed by the order the render function called it in. */
+export interface Pointer<T> {
+    get: () => T;
+    set: (value: T) => void;
+    initialized: boolean;
+}
+/** Take the next hook slot, hand it to `cb`, and advance the index. */
+export declare function withPointer<T, R>(cb: (pointer: Pointer<T>) => R): R;
+/** Ask for a re-render. */
+export declare function handleChange(): void;
+/**
+ * The effect queue.
+ *
+ * Effects never run during the render that queued them — "useEffect: is not called
+ * synchronously during render" is a case — so they are collected and flushed by the loop
+ * after `screen.render()`. `clearAll` is what a settling prompt calls, and it runs every
+ * cleanup exactly once.
+ */
+export declare const effectScheduler: {
+    /** Queue `cb` to run after this render, cleaning up whatever the same slot left behind. */
+    queue(cb: (rl: PromptReadline) => Cleanup): void;
+    /** Flush the queue, coalescing every state change the effects make into one re-render. */
+    run(): void;
+    /** Run every cleanup and forget both lists. Idempotent, because settling can race. */
+    clearAll(): void;
+};
+/** A state value that is not itself a function, so the setter can tell a reducer apart. */
+type NotFunction<T> = T extends (...args: never) => unknown ? never : T;
+/** The setter `useState` returns: a new value, or a reducer over the current one. */
+export type SetState<Value> = (newValue: NotFunction<Value> | ((current: Value) => Value)) => void;
+/**
+ * State that survives a re-render, addressed by call order.
+ *
+ * The setter accepts a value or a reducer, and does nothing at all when the next value is
+ * `Object.is`-equal to the current one — which is why `setValue(NaN)` on a `NaN` state does
+ * not re-render, and why a reducer returning its argument is free.
+ */
+export declare function useState<Value>(defaultValue: NotFunction<Value> | (() => Value)): [Value, SetState<Value>];
+/** The no-argument form, for state a later keypress fills. */
+export declare function useState<Value>(defaultValue?: NotFunction<Value> | (() => Value)): [Value | undefined, SetState<Value | undefined>];
+/**
+ * A side effect, queued when its dependency array changes and cleaned up before it re-runs.
+ *
+ * The comparison is `Object.is` per element, like the incumbent's, so a `useRef` handed back
+ * as a dependency is stable and an object literal is not.
+ */
+export declare function useEffect(cb: (rl: PromptReadline) => Cleanup, depArray: readonly unknown[]): void;
+/**
+ * A memoised value.
+ *
+ * Compared with `!==` rather than `Object.is`, and by length first, exactly as upstream
+ * does it — a drop-in that quietly tightened the comparison would recompute where the
+ * incumbent does not, and the graded case counts the calls.
+ */
+export declare function useMemo<Value>(fn: () => Value, dependencies: readonly unknown[]): Value;
+/** A box that survives re-renders. One `useState` slot holding an object that never changes. */
+export declare function useRef<Value>(value: Value): {
+    current: Value;
+};
+/** The no-argument form, for a box a later render fills — `useRef<Timeout | undefined>()`. */
+export declare function useRef<Value>(value?: Value): {
+    current: Value | undefined;
+};
+export {};