@zhushanwen/pi-ask-user 0.0.4 → 0.1.0

package/src/component.ts

@@ -1,14 +1,16 @@
 // src/component.ts
-import { type Component, matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
+import { type Component, matchesKey, parseKey, truncateToWidth } from "@mariozechner/pi-tui";
 
 import { allOptions, renderQuestionView } from "./question-view";
-import { buildResult, renderSubmitView } from "./submit-view";
+import { buildResult, renderButtonBar, renderSubmitView } from "./submit-view";
 import {
 	createQuestionState,
 	HEADER_MAX_CHARS,
+	isHighSurrogate,
 	type Question,
 	type QuestionState,
 	type Result,
+	SURROGATE_PAIR_LEN,
 	type ThemeLike,
 } from "./types";
 
@@ -32,7 +34,6 @@ export class AskUserComponent implements Component {
 
 	private states: QuestionState[];
 	private activeTab: number = 0;
-	private editorText: string = "";
 
 	/** Submit tab 上的左右焦点：默认 Submit；← / → 切换；Enter 触发当前项。
 	 *  问题 tab 上无意义（仅视觉占位），不参与输入路由。 */
@@ -107,7 +108,7 @@ export class AskUserComponent implements Component {
 		} else {
 			const q = this.questions[this.activeTab]!;
 			const state = this.states[this.activeTab]!;
-			for (const line of renderQuestionView(q, state, t, innerWidth, this.isSingle, this.editorText)) {
+			for (const line of renderQuestionView(q, state, t, innerWidth, this.isSingle, state.draftText)) {
 				add(line);
 			}
 		}
@@ -115,7 +116,7 @@ export class AskUserComponent implements Component {
 		// 多问题：底部按钮栏（Submit / Cancel）。Submit tab 上不重复渲染（renderSubmitView 内嵌 focus 高亮）
 		if (!this.isSingle && this.activeTab < this.questions.length) {
 			inner.push("");
-			this.renderButtonBar(innerWidth, add, null);
+			add(renderButtonBar(this.theme, this.allConfirmed(), null));
 		}
 
 		// 用 box 边框包裹：每行 pad 到 innerWidth 后加 │ 左右边框
@@ -162,28 +163,6 @@ export class AskUserComponent implements Component {
 		add(truncateToWidth(parts.join(""), innerWidth));
 	}
 
-	/**
-	 * 底部按钮栏：[ Submit ]   [ Cancel ]。
-	 * focus: null=纯展示（问题 tab），"submit"/"cancel"=高亮对应按钮（Submit tab）。
-	 */
-	private renderButtonBar(
-		innerWidth: number,
-		add: (s: string) => void,
-		focus: "submit" | "cancel" | null,
-	): void {
-		const t = this.theme;
-		const allDone = this.allConfirmed();
-		const isSubmit = focus === "submit";
-		const isCancel = focus === "cancel";
-		const submit = isSubmit
-			? (allDone ? t.fg("success", t.bold(" Submit ")) : t.fg("accent", t.bold(" Submit ")))
-			: (allDone ? t.fg("success", " Submit ") : t.fg("dim", " Submit "));
-		const cancel = isCancel
-			? t.fg("accent", t.bold(" Cancel "))
-			: t.fg("muted", " Cancel ");
-		add(`${t.fg("dim", "[")}${submit}${t.fg("dim", "]")}   ${t.fg("dim", "[")}${cancel}${t.fg("dim", "]")}`);
-	}
-
 	// ── 输入路由 ──
 	handleInput(data: string): void {
 		if (this._resolved) return;
@@ -215,15 +194,22 @@ export class AskUserComponent implements Component {
 			return;
 		}
 
+		// options mode → delegate to handleOptionsInput
+		this.handleOptionsInput(data, state, q);
+	}
+
+	/**
+	 * options 模式的输入处理（从 handleInput 拆出）。
+	 * 含：Esc 回退/确认取消、←/→ 切 tab、↑/↓ 移光标、Enter 确认、Space toggle。
+	 */
+	private handleOptionsInput(data: string, state: QuestionState, q: Question): void {
 		// Esc → 回退到上一个问题；在首个问题时进入确认取消覆盖层
 		if (matchesKey(data, "escape")) {
 			this.escBackOrConfirm();
 			return;
 		}
 
-		// ← / → 切换问题 tab（多问题，options 模式）：末尾 → 进入 Submit tab，
-		// 首个 ← 停在首个问题（不环绕）。Tab/Shift+Tab 不在问题 tab 切 tab——
-		// 留给 Submit tab 上的 Submit/Cancel 焦点切换。
+		// ← / → 切换问题 tab（多问题，options 模式）
 		if (!this.isSingle && matchesKey(data, "right")) {
 			this.gotoTab(Math.min(this.activeTab + 1, this.questions.length));
 			return;
@@ -250,12 +236,12 @@ export class AskUserComponent implements Component {
 		const opts = allOptions(q);
 		const onOther = state.cursorIndex === opts.length - 1;
 
-		// Other row → Enter opens freeform editor（单选/多选统一入口）。
-		//   单选/多选普通选项的 Enter 各自有不同语义（确认/加入选中），与 Other 互斥：
-		//   onOther 时本分支先消费 Enter，下面多选/单选分支不再处理。
+		// Other row → Enter opens freeform editor
 		if (onOther && matchesKey(data, "enter")) {
+			state.savedOptionsCursorIndex = state.cursorIndex;
 			state.mode = "freeform";
-			this.editorText = state.freeTextValue ?? "";
+			state.draftText = state.freeTextValue ?? state.freeDraft ?? "";
+			state.cursorIndex = state.draftText.length;
 			this.invalidate();
 			this.tui.requestRender();
 			return;
@@ -267,10 +253,6 @@ export class AskUserComponent implements Component {
 				return;
 			}
 			if (matchesKey(data, "enter")) {
-				// Enter 先把光标所在的普通选项加入选中再确认，与单选分支（Enter 时
-				// selectedIndex = cursorIndex）保持一致。即使 freeTextValue 已存在
-				// （Other 录入），也尊重「在此选项上按 Enter 想选中它」的意图，避免
-				// 静默用旧 Other 文本确认。add 幂等，不会误取消已选项。
 				state.selectedIndices.add(state.cursorIndex);
 				this.afterConfirm(state, q);
 				return;
@@ -330,80 +312,157 @@ export class AskUserComponent implements Component {
 	}
 
 	private handleEditorInput(data: string, state: QuestionState, q: Question): void {
+		// parseKey 白名单拦截 — 替代旧的 matchesKey 散调 + 兜底 printable 遍历
+		const keyId = parseKey(data);
+		if (keyId !== undefined) {
+			this.handleEditorKey(data, keyId, state, q);
+			return;
+		}
+		this.handleEditorPaste(data, state);
+	}
+
+	/** parseKey 命中的键：escape/enter/backspace/光标移动/space/printable 各有语义，
+	 *  其他 special key（功能键/modifier 组合）no-op。 */
+	private handleEditorKey(data: string, keyId: string, state: QuestionState, q: Question): void {
 		if (matchesKey(data, "escape")) {
-			if (state.mode === "comment") {
-				// AC-17: Esc in comment = skip comment, advance (keep existing commentValue)
-				state.mode = "options";
-				this.editorText = "";
-				this.advance();
-				return;
-			}
-			// Esc in freeform editor = back to options (discard input)
-			state.mode = "options";
-			this.editorText = "";
-			this.invalidate();
-			this.tui.requestRender();
+			this.handleEditorEsc(state);
 			return;
 		}
 		if (matchesKey(data, "enter")) {
-			const text = this.editorText.trim();
-			if (state.mode === "freeform") {
-				if (text) {
-					state.freeTextValue = text;
-					state.selectedIndex = null;
-					state.mode = "options";
-					this.editorText = "";
-					// freeform 保存后走 afterConfirm（可能进 comment 模式）
-					this.afterConfirm(state, q);
-				} else {
-					// FR-6: 空 Enter 仅清除 freeTextValue、关闭编辑器回选项列表，不含确认语义（不置 confirmed）
-					state.freeTextValue = null;
-					state.mode = "options";
-					this.editorText = "";
-					// 对齐 toggleIndex 守卫：清空后若全无答案，重置 confirmed，维持 confirmed ⟹ 有答案 不变式
-					if ((q.multiSelect ? state.selectedIndices.size === 0 : state.selectedIndex === null) && state.freeTextValue === null) {
-						state.confirmed = false;
-					}
-					this.invalidate();
-					this.tui.requestRender();
-				}
-				return;
-			}
-			// comment mode：保存评论后直接前进（不再回头进 comment）
-			state.commentValue = text || null;
+			this.handleEditorEnter(state, q);
+			return;
+		}
+		if (matchesKey(data, "backspace")) {
+			this.deleteCharBeforeCursor(state);
+			return;
+		}
+		if (this.moveCursor(data, state)) return;
+		// 空格特判：parseKey(" ") 返回 "space"（非单字符），需显式插入
+		if (matchesKey(data, "space")) {
+			this.insertAtCursor(state, " ");
+			return;
+		}
+		// 单字符 printable：parseKey("a") 返回 "a"（code 32-126），在光标处插入
+		if (keyId.length === 1 && keyId >= " " && keyId <= "~") {
+			this.insertAtCursor(state, keyId);
+			return;
+		}
+		// 其他 special key（功能键/modifier 组合）→ no-op（不泄漏）
+	}
+
+	/** Esc：comment 跳过评论并 advance；freeform 存 freeDraft 草稿后回 options。 */
+	private handleEditorEsc(state: QuestionState): void {
+		if (state.mode === "comment") {
+			// comment Esc: skip comment, advance (keep existing commentValue)
 			state.mode = "options";
-			this.editorText = "";
+			state.draftText = "";
+			state.cursorIndex = state.savedOptionsCursorIndex;
 			this.advance();
 			return;
 		}
-		if (matchesKey(data, "backspace")) {
-			this.editorText = this.editorText.slice(0, -1);
-			this.invalidate();
-			this.tui.requestRender();
+		// freeform Esc: save draft to freeDraft (separate from submitted freeTextValue)
+		// so discarded drafts don't pollute the answer or trigger auto-confirm.
+		state.freeDraft = state.draftText || null;
+		state.mode = "options";
+		state.draftText = "";
+		state.cursorIndex = state.savedOptionsCursorIndex;
+		this.invalidate();
+		this.tui.requestRender();
+	}
+
+	/** Enter：freeform 有文本→提交，空文本→回退；comment→保存评论并 advance。 */
+	private handleEditorEnter(state: QuestionState, q: Question): void {
+		const text = state.draftText.trim();
+		if (state.mode === "freeform") {
+			state.cursorIndex = state.savedOptionsCursorIndex;
+			if (text) {
+				state.freeTextValue = text;
+				state.selectedIndex = null;
+				state.mode = "options";
+				state.draftText = "";
+				this.afterConfirm(state, q);
+			} else {
+				state.freeTextValue = null;
+				state.mode = "options";
+				state.draftText = "";
+				// freeTextValue 刚清空；confirmed 仅在无其他选择时置 false（允许重新作答）
+				if (q.multiSelect ? state.selectedIndices.size === 0 : state.selectedIndex === null) {
+					state.confirmed = false;
+				}
+				this.invalidate();
+				this.tui.requestRender();
+			}
+			return;
+		}
+		state.commentValue = text || null;
+		state.mode = "options";
+		state.draftText = "";
+		state.cursorIndex = state.savedOptionsCursorIndex;
+		this.advance();
+	}
+
+	/** 在光标处插入文本，光标前移 text.length。 */
+	private insertAtCursor(state: QuestionState, text: string): void {
+		state.draftText = state.draftText.slice(0, state.cursorIndex) + text + state.draftText.slice(state.cursorIndex);
+		state.cursorIndex += text.length;
+		this.invalidate();
+		this.tui.requestRender();
+	}
+
+	/** 删除光标前一个 code point（surrogate pair 时删整个 code point）。 */
+	private deleteCharBeforeCursor(state: QuestionState): void {
+		if (state.cursorIndex <= 0) return;
+		const deleteCount = state.cursorIndex >= SURROGATE_PAIR_LEN && isHighSurrogate(state.draftText, state.cursorIndex - SURROGATE_PAIR_LEN) ? SURROGATE_PAIR_LEN : 1;
+		state.draftText = state.draftText.slice(0, state.cursorIndex - deleteCount) + state.draftText.slice(state.cursorIndex);
+		state.cursorIndex -= deleteCount;
+		this.invalidate();
+		this.tui.requestRender();
+	}
+
+	/** 光标移动（left/right/home/end），surrogate pair 安全跳过代理中间位。
+	 *  返回 true 表示命中了移动键；false 表示非移动键，交由上层处理。 */
+	private moveCursor(data: string, state: QuestionState): boolean {
+		if (matchesKey(data, "left")) {
+			const newLeft = state.cursorIndex - 1;
+			state.cursorIndex = newLeft > 0 && isHighSurrogate(state.draftText, newLeft - 1)
+				? newLeft - 1
+				: Math.max(0, newLeft);
+		} else if (matchesKey(data, "right")) {
+			state.cursorIndex = isHighSurrogate(state.draftText, state.cursorIndex)
+				? Math.min(state.draftText.length, state.cursorIndex + SURROGATE_PAIR_LEN)
+				: Math.min(state.draftText.length, state.cursorIndex + 1);
+		} else if (matchesKey(data, "home")) {
+			state.cursorIndex = 0;
+		} else if (matchesKey(data, "end")) {
+			state.cursorIndex = state.draftText.length;
+		} else {
+			return false;
+		}
+		this.invalidate();
+		this.tui.requestRender();
+		return true;
+	}
+
+	/** 多字符粘贴 chunk → printable 提取（BC-1/BC-2/BC-3 保持）。
+	 *  未识别控制序列（OSC/DA/DCS/APC/unknown CSI）整体丢弃，不提取可见残渣。
+	 *  排除 bracketed paste 标记防 C-PASTE 退化。依赖 StdinBuffer 序列拆分保证 data 整体性。 */
+	private handleEditorPaste(data: string, state: QuestionState): void {
+		if (data.startsWith("\x1b") && !data.includes("\x1b[200~") && !data.includes("\x1b[201~")) {
 			return;
 		}
-		// Printable char(s) — handle both single keystrokes and multi-char paste.
-		// Terminals deliver pasted text as a single data chunk; iterating each char
-		// ensures the full paste is captured instead of silently dropping everything
-		// after the first character.
-		// 先剥离 bracketed paste 标记序列：启用该模式的终端会把粘贴内容包裹在
-		// \x1b[200~ ... \x1b[201~ 中。下面的 `c >= " "` 守卫会滤掉 ESC(\x1b)，
-		// 但序列里的可见字符（[200~/[201~）会残留混进编辑器文本，必须显式剥离。
 		const cleaned = data.replace(/\x1b\[200~|\x1b\[201~/g, "");
-		// for...of 按 code point 迭代：代理对（如 😀 U+1F600）作为一个 c（length===2）出现，
-		// 因此不能用 `c.length === 1` 守卫——那会把所有 BMP 之外的字符（emoji、部分 CJK 扩展）全过滤。
-		// 只保留 `c >= " "`（code point 比较），过滤控制字符（< 空格 U+0020）。
 		let changed = false;
-		for (const c of cleaned) {
+		// 用 Array.from 正确拆分 emoji/surrogate pairs
+		for (const c of Array.from(cleaned)) {
 			if (c >= " ") {
-				this.editorText += c;
+				state.draftText = state.draftText.slice(0, state.cursorIndex) + c + state.draftText.slice(state.cursorIndex);
+				state.cursorIndex += c.length;
 				changed = true;
 			}
 		}
 		if (changed) {
 			this.invalidate();
 			this.tui.requestRender();
-			return;
 		}
 	}
 
@@ -452,10 +511,10 @@ export class AskUserComponent implements Component {
 	private afterConfirm(state: QuestionState, q: Question): void {
 		state.confirmed = true;
 		if (q.allowComment && state.mode !== "comment") {
-			// 进入评论输入行。预填已有评论，空 Enter=清除、新文本=覆盖（FR-4 item6）。
-			// 允许回改时重新编辑/清除已输入评论，避免评论被错误附着到后改的答案。
+			state.savedOptionsCursorIndex = state.cursorIndex;
 			state.mode = "comment";
-			this.editorText = state.commentValue ?? "";
+			state.draftText = state.commentValue ?? "";
+			state.cursorIndex = state.draftText.length;
 			this.invalidate();
 			this.tui.requestRender();
 			return;
@@ -482,8 +541,11 @@ export class AskUserComponent implements Component {
 		this.done(buildResult(this.questions, this.states));
 	}
 
-	/** 取消。public 供 signal abort 监听器复用 _resolved 守卫（FR-12 竞态） */
+	/** 取消。public 供 signal abort 监听器复用 _resolved 守卫（FR-12 竞态）。
+	 *  守卫在方法内：signal abort 可能在用户已 submit/cancel 后才触发，
+	 *  此时必须 no-op，避免二次调 done（FR-12）。 */
 	cancel(): void {
+		if (this._resolved) return;
 		this._resolved = true;
 		this.done(null);
 	}

package/src/index.ts

@@ -1,5 +1,5 @@
 // src/index.ts
-import type { AgentToolResult, ExtensionAPI, ExtensionContext, ToolRenderResultOptions } from "@mariozechner/pi-coding-agent";
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, ToolRenderResultOptions } from "@mariozechner/pi-coding-agent";
 import { Box, Text, TruncatedText, truncateToWidth } from "@mariozechner/pi-tui";
 import { type Static } from "@sinclair/typebox";
 
@@ -76,7 +76,7 @@ If you recommend an option, prefix its label with "(Recommended)" and list it fi
 			_toolCallId: string,
 			params: Static<typeof InputSchema>,
 			signal: AbortSignal | undefined,
-			_onUpdate: unknown,
+			_onUpdate: AgentToolUpdateCallback<AskUserDetails> | undefined,
 			ctx: ExtensionContext,
 		): Promise<ExecuteResult> {
 			const questions = params.questions;
@@ -111,13 +111,15 @@ If you recommend an option, prefix its label with "(Recommended)" and list it fi
 				};
 			}
 
-			// 3. Signal abort 入口检查（spec FR-10）
+			// 3. Signal abort 入口检查（spec FR-10）。
+			// abort 是 agent 被外部终止（goal 取消 / context compact / session 切换），
+			// 不是用户意图——文案必须区别于 step 5 的用户取消，避免 LLM 俊等用户。
 			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.",
+							text: "Agent aborted (goal cancelled, context compacted, or session switched). Do not assume an answer; do not retry ask_user — propagate the abort, or wait for new instructions if the decision is still required.",
 						},
 					],
 					details: { questions, answers: {}, cancelled: true } satisfies Result,

package/src/question-view.ts

@@ -2,6 +2,7 @@
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
 
 import {
+	isHighSurrogate,
 	OTHER_LABEL,
 	type Question,
 	type QuestionState,
@@ -9,9 +10,16 @@ import {
 	SPLIT_PANE_MIN_WIDTH,
 	SPLIT_PANE_RIGHT_MIN,
 	SPLIT_PANE_SEPARATOR,
+	SURROGATE_PAIR_LEN,
 	type ThemeLike,
 } from "./types";
 
+const SPLIT_PANE_LEFT_RATIO = 0.42;
+const DESCRIPTION_INDENT_MULTI = 10;
+const DESCRIPTION_INDENT_SINGLE = 8;
+const PREVIEW_MIN_WIDTH = 10;
+const QUESTION_TEXT_MARGIN = 2;
+
 export interface DisplayOption {
 	label: string;
 	description?: string;
@@ -21,6 +29,21 @@ export interface DisplayOption {
 /** Other 自由输入 / 已保存预览的软换行行数上限。超出则截断并加省略号。 */
 const MAX_EDITOR_LINES = 5;
 
+/**
+ * 渲染编辑器文本，光标位置用反色高亮（ANSI SGR 7/27），不占额外列。
+ * surrogate pair 安全：光标在高代理前时反色高亮整个 code point（2 个 code unit），
+ * 与光标移动/Backspace 的跳过逻辑对称，避免拆散 emoji 导致终端显示替换字符。
+ * 光标在文本末尾（超出范围）时反色高亮一个空格占位。
+ */
+function renderCursorText(text: string, cursorPos: number): string {
+	const before = text.slice(0, cursorPos);
+	// 光标在高代理前 → 反色高亮整个 surrogate pair
+	const charLen = isHighSurrogate(text, cursorPos) ? SURROGATE_PAIR_LEN : 1;
+	const charAtCursor = text.slice(cursorPos, cursorPos + charLen) || " ";
+	const after = text.slice(cursorPos + charLen);
+	return `${before}\x1b[7m${charAtCursor}\x1b[27m${after}`;
+}
+
 /**
  * 把一段带样式的文本按 availWidth 软换行输出为多行，最多 maxLines 行。
  * - 首行前缀 lead（如 "> [ ] "），后续行用等宽空格缩进到 input 起始列对齐。
@@ -29,7 +52,7 @@ const MAX_EDITOR_LINES = 5;
  *
  * @param push      输出回调（通常为带 truncateToWidth 的 add，提供安全兜底）
  * @param lead      首行前缀（含选中标记 / 勾选框）
- * @param content   待换行展示的已样式化文本（可含 ANSI + 末尾光标 █），为空则只输出 lead
+ * @param content   待换行展示的已样式化文本（可含 ANSI + 末尾反色光标），为空则只输出 lead
  * @param availWidth 单行可用宽度
  * @param maxLines  最多行数
  */
@@ -71,7 +94,7 @@ export function getSplitPaneWidths(width: number): { left: number; right: number
 	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 preferredLeft = Math.floor(available * SPLIT_PANE_LEFT_RATIO);
 	const left = Math.max(
 		SPLIT_PANE_LEFT_MIN,
 		Math.min(preferredLeft, available - SPLIT_PANE_RIGHT_MIN),
@@ -81,8 +104,12 @@ export function getSplitPaneWidths(width: number): { left: number; right: number
 	return { left, right };
 }
 
+/** 编辑器底部操作提示：随实现能力更新（实现偏差 D-005 已支持光标移动）。
+ *  反色光标占位已暗示可输入，故突出新增的方向键/移动能力。 */
+const EDITOR_HINT = " ←/→ Home/End move · Backspace deletes · Enter submit · Esc back";
+
 /** 构建选项列表行（不含分屏预览）。hideDescriptions 用于分屏模式左列。
- *  freeform 模式下，Other 行**原地**变 [ ] <input>█（多选）/ <input>█（单选），
+ *  freeform 模式下，Other 行**原地**变 [ ] <input> 反色光标（多选）/ <input> 反色光标（单选），
  *  不再依赖 buildEditorBlock 的下方独立编辑块。 */
 function buildOptionLines(
 	q: Question,
@@ -90,7 +117,7 @@ function buildOptionLines(
 	theme: ThemeLike,
 	width: number,
 	hideDescriptions: boolean,
-	editorText: string = "",
+	draftText: string = "",
 ): string[] {
 	const t = theme;
 	const opts = allOptions(q);
@@ -101,7 +128,9 @@ function buildOptionLines(
 
 	for (let i = 0; i < opts.length; i++) {
 		const opt = opts[i]!;
-		const isSelected = i === state.cursorIndex;
+		// 编辑器模式下用 savedOptionsCursorIndex 判断选项高亮，cursorIndex 此时是文本光标
+		const activeOptionCursor = (state.mode === "freeform" || state.mode === "comment") ? state.savedOptionsCursorIndex : state.cursorIndex;
+		const isSelected = i === activeOptionCursor;
 		const isOther = opt.isOther === true;
 		const prefix = isSelected ? t.fg("accent", ">") : " ";
 
@@ -115,15 +144,16 @@ function buildOptionLines(
 				const num = i + 1;
 				const lead = `${prefix} ${marker} `;
 				const avail = Math.max(1, width - visibleWidth(lead));
-				// 编号 + 文本 + 末尾光标 █ 整体软换行（空 input 时仅编号 + 光标，wrapTextWithAnsi 单行）
-				const styled = `${t.fg("muted", `${num}. `)}${t.fg("text", editorText)}${t.fg("accent", "█")}`;
+				// 编号 + 文本，光标用反色高亮当前字符（surrogate pair 安全，不占额外位置）
+				const cursorText = renderCursorText(draftText, state.cursorIndex);
+				const styled = `${t.fg("muted", `${num}. `)}${t.fg("text", cursorText)}`;
 				addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
 			} else {
 				const hasFreeText = state.freeTextValue !== null;
 				const marker = q.multiSelect
 					? (hasFreeText ? t.fg("success", "[✓]") : t.fg("dim", "[ ]"))
 					: (hasFreeText ? t.fg("success", "✓") : " ");
-				const labelColor = isSelected ? "accent" : "muted";
+				const labelColor = isSelected ? "accent" : "text";
 				const num = i + 1;
 				add(`${prefix} ${marker} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
 				if (hasFreeText) {
@@ -145,7 +175,7 @@ function buildOptionLines(
 			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 - 10);
+				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_MULTI);
 				for (const line of wrapped) add(`          ${line}`);
 			}
 		} else {
@@ -155,7 +185,7 @@ function buildOptionLines(
 			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 - 8);
+				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_SINGLE);
 				for (const line of wrapped) add(`        ${line}`);
 			}
 		}
@@ -184,19 +214,14 @@ function buildPreviewLines(
 		if (opt.description?.trim()) text += `\n\n${opt.description}`;
 	}
 
-	const wrapped = wrapTextWithAnsi(t.fg("muted", text), Math.max(10, width));
+	const wrapped = wrapTextWithAnsi(t.fg("muted", text), Math.max(PREVIEW_MIN_WIDTH, 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>█ 行），
+ * freeform 模式：editor 已在 buildOptionLines 中原地渲染（[ ] <input> 反色光标 行），
  * buildEditorBlock 在此模式下不重复输出，**仅留出与正常 help 行同位置的视觉空隙**。
  * comment 模式：保留独立编辑块（与 normal help 行解耦：comment 行有更长的 prompt）。
  */
@@ -204,7 +229,8 @@ function buildEditorBlock(
 	theme: ThemeLike,
 	width: number,
 	mode: "freeform" | "comment",
-	editorText: string,
+	draftText: string,
+	cursorIndex?: number,
 ): string[] {
 	if (mode === "freeform") {
 		return [""];
@@ -217,12 +243,12 @@ function buildEditorBlock(
 	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", "█")}`);
+	// 渲染当前编辑器文本，光标用反色高亮当前字符（surrogate pair 安全）
+	const pos = cursorIndex ?? draftText.length;
+	const cursorText = renderCursorText(draftText, pos);
+	add(` ${t.fg("text", cursorText)}`);
 	add("");
-	add(t.fg("dim", " Enter submit · Esc back"));
+	add(t.fg("dim", EDITOR_HINT));
 	return lines;
 }
 
@@ -233,14 +259,14 @@ function buildSplitPane(
 	theme: ThemeLike,
 	split: { left: number; right: number },
 	width: number,
-	editorText: string = "",
+	draftText: 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 leftLines = buildOptionLines(q, state, theme, split.left, true, draftText);
 	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);
@@ -252,13 +278,18 @@ function buildSplitPane(
 	return lines;
 }
 
+/**
+ * 渲染单个问题视图（spec FR-4）。
+ * isSingle: 单问题模式（无 Tab 提示）。
+ * draftText: freeform/comment 模式下当前编辑器草稿（来自 QuestionState.draftText）。
+ */
 export function renderQuestionView(
 	q: Question,
 	state: QuestionState,
 	theme: ThemeLike,
 	width: number,
 	isSingle: boolean,
-	editorText: string,
+	draftText: string,
 ): string[] {
 	const t = theme;
 	const lines: string[] = [];
@@ -268,13 +299,13 @@ export function renderQuestionView(
 	const divider = (): void => add(t.fg("dim", "─".repeat(Math.max(0, width))));
 
 	// 问题文本（word-wrap）
-	const wrapped = wrapTextWithAnsi(t.fg("text", ` ${q.question}`), width - 2);
+	const wrapped = wrapTextWithAnsi(t.fg("text", ` ${q.question}`), width - QUESTION_TEXT_MARGIN);
 	for (const line of wrapped) add(line);
 
 	// 上下文（如有）
 	if (q.context?.trim()) {
 		divider();
-		const ctxWrapped = wrapTextWithAnsi(t.fg("muted", q.context), width - 2);
+		const ctxWrapped = wrapTextWithAnsi(t.fg("muted", q.context), width - QUESTION_TEXT_MARGIN);
 		for (const line of ctxWrapped) add(line);
 	}
 
@@ -292,24 +323,24 @@ export function renderQuestionView(
 	// 且右侧详情预览在输入自定义内容时无意义。隐藏 descriptions 以避免行数爆炸。
 	if (state.mode === "freeform" || state.mode === "comment") {
 		add("");
-		const optionLines = buildOptionLines(q, state, theme, width, false, editorText);
+		const optionLines = buildOptionLines(q, state, theme, width, false, draftText);
 		for (const line of optionLines) add(line);
-		const editorBlock = buildEditorBlock(theme, width, state.mode, editorText);
+		const editorBlock = buildEditorBlock(theme, width, state.mode, draftText, state.cursorIndex);
 		lines.push(...editorBlock);
 		if (state.mode === "freeform") {
 			// freeform 模式 help 行：光标锁在 Other 上，正在输入
-			add(t.fg("dim", " Enter submit · Esc back"));
+			add(t.fg("dim", EDITOR_HINT));
 		}
 		return lines;
 	}
 
 	if (!split) {
 		// 单列模式
-		const optionLines = buildOptionLines(q, state, theme, width, false, editorText);
+		const optionLines = buildOptionLines(q, state, theme, width, false, draftText);
 		for (const line of optionLines) add(line);
 	} else {
 		// 分屏模式
-		lines.push(...buildSplitPane(q, state, theme, split, width, editorText));
+		lines.push(...buildSplitPane(q, state, theme, split, width, draftText));
 	}
 
 	add("");