@zhushanwen/pi-ask-user 0.0.4 → 0.2.0

package/src/__tests__/question-view.test.ts

@@ -1,14 +1,9 @@
 // src/__tests__/question-view.test.ts
 import { describe, expect, it } from "vitest";
 
-import { getSplitPaneWidths, renderQuestionView } from "../question-view";
-import { createQuestionState, type Question, type QuestionState, type ThemeLike } from "../types";
-
-const stubTheme: ThemeLike = {
-	fg: (_t: string, s: string) => s,
-	bg: (_t: string, s: string) => s,
-	bold: (s: string) => s,
-};
+import { getSplitPaneWidths, renderQuestionView, type RenderContext } from "../question-view";
+import { createQuestionState, type Question, type QuestionState } from "../types";
+import { stubTheme } from "./fixtures";
 
 const singleQ: Question = {
 	question: "Which database?",
@@ -23,18 +18,33 @@ const makeState = (over: Partial<QuestionState> = {}): QuestionState => ({
 	...over,
 });
 
+/** 测试辅助：桥接旧的位置参数签名到新的 RenderContext 签名。
+ *  draftText 合并进 state（新 API 从 state.draftText 读）。 */
+function rv(
+	q: Question,
+	state: QuestionState,
+	theme: typeof stubTheme,
+	width: number,
+	isSingle: boolean,
+	draftText: string = "",
+): string[] {
+	const mergedState = { ...state, draftText: draftText || state.draftText };
+	const ctx: RenderContext = { question: q, state: mergedState, theme, width, isSingle };
+	return renderQuestionView(ctx);
+}
+
 // Helper: join all lines for substring search
 const text = (lines: string[]): string => lines.join("\n");
 
 // ── Q-1 ~ Q-6: 基础渲染 ──────────────────────────────────
 describe("renderQuestionView — basics", () => {
 	it("Q-1: renders question text", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 60, true, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 60, true, "");
 		expect(text(lines)).toContain("Which database?");
 	});
 
 	it("Q-2: renders all options + Other", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 60, true, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 60, true, "");
 		const t = text(lines);
 		expect(t).toContain("Postgres");
 		expect(t).toContain("SQLite");
@@ -42,14 +52,14 @@ describe("renderQuestionView — basics", () => {
 	});
 
 	it("Q-3: renders cursor > on first option", () => {
-		const lines = renderQuestionView(singleQ, makeState({ cursorIndex: 0 }), stubTheme, 60, true, "");
+		const lines = rv(singleQ, makeState({ cursorIndex: 0 }), stubTheme, 60, true, "");
 		const t = text(lines);
 		expect(t).toContain(">");
 		expect(t).toContain("Postgres");
 	});
 
 	it("Q-4: renders single-select check on confirmed selection", () => {
-		const lines = renderQuestionView(singleQ, makeState({ selectedIndex: 1 }), stubTheme, 60, true, "");
+		const lines = rv(singleQ, makeState({ selectedIndex: 1 }), stubTheme, 60, true, "");
 		expect(text(lines)).toContain("✓");
 		expect(text(lines)).toContain("SQLite");
 	});
@@ -60,7 +70,7 @@ describe("renderQuestionView — basics", () => {
 			options: [{ label: "Auth" }, { label: "Search" }],
 			multiSelect: true,
 		};
-		const lines = renderQuestionView(
+		const lines = rv(
 			multiQ,
 			makeState({ selectedIndices: new Set([0]) }),
 			stubTheme,
@@ -74,7 +84,7 @@ describe("renderQuestionView — basics", () => {
 	});
 
 	it("Q-6: renders descriptions in muted", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 60, true, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 60, true, "");
 		expect(text(lines)).toContain("Battle-tested");
 	});
 });
@@ -101,7 +111,7 @@ describe("renderQuestionView — split pane", () => {
 	});
 
 	it("Q-9: split-pane left column hides descriptions", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 100, true, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 100, true, "");
 		const t = text(lines);
 		// In split mode, descriptions appear only in the right pane preview of the focused item.
 		// The focused item (cursorIndex=0=Postgres) shows "Battle-tested" in the right pane,
@@ -114,7 +124,7 @@ describe("renderQuestionView — split pane", () => {
 	});
 
 	it("Q-10: split-pane right pane shows focused option detail", () => {
-		const lines = renderQuestionView(singleQ, makeState({ cursorIndex: 1 }), stubTheme, 100, true, "");
+		const lines = rv(singleQ, makeState({ cursorIndex: 1 }), stubTheme, 100, true, "");
 		const t = text(lines);
 		// Focused on SQLite → right pane should show SQLite's description
 		expect(t).toContain("Embedded");
@@ -122,13 +132,13 @@ describe("renderQuestionView — split pane", () => {
 
 	it("Q-11: split-pane right pane on Other shows custom-answer hint", () => {
 		// cursorIndex = last option (Other) = 2
-		const lines = renderQuestionView(singleQ, makeState({ cursorIndex: 2 }), stubTheme, 100, true, "");
+		const lines = rv(singleQ, makeState({ cursorIndex: 2 }), stubTheme, 100, true, "");
 		const t = text(lines);
 		expect(t).toContain("custom");
 	});
 
 	it("Q-14: single-column mode shows indented descriptions", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 60, true, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 60, true, "");
 		// Both descriptions shown inline (single-column mode)
 		const t = text(lines);
 		expect(t).toContain("Battle-tested");
@@ -139,7 +149,7 @@ describe("renderQuestionView — split pane", () => {
 // ── Q-15 ~ Q-17: Other 编辑器模式 ───────────────────────
 describe("renderQuestionView — Other editor mode", () => {
 	it("Q-15: freeform mode renders Other row in-place with draft + cursor + number prefix", () => {
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ mode: "freeform", cursorIndex: 2 }),
 			stubTheme,
@@ -148,9 +158,10 @@ describe("renderQuestionView — Other editor mode", () => {
 			"my draft",
 		);
 		const t = text(lines);
-		// Other 行原地变 [ ] <input>█（freeform 模式不依赖 buildEditorBlock 独立编辑块）
-		expect(t).toContain("my draft");
-		expect(t).toContain("█");
+		// cursorIndex=2 → █ 在 "my" 和 " draft" 之间
+		expect(t).toContain("my");
+		expect(t).toContain("draft");
+		expect(t).toContain("\x1b[7m");
 		// 不再独立 "Your answer" 提示行
 		expect(t).not.toContain("Your answer");
 		// 需求4：Other 在 freeform 态也有编号前缀（与其他选项一致）。
@@ -165,7 +176,7 @@ describe("renderQuestionView — Other editor mode", () => {
 			multiSelect: true,
 			options: [{ label: "Auth" }, { label: "Search" }],
 		};
-		const lines = renderQuestionView(
+		const lines = rv(
 			multiQ,
 			makeState({ mode: "freeform", cursorIndex: 2 }),
 			stubTheme,
@@ -177,12 +188,15 @@ describe("renderQuestionView — Other editor mode", () => {
 		// 多选 box [ ] + 编号 3. 都在编辑行上
 		expect(t).toContain("[ ]");
 		expect(t).toContain("3. ");
-		expect(t).toContain("custom");
-		expect(t).toContain("█");
+		// cursorIndex=2 → cursor 在 "s" 上: "cu\x1b[7ms\x1b[27mtom" — "stom" 被 cursor 打断
+		expect(t).toContain("cu");
+		expect(t).toContain("s");
+		expect(t).toContain("tom");
+		expect(t).toContain("\x1b[7m");
 	});
 
 	it("Q-16: Other with saved free-text shows checkmark + preview", () => {
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ cursorIndex: 2, freeTextValue: "saved text" }),
 			stubTheme,
@@ -196,7 +210,7 @@ describe("renderQuestionView — Other editor mode", () => {
 	});
 
 	it("Q-17: Other row focused shows Enter hint (Tab now navigates tabs)", () => {
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ cursorIndex: 2 }),
 			stubTheme,
@@ -213,7 +227,7 @@ describe("renderQuestionView — Other editor mode", () => {
 		const width = 30;
 		// lead = "> [ ] " (单选 box="  ") = 6 列 → avail = 24
 		const long = "x".repeat(60);
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ mode: "freeform", cursorIndex: 2 }),
 			stubTheme,
@@ -227,10 +241,13 @@ describe("renderQuestionView — Other editor mode", () => {
 		expect(xCount).toBe(60);
 		expect(lines.some((l) => l.includes("x"))).toBe(true);
 		// 光标仍在末尾出现
-		expect(t).toContain("█");
-		// 每个含 x 的行都不超过总宽 width（stubTheme 无 ANSI，长度=可见宽）
+		expect(t).toContain("\x1b[7m");
+		// 每个含 x 的行可见宽度不超过 width（strip ANSI 后测量）
 		for (const l of lines) {
-			if (l.includes("x")) expect(l.length).toBeLessThanOrEqual(width);
+			if (l.includes("x")) {
+				const visible = l.replace(/\x1b\[[0-9;]*m/g, "");
+				expect(visible.length).toBeLessThanOrEqual(width);
+			}
 		}
 	});
 
@@ -243,7 +260,7 @@ describe("renderQuestionView — Other editor mode", () => {
 		// 单选 lead visLen=5 → avail = width - 5 = 95。用 60 字符（< 95）应单行装下。
 		// 修复前若用 split.left≈40，avail≈35 → 60 字符会换 2 行。
 		const input = "a".repeat(60);
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ mode: "freeform", cursorIndex: 2 }),
 			stubTheme,
@@ -252,7 +269,7 @@ describe("renderQuestionView — Other editor mode", () => {
 			input,
 		);
 		// 用 █ 定位编辑器行（help 行不含 █），排除 “submit” 含 a 的干扰
-		const editorLines = lines.filter((l) => l.includes("█"));
+		const editorLines = lines.filter((l) => l.includes("\x1b[7m"));
 		expect(editorLines.length).toBe(1);
 		// 全部 60 个 a 都在这一行（未被换行拆分）
 		const aCount = editorLines[0]!.split("").filter((c) => c === "a").length;
@@ -263,7 +280,7 @@ describe("renderQuestionView — Other editor mode", () => {
 		const width = 30;
 		// avail=24，200 字符 → 9 行，超过 5 行上限
 		const huge = "y".repeat(200);
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ mode: "freeform", cursorIndex: 2 }),
 			stubTheme,
@@ -273,7 +290,8 @@ describe("renderQuestionView — Other editor mode", () => {
 		);
 		// 统计含输入内容的行数 = input 渲染行数（应被截到 5 行）
 		// 编号 "3. " 现在是 styled 内容的一部分，首行包裹段 "3." 不含 'y'
-		const inputLines = lines.filter((l) => l.includes("y") || l.includes("3."));
+		// 排除 help 行（含 "Type to add" 的提示行也含 'y'）
+		const inputLines = lines.filter((l) => (l.includes("y") || l.includes("3.")) && !l.includes("Type to add"));
 		expect(inputLines.length).toBe(5);
 		// 最后一行带省略号（表示还有更多，光标已被省略号取代）
 		expect(inputLines[inputLines.length - 1]).toContain("…");
@@ -283,7 +301,7 @@ describe("renderQuestionView — Other editor mode", () => {
 		const width = 40;
 		// 预览 lead="     "(5 列) → avail=35；预览文本带引号
 		const long = "z".repeat(80);
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ cursorIndex: 2, freeTextValue: long }),
 			stubTheme,
@@ -303,7 +321,7 @@ describe("renderQuestionView — Other editor mode", () => {
 		const width = 30;
 		// 预览 avail = 30-5 = 25，300 字符 → >5 行
 		const huge = "w".repeat(300);
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ cursorIndex: 2, freeTextValue: huge }),
 			stubTheme,
@@ -320,7 +338,7 @@ describe("renderQuestionView — Other editor mode", () => {
 // ── Q-18 ~ Q-19: 评论模式 ───────────────────────────────
 describe("renderQuestionView — comment mode", () => {
 	it("Q-18: comment mode renders editor with note text", () => {
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ mode: "comment", selectedIndex: 0 }),
 			stubTheme,
@@ -334,7 +352,7 @@ describe("renderQuestionView — comment mode", () => {
 	});
 
 	it("Q-19: comment prompt includes (optional)", () => {
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ mode: "comment", selectedIndex: 0 }),
 			stubTheme,
@@ -349,7 +367,7 @@ describe("renderQuestionView — comment mode", () => {
 // ── Q-20 ~ Q-23: 帮助行 ─────────────────────────────────
 describe("renderQuestionView — help line", () => {
 	it("Q-20: single-select help shows 'Enter select'", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 60, true, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 60, true, "");
 		expect(text(lines)).toContain("Enter select");
 	});
 
@@ -359,17 +377,17 @@ describe("renderQuestionView — help line", () => {
 			options: [{ label: "A" }, { label: "B" }],
 			multiSelect: true,
 		};
-		const lines = renderQuestionView(multiQ, makeState(), stubTheme, 60, true, "");
+		const lines = rv(multiQ, makeState(), stubTheme, 60, true, "");
 		expect(text(lines)).toContain("Space toggle");
 	});
 
 	it("Q-22: single question omits tab-switch hint", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 60, true, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 60, true, "");
 		expect(text(lines)).not.toContain("switch tabs");
 	});
 
 	it("Q-23: multi question includes tab-switch hint", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 60, false, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 60, false, "");
 		expect(text(lines)).toContain("switch tabs");
 	});
 });
@@ -378,7 +396,7 @@ describe("renderQuestionView — help line", () => {
 describe("renderQuestionView — Other row alignment", () => {
 	it("Q-32: 单选 Other freeform 编辑行编号与普通选项对齐", () => {
 		// 回归：单选 freeform 占位从 \"  \"(2列) 改为 \" \"(1列)，编号列与普通单选对齐
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ mode: "freeform", cursorIndex: 2 }),
 			stubTheme,
@@ -387,7 +405,7 @@ describe("renderQuestionView — Other row alignment", () => {
 			"custom",
 		);
 		const normalLine = lines.find((l) => l.includes("Postgres"))!;
-		const otherLine = lines.find((l) => l.includes("█"))!;
+		const otherLine = lines.find((l) => l.includes("\x1b[7m"))!;
 		// stubTheme 无 ANSI，indexOf 反映可见列位置。普通选项编号 idx === Other 编号 idx
 		expect(normalLine.indexOf("1.")).toBe(otherLine.indexOf("3."));
 	});
@@ -399,7 +417,7 @@ describe("renderQuestionView — Other row alignment", () => {
 			multiSelect: true,
 			options: [{ label: "Auth" }, { label: "Search" }],
 		};
-		const lines = renderQuestionView(
+		const lines = rv(
 			multiQ,
 			makeState({ cursorIndex: 2 }),
 			stubTheme,
@@ -414,7 +432,7 @@ describe("renderQuestionView — Other row alignment", () => {
 
 	it("Q-34: 单选 Other freeText 预览缩进对齐到 label 起始列", () => {
 		// 回归：预览 lead 从硬编码 6 列改为动态计算（单选个位 = 7 列）
-		const lines = renderQuestionView(
+		const lines = rv(
 			singleQ,
 			makeState({ cursorIndex: 2, freeTextValue: "saved" }),
 			stubTheme,
@@ -434,7 +452,7 @@ describe("renderQuestionView — Other row alignment", () => {
 			multiSelect: true,
 			options: [{ label: "Auth" }, { label: "Search" }],
 		};
-		const lines = renderQuestionView(
+		const lines = rv(
 			multiQ,
 			makeState({ cursorIndex: 2, freeTextValue: "saved" }),
 			stubTheme,
@@ -453,7 +471,7 @@ describe("renderQuestionView — Other row alignment", () => {
 			question: "Q",
 			options: Array.from({ length: 10 }, (_, k) => ({ label: `Opt${k + 1}` })),
 		};
-		const lines = renderQuestionView(
+		const lines = rv(
 			bigQ,
 			makeState({ cursorIndex: 10, freeTextValue: "x" }),
 			stubTheme,
@@ -471,12 +489,12 @@ describe("renderQuestionView — Other row alignment", () => {
 describe("renderQuestionView — context", () => {
 	it("Q-24: renders context when present", () => {
 		const q: Question = { ...singleQ, context: "Background info here" };
-		const lines = renderQuestionView(q, makeState(), stubTheme, 60, true, "");
+		const lines = rv(q, makeState(), stubTheme, 60, true, "");
 		expect(text(lines)).toContain("Background info here");
 	});
 
 	it("Q-25: no context field → no extra context text", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 60, true, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 60, true, "");
 		// No "context" label text in output (only question/options/help)
 		expect(text(lines)).toContain("Which database?");
 	});
@@ -485,7 +503,7 @@ describe("renderQuestionView — context", () => {
 // ── Q-26 ~ Q-27: 边界 ───────────────────────────────────
 describe("renderQuestionView — edge cases", () => {
 	it("Q-26: very narrow terminal width=20 does not crash", () => {
-		const lines = renderQuestionView(singleQ, makeState(), stubTheme, 20, true, "");
+		const lines = rv(singleQ, makeState(), stubTheme, 20, true, "");
 		expect(lines.length).toBeGreaterThan(0);
 	});
 
@@ -494,7 +512,7 @@ describe("renderQuestionView — edge cases", () => {
 			question: "Q",
 			options: [{ label: "A".repeat(80), description: "desc" }, { label: "B" }],
 		};
-		const lines = renderQuestionView(q, makeState(), stubTheme, 40, true, "");
+		const lines = rv(q, makeState(), stubTheme, 40, true, "");
 		// Should not contain the full 80-char label on a 40-col terminal
 		const t = text(lines);
 		expect(t).not.toContain("A".repeat(80));

package/src/__tests__/sdk-contract.test.ts

@@ -0,0 +1,111 @@
+// src/__tests__/sdk-contract.test.ts
+//
+// SDK 契约测试：验证 ask-user 扩展的工厂函数和注册接口与 SDK 类型兼容。
+// 核心断言：
+//   1. default export 是接受 ExtensionAPI 的工厂函数
+//   2. registerTool 注册名为 "ask_user" 的 tool，含 description/execute/renderCall/renderResult
+//   3. renderCall 参数数量 >= 1（args）
+//   4. renderResult 参数数量 >= 2（result, options）
+//   5. validateInput 校验逻辑正确
+
+import { describe, expect, it } from "vitest";
+
+import { validateInput } from "../validate";
+import askUserExtension from "../index";
+
+describe("ask-user SDK contract", () => {
+	it("default export is a function accepting ExtensionAPI", () => {
+		expect(typeof askUserExtension).toBe("function");
+		// 工厂函数应接受 1 个参数 (pi: ExtensionAPI)
+		expect(askUserExtension.length).toBe(1);
+	});
+
+	it("registerTool receives a valid ToolDefinition named 'ask_user'", () => {
+		let toolDef: Record<string, unknown> | undefined;
+		const mockPi = {
+			registerTool(def: Record<string, unknown>) {
+				toolDef = def;
+			},
+			on() {},
+			registerCommand() {},
+			getAllTools() { return []; },
+			setActiveTools() {},
+		} as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI;
+
+		askUserExtension(mockPi);
+
+		expect(toolDef).toBeDefined();
+		expect(toolDef!.name).toBe("ask_user");
+		expect(typeof toolDef!.description).toBe("string");
+		expect(typeof toolDef!.execute).toBe("function");
+		expect(typeof toolDef!.renderCall).toBe("function");
+		expect(typeof toolDef!.renderResult).toBe("function");
+		// parameters schema 应存在
+		expect(toolDef!.parameters).toBeDefined();
+	});
+
+	it("renderCall accepts >= 1 args (args, [theme])", () => {
+		let toolDef: Record<string, unknown> | undefined;
+		const mockPi = {
+			registerTool(def: Record<string, unknown>) { toolDef = def; },
+			on() {},
+			registerCommand() {},
+			getAllTools() { return []; },
+			setActiveTools() {},
+		} as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI;
+		askUserExtension(mockPi);
+		expect(toolDef!.renderCall!.length).toBeGreaterThanOrEqual(1);
+	});
+
+	it("renderResult accepts >= 2 args (result, options, [theme])", () => {
+		let toolDef: Record<string, unknown> | undefined;
+		const mockPi = {
+			registerTool(def: Record<string, unknown>) { toolDef = def; },
+			on() {},
+			registerCommand() {},
+			getAllTools() { return []; },
+			setActiveTools() {},
+		} as unknown as import("@mariozechner/pi-coding-agent").ExtensionAPI;
+		askUserExtension(mockPi);
+		expect(toolDef!.renderResult!.length).toBeGreaterThanOrEqual(2);
+	});
+
+	it("validateInput accepts empty questions array (schema-level, not runtime)", () => {
+		// validateInput 是运行时校验，不检查数组长度（minItems 由 typebox schema 层强制）
+		expect(validateInput([])).toBeNull();
+	});
+
+	it("validateInput accepts empty options array (schema-level, not runtime)", () => {
+		// 同上：options 长度由 schema 层校验
+		expect(
+			validateInput([
+				{ question: "Q?", options: [] },
+			] as unknown as import("../types").Question[]),
+		).toBeNull();
+	});
+
+	it("validateInput rejects duplicate question text", () => {
+		expect(
+			validateInput([
+				{ question: "Same?", options: [{ label: "A" }, { label: "B" }] },
+				{ question: "Same?", header: "Dup", options: [{ label: "X" }, { label: "Y" }] },
+			] as import("../types").Question[]),
+		).toBeTruthy();
+	});
+
+	it("validateInput rejects empty option label", () => {
+		expect(
+			validateInput([
+				{ question: "Q?", options: [{ label: "" }, { label: "B" }] },
+			] as import("../types").Question[]),
+		).toBeTruthy();
+	});
+
+	it("validateInput accepts a valid single question", () => {
+		expect(
+			validateInput([
+				{ question: "Q1?", options: [{ label: "A" }, { label: "B" }] },
+			] as import("../types").Question[]),
+		).toBeNull();
+	});
+});

package/src/__tests__/validate.test.ts

@@ -1,7 +1,7 @@
 // src/__tests__/validate.test.ts
 import { describe, expect, it } from "vitest";
 
-import type { Question } from "../types";
+import { HEADER_MAX_CHARS, type Question } from "../types";
 import { validateInput } from "../validate";
 
 const q = (overrides: Partial<Question> = {}): Question => ({
@@ -80,13 +80,15 @@ describe("validateInput", () => {
 		expect(result).toBeNull();
 	});
 
-	// V-10: 不同 question 可以有相同 header（header 不要求唯一）
-	it("allows duplicate headers across different questions", () => {
+	// V-10/S3: 多 question 时 header 必须唯一——重复 header 会导致 askUserKey 碰撞
+	// （协议 helper 用 header 作 answers 读取 key，后一个覆盖前一个的 Other/comment）
+	it("rejects duplicate headers across different questions", () => {
 		const result = validateInput([
 			q({ question: "Q1", header: "Same" }),
 			q({ question: "Q2", header: "Same" }),
 		]);
-		expect(result).toBeNull();
+		expect(result).not.toBeNull();
+		expect(result).toContain("Duplicate header");
 	});
 
 	// V-11: option description 不参与唯一性校验
@@ -121,4 +123,17 @@ describe("validateInput", () => {
 			expect(result).toContain("control characters");
 		}
 	});
+
+	// V-15: header 超过 HEADER_MAX_CHARS(12) 上限被拒绝（A3：补 validate 层校验）
+	it("rejects header exceeding HEADER_MAX_CHARS (12)", () => {
+		const result = validateInput([q({ header: "This header is too long" })]);
+		expect(result).not.toBeNull();
+		expect(result).toContain("Header exceeds");
+		expect(result).toContain(`${HEADER_MAX_CHARS}`);
+	});
+
+	// V-16: header 恰好 12 字符（边界值，合法）
+	it("accepts header at exactly HEADER_MAX_CHARS (12)", () => {
+		expect(validateInput([q({ header: "123456789012" })])).toBeNull();
+	});
 });