pi-ask-user 0.3.0 → 0.4.1

package/README.md

@@ -17,7 +17,7 @@ High-quality video: [ask-user-demo.mp4](./media/ask-user-demo.mp4)
 - Overlay mode — dialog floats over conversation, preserving context
 - Custom TUI rendering for tool calls and results
 - System prompt integration via `promptSnippet` and `promptGuidelines`
-- Optional timeout for auto-dismiss (fallback input mode)
+- Optional timeout for auto-dismiss in both overlay and fallback input modes
 - Structured `details` on all results for session state reconstruction
 - Graceful fallback when interactive UI is unavailable
 - Bundled `ask-user` skill for mandatory decision-gating in high-stakes or ambiguous tasks
@@ -60,7 +60,7 @@ The registered tool name is:
 | `options` | `(string \| {title, description?})[]?` | `[]` | Multiple-choice options |
 | `allowMultiple` | `boolean?` | `false` | Enable multi-select mode |
 | `allowFreeform` | `boolean?` | `true` | Add a "Type something" freeform option |
-| `timeout` | `number?` | — | Auto-dismiss after N ms (applies to fallback input mode) |
+| `timeout` | `number?` | — | Auto-dismiss after N ms and return `null` if the prompt times out |
 
 ## Example usage shape
 
@@ -99,7 +99,7 @@ interface AskToolDetails {
 - Added `promptSnippet` and `promptGuidelines` for better LLM tool selection in the system prompt
 - Added `renderCall` and `renderResult` for custom TUI rendering (compact tool call display, ✓/Cancelled result indicators)
 - Added overlay mode — dialog now floats over the conversation instead of clearing the screen
-- Added `timeout` parameter for auto-dismiss in fallback input mode (when no options are provided)
+- Added `timeout` parameter for auto-dismiss and cancellation support
 - Added structured `details` (`AskToolDetails`) to all result paths for session state reconstruction and branching support
 
 ### 0.2.1

package/index.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
-import { DynamicBorder } from "@mariozechner/pi-coding-agent";
+import { DynamicBorder, getMarkdownTheme, rawKeyHint } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import {
 	Container,
@@ -14,15 +14,16 @@ import {
 	Editor,
 	type EditorTheme,
 	Key,
+	Markdown,
+	type MarkdownTheme,
 	matchesKey,
-	SelectList,
-	type SelectItem,
 	Spacer,
 	Text,
 	type TUI,
 	truncateToWidth,
 	wrapTextWithAnsi,
 } from "@mariozechner/pi-tui";
+import { renderSingleSelectRows } from "./single-select-layout";
 
 interface QuestionOption {
 	title: string;
@@ -72,8 +73,6 @@ function formatOptionsForMessage(options: QuestionOption[]): string {
 		.join("\n");
 }
 
-const FREEFORM_VALUE = "__freeform__";
-
 function createSelectListTheme(theme: Theme) {
 	return {
 		selectedPrefix: (t: string) => theme.fg("accent", t),
@@ -93,6 +92,10 @@ function createEditorTheme(theme: Theme): EditorTheme {
 
 type AskMode = "select" | "freeform";
 
+const ASK_OVERLAY_MAX_HEIGHT_RATIO = 0.85;
+const ASK_OVERLAY_WIDTH = "92%";
+const ASK_OVERLAY_MIN_WIDTH = 40;
+
 class MultiSelectList implements Component {
 	private options: QuestionOption[];
 	private allowFreeform: boolean;
@@ -262,6 +265,135 @@ class MultiSelectList implements Component {
 	}
 }
 
+class WrappedSingleSelectList implements Component {
+	private options: QuestionOption[];
+	private allowFreeform: boolean;
+	private theme: Theme;
+	private selectedIndex = 0;
+	private maxVisibleRows = 12;
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	public onCancel?: () => void;
+	public onSubmit?: (result: string) => void;
+	public onEnterFreeform?: () => void;
+
+	constructor(options: QuestionOption[], allowFreeform: boolean, theme: Theme) {
+		this.options = options;
+		this.allowFreeform = allowFreeform;
+		this.theme = theme;
+	}
+
+	setMaxVisibleRows(rows: number): void {
+		const next = Math.max(1, Math.floor(rows));
+		if (next !== this.maxVisibleRows) {
+			this.maxVisibleRows = next;
+			this.invalidate();
+		}
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+
+	private getItemCount(): number {
+		return this.options.length + (this.allowFreeform ? 1 : 0);
+	}
+
+	private isFreeformRow(index: number): boolean {
+		return this.allowFreeform && index === this.options.length;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.onCancel?.();
+			return;
+		}
+
+		const count = this.getItemCount();
+		if (count === 0) {
+			this.onCancel?.();
+			return;
+		}
+
+		if (matchesKey(data, Key.up) || matchesKey(data, Key.shift("tab"))) {
+			this.selectedIndex = this.selectedIndex === 0 ? count - 1 : this.selectedIndex - 1;
+			this.invalidate();
+			return;
+		}
+
+		if (matchesKey(data, Key.down) || matchesKey(data, Key.tab)) {
+			this.selectedIndex = this.selectedIndex === count - 1 ? 0 : this.selectedIndex + 1;
+			this.invalidate();
+			return;
+		}
+
+		const numMatch = data.match(/^[1-9]$/);
+		if (numMatch) {
+			const idx = Number.parseInt(numMatch[0], 10) - 1;
+			if (idx >= 0 && idx < count) {
+				this.selectedIndex = idx;
+				this.invalidate();
+			}
+			return;
+		}
+
+		if (matchesKey(data, Key.enter)) {
+			if (this.isFreeformRow(this.selectedIndex)) {
+				this.onEnterFreeform?.();
+				return;
+			}
+
+			const result = this.options[this.selectedIndex]?.title;
+			if (result) this.onSubmit?.(result);
+			else this.onCancel?.();
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) {
+			return this.cachedLines;
+		}
+
+		const count = this.getItemCount();
+		if (count === 0) {
+			this.cachedLines = [this.theme.fg("warning", "No options")];
+			this.cachedWidth = width;
+			return this.cachedLines;
+		}
+
+		const lines = renderSingleSelectRows({
+			options: this.options,
+			selectedIndex: this.selectedIndex,
+			width,
+			allowFreeform: this.allowFreeform,
+			maxRows: this.maxVisibleRows,
+		}).map((line) => {
+			const trimmed = line.trim();
+			let styled = line;
+
+			if (trimmed.startsWith("(")) {
+				styled = this.theme.fg("dim", line);
+			} else if (line.startsWith("      ")) {
+				styled = this.theme.fg("muted", line);
+			} else if (line.startsWith("→")) {
+				styled = this.theme.fg("accent", this.theme.bold(line));
+			} else if (trimmed.startsWith("Type something.")) {
+				styled = this.theme.fg("text", line);
+			} else {
+				styled = this.theme.fg("text", line);
+			}
+
+			return truncateToWidth(styled, width, "");
+		});
+
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+}
+
 /**
  * Interactive ask UI. Uses a root Container for layout and swaps the center
  * component between SelectList/MultiSelectList and an Editor (freeform mode).
@@ -281,16 +413,16 @@ class AskComponent extends Container {
 	// Static layout components
 	private titleText: Text;
 	private questionText: Text;
-	private contextText?: Text;
+	private contextComponent?: Component;
 	private modeContainer: Container;
 	private helpText: Text;
 
 	// Mode components
-	private selectList?: SelectList;
+	private singleSelectList?: WrappedSingleSelectList;
 	private multiSelectList?: MultiSelectList;
 	private editor?: Editor;
 
-	// Focus propagation for IME cursor positioning (Editor is Focusable)
+	// Focusable - propagate to Editor for IME cursor positioning
 	private _focused = false;
 	get focused(): boolean {
 		return this._focused;
@@ -298,8 +430,7 @@ class AskComponent extends Container {
 	set focused(value: boolean) {
 		this._focused = value;
 		if (this.editor && this.mode === "freeform") {
-			const anyEditor = this.editor as unknown as { focused?: boolean };
-			anyEditor.focused = value;
+			(this.editor as any).focused = value;
 		}
 	}
 
@@ -337,8 +468,16 @@ class AskComponent extends Container {
 
 		if (this.context) {
 			this.addChild(new Spacer(1));
-			this.contextText = new Text("", 1, 0);
-			this.addChild(this.contextText);
+			let mdTheme: MarkdownTheme | undefined;
+			try {
+				mdTheme = getMarkdownTheme();
+			} catch {}
+			if (mdTheme) {
+				this.contextComponent = new Markdown("", 1, 0, mdTheme);
+			} else {
+				this.contextComponent = new Text("", 1, 0);
+			}
+			this.addChild(this.contextComponent);
 		}
 
 		this.addChild(new Spacer(1));
@@ -364,76 +503,90 @@ class AskComponent extends Container {
 	}
 
 	override render(width: number): string[] {
+		if (this.mode === "select" && !this.allowMultiple) {
+			const overlayMaxHeight = Math.max(12, Math.floor(this.tui.terminal.rows * ASK_OVERLAY_MAX_HEIGHT_RATIO));
+			const staticLines = this.countStaticLines(width);
+			const availableOptionRows = Math.max(4, overlayMaxHeight - staticLines);
+			this.ensureSingleSelectList().setMaxVisibleRows(availableOptionRows);
+		}
+
 		// Defensive: ensure no line exceeds width, otherwise pi-tui will hard-crash.
 		const lines = super.render(width);
 		return lines.map((l) => truncateToWidth(l, width, ""));
 	}
 
+	private countWrappedLines(text: string, width: number): number {
+		return Math.max(1, wrapTextWithAnsi(text, Math.max(10, width - 2)).length);
+	}
+
+	private countStaticLines(width: number): number {
+		const titleLines = 1;
+		const questionLines = this.countWrappedLines(this.question, width);
+		const contextLines = this.context ? 1 + this.countWrappedLines(this.context, width) : 0;
+		const helpLines = 1;
+		const borderLines = 2;
+		const spacerLines = this.context ? 6 : 5;
+		return borderLines + spacerLines + titleLines + questionLines + contextLines + helpLines;
+	}
+
 	private updateStaticText(): void {
 		const theme = this.theme;
 		this.titleText.setText(theme.fg("accent", theme.bold("Question")));
 		this.questionText.setText(theme.fg("text", theme.bold(this.question)));
-		if (this.contextText && this.context) {
-			this.contextText.setText(`${theme.fg("accent", theme.bold("Context:"))}\n${theme.fg("dim", this.context)}`);
+		if (this.contextComponent && this.context) {
+			if (this.contextComponent instanceof Markdown) {
+				(this.contextComponent as Markdown).setText(
+					`**Context:**\n${this.context}`,
+				);
+			} else {
+				(this.contextComponent as Text).setText(
+					`${theme.fg("accent", theme.bold("Context:"))}\n${theme.fg("dim", this.context)}`,
+				);
+			}
 		}
 	}
 
 	private updateHelpText(): void {
 		const theme = this.theme;
 		if (this.mode === "freeform") {
-			this.helpText.setText(
-				theme.fg(
-					"dim",
-					"enter submit • shift+enter newline • (ctrl+enter submit if supported) • esc back • ctrl+c cancel",
-				),
-			);
+			const hints = [
+				rawKeyHint("enter", "submit"),
+				rawKeyHint("shift+enter", "newline"),
+				rawKeyHint("esc", "back"),
+				rawKeyHint("ctrl+c", "cancel"),
+			].join(" • ");
+			this.helpText.setText(theme.fg("dim", hints));
 			return;
 		}
 
 		if (this.allowMultiple) {
-			this.helpText.setText(theme.fg("dim", "↑↓ navigate • space toggle • enter submit • esc cancel"));
+			const hints = [
+				rawKeyHint("↑↓", "navigate"),
+				rawKeyHint("space", "toggle"),
+				rawKeyHint("enter", "submit"),
+				rawKeyHint("esc", "cancel"),
+			].join(" • ");
+			this.helpText.setText(theme.fg("dim", hints));
 		} else {
-			this.helpText.setText(theme.fg("dim", "↑↓ navigate • enter select • esc cancel"));
-		}
-	}
-
-	private buildSingleSelectItems(): SelectItem[] {
-		const items: SelectItem[] = this.options.map((o, idx) => ({
-			value: String(idx),
-			label: o.title,
-			description: o.description,
-		}));
-
-		if (this.allowFreeform) {
-			items.push({
-				value: FREEFORM_VALUE,
-				label: "Type something.",
-				description: "Enter a custom response",
-			});
+			const hints = [
+				rawKeyHint("↑↓", "navigate"),
+				rawKeyHint("enter", "select"),
+				rawKeyHint("esc", "cancel"),
+			].join(" • ");
+			this.helpText.setText(theme.fg("dim", hints));
 		}
-
-		return items;
 	}
 
-	private ensureSingleSelectList(): SelectList {
-		if (this.selectList) return this.selectList;
-
-		const items = this.buildSingleSelectItems();
-		const selectList = new SelectList(items, Math.min(items.length, 10), createSelectListTheme(this.theme));
+	private ensureSingleSelectList(): WrappedSingleSelectList {
+		if (this.singleSelectList) return this.singleSelectList;
 
-		selectList.onSelect = (item) => {
-			if (item.value === FREEFORM_VALUE) {
-				this.showFreeformMode();
-				return;
-			}
-			const idx = Number.parseInt(item.value, 10);
-			const option = this.options[idx];
-			this.onDone(option?.title ?? null);
-		};
-		selectList.onCancel = () => this.onDone(null);
+		const list = new WrappedSingleSelectList(this.options, this.allowFreeform, this.theme);
+		list.onSubmit = (result) => this.onDone(result);
+		list.onCancel = () => this.onDone(null);
+		list.onEnterFreeform = () => this.showFreeformMode();
 
-		this.selectList = selectList;
-		return selectList;
+		this.singleSelectList = list;
+		return list;
 	}
 
 	private ensureMultiSelectList(): MultiSelectList {
@@ -450,11 +603,7 @@ class AskComponent extends Container {
 
 	private ensureEditor(): Editor {
 		if (this.editor) return this.editor;
-		// Note: pi's bundled pi-tui Editor expects (tui, theme, options?)
-		const editor = new Editor(this.tui, createEditorTheme(this.theme));
-		// Default Editor behavior: Enter submits, Shift+Enter inserts newline.
-		// Ctrl+Enter is only distinguishable in terminals with Kitty protocol mappings,
-		// so we support it as an *additional* submit shortcut in our wrapper.
+		const editor = new Editor(createEditorTheme(this.theme));
 		editor.disableSubmit = false;
 		editor.onSubmit = (text: string) => {
 			const trimmed = text.trim();
@@ -484,8 +633,7 @@ class AskComponent extends Container {
 		this.modeContainer.clear();
 
 		const editor = this.ensureEditor();
-		// Ensure focus is propagated immediately when switching modes.
-		(editor as unknown as { focused?: boolean }).focused = this._focused;
+		(editor as any).focused = this._focused;
 
 		this.modeContainer.addChild(new Text(this.theme.fg("accent", this.theme.bold("Custom response")), 1, 0));
 		this.modeContainer.addChild(new Spacer(1));
@@ -496,12 +644,6 @@ class AskComponent extends Container {
 		this.tui.requestRender();
 	}
 
-	private submitFreeform(): void {
-		const editor = this.ensureEditor();
-		const text = editor.getText().trim();
-		this.onDone(text ? text : null);
-	}
-
 	handleInput(data: string): void {
 		if (this.mode === "freeform") {
 			if (matchesKey(data, Key.escape)) {
@@ -514,13 +656,13 @@ class AskComponent extends Container {
 				return;
 			}
 
-			// Submit on Ctrl+Enter (only works if terminal distinguishes it, e.g. Kitty protocol)
 			if (matchesKey(data, Key.ctrl("enter")) || matchesKey(data, "ctrl+enter")) {
-				this.submitFreeform();
+				const editor = this.ensureEditor();
+				const text = editor.getText().trim();
+				this.onDone(text ? text : null);
 				return;
 			}
 
-			// Let Editor handle everything else (Enter submits, Shift+Enter newline)
 			this.ensureEditor().handleInput(data);
 			this.tui.requestRender();
 			return;
@@ -578,11 +720,11 @@ export default function (pi: ExtensionAPI) {
 				Type.Boolean({ description: "Add a freeform text option. Default: true" }),
 			),
 			timeout: Type.Optional(
-				Type.Number({ description: "Auto-dismiss after N milliseconds (applies to fallback input mode when no options are provided)" }),
+				Type.Number({ description: "Auto-dismiss after N milliseconds. Returns null (cancelled) when expired." }),
 			),
 		}),
 
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			if (signal?.aborted) {
 				return {
 					content: [{ type: "text", text: "Cancelled" }],
@@ -629,16 +771,33 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
+				pi.events.emit("ask:answered", { question, context: normalizedContext, answer, wasCustom: true });
 				return {
 					content: [{ type: "text", text: `User answered: ${answer}` }],
 					details: { question, context: normalizedContext, options, answer, cancelled: false, wasCustom: true } as AskToolDetails,
 				};
 			}
 
+			onUpdate?.({
+				content: [{ type: "text", text: "Waiting for user input..." }],
+				details: { question, context: normalizedContext, options, answer: null, cancelled: false },
+			});
+
 			let result: string | null;
 			try {
 				result = await ctx.ui.custom<string | null>(
 					(tui, theme, _kb, done) => {
+						// Wire AbortSignal so agent cancellation auto-dismisses the overlay
+						if (signal) {
+							const onAbort = () => done(null);
+							signal.addEventListener("abort", onAbort, { once: true });
+						}
+
+						// Wire timeout for overlay mode
+						if (timeout && timeout > 0) {
+							setTimeout(() => done(null), timeout);
+						}
+
 						return new AskComponent(
 							question,
 							normalizedContext,
@@ -650,7 +809,16 @@ export default function (pi: ExtensionAPI) {
 							done,
 						);
 					},
-					{ overlay: true },
+					{
+						overlay: true,
+						overlayOptions: {
+							anchor: "center",
+							width: ASK_OVERLAY_WIDTH,
+							minWidth: ASK_OVERLAY_MIN_WIDTH,
+							maxHeight: "85%",
+							margin: 1,
+						},
+					},
 				);
 			} catch (error) {
 				const message =
@@ -663,12 +831,14 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (result === null) {
+				pi.events.emit("ask:cancelled", { question, context: normalizedContext, options });
 				return {
 					content: [{ type: "text", text: "User cancelled the question" }],
 					details: { question, context: normalizedContext, options, answer: null, cancelled: true } as AskToolDetails,
 				};
 			}
 
+			pi.events.emit("ask:answered", { question, context: normalizedContext, answer: result, wasCustom: false });
 			return {
 				content: [{ type: "text", text: `User answered: ${result}` }],
 				details: { question, context: normalizedContext, options, answer: result, cancelled: false } as AskToolDetails,
@@ -692,26 +862,55 @@ export default function (pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, _options, theme) {
+		renderResult(result, options, theme) {
 			const details = result.details as (AskToolDetails & { error?: string }) | undefined;
 
-			// Error state
 			if (details?.error) {
 				return new Text(theme.fg("error", `✗ ${details.error}`), 0, 0);
 			}
 
-			// Cancelled / no details
+			if (options.isPartial) {
+				const waitingText = result.content
+					?.filter((part: { type?: string; text?: string }) => part?.type === "text")
+					.map((part: { text?: string }) => part.text ?? "")
+					.join("\n")
+					.trim() || "Waiting for user input...";
+				return new Text(theme.fg("muted", waitingText), 0, 0);
+			}
+
 			if (!details || details.cancelled) {
 				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
 			}
 
-			// Success
 			const answer = details.answer ?? "";
 			let text = theme.fg("success", "✓ ");
 			if (details.wasCustom) {
 				text += theme.fg("muted", "(wrote) ");
 			}
 			text += theme.fg("accent", answer);
+
+			if (options.expanded) {
+				const selectedTitles = new Set(
+					answer
+						.split(",")
+						.map((value) => value.trim())
+						.filter(Boolean),
+				);
+				text += "\n" + theme.fg("dim", `Q: ${details.question}`);
+				if (details.context) {
+					text += "\n" + theme.fg("dim", details.context);
+				}
+				if (details.options && details.options.length > 0) {
+					text += "\n" + theme.fg("dim", "Options:");
+					for (const opt of details.options) {
+						const desc = opt.description ? ` — ${opt.description}` : "";
+						const isSelected = opt.title === answer || selectedTitles.has(opt.title);
+						const marker = isSelected ? theme.fg("success", "●") : theme.fg("dim", "○");
+						text += `\n  ${marker} ${theme.fg("dim", opt.title)}${theme.fg("dim", desc)}`;
+					}
+				}
+			}
+
 			return new Text(text, 0, 0);
 		},
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-user",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Interactive ask_user tool for pi-coding-agent with multi-select and freeform input UI",
   "type": "module",
   "keywords": [
@@ -35,6 +35,7 @@
   },
   "files": [
     "index.ts",
+    "single-select-layout.ts",
     "skills",
     "README.md",
     "LICENSE"

package/single-select-layout.ts

@@ -0,0 +1,172 @@
+export interface QuestionOption {
+	title: string;
+	description?: string;
+}
+
+export interface RenderSingleSelectRowsParams {
+	options: QuestionOption[];
+	selectedIndex: number;
+	width: number;
+	allowFreeform: boolean;
+	maxRows?: number;
+}
+
+function wrapText(text: string, width: number): string[] {
+	const normalized = text.replace(/\s+/g, " ").trim();
+	if (!normalized) return [""];
+	if (width <= 1) return normalized.split("");
+
+	const words = normalized.split(" ");
+	const lines: string[] = [];
+	let current = "";
+
+	for (const word of words) {
+		if (!current) {
+			if (word.length <= width) {
+				current = word;
+			} else {
+				for (let i = 0; i < word.length; i += width) {
+					lines.push(word.slice(i, i + width));
+				}
+			}
+			continue;
+		}
+
+		const candidate = `${current} ${word}`;
+		if (candidate.length <= width) {
+			current = candidate;
+			continue;
+		}
+
+		lines.push(current);
+		if (word.length <= width) {
+			current = word;
+		} else {
+			for (let i = 0; i < word.length; i += width) {
+				const chunk = word.slice(i, i + width);
+				if (chunk.length === width || i + width < word.length) lines.push(chunk);
+				else current = chunk;
+			}
+			if (!current || current.length === width) current = "";
+		}
+	}
+
+	if (current) lines.push(current);
+	return lines;
+}
+
+function padLine(prefix: string, content: string): string {
+	return `${prefix}${content}`.trimEnd();
+}
+
+interface ItemBlock {
+	itemIndex: number;
+	lines: string[];
+}
+
+function buildItemBlocks(
+	options: QuestionOption[],
+	width: number,
+	allowFreeform: boolean,
+	selectedIndex: number,
+): ItemBlock[] {
+	const normalizedWidth = Math.max(12, width);
+	const freeformLabel = "Type something. — Enter a custom response";
+	const allItems = options.map((option) => ({ type: "option" as const, option }));
+	if (allowFreeform) {
+		allItems.push({ type: "freeform" as const, option: { title: freeformLabel } });
+	}
+
+	return allItems.map((item, itemIndex) => {
+		const pointer = itemIndex === selectedIndex ? "→" : " ";
+		const lines: string[] = [];
+
+		if (item.type === "freeform") {
+			const prefix = `${pointer}   `;
+			const wrapped = wrapText(item.option.title, Math.max(8, normalizedWidth - prefix.length));
+			wrapped.forEach((line, lineIndex) => {
+				lines.push(padLine(lineIndex === 0 ? prefix : " ".repeat(prefix.length), line));
+			});
+			return { itemIndex, lines };
+		}
+
+		const numberPrefix = `${pointer} ${itemIndex + 1}. `;
+		const continuationPrefix = " ".repeat(numberPrefix.length);
+		const titleLines = wrapText(item.option.title, Math.max(8, normalizedWidth - numberPrefix.length));
+		titleLines.forEach((line, lineIndex) => {
+			lines.push(padLine(lineIndex === 0 ? numberPrefix : continuationPrefix, line));
+		});
+
+		if (item.option.description) {
+			const descriptionPrefix = "      ";
+			const descriptionLines = wrapText(
+				item.option.description,
+				Math.max(8, normalizedWidth - descriptionPrefix.length),
+			);
+			descriptionLines.forEach((line) => {
+				lines.push(padLine(descriptionPrefix, line));
+			});
+		}
+
+		return { itemIndex, lines };
+	});
+}
+
+function flatten(blocks: ItemBlock[]): string[] {
+	return blocks.flatMap((block) => block.lines);
+}
+
+export function renderSingleSelectRows({
+	options,
+	selectedIndex,
+	width,
+	allowFreeform,
+	maxRows,
+}: RenderSingleSelectRowsParams): string[] {
+	const itemCount = options.length + (allowFreeform ? 1 : 0);
+	const blocks = buildItemBlocks(options, width, allowFreeform, selectedIndex);
+	const allRows = flatten(blocks);
+
+	if (!Number.isFinite(maxRows) || !maxRows || maxRows <= 0 || allRows.length <= maxRows) {
+		return allRows;
+	}
+
+	const safeMaxRows = Math.max(1, Math.floor(maxRows));
+	const selectedBlock = blocks[selectedIndex] ?? blocks[0];
+	if (!selectedBlock) return [];
+
+	const indicator = `  (${selectedIndex + 1}/${itemCount})`;
+	const availableRows = safeMaxRows > 1 ? safeMaxRows - 1 : 1;
+
+	if (selectedBlock.lines.length >= availableRows) {
+		const visible = selectedBlock.lines.slice(0, availableRows);
+		if (safeMaxRows > 1) visible.push(indicator);
+		return visible.slice(0, safeMaxRows);
+	}
+
+	let start = selectedIndex;
+	let end = selectedIndex + 1;
+	let usedRows = selectedBlock.lines.length;
+
+	while (true) {
+		const nextCanFit = end < blocks.length && usedRows + blocks[end]!.lines.length <= availableRows;
+		if (nextCanFit) {
+			usedRows += blocks[end]!.lines.length;
+			end += 1;
+			continue;
+		}
+
+		const prevCanFit = start > 0 && usedRows + blocks[start - 1]!.lines.length <= availableRows;
+		if (prevCanFit) {
+			start -= 1;
+			usedRows += blocks[start]!.lines.length;
+			continue;
+		}
+
+		break;
+	}
+
+	const visible = flatten(blocks.slice(start, end));
+	visible.push(indicator);
+	return visible.slice(0, safeMaxRows);
+}