@hank-warren/pi-ask-user-question 0.3.0 → 0.4.0

package/README.md

@@ -4,8 +4,9 @@ A structured questionnaire the model can put to you when it would otherwise
 guess. Instead of a free-form "which do you prefer?" in chat, you get a dialog
 with numbered options, digit hotkeys, a typed-answer escape, and Tab-to-comment.
 
-> **v0.2** ships 1-4 questions per call as cycleable tabs, single-select, no
-> preview pane. See [the spec](../../docs/specs/pi-ask-user-question.md) §14.
+> **v0.3** ships 1-4 questions per call as cycleable tabs, single-select, with
+> an optional preview pane. See
+> [the spec](../../docs/specs/pi-ask-user-question.md) §14.
 
 ## Install
 
@@ -33,6 +34,15 @@ answering one jumps to the next unanswered question, and the call returns once
 every question has an answer. Cycling back and re-answering replaces that
 question's answer rather than recording a second one.
 
+## Previews
+
+An option may carry a `preview` field — markdown shown in a pane below the
+options while that option is highlighted. Use it for concrete artifacts worth
+comparing (ASCII mockups, code snippets, configuration variations), not for
+simple preference questions. The pane is stacked rather than side-by-side, and
+long previews are clipped with a `… N more lines` marker so the options always
+stay visible.
+
 **Why `n` and not `Tab` for notes?** Tab cycles questions here, matching
 `@juicesharp/rpiv-ask-user-question`. `pi-auto-permissions` approval prompts
 keep `Tab` for notes — they are single-question and have no tabs to cycle.

package/ask-user-question.ts

@@ -6,7 +6,7 @@
  * package replays cleanly. Only one of the two may be installed at a time.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import {
 	ASK_USER_BLOCKED_EVENT,
 	ASK_USER_PROMPT_EVENT,
@@ -41,6 +41,9 @@ const DESCRIPTION = `Ask the user one or more structured questions during execut
 3. Get decisions on implementation choices as you work
 4. Offer choices to the user about what direction to take
 
+Preview feature:
+Use the optional \`preview\` field on an option when presenting a concrete artifact the user needs to compare visually: an ASCII mockup, a code snippet, a diagram or configuration variation. It renders as markdown in a pane below the options while that option is highlighted. Do not use it for simple preference questions where the label and description already say enough.
+
 Usage notes:
 - The user can pick an option with the number keys, type a custom answer via the automatically appended "Type something." row, attach a note to their choice by pressing n, or press Esc to decline. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
 - If you recommend a specific option, make it the first option and add "(Recommended)" at the end of the label.
@@ -96,6 +99,9 @@ export function registerTool(pi: ExtensionAPI): void {
 						new QuestionnaireDialog({
 							session,
 							theme,
+							// Reuse pi's own markdown theme so previews match the
+							// transcript rather than inventing a second code style.
+							markdownTheme: getMarkdownTheme(),
 							done,
 							requestRender: () => tui.requestRender(),
 						}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-ask-user-question",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Structured questionnaire tool for Pi with numbered options, digit hotkeys and Tab-to-comment, composed from the shared permission-selector component.",
   "type": "module",
   "keywords": [
@@ -45,7 +45,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@hank-warren/pi-permission-selector": "^0.3.0"
+    "@hank-warren/pi-permission-selector": "^0.3.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/questionnaire.ts

@@ -28,6 +28,8 @@ export interface SelectableRow {
 	value: string;
 	label: string;
 	description?: string;
+	/** Markdown shown in the preview pane while this row is highlighted. */
+	preview?: string;
 }
 
 export class QuestionnaireSession {
@@ -109,6 +111,7 @@ export class QuestionnaireSession {
 			value: option.label,
 			label: option.label,
 			description: option.description,
+			...(option.preview ? { preview: option.preview } : {}),
 		}));
 		rows.push({ value: CUSTOM_ANSWER_VALUE, label: CUSTOM_ANSWER_LABEL });
 		return rows;
@@ -127,12 +130,17 @@ export class QuestionnaireSession {
 	recordAnswer(answer: string, opts: { custom?: boolean; notes?: string } = {}): void {
 		const question = this.current;
 		if (!question) return;
+		// A custom typed answer never carries a preview; only a chosen option can.
+		const preview = opts.custom
+			? undefined
+			: question.options.find((option) => option.label === answer)?.preview;
 		this.answers[this.index] = {
 			questionIndex: this.index,
 			question: question.question,
 			answer,
 			custom: opts.custom === true,
 			...(opts.notes ? { notes: opts.notes } : {}),
+			...(preview ? { preview } : {}),
 		};
 	}
 

package/tool/envelope.ts

@@ -23,9 +23,14 @@ export function buildToolResult(text: string, details: QuestionnaireResult): Too
 	return { content: [{ type: "text" as const, text }], details };
 }
 
-/** Format a single answer as `"question"="answer"`, with an optional note. */
+/**
+ * Format a single answer as `"question"="answer"`, with the chosen option's
+ * preview and the user's note appended when present. Order and wording match
+ * rpiv's envelope and are pinned by tests.
+ */
 export function buildAnswerSegment(a: QuestionAnswer): string {
 	const parts: string[] = [`"${a.question}"="${a.answer}"`];
+	if (a.preview && a.preview.length > 0) parts.push(`selected preview: ${a.preview}`);
 	if (a.notes && a.notes.length > 0) parts.push(`user notes: ${a.notes}`);
 	return `${parts.join(". ")}.`;
 }

package/tool/schema.ts

@@ -39,6 +39,12 @@ export const OptionSchema = Type.Object({
 		description:
 			"Explanation of what this option means or what will happen if chosen. Useful for providing context about trade-offs or implications.",
 	}),
+	preview: Type.Optional(
+		Type.String({
+			description:
+				"Optional markdown shown in a pane below the options while this option is highlighted. Use for concrete artifacts the user needs to compare: ASCII mockups, code snippets, diagram or configuration variations. Do NOT use it for simple preference questions where the label and description already say enough.",
+		}),
+	),
 });
 
 export const QuestionSchema = Type.Object({
@@ -70,6 +76,7 @@ export const QuestionParamsSchema = Type.Object({
 export interface OptionParams {
 	label: string;
 	description: string;
+	preview?: string;
 }
 
 export interface QuestionParams {
@@ -88,8 +95,10 @@ export interface QuestionAnswer {
 	question: string;
 	answer: string;
 	custom: boolean;
-	/** Trimmed Tab-to-comment note, when the user attached one. */
+	/** Trimmed note, when the user attached one. */
 	notes?: string;
+	/** Preview text of the chosen option, when it carried one. */
+	preview?: string;
 }
 
 export interface QuestionnaireResult {

package/view/dialog.ts

@@ -55,6 +55,7 @@ import {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
+import { Markdown, type MarkdownTheme } from "@earendil-works/pi-tui";
 import type { QuestionnaireSession } from "../questionnaire.ts";
 import type { QuestionnaireResult } from "../tool/schema.ts";
 
@@ -75,6 +76,12 @@ export interface DialogOptions {
 	 * the transcript show through to its right.
 	 */
 	maxWidth?: number;
+	/**
+	 * Markdown theme for the preview pane. Hosts pass pi's `getMarkdownTheme()`;
+	 * when omitted the preview renders as plain wrapped text, which keeps this
+	 * component unit-testable without constructing a 14-function theme.
+	 */
+	markdownTheme?: MarkdownTheme;
 }
 
 /** Left/right border plus one space of padding on each side. */
@@ -84,6 +91,8 @@ const FIELD_INDENT = "  ";
 /** Opens the note editor. Tab is taken by question cycling. */
 const NOTE_KEY = "n";
 const isNoteKey = isCharKey(NOTE_KEY);
+/** Maximum rows the preview pane may occupy before it is clipped. */
+const PREVIEW_MAX_ROWS = 12;
 
 /** Per-question UI state, preserved while cycling between tabs. */
 interface TabState {
@@ -232,12 +241,63 @@ export class QuestionnaireDialog {
 		}
 
 		lines.push(...tab.selector.render(inner));
+		lines.push(...this.previewLines(inner));
 		if (session.total > 1 && !tab.selector.isCommenting()) {
 			lines.push(this.style("dim", "  tab next · shift+tab prev question"));
 		}
 		return lines;
 	}
 
+	/** Preview markdown for the highlighted row, if it carries any. */
+	private currentPreview(): string | undefined {
+		const selected = this.tab.selector.getSelected();
+		if (!selected) return undefined;
+		return this.session.rows().find((row) => row.value === selected.value)?.preview;
+	}
+
+	/**
+	 * The preview pane: markdown between two rules, below the options.
+	 *
+	 * Stacked, not side-by-side. rpiv spent ~712 lines largely on making a
+	 * two-column layout behave at narrow widths; stacking needs none of it
+	 * (docs/specs/pi-ask-user-question.md §6.2).
+	 */
+	private previewLines(inner: number): string[] {
+		const preview = this.currentPreview();
+		if (!preview) return [];
+
+		const rendered = this.renderMarkdown(preview, inner);
+
+		// Cap the pane so a long preview cannot push the options off screen.
+		const clipped = rendered.slice(0, PREVIEW_MAX_ROWS);
+		if (rendered.length > PREVIEW_MAX_ROWS) {
+			clipped.push(this.style("dim", `… ${rendered.length - PREVIEW_MAX_ROWS} more lines`));
+		}
+
+		const rule = this.style("dim", "─".repeat(Math.max(1, inner)));
+		return ["", rule, ...clipped, rule];
+	}
+
+	/**
+	 * Render preview markdown, falling back to plain wrapped text.
+	 *
+	 * The fallback is not just for hosts that pass no theme. pi's
+	 * `getMarkdownTheme()` returns lazily-bound functions that throw
+	 * "Theme not initialized" until `initTheme()` has run, and a throw inside
+	 * `render()` would take down the entire dialog rather than one pane. A
+	 * preview is a nicety; it must never be able to do that.
+	 */
+	private renderMarkdown(preview: string, inner: number): string[] {
+		if (this.opts.markdownTheme) {
+			try {
+				return new Markdown(preview, 0, 0, this.opts.markdownTheme).render(inner);
+			} catch {
+				// fall through to plain text
+			}
+		}
+		return preview.split("\n").flatMap((line) => wrapTextWithAnsi(line, inner));
+	}
+
 	render(width: number): string[] {
 		const cap = this.opts.maxWidth ?? width;
 		const outer = Math.max(20, Math.min(width, cap));