@xynogen/pix-ask 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-ask",
-	"version": "0.1.5",
+	"version": "0.2.0",
 	"description": "Pi tool — structured questionnaire UI (ask_user)",
 	"type": "module",
 	"main": "src/index.ts",

package/src/frame.test.ts

@@ -0,0 +1,39 @@
+import { expect, test } from "bun:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { frameLines, modalWidth } from "./frame.js";
+
+const noColor = (s: string) => s;
+
+test("modalWidth clamps to [40, 96] with 4-col margin", () => {
+	expect(modalWidth(200)).toBe(96);
+	expect(modalWidth(50)).toBe(46);
+	expect(modalWidth(10)).toBe(40);
+});
+
+test("frameLines draws rounded border with uniform width", () => {
+	const out = frameLines({
+		width: 40,
+		lines: ["hello", "world"],
+		color: noColor,
+	});
+	const first = out[0] ?? "";
+	const last = out[out.length - 1] ?? "";
+	expect(first.startsWith("╭")).toBe(true);
+	expect(first.endsWith("╮")).toBe(true);
+	expect(last.startsWith("╰")).toBe(true);
+	expect(last.endsWith("╯")).toBe(true);
+	for (const line of out) {
+		expect(visibleWidth(line)).toBe(40);
+	}
+});
+
+test("frameLines pads ANSI-colored input by visible width", () => {
+	const out = frameLines({
+		width: 40,
+		lines: ["\x1b[31mhi\x1b[0m"],
+		color: noColor,
+	});
+	for (const line of out) {
+		expect(visibleWidth(line)).toBe(40);
+	}
+});

package/src/frame.ts

@@ -0,0 +1,49 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+const MIN_WIDTH = 40;
+const MAX_WIDTH = 96;
+const MARGIN = 4;
+// 2 border cols + 2 padding spaces
+const CHROME = 4;
+
+export function modalWidth(termWidth: number): number {
+	return Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, termWidth - MARGIN));
+}
+
+export function frameLines(opts: {
+	width: number;
+	lines: string[];
+	color: (s: string) => string;
+	bg?: (s: string) => string;
+	top?: string;
+}): string[] {
+	const { width, lines, color, top } = opts;
+	const bg = opts.bg ?? ((s: string) => s);
+	const inner = Math.max(1, width - CHROME);
+	const dashes = "─".repeat(width - 2);
+
+	// Derive the bg OPEN sequence so we can re-assert it after any full reset
+	// (\x1b[0m) or bg reset (\x1b[49m) embedded in content — theme fg/bold spans
+	// emit \x1b[0m, which would otherwise punch transparent holes in the fill.
+	const SENTINEL = "\x00";
+	const bgOpen = bg(SENTINEL).split(SENTINEL)[0] ?? "";
+	const reassert = (s: string): string =>
+		bgOpen
+			? s.replace(/\x1b\[([0-9;]*)m/g, (seq, p: string) =>
+					p === "0" || p.split(";").includes("49") ? `${seq}${bgOpen}` : seq,
+				)
+			: s;
+
+	const row = (content: string): string => {
+		const pad = inner - visibleWidth(content);
+		const padded =
+			pad > 0 ? content + " ".repeat(pad) : truncateToWidth(content, inner);
+		return bg(`${color("│")} ${reassert(padded)} ${color("│")}`);
+	};
+
+	const out: string[] = [bg(color(`╭${dashes}╮`))];
+	if (top !== undefined) out.push(row(top));
+	for (const line of lines) out.push(row(line));
+	out.push(bg(color(`╰${dashes}╯`)));
+	return out;
+}

package/src/glyphs.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { checkboxGlyphs, selectionGlyph } from "./glyphs.js";
+
+describe("selectionGlyph", () => {
+	test("multi checked → ▣ / success", () => {
+		expect(
+			selectionGlyph({ multi: true, selected: false, checked: true }),
+		).toEqual({
+			glyph: "▣",
+			color: "success",
+		});
+	});
+
+	test("multi unchecked → ☐ / dim", () => {
+		expect(
+			selectionGlyph({ multi: true, selected: true, checked: false }),
+		).toEqual({
+			glyph: "☐",
+			color: "dim",
+		});
+	});
+
+	test("radio selected → ◉ / accent", () => {
+		expect(
+			selectionGlyph({ multi: false, selected: true, checked: false }),
+		).toEqual({
+			glyph: "◉",
+			color: "accent",
+		});
+	});
+
+	test("radio unselected → ○ / dim", () => {
+		expect(
+			selectionGlyph({ multi: false, selected: false, checked: false }),
+		).toEqual({
+			glyph: "○",
+			color: "dim",
+		});
+	});
+});
+
+describe("checkboxGlyphs", () => {
+	test("checked and unchecked have equal display width", () => {
+		const { checked, unchecked } = checkboxGlyphs();
+		expect(visibleWidth(checked)).toBe(visibleWidth(unchecked));
+	});
+});

package/src/glyphs.ts

@@ -0,0 +1,36 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+const CHECKBOX_CHECKED = "▣";
+const CHECKBOX_UNCHECKED = "☐";
+const RADIO_SELECTED = "◉";
+const RADIO_UNSELECTED = "○";
+
+/** Glyph + theme color token for a selection row. Caller applies theme.fg(color, glyph). */
+export function selectionGlyph(opts: {
+	multi: boolean;
+	selected: boolean;
+	checked: boolean;
+}): { glyph: string; color: string } {
+	if (opts.multi) {
+		return opts.checked
+			? { glyph: CHECKBOX_CHECKED, color: "success" }
+			: { glyph: CHECKBOX_UNCHECKED, color: "dim" };
+	}
+	return opts.selected
+		? { glyph: RADIO_SELECTED, color: "accent" }
+		: { glyph: RADIO_UNSELECTED, color: "dim" };
+}
+
+/**
+ * Checkbox glyph pair, falling back to ASCII [x]/[ ] when the unicode squares
+ * do not measure as a single display cell (some terminals render
+ * geometric-shape codepoints as width-2, breaking column alignment).
+ */
+export function checkboxGlyphs(): { checked: string; unchecked: string } {
+	const unicodeSafe =
+		visibleWidth(CHECKBOX_CHECKED) === 1 &&
+		visibleWidth(CHECKBOX_UNCHECKED) === 1;
+	return unicodeSafe
+		? { checked: CHECKBOX_CHECKED, unchecked: CHECKBOX_UNCHECKED }
+		: { checked: "[x]", unchecked: "[ ]" };
+}

package/src/index.ts

@@ -11,7 +11,6 @@ import {
 	MAX_QUESTIONS,
 	MIN_OPTIONS,
 	ParamsSchema,
-	SENTINEL_CHAT,
 	SENTINEL_FREEFORM,
 } from "./schema.js";
 import type { QuestionAnswer, QuestionnaireResult } from "./types.js";
@@ -42,8 +41,8 @@ export default function registerAsk(pi: ExtensionAPI): void {
 			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.`,
+				`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).`,
+				`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). 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",
@@ -88,6 +87,7 @@ export default function registerAsk(pi: ExtensionAPI): void {
 						}
 						return new AskQuestionnaire(typed, tui, theme, keybindings, done);
 					},
+					{ overlay: true },
 				);
 
 				if (!result || result.cancelled) {

package/src/questionnaire.ts

@@ -13,10 +13,11 @@ import {
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 import { dim } from "./components.js";
+import { frameLines, modalWidth } from "./frame.js";
+import { checkboxGlyphs, selectionGlyph } from "./glyphs.js";
 import { safeMarkdownTheme, sentinelsFor } from "./helpers.js";
 import type { OptionData, Params, QuestionData } from "./schema.js";
 import {
-	SENTINEL_CHAT,
 	SENTINEL_FREEFORM,
 	SENTINEL_NEXT,
 	SEPARATOR,
@@ -251,11 +252,9 @@ export class AskQuestionnaire extends Container {
 	// ── Input handling ─────────────────────────────────────────────────
 
 	handleInput(data: string): void {
-		if (this.keybindings.matches(data, "tui.select.cancel")) {
-			this.cancel();
-			return;
-		}
-
+		// Input mode owns esc (back to options) — handle it BEFORE the global
+		// cancel guard, which is also bound to esc and would otherwise close the
+		// whole questionnaire instead of stepping back.
 		if (this.inputMode) {
 			if (matchesKey(data, Key.escape)) {
 				this.inputMode = false;
@@ -263,11 +262,20 @@ export class AskQuestionnaire extends Container {
 				this.refresh();
 				return;
 			}
+			if (this.keybindings.matches(data, "tui.select.cancel")) {
+				this.cancel();
+				return;
+			}
 			this.ensureEditor().handleInput(data);
 			this.tui.requestRender();
 			return;
 		}
 
+		if (this.keybindings.matches(data, "tui.select.cancel")) {
+			this.cancel();
+			return;
+		}
+
 		const isMulti = !!this.currentQ.multiSelect;
 		const total = this.totalItems;
 
@@ -389,12 +397,23 @@ export class AskQuestionnaire extends Container {
 		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", "○")
-				: "";
+		const box = checkboxGlyphs();
+		// Glyph per option: checkbox (▣/☐) for multi, radio (◉/○) for single.
+		// `sel` = cursor row; for radio the cursor row IS the chosen one.
+		const glyphFor = (optIdx: number, sel: boolean): string => {
+			const g = selectionGlyph({
+				multi: isMulti,
+				selected: sel,
+				checked: this.multiChecked.has(optIdx),
+			});
+			// width-safety fallback only affects the checkbox pair
+			const glyph = isMulti
+				? this.multiChecked.has(optIdx)
+					? box.checked
+					: box.unchecked
+				: g.glyph;
+			return t.fg(g.color as Parameters<typeof t.fg>[0], glyph);
+		};
 
 		if (total === 0) return [t.fg("warning", "No options")];
 
@@ -409,7 +428,10 @@ export class AskQuestionnaire extends Container {
 		const end = Math.min(start + maxVisible, total);
 
 		const lines: string[] = [];
-		const pad = "   ";
+		// Hang-indent descriptions under the LABEL column, not the pointer.
+		// Prefix is `→ G ` = ptr(1)+sp(1)+glyph(1)+sp(1) = 4 cols.
+		const LABEL_COL = 4;
+		const pad = " ".repeat(LABEL_COL);
 
 		for (let i = start; i < end; i++) {
 			const item = items[i]!;
@@ -418,18 +440,15 @@ export class AskQuestionnaire extends Container {
 
 			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 glyph = glyphFor(optIdx, sel);
 				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, ""),
-				);
+				lines.push(truncateToWidth(`${ptr} ${glyph} ${label}`, inner, ""));
 				if (item.option.description) {
 					const wrapped = wrapTextWithAnsi(
 						item.option.description,
-						Math.max(10, inner - 6),
+						Math.max(10, inner - LABEL_COL),
 					);
 					for (const w of wrapped) {
 						lines.push(truncateToWidth(`${pad}${t.fg("muted", w)}`, inner, ""));
@@ -488,8 +507,12 @@ export class AskQuestionnaire extends Container {
 		);
 	}
 
-	override render(width: number): string[] {
-		const inner = Math.max(20, width - 4);
+	override render(termWidth: number): string[] {
+		// Cap to a fixed-width floating modal; render content at the inner width
+		// and frame it with a rounded border (see frameLines).
+		const mw = modalWidth(termWidth);
+		const width = mw - 4; // border (2) + padding (2)
+		const inner = Math.max(20, width);
 		const t = this.theme;
 		const isMulti = !!this.currentQ.multiSelect;
 		const hasPreview =
@@ -498,15 +521,16 @@ export class AskQuestionnaire extends Container {
 			!!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 leftWidth = useSplit ? Math.floor((width - 2) * 0.45) : inner;
+		const previewWidth = useSplit ? Math.max(20, width - leftWidth - 3) : 0;
 
 		const lines: string[] = [];
 
 		const row = (content: string): string =>
-			` ${truncateToWidth(content, Math.max(0, width - 1), "")}`;
+			truncateToWidth(content, width, "");
 
-		// Tab bar
+		// Tab bar — rendered as the framed top edge (frameLines `top`).
+		let top: string | undefined;
 		if (this.params.questions.length > 1) {
 			const tabParts: string[] = [];
 			for (let i = 0; i < this.params.questions.length; i++) {
@@ -514,7 +538,7 @@ export class AskQuestionnaire extends Container {
 				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", "  "))));
+			top = truncateToWidth(tabParts.join(t.fg("dim", "  ")), width, "");
 		}
 
 		// Header chip
@@ -538,14 +562,13 @@ export class AskQuestionnaire extends Container {
 			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));
+			const editorLines = this.ensureEditor().render(width);
 			for (const el of editorLines) {
-				lines.push(` ${truncateToWidth(el, Math.max(0, width - 1), "")}`);
+				lines.push(truncateToWidth(el, width, ""));
 			}
 			lines.push("");
 			lines.push(row(dim(t)("enter submit • esc back • ctrl+c cancel")));
-			lines.push("");
-			return lines.map((l) => truncateToWidth(l, width, ""));
+			return this.frame(mw, lines, top);
 		}
 
 		// Search bar
@@ -556,34 +579,18 @@ export class AskQuestionnaire extends Container {
 			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 optionLines = this.renderOptions(useSplit ? leftWidth : width);
 		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), "")}`);
+				const left = truncateToWidth(optionLines[i] ?? "", leftWidth, "", true);
+				const right = truncateToWidth(previewLines[i] ?? "", previewWidth, "");
+				const body = `${left || " ".repeat(leftWidth)}${sep}${right || " ".repeat(previewWidth)}`;
+				lines.push(truncateToWidth(body, width, ""));
 			}
 		} else {
 			for (const line of optionLines) lines.push(row(line));
@@ -602,8 +609,23 @@ export class AskQuestionnaire extends Container {
 					"ctrl+c cancel",
 				];
 		lines.push(row(dim(t)(hintParts.join(" • "))));
-		lines.push("");
 
-		return lines.map((l) => truncateToWidth(l, width, ""));
+		return this.frame(mw, lines, top);
+	}
+
+	/** Wrap body lines in the rounded modal border at the given outer width. */
+	private frame(
+		outerWidth: number,
+		lines: string[],
+		top: string | undefined,
+	): string[] {
+		const t = this.theme;
+		return frameLines({
+			width: outerWidth,
+			lines,
+			top,
+			color: (s) => t.fg("accent", s),
+			bg: (s) => t.bg("customMessageBg", s),
+		});
 	}
 }

package/src/schema.ts

@@ -45,7 +45,7 @@ export const QuestionSchema = Type.Object({
 		minItems: MIN_OPTIONS,
 		maxItems: MAX_OPTIONS,
 		description:
-			"2-4 options. 'Type something.' and 'Chat about this' are auto-appended.",
+			"2-4 options. 'Type something.' is auto-appended for single-select.",
 	}),
 	multiSelect: Type.Optional(
 		Type.Boolean({