pi-ask-questions 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-10-25
+
+### Changed
+
+- Added explicit `mode: "urgent"` (blocking) and `mode: "background"` (default) choices. `noWait` remains a compatibility alias; an explicit mode takes precedence.
+- Background answers now use steering delivery at the next model/tool boundary instead of waiting in the follow-up queue.
+
+- Tabs preserve unfinished drafts, caret positions, and option cursors when revisiting questions.
+- Multiline extra answers support arrow-key editing between lines; PageUp and PageDown navigate long option lists.
+- Questionnaires show progress, live selection counts, and optional-question hints. The review tab preserves answer summaries while displaying specific validation errors.
+
+### Fixed
+
+- Invalid selections above the maximum are shown as partially answered instead of complete.
+- Validation feedback clears as answers become valid and does not carry over to the next question.
+- Cancellation handles signals aborted before component creation, and disposed components ignore late input.
+- Selecting a single-choice option with Space or a number key now waits for Enter, allowing an extra typed answer alongside the selected option. Confirming preserves the selection even after moving the cursor.
+- Selecting an already selected single-choice option clears it while preserving the typed answer, so presets can be replaced with text alone.
+- Large pasted answers retain their full text instead of returning an editor paste marker, including when submitted through the review tab.
+- Extra typed answers support backslash + Enter for newlines and remain editable after a validation error.
+- Editor undo history is isolated per question so Undo cannot copy an answer from another question.
+- RPC option dialogs support selecting an option and adding text before choosing Done.
+- Selection-limit warnings remain visible when an extra option cannot be selected.
+- Questionnaire rendering recalculates when the terminal width changes.
+
 ## [0.2.1] - 2026-10-15
 
 ### Fixed

package/README.md

@@ -44,23 +44,24 @@ Once installed, run `/ask-demo` to preview the UI, or just let the model call `a
 
 ## Features
 
-- **Tabs** — every question gets a tab, with answered state shown by color (green = answered, accent = partially answered, muted = untouched). Move with `Tab` / `Shift+Tab`.
-- **Single-select** radio options with optional descriptions.
-- **Multi-select** checkboxes (`multiple: true`), including `min` / `max` validation, `A` to select all, and `C` to clear.
-- **Free-form typing** — a question without options is a plain text prompt. Option questions can also hold one typed answer unless `allowOther: false`.
+- **Tabs** — every question gets a tab, with answered state shown by color (green = answered, accent = partially answered, muted = untouched) and a count of questions ready to submit. Move with `Tab` / `Shift+Tab`; each tab remembers your draft, option cursor, and text caret.
+- **Single-select** radio options with optional descriptions. Select an option, add extra text if needed, then confirm with `Enter`.
+- **Multi-select** checkboxes (`multiple: true`), including `min` / `max` validation, a live answer count, `A` to select all, and `C` to clear. Typed answers count toward the selection bounds.
+- **Free-form typing** — a question without options is a plain text prompt. Option questions can also hold one typed answer alongside the selected option(s) unless `allowOther: false`.
 - **Inline editing** — move the cursor onto “Type something…” and type; the editor appears directly under the row with the options still visible. No separate menu, and the answer can be edited again in place.
 - **One typed answer per question** — typed answers are never duplicated; editing replaces the previous text.
 - **Optional questions** (`required: false`) that can be skipped, plus preset answers (`selected: true`) and defaults.
-- **Review tab** — see everything before submitting; jump back to any question to edit it.
+- **Review tab** — see your answers and specific validation errors together before submitting; jump back to any question to edit it.
 - **Validation** — required answers and `min`/`max` selection counts are enforced before submit.
-- **Background mode** — set `noWait: true` and the tool returns immediately while the questionnaire stays open; the answers arrive later as a follow-up message.
+- **Urgent mode** — set `mode: "urgent"` to block further work until the questionnaire is answered or cancelled.
+- **Background mode** — use `mode: "background"` (the default) and the tool returns immediately while the questionnaire stays open; answers steer the active run at the next model/tool boundary.
 - **Safe cancel** — `Esc` arms cancellation, a second `Esc` or `Ctrl+C` cancels immediately.
-- **Scrollable option lists** — long lists show “n more above / below” indicators.
+- **Scrollable option lists** — long lists show “n more above / below” indicators. Use `PageUp` / `PageDown` to move eight rows at a time.
 - **Structured results** — the tool returns text for the model and a machine-readable `structuredContent` payload for codemode scripts.
 
 ## How the model uses it
 
-`ask_user` accepts one or more questions. A single-select question resolves immediately; everything else flows into tabs and a submit step.
+`ask_user` accepts one or more questions. `Space` or `1`–`9` selects an option without submitting, so you can move to “Type something…” and add text. Select an already selected option again to clear it and keep just the typed answer. `Enter` confirms the answer. A questionnaire with one question then resolves; multiple questions flow into tabs and a review step.
 
 ```json
 {
@@ -124,19 +125,31 @@ Notes: (skipped)
 | `questions[].options[].label` | string | Display label. |
 | `questions[].options[].description` | string | Explanation shown below the label. |
 | `questions[].options[].selected` | boolean | Preselect the option. |
-| `questions[].multiple` | boolean | Allow more than one selection. |
+| `questions[].multiple` | boolean | Allow more than one listed option. A typed answer can accompany either mode. |
 | `questions[].allowOther` | boolean | Show the typed-answer entry. Default `true`. |
 | `questions[].required` | boolean | Require an answer before submit. Default `true`. |
 | `questions[].min` / `max` | integer | Selection bounds for multi-select. |
 | `questions[].placeholder` | string | Placeholder for the free-form editor. |
 | `questions[].otherLabel` | string | Custom label for the typed-answer entry. |
-| `noWait` | boolean | Show the questionnaire in the background and return immediately (interactive TUI only). The answers arrive as a follow-up message. Only one background questionnaire can be open at a time. |
+| `mode` | `"urgent"` / `"background"` | `"urgent"` waits for answers. Default `"background"` returns immediately and delivers answers as steering (interactive TUI only; other interactive modes wait). Only one background questionnaire can be open at a time. |
+| `noWait` | boolean | Compatibility alias: `true` means background, `false` means urgent. An explicit `mode` takes precedence. |
+
+Choose `mode: "urgent"` when the model needs input before proceeding anywhere. Choose `mode: "background"` when it can continue independent work:
+
+```json
+{
+  "mode": "background",
+  "questions": [{ "question": "Which deployment environment should I use?" }]
+}
+```
+
+Background answers use Pi's steering queue, so they are considered at the next model/tool boundary instead of waiting for the agent to finish. Steering does not interrupt a response mid-token or abort a running tool. If the agent has already stopped, submitting answers starts a new turn. Cancellation is also reported. In RPC mode, both modes wait for the dialog answers.
 
 ### Structured results
 
 `structuredContent` mirrors the answers for codemode scripts: `cancelled`, an optional `pending`, and `answers[]` with `{ id, question, skipped, answers: [{ value, label, custom }] }`.
 
-While a background questionnaire is open, `pending` is `true` and each `answers[]` entry is a stub with an empty `answers` array. Branch on `pending` before reading them; the real answers arrive as a follow-up message.
+While a background questionnaire is open, `pending` is `true` and each `answers[]` entry is a stub with an empty `answers` array. Branch on `pending` before reading them; the real answers arrive as a steering message.
 
 ### Keyboard reference
 
@@ -144,20 +157,23 @@ While a background questionnaire is open, `pending` is `true` and each `answers[
 | --- | --- |
 | `Tab` / `Shift+Tab` | Switch tabs |
 | `↑` / `↓`, `Home` / `End` | Move the option cursor |
-| `Space` | Toggle a checkbox / select a radio option |
-| `1`–`9` | Jump to an option (toggles it in multi-select) |
+| `PageUp` / `PageDown` | Move a page through the option list |
+| `Space` | Select or clear the highlighted option |
+| `1`–`9` | Select or clear a numbered option, without submitting |
 | `A` / `C` | Select all / clear (multi-select) |
 | `Enter` | Confirm the question, or submit on the review tab |
 | `Esc` | Arm cancel; `Esc` twice cancels |
 | `Ctrl+C` | Cancel immediately |
-| `\` + `Enter` | Newline in a free-form answer |
+| `\` + `Enter` | Newline in a free-form or extra typed answer |
+
+In a multiline extra answer, `↑` / `↓` edits between text lines. Moving up from the first line or down from the last line returns to the option list.
 
 ## Modes
 
 | Mode | Behavior |
 | --- | --- |
-| Interactive TUI | Full tabbed questionnaire. |
-| Interactive TUI + `noWait` | Tool returns immediately; answers are delivered as a follow-up message. |
+| Interactive TUI + `mode: "urgent"` | Full tabbed questionnaire; tool waits for answers before further work. |
+| Interactive TUI + `mode: "background"` (default) | Tool returns immediately; answers steer the active run at the next model/tool boundary. |
 | RPC | Sequential fallback built from the dialog API (`select` / `input`). |
 | Print / JSON | The tool reports that no UI is available and lists the questions so the model can ask them in plain text. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-ask-questions",
-	"version": "0.2.1",
+	"version": "0.4.0",
 	"description": "Interactive questionnaires for Pi: tabs, multi-select, free-form typing, validation, and structured answers.",
 	"keywords": [
 		"pi-package",

package/src/extension.ts

@@ -28,28 +28,30 @@ import { runQuestionnaire, type QuestionnaireContext } from "./ui/ask-questionna
 /** Structured details stored with the tool result for rendering. */
 export interface AskToolDetails {
 	cancelled: boolean;
-	/** True while a noWait questionnaire is still open in the background. */
+	/** True while a background questionnaire is still open. */
 	pending?: boolean;
 	answers: QuestionAnswer[];
 	questions: NormalizedQuestion[];
 }
 
-const TOOL_DESCRIPTION = `Ask the user one or more questions and wait for their answers. Use it when you need a decision, preference, or piece of information that only the user can provide.
+const TOOL_DESCRIPTION = `Ask the user one or more questions, either blocking for answers or continuing in the background. Use it when you need a decision, preference, or piece of information that only the user can provide.
 
 The interactive UI supports:
 - Tabs: every question gets its own tab (Tab / Shift+Tab and arrow keys switch).
 - Single-select and multi-select questions (set multiple: true).
-- Free-form typing: a question with no options is a text prompt. Option questions can also hold one typed answer unless allowOther is false, and the answer is edited inline.
+- Free-form typing: a question with no options is a text prompt. Option questions can also hold one typed answer alongside the selected option(s) unless allowOther is false, and the answer is edited inline.
 - Optional questions (required: false) that can be skipped, preselected options (selected: true), and min/max selection counts.
-- Number keys 1-9 jump to options; A selects all; C clears a multi-select.
-- Set noWait: true to open the questionnaire in the background: the tool returns immediately and the answers arrive later as a follow-up message.
+- Space or number keys 1-9 select or clear options without submitting; Enter confirms. A selects all; C clears a multi-select.
+- Set mode: "urgent" to wait for the user before proceeding with any further work.
+- Use mode: "background" (default) to continue independent work while the questionnaire stays open. Answers are injected as steering at the next model/tool boundary, before further work; they do not wait until the agent finishes. This does not abort an in-flight response or running tool.
+- noWait is a compatibility alias: true means background, false means urgent. An explicit mode takes precedence.
 
 Guidelines:
 - Prefer this tool over asking questions in prose when you actually need the answer to proceed.
 - Group related questions into one call (2-6 questions) instead of asking repeatedly.
 - Provide concrete, labeled options whenever you can; use a free-form question only when the answer space is open.
 - Put recommended options first.
-- Use noWait only when you can keep working without the answer; otherwise omit it so the answers arrive in the same turn.`;
+- Choose urgent when an answer is required before any further work; choose background only when you can continue independent work. In non-TUI interactive modes, background falls back to waiting for answers.`;
 
 const HELP_TEXT = `Interactive UI is not available in this mode. Ask the user the following questions directly in your reply instead:
 {{questions}}`;
@@ -92,8 +94,8 @@ function resultContent(result: AskResult): string {
 
 /** Start the questionnaire and wait for the user. */
 export default function askQuestionsExtension(pi: ExtensionAPI): void {
-	// A noWait questionnaire stays open after its tool call returns. It owns a
-	// session-scoped abort controller and reports its answers with a follow-up
+	// A background questionnaire stays open after its tool call returns. It owns a
+	// session-scoped abort controller and reports its answers with a steering
 	// message instead of a tool result.
 	let backgroundController: AbortController | undefined;
 	let shuttingDown = false;
@@ -116,7 +118,7 @@ export default function askQuestionsExtension(pi: ExtensionAPI): void {
 		promptGuidelines: [
 			"Use ask_user when you need a decision or missing detail from the user; batch related questions into one call instead of asking repeatedly.",
 			"Give ask_user questions labeled options where possible, keep them self-contained, and put recommended options first.",
-			"Set noWait only when you can keep working without the answers, for example to ask while investigating something else.",
+			'Use mode: "urgent" when input is required before proceeding anywhere. Use mode: "background" (default) for independent work; answers steer the active run at the next model/tool boundary.',
 		],
 		parameters: AskUserParamsSchema,
 		outputSchema: AskUserOutputSchema,
@@ -140,7 +142,8 @@ export default function askQuestionsExtension(pi: ExtensionAPI): void {
 
 			const submitLabel = params.submitLabel?.trim() || DEFAULT_SUBMIT_LABEL;
 
-			if (params.noWait === true && ctx.mode === "tui") {
+			const mode = params.mode ?? (params.noWait === false ? "urgent" : "background");
+			if (mode === "background" && ctx.mode === "tui") {
 				if (backgroundController) {
 					return {
 						content: [
@@ -172,7 +175,7 @@ export default function askQuestionsExtension(pi: ExtensionAPI): void {
 								display: true,
 								details: { cancelled: result.cancelled, answers: result.answers, questions },
 							},
-							{ triggerTurn: true, deliverAs: "followUp" },
+							{ triggerTurn: true, deliverAs: "steer" },
 						);
 					})
 					.catch((error: unknown) => {
@@ -199,7 +202,7 @@ export default function askQuestionsExtension(pi: ExtensionAPI): void {
 					content: [
 						{
 							type: "text",
-							text: `Questionnaire shown to the user in the background. Continue with other work; the answers will arrive as a follow-up message.`,
+							text: `Questionnaire shown to the user in the background. Continue with other work; the answers will be injected as steering at the next model/tool boundary. Incorporate them before continuing further work.`,
 						},
 					],
 					details: { cancelled: false, pending: true, answers: [], questions },

package/src/fallback.ts

@@ -33,10 +33,8 @@ export async function runFallbackSurvey(
 		let answered: boolean;
 		if (question.options.length === 0) {
 			answered = await askFreeForm(ui, question, answers, dialogOptions);
-		} else if (question.multiple) {
-			answered = await askMultiple(ui, question, answers, dialogOptions);
 		} else {
-			answered = await askSingle(ui, question, answers, dialogOptions);
+			answered = await askOptions(ui, question, answers, dialogOptions);
 		}
 		if (!answered) {
 			return done(true);
@@ -72,57 +70,7 @@ async function askFreeForm(
 	}
 }
 
-async function askSingle(
-	ui: FallbackUI,
-	question: NormalizedQuestion,
-	answers: Map<string, QuestionAnswer>,
-	options: DialogOptions,
-): Promise<boolean> {
-	const customLabel = `${question.otherLabel} (type an answer)`;
-	const skipLabel = "Skip this question";
-	while (true) {
-		const optionLabels = question.options.map((option, index) => `${index + 1}. ${option.label}`);
-		const choices = [...optionLabels];
-		if (question.allowOther) {
-			choices.push(customLabel);
-		}
-		if (!question.required) {
-			choices.push(skipLabel);
-		}
-		const choice = await ui.select(question.question, choices, options);
-		if (choice === undefined) {
-			return false;
-		}
-		if (choice === skipLabel) {
-			answers.set(question.id, makeAnswer(question, [], true));
-			return true;
-		}
-		if (choice === customLabel) {
-			const typed = await ui.input(question.question, question.placeholder ?? "", options);
-			if (typed === undefined) {
-				return false;
-			}
-			const value = typed.trim();
-			if (value.length === 0) {
-				ui.notify("Type an answer first.", "warning");
-				continue;
-			}
-			answers.set(question.id, makeAnswer(question, [{ value, label: value, custom: true }]));
-			return true;
-		}
-		const index = choices.indexOf(choice);
-		if (index >= 0 && index < question.options.length) {
-			const option = question.options[index]!;
-			answers.set(
-				question.id,
-				makeAnswer(question, [{ value: option.value, label: option.label, custom: false }]),
-			);
-			return true;
-		}
-	}
-}
-
-async function askMultiple(
+async function askOptions(
 	ui: FallbackUI,
 	question: NormalizedQuestion,
 	answers: Map<string, QuestionAnswer>,
@@ -130,7 +78,7 @@ async function askMultiple(
 ): Promise<boolean> {
 	const selected = new Set<number>();
 	question.options.forEach((option, index) => {
-		if (option.selected) {
+		if (option.selected && (question.multiple || selected.size === 0)) {
 			selected.add(index);
 		}
 	});
@@ -140,9 +88,12 @@ async function askMultiple(
 	const skipLabel = "Skip this question";
 
 	while (true) {
-		const optionLabels = question.options.map(
-			(option, index) => `${selected.has(index) ? "[x]" : "[ ]"} ${index + 1}. ${option.label}`,
-		);
+		const optionLabels = question.options.map((option, index) => {
+			const marker = question.multiple
+				? (selected.has(index) ? "[x]" : "[ ]")
+				: (selected.has(index) ? "(•)" : "( )");
+			return `${marker} ${index + 1}. ${option.label}`;
+		});
 		const choices = [...optionLabels, doneLabel];
 		if (question.allowOther) {
 			choices.push(customLabel);
@@ -164,12 +115,9 @@ async function askMultiple(
 				return false;
 			}
 			const value = typed.trim();
-			if (value.length === 0) {
-				ui.notify("Type an answer first.", "warning");
-				continue;
-			}
-			// A question holds at most one typed answer; editing replaces it.
-			custom = { value, label: value, custom: true };
+			// A question holds at most one typed answer; editing replaces it,
+			// and clearing it preserves the listed selection.
+			custom = value ? { value, label: value, custom: true } : undefined;
 			continue;
 		}
 		if (choice === doneLabel) {
@@ -184,12 +132,18 @@ async function askMultiple(
 				ui.notify(error, "warning");
 				continue;
 			}
-			answers.set(question.id, makeAnswer(question, entries));
+			answers.set(question.id, makeAnswer(question, entries, !question.required && entries.length === 0));
 			return true;
 		}
 		const index = choices.indexOf(choice);
 		if (index >= 0 && index < question.options.length) {
-			if (selected.has(index)) {
+			if (!question.multiple) {
+				const wasSelected = selected.has(index);
+				selected.clear();
+				if (!wasSelected) {
+					selected.add(index);
+				}
+			} else if (selected.has(index)) {
 				selected.delete(index);
 			} else {
 				selected.add(index);

package/src/questions.ts

@@ -128,8 +128,12 @@ export function answerError(
 	if (entries.length === 0) {
 		return question.required ? "This question needs an answer." : null;
 	}
-	if (!question.multiple && entries.length > 1) {
-		return "Only one answer is allowed.";
+	const customCount = entries.filter((entry) => entry.custom).length;
+	if (customCount > 1) {
+		return "Only one typed answer is allowed.";
+	}
+	if (!question.multiple && entries.length - customCount > 1) {
+		return "Only one option is allowed.";
 	}
 	if (question.multiple) {
 		const min = question.min ?? (question.required ? 1 : 0);
@@ -167,7 +171,7 @@ export function answerStatus(
 	if (entries.length === 0) {
 		return question.required ? "unanswered" : "skipped";
 	}
-	if (question.multiple && question.min !== undefined && entries.length < question.min) {
+	if (answerError(question, answer)) {
 		return "partial";
 	}
 	return "complete";

package/src/schema.ts

@@ -55,13 +55,13 @@ export const QuestionSchema = Type.Object({
 	),
 	multiple: Type.Optional(
 		Type.Boolean({
-			description: "Allow multiple selections (default: false).",
+			description: "Allow multiple listed options (default: false). One typed answer can accompany either mode.",
 		}),
 	),
 	allowOther: Type.Optional(
 		Type.Boolean({
 			description:
-				'Show a "Type something…" entry so the user can type a custom answer (default: true).',
+				'Show a "Type something…" entry for one typed answer, alone or alongside selected options (default: true).',
 		}),
 	),
 	required: Type.Optional(
@@ -111,10 +111,16 @@ export const AskUserParamsSchema = Type.Object({
 		description:
 			"Questions to ask, in order. Each question gets its own tab; the user can move between tabs freely.",
 	}),
+	mode: Type.Optional(
+		Type.Union([Type.Literal("urgent"), Type.Literal("background")], {
+			description:
+				'"urgent" blocks further work until the questionnaire is answered or cancelled. "background" (default) returns immediately and injects answers as steering at the next model/tool boundary (interactive TUI only; other interactive modes wait). Takes precedence over noWait. Only one background questionnaire can be open at a time.',
+		}),
+	),
 	noWait: Type.Optional(
 		Type.Boolean({
 			description:
-				"Show the questionnaire in the background and return immediately instead of waiting for the user (interactive TUI only). The answers arrive later as a follow-up message. Useful when the answers are not needed right now. Only one background questionnaire can be open at a time.",
+				"Compatibility alias: true selects background mode, false selects urgent mode. Prefer mode; an explicit mode takes precedence.",
 		}),
 	),
 });
@@ -126,7 +132,7 @@ export const AskUserOutputSchema = Type.Object({
 	pending: Type.Optional(
 		Type.Boolean({
 			description:
-				"True when the questionnaire is still open in the background (noWait); answers arrive in a follow-up message.",
+				"True when the questionnaire is still open in background mode; answers arrive as a steering message.",
 		}),
 	),
 	answers: Type.Array(

package/src/ui/ask-questionnaire.ts

@@ -23,8 +23,9 @@
  * Keyboard contract:
  * - Tab / Shift+Tab switch tabs.
  * - ↑/↓ move the cursor; Home/End jump to the first/last row.
- * - Space toggles a multiple-choice option; Enter confirms the question.
- * - 1-9 jumps to an option; on multiple-choice it toggles it.
+ * - PageUp/PageDown move through long option lists.
+ * - Space selects or toggles an option; Enter confirms the question.
+ * - 1-9 jumps to an option and toggles it without confirming the question.
  * - A selects all options, C clears the selection (multiple-choice only).
  * - Moving the cursor onto "Type something…" starts editing immediately;
  *   the inline editor is always there, no separate menu.
@@ -115,11 +116,16 @@ export function createQuestionnaireComponent(
 	let notice: { text: string; kind: NoticeKind } | undefined;
 	let editorText = "";
 	let cachedLines: string[] | undefined;
+	let cachedWidth: number | undefined;
 	let finished = false;
 	let componentFocused = false;
 	let suppressEditorEvents = false;
 
 	const answers = new Map<string, QuestionAnswer>();
+	const editors = new Map<NormalizedQuestion | undefined, Editor>();
+	const cursors = new Map<NormalizedQuestion | undefined, number>();
+	let preparedQuestion: NormalizedQuestion | undefined;
+	let editor: Editor;
 
 	// ── State helpers ────────────────────────────────────────────────────
 
@@ -272,8 +278,25 @@ export function createQuestionnaireComponent(
 	}
 
 	function prepareQuestion(question: NormalizedQuestion | undefined): void {
-		cursor = 0;
-		setEditorForQuestion(question);
+		if (editor) {
+			cursors.set(preparedQuestion, cursor);
+			editor.focused = false;
+		}
+		let nextEditor = editors.get(question);
+		if (!nextEditor) {
+			nextEditor = createEditor();
+			editors.set(question, nextEditor);
+		}
+		editor = nextEditor;
+		preparedQuestion = question;
+		cursor = cursors.get(question) ?? Math.max(0, question?.options.findIndex((option) => option.selected) ?? 0);
+		// Existing editors own the raw draft, caret, and undo history. Loading
+		// the trimmed answer again would discard spaces and reset the caret.
+		if (!cursors.has(question)) {
+			setEditorForQuestion(question);
+		} else {
+			editorText = editor.getText();
+		}
 		syncEditorFocus();
 	}
 
@@ -302,6 +325,7 @@ export function createQuestionnaireComponent(
 
 	function advance(): void {
 		cancelArmed = false;
+		notice = undefined;
 		if (questions.length === 1) {
 			finish(false);
 			return;
@@ -367,13 +391,14 @@ export function createQuestionnaireComponent(
 		}
 		if (row.kind === "skip") {
 			answers.set(question.id, makeAnswer(question, [], true));
+			setText("");
 			advance();
 			return;
 		}
 		if (question.multiple) {
 			if (toggle) {
-				setEntries(question, toggleOption(question, row.option));
 				notice = undefined;
+				setEntries(question, toggleOption(question, row.option));
 				refresh();
 				return;
 			}
@@ -386,7 +411,18 @@ export function createQuestionnaireComponent(
 			advance();
 			return;
 		}
-		setEntries(question, [optionEntry(row.option)]);
+		const entries = getAnswer(question).entries;
+		const custom = entries.filter((entry) => entry.custom);
+		if (toggle && isOptionSelected(question, row.option)) {
+			setEntries(question, custom);
+		} else if (toggle || entries.length === 0) {
+			setEntries(question, [optionEntry(row.option), ...custom]);
+		}
+		if (toggle) {
+			notice = undefined;
+			refresh();
+			return;
+		}
 		advance();
 	}
 
@@ -454,19 +490,17 @@ export function createQuestionnaireComponent(
 	}
 
 	function handleCustomRow(data: string, question: NormalizedQuestion): void {
-		if (matchesKey(data, Key.up)) {
+		// Keep single-line row navigation quick, while allowing multiline
+		// answers to use arrow keys within the editor.
+		if (matchesKey(data, Key.up) && editor.getCursor().line === 0) {
 			moveCursor(-1, question);
 			return;
 		}
-		if (matchesKey(data, Key.down)) {
+		if (matchesKey(data, Key.down) && editor.getCursor().line === editor.getLines().length - 1) {
 			moveCursor(1, question);
 			return;
 		}
-		if (matchesKey(data, Key.enter)) {
-			activateRow(false);
-			return;
-		}
-		// Left/right and everything else edit the inline text.
+		// Let the editor handle submission, paste expansion, and newline shortcuts.
 		editor.handleInput(data);
 		refresh();
 	}
@@ -487,6 +521,13 @@ export function createQuestionnaireComponent(
 			return;
 		}
 		if (rows.length > 0) {
+			if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.pageDown)) {
+				const delta = matchesKey(data, Key.pageUp) ? -MAX_VISIBLE_ROWS : MAX_VISIBLE_ROWS;
+				cursor = Math.max(0, Math.min(rows.length - 1, cursor + delta));
+				syncEditorFocus();
+				refresh();
+				return;
+			}
 			if (matchesKey(data, Key.up)) {
 				moveCursor(-1, question);
 				return;
@@ -539,7 +580,7 @@ export function createQuestionnaireComponent(
 			if (index >= 0) {
 				cursor = index;
 				syncEditorFocus();
-				activateRow(question.multiple);
+				activateRow(true);
 			}
 		}
 	}
@@ -557,6 +598,7 @@ export function createQuestionnaireComponent(
 		if (!escape && cancelArmed) {
 			cancelArmed = false;
 			notice = undefined;
+			refresh();
 		}
 		if (escape) {
 			if (cancelArmed) {
@@ -622,6 +664,8 @@ export function createQuestionnaireComponent(
 			parts.push(theme.fg(ready ? "success" : "dim", submitText));
 		}
 		add(" ", parts.join(" "));
+		const readyCount = questions.filter((question) => !answerError(question, answers.get(question.id))).length;
+		add(" ", theme.fg("dim", `${readyCount} of ${questions.length} questions ready`));
 	}
 
 	function renderRows(add: AddLine, lines: string[], renderWidth: number, question: NormalizedQuestion): void {
@@ -680,10 +724,15 @@ export function createQuestionnaireComponent(
 		if (question.header) {
 			add(" ", theme.fg("muted", question.header));
 		}
+		if (!question.required) {
+			const hint = question.options.length === 0 ? "leave empty to skip" : "choose Skip this question to skip";
+			add(" ", theme.fg("dim", `Optional • ${hint}`));
+		}
 		if (question.multiple) {
-			const min = question.min !== undefined ? `at least ${question.min}` : "one or more";
+			const min = question.min !== undefined ? `at least ${question.min}` : question.required ? "one or more" : "any number";
 			const max = question.max !== undefined ? `, up to ${question.max}` : "";
-			add(" ", theme.fg("dim", `Select ${min}${max} • Space toggles`));
+			const count = getAnswer(question).entries.length;
+			add(" ", theme.fg("dim", `Select ${min}${max} • ${count} ${count === 1 ? "answer" : "answers"} selected • Space toggles`));
 		}
 		add(" ", "");
 		if (question.options.length === 0) {
@@ -702,7 +751,7 @@ export function createQuestionnaireComponent(
 		add(" ", theme.bold(theme.fg("text", "Review your answers")));
 		add(" ", "");
 		const errors = collectAnswerErrors(questions, answers);
-		const invalid = new Set(errors.map((error) => error.id));
+		const invalid = new Map(errors.map((error) => [error.id, error.message]));
 		for (let index = 0; index < questions.length; index += 1) {
 			const question = questions[index]!;
 			const answer = getAnswer(question);
@@ -711,10 +760,8 @@ export function createQuestionnaireComponent(
 			let summary: string;
 			if (answer.skipped) {
 				summary = theme.fg("dim", "(skipped)");
-			} else if (invalid.has(question.id)) {
-				summary = theme.fg("warning", "needs an answer");
 			} else if (answer.entries.length === 0) {
-				summary = theme.fg("dim", "(optional, skipped)");
+				summary = theme.fg(question.required ? "warning" : "dim", question.required ? "(unanswered)" : "(optional, skipped)");
 			} else {
 				summary = answer.entries
 					.map((entry) =>
@@ -723,6 +770,10 @@ export function createQuestionnaireComponent(
 					.join(theme.fg("dim", ", "));
 			}
 			add(marker, `${theme.fg("muted", `${question.label}: `)}${summary}`);
+			const error = invalid.get(question.id);
+			if (error) {
+				add("    ", theme.fg("warning", error));
+			}
 		}
 		add(" ", "");
 		const ready = errors.length === 0;
@@ -737,7 +788,7 @@ export function createQuestionnaireComponent(
 				"  ",
 				theme.fg(
 					"warning",
-					`${count} ${count === 1 ? "question still needs" : "questions still need"} an answer`,
+					`${count} ${count === 1 ? "question needs" : "questions need"} attention`,
 				),
 			);
 		}
@@ -752,19 +803,19 @@ export function createQuestionnaireComponent(
 			return "Tab switch • Esc cancel";
 		}
 		if (question.options.length === 0) {
-			return "Enter submit • \\+Enter newline • Esc cancel";
+			return `Enter ${showTabs ? "confirm" : "submit"} • \\+Enter newline${showTabs ? " • Tab switch" : ""} • Esc cancel`;
 		}
 		if (cursorRow(question)?.kind === "custom") {
-			return "Type your answer • Enter confirm • ↑↓ move • Tab switch • Esc cancel";
+			return "Type your answer • Enter confirm • \\+Enter newline • ↑↓ edit/move • Esc cancel";
 		}
 		if (question.multiple) {
 			return "↑↓ move • Space toggle • A all • C clear • 1-9 jump • Enter confirm • Tab switch";
 		}
-		return "↑↓ move • Space/Enter select • 1-9 jump • Tab switch • Esc cancel";
+		return "↑↓ move • Space select/clear • 1-9 select/clear • Enter confirm • Tab switch • Esc cancel";
 	}
 
 	function render(width: number): string[] {
-		if (cachedLines) {
+		if (cachedLines && cachedWidth === width) {
 			return cachedLines;
 		}
 		const renderWidth = Math.max(1, width);
@@ -806,6 +857,7 @@ export function createQuestionnaireComponent(
 		lines.push(theme.fg("borderAccent", "─".repeat(renderWidth)));
 
 		cachedLines = lines;
+		cachedWidth = width;
 		return lines;
 	}
 
@@ -821,46 +873,58 @@ export function createQuestionnaireComponent(
 			noMatch: (text) => theme.fg("warning", text),
 		},
 	};
-	const editor = new Editor(tui, editorTheme);
-	editor.onChange = (value) => {
-		editorText = value;
-		if (!suppressEditorEvents) {
+	function createEditor(): Editor {
+		const questionEditor = new Editor(tui, editorTheme);
+		questionEditor.onChange = (value) => {
+			editorText = value;
+			if (!suppressEditorEvents) {
+				applyEditorText(questionEditor.getExpandedText());
+				const question = currentQuestion();
+				if (question && !answerError(question, answers.get(question.id))) {
+					notice = undefined;
+				}
+			}
+			cachedLines = undefined;
+		};
+		questionEditor.onSubmit = (value) => {
+			const question = currentQuestion();
+			if (!question) {
+				return;
+			}
+			// Submission clears the editor first. Restore the submitted text so a
+			// validation error leaves the answer available for further editing.
+			setText(value);
 			applyEditorText(value);
-		}
-		cachedLines = undefined;
-	};
-	editor.onSubmit = (value) => {
-		const question = currentQuestion();
-		if (!question) {
-			return;
-		}
-		// submitValue() clears the editor and fires onChange("") before calling
-		// onSubmit, so re-apply the submitted text before validating.
-		applyEditorText(value);
-		const error = answerError(question, answers.get(question.id));
-		if (error) {
-			notice = { text: error, kind: "warning" };
-			refresh();
-			return;
-		}
-		advance();
-	};
+			const error = answerError(question, answers.get(question.id));
+			if (error) {
+				notice = { text: error, kind: "warning" };
+				refresh();
+				return;
+			}
+			advance();
+		};
+		return questionEditor;
+	}
 
 	prepareQuestion(questions[0]);
 
-	const onAbort = (): void => {
-		finished = true;
-		done(buildResult(questions, answers, true));
-	};
+	const onAbort = (): void => finish(true);
 	options.signal?.addEventListener("abort", onAbort, { once: true });
+	if (options.signal?.aborted) {
+		onAbort();
+	}
 
 	return {
 		get focused(): boolean {
 			return componentFocused;
 		},
 		set focused(value: boolean) {
+			if (componentFocused === value) {
+				return;
+			}
 			componentFocused = value;
 			syncEditorFocus();
+			refresh();
 		},
 		render,
 		handleInput,
@@ -868,6 +932,8 @@ export function createQuestionnaireComponent(
 			cachedLines = undefined;
 		},
 		dispose: () => {
+			finished = true;
+			editor.focused = false;
 			options.signal?.removeEventListener("abort", onAbort);
 		},
 	};