@zhushanwen/pi-ask-user 0.0.3 → 0.1.0

package/src/__tests__/w2-draft-hint.test.ts

@@ -0,0 +1,246 @@
+// src/__tests__/w2-draft-hint.test.ts
+// W2: draftText migration (#2) + handleInput split (#3) + hint line (#4)
+import { describe, expect, it } from "vitest";
+
+import { AskUserComponent } from "../component";
+import type { Question, Result } from "../types";
+import {
+	DOWN,
+	ENTER,
+	ESC,
+	LEFT,
+	mockTui,
+	multiQ,
+	RIGHT,
+	singleQ,
+	singleQWithComment,
+	stubTheme,
+	UP,
+} from "./fixtures";
+
+const make = (
+	questions: Question[],
+): { c: AskUserComponent; result: { val: Result | null | undefined } } => {
+	const result = { val: undefined as Result | null | undefined };
+	const c = new AskUserComponent(questions, mockTui, stubTheme, (r) => (result.val = r));
+	return { c, result };
+};
+
+// ── parseKey guard: arrow keys no-op in editor ──
+describe("W2 — parseKey guard (arrow/keys no-op in editor)", () => {
+	it("C-ARROW-1: three right arrows do not leak escape fragments", () => {
+		const { c } = make([singleQ]);
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER); // open freeform
+		c.handleInput(RIGHT);
+		c.handleInput(RIGHT);
+		c.handleInput(RIGHT);
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toBeDefined();
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+	});
+
+	it("C-ARROW-2: arrow keys between typed chars with cursor movement", () => {
+		const { c } = make([singleQ]);
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER); // open freeform
+		c.handleInput(DOWN);  // no-op
+		c.handleInput(RIGHT); // no-op (empty text)
+		c.handleInput("a");   // insert at 0 → "a", cursor=1
+		c.handleInput(UP);    // no-op
+		c.handleInput(LEFT);  // cursor 1→0
+		c.handleInput("b");   // insert at 0 → "ba", cursor=1
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toBeDefined();
+		// cursor at 1: "b█a" — 去 ANSI 后精确文本 "ba"（证明 insert 位置：b 在 a 前）
+		const stripped = editorLine!.replace(/\x1b\[[0-9;]*m/g, "");
+		expect(stripped).toContain("ba");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+	});
+
+	it("C-KEYMAP-SPACE: space input appends a space character", () => {
+		const { c } = make([singleQ]);
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER);
+		c.handleInput("a");
+		c.handleInput(" ");
+		c.handleInput("b");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("a b");
+	});
+
+	it("C-KEYMAP-UP: up arrow is no-op in freeform editor", () => {
+		const { c } = make([singleQ]);
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER);
+		c.handleInput("a");
+		c.handleInput(UP);
+		c.handleInput("b");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("ab");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+	});
+
+	it.each([
+		["ctrl+up", "\x1b[1;5A"],
+		["ctrl+down", "\x1b[1;5B"],
+		["ctrl+left", "\x1b[1;5D"],
+		["ctrl+right", "\x1b[1;5C"],
+		["alt+up", "\x1b[1;3A"],
+		["alt+down", "\x1b[1;3B"],
+		["shift+up", "\x1b[1;2A"],
+		["shift+down", "\x1b[1;2B"],
+		["shift+left", "\x1b[1;2D"],
+		["shift+right", "\x1b[1;2C"],
+	])("C-KEYMAP-MOD: %s is no-op in editor", (_name, seq) => {
+		const { c } = make([singleQ]);
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER);
+		c.handleInput("a");
+		c.handleInput(seq);
+		c.handleInput("b");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("ab");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+	});
+});
+
+// ── draftText migration: per-question draft persistence ──
+describe("W2 — draftText migration", () => {
+	it("C-DRAFT-1: freeform draft persists when switching tabs away and back", () => {
+		const { c } = make(multiQ);
+		// Q1: navigate to Other (index 2), open freeform, type "abc"
+		c.handleInput(DOWN); // 0→1
+		c.handleInput(DOWN); // 1→2 (Other)
+		c.handleInput(ENTER);
+		c.handleInput("abc");
+		c.handleInput(ESC); // back to options
+		// Switch to Q2 and back to Q1
+		c.handleInput(RIGHT);
+		c.handleInput(LEFT);
+		// Re-enter freeform
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER);
+		const lines = c.render(80);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toBeDefined();
+		expect(editorLine).toContain("abc");
+	});
+
+	it("C-DRAFT-2: drafts on different questions are independent", () => {
+		const { c } = make(multiQ);
+		// Q1: type "aaa"
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER);
+		c.handleInput("aaa");
+		c.handleInput(ESC);
+		// Navigate to Q3
+		c.handleInput(RIGHT);
+		c.handleInput(RIGHT);
+		// Q3: type "ccc"
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER);
+		c.handleInput("ccc");
+		c.handleInput(ESC);
+		// Go back to Q1
+		c.handleInput(LEFT);
+		c.handleInput(LEFT);
+		// Re-enter freeform on Q1
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER);
+		const lines1 = c.render(80);
+		const editorLine1 = lines1.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine1).toContain("aaa");
+		expect(editorLine1).not.toContain("ccc");
+	});
+
+	it("C-BC4C: comment flow submits comment with answer", () => {
+		const { c, result } = make([singleQWithComment]);
+		c.handleInput(ENTER); // select A → comment mode
+		c.handleInput("my note");
+		c.handleInput(ENTER); // submit
+		expect(result.val).toBeDefined();
+		expect(result.val!.answers["Which DB? (with comment)"]).toBe("Postgres — my note");
+	});
+});
+
+// ── hint line: append-only UX hint ──
+describe("W2 — hint line", () => {
+	it("C-HINT-1: freeform editor hint contains all expected hints", () => {
+		const { c } = make([singleQ]);
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER);
+		const lines = c.render(80);
+		const hintLine = lines.find((l: string) => l.includes("move") && l.includes("Backspace deletes"));
+		expect(hintLine).toBeDefined();
+		expect(hintLine).toContain("Enter submit");
+		expect(hintLine).toContain("Esc back");
+	});
+
+	it("C-HINT-2: comment editor hint contains all expected hints", () => {
+		const { c } = make([singleQWithComment]);
+		c.handleInput(ENTER);
+		const lines = c.render(80);
+		const hintLine = lines.find((l: string) => l.includes("move") && l.includes("Backspace deletes"));
+		expect(hintLine).toBeDefined();
+		expect(hintLine).toContain("Enter submit");
+		expect(hintLine).toContain("Esc back");
+	});
+});
+
+// ── freeDraft 隔离：丢弃的 freeform 草稿不污染答案、不触发 auto-confirm ──
+describe("C-FREEDRAFT: discarded draft isolation", () => {
+	it("C-FREEDRAFT-1: discarded freeform draft blocks submit (Q1 stays unconfirmed)", () => {
+		const { c, result } = make(multiQ);
+		// Q1: 打开 freeform，输入草稿 "abc"，ESC 丢弃（存入 freeDraft，但不 confirmed）
+		c.handleInput(DOWN);  // 0→1
+		c.handleInput(DOWN);  // 1→2 (Other)
+		c.handleInput(ENTER); // 打开 freeform
+		c.handleInput("abc");
+		c.handleInput(ESC);   // freeDraft="abc"，回到 options，Q1 仍未答
+		// 跳到 Submit tab 尝试提交
+		c.handleInput(RIGHT); // → Q2
+		c.handleInput(RIGHT); // → Q3
+		c.handleInput(RIGHT); // → Submit tab
+		c.handleInput(ENTER); // allConfirmed=false → 提交被阻塞
+		expect(result.val).toBeUndefined();
+	});
+
+	it("C-FREEDRAFT-2: discarded draft does not appear in submitted answers", () => {
+		const { c, result } = make(multiQ);
+		// Q1: freeform 草稿 "abc" → ESC 丢弃 → 改选选项 A
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER); // freeform
+		c.handleInput("abc");
+		c.handleInput(ESC);   // 丢弃草稿，光标回到 Other
+		c.handleInput(UP);    // 2→1
+		c.handleInput(UP);    // 1→0 (A)
+		c.handleInput(ENTER); // 选 A → confirmed → advance Q2
+		// Q2 (multiSelect): 选 X → confirmed → advance Q3
+		c.handleInput(ENTER);
+		// Q3: 选 M → confirmed → advance Submit tab
+		c.handleInput(ENTER);
+		// Submit
+		c.handleInput(ENTER);
+		expect(result.val).toBeDefined();
+		expect(result.val!.answers["Q1"]).toBe("A");
+		// 丢弃的草稿 "abc" 不应出现在任何答案中
+		expect(JSON.stringify(result.val!.answers)).not.toContain("abc");
+	});
+});

package/src/__tests__/w3-regression.test.ts

@@ -0,0 +1,310 @@
+// src/__tests__/w3-regression.test.ts
+// W3: Forward regression + full validation (#5)
+// Comprehensive no-op key coverage + draftText edge cases + full regression.
+import { describe, expect, it } from "vitest";
+
+import { AskUserComponent } from "../component";
+import type { Question, Result } from "../types";
+import {
+	BACKSPACE,
+	DELETE,
+	DOWN,
+	END,
+	ENTER,
+	ESC,
+	F1,
+	HOME,
+	INSERT,
+	LEFT,
+	mockTui,
+	multiQ,
+	multiQWithComment,
+	PGDN,
+	PGUP,
+	RIGHT,
+	singleQ,
+	singleQWithComment,
+	stubTheme,
+} from "./fixtures";
+
+const make = (
+	questions: Question[] = [singleQ],
+): { c: AskUserComponent; result: { val: Result | null | undefined } } => {
+	const result = { val: undefined as Result | null | undefined };
+	const c = new AskUserComponent(questions, mockTui, stubTheme, (r) => (result.val = r));
+	return { c, result };
+};
+
+/** Helper: open freeform editor on singleQ (navigate to Other → Enter) */
+function openFreeform(c: AskUserComponent): void {
+	c.handleInput(DOWN); // 0→1
+	c.handleInput(DOWN); // 1→2 (Other)
+	c.handleInput(ENTER); // open freeform
+}
+
+// ── C-KEYMAP-*: extended no-op key coverage ──
+describe("W3 — extended no-op key coverage (C-KEYMAP-*)", () => {
+	it("C-KEYMAP-DOWN: down arrow is no-op in freeform editor", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("a");
+		c.handleInput(DOWN);
+		c.handleInput("b");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("ab");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+	});
+
+	it("C-KEYMAP-LEFT: left arrow moves cursor in freeform editor", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("ab");  // "ab", cursor=2
+		c.handleInput(LEFT);   // cursor 2→1
+		c.handleInput("c");   // insert at 1 → "acb", cursor=2
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		// cursor at 2: "ac█b" — 去 ANSI 后精确文本 "acb"（证明 c 插在 a 与 b 之间）
+		const stripped = editorLine!.replace(/\x1b\[[0-9;]*m/g, "");
+		expect(stripped).toContain("acb");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+	});
+
+	it("C-KEYMAP-HOME: Home key moves cursor to start in freeform editor", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("abc");  // fallback: "abc", cursor=3
+		c.handleInput(HOME);    // cursor 3→0
+		c.handleInput("d");    // insert at 0 → "dabc", cursor=1
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		// cursor at 1: "d\x1b[7ma\x1b[27mbc" — 去 ANSI 后精确文本 "dabc"（证明 d 插在开头）
+		const stripped = editorLine!.replace(/\x1b\[[0-9;]*m/g, "");
+		expect(stripped).toContain("dabc");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+		expect(editorLine).not.toContain("\x1b[H");
+	});
+
+	it("C-KEYMAP-END: End key moves cursor to end of text", () => {
+		const { c } = make();
+		openFreeform(c);
+		c.handleInput("abc");
+		c.handleInput(HOME); // 移到开头
+		c.handleInput(END);  // 移到末尾
+		// 验证在末尾输入 "d" 被追加到末尾
+		c.handleInput("d");
+		const lines = c.render(60);
+		const editorLine = lines.find((l: string) => l.includes("\x1b[7m"));
+		// 去除 ANSI 转义码后检查
+		const stripped = editorLine!.replace(/\x1b\[[0-9;]*m/g, "");
+		expect(stripped).toContain("abcd");
+	});
+
+	it("C-KEYMAP-INSERT: Insert key is no-op in freeform editor", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("a");
+		c.handleInput(INSERT);
+		c.handleInput("b");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("ab");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+		expect(editorLine).not.toContain("~");
+	});
+
+	it("C-KEYMAP-PGUP: Page Up is no-op in freeform editor", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("a");
+		c.handleInput(PGUP);
+		c.handleInput("b");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("ab");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+		expect(editorLine).not.toContain("~");
+	});
+
+	it("C-KEYMAP-PGDN: Page Down is no-op in freeform editor", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("a");
+		c.handleInput(PGDN);
+		c.handleInput("b");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("ab");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+		expect(editorLine).not.toContain("~");
+	});
+
+	it("C-KEYMAP-F1: F1 key is no-op in freeform editor", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("a");
+		c.handleInput(F1);
+		c.handleInput("b");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("ab");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+		expect(editorLine).not.toContain("\x1bO");
+	});
+
+	it("C-KEYMAP-DELETE: Delete key is no-op in freeform editor (not backspace)", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("abc");
+		c.handleInput(DELETE); // delete ≠ backspace — should NOT delete
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("abc"); // unchanged
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+		expect(editorLine).not.toContain("~");
+	});
+
+	it.each([
+		["super+up", "\x1b[1;9A"],
+		["super+down", "\x1b[1;9B"],
+		["super+left", "\x1b[1;9D"],
+		["super+right", "\x1b[1;9C"],
+		["ctrl+shift+up", "\x1b[1;6A"],
+		["ctrl+shift+down", "\x1b[1;6B"],
+	])("C-KEYMAP-MOD (extended): %s is no-op in editor", (_name, seq) => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("a");
+		c.handleInput(seq);
+		c.handleInput("b");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("ab");
+		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
+	});
+});
+
+// ── C-BC4B: freeform Enter clears selectedIndex (BC-4b regression) ──
+describe("W3 — freeform Enter clears selectedIndex (C-BC4B)", () => {
+	it("C-BC4B: freeform text overrides selected option in result", () => {
+		const { c, result } = make([singleQ]);
+		// Navigate to Other (index 2) and open freeform
+		c.handleInput(DOWN); // 0→1
+		c.handleInput(DOWN); // 1→2 (Other)
+		c.handleInput(ENTER); // open freeform
+		c.handleInput("custom answer");
+		c.handleInput(ENTER); // confirm freeform → afterConfirm → submit
+		expect(result.val).toBeDefined();
+		// The answer should be the freeform text
+		expect(result.val!.answers["Which DB?"]).toBe("custom answer");
+	});
+
+	it("C-BC4B-SELECT: freeform on same question clears selectedIndex", () => {
+		const { c, result } = make(multiQ);
+		// Q1: stay on cursorIndex=0 (A), open freeform via Other
+		c.handleInput(DOWN); // 0→1
+		c.handleInput(DOWN); // 1→2 (Other)
+		c.handleInput(ENTER); // open freeform
+		c.handleInput("override");
+		c.handleInput(ENTER); // confirm freeform → afterConfirm → advance to Q2
+		// Q2: select X
+		c.handleInput(ENTER); // select X
+		c.handleInput(ENTER); // confirm → advance to Q3
+		// Q3: select M
+		c.handleInput(ENTER); // select M
+		c.handleInput(ENTER); // confirm → advance to submit
+		// Submit
+		c.handleInput(ENTER);
+		expect(result.val).toBeDefined();
+		// Q1 answer should be the freeform text only
+		expect(result.val!.answers["Q1"]).toBe("override");
+	});
+});
+
+// ── C-BC4C-REEDIT: comment re-edit prefills old comment ──
+describe("W3 — comment re-edit prefills old comment (C-BC4C-REEDIT)", () => {
+	it("C-BC4C-REEDIT: editing comment after initial submission prefills old text", () => {
+		const { c, result } = make([singleQWithComment]);
+		// Select option A → enter comment mode
+		c.handleInput(ENTER);
+		// Type initial comment
+		c.handleInput("initial comment");
+		c.handleInput(ENTER); // submit → auto-advance → submit all
+		expect(result.val).toBeDefined();
+		expect(result.val!.answers["Which DB? (with comment)"]).toBe("Postgres — initial comment");
+	});
+
+	it("C-BC4C-CLEAR: Esc in comment mode skips comment, keeps existing commentValue", () => {
+		const { c, result } = make(multiQWithComment);
+		// Q1: select A → comment mode
+		c.handleInput(ENTER);
+		c.handleInput("my note");
+		c.handleInput(ENTER); // submit comment → advance to Q2
+		// Q2: select X
+		c.handleInput(ENTER);
+		c.handleInput(ENTER); // confirm Q2 → advance to submit tab
+		// Go back to Q1
+		c.handleInput(LEFT);
+		// Q1 is already confirmed, re-select A to trigger comment again
+		c.handleInput(ENTER); // re-select A → afterConfirm → comment mode
+		c.handleInput(ESC); // skip comment
+		// Submit
+		c.handleInput(RIGHT);
+		c.handleInput(RIGHT); // navigate to submit tab
+		c.handleInput(ENTER);
+		expect(result.val).toBeDefined();
+		// Comment should still be "my note" (Esc preserved commentValue)
+		expect(result.val!.answers["Q1"]).toBe("A — my note");
+	});
+});
+
+// ── C-PASTE-EQUIV: single char via parseKey path (not undefined path) ──
+describe("W3 — single char append via parseKey path (C-PASTE-5 equiv)", () => {
+	it("single char 'x' is appended correctly (parseKey returns 'x')", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		c.handleInput("x");
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("x");
+	});
+
+	it("single printable chars in sequence build string correctly", () => {
+		const { c } = make([singleQ]);
+		openFreeform(c);
+		for (const ch of "hello") {
+			c.handleInput(ch);
+		}
+		const lines = c.render(60);
+		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
+		expect(editorLine).toContain("hello");
+	});
+});
+
+// ── C-BKSP-EDGE: backspace at cursorIndex=0 ──
+
+describe("W3 — backspace at cursorIndex=0 (C-BKSP-EDGE)", () => {
+	it("C-BKSP-EDGE: backspace at cursorIndex=0 is no-op on empty text", () => {
+		const { c } = make();
+		// 打开 freeform 编辑器
+		openFreeform(c);
+		c.handleInput(BACKSPACE); // 空文本 + cursorIndex=0
+		// 不应 crash
+		const lines = c.render(60);
+		// 编辑器仍然可见（反色空格光标）
+		expect(lines.some((l: string) => l.includes("\x1b[7m"))).toBe(true);
+	});
+
+	it("C-BKSP-EDGE-2: backspace at cursorIndex=0 on non-empty text is no-op", () => {
+		const { c } = make();
+		openFreeform(c);
+		c.handleInput("abc");
+		c.handleInput(HOME); // 移到开头
+		c.handleInput(BACKSPACE); // cursorIndex=0，不应删除
+		const lines = c.render(60);
+		const editorLine = lines.find((l: string) => l.includes("\x1b[7m"));
+		// 文本完整保留（去除 ANSI 转义码后检查）
+		const stripped = editorLine!.replace(/\x1b\[[0-9;]*m/g, "");
+		expect(stripped).toContain("abc");
+	});
+});