@crustjs/prompts 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,966 @@
+/**
+* Result of a fuzzy match against a single candidate.
+*/
+interface FuzzyMatchResult {
+	/** Whether the candidate matches the query */
+	readonly match: boolean;
+	/** Match quality score — higher is better. 0 if no match. */
+	readonly score: number;
+	/** Indices of matched characters in the candidate string */
+	readonly indices: readonly number[];
+}
+/**
+* A fuzzy-filtered item with its match metadata.
+*/
+interface FuzzyFilterResult<T> {
+	/** The original item */
+	readonly item: {
+		readonly label: string;
+		readonly value: T;
+	};
+	/** Match quality score */
+	readonly score: number;
+	/** Indices of matched characters in the label */
+	readonly indices: readonly number[];
+}
+/**
+* Test whether a query fuzzy-matches a candidate string.
+*
+* Each character in `query` must appear in `candidate` in order (but not
+* necessarily contiguously). Matching is case-insensitive.
+*
+* The score rewards:
+* - Consecutive matched characters (contiguity bonus)
+* - Matches at the start of the string
+* - Matches at word boundaries (after space, `-`, `_`, `.`)
+*
+* @param query - The search query
+* @param candidate - The string to match against
+* @returns Match result with boolean, score, and matched character indices
+*
+* @example
+* ```ts
+* fuzzyMatch("abc", "alphabet cookie"); // { match: true, score: ..., indices: [0, 9, 10] }
+* fuzzyMatch("xyz", "hello");           // { match: false, score: 0, indices: [] }
+* fuzzyMatch("", "anything");           // { match: true, score: 0, indices: [] }
+* ```
+*/
+declare function fuzzyMatch(query: string, candidate: string): FuzzyMatchResult;
+/**
+* Filter and sort a list of labeled items by fuzzy-matching against a query.
+*
+* Returns only items that match, sorted by score descending (best matches first).
+* An empty query returns all items (each with score 0 and empty indices).
+*
+* @param query - The search query
+* @param items - Array of items with `label` and `value` properties
+* @returns Matched items sorted by score (highest first)
+*
+* @example
+* ```ts
+* const results = fuzzyFilter("ts", [
+*   { label: "TypeScript", value: "ts" },
+*   { label: "JavaScript", value: "js" },
+*   { label: "Rust", value: "rs" },
+* ]);
+* // Returns TypeScript and Rust (both contain "t" then "s")
+* ```
+*/
+declare function fuzzyFilter<T>(query: string, items: readonly {
+	readonly label: string;
+	readonly value: T;
+}[]): FuzzyFilterResult<T>[];
+import { StyleFn } from "@crustjs/style";
+/**
+* Style slots for all prompt elements.
+*
+* Each slot is a `StyleFn` — a `(text: string) => string` function that
+* applies ANSI styling. The theme controls the visual appearance of every
+* prompt component.
+*
+* @example
+* ```ts
+* const theme: PromptTheme = {
+*   prefix: cyan,
+*   message: bold,
+*   placeholder: dim,
+*   // ...
+* };
+* ```
+*/
+interface PromptTheme {
+	/** Prefix glyph before the prompt message (e.g., "?" or "◆") */
+	readonly prefix: StyleFn;
+	/** The prompt message text */
+	readonly message: StyleFn;
+	/** Placeholder text shown when input is empty */
+	readonly placeholder: StyleFn;
+	/** Cursor indicator in selection lists */
+	readonly cursor: StyleFn;
+	/** Selected / active item styling */
+	readonly selected: StyleFn;
+	/** Unselected / inactive item styling */
+	readonly unselected: StyleFn;
+	/** Validation error messages */
+	readonly error: StyleFn;
+	/** Success / confirmed value styling */
+	readonly success: StyleFn;
+	/** Hint text (e.g., keybinding hints, choice hints) */
+	readonly hint: StyleFn;
+	/** Spinner frame characters */
+	readonly spinner: StyleFn;
+	/** Matched characters in fuzzy filter results */
+	readonly filterMatch: StyleFn;
+}
+/**
+* Partial version of `PromptTheme` for user overrides.
+* Users only need to specify the slots they want to customize.
+*/
+type PartialPromptTheme = Partial<PromptTheme>;
+/**
+* A choice item for select, multiselect, and filter prompts.
+*
+* Accepts either a plain string (where `label === value`) or an object
+* with explicit label, value, and optional hint.
+*
+* @example
+* ```ts
+* // String choices
+* const colors: Choice<string>[] = ["red", "green", "blue"];
+*
+* // Object choices with typed values
+* const ports: Choice<number>[] = [
+*   { label: "HTTP", value: 80 },
+*   { label: "HTTPS", value: 443, hint: "recommended" },
+* ];
+* ```
+*/
+type Choice<T> = string | {
+	readonly label: string;
+	readonly value: T;
+	readonly hint?: string;
+};
+/**
+* Result of a validation function.
+* - `true` means valid
+* - A `string` is the error message to display
+*/
+type ValidateResult = true | string;
+/**
+* Validation function for prompt values.
+* May be synchronous or asynchronous.
+*
+* @example
+* ```ts
+* const validateEmail: ValidateFn<string> = (value) => {
+*   if (!value.includes("@")) return "Must be a valid email address";
+*   return true;
+* };
+* ```
+*/
+type ValidateFn<T> = (value: T) => ValidateResult | Promise<ValidateResult>;
+/**
+* Calculate the scroll offset to keep the cursor within the visible viewport.
+*
+* Used by select, multiselect, and filter prompts to manage scrolling
+* when the number of items exceeds the visible viewport.
+*
+* @param cursor - Current cursor position in the list
+* @param scrollOffset - Current scroll offset
+* @param totalItems - Total number of items in the list
+* @param maxVisible - Maximum number of visible items in the viewport
+* @returns The new scroll offset
+*/
+declare function calculateScrollOffset(cursor: number, scrollOffset: number, totalItems: number, maxVisible: number): number;
+/**
+* A normalized choice item with explicit label, value, and optional hint.
+* This is the internal representation used by select, multiselect, and filter prompts.
+*/
+interface NormalizedChoice<T> {
+	readonly label: string;
+	readonly value: T;
+	readonly hint?: string;
+}
+/**
+* Normalize an array of choices into a consistent `{ label, value, hint? }` format.
+*
+* String choices are converted to `{ label: str, value: str }`.
+* Object choices are passed through as-is.
+*
+* @param choices - Array of string or object choices
+* @returns Array of normalized choice objects
+*
+* @example
+* ```ts
+* // String choices
+* normalizeChoices(["red", "green", "blue"]);
+* // => [{ label: "red", value: "red" }, { label: "green", value: "green" }, ...]
+*
+* // Object choices
+* normalizeChoices([{ label: "HTTP", value: 80 }]);
+* // => [{ label: "HTTP", value: 80 }]
+* ```
+*/
+declare function normalizeChoices<T>(choices: readonly Choice<T>[]): NormalizedChoice<T>[];
+/**
+* Default prompt theme with a polished, gum/clack-inspired aesthetic.
+*
+* Uses `@crustjs/style` color functions for ANSI output that respects
+* terminal capability detection (NO_COLOR, non-TTY graceful degradation).
+*/
+declare const defaultTheme: PromptTheme;
+/**
+* Create a complete theme by merging partial overrides onto the default theme.
+*
+* Use this to build a reusable theme object, then apply it globally
+* with {@link setTheme}.
+*
+* @param overrides - Partial theme slots to override. Only specified slots
+*   are replaced; all others retain their default values.
+* @returns A complete `PromptTheme` with all slots defined.
+*
+* @example
+* ```ts
+* import { createTheme, setTheme } from "@crustjs/prompts";
+* import { magenta, cyan } from "@crustjs/style";
+*
+* const myTheme = createTheme({
+*   prefix: magenta,
+*   success: cyan,
+* });
+*
+* // Apply globally so all prompts use it
+* setTheme(myTheme);
+* ```
+*/
+declare function createTheme(overrides?: PartialPromptTheme): PromptTheme;
+/**
+* Set the global theme applied to all prompts.
+*
+* Accepts either a complete `PromptTheme` (e.g., from {@link createTheme})
+* or a `PartialPromptTheme` with only the slots you want to override.
+* Unspecified slots fall back to {@link defaultTheme}.
+*
+* Call with no arguments or `undefined` to clear the global theme.
+*
+* @param theme - Theme or partial overrides to apply globally.
+*
+* @example
+* ```ts
+* import { setTheme } from "@crustjs/prompts";
+* import { magenta, cyan } from "@crustjs/style";
+*
+* // Set once at app bootstrap
+* setTheme({ prefix: magenta, success: cyan });
+*
+* // Clear the global theme
+* setTheme();
+* ```
+*/
+declare function setTheme(theme?: PartialPromptTheme): void;
+/**
+* Get the current global theme with all slots resolved.
+*
+* Returns {@link defaultTheme} if no global theme has been set.
+*
+* @returns The complete resolved global `PromptTheme`.
+*
+* @example
+* ```ts
+* import { getTheme, setTheme } from "@crustjs/prompts";
+*
+* setTheme({ prefix: magenta });
+* const theme = getTheme();
+* // theme.prefix === magenta
+* // theme.message === bold (default)
+* ```
+*/
+declare function getTheme(): PromptTheme;
+/**
+* Structured keypress event parsed from raw terminal input.
+*/
+interface KeypressEvent {
+	/** The character string for printable keys, or empty string for special keys */
+	readonly char: string;
+	/** Key name (e.g., "return", "backspace", "up", "down", "left", "right", "tab") */
+	readonly name: string;
+	/** Whether Ctrl was held */
+	readonly ctrl: boolean;
+	/** Whether Meta/Alt was held */
+	readonly meta: boolean;
+	/** Whether Shift was held */
+	readonly shift: boolean;
+}
+/**
+* Symbol used internally to discriminate submit results from state updates.
+* Using a symbol prevents collisions with user-defined state types.
+*/
+declare const SUBMIT: unique symbol;
+/**
+* A submit action wrapping the final value.
+*/
+interface SubmitResult<T> {
+	readonly [SUBMIT]: T;
+}
+/**
+* Create a submit result to resolve the prompt with the given value.
+*
+* @param value - The value to resolve the prompt with
+* @returns A submit action object
+*
+* @example
+* ```ts
+* handleKey: (key, state) => {
+*   if (key.name === "return") return submit(state.value);
+*   return { ...state, value: state.value + key.char };
+* }
+* ```
+*/
+declare function submit<T>(value: T): SubmitResult<T>;
+/**
+* Result of a keypress handler.
+* - Return updated state to continue the prompt
+* - Return `submit(value)` to resolve the prompt with a value
+*/
+type HandleKeyResult<
+	S,
+	T
+> = S | SubmitResult<T>;
+/**
+* Configuration for `runPrompt` — each prompt provides these functions
+* to define its behavior.
+*/
+interface PromptConfig<
+	S,
+	T
+> {
+	/** Render the current state to a string (may contain newlines) */
+	readonly render: (state: S, theme: PromptTheme) => string;
+	/** Handle a keypress event — return new state or `submit(value)` to resolve */
+	readonly handleKey: (key: KeypressEvent, state: S) => HandleKeyResult<S, T> | Promise<HandleKeyResult<S, T>>;
+	/** Initial state for the prompt */
+	readonly initialState: S;
+	/** Resolved theme for this prompt */
+	readonly theme: PromptTheme;
+	/**
+	* Optional: render the final submitted state.
+	* Called after submit with the final state and submitted value.
+	* If not provided, the last render output is left on screen.
+	*/
+	readonly renderSubmitted?: (state: S, value: T, theme: PromptTheme) => string;
+}
+/**
+* Error thrown when a prompt requires an interactive TTY but none is available.
+*/
+declare class NonInteractiveError extends Error {
+	constructor(message?: string);
+}
+/**
+* Error thrown when the user cancels a prompt with Ctrl+C.
+*/
+declare class CancelledError extends Error {
+	constructor(message?: string);
+}
+/**
+* Check that stdin is an interactive TTY.
+* @throws {NonInteractiveError} when stdin is not a TTY
+*/
+declare function assertTTY(): void;
+/**
+* Run an interactive prompt with the given configuration.
+*
+* Manages the full terminal lifecycle:
+* 1. Asserts stdin is a TTY
+* 2. Enables raw mode and hides cursor
+* 3. Renders initial state
+* 4. Listens for keypress events, delegating to `handleKey`
+* 5. Re-renders on state changes
+* 6. On submit, renders final state, cleans up, and resolves
+*
+* Output is written to `process.stderr` so prompt UI doesn't pollute
+* piped stdout.
+*
+* @param config - Prompt configuration (render, handleKey, initialState, theme)
+* @returns Promise resolving to the user's submitted value
+* @throws {NonInteractiveError} when stdin is not a TTY
+*
+* @example
+* ```ts
+* const value = await runPrompt({
+*   initialState: { value: "", submitted: false },
+*   theme: resolveTheme(),
+*   render: (state, theme) => `${theme.prefix("?")} Enter value: ${state.value}`,
+*   handleKey: (key, state) => {
+*     if (key.name === "return") return { submit: state.value };
+*     return { ...state, value: state.value + key.char };
+*   },
+* });
+* ```
+*/
+declare function runPrompt<
+	S,
+	T
+>(config: PromptConfig<S, T>): Promise<T>;
+/**
+* Options for the {@link confirm} prompt.
+*
+* @example
+* ```ts
+* const shouldContinue = await confirm({
+*   message: "Do you want to continue?",
+* });
+* ```
+*
+* @example
+* ```ts
+* const agreed = await confirm({
+*   message: "Accept terms?",
+*   active: "Agree",
+*   inactive: "Decline",
+*   default: false,
+* });
+* ```
+*/
+interface ConfirmOptions {
+	/** The prompt message displayed to the user */
+	readonly message: string;
+	/** Default value when the user presses Enter without toggling (defaults to `true`) */
+	readonly default?: boolean;
+	/** Initial value — if provided, the prompt is skipped and this value is returned immediately */
+	readonly initial?: boolean;
+	/** Label for the affirmative option (defaults to `"Yes"`) */
+	readonly active?: string;
+	/** Label for the negative option (defaults to `"No"`) */
+	readonly inactive?: string;
+	/** Per-prompt theme overrides */
+	readonly theme?: PartialPromptTheme;
+}
+/**
+* Display an interactive yes/no confirmation prompt.
+*
+* Shows two side-by-side options (default: "Yes" / "No") that the user
+* toggles with arrow keys, h/l, y/n, or Tab, then confirms with Enter.
+*
+* If `initial` is provided, the prompt is skipped and the value is returned
+* immediately — useful for prefilling from CLI flags.
+*
+* @param options - Confirm prompt configuration
+* @returns The user's boolean selection
+* @throws {NonInteractiveError} when stdin is not a TTY and no `initial` is provided
+*
+* @example
+* ```ts
+* const proceed = await confirm({
+*   message: "Do you want to continue?",
+* });
+* ```
+*
+* @example
+* ```ts
+* // Custom labels with default value
+* const accepted = await confirm({
+*   message: "Accept the license?",
+*   active: "Accept",
+*   inactive: "Decline",
+*   default: false,
+* });
+* ```
+*
+* @example
+* ```ts
+* // Skip prompt when flag is provided
+* const yes = await confirm({
+*   message: "Continue?",
+*   initial: flags.yes,
+* });
+* ```
+*/
+declare function confirm(options: ConfirmOptions): Promise<boolean>;
+/**
+* Options for the {@link filter} prompt.
+*
+* @example
+* ```ts
+* const lang = await filter({
+*   message: "Search for a language",
+*   choices: ["TypeScript", "JavaScript", "Rust", "Python", "Go"],
+* });
+* ```
+*
+* @example
+* ```ts
+* const pkg = await filter<{ name: string; version: string }>({
+*   message: "Find a package",
+*   choices: [
+*     { label: "react", value: { name: "react", version: "18.2" } },
+*     { label: "vue", value: { name: "vue", version: "3.3" } },
+*   ],
+*   placeholder: "Type to filter...",
+* });
+* ```
+*/
+interface FilterOptions<T> {
+	/** The prompt message displayed to the user */
+	readonly message: string;
+	/** List of choices — strings or `{ label, value, hint? }` objects */
+	readonly choices: readonly Choice<T>[];
+	/** Initial value — if provided, the prompt is skipped and this value is returned immediately */
+	readonly initial?: T;
+	/** Placeholder text shown when the query input is empty */
+	readonly placeholder?: string;
+	/** Maximum number of visible filtered results before scrolling (defaults to 10) */
+	readonly maxVisible?: number;
+	/** Per-prompt theme overrides */
+	readonly theme?: PartialPromptTheme;
+}
+/**
+* Display an interactive fuzzy-filter prompt over a list of choices.
+*
+* Type to filter the list using fuzzy matching. Navigate filtered results
+* with Up/Down arrows, confirm with Enter. Matched characters are
+* highlighted in the results.
+*
+* If `initial` is provided, the prompt is skipped and the value is returned
+* immediately — useful for prefilling from CLI flags.
+*
+* @param options - Filter prompt configuration
+* @returns The value of the selected choice
+* @throws {NonInteractiveError} when stdin is not a TTY and no `initial` is provided
+*
+* @example
+* ```ts
+* const lang = await filter({
+*   message: "Search for a language",
+*   choices: ["TypeScript", "JavaScript", "Rust", "Python", "Go"],
+* });
+* ```
+*
+* @example
+* ```ts
+* const pkg = await filter<{ name: string; version: string }>({
+*   message: "Find a package",
+*   choices: [
+*     { label: "react", value: { name: "react", version: "18.2" } },
+*     { label: "vue", value: { name: "vue", version: "3.3" } },
+*   ],
+*   placeholder: "Type to filter...",
+* });
+* ```
+*
+* @example
+* ```ts
+* // Skip prompt when flag is provided
+* const tool = await filter({
+*   message: "Pick a tool",
+*   choices: ["prettier", "eslint", "biome"],
+*   initial: flags.tool,
+* });
+* ```
+*/
+declare function filter<T>(options: FilterOptions<T>): Promise<T>;
+/**
+* Options for the {@link input} prompt.
+*
+* @example
+* ```ts
+* const name = await input({
+*   message: "What is your name?",
+*   placeholder: "Enter your name",
+*   validate: (v) => v.length > 0 || "Name is required",
+* });
+* ```
+*/
+interface InputOptions {
+	/** The prompt message displayed to the user */
+	readonly message: string;
+	/** Placeholder text shown when the input is empty */
+	readonly placeholder?: string;
+	/** Default value used when the user submits an empty input */
+	readonly default?: string;
+	/** Initial value — if provided, the prompt is skipped and this value is returned immediately */
+	readonly initial?: string;
+	/** Validation function — return `true` for valid, or a string error message */
+	readonly validate?: ValidateFn<string>;
+	/** Per-prompt theme overrides */
+	readonly theme?: PartialPromptTheme;
+}
+/**
+* Display an interactive single-line text input prompt.
+*
+* Supports placeholder text, default values, validation with inline error
+* display, and full cursor editing (insert, delete, arrow keys, home/end).
+*
+* If `initial` is provided, the prompt is skipped and the value is returned
+* immediately — useful for prefilling from CLI flags.
+*
+* @param options - Input prompt configuration
+* @returns The user's entered text
+* @throws {NonInteractiveError} when stdin is not a TTY and no `initial` is provided
+*
+* @example
+* ```ts
+* const name = await input({
+*   message: "What is your name?",
+*   placeholder: "John Doe",
+*   validate: (v) => v.length > 0 || "Name cannot be empty",
+* });
+* ```
+*
+* @example
+* ```ts
+* // Skip prompt when flag is provided
+* const name = await input({
+*   message: "Name?",
+*   initial: flags.name,
+* });
+* ```
+*/
+declare function input(options: InputOptions): Promise<string>;
+/**
+* Options for the {@link multiselect} prompt.
+*
+* @example
+* ```ts
+* const toppings = await multiselect({
+*   message: "Select toppings",
+*   choices: ["cheese", "pepperoni", "mushrooms", "olives"],
+* });
+* ```
+*
+* @example
+* ```ts
+* const features = await multiselect<string>({
+*   message: "Enable features",
+*   choices: [
+*     { label: "TypeScript", value: "ts", hint: "recommended" },
+*     { label: "ESLint", value: "eslint" },
+*     { label: "Prettier", value: "prettier" },
+*   ],
+*   default: ["ts"],
+*   required: true,
+* });
+* ```
+*/
+interface MultiselectOptions<T> {
+	/** The prompt message displayed to the user */
+	readonly message: string;
+	/** List of choices — strings or `{ label, value, hint? }` objects */
+	readonly choices: readonly Choice<T>[];
+	/** Default selected values — pre-selects matching choices */
+	readonly default?: readonly T[];
+	/** Initial value — if provided, the prompt is skipped and this value is returned immediately */
+	readonly initial?: readonly T[];
+	/** Whether at least one item must be selected (defaults to false) */
+	readonly required?: boolean;
+	/** Minimum number of selections required */
+	readonly min?: number;
+	/** Maximum number of selections allowed */
+	readonly max?: number;
+	/** Maximum number of visible choices before scrolling (defaults to 10) */
+	readonly maxVisible?: number;
+	/** Per-prompt theme overrides */
+	readonly theme?: PartialPromptTheme;
+}
+/**
+* Display an interactive checkbox-style multi-selection prompt.
+*
+* Navigate with Up/Down arrows (or k/j vim keys), toggle selection with Space,
+* toggle all with 'a', invert selection with 'i', and confirm with Enter.
+* When the list exceeds `maxVisible` items, the viewport scrolls with
+* indicators showing more items above or below.
+*
+* If `initial` is provided, the prompt is skipped and the value is returned
+* immediately -- useful for prefilling from CLI flags.
+*
+* @param options - Multiselect prompt configuration
+* @returns Array of selected values
+* @throws {NonInteractiveError} when stdin is not a TTY and no `initial` is provided
+*
+* @example
+* ```ts
+* const toppings = await multiselect({
+*   message: "Select toppings",
+*   choices: ["cheese", "pepperoni", "mushrooms", "olives"],
+* });
+* ```
+*
+* @example
+* ```ts
+* const features = await multiselect<string>({
+*   message: "Enable features",
+*   choices: [
+*     { label: "TypeScript", value: "ts", hint: "recommended" },
+*     { label: "ESLint", value: "eslint" },
+*     { label: "Prettier", value: "prettier" },
+*   ],
+*   default: ["ts"],
+*   required: true,
+* });
+* ```
+*
+* @example
+* ```ts
+* // Skip prompt when flags are provided
+* const features = await multiselect({
+*   message: "Features?",
+*   choices: ["auth", "logging", "metrics"],
+*   initial: flags.features,
+* });
+* ```
+*/
+declare function multiselect<T>(options: MultiselectOptions<T>): Promise<T[]>;
+/**
+* Options for the {@link password} prompt.
+*
+* @example
+* ```ts
+* const secret = await password({
+*   message: "Enter your password:",
+*   validate: (v) => v.length >= 8 || "Password must be at least 8 characters",
+* });
+* ```
+*/
+interface PasswordOptions {
+	/** The prompt message displayed to the user */
+	readonly message: string;
+	/** Character used to mask the input (default: `"*"`) */
+	readonly mask?: string;
+	/** Validation function — return `true` for valid, or a string error message */
+	readonly validate?: ValidateFn<string>;
+	/** Initial value — if provided, the prompt is skipped and this value is returned immediately */
+	readonly initial?: string;
+	/** Per-prompt theme overrides */
+	readonly theme?: PartialPromptTheme;
+}
+/**
+* Display an interactive masked password input prompt.
+*
+* Characters are shown as the mask character (default `"*"`) as the user
+* types. After submission, a fixed-length mask is displayed to prevent
+* revealing the password length.
+*
+* Supports validation with inline error display and full cursor editing
+* (insert, delete, arrow keys, home/end).
+*
+* If `initial` is provided, the prompt is skipped and the value is returned
+* immediately — useful for prefilling from CLI flags.
+*
+* @param options - Password prompt configuration
+* @returns The user's entered password
+* @throws {NonInteractiveError} when stdin is not a TTY and no `initial` is provided
+*
+* @example
+* ```ts
+* const secret = await password({
+*   message: "Enter your password:",
+*   validate: (v) => v.length >= 8 || "Password must be at least 8 characters",
+* });
+* ```
+*
+* @example
+* ```ts
+* // Custom mask character
+* const pin = await password({
+*   message: "Enter PIN:",
+*   mask: "●",
+* });
+* ```
+*/
+declare function password(options: PasswordOptions): Promise<string>;
+/**
+* Options for the {@link select} prompt.
+*
+* @example
+* ```ts
+* const color = await select({
+*   message: "Pick a color",
+*   choices: ["red", "green", "blue"],
+* });
+* ```
+*
+* @example
+* ```ts
+* const port = await select<number>({
+*   message: "Choose a port",
+*   choices: [
+*     { label: "HTTP", value: 80 },
+*     { label: "HTTPS", value: 443, hint: "recommended" },
+*   ],
+*   default: 443,
+* });
+* ```
+*/
+interface SelectOptions<T> {
+	/** The prompt message displayed to the user */
+	readonly message: string;
+	/** List of choices — strings or `{ label, value, hint? }` objects */
+	readonly choices: readonly Choice<T>[];
+	/** Default value — sets the initial cursor position to the matching choice */
+	readonly default?: T;
+	/** Initial value — if provided, the prompt is skipped and this value is returned immediately */
+	readonly initial?: T;
+	/** Maximum number of visible choices before scrolling (defaults to 10) */
+	readonly maxVisible?: number;
+	/** Per-prompt theme overrides */
+	readonly theme?: PartialPromptTheme;
+}
+/**
+* Display an interactive single-selection prompt from a list of choices.
+*
+* Navigate with Up/Down arrows (or k/j vim keys), confirm with Enter.
+* When the list exceeds `maxVisible` items, the viewport scrolls with
+* indicators showing more items above or below.
+*
+* If `initial` is provided, the prompt is skipped and the value is returned
+* immediately -- useful for prefilling from CLI flags.
+*
+* @param options - Select prompt configuration
+* @returns The value of the selected choice
+* @throws {NonInteractiveError} when stdin is not a TTY and no `initial` is provided
+*
+* @example
+* ```ts
+* const color = await select({
+*   message: "Pick a color",
+*   choices: ["red", "green", "blue"],
+* });
+* ```
+*
+* @example
+* ```ts
+* const port = await select<number>({
+*   message: "Choose a port",
+*   choices: [
+*     { label: "HTTP", value: 80 },
+*     { label: "HTTPS", value: 443, hint: "recommended" },
+*   ],
+*   default: 443,
+* });
+* ```
+*
+* @example
+* ```ts
+* // Skip prompt when flag is provided
+* const env = await select({
+*   message: "Environment?",
+*   choices: ["dev", "staging", "prod"],
+*   initial: flags.env,
+* });
+* ```
+*/
+declare function select<T>(options: SelectOptions<T>): Promise<T>;
+/**
+* Built-in spinner animation names or a custom frame configuration.
+*
+* Built-in spinners:
+* - `"dots"` — Braille dot pattern (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏)
+* - `"line"` — Line rotation (-\\|/)
+* - `"arc"` — Quarter circle rotation (◐◓◑◒)
+* - `"bounce"` — Bouncing braille dot (⠁⠂⠄⡀⢀⠠⠐⠈)
+*
+* Or provide a custom `{ frames: string[]; interval: number }` object.
+*/
+type SpinnerType = "dots" | "line" | "arc" | "bounce" | {
+	readonly frames: readonly string[];
+	readonly interval: number;
+};
+/**
+* Options for the {@link spinner} prompt.
+*
+* @example
+* ```ts
+* const data = await spinner({
+*   message: "Fetching data...",
+*   task: async () => {
+*     const res = await fetch("https://api.example.com/data");
+*     return res.json();
+*   },
+* });
+* ```
+*/
+interface SpinnerOptions<T> {
+	/** The message displayed alongside the spinner */
+	readonly message: string;
+	/** The async task to run while the spinner is displayed */
+	readonly task: () => Promise<T>;
+	/** Spinner animation style (defaults to `"dots"`) */
+	readonly spinner?: SpinnerType;
+	/** Per-prompt theme overrides */
+	readonly theme?: PartialPromptTheme;
+}
+/**
+* Display a spinner animation while running an async task.
+*
+* The spinner renders to stderr so it doesn't interfere with piped stdout.
+* On task completion, the spinner is replaced with a success (✔) or error (✖)
+* indicator. If the task throws, the error is re-thrown after cleanup.
+*
+* Unlike other prompts, the spinner does **not** use raw mode or keypress
+* handling — it is output-only and non-interactive.
+*
+* @param options - Spinner prompt configuration
+* @returns The result of the async task
+*
+* @example
+* ```ts
+* const data = await spinner({
+*   message: "Loading data...",
+*   task: async () => {
+*     const res = await fetch("https://api.example.com/data");
+*     return res.json();
+*   },
+* });
+* ```
+*
+* @example
+* ```ts
+* // Custom spinner animation
+* await spinner({
+*   message: "Building project...",
+*   task: async () => { await buildProject(); },
+*   spinner: "arc",
+* });
+* ```
+*
+* @example
+* ```ts
+* // Custom frames and interval
+* await spinner({
+*   message: "Processing...",
+*   task: async () => { await processData(); },
+*   spinner: { frames: ["⊶", "⊷"], interval: 150 },
+* });
+* ```
+*/
+declare function spinner<T>(options: SpinnerOptions<T>): Promise<T>;
+/** Thin vertical bar used as cursor indicator in text inputs */
+declare const CURSOR_CHAR = "│";
+/**
+* The text + cursor fields that `handleTextEdit` reads and updates.
+* Prompts embed these fields in their own state type.
+*/
+interface TextEditState {
+	readonly text: string;
+	readonly cursorPos: number;
+}
+/**
+* Result of a text-edit operation.
+* `null` means the key was not a text-editing key and the caller should
+* handle it (e.g., Enter for submit, arrow-up/down for list navigation).
+*/
+type TextEditResult = TextEditState | null;
+/**
+* Handle common text-editing keypresses: backspace, delete, left, right,
+* home, end, and printable character insertion.
+*
+* Returns the updated `{ text, cursorPos }` if the key was handled,
+* or `null` if the key is not a text-editing key (so the caller can
+* handle it for prompt-specific logic like submit or list navigation).
+*
+* @param key - The keypress event
+* @param text - Current text content
+* @param cursorPos - Current cursor position within the text
+* @returns Updated text/cursor, or `null` if not a text-edit key
+*/
+declare function handleTextEdit(key: KeypressEvent, text: string, cursorPos: number): TextEditResult;
+export { submit, spinner, setTheme, select, runPrompt, password, normalizeChoices, multiselect, input, handleTextEdit, getTheme, fuzzyMatch, fuzzyFilter, filter, defaultTheme, createTheme, confirm, calculateScrollOffset, assertTTY, ValidateResult, ValidateFn, TextEditState, TextEditResult, SubmitResult, SpinnerType, SpinnerOptions, SelectOptions, PromptTheme, PromptConfig, PasswordOptions, PartialPromptTheme, NormalizedChoice, NonInteractiveError, MultiselectOptions, KeypressEvent, InputOptions, HandleKeyResult, FuzzyMatchResult, FuzzyFilterResult, FilterOptions, ConfirmOptions, Choice, CancelledError, CURSOR_CHAR };