@hheei/pi-ask-user 0.0.0-stage → 0.1.1

package/dist/prompt-help.d.ts

@@ -0,0 +1,23 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { KeybindingsManager } from "@earendil-works/pi-tui";
+import type { AskMode } from "./constants";
+import type { AskDisplayMode } from "./schema";
+export declare function formatKeyList(keys: readonly string[]): string;
+export interface HelpHintInput {
+    theme: Theme;
+    mode: AskMode;
+    displayMode: AskDisplayMode;
+    allowMultiple: boolean;
+    hasOptions: boolean;
+    contextCollapsible: boolean;
+    contextToggleKey: string;
+    /** True when the prompt pane clipped, so the scroll keys are worth showing. */
+    promptScrollable: boolean;
+    keybindings: KeybindingsManager;
+}
+/**
+ * One dim hint row: the keys the current mode accepts, in the order they matter.
+ * Every hint that does not apply drops out, so the row never wraps on an 80-column
+ * terminal unless a remapped key makes it long.
+ */
+export declare function buildHelpText(input: HelpHintInput): string;

package/dist/prompt-help.js

@@ -0,0 +1,50 @@
+/** Keys that render as one glyph so the whole hint row still fits a terminal row. */
+const KEY_GLYPH = {
+    up: "↑",
+    down: "↓",
+    enter: "↵",
+    escape: "⎋",
+    space: "␣",
+    tab: "⇥",
+};
+export function formatKeyList(keys) {
+    return keys.map((key) => KEY_GLYPH[key] ?? key).join("/");
+}
+/**
+ * One dim hint row: the keys the current mode accepts, in the order they matter.
+ * Every hint that does not apply drops out, so the row never wraps on an 80-column
+ * terminal unless a remapped key makes it long.
+ */
+export function buildHelpText(input) {
+    const { theme, keybindings } = input;
+    const binding = (id) => formatKeyList(keybindings.getKeys(id));
+    const alternateCancelKeys = keybindings
+        .getKeys("tui.select.cancel")
+        .filter((key) => key !== "escape");
+    const alternateCancel = alternateCancelKeys.length > 0 ? [formatKeyList(alternateCancelKeys), "cancel"] : null;
+    const hints = input.mode === "select"
+        ? [
+            ["↕", "navigate"],
+            input.allowMultiple
+                ? [binding("tui.select.confirm"), "submit"]
+                : [binding("tui.select.confirm"), "select"],
+            input.allowMultiple ? ["␣", "toggle"] : null,
+            input.contextCollapsible ? [input.contextToggleKey, "context"] : null,
+            input.promptScrollable ? ["PgUp/PgDn", "prompt"] : null,
+            [binding("tui.select.cancel"), "cancel"],
+        ]
+        : [
+            [binding("tui.input.submit"), "submit"],
+            [binding("tui.input.newLine"), "newline"],
+            [
+                input.hasOptions ? "⎋" : binding("tui.select.cancel"),
+                input.hasOptions ? "back" : "cancel",
+            ],
+            // esc only steps back to the list, so the cancel key still needs a hint.
+            alternateCancel,
+        ];
+    return theme.fg("dim", hints
+        .filter((hint) => hint !== null)
+        .map(([keys, label]) => `${keys} ${label}`)
+        .join(" · "));
+}

package/dist/prompt-layout.d.ts

@@ -0,0 +1,43 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type AskMode } from "./constants";
+import type { AskDisplayMode } from "./schema";
+/** A surface is bracketed by two `──` rails, the way `pi-ext-ui` groups are. */
+export declare const RAIL_ROWS = 2;
+/** The native separator row: one full-width `─` rule in `borderMuted`. */
+export declare function railRow(theme: Theme, width: number): string;
+/** Rows an overlay may draw for the terminal height: a ratio cap with a usable floor. */
+export declare function getOverlayMaxRenderLinesForRows(rows: number): number;
+export declare function modeMinRows(mode: AskMode): number;
+export declare function modePreferredRows(mode: AskMode): number;
+export declare function overlayHelpBudget(bodyCapacity: number, renderedHelpRows: number): number;
+export interface ContextCollapseInput {
+    displayMode: AskDisplayMode;
+    mode: AskMode;
+    contextCollapsible: boolean;
+    questionRows: number;
+    contextRows: number;
+    bodyCapacity: number;
+    helpRows: number;
+}
+/**
+ * Inline mode always follows the row budget; the overlay keeps context open
+ * when the prompt still fits next to the minimum mode rows.
+ */
+export declare function contextShouldCollapse(input: ContextCollapseInput): boolean;
+export interface BodyPlanInput {
+    maxRenderLines: number;
+    mode: AskMode;
+    contextCollapsible: boolean;
+    promptRows: number;
+    helpRows: number;
+}
+export interface BodyPlan {
+    bodyCapacity: number;
+    helpBudget: number;
+    contentRows: number;
+    promptBudget: number;
+    modeBudget: number;
+    separatorRows: number;
+}
+/** Split the overlay rows between prompt, mode body and help. */
+export declare function planOverlayBody(input: BodyPlanInput): BodyPlan;

package/dist/prompt-layout.js

@@ -0,0 +1,89 @@
+import { ASK_OVERLAY_MAX_HEIGHT_RATIO, ASK_OVERLAY_MIN_RENDER_LINES, } from "./constants";
+/** Rows each mode needs to stay usable, and the size it grows to when there is room. */
+const MODE_ROWS = {
+    select: { min: 3, preferred: 8 },
+    freeform: { min: 5, preferred: 10 },
+};
+/** A surface is bracketed by two `──` rails, the way `pi-ext-ui` groups are. */
+export const RAIL_ROWS = 2;
+/** The native separator row: one full-width `─` rule in `borderMuted`. */
+export function railRow(theme, width) {
+    return theme.fg("borderMuted", "─".repeat(Math.max(0, width)));
+}
+/** Rows an overlay may draw for the terminal height: a ratio cap with a usable floor. */
+export function getOverlayMaxRenderLinesForRows(rows) {
+    const normalizedRows = Number.isFinite(rows) ? Math.max(1, Math.floor(rows)) : 24;
+    const availableRows = Math.max(1, normalizedRows - 2);
+    const ratioRows = Math.max(1, Math.floor(normalizedRows * ASK_OVERLAY_MAX_HEIGHT_RATIO));
+    const minimumRows = Math.min(ASK_OVERLAY_MIN_RENDER_LINES, availableRows);
+    return Math.min(availableRows, Math.max(minimumRows, ratioRows));
+}
+export function modeMinRows(mode) {
+    return MODE_ROWS[mode].min;
+}
+export function modePreferredRows(mode) {
+    return MODE_ROWS[mode].preferred;
+}
+export function overlayHelpBudget(bodyCapacity, renderedHelpRows) {
+    if (renderedHelpRows <= 0 || bodyCapacity <= 0)
+        return 0;
+    if (bodyCapacity >= 12)
+        return Math.min(2, renderedHelpRows);
+    return 1;
+}
+/**
+ * Inline mode always follows the row budget; the overlay keeps context open
+ * when the prompt still fits next to the minimum mode rows.
+ */
+export function contextShouldCollapse(input) {
+    if (input.displayMode === "inline")
+        return input.contextCollapsible;
+    if (input.mode !== "select")
+        return input.contextCollapsible;
+    if (input.contextRows === 0)
+        return false;
+    const helpBudget = overlayHelpBudget(input.bodyCapacity, input.helpRows);
+    const contentRows = Math.max(0, input.bodyCapacity - helpBudget);
+    const separatorRows = contentRows >= 4 ? 1 : 0;
+    const promptCapacity = Math.max(0, contentRows - separatorRows - modeMinRows(input.mode));
+    return input.questionRows + 1 + input.contextRows > promptCapacity;
+}
+/** Split the overlay rows between prompt, mode body and help. */
+export function planOverlayBody(input) {
+    const bodyCapacity = Math.max(0, input.maxRenderLines);
+    const helpBudget = overlayHelpBudget(bodyCapacity, input.helpRows);
+    const contentRows = Math.max(0, bodyCapacity - helpBudget);
+    let promptBudget = 0;
+    let modeBudget = 0;
+    let separatorRows = 0;
+    if (input.mode === "select") {
+        separatorRows = contentRows >= 4 ? 1 : 0;
+        const promptAndModeRows = Math.max(0, contentRows - separatorRows);
+        promptBudget = promptAndModeRows;
+        if (promptAndModeRows > 0) {
+            const promptMinRows = input.promptRows > 0 ? 1 : 0;
+            const maximumModeRows = Math.max(0, promptAndModeRows - promptMinRows);
+            const modeMin = Math.min(modeMinRows(input.mode), maximumModeRows);
+            modeBudget = Math.min(modePreferredRows(input.mode), maximumModeRows);
+            modeBudget = Math.max(modeMin, modeBudget);
+            promptBudget = promptAndModeRows - modeBudget;
+            const usefulPromptTarget = input.contextCollapsible ? 3 : 2;
+            const usefulPromptRows = Math.min(input.promptRows, promptAndModeRows >= modeMin + usefulPromptTarget ? usefulPromptTarget : promptMinRows);
+            if (promptBudget < usefulPromptRows && modeBudget > modeMin) {
+                const shiftedRows = Math.min(usefulPromptRows - promptBudget, modeBudget - modeMin);
+                modeBudget -= shiftedRows;
+                promptBudget += shiftedRows;
+            }
+        }
+    }
+    else {
+        modeBudget = Math.min(modePreferredRows(input.mode), contentRows);
+        modeBudget = Math.max(Math.min(modeMinRows(input.mode), contentRows), modeBudget);
+        promptBudget = Math.max(0, contentRows - modeBudget);
+        if (promptBudget > 0 && modeBudget > 0) {
+            separatorRows = 1;
+            promptBudget = Math.max(0, promptBudget - separatorRows);
+        }
+    }
+    return { bodyCapacity, helpBudget, contentRows, promptBudget, modeBudget, separatorRows };
+}

package/dist/prompt-overflow.d.ts

@@ -0,0 +1,5 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+export declare function applyOverflowMarkers(theme: Theme, lines: string[], width: number, hasHiddenAbove: boolean, hasHiddenBelow: boolean): string[];
+export declare function limitLines(theme: Theme, lines: string[], budget: number, width: number, showOverflowMarker: boolean): string[];
+/** Editor rows keep their top/bottom borders and follow the cursor when clipped. */
+export declare function limitEditorLines(theme: Theme, lines: string[], budget: number, width: number): string[];

package/dist/prompt-overflow.js

@@ -0,0 +1,59 @@
+import { CURSOR_MARKER, truncateToWidth } from "@earendil-works/pi-tui";
+export function applyOverflowMarkers(theme, lines, width, hasHiddenAbove, hasHiddenBelow) {
+    if (lines.length === 0)
+        return lines;
+    const marker = (line, glyph) => truncateToWidth(`${theme.fg("dim", glyph)} ${line}`, width, "", true);
+    const marked = [...lines];
+    if (hasHiddenAbove && hasHiddenBelow && marked.length === 1) {
+        marked[0] = marker(marked[0] ?? "", "↕");
+        return marked;
+    }
+    if (hasHiddenAbove) {
+        marked[0] = marker(marked[0] ?? "", "↑");
+    }
+    if (hasHiddenBelow) {
+        const lastIndex = marked.length - 1;
+        marked[lastIndex] = marker(marked[lastIndex] ?? "", "↓");
+    }
+    return marked;
+}
+const truncateLines = (lines, width) => lines.map((line) => truncateToWidth(line, width, "", true));
+export function limitLines(theme, lines, budget, width, showOverflowMarker) {
+    const safeBudget = Math.max(0, Math.floor(budget));
+    if (safeBudget <= 0)
+        return [];
+    if (lines.length <= safeBudget)
+        return truncateLines(lines, width);
+    if (!showOverflowMarker)
+        return truncateLines(lines.slice(0, safeBudget), width);
+    if (safeBudget === 1)
+        return [theme.fg("dim", "…")];
+    return [...truncateLines(lines.slice(0, safeBudget - 1), width), theme.fg("dim", "…")];
+}
+/** Editor rows keep their top/bottom borders and follow the cursor when clipped. */
+export function limitEditorLines(theme, lines, budget, width) {
+    const safeBudget = Math.max(0, Math.floor(budget));
+    if (safeBudget <= 0)
+        return [];
+    if (lines.length <= safeBudget)
+        return truncateLines(lines, width);
+    if (safeBudget === 1)
+        return [theme.fg("dim", "…")];
+    const topBorder = truncateToWidth(lines[0] ?? "", width, "", true);
+    const bottomBorder = truncateToWidth(lines[lines.length - 1] ?? "", width, "", true);
+    if (safeBudget === 2)
+        return [topBorder, bottomBorder];
+    const contentLines = lines.slice(1, -1);
+    const contentBudget = safeBudget - 2;
+    // Locate the cursor row: prefer the zero-width CURSOR_MARKER the editor
+    // emits while focused (the same mechanism pi-tui core uses for hardware
+    // cursor placement), falling back to the inverse-video fake cursor.
+    const cursorLineIndex = contentLines.findIndex((line) => line.includes(CURSOR_MARKER) || line.includes("\x1b[7m"));
+    const maxStart = Math.max(0, contentLines.length - contentBudget);
+    const start = cursorLineIndex >= 0
+        ? Math.max(0, Math.min(cursorLineIndex - contentBudget + 1, maxStart))
+        : maxStart;
+    const visibleContentLines = contentLines.slice(start, start + contentBudget);
+    const markedContentLines = applyOverflowMarkers(theme, visibleContentLines, width, start > 0, start + contentBudget < contentLines.length);
+    return [topBorder, ...markedContentLines, bottomBorder];
+}

package/dist/response.d.ts

@@ -0,0 +1,46 @@
+import type { QuestionOption } from "./single-select-layout";
+export type AskResponse = {
+    kind: "selection";
+    selections: string[];
+} | {
+    kind: "freeform";
+    text: string;
+};
+export interface AskToolDetails {
+    question: string;
+    context?: string | undefined;
+    options: QuestionOption[];
+    response: AskResponse | null;
+    cancelled: boolean;
+}
+export type BatchAnswer = {
+    status: "answered";
+    response: AskResponse;
+} | {
+    status: "skipped";
+};
+/** Result details of a `questions` batch. Single-question results keep AskToolDetails. */
+export interface AskBatchDetails {
+    kind: "batch";
+    /** The top-level question sent alongside questions, shown as the batch heading. */
+    heading?: string;
+    questions: Array<{
+        question: string;
+        context?: string | undefined;
+        options: QuestionOption[];
+    }>;
+    /** Index-aligned with `questions`; empty when the batch was cancelled. */
+    answers: BatchAnswer[];
+    cancelled: boolean;
+}
+export declare function isBatchDetails<T extends AskToolDetails | AskBatchDetails>(details: T): details is Extract<T, AskBatchDetails>;
+export type AskUIResult = AskResponse;
+export declare function formatOptionsForMessage(options: QuestionOption[]): string;
+export declare function createFreeformResponse(text: string | null | undefined): AskResponse | null;
+export declare function createSelectionResponse(selections: string[]): AskResponse | null;
+export declare function formatResponseSummary(response: AskResponse): string;
+export declare function isSelectionResponse(response: AskResponse): response is Extract<AskResponse, {
+    kind: "selection";
+}>;
+/** An empty dialog answer (dismissed or blank) cancels instead of recording a response. */
+export declare function isCancelledInput(value: string | undefined): boolean;

package/dist/response.js

@@ -0,0 +1,31 @@
+export function isBatchDetails(details) {
+    return details.kind === "batch";
+}
+export function formatOptionsForMessage(options) {
+    return options
+        .map((option, index) => {
+        const desc = option.description ? ` — ${option.description}` : "";
+        return `${index + 1}. ${option.title}${desc}`;
+    })
+        .join("\n");
+}
+export function createFreeformResponse(text) {
+    const trimmed = text?.trim();
+    return trimmed ? { kind: "freeform", text: trimmed } : null;
+}
+export function createSelectionResponse(selections) {
+    const normalizedSelections = selections.map((selection) => selection.trim()).filter(Boolean);
+    return normalizedSelections.length === 0
+        ? null
+        : { kind: "selection", selections: normalizedSelections };
+}
+export function formatResponseSummary(response) {
+    return response.kind === "freeform" ? response.text : response.selections.join(", ");
+}
+export function isSelectionResponse(response) {
+    return response.kind === "selection";
+}
+/** An empty dialog answer (dismissed or blank) cancels instead of recording a response. */
+export function isCancelledInput(value) {
+    return value === undefined || value.trim() === "";
+}

package/dist/schema.d.ts

@@ -0,0 +1,43 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { QuestionOption } from "./single-select-layout";
+export { StringEnum };
+type AskOptionInput = QuestionOption | string;
+export type AskDisplayMode = "overlay" | "inline";
+interface BatchQuestionInput {
+    question: string;
+    context?: string;
+    options?: AskOptionInput[];
+    allowMultiple?: boolean;
+    allowFreeform?: boolean;
+}
+export interface AskParams {
+    question?: string;
+    questions?: BatchQuestionInput[];
+    context?: string;
+    options?: AskOptionInput[];
+    allowMultiple?: boolean;
+    allowFreeform?: boolean;
+    displayMode?: AskDisplayMode;
+    timeout_ms?: number;
+}
+/** One validated entry of a `questions` batch. */
+export interface BatchQuestion {
+    question: string;
+    context?: string | undefined;
+    options: QuestionOption[];
+    allowMultiple: boolean;
+    allowFreeform: boolean;
+}
+export declare function coerceOption(option: unknown): QuestionOption | null;
+/** Options arrive as strings, objects, or numbers when a proxy mangled the schema. */
+export declare function coerceOptions(rawOptions: unknown[]): QuestionOption[];
+/** Nothing usable was left after normalization, so the prompt cannot open. */
+export declare function malformedOptionsError(count: number, label?: string): Error;
+/** A top-level question sent with questions is the batch's heading, not another question (#80). */
+export declare function batchHeading(params: AskParams): string | undefined;
+/**
+ * Validate and normalize a `questions` batch. Every problem throws before any
+ * UI opens or event fires (#67), with a message that tells the model how to
+ * correct the call.
+ */
+export declare function normalizeBatchQuestions(params: AskParams): BatchQuestion[];

package/dist/schema.js

@@ -0,0 +1,87 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { isRecord } from "@hheei/pi-ext-core";
+import { BATCH_MAX_QUESTIONS, BATCH_MIN_QUESTIONS } from "./constants";
+export { StringEnum };
+// Key aliases models fall back to when a schema-mangling proxy (Google
+// function calling, Codex-style backends, cmux) strips the option shape and
+// the model has to guess. See issue #22.
+const OPTION_TITLE_KEYS = ["title", "label", "text", "value", "name", "option"];
+export function coerceOption(option) {
+    if (typeof option === "string" || typeof option === "number" || typeof option === "boolean") {
+        const title = String(option).trim();
+        return title ? { title } : null;
+    }
+    if (isRecord(option)) {
+        for (const key of OPTION_TITLE_KEYS) {
+            const value = option[key];
+            if (typeof value === "string" && value.trim()) {
+                const description = typeof option.description === "string" && option.description.trim()
+                    ? option.description
+                    : undefined;
+                return description ? { title: value.trim(), description } : { title: value.trim() };
+            }
+        }
+    }
+    return null;
+}
+/** Options arrive as strings, objects, or numbers when a proxy mangled the schema. */
+export function coerceOptions(rawOptions) {
+    return rawOptions.map(coerceOption).filter((option) => option !== null);
+}
+/** Nothing usable was left after normalization, so the prompt cannot open. */
+export function malformedOptionsError(count, label) {
+    return new Error(`All ${count} option(s)${label ? ` in ${label}` : ""} were malformed, so nothing could be shown to the user. ` +
+        `Each option must be a plain string or an object like { "title": "Short label", "description": "Optional detail" }. ` +
+        `Call ask_user again with corrected options.`);
+}
+/** A top-level question sent with questions is the batch's heading, not another question (#80). */
+export function batchHeading(params) {
+    return typeof params.question === "string" && params.question.trim()
+        ? params.question.trim()
+        : undefined;
+}
+/**
+ * Validate and normalize a `questions` batch. Every problem throws before any
+ * UI opens or event fires (#67), with a message that tells the model how to
+ * correct the call.
+ */
+export function normalizeBatchQuestions(params) {
+    // Top-level context/options/allowMultiple/allowFreeform are ignored here: entries carry their own,
+    // and models that echo schema defaults would otherwise loop on a validation error (#88).
+    const { questions } = params;
+    if (!Array.isArray(questions)) {
+        throw new Error(`questions must be an array of ${BATCH_MIN_QUESTIONS}-${BATCH_MAX_QUESTIONS} question objects.`);
+    }
+    if (questions.length < BATCH_MIN_QUESTIONS) {
+        throw new Error(`questions needs ${BATCH_MIN_QUESTIONS}-${BATCH_MAX_QUESTIONS} entries but got ${questions.length}. To ask one question, use question instead.`);
+    }
+    if (questions.length > BATCH_MAX_QUESTIONS) {
+        throw new Error(`questions accepts at most ${BATCH_MAX_QUESTIONS} entries but got ${questions.length}. Ask the rest in a later ask_user call.`);
+    }
+    const seen = new Set();
+    return questions.map((entry, index) => {
+        const label = `questions[${index}]`;
+        const question = typeof entry?.question === "string" ? entry.question.trim() : "";
+        if (!question)
+            throw new Error(`${label}.question must be a non-empty string.`);
+        const key = question.toLowerCase();
+        if (seen.has(key)) {
+            throw new Error(`${label} repeats the question "${question}". Each question in a batch must be distinct.`);
+        }
+        seen.add(key);
+        const rawOptions = entry.options ?? [];
+        if (!Array.isArray(rawOptions))
+            throw new Error(`${label}.options must be an array.`);
+        const options = coerceOptions(rawOptions);
+        if (rawOptions.length > 0 && options.length === 0) {
+            throw malformedOptionsError(rawOptions.length, label);
+        }
+        return {
+            question,
+            context: typeof entry.context === "string" ? entry.context.trim() || undefined : undefined,
+            options,
+            allowMultiple: entry.allowMultiple ?? false,
+            allowFreeform: entry.allowFreeform ?? true,
+        };
+    });
+}

package/dist/settings-provider.d.ts

@@ -0,0 +1,15 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type SettingField, type SettingsProvider } from "@hheei/pi-ext-core";
+import type { AskDisplayMode } from "./schema";
+export declare const ASK_USER_SETTINGS_PROVIDER_ID = "pi-ask-user";
+/**
+ * The `askUser` section, defined once: the settings UI renders these fields and the tool
+ * resolves its own defaults from them. Values land in the global layer; a project layer
+ * still wins when the tool resolves preferences.
+ */
+export declare const ASK_USER_FIELDS: {
+    displayMode: SettingField<AskDisplayMode>;
+};
+export declare function createAskUserSettingsProvider(): SettingsProvider;
+/** Registers the provider in the runtime registry; returns the unregister handle. */
+export declare function registerAskUserSettings(pi: ExtensionAPI): () => void;

package/dist/settings-provider.js

@@ -0,0 +1,42 @@
+import { createJsonSettingsStorage, getRuntimeSettingsRegistry, registerSettings, } from "@hheei/pi-ext-core";
+import { SETTINGS_SECTION } from "./constants";
+export const ASK_USER_SETTINGS_PROVIDER_ID = "pi-ask-user";
+function enumField(id, label, description, defaultValue, values) {
+    return {
+        id,
+        label,
+        type: "enum",
+        defaultValue,
+        description,
+        options: values.map((value) => ({ value, label: value })),
+        parse: (draft) => (values.includes(draft) ? draft : defaultValue),
+    };
+}
+/**
+ * The `askUser` section, defined once: the settings UI renders these fields and the tool
+ * resolves its own defaults from them. Values land in the global layer; a project layer
+ * still wins when the tool resolves preferences.
+ */
+export const ASK_USER_FIELDS = {
+    displayMode: enumField("displayMode", "display mode", "Overlay shows a centered modal; inline renders the prompt in place.", "overlay", ["overlay", "inline"]),
+};
+export function createAskUserSettingsProvider() {
+    return {
+        id: ASK_USER_SETTINGS_PROVIDER_ID,
+        title: "ask_user",
+        origin: "@hheei/pi-ask-user",
+        description: "Interactive prompts: where the question is drawn.",
+        groups: [
+            {
+                id: SETTINGS_SECTION,
+                title: "",
+                fields: Object.values(ASK_USER_FIELDS),
+            },
+        ],
+        storage: createJsonSettingsStorage({ group: SETTINGS_SECTION }),
+    };
+}
+/** Registers the provider in the runtime registry; returns the unregister handle. */
+export function registerAskUserSettings(pi) {
+    return registerSettings(createAskUserSettingsProvider(), getRuntimeSettingsRegistry(pi));
+}

package/dist/shortcuts.d.ts

@@ -0,0 +1,7 @@
+import { type KeybindingsManager } from "@earendil-works/pi-tui";
+export declare function matchesSelectUp(data: string, keybindings: KeybindingsManager): boolean;
+export declare function matchesSelectDown(data: string, keybindings: KeybindingsManager): boolean;
+/** PageUp/PageDown move by a viewport. The prompt pane owns these; lists own the arrows. */
+export declare function pageDelta(data: string, pageRows: number): number;
+/** A 1-9 digit key, including the CSI-u form the kitty keyboard protocol sends. */
+export declare function digitKey(data: string): number | null;

package/dist/shortcuts.js

@@ -0,0 +1,21 @@
+import { decodeKittyPrintable, Key, matchesKey, } from "@earendil-works/pi-tui";
+// tab/shift+tab mirror the host's select lists; a batch prompt takes tab for paging first.
+export function matchesSelectUp(data, keybindings) {
+    return keybindings.matches(data, "tui.select.up") || matchesKey(data, Key.shift("tab"));
+}
+export function matchesSelectDown(data, keybindings) {
+    return keybindings.matches(data, "tui.select.down") || matchesKey(data, Key.tab);
+}
+/** PageUp/PageDown move by a viewport. The prompt pane owns these; lists own the arrows. */
+export function pageDelta(data, pageRows) {
+    if (matchesKey(data, Key.pageUp))
+        return -pageRows;
+    if (matchesKey(data, Key.pageDown))
+        return pageRows;
+    return 0;
+}
+/** A 1-9 digit key, including the CSI-u form the kitty keyboard protocol sends. */
+export function digitKey(data) {
+    const key = decodeKittyPrintable(data) ?? data;
+    return key.length === 1 && key >= "1" && key <= "9" ? Number(key) : null;
+}

package/dist/single-select-layout.d.ts

@@ -0,0 +1,19 @@
+export interface QuestionOption {
+    title: string;
+    description?: string;
+}
+/** What a rendered row is, so the list styles it without sniffing its text. */
+export type OptionRowKind = "option" | "description" | "helper" | "indicator";
+export interface AnnotatedRow {
+    line: string;
+    selected: boolean;
+    kind: OptionRowKind;
+}
+export interface RenderSingleSelectRowsParams {
+    options: QuestionOption[];
+    selectedIndex: number;
+    width: number;
+    allowFreeform: boolean;
+    maxRows?: number;
+}
+export declare function renderSingleSelectRows({ options, selectedIndex, width, allowFreeform, maxRows, }: RenderSingleSelectRowsParams): AnnotatedRow[];

package/dist/single-select-layout.js

@@ -0,0 +1,61 @@
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { FREEFORM_HINT, FREEFORM_LABEL } from "./constants";
+import { visibleBlockWindow } from "./option-rows";
+/** Wraps `text` under `prefix`, indenting continuation lines to the same column. */
+function wrappedRow(text, prefix, width, kind) {
+    const indent = " ".repeat(prefix.length);
+    return wrapTextWithAnsi(text, Math.max(8, width - prefix.length)).map((line, index) => ({
+        text: `${index === 0 ? prefix : indent}${line}`.trimEnd(),
+        kind,
+    }));
+}
+function buildItemBlocks(options, width, allowFreeform, selectedIndex) {
+    const normalizedWidth = Math.max(12, width);
+    const allItems = options.map((option, index) => ({
+        type: "option",
+        option,
+        index,
+    }));
+    if (allowFreeform)
+        allItems.push({ type: "freeform" });
+    return allItems.map((item, itemIndex) => {
+        const pointer = itemIndex === selectedIndex ? "→" : " ";
+        const helperPrefix = `${pointer}   `;
+        if (item.type === "freeform") {
+            const label = `${FREEFORM_LABEL} — ${FREEFORM_HINT}`;
+            return { itemIndex, lines: wrappedRow(label, helperPrefix, normalizedWidth, "helper") };
+        }
+        const numberPrefix = `${pointer} ${item.index + 1}. `;
+        const lines = wrappedRow(item.option.title, numberPrefix, normalizedWidth, "option");
+        if (item.option.description) {
+            lines.push(...wrappedRow(item.option.description, "      ", normalizedWidth, "description"));
+        }
+        return { itemIndex, lines };
+    });
+}
+function flatten(blocks, selectedIndex) {
+    return blocks.flatMap((block) => block.lines.map((line) => ({
+        line: line.text,
+        kind: line.kind,
+        selected: block.itemIndex === selectedIndex,
+    })));
+}
+export function renderSingleSelectRows({ options, selectedIndex, width, allowFreeform, maxRows, }) {
+    const itemCount = options.length + (allowFreeform ? 1 : 0);
+    const blocks = buildItemBlocks(options, width, allowFreeform, selectedIndex);
+    const allRows = flatten(blocks, selectedIndex);
+    if (!Number.isFinite(maxRows) || !maxRows || maxRows <= 0 || allRows.length <= maxRows) {
+        return allRows;
+    }
+    const safeMaxRows = Math.max(1, Math.floor(maxRows));
+    const window = visibleBlockWindow(blocks, selectedIndex, safeMaxRows);
+    const visible = flatten(window, selectedIndex);
+    if (window !== blocks && safeMaxRows > 1) {
+        visible.push({
+            line: `  (${selectedIndex + 1}/${itemCount})`,
+            kind: "indicator",
+            selected: false,
+        });
+    }
+    return visible.slice(0, safeMaxRows);
+}