@xynogen/pix-ask 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@xynogen/pix-ask",
+	"version": "0.1.0",
+	"description": "Pi tool — structured questionnaire UI (ask_user)",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"src/index.ts"
+		]
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"ask"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-ask"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"typebox": "^1.1.38"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}

package/src/ask.test.ts

@@ -0,0 +1,243 @@
+/**
+ * ask.test.ts — tests for the ask questionnaire tool
+ *
+ * Tests cover pure functions (schema validation, sentinel logic, answer
+ * formatting). TUI components are not tested here.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+	buildResponseText,
+	formatAnswerScalar,
+	hasAnyPreview,
+	type OptionData,
+	type QuestionData,
+	sentinelsFor,
+} from "./index.ts";
+
+// ── Fixtures ──────────────────────────────────────────────────────────
+
+const opt = (
+	label: string,
+	description = "Test option",
+	preview?: string,
+): OptionData => ({
+	label,
+	description,
+	...(preview ? { preview } : {}),
+});
+
+const qSingle: QuestionData = {
+	question: "Which approach?",
+	header: "Approach",
+	options: [
+		opt("REST", "Traditional REST API"),
+		opt("GraphQL", "Query language for APIs"),
+	],
+};
+
+const qMulti: QuestionData = {
+	question: "Which features?",
+	header: "Features",
+	options: [
+		opt("Auth", "User authentication"),
+		opt("Search", "Full text search"),
+		opt("Export", "Data export"),
+	],
+	multiSelect: true,
+};
+
+const qWithPreview: QuestionData = {
+	question: "Pick a component?",
+	header: "Component",
+	options: [
+		opt("Button", "Clickable button", "<Button>Primary</Button>"),
+		opt("Card", "Container card", "<Card><Content/></Card>"),
+	],
+};
+
+const qSingleNoPreview: QuestionData = {
+	question: "Color?",
+	header: "Color",
+	options: [opt("Red", "Ruby red"), opt("Blue", "Ocean blue")],
+};
+
+// ── hasAnyPreview ─────────────────────────────────────────────────────
+
+describe("hasAnyPreview", () => {
+	test("returns false when no option has preview", () => {
+		expect(hasAnyPreview(qSingle)).toBe(false);
+		expect(hasAnyPreview(qMulti)).toBe(false);
+	});
+
+	test("returns true when at least one option has preview", () => {
+		expect(hasAnyPreview(qWithPreview)).toBe(true);
+	});
+
+	test("returns false for empty options", () => {
+		const q: QuestionData = { question: "?", header: "X", options: [] };
+		expect(hasAnyPreview(q)).toBe(false);
+	});
+});
+
+// ── sentinelsFor ──────────────────────────────────────────────────────
+
+describe("sentinelsFor", () => {
+	test('single-select without preview appends "Type something."', () => {
+		const r = sentinelsFor(qSingleNoPreview);
+		expect(r).toHaveLength(1);
+		expect(r[0]?.kind).toBe("other");
+		expect(r[0]?.label).toBe("Type something.");
+	});
+
+	test('single-select with preview appends nothing (only "Chat about this" is separate)', () => {
+		const r = sentinelsFor(qWithPreview);
+		expect(r).toHaveLength(0);
+	});
+
+	test('multi-select appends "Next"', () => {
+		const r = sentinelsFor(qMulti);
+		expect(r).toHaveLength(1);
+		expect(r[0]?.kind).toBe("next");
+		expect(r[0]?.label).toBe("Next");
+	});
+
+	test("multi-select never appends Type something.", () => {
+		const r = sentinelsFor({ ...qMulti, multiSelect: true });
+		expect(r.every((s) => s.kind !== "other")).toBe(true);
+	});
+
+	test("empty options still gets freeform sentinel (no preview = single-select)", () => {
+		const r = sentinelsFor({ question: "?", header: "X", options: [] });
+		expect(r).toHaveLength(1);
+		expect(r[0]?.kind).toBe("other");
+	});
+});
+
+// ── formatAnswerScalar ────────────────────────────────────────────────
+
+describe("formatAnswerScalar", () => {
+	test("option kind returns the answer string", () => {
+		const a = {
+			questionIndex: 0,
+			question: "Q",
+			kind: "option" as const,
+			answer: "REST",
+		};
+		expect(formatAnswerScalar(a)).toBe("REST");
+	});
+
+	test("multi kind joins selected with comma", () => {
+		const a = {
+			questionIndex: 0,
+			question: "Q",
+			kind: "multi" as const,
+			answer: null,
+			selected: ["Auth", "Search"],
+		};
+		expect(formatAnswerScalar(a)).toBe("Auth, Search");
+	});
+
+	test("custom kind returns the typed text", () => {
+		const a = {
+			questionIndex: 0,
+			question: "Q",
+			kind: "custom" as const,
+			answer: "my custom answer",
+		};
+		expect(formatAnswerScalar(a)).toBe("my custom answer");
+	});
+
+	test("chat kind returns (chat)", () => {
+		const a = {
+			questionIndex: 0,
+			question: "Q",
+			kind: "chat" as const,
+			answer: null,
+		};
+		expect(formatAnswerScalar(a)).toBe("(chat)");
+	});
+});
+
+// ── buildResponseText ─────────────────────────────────────────────────
+
+describe("buildResponseText", () => {
+	test("formats single answer", () => {
+		const answers = [
+			{
+				questionIndex: 0,
+				question: "Which approach?",
+				kind: "option" as const,
+				answer: "REST",
+			},
+		];
+		const text = buildResponseText(answers, [qSingle]);
+		expect(text).toContain("REST");
+		expect(text).toContain("Which approach?");
+	});
+
+	test("formats multi-select answer", () => {
+		const answers = [
+			{
+				questionIndex: 0,
+				question: "Which features?",
+				kind: "multi" as const,
+				answer: null,
+				selected: ["Auth", "Search"],
+			},
+		];
+		const text = buildResponseText(answers, [qMulti]);
+		expect(text).toContain("Auth, Search");
+		expect(text).toContain("Which features?");
+	});
+
+	test("includes preview in response when present", () => {
+		const answers = [
+			{
+				questionIndex: 0,
+				question: "Pick a component?",
+				kind: "option" as const,
+				answer: "Button",
+				preview: "<Button>Primary</Button>",
+			},
+		];
+		const text = buildResponseText(answers, [qWithPreview]);
+		expect(text).toContain("preview: <Button>Primary</Button>");
+	});
+
+	test("formats multiple answers", () => {
+		const qs = [qSingle, qMulti];
+		const answers = [
+			{
+				questionIndex: 0,
+				question: "Which approach?",
+				kind: "option" as const,
+				answer: "GraphQL",
+			},
+			{
+				questionIndex: 1,
+				question: "Which features?",
+				kind: "multi" as const,
+				answer: null,
+				selected: ["Export"],
+			},
+		];
+		const text = buildResponseText(answers, qs);
+		expect(text).toContain("GraphQL");
+		expect(text).toContain("Export");
+	});
+
+	test("shows declined message when no answers", () => {
+		const text = buildResponseText([], [qSingle]);
+		expect(text).toContain("declined");
+	});
+});
+
+// ── Tool registration shape ─────────────────────────────────────────
+
+describe("registerAsk", () => {
+	test("exports a default function", async () => {
+		const mod = await import("./index.ts");
+		expect(typeof mod.default).toBe("function");
+	});
+});

package/src/components.ts

@@ -0,0 +1,55 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
+import type { QuestionData } from "./schema.js";
+
+// ── Color helpers ──────────────────────────────────────────────────────
+
+export function borderColor(theme: Theme): (s: string) => string {
+	return (s: string) => theme.fg("accent", s);
+}
+
+export function dim(theme: Theme): (s: string) => string {
+	return (s: string) => theme.fg("dim", s);
+}
+
+// ── TabBar ─────────────────────────────────────────────────────────────
+
+export class TabBar implements Component {
+	private questions: QuestionData[];
+	private activeIndex: number;
+	private theme: Theme;
+
+	constructor(questions: QuestionData[], activeIndex: number, theme: Theme) {
+		this.questions = questions;
+		this.activeIndex = activeIndex;
+		this.theme = theme;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const t = this.theme;
+		const inner = Math.max(10, width - 2);
+
+		const parts: string[] = [];
+		for (let i = 0; i < this.questions.length; i++) {
+			const active = i === this.activeIndex;
+			const num = `${i + 1}`;
+			const tag = `${num}.${this.questions[i]?.header}`;
+			parts.push(active ? t.fg("accent", t.bold(tag)) : t.fg("dim", tag));
+		}
+		const line = parts.join(t.fg("dim", "  "));
+		return [
+			truncateToWidth(
+				t.fg("accent", "╭─") +
+					line +
+					t.fg(
+						"accent",
+						`${"─".repeat(Math.max(0, inner - line.length - 1))}╮`,
+					),
+				width,
+				"",
+			),
+		].filter(Boolean);
+	}
+}

package/src/helpers.ts

@@ -0,0 +1,77 @@
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import type { MarkdownTheme } from "@earendil-works/pi-tui";
+import type { OptionData, QuestionData } from "./schema.js";
+import { SENTINEL_CHAT, SENTINEL_FREEFORM, SENTINEL_NEXT } from "./schema.js";
+import type { AnswerKind, QuestionAnswer } from "./types.js";
+
+// ── Markdown theme ─────────────────────────────────────────────────────
+
+export function safeMarkdownTheme(): MarkdownTheme | undefined {
+	try {
+		const md = getMarkdownTheme();
+		if (!md) return undefined;
+		md.bold("");
+		return md;
+	} catch {
+		return undefined;
+	}
+}
+
+// ── Option / question helpers ──────────────────────────────────────────
+
+export function hasAnyPreview(q: QuestionData): boolean {
+	return q.options.some(
+		(o) => typeof o.preview === "string" && o.preview.length > 0,
+	);
+}
+
+/** Which sentinel rows are auto-appended for a question. */
+export function sentinelsFor(
+	q: QuestionData,
+): Array<{ kind: string; label: string }> {
+	const out: Array<{ kind: string; label: string }> = [];
+	if (q.multiSelect) {
+		out.push({ kind: "next", label: SENTINEL_NEXT });
+	} else if (!hasAnyPreview(q)) {
+		out.push({ kind: "other", label: SENTINEL_FREEFORM });
+	}
+	return out;
+}
+
+// ── Answer formatting ──────────────────────────────────────────────────
+
+export function formatAnswerScalar(a: QuestionAnswer): string {
+	if (a.kind === "multi") return (a.selected ?? []).join(", ");
+	if (a.kind === "custom") return a.answer ?? "(custom)";
+	if (a.kind === "chat") return "(chat)";
+	return a.answer ?? "(selected)";
+}
+
+export function buildResponseText(
+	answers: QuestionAnswer[],
+	questions: QuestionData[],
+): string {
+	const segs: string[] = [];
+	for (const a of answers) {
+		const q = questions[a.questionIndex]?.question ?? `Q${a.questionIndex + 1}`;
+		let s = `"${q}"="${formatAnswerScalar(a)}"`;
+		if (a.preview) s += `. selected preview: ${a.preview}`;
+		segs.push(s);
+	}
+	return segs.length
+		? `User answered: ${segs.join(". ")}.`
+		: "User declined to answer questions.";
+}
+
+// ── Scroll indicator ───────────────────────────────────────────────────
+
+export function scrollIndicator(index: number, total: number): string {
+	if (total <= 1) return "";
+	const pos = Math.round((index / (total - 1)) * 6);
+	const bar = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦"][pos] ?? "·";
+	return ` ${bar} ${index + 1}/${total}`;
+}
+
+export type { AnswerKind, OptionData, QuestionData };
+// Re-export sentinel constants so callers don't need to import schema directly
+export { SENTINEL_CHAT, SENTINEL_FREEFORM, SENTINEL_NEXT };

package/src/index.ts

@@ -0,0 +1,130 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { buildResponseText } from "./helpers.js";
+import { AskQuestionnaire } from "./questionnaire.js";
+import { rpcFallback } from "./rpc.js";
+import type { Params } from "./schema.js";
+import {
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	ParamsSchema,
+	SENTINEL_CHAT,
+	SENTINEL_FREEFORM,
+} from "./schema.js";
+import type { QuestionAnswer, QuestionnaireResult } from "./types.js";
+
+// ── Re-exports (consumed by tests and single-select-layout) ───────────
+
+export {
+	buildResponseText,
+	formatAnswerScalar,
+	hasAnyPreview,
+	sentinelsFor,
+} from "./helpers.js";
+export type { OptionData, QuestionData } from "./schema.js";
+export type {
+	AnswerKind,
+	QuestionAnswer,
+	QuestionnaireResult,
+} from "./types.js";
+
+// ── Tool registration ──────────────────────────────────────────────────
+
+export default function registerAsk(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "ask_user",
+		label: "Ask",
+		description: `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous.`,
+		promptSnippet: `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`,
+		promptGuidelines: [
+			`Use ask whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,
+			`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer ("${SENTINEL_FREEFORM}" row is appended automatically to single-select questions) or pick "${SENTINEL_CHAT}" to abandon the questionnaire.`,
+			`Set multiSelect: true when multiple answers are valid; this suppresses the "${SENTINEL_FREEFORM}" row. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. NOTE: any non-empty preview on a single-select question ALSO suppresses the "${SENTINEL_FREEFORM}" row (no room in the side-by-side layout); "${SENTINEL_CHAT}" remains the escape hatch. If you recommend a specific option, make it the first option and append "(Recommended)" to its label.`,
+			"Do not stack multiple ask calls back-to-back — group all clarifying questions into one invocation.",
+		],
+		executionMode: "sequential",
+		parameters: ParamsSchema,
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			if (signal?.aborted) {
+				return {
+					content: [{ type: "text", text: "Cancelled" }],
+					details: { answers: [], cancelled: true },
+				};
+			}
+
+			const typed = params as unknown as Params;
+
+			if (!Array.isArray(typed.questions) || typed.questions.length === 0) {
+				return {
+					content: [
+						{ type: "text", text: "At least one question is required." },
+					],
+					isError: true,
+					details: { answers: [], cancelled: true },
+				};
+			}
+
+			if (!ctx.hasUI) {
+				const result = await rpcFallback(ctx.ui, typed);
+				const text = result.cancelled
+					? "User cancelled the questionnaire"
+					: buildResponseText(result.answers, typed.questions);
+				return { content: [{ type: "text", text }], details: result };
+			}
+
+			const result = await ctx.ui.custom<QuestionnaireResult | null>(
+				(tui, theme, keybindings, done) => {
+					if (signal) {
+						signal.addEventListener(
+							"abort",
+							() => done({ answers: [], cancelled: true }),
+							{ once: true },
+						);
+					}
+					return new AskQuestionnaire(typed, tui, theme, keybindings, done);
+				},
+			);
+
+			if (!result || result.cancelled) {
+				return {
+					content: [{ type: "text", text: "User cancelled the questionnaire" }],
+					details: result ?? { answers: [], cancelled: true },
+				};
+			}
+
+			const text = buildResponseText(result.answers, typed.questions);
+			return { content: [{ type: "text", text }], details: result };
+		},
+
+		renderCall(args, theme) {
+			const questions = Array.isArray(args.questions) ? args.questions : [];
+			const count = questions.length;
+			const firstQ = (questions[0]?.question ?? "") as string;
+			let text = theme.fg("toolTitle", theme.bold(`ask (${count}) `));
+			text += theme.fg("muted", firstQ);
+			if (count > 1) text += theme.fg("dim", ` +${count - 1} more`);
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, options, theme) {
+			const details = result.details as
+				| { answers?: QuestionAnswer[]; cancelled?: boolean }
+				| undefined;
+			if (options.isPartial) {
+				return new Text(theme.fg("muted", "Waiting for user input..."), 0, 0);
+			}
+			if (!details || details.cancelled || !details.answers?.length) {
+				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			}
+			const texts = details.answers.map((a) => {
+				const v =
+					a.kind === "multi" ? (a.selected ?? []).join(", ") : (a.answer ?? "");
+				return `${a.questionIndex + 1}: ${v}`;
+			});
+			return new Text(theme.fg("success", `✓ ${texts.join(" • ")}`), 0, 0);
+		},
+	});
+}

package/src/questionnaire.ts

@@ -0,0 +1,609 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	decodeKittyPrintable,
+	Editor,
+	fuzzyFilter,
+	Key,
+	type KeybindingsManager,
+	Markdown,
+	matchesKey,
+	type TUI,
+	truncateToWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import { dim } from "./components.js";
+import { safeMarkdownTheme, sentinelsFor } from "./helpers.js";
+import type { OptionData, Params, QuestionData } from "./schema.js";
+import {
+	SENTINEL_CHAT,
+	SENTINEL_FREEFORM,
+	SENTINEL_NEXT,
+	SEPARATOR,
+	SPLIT_PANE_MIN_WIDTH,
+} from "./schema.js";
+import type {
+	AnswerKind,
+	QuestionAnswer,
+	QuestionnaireResult,
+} from "./types.js";
+
+// ── AskQuestionnaire ───────────────────────────────────────────────────
+
+export class AskQuestionnaire extends Container {
+	private params: Params;
+	private tui: TUI;
+	private theme: Theme;
+	private keybindings: KeybindingsManager;
+	private onDone: (result: QuestionnaireResult | null) => void;
+
+	private currentIndex = 0;
+	private answers: QuestionAnswer[] = [];
+	private searchQuery = "";
+	private selectedOptionIndex = 0;
+	private multiChecked = new Set<number>();
+	private inputMode = false;
+	private editor?: Editor;
+	private mdTheme = safeMarkdownTheme();
+
+	constructor(
+		params: Params,
+		tui: TUI,
+		theme: Theme,
+		keybindings: KeybindingsManager,
+		onDone: (result: QuestionnaireResult | null) => void,
+	) {
+		super();
+		this.params = params;
+		this.tui = tui;
+		this.theme = theme;
+		this.keybindings = keybindings;
+		this.onDone = onDone;
+	}
+
+	// ── Accessors ──────────────────────────────────────────────────────
+
+	private get currentQ(): QuestionData {
+		return this.params.questions[this.currentIndex]!;
+	}
+
+	private get filteredOptions(): OptionData[] {
+		if (!this.searchQuery) return this.currentQ.options;
+		return fuzzyFilter(
+			this.currentQ.options,
+			this.searchQuery,
+			(o) => `${o.label} ${o.description}`,
+		);
+	}
+
+	private get mainListItems(): Array<{
+		kind: string;
+		label?: string;
+		option?: OptionData;
+	}> {
+		const items: Array<{ kind: string; label?: string; option?: OptionData }> =
+			[];
+		for (const o of this.filteredOptions) {
+			items.push({ kind: "option", option: o });
+		}
+		for (const s of sentinelsFor(this.currentQ)) {
+			items.push({ kind: s.kind, label: s.label });
+		}
+		return items;
+	}
+
+	private get totalItems(): number {
+		return this.mainListItems.length;
+	}
+
+	private get selectedItem(): (typeof this.mainListItems)[0] | undefined {
+		return this.mainListItems[this.selectedOptionIndex];
+	}
+
+	// ── Layout ─────────────────────────────────────────────────────────
+
+	private ensureEditor(): Editor {
+		if (this.editor) return this.editor;
+		const editor = new Editor(this.tui, {
+			borderColor: (s: string) => this.theme.fg("accent", s),
+			selectList: {
+				selectedPrefix: (s: string) => this.theme.fg("accent", s),
+				selectedText: (s: string) => this.theme.fg("accent", s),
+				description: (s: string) => this.theme.fg("muted", s),
+				scrollInfo: (s: string) => this.theme.fg("dim", s),
+				noMatch: (s: string) => this.theme.fg("warning", s),
+			},
+		});
+		editor.disableSubmit = false;
+		editor.onSubmit = (text: string) => this.handleFreeformSubmit(text);
+		editor.focused = true;
+		this.editor = editor;
+		return editor;
+	}
+
+	private refresh(): void {
+		this.invalidate();
+		this.tui.requestRender();
+	}
+
+	// ── Answer management ──────────────────────────────────────────────
+
+	private recordAnswer(
+		kind: AnswerKind,
+		answer: string | null,
+		selected?: string[],
+		preview?: string,
+	): void {
+		this.answers = this.answers.filter(
+			(a) => a.questionIndex !== this.currentIndex,
+		);
+		this.answers.push({
+			questionIndex: this.currentIndex,
+			question: this.currentQ.question,
+			kind,
+			answer,
+			selected,
+			preview,
+		});
+	}
+
+	private commitAnswer(): void {
+		const item = this.selectedItem;
+		if (!item) {
+			this.cancel();
+			return;
+		}
+
+		if (item.kind === "option" && item.option) {
+			this.recordAnswer(
+				"option",
+				item.option.label,
+				undefined,
+				item.option.preview,
+			);
+			this.nextQuestion();
+		} else if (item.kind === "other") {
+			this.inputMode = true;
+			this.ensureEditor().focused = true;
+			this.refresh();
+		} else if (item.kind === "next") {
+			const selected = Array.from(this.multiChecked)
+				.sort((a, b) => a - b)
+				.map((i) => this.currentQ.options[i]?.label);
+			if (selected.length === 0) {
+				this.cancel();
+				return;
+			}
+			this.recordAnswer("multi", null, selected);
+			this.nextQuestion();
+		}
+	}
+
+	private handleFreeformSubmit(text: string): void {
+		if (!text.trim()) {
+			this.cancel();
+			return;
+		}
+		this.recordAnswer("custom", text.trim());
+		this.nextQuestion();
+	}
+
+	private gotoQuestion(index: number): void {
+		if (index < 0 || index >= this.params.questions.length) return;
+		this.currentIndex = index;
+		this.searchQuery = "";
+		this.multiChecked.clear();
+		this.inputMode = false;
+		this.selectedOptionIndex = 0;
+		this.editor = undefined;
+		this.restoreAnswerState();
+		this.refresh();
+	}
+
+	private restoreAnswerState(): void {
+		const prev = this.answers.find(
+			(a) => a.questionIndex === this.currentIndex,
+		);
+		if (!prev) return;
+		const q = this.currentQ;
+		if (prev.kind === "multi") {
+			for (let i = 0; i < q.options.length; i++) {
+				if (prev.selected?.includes(q.options[i]!.label)) {
+					this.multiChecked.add(i);
+				}
+			}
+		} else if (prev.kind === "option" && prev.answer) {
+			const idx = this.mainListItems.findIndex(
+				(it) => it.kind === "option" && it.option?.label === prev.answer,
+			);
+			if (idx >= 0) this.selectedOptionIndex = idx;
+		} else if (prev.kind === "custom") {
+			const idx = this.mainListItems.findIndex((it) => it.kind === "other");
+			if (idx >= 0) this.selectedOptionIndex = idx;
+		}
+	}
+
+	private nextQuestion(): void {
+		const total = this.params.questions.length;
+		const answered = new Set(this.answers.map((a) => a.questionIndex));
+		for (let step = 1; step <= total; step++) {
+			const idx = (this.currentIndex + step) % total;
+			if (!answered.has(idx)) {
+				this.gotoQuestion(idx);
+				return;
+			}
+		}
+		this.answers.sort((a, b) => a.questionIndex - b.questionIndex);
+		this.onDone({ answers: this.answers, cancelled: false });
+	}
+
+	private cancel(): void {
+		this.onDone({ answers: this.answers, cancelled: true });
+	}
+
+	private toggleMulti(index: number): void {
+		if (index < 0 || index >= this.currentQ.options.length) return;
+		if (this.multiChecked.has(index)) this.multiChecked.delete(index);
+		else this.multiChecked.add(index);
+		this.invalidate();
+	}
+
+	// ── Input handling ─────────────────────────────────────────────────
+
+	handleInput(data: string): void {
+		if (this.keybindings.matches(data, "tui.select.cancel")) {
+			this.cancel();
+			return;
+		}
+
+		if (this.inputMode) {
+			if (matchesKey(data, Key.escape)) {
+				this.inputMode = false;
+				this.editor = undefined;
+				this.refresh();
+				return;
+			}
+			this.ensureEditor().handleInput(data);
+			this.tui.requestRender();
+			return;
+		}
+
+		const isMulti = !!this.currentQ.multiSelect;
+		const total = this.totalItems;
+
+		if (
+			this.keybindings.matches(data, "tui.select.up") ||
+			matchesKey(data, Key.shift("tab")) ||
+			matchesKey(data, Key.ctrl("k"))
+		) {
+			if (total > 0) {
+				this.selectedOptionIndex =
+					(this.selectedOptionIndex - 1 + total) % total;
+				this.refresh();
+			}
+			return;
+		}
+
+		if (
+			this.keybindings.matches(data, "tui.select.down") ||
+			matchesKey(data, Key.tab) ||
+			matchesKey(data, Key.ctrl("j"))
+		) {
+			if (total > 0) {
+				this.selectedOptionIndex = (this.selectedOptionIndex + 1) % total;
+				this.refresh();
+			}
+			return;
+		}
+
+		if (matchesKey(data, Key.left)) {
+			this.gotoQuestion(this.currentIndex - 1);
+			return;
+		}
+		if (matchesKey(data, Key.right)) {
+			this.gotoQuestion(this.currentIndex + 1);
+			return;
+		}
+
+		if (
+			this.keybindings.matches(data, "tui.editor.deleteCharBackward") ||
+			matchesKey(data, Key.backspace)
+		) {
+			if (this.searchQuery) {
+				const chars = [...this.searchQuery];
+				chars.pop();
+				this.searchQuery = chars.join("");
+				this.selectedOptionIndex = 0;
+				this.refresh();
+			}
+			return;
+		}
+
+		if (matchesKey(data, Key.escape)) {
+			if (this.searchQuery) {
+				this.searchQuery = "";
+				this.selectedOptionIndex = 0;
+				this.refresh();
+			}
+			return;
+		}
+
+		if (matchesKey(data, Key.space) && isMulti) {
+			if (this.selectedItem?.kind === "option" && this.selectedItem.option) {
+				const idx = this.filteredOptions.indexOf(this.selectedItem.option);
+				if (idx >= 0) this.toggleMulti(idx);
+				this.refresh();
+			}
+			return;
+		}
+
+		const numMatch = data.match(/^[1-9]$/);
+		if (numMatch && this.filteredOptions.length > 0) {
+			const idx = Number(numMatch[0]) - 1;
+			if (idx >= 0 && idx < this.filteredOptions.length) {
+				if (isMulti) {
+					this.toggleMulti(idx);
+					this.selectedOptionIndex = Math.min(idx, this.totalItems - 1);
+					this.refresh();
+				} else {
+					const opt = this.filteredOptions[idx]!;
+					this.recordAnswer("option", opt.label, undefined, opt.preview);
+					this.nextQuestion();
+				}
+				return;
+			}
+		}
+
+		if (this.keybindings.matches(data, "tui.select.confirm")) {
+			this.commitAnswer();
+			return;
+		}
+
+		if (!isMulti) {
+			const printable = decodeKittyPrintable(data);
+			if (printable !== undefined) {
+				this.searchQuery += printable;
+				this.selectedOptionIndex = 0;
+				this.refresh();
+				return;
+			}
+			const chars = [...data];
+			if (
+				chars.length === 1 &&
+				chars[0] &&
+				chars[0].charCodeAt(0) >= 32 &&
+				chars[0].charCodeAt(0) < 127
+			) {
+				this.searchQuery += chars[0];
+				this.selectedOptionIndex = 0;
+				this.refresh();
+			}
+		}
+	}
+
+	// ── Rendering ──────────────────────────────────────────────────────
+
+	private renderOptions(width: number): string[] {
+		const t = this.theme;
+		const inner = Math.max(20, width - 6);
+		const isMulti = !!this.currentQ.multiSelect;
+		const items = this.mainListItems;
+		const total = items.length;
+		const chk = (i: number) =>
+			isMulti
+				? this.multiChecked.has(i)
+					? t.fg("success", "✓")
+					: t.fg("dim", "○")
+				: "";
+
+		if (total === 0) return [t.fg("warning", "No options")];
+
+		const maxVisible = Math.min(total, 12);
+		const start = Math.max(
+			0,
+			Math.min(
+				this.selectedOptionIndex - Math.floor(maxVisible / 2),
+				total - maxVisible,
+			),
+		);
+		const end = Math.min(start + maxVisible, total);
+
+		const lines: string[] = [];
+		const pad = "   ";
+
+		for (let i = start; i < end; i++) {
+			const item = items[i]!;
+			const sel = i === this.selectedOptionIndex;
+			const ptr = sel ? t.fg("accent", "→") : " ";
+
+			if (item.kind === "option" && item.option) {
+				const optIdx = this.filteredOptions.indexOf(item.option);
+				const checkbox = isMulti ? ` ${chk(optIdx)}` : "";
+				const num = t.fg("dim", `${optIdx + 1}.`);
+				const label = sel
+					? t.fg("accent", t.bold(item.option.label))
+					: t.fg("text", t.bold(item.option.label));
+				lines.push(
+					truncateToWidth(`${ptr} ${num}${checkbox} ${label}`, inner, ""),
+				);
+				if (item.option.description) {
+					const wrapped = wrapTextWithAnsi(
+						item.option.description,
+						Math.max(10, inner - 6),
+					);
+					for (const w of wrapped) {
+						lines.push(truncateToWidth(`${pad}${t.fg("muted", w)}`, inner, ""));
+					}
+				}
+			} else if (item.kind === "other") {
+				const label = sel
+					? t.fg("accent", t.bold(SENTINEL_FREEFORM))
+					: t.fg("text", t.bold(SENTINEL_FREEFORM));
+				lines.push(
+					truncateToWidth(`${ptr} ${t.fg("dim", "✎")} ${label}`, inner, ""),
+				);
+			} else if (item.kind === "next") {
+				const label = sel
+					? t.fg("accent", t.bold(SENTINEL_NEXT))
+					: t.fg("text", t.bold(SENTINEL_NEXT));
+				lines.push(
+					truncateToWidth(`${ptr} ${t.fg("dim", "→")} ${label}`, inner, ""),
+				);
+			}
+		}
+
+		if (start > 0 || end < total) {
+			const count =
+				this.filteredOptions.length > 0
+					? `${this.selectedOptionIndex + 1}/${total}`
+					: `${total}`;
+			lines.push(t.fg("dim", truncateToWidth(`  ${count}`, inner, "")));
+		}
+
+		return lines;
+	}
+
+	private renderPreview(width: number): string[] {
+		const item = this.selectedItem;
+		if (item?.kind !== "option" || !item.option?.preview) {
+			return [this.theme.fg("dim", "No preview")];
+		}
+
+		const mdText = item.option.preview;
+		const mdWidth = Math.max(10, width);
+
+		if (this.mdTheme) {
+			const md = new Markdown(
+				`## ${item.option.label}\n\n${mdText}`,
+				0,
+				0,
+				this.mdTheme,
+			);
+			return md.render(mdWidth);
+		}
+
+		const lines = wrapTextWithAnsi(mdText, mdWidth);
+		return lines.map((l) =>
+			truncateToWidth(this.theme.fg("muted", l), mdWidth, ""),
+		);
+	}
+
+	override render(width: number): string[] {
+		const inner = Math.max(20, width - 4);
+		const t = this.theme;
+		const isMulti = !!this.currentQ.multiSelect;
+		const hasPreview =
+			!isMulti &&
+			this.selectedItem?.kind === "option" &&
+			!!this.selectedItem?.option?.preview;
+
+		const useSplit = hasPreview && width >= SPLIT_PANE_MIN_WIDTH;
+		const leftWidth = useSplit ? Math.floor((width - 6) * 0.45) : inner;
+		const previewWidth = useSplit ? Math.max(20, width - leftWidth - 10) : 0;
+
+		const lines: string[] = [];
+
+		const row = (content: string): string =>
+			` ${truncateToWidth(content, Math.max(0, width - 1), "")}`;
+
+		// Tab bar
+		if (this.params.questions.length > 1) {
+			const tabParts: string[] = [];
+			for (let i = 0; i < this.params.questions.length; i++) {
+				const active = i === this.currentIndex;
+				const tag = `${i + 1}.${this.params.questions[i]?.header}`;
+				tabParts.push(active ? t.fg("accent", t.bold(tag)) : t.fg("dim", tag));
+			}
+			lines.push(row(tabParts.join(t.fg("dim", "  "))));
+		}
+
+		// Header chip
+		const chip = t.fg("accent", t.bold(this.currentQ.header));
+		const prog =
+			this.params.questions.length > 1
+				? dim(t)(` ${this.currentIndex + 1}/${this.params.questions.length}`)
+				: "";
+		lines.push(row(`${chip}${prog}`));
+
+		// Question text
+		for (const w of wrapTextWithAnsi(
+			this.currentQ.question,
+			Math.max(10, inner),
+		)) {
+			lines.push(row(t.fg("text", t.bold(w))));
+		}
+
+		// Input mode
+		if (this.inputMode) {
+			lines.push("");
+			lines.push(row(t.fg("accent", t.bold("Type your response:"))));
+			lines.push("");
+			const editorLines = this.ensureEditor().render(Math.max(0, width - 1));
+			for (const el of editorLines) {
+				lines.push(` ${truncateToWidth(el, Math.max(0, width - 1), "")}`);
+			}
+			lines.push("");
+			lines.push(row(dim(t)("enter submit • esc back • ctrl+c cancel")));
+			lines.push("");
+			return lines.map((l) => truncateToWidth(l, width, ""));
+		}
+
+		// Search bar
+		if (!isMulti) {
+			const searchVal = this.searchQuery
+				? t.fg("text", this.searchQuery)
+				: t.fg("dim", "type to filter");
+			lines.push(row(`${t.fg("accent", "Filter:")} ${searchVal}`));
+		}
+
+		// Chat sentinel
+		const chatLabel =
+			this.selectedOptionIndex === -999
+				? t.fg("accent", t.bold(SENTINEL_CHAT))
+				: t.fg("dim", SENTINEL_CHAT);
+		lines.push(row(`  ${t.fg("dim", "💬")} ${chatLabel}`));
+
+		// Options (with optional split-pane preview)
+		const optionLines = this.renderOptions(useSplit ? leftWidth : width - 4);
+		const previewLines = useSplit ? this.renderPreview(previewWidth) : [];
+		const maxOptLines = Math.max(optionLines.length, previewLines.length);
+
+		if (useSplit) {
+			const sep = t.fg("dim", SEPARATOR);
+			for (let i = 0; i < maxOptLines; i++) {
+				const left = truncateToWidth(
+					optionLines[i] ?? "",
+					leftWidth - 1,
+					"",
+					true,
+				);
+				const right = truncateToWidth(
+					previewLines[i] ?? "",
+					previewWidth - 2,
+					"",
+				);
+				const body = `${left || " ".repeat(leftWidth - 1)}${sep}${right || " ".repeat(previewWidth - 2)}`;
+				lines.push(` ${truncateToWidth(body, Math.max(0, width - 1), "")}`);
+			}
+		} else {
+			for (const line of optionLines) lines.push(row(line));
+		}
+
+		// Footer hints
+		const navHint =
+			this.params.questions.length > 1 ? "↑↓ nav • ←→ question" : "↑↓ nav";
+		const hintParts = isMulti
+			? [
+					`${navHint} • space toggle • enter commit • esc clear`,
+					"ctrl+c cancel",
+				]
+			: [
+					`${navHint} • type filter • enter select • esc clear`,
+					"ctrl+c cancel",
+				];
+		lines.push(row(dim(t)(hintParts.join(" • "))));
+		lines.push("");
+
+		return lines.map((l) => truncateToWidth(l, width, ""));
+	}
+}

package/src/rpc.ts

@@ -0,0 +1,84 @@
+import type { Params } from "./schema.js";
+import { SENTINEL_FREEFORM } from "./schema.js";
+import type { QuestionAnswer, QuestionnaireResult } from "./types.js";
+
+// ── RPC / non-TUI fallback ─────────────────────────────────────────────
+// Used when ctx.hasUI is false (headless / JSON / print mode).
+
+export async function rpcFallback(
+	ui: { select: Function; input: Function },
+	params: Params,
+): Promise<QuestionnaireResult> {
+	const answers: QuestionAnswer[] = [];
+	let cancelled = false;
+
+	for (let i = 0; i < params.questions.length; i++) {
+		const q = params.questions[i]!;
+		const header = q.header;
+
+		if (q.multiSelect) {
+			const lines = q.options.map(
+				(o, idx) => `${idx + 1}. ${o.label} — ${o.description}`,
+			);
+			const raw = await ui.input(
+				`${header}: ${q.question}\n\n${lines.join("\n")}\n\nEnter numbers separated by commas:`,
+				"e.g. 1,3",
+			);
+			if (raw == null) {
+				cancelled = true;
+				break;
+			}
+			const indices = String(raw)
+				.split(",")
+				.map((s) => Number(s.trim()))
+				.filter((n) => n >= 1 && n <= q.options.length);
+			const selected = indices.map((n) => q.options[n - 1]?.label);
+			if (selected.length > 0) {
+				answers.push({
+					questionIndex: i,
+					question: q.question,
+					kind: "multi",
+					answer: null,
+					selected,
+				});
+			} else {
+				cancelled = true;
+				break;
+			}
+		} else {
+			const items = q.options.map((o) => `${o.label} — ${o.description}`);
+			items.push(SENTINEL_FREEFORM);
+			const chosen = await ui.select(`${header}: ${q.question}`, items);
+			if (chosen == null) {
+				cancelled = true;
+				break;
+			}
+			if (chosen === SENTINEL_FREEFORM) {
+				const text = await ui.input(q.question, "Type your answer...");
+				if (text == null) {
+					cancelled = true;
+					break;
+				}
+				answers.push({
+					questionIndex: i,
+					question: q.question,
+					kind: "custom",
+					answer: String(text),
+				});
+			} else {
+				const opt = q.options.find(
+					(o) =>
+						chosen === o.label || `${o.label} — ${o.description}` === chosen,
+				)!;
+				answers.push({
+					questionIndex: i,
+					question: q.question,
+					kind: "option",
+					answer: opt?.label ?? String(chosen),
+				});
+			}
+		}
+	}
+
+	return { answers, cancelled };
+}

package/src/schema.ts

@@ -0,0 +1,69 @@
+import { type Static, Type } from "typebox";
+
+// ── Constants ──────────────────────────────────────────────────────────
+
+export const MAX_QUESTIONS = 4;
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 4;
+export const MAX_HEADER_LENGTH = 16;
+export const MAX_LABEL_LENGTH = 60;
+
+export const SENTINEL_FREEFORM = "Type something.";
+export const SENTINEL_CHAT = "Chat about this";
+export const SENTINEL_NEXT = "Next";
+
+export const SPLIT_PANE_MIN_WIDTH = 84;
+export const SEPARATOR = " │ ";
+
+// ── Schemas ────────────────────────────────────────────────────────────
+
+export const OptionSchema = Type.Object({
+	label: Type.String({
+		maxLength: MAX_LABEL_LENGTH,
+		description: `MAX ${MAX_LABEL_LENGTH} CHARACTERS. Display text for this option. Concise (1-5 words).`,
+	}),
+	description: Type.String({
+		description: "Explanation of what this option means or trade-offs.",
+	}),
+	preview: Type.Optional(
+		Type.String({
+			description:
+				"Optional markdown preview for side-by-side layout (single-select only).",
+		}),
+	),
+});
+
+export const QuestionSchema = Type.Object({
+	question: Type.String({
+		description: "Clear, specific question ending with ?",
+	}),
+	header: Type.String({
+		maxLength: MAX_HEADER_LENGTH,
+		description: `MAX ${MAX_HEADER_LENGTH} CHARS — short chip/tag. E.g. "Auth method", "Approach".`,
+	}),
+	options: Type.Array(OptionSchema, {
+		minItems: MIN_OPTIONS,
+		maxItems: MAX_OPTIONS,
+		description:
+			"2-4 options. 'Type something.' and 'Chat about this' are auto-appended.",
+	}),
+	multiSelect: Type.Optional(
+		Type.Boolean({
+			default: false,
+			description:
+				"Allow multiple selections. Suppresses 'Type something.' row.",
+		}),
+	),
+});
+
+export const QuestionsSchema = Type.Array(QuestionSchema, {
+	minItems: 1,
+	maxItems: MAX_QUESTIONS,
+	description: "1-4 questions",
+});
+
+export const ParamsSchema = Type.Object({ questions: QuestionsSchema });
+
+export type OptionData = Static<typeof OptionSchema>;
+export type QuestionData = Static<typeof QuestionSchema>;
+export type Params = Static<typeof ParamsSchema>;

package/src/types.ts

@@ -0,0 +1,17 @@
+// ── Answer & result types ──────────────────────────────────────────────
+
+export type AnswerKind = "option" | "custom" | "chat" | "multi";
+
+export interface QuestionAnswer {
+	questionIndex: number;
+	question: string;
+	kind: AnswerKind;
+	answer: string | null;
+	selected?: string[];
+	preview?: string;
+}
+
+export interface QuestionnaireResult {
+	answers: QuestionAnswer[];
+	cancelled: boolean;
+}