@zhushanwen/pi-ask-user 0.0.1

package/src/index.ts

@@ -0,0 +1,229 @@
+// src/index.ts
+import type { AgentToolResult, ExtensionAPI, ExtensionContext, ToolRenderResultOptions } from "@mariozechner/pi-coding-agent";
+import { Box, Text, TruncatedText, truncateToWidth } from "@mariozechner/pi-tui";
+import { type Static } from "@sinclair/typebox";
+
+import { AskUserComponent } from "./component";
+import {
+	type AskUserDetails,
+	type ErrorDetails,
+	HEADER_MAX_CHARS,
+	InputSchema,
+	type Option,
+	type Question,
+	type Result,
+	type ThemeLike,
+} from "./types";
+import { validateInput } from "./validate";
+
+/**
+ * execute 的返回形状：复用 SDK AgentToolResult<AskUserDetails>，叠加运行时使用的 isError 标记。
+ * SDK 的 AgentToolResult 类型未声明 isError（运行时通过它标记错误），这里显式补齐。
+ */
+type ExecuteResult = AgentToolResult<AskUserDetails> & { isError?: boolean };
+
+/**
+ * expanded 渲染辅助：展开某问题的全部选项，用 ●/○ 标记是否被选中（spec FR-9）。
+ * 选中判定：answer 含该 option label（answer 形如 "Postgres" / "A, B" / "X — comment"）。
+ * 返回 TruncatedText 数组供 box.addChild 展开。
+ */
+function renderExpandedOptions(
+	q: Question,
+	answer: string,
+	theme: ThemeLike,
+): TruncatedText[] {
+	const answerTokens = new Set(answer.split(/\s*[,—]\s*|\s*,\s*/).filter(Boolean));
+	const mark = (opt: Option): string =>
+		answerTokens.has(opt.label) || answer.includes(opt.label)
+			? theme.fg("success", "●")
+			: theme.fg("dim", "○");
+	// 只展开真实选项（不含自动追加的 Other）；Other 文本单独显示
+	const out: TruncatedText[] = q.options.map(
+		(opt: Option) =>
+			new TruncatedText(
+				theme.fg("dim", "   ") +
+					mark(opt) +
+					theme.fg("text", ` ${opt.label}`),
+				0,
+				0,
+			),
+	);
+	return out;
+}
+
+export default function (pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "ask_user",
+		label: "Ask User",
+		description: `Ask the user to resolve ambiguity you cannot resolve yourself. Use ONLY when ALL hold: (1) the request has ≥2 reasonable approaches, (2) you have already gathered context (read/grep) and the answer is still genuinely ambiguous, and (3) picking wrong means redoing real work. One question = one decision with mutually exclusive options.
+
+Do NOT use this tool to outsource judgment you should make — if you can form a defensible recommendation from the codebase, proceed and state your choice. Do NOT use for trivia answerable by reading code/docs, or for simple confirmations ("I'll delete X") where plain text suffices. You cannot use this tool to collect free-form requirements, long-form feedback, or multi-paragraph input — it returns short selections only.
+
+If you recommend an option, prefix its label with "(Recommended)" and list it first. For structured multi-option decisions, prefer this tool over plain-text questions; for everything else, reply in plain text.`,
+		promptSnippet:
+			"Ask the user structured clarifying questions with options — only when you cannot resolve the ambiguity yourself",
+		promptGuidelines: [
+			"Use ask_user only when the request has ≥2 reasonable approaches you cannot resolve from context. Models over-ask because asking feels safer than deciding — resist this: if context makes the answer clear, proceed without asking.",
+			"Gather context first (read/grep) and pass a short summary via the context field — don't ask blind. If the answer becomes clear after gathering context, proceed and state your choice.",
+			"Ask focused questions; each question = one decision with mutually exclusive options. Batch related decisions into one call (1-4 questions).",
+			"Do NOT use ask_user for trivia answerable by reading code/docs, or to confirm simple actions ('I'll delete X') — plain text suffices there.",
+			"Do NOT outsource judgment you can make yourself: if you can form a defensible recommendation from the codebase, proceed and state it instead of asking.",
+			"Do NOT include an 'Other' option yourself — it is always available automatically.",
+		],
+		parameters: InputSchema,
+
+		async execute(
+			_toolCallId: string,
+			params: Static<typeof InputSchema>,
+			signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: ExtensionContext,
+		): Promise<ExecuteResult> {
+			const questions = params.questions;
+
+			// 1. 参数校验（spec FR-2）→ isError
+			const validationError = validateInput(questions);
+			if (validationError) {
+				return {
+					content: [{ type: "text" as const, text: `Error: ${validationError}` }],
+					isError: true,
+					details: { questions, answers: {}, cancelled: true } satisfies Result,
+				};
+			}
+
+			// 2. Headless 检查（spec FR-8）→ isError + 禁用工具
+			if (!ctx.hasUI) {
+				pi.setActiveTools(
+					pi
+						.getAllTools()
+						.map((t: { name: string }) => t.name)
+						.filter((n: string) => n !== "ask_user"),
+				);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Error: ask_user requires an interactive session. The tool has been disabled for this session. Do not retry — proceed without user input (make a defensible decision and state it) or wait for the user to reconnect.",
+						},
+					],
+					isError: true,
+					details: { questions, answers: {}, cancelled: true } satisfies Result,
+				};
+			}
+
+			// 3. Signal abort 入口检查（spec FR-10）
+			if (signal?.aborted) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "User cancelled. Do not assume an answer or continue the task — wait for new instructions or re-ask with refined options if the decision is still required.",
+						},
+					],
+					details: { questions, answers: {}, cancelled: true } satisfies Result,
+				};
+			}
+
+			// 4. 顶层 try/catch（spec FR-13）
+			let result: Result | null;
+			try {
+				result = await ctx.ui.custom<Result | null>(
+					(tui: unknown, theme: unknown, _kb: unknown, done: (r: Result | null) => void) => {
+						const comp = new AskUserComponent(
+							questions,
+							tui as { requestRender(): void },
+							theme as ThemeLike,
+							done,
+						);
+						// signal abort 监听（spec FR-10）：走组件 cancel() 复用 _resolved 守卫，
+						// 避免用户已 submit/cancel 后 signal 才 abort 二次调 done（FR-12 竞态）
+						if (signal) {
+							signal.addEventListener("abort", () => comp.cancel(), { once: true });
+						}
+						return comp;
+					},
+					// 不传 options → inline 渲染（spec FR-3）
+				);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `ask_user failed: ${message}. Treat as cancelled — do not assume an answer; retry the call with corrected parameters, or proceed with a defensible decision if the user cannot be reached.`,
+						},
+					],
+					isError: true,
+					details: { error: message } satisfies ErrorDetails,
+				};
+			}
+
+			// 5. 取消（null / cancelled）
+			if (result === null || result.cancelled) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "User cancelled. Do not assume an answer or continue the task — wait for new instructions or re-ask with refined options if the decision is still required.",
+						},
+					],
+					details: { questions, answers: {}, cancelled: true } satisfies Result,
+				};
+			}
+
+			// 6. 正常返回
+			const summary = result.questions.map(
+				(q: Question) => `"${q.question}" = "${result!.answers[q.question] ?? "(no answer)"}"`,
+			);
+			return {
+				content: [{ type: "text" as const, text: summary.join("\n") }],
+				details: result satisfies Result,
+			};
+		},
+
+		renderCall(args: Static<typeof InputSchema>, theme: ThemeLike) {
+			const questions: Question[] = args.questions ?? [];
+			const topics = questions.map((q) => q.header ?? truncateToWidth(q.question, HEADER_MAX_CHARS)).join(", ");
+			return new TruncatedText(
+				theme.fg("toolTitle", theme.bold("ask_user ")) + theme.fg("muted", topics),
+				0,
+				0,
+			);
+		},
+
+		renderResult(
+			result: AgentToolResult<AskUserDetails>,
+			options: ToolRenderResultOptions,
+			theme: ThemeLike,
+		) {
+			const details = result.details;
+			if (details && "error" in details && details.error) {
+				return new Text(theme.fg("error", `✗ ${details.error}`), 0, 0);
+			}
+			// details 现已排除 ErrorDetails 分支，收窄为 Result | undefined
+			const d = details as Result | undefined;
+			if (!d || d.cancelled) {
+				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			}
+			const box = new Box(0, 0);
+			for (const q of d.questions) {
+				const header = q.header ?? truncateToWidth(q.question, HEADER_MAX_CHARS);
+				const answer = d.answers[q.question] ?? "(no answer)";
+				box.addChild(
+					new TruncatedText(
+						theme.fg("success", "✓ ") +
+							theme.fg("accent", `${header}: `) +
+							theme.fg("text", answer),
+						0,
+						0,
+					),
+				);
+				// options.expanded：展开显示该问题全部选项 + ●/○ 选中标记 + 评论（spec FR-9）
+				if (options?.expanded) {
+					for (const child of renderExpandedOptions(q, answer, theme)) box.addChild(child);
+				}
+			}
+			return box;
+		},
+	});
+}

package/src/question-view.ts

@@ -0,0 +1,317 @@
+// src/question-view.ts
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
+
+import {
+	OTHER_LABEL,
+	type Question,
+	type QuestionState,
+	SPLIT_PANE_LEFT_MIN,
+	SPLIT_PANE_MIN_WIDTH,
+	SPLIT_PANE_RIGHT_MIN,
+	SPLIT_PANE_SEPARATOR,
+	type ThemeLike,
+} from "./types";
+
+export interface DisplayOption {
+	label: string;
+	description?: string;
+	isOther?: boolean;
+}
+
+/** Other 自由输入 / 已保存预览的软换行行数上限。超出则截断并加省略号。 */
+const MAX_EDITOR_LINES = 5;
+
+/**
+ * 把一段带样式的文本按 availWidth 软换行输出为多行，最多 maxLines 行。
+ * - 首行前缀 lead（如 "> [ ] "），后续行用等宽空格缩进到 input 起始列对齐。
+ * - 超过 maxLines：截断到 maxLines 行，并在最后一行末尾用 ellipsis 提示。
+ *   此时末行可能已不含末尾光标字符，用 ellipsis 占位表达「还有更多」。
+ *
+ * @param push      输出回调（通常为带 truncateToWidth 的 add，提供安全兜底）
+ * @param lead      首行前缀（含选中标记 / 勾选框）
+ * @param content   待换行展示的已样式化文本（可含 ANSI + 末尾光标 █），为空则只输出 lead
+ * @param availWidth 单行可用宽度
+ * @param maxLines  最多行数
+ */
+function addWrappedInput(
+	push: (s: string) => void,
+	lead: string,
+	content: string,
+	availWidth: number,
+	maxLines: number,
+): void {
+	const avail = Math.max(1, availWidth);
+	const indent = " ".repeat(visibleWidth(lead));
+	if (content === "") {
+		push(lead);
+		return;
+	}
+	let wrapped = wrapTextWithAnsi(content, avail);
+	if (wrapped.length > maxLines) {
+		wrapped = wrapped.slice(0, maxLines);
+		// 最后一行去掉超出，用省略号占位（光标已被省略号取代）
+		const lastIdx = wrapped.length - 1;
+		wrapped[lastIdx] = truncateToWidth(wrapped[lastIdx]!, Math.max(1, avail - 1), "…");
+	}
+	for (let i = 0; i < wrapped.length; i++) {
+		const seg = wrapped[i]!;
+		push(i === 0 ? `${lead}${seg}` : `${indent}${seg}`);
+	}
+}
+
+/** 在选项数组末尾追加 Other 自由输入项。 */
+export function allOptions(q: Question): DisplayOption[] {
+	return [...q.options, { label: OTHER_LABEL, isOther: true }];
+}
+
+/**
+ * 宽终端（≥SPLIT_PANE_MIN_WIDTH）计算左右分屏宽度。窄终端返回 null（单列模式）。
+ */
+export function getSplitPaneWidths(width: number): { left: number; right: number } | null {
+	if (width < SPLIT_PANE_MIN_WIDTH) return null;
+	const available = width - SPLIT_PANE_SEPARATOR.length;
+	if (available < SPLIT_PANE_LEFT_MIN + SPLIT_PANE_RIGHT_MIN) return null;
+	const preferredLeft = Math.floor(available * 0.42);
+	const left = Math.max(
+		SPLIT_PANE_LEFT_MIN,
+		Math.min(preferredLeft, available - SPLIT_PANE_RIGHT_MIN),
+	);
+	const right = available - left;
+	if (right < SPLIT_PANE_RIGHT_MIN) return null;
+	return { left, right };
+}
+
+/** 构建选项列表行（不含分屏预览）。hideDescriptions 用于分屏模式左列。
+ *  freeform 模式下，Other 行**原地**变 [ ] <input>█（多选）/ <input>█（单选），
+ *  不再依赖 buildEditorBlock 的下方独立编辑块。 */
+function buildOptionLines(
+	q: Question,
+	state: QuestionState,
+	theme: ThemeLike,
+	width: number,
+	hideDescriptions: boolean,
+	editorText: string = "",
+): string[] {
+	const t = theme;
+	const opts = allOptions(q);
+	const lines: string[] = [];
+	const add = (s: string): void => {
+		lines.push(truncateToWidth(s, width));
+	};
+
+	for (let i = 0; i < opts.length; i++) {
+		const opt = opts[i]!;
+		const isSelected = i === state.cursorIndex;
+		const isOther = opt.isOther === true;
+		const prefix = isSelected ? t.fg("accent", ">") : " ";
+
+		if (isOther) {
+			if (state.mode === "freeform") {
+				// 原地编辑：与多选普通选项的 [ ] 框视觉对齐（单选无勾选语义则留空）
+				const box = q.multiSelect ? t.fg("dim", "[ ]") : "  ";
+				const lead = `${prefix} ${box} `;
+				const avail = Math.max(1, width - visibleWidth(lead));
+				// 文本 + 末尾光标 █ 整体软换行（空 input 时仅光标，wrapTextWithAnsi("█") 单行）
+				const styled = `${t.fg("text", editorText)}${t.fg("accent", "█")}`;
+				addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
+			} else {
+				const hasFreeText = state.freeTextValue !== null;
+				const check = hasFreeText ? t.fg("success", "✓") : " ";
+				const labelColor = isSelected ? "accent" : "muted";
+				const num = i + 1;
+				add(`${prefix} ${check} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
+				if (hasFreeText) {
+					// 已保存 freeText 预览：软换行展示，最多 MAX_EDITOR_LINES 行（不再单行截断）
+					const lead = "     "; // 5 列缩进，与上方 label 行对齐
+					const avail = Math.max(1, width - visibleWidth(lead));
+					const styled = t.fg("dim", `"${state.freeTextValue ?? ""}"`);
+					addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
+				}
+			}
+		} else if (q.multiSelect) {
+			const checked = state.selectedIndices.has(i);
+			const box = checked ? t.fg("accent", "[✓]") : t.fg("dim", "[ ]");
+			const labelColor = isSelected ? "accent" : "text";
+			const num = i + 1;
+			add(`${prefix} ${box} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
+			if (opt.description && !hideDescriptions) {
+				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - 7);
+				for (const line of wrapped) add(`       ${line}`);
+			}
+		} else {
+			const isConfirmed = state.selectedIndex === i;
+			const check = isConfirmed ? t.fg("success", "✓") : " ";
+			const labelColor = isSelected ? "accent" : "text";
+			const num = i + 1;
+			add(`${prefix} ${check} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
+			if (opt.description && !hideDescriptions) {
+				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - 5);
+				for (const line of wrapped) add(`     ${line}`);
+			}
+		}
+	}
+	return lines;
+}
+
+/** 构建分屏右侧 Markdown 详情预览。 */
+function buildPreviewLines(
+	q: Question,
+	state: QuestionState,
+	theme: ThemeLike,
+	width: number,
+	maxLines: number,
+): string[] {
+	const t = theme;
+	const opts = allOptions(q);
+	const opt = opts[state.cursorIndex];
+	if (!opt) return [t.fg("dim", "—")];
+
+	let text = "";
+	if (opt.isOther) {
+		text = `${opt.label}: enter a custom answer not listed above.`;
+	} else {
+		text = opt.label;
+		if (opt.description?.trim()) text += `\n\n${opt.description}`;
+	}
+
+	const wrapped = wrapTextWithAnsi(t.fg("muted", text), Math.max(10, width));
+	const lines = wrapped.slice(0, maxLines);
+	if (wrapped.length > maxLines) lines.push(t.fg("dim", "…"));
+	return lines;
+}
+
+/**
+ * 渲染单个问题视图（spec FR-4）。
+ * isSingle: 单问题模式（无 Tab 提示）。
+ * editorText: freeform/comment 模式下当前编辑器文本（纯 string，由 component 持有）。
+ */
+/**
+ * freeform 模式：editor 已在 buildOptionLines 中原地渲染（[ ] <input>█ 行），
+ * buildEditorBlock 在此模式下不重复输出，**仅留出与正常 help 行同位置的视觉空隙**。
+ * comment 模式：保留独立编辑块（与 normal help 行解耦：comment 行有更长的 prompt）。
+ */
+function buildEditorBlock(
+	theme: ThemeLike,
+	width: number,
+	mode: "freeform" | "comment",
+	editorText: string,
+): string[] {
+	if (mode === "freeform") {
+		return [""];
+	}
+	const t = theme;
+	const lines: string[] = [];
+	const add = (s: string): void => {
+		lines.push(truncateToWidth(s, width));
+	};
+	add("");
+	const prompt = t.fg("muted", " Your comment (optional):");
+	add(prompt);
+	// 渲染当前编辑器文本（单行；多行时按 \n 拆分）
+	for (const line of editorText.split("\n")) add(` ${line}`);
+	// 光标行
+	add(` ${t.fg("accent", "█")}`);
+	add("");
+	add(t.fg("dim", " Enter submit · Esc back"));
+	return lines;
+}
+
+/** 渲染分屏模式下的左右双列（选项列表 + 详情预览）。 */
+function buildSplitPane(
+	q: Question,
+	state: QuestionState,
+	theme: ThemeLike,
+	split: { left: number; right: number },
+	width: number,
+	editorText: string = "",
+): string[] {
+	const t = theme;
+	const lines: string[] = [];
+	const add = (s: string): void => {
+		lines.push(truncateToWidth(s, width));
+	};
+	const leftLines = buildOptionLines(q, state, theme, split.left, true, editorText);
+	const rightLines = buildPreviewLines(q, state, theme, split.right, Math.max(leftLines.length, 8));
+	const rowCount = Math.max(leftLines.length, rightLines.length);
+	const sep = t.fg("dim", SPLIT_PANE_SEPARATOR);
+	for (let i = 0; i < rowCount; i++) {
+		const left = truncateToWidth(leftLines[i] ?? "", split.left, "", true);
+		const right = truncateToWidth(rightLines[i] ?? "", split.right);
+		add(`${left}${sep}${right}`);
+	}
+	return lines;
+}
+
+export function renderQuestionView(
+	q: Question,
+	state: QuestionState,
+	theme: ThemeLike,
+	width: number,
+	isSingle: boolean,
+	editorText: string,
+): string[] {
+	const t = theme;
+	const lines: string[] = [];
+	const add = (s: string): void => {
+		lines.push(truncateToWidth(s, width));
+	};
+	const divider = (): void => add(t.fg("dim", "─".repeat(Math.max(0, width))));
+
+	// 问题文本（word-wrap）
+	const wrapped = wrapTextWithAnsi(t.fg("text", ` ${q.question}`), width - 2);
+	for (const line of wrapped) add(line);
+
+	// 上下文（如有）
+	if (q.context?.trim()) {
+		divider();
+		const ctxWrapped = wrapTextWithAnsi(t.fg("muted", q.context), width - 2);
+		for (const line of ctxWrapped) add(line);
+	}
+
+	// 分屏判断
+	const split = getSplitPaneWidths(width);
+
+	// 选项模式下：question/context 与 options 之间加分割线（三段式）
+	// 编辑器模式不加（编辑器块自带视觉边界）
+	if (state.mode !== "freeform" && state.mode !== "comment") {
+		divider();
+	}
+
+	// 编辑器/评论模式：选项列表 + 编辑器块（freeform 模式下编辑器块为空，由 buildOptionLines 原地渲染）
+	if (state.mode === "freeform" || state.mode === "comment") {
+		add("");
+		const optionLines = buildOptionLines(q, state, theme, split ? split.left : width, !!split, editorText);
+		for (const line of optionLines) add(line);
+		const editorBlock = buildEditorBlock(theme, width, state.mode, editorText);
+		lines.push(...editorBlock);
+		if (state.mode === "freeform") {
+			// freeform 模式 help 行：光标锁在 Other 上，正在输入
+			add(t.fg("dim", " Enter submit · Esc back"));
+		}
+		return lines;
+	}
+
+	if (!split) {
+		// 单列模式
+		const optionLines = buildOptionLines(q, state, theme, width, false, editorText);
+		for (const line of optionLines) add(line);
+	} else {
+		// 分屏模式
+		lines.push(...buildSplitPane(q, state, theme, split, width, editorText));
+	}
+
+	add("");
+
+	// 帮助行（上下文相关）
+	const opts = allOptions(q);
+	const onOther = state.cursorIndex === opts.length - 1;
+	const tabHint = isSingle ? "" : " · Tab switch tabs";
+	const actionHint = onOther
+		? "Enter open editor"
+		: q.multiSelect
+			? "Space toggle · Enter confirm"
+			: "Enter select";
+	add(t.fg("dim", ` ↑↓ navigate · ${actionHint}${tabHint} · Esc back`));
+
+	return lines;
+}

package/src/submit-view.ts

@@ -0,0 +1,114 @@
+// src/submit-view.ts
+import { truncateToWidth } from "@mariozechner/pi-tui";
+
+import {
+	ANSWER_COMMENT_SEPARATOR,
+	HEADER_MAX_CHARS,
+	type Question,
+	type QuestionState,
+	type Result,
+	type ThemeLike,
+} from "./types";
+
+/**
+ * 获取单问题的答案文本（供 Submit tab 显示）。
+ * 返回 null 表示未答。
+ */
+export function getAnswerText(q: Question, s: QuestionState): string | null {
+	if (!s.confirmed) return null;
+	const parts: string[] = [];
+	if (q.multiSelect) {
+		const labels = [...s.selectedIndices]
+			.sort((a, b) => a - b)
+			.map((idx) => q.options[idx]?.label)
+			.filter((l): l is string => !!l);
+		parts.push(...labels);
+	} else if (s.selectedIndex !== null) {
+		const label = q.options[s.selectedIndex]?.label;
+		if (label) parts.push(label);
+	}
+	if (s.freeTextValue !== null) parts.push(s.freeTextValue);
+	if (parts.length === 0) return null;
+	const base = parts.join(", ");
+	return s.commentValue ? `${base}${ANSWER_COMMENT_SEPARATOR}${s.commentValue}` : base;
+}
+
+/**
+ * 渲染 Submit tab 视图。
+ * focus: 当前在 [Submit]/[Cancel] 上的焦点（←/→ 切换）。
+ *   渲染内嵌按钮栏高亮 focus；help 行更新为 "←/→ toggle · Enter confirm"。
+ */
+export function renderSubmitView(
+	questions: Question[],
+	states: QuestionState[],
+	theme: ThemeLike,
+	width: number,
+	focus: "submit" | "cancel" = "submit",
+): string[] {
+	const t = theme;
+	const lines: string[] = [];
+	const add = (s: string): void => {
+		lines.push(truncateToWidth(s, width));
+	};
+
+	const allDone = states.every((s) => s.confirmed);
+
+	add(
+		allDone
+			? t.fg("success", t.bold(" Ready to submit"))
+			: t.fg("warning", t.bold(" Unanswered questions")),
+	);
+	add("");
+
+	for (let i = 0; i < questions.length; i++) {
+		const q = questions[i]!;
+		const answer = getAnswerText(q, states[i]!);
+		const headerLabel = truncateToWidth(q.header ?? "", HEADER_MAX_CHARS);
+		if (answer !== null) {
+			add(` ${t.fg("muted", `${headerLabel}: `)}${t.fg("text", answer)}`);
+		} else {
+			add(` ${t.fg("dim", `${headerLabel}: `)}${t.fg("warning", "—")}`);
+		}
+	}
+
+	add("");
+	if (allDone) {
+		add(t.fg("success", " All questions answered"));
+	} else {
+		const missing = questions
+			.filter((_, i) => !states[i]!.confirmed)
+			.map((q) => truncateToWidth(q.header ?? "", HEADER_MAX_CHARS))
+			.join(", ");
+		add(t.fg("warning", ` Still needed: ${missing}`));
+	}
+
+	// 内嵌按钮栏：[ Submit ]   [ Cancel ]，根据 focus 高亮
+	add("");
+	const isSubmit = focus === "submit";
+	const isCancel = focus === "cancel";
+	const submitBtn = isSubmit
+		? (allDone ? t.fg("success", t.bold(" Submit ")) : t.fg("accent", t.bold(" Submit ")))
+		: (allDone ? t.fg("success", " Submit ") : t.fg("dim", " Submit "));
+	const cancelBtn = isCancel ? t.fg("accent", t.bold(" Cancel ")) : t.fg("muted", " Cancel ");
+	add(`${t.fg("dim", "[")}${submitBtn}${t.fg("dim", "]")}   ${t.fg("dim", "[")}${cancelBtn}${t.fg("dim", "]")}`);
+
+	// Submit tab 帮助行
+	add("");
+	add(t.fg("dim", " ←/→ toggle · Enter confirm · Tab back to first question"));
+
+	return lines;
+}
+
+/**
+ * 从 states 构建 Result（供组件 buildResult 调用）。
+ */
+export function buildResult(questions: Question[], states: QuestionState[]): Result {
+	const answers: Record<string, string> = {};
+	for (let i = 0; i < questions.length; i++) {
+		const q = questions[i]!;
+		const s = states[i]!;
+		const text = getAnswerText(q, s);
+		if (text !== null) answers[q.question] = text;
+	}
+	return { questions, answers, cancelled: false };
+}