@garygentry/feature-forge 0.2.14 → 0.3.1

package/adapters/pi/extensions/ask-user-question/tool/types.ts

@@ -0,0 +1,147 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/tool/types.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import { type Static, Type } from "typebox";
+import { LABELS_BY_KIND, ROW_INTENT_META } from "../state/row-intent.js";
+
+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;
+
+/**
+ * User-facing labels for the three runtime sentinel rows, keyed by their
+ * `WrappingSelectItem.kind` discriminator. Sourced from
+ * `ROW_INTENT_META` via `LABELS_BY_KIND` (`row-intent.ts`) — single source of
+ * truth. Adding a new sentinel requires extending the `WrappingSelectItem`
+ * union AND adding an entry to `ROW_INTENT_META`; this map then auto-extends.
+ */
+export const SENTINEL_LABELS = LABELS_BY_KIND;
+
+export type SentinelKind = keyof typeof SENTINEL_LABELS;
+export type SentinelLabel = (typeof SENTINEL_LABELS)[SentinelKind];
+
+/**
+ * Labels reserved for Pi-internal sentinels — authoring an option with any
+ * of these labels triggers the `reserved_label` runtime guard. Two of the
+ * three come from `ROW_INTENT_META` (the runtime kinds); `"Other"` is
+ * reserved for CC parity only (the model is conditioned to reach for
+ * "Other" in CC; we reject it so the runtime sentinel is the single source
+ * of truth) and has no runtime kind.
+ *
+ * Reserved unconditionally — every question mode rejects these labels, even
+ * when a given runtime sentinel is not appended in that mode.
+ *
+ * Order is pinned by `types.test.ts:292` — keep the explicit
+ * `["Other", other, next]` literal so consumers using
+ * `RESERVED_LABELS[i]` indexing or `Set` membership see no behavior change.
+ */
+export const RESERVED_LABELS = ["Other", ROW_INTENT_META.other.label, ROW_INTENT_META.next.label] as const;
+export type ReservedLabel = (typeof RESERVED_LABELS)[number];
+
+export const OptionSchema = Type.Object({
+	label: Type.String({
+		maxLength: MAX_LABEL_LENGTH,
+		description: `MAX ${MAX_LABEL_LENGTH} CHARACTERS — hard limit, requests over the limit are rejected. The display text for this option that the user will see and select. Should be concise (1-5 words) and clearly describe the choice.`,
+	}),
+	description: Type.String({
+		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 preview content rendered when this option is focused. Use for mockups, code snippets, or visual comparisons that help users compare options. See the tool description for the expected content format.",
+		}),
+	),
+});
+
+export const QuestionSchema = Type.Object({
+	question: Type.String({
+		description:
+			'The complete question to ask the user. Should be clear, specific, and end with a question mark. Example: "Which library should we use for date formatting?" If multiSelect is true, phrase it accordingly, e.g. "Which features do you want to enable?"',
+	}),
+	header: Type.String({
+		maxLength: MAX_HEADER_LENGTH,
+		description: `MAX ${MAX_HEADER_LENGTH} CHARACTERS — hard limit, requests over the limit are rejected. Very short chip/tag shown next to the question. Examples: "Auth method", "Library", "Approach".`,
+	}),
+	options: Type.Array(OptionSchema, {
+		minItems: MIN_OPTIONS,
+		maxItems: MAX_OPTIONS,
+		description:
+			"The available choices for this question. Must have 2-4 options. Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). The 'Type something.' row is appended automatically — do NOT author it.",
+	}),
+	multiSelect: Type.Optional(
+		Type.Boolean({
+			default: false,
+			description:
+				"Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive.",
+		}),
+	),
+});
+
+export const QuestionsSchema = Type.Array(QuestionSchema, {
+	minItems: 1,
+	maxItems: MAX_QUESTIONS,
+	description: "Questions to ask the user (1-4 questions)",
+});
+
+export const QuestionParamsSchema = Type.Object({
+	questions: QuestionsSchema,
+});
+
+export type OptionData = Static<typeof OptionSchema>;
+export type QuestionData = Static<typeof QuestionSchema>;
+export type QuestionParams = Static<typeof QuestionParamsSchema>;
+
+/**
+ * Answer-intent discriminated union. `kind` is the single discriminator —
+ * pre-1.0.3 boolean flags have been removed (see `banned-flags.test.ts`).
+ * Mirrors the row-side `WrappingSelectItem.kind` vocabulary where possible;
+ * `multi` is the multi-select variant (no row-side analog).
+ *
+ * Variant semantics:
+ * - `option`: user picked one of the author-defined options. `answer` is the option's label.
+ * - `custom`: user typed free-text via the "Type something." row. `answer` is the typed text or null.
+ * - `multi`: user committed multi-select choices. `selected` carries chosen labels; `answer` is null.
+ */
+export interface QuestionAnswer {
+	questionIndex: number;
+	question: string;
+	kind: "option" | "custom" | "multi";
+	answer: string | null;
+	selected?: string[];
+	notes?: string;
+	/**
+	 * Markdown text from the matched option's `preview` field, populated only
+	 * when the user lands on a single-select option carrying a `preview`.
+	 * Used by `buildQuestionnaireResponse` to echo `selected preview: <preview>`
+	 * into the LLM-facing envelope. Undefined for multi-select and custom-text
+	 * (`kind: "custom"`) answers.
+	 */
+	preview?: string;
+}
+
+export type QuestionnaireError =
+	| "no_ui"
+	| "no_custom_ui"
+	| "no_questions"
+	| "empty_options"
+	| "too_many_questions"
+	| "duplicate_question"
+	| "duplicate_option_label"
+	| "reserved_label"
+	| "session_load_failed"
+	| "stale_module_cache";
+
+export interface QuestionnaireResult {
+	answers: QuestionAnswer[];
+	cancelled: boolean;
+	error?: QuestionnaireError;
+}
+
+export function isQuestionnaireResult(value: unknown): value is QuestionnaireResult {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Record<string, unknown>;
+	return Array.isArray(v.answers) && typeof v.cancelled === "boolean";
+}

package/adapters/pi/extensions/ask-user-question/tool/validate-questionnaire.ts

@@ -0,0 +1,58 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/tool/validate-questionnaire.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import { MAX_QUESTIONS, MIN_OPTIONS, type QuestionnaireError, type QuestionParams, RESERVED_LABELS } from "./types.js";
+
+export const ERROR_NO_QUESTIONS = "Error: At least one question is required";
+export const ERROR_TOO_MANY_QUESTIONS = `Error: At most ${MAX_QUESTIONS} questions are allowed per invocation`;
+export const ERROR_DUPLICATE_QUESTION = "Error: Question text must be unique within an invocation";
+export const ERROR_TOO_FEW_OPTIONS = `Error: Each question requires at least ${MIN_OPTIONS} options`;
+export const ERROR_RESERVED_LABEL = `Error: Option label is reserved (${RESERVED_LABELS.join(", ")})`;
+export const ERROR_DUPLICATE_OPTION_LABEL = "Error: Option labels must be unique within a question";
+
+const RESERVED_LABEL_SET: ReadonlySet<string> = new Set(RESERVED_LABELS);
+
+export type ValidationResult = { ok: true } | { ok: false; error: QuestionnaireError; message: string };
+
+/**
+ * Pure runtime validator for `QuestionParams`. Covers every guard except
+ * `no_ui` (which depends on `ctx.hasUI` and stays inline at the call site).
+ * `reserved_label` MUST short-circuit before `duplicate_option_label`.
+ */
+export function validateQuestionnaire(typed: QuestionParams): ValidationResult {
+	if (typed.questions.length === 0) {
+		return { ok: false, error: "no_questions", message: ERROR_NO_QUESTIONS };
+	}
+	if (typed.questions.length > MAX_QUESTIONS) {
+		return { ok: false, error: "too_many_questions", message: ERROR_TOO_MANY_QUESTIONS };
+	}
+
+	const seenQuestions = new Set<string>();
+	for (const q of typed.questions) {
+		if (seenQuestions.has(q.question)) {
+			return { ok: false, error: "duplicate_question", message: ERROR_DUPLICATE_QUESTION };
+		}
+		seenQuestions.add(q.question);
+	}
+
+	for (const q of typed.questions) {
+		if (q.options.length < MIN_OPTIONS) {
+			return { ok: false, error: "empty_options", message: ERROR_TOO_FEW_OPTIONS };
+		}
+		const seenLabels = new Set<string>();
+		for (const o of q.options) {
+			if (RESERVED_LABEL_SET.has(o.label)) {
+				return { ok: false, error: "reserved_label", message: ERROR_RESERVED_LABEL };
+			}
+			if (seenLabels.has(o.label)) {
+				return {
+					ok: false,
+					error: "duplicate_option_label",
+					message: ERROR_DUPLICATE_OPTION_LABEL,
+				};
+			}
+			seenLabels.add(o.label);
+		}
+	}
+
+	return { ok: true };
+}

package/adapters/pi/extensions/ask-user-question/vendor-config-shim.ts

@@ -0,0 +1,65 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/vendor-config-shim.ts
+// Regenerate with: python3 scripts/build-adapters.py
+/**
+ * FEATURE-FORGE VENDOR PATCH — local stand-in for `@juicesharp/rpiv-config`.
+ *
+ * Upstream `config.ts` imports three symbols from `@juicesharp/rpiv-config`
+ * (316 LOC, its only hard dependency). Feature-forge vendors this package to
+ * keep `adapters/pi/` dependency-free, so those three symbols are supplied
+ * here instead:
+ *
+ * - `GuidanceFields` / `validateGuidanceFields` — copied verbatim from
+ *   rpiv-config@2.1.0 `config.ts:180-221`.
+ * - `loadJsonConfigWithLegacyFallback` — upstream reads user JSON config from
+ *   `~/.config/rpiv-ask-user-question/config.json` so users can override the
+ *   tool's LLM-facing guidance. Feature-forge pins its own guidance instead:
+ *   the skills are written against these exact strings, so a user override
+ *   would silently change how the pipeline's interview stages behave. This
+ *   returns the fixed feature-forge config and never touches the filesystem.
+ */
+
+export interface GuidanceFields {
+	promptSnippet?: string;
+	promptGuidelines?: string[];
+}
+
+/** Verbatim from rpiv-config@2.1.0 (config.ts:207). */
+export function validateGuidanceFields(fields: unknown): GuidanceFields {
+	if (!fields || typeof fields !== "object") return {};
+	const g = fields as Record<string, unknown>;
+	const result: GuidanceFields = {};
+	if (typeof g.promptSnippet === "string" && g.promptSnippet.length > 0) {
+		result.promptSnippet = g.promptSnippet;
+	}
+	if (
+		Array.isArray(g.promptGuidelines) &&
+		g.promptGuidelines.length > 0 &&
+		g.promptGuidelines.every((s) => typeof s === "string" && s.length > 0)
+	) {
+		result.promptGuidelines = g.promptGuidelines;
+	}
+	return result;
+}
+
+/**
+ * Feature-forge's pinned guidance, replacing upstream's user-config load.
+ *
+ * Carried over from `adapter-src/pi/ask-user-question.ts` with one wording fix:
+ * upstream appends a `Type something.` row rather than an `Other` option, and
+ * reserves the literal label `Other`, so the guideline names the behaviour
+ * rather than the Claude label.
+ */
+const FEATURE_FORGE_CONFIG = {
+	guidance: {
+		promptSnippet: "Ask the user structured multiple-choice questions and return Claude-shaped answers.",
+		promptGuidelines: [
+			"Use AskUserQuestion only for genuine user decisions or requirements clarification.",
+			"AskUserQuestion accepts 1-4 questions with 2-4 options each; the UI appends a custom free-text row automatically — never author an option labelled \"Other\".",
+			"Use AskUserQuestion multiSelect only when several options can validly apply together.",
+		],
+	},
+};
+
+export function loadJsonConfigWithLegacyFallback<T>(_name: string, _file: string = "config.json"): T {
+	return FEATURE_FORGE_CONFIG as T;
+}

package/adapters/pi/extensions/ask-user-question/view/component-binding.ts

@@ -0,0 +1,47 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/view/component-binding.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import type {
+	BindingContext,
+	GlobalSelector,
+	PerTabBindingContext,
+	PerTabSelector,
+} from "../state/selectors/contract.js";
+import type { QuestionnaireState } from "../state/state.js";
+import type { StatefulView } from "./stateful-view.js";
+import type { TabComponents } from "./tab-components.js";
+
+export interface ComponentBinding<P> {
+	readonly component: StatefulView<P>;
+	readonly select: GlobalSelector<P>;
+}
+
+export interface PerTabBinding<P> {
+	readonly resolve: (tab: TabComponents) => StatefulView<P> | undefined;
+	readonly select: PerTabSelector<P>;
+	readonly predicate?: PerTabSelector<boolean>;
+}
+
+export interface BoundGlobalBinding {
+	apply(state: QuestionnaireState, ctx: BindingContext): void;
+	invalidate(): void;
+}
+
+export interface BoundPerTabBinding {
+	apply(state: QuestionnaireState, ctx: PerTabBindingContext): void;
+}
+
+export function globalBinding<P>(spec: ComponentBinding<P>): BoundGlobalBinding {
+	return {
+		apply: (state, ctx) => spec.component.setProps(spec.select(state, ctx)),
+		invalidate: () => spec.component.invalidate(),
+	};
+}
+
+export function perTabBinding<P>(spec: PerTabBinding<P>): BoundPerTabBinding {
+	return {
+		apply: (state, ctx) => {
+			if (spec.predicate && !spec.predicate(state, ctx)) return;
+			spec.resolve(ctx.tab)?.setProps(spec.select(state, ctx));
+		},
+	};
+}

package/adapters/pi/extensions/ask-user-question/view/components/inline-input.ts

@@ -0,0 +1,98 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/view/components/inline-input.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import { CURSOR_MARKER, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+// Grapheme-aware extraction at the cursor: pi-tui's Input advances `cursor` by
+// grapheme-cluster code-unit length, so the cursor can land between code units of
+// one cluster (emoji, ZWJ, combining marks). Single-code-unit slicing would split
+// the cluster across the SGR 7/27 boundary. Moved here from wrapping-select.ts so
+// both the single-select (wrap) and multi-select (truncate-to-one-line) inline
+// inputs share one cursor-building core.
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+export interface RenderInlineInputOptions {
+	/** Live inline-input buffer. */
+	buffer: string;
+	/** Cursor offset; `undefined` / out-of-range → end-of-buffer fallback. */
+	cursorOffset: number | undefined;
+	/** Prefix for the first emitted line (e.g. `❯ 4. `). */
+	rowPrefix: string;
+	/** Prefix for continuation lines (whitespace of equal visible width). */
+	continuationPrefix: string;
+	/** Visible columns available for the buffer content (width − prefix width). */
+	contentWidth: number;
+	/** Per-line styling (single-select: `theme.selectedText`; multi-select: accent+bold). */
+	selectedText: (text: string) => string;
+	/**
+	 * `true` (single-select): wrap across lines at `contentWidth` (byte-identical to the
+	 * pre-extraction wrapping-select behavior).
+	 * `false` (multi-select): collapse to ONE line — truncate the plain buffer to
+	 * `contentWidth` with `…` when the cursor-marked content would overflow, keeping the
+	 * dialog height state-independent. The cursor is clipped past the visible window
+	 * (accepted trade): when the cursor-marked content fits it is rendered in full.
+	 */
+	multiline: boolean;
+}
+
+/**
+ * Resolve the cursor offset, falling back to end-of-buffer for `undefined`/out-of-range.
+ * Mirrors the original wrapping-select.resolveOffset exactly.
+ */
+function resolveCursorOffset(buffer: string, requested: number | undefined): number {
+	if (requested !== undefined && requested >= 0 && requested <= buffer.length) return requested;
+	return buffer.length;
+}
+
+/**
+ * Build the cursor-marked raw string for the whole buffer: `before | CURSOR_MARKER |
+ * SGR-7 reverse-video cell | SGR-27 | after`. The cell UNDER the cursor is the single
+ * grapheme at the offset (or U+00A0 NBSP at end-of-buffer / on a literal space — NBSP is
+ * wrap-safe where a literal space would tokenize as a wrap break). Zero characters shift;
+ * the column under the cursor inverts. `CURSOR_MARKER` is zero-width so wrap/truncate math
+ * is preserved.
+ */
+function buildCursorRaw(buffer: string, offset: number): string {
+	const before = buffer.slice(0, offset);
+	const [firstGrapheme] = graphemeSegmenter.segment(buffer.slice(offset));
+	const rawAt = firstGrapheme ? firstGrapheme.segment : "";
+	// NBSP (U+00A0) fallback: visually identical to a space, wrap-safe.
+	const atCursor = rawAt === "" || rawAt === " " ? "\xa0" : rawAt;
+	const after = buffer.slice(offset + rawAt.length);
+	return `${before}${CURSOR_MARKER}\x1b[7m${atCursor}\x1b[27m${after}`;
+}
+
+/**
+ * Render the inline-input row. `multiline: true` wraps (single-select, byte-identical to
+ * the pre-extraction output); `multiline: false` collapses to a single line.
+ *
+ * Cursor visualization follows the standard TUI input-widget pattern (ECMA-48 SGR 7
+ * reverse-video on the cell AT the cursor, not an inserted glyph) — same approach used by
+ * pi-tui Input.render, ink-text-input, terkelg/prompts, ratatui's user-input example.
+ */
+export function renderInlineInputRow(opts: RenderInlineInputOptions): string[] {
+	const { buffer, cursorOffset, rowPrefix, continuationPrefix, contentWidth, selectedText, multiline } = opts;
+	const offset = resolveCursorOffset(buffer, cursorOffset);
+
+	if (multiline) {
+		// Single-select: wrap at contentWidth. Byte-identical to the original
+		// wrapping-select.renderInlineInputRow output (same raw, same wrapTextWithAnsi,
+		// same prefix/selectedText per line).
+		const raw = buildCursorRaw(buffer, offset);
+		const wrapped = wrapTextWithAnsi(raw, contentWidth);
+		return wrapped.map((segment, index) => {
+			const prefix = index === 0 ? rowPrefix : continuationPrefix;
+			return selectedText(`${prefix}${segment}`);
+		});
+	}
+
+	// Multi-select: single line. Build the cursor markup on the full buffer; if it fits
+	// contentWidth, emit it as one line. If it overflows, fall back to truncating the PLAIN
+	// buffer (ANSI-safe — never cut a CURSOR_MARKER/SGR sequence) with `…` and clip the
+	// cursor. This keeps the row at exactly one line so naturalHeight stays state-independent.
+	const cursorRaw = buildCursorRaw(buffer, offset);
+	if (visibleWidth(cursorRaw) <= contentWidth) {
+		return [selectedText(`${rowPrefix}${cursorRaw}`)];
+	}
+	const clipped = truncateToWidth(buffer, contentWidth, "…");
+	return [selectedText(`${rowPrefix}${clipped}`)];
+}

package/adapters/pi/extensions/ask-user-question/view/components/multi-select-view.ts

@@ -0,0 +1,193 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/view/components/multi-select-view.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { displayLabel } from "../../state/i18n-bridge.js";
+import type { QuestionData } from "../../tool/types.js";
+import type { StatefulView } from "../stateful-view.js";
+import { renderInlineInputRow } from "./inline-input.js";
+
+const ACTIVE_POINTER = "❯ ";
+const INACTIVE_POINTER = "  ";
+const CHECKED = "[✔]";
+const UNCHECKED = "[ ]";
+const NUMBER_SEPARATOR = ". ";
+const BOX_LABEL_GAP = " ";
+// CC parity: description continuation indents to col 2 (past the pointer slot), NOT to the
+// full prefix column. Wrap width still uses prefixVisibleWidth so naturalHeight matches render.
+const CONTINUATION_INDENT = "  ";
+
+export const MULTI_SUBMIT_LABEL = "Submit";
+
+export interface MultiSelectOtherRowProps {
+	/** The "Type something." row is the focused row (optionIndex === options.length). */
+	active: boolean;
+	/** `state.inputMode` — true once the row has focus and keystrokes append to the buffer. */
+	inputMode: boolean;
+	/** Live inline-input buffer (read from `runtime.inputBuffer` / `ctx.inputBuffer`). */
+	inputBuffer: string;
+	inputCursorOffset: number | undefined;
+}
+
+export interface MultiSelectViewProps {
+	rows: ReadonlyArray<{ checked: boolean; active: boolean }>;
+	other: MultiSelectOtherRowProps;
+	nextActive: boolean;
+	nextLabel: string;
+}
+
+/**
+ * Renders the multi-select option list (one row per option — pointer + checkbox + label —
+ * plus zero or more wrapped continuation lines per description).
+ *
+ * `naturalHeight(width)` is state-INDEPENDENT (depends only on theme glyph widths,
+ * question.options, and width) so the host can compute a stable globalContentHeight
+ * without rendering. `naturalHeight(w) === render(w).length` for every props.
+ *
+ * `setProps(props)` is a pure field reassignment — no render, no invalidate side effects.
+ */
+export class MultiSelectView implements StatefulView<MultiSelectViewProps> {
+	private props: MultiSelectViewProps;
+
+	constructor(
+		private readonly theme: Theme,
+		private readonly question: QuestionData,
+	) {
+		this.props = {
+			rows: [],
+			other: { active: false, inputMode: false, inputBuffer: "", inputCursorOffset: undefined },
+			nextActive: false,
+			nextLabel: displayLabel("next"),
+		};
+	}
+
+	setProps(props: MultiSelectViewProps): void {
+		this.props = props;
+	}
+
+	handleInput(_data: string): void {}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const lines: string[] = [];
+		const prefixWidth = this.prefixVisibleWidth();
+		const contentWidth = Math.max(1, width - prefixWidth);
+		const numberWidth = String(Math.max(1, this.question.options.length + 1)).length;
+		for (let i = 0; i < this.question.options.length; i++) {
+			const opt = this.question.options[i];
+			const row = this.props.rows[i];
+			if (!opt || !row) continue;
+			const pointer = row.active ? this.theme.fg("accent", ACTIVE_POINTER) : INACTIVE_POINTER;
+			// Checked uses the same `accent` hue as the active-row label so checked rows read
+			// as "selected" rather than "success" — matches the visual rhythm of the rest of
+			// the dialog (active pointer, label, picker rows are all accent).
+			const box = row.checked ? this.theme.fg("accent", CHECKED) : this.theme.fg("muted", UNCHECKED);
+			const label = truncateToWidth(opt.label, contentWidth, "…");
+			const styledLabel = row.active ? this.theme.fg("accent", this.theme.bold(label)) : label;
+			const num = String(i + 1).padStart(numberWidth, " ");
+			const line = `${pointer}${num}${NUMBER_SEPARATOR}${box}${BOX_LABEL_GAP}${styledLabel}`;
+			lines.push(truncateToWidth(line, width, ""));
+			if (opt.description) {
+				const wrapped = wrapTextWithAnsi(opt.description, contentWidth);
+				for (const segment of wrapped) {
+					lines.push(CONTINUATION_INDENT + this.theme.fg("muted", segment));
+				}
+			}
+		}
+
+		// "Type something." row — numbered N+1, box always [ ] muted UNCHECKED (never checkable).
+		// When focused + inputMode, render the label slot via the shared inline-input helper
+		// (single-line); otherwise a static localized label truncated to contentWidth with `…`.
+		const other = this.props.other;
+		const otherPointer = other.active ? this.theme.fg("accent", ACTIVE_POINTER) : INACTIVE_POINTER;
+		const otherBox = this.theme.fg("muted", UNCHECKED);
+		const otherNum = String(this.question.options.length + 1).padStart(numberWidth, " ");
+		let otherLabel: string;
+		if (other.active && other.inputMode) {
+			const rendered = renderInlineInputRow({
+				buffer: other.inputBuffer,
+				cursorOffset: other.inputCursorOffset,
+				rowPrefix: "",
+				continuationPrefix: "",
+				contentWidth,
+				selectedText: (t) => this.theme.fg("accent", this.theme.bold(t)),
+				multiline: false,
+			});
+			otherLabel = rendered[0] ?? "";
+		} else {
+			const label = truncateToWidth(displayLabel("other"), contentWidth, "…");
+			otherLabel = other.active ? this.theme.fg("accent", this.theme.bold(label)) : label;
+		}
+		lines.push(
+			truncateToWidth(
+				`${otherPointer}${otherNum}${NUMBER_SEPARATOR}${otherBox}${BOX_LABEL_GAP}${otherLabel}`,
+				width,
+				"",
+			),
+		);
+
+		const nextPointer = this.props.nextActive ? this.theme.fg("accent", ACTIVE_POINTER) : INACTIVE_POINTER;
+		const nextLabel = this.props.nextActive
+			? this.theme.fg("accent", this.theme.bold(this.props.nextLabel))
+			: this.props.nextLabel;
+		lines.push(truncateToWidth(`${nextPointer}${nextLabel}`, width, ""));
+		return lines;
+	}
+
+	/**
+	 * Returns the [startRow, endRow) range of the active (focused) row within
+	 * `render(width)`. Labels are always 1 row (truncated); descriptions wrap.
+	 */
+	focusedItemRowRange(width: number): [number, number] {
+		const prefixWidth = this.prefixVisibleWidth();
+		const contentWidth = Math.max(1, width - prefixWidth);
+		let row = 0;
+		for (let i = 0; i < this.question.options.length; i++) {
+			const opt = this.question.options[i];
+			const r = this.props.rows[i];
+			if (!opt || !r) continue;
+			const itemHeight = 1 + (opt.description ? wrapTextWithAnsi(opt.description, contentWidth).length : 0);
+			if (r.active) {
+				return [row, row + itemHeight];
+			}
+			row += itemHeight;
+		}
+		// "Type something." row is always exactly 1 line (truncated, no description).
+		if (this.props.other.active) {
+			return [row, row + 1];
+		}
+		row += 1;
+		if (this.props.nextActive) {
+			return [row, row + 1];
+		}
+		return [0, 0];
+	}
+
+	naturalHeight(width: number): number {
+		const contentWidth = Math.max(1, width - this.prefixVisibleWidth());
+		let total = 0;
+		for (const opt of this.question.options) {
+			if (!opt) continue;
+			total += 1; // row line
+			if (opt.description) {
+				total += wrapTextWithAnsi(opt.description, contentWidth).length;
+			}
+		}
+		return total + 2; // "Type something." row + Next sentinel row (neither wraps).
+	}
+
+	private prefixVisibleWidth(): number {
+		// Canonical prefix for OPTION rows: INACTIVE_POINTER + numberWidth digits + NUMBER_SEPARATOR
+		// + UNCHECKED + BOX_LABEL_GAP. State-independent because ACTIVE/INACTIVE pointer share
+		// visibleWidth, CHECKED/UNCHECKED share visibleWidth, and numberWidth is constant per question.
+		// The number column fits `options.length + 1` so the "Type something." row's N+1 number
+		// is never clipped. The Next sentinel uses a bare `pointer + "Next"` shape — its width
+		// never exceeds this prefix at any reasonable terminal width, so it's safe to leave it
+		// out of the canonical computation.
+		const numberWidth = String(Math.max(1, this.question.options.length + 1)).length;
+		return (
+			visibleWidth(INACTIVE_POINTER) + numberWidth + visibleWidth(`${NUMBER_SEPARATOR}${UNCHECKED}${BOX_LABEL_GAP}`)
+		);
+	}
+}

package/adapters/pi/extensions/ask-user-question/view/components/option-list-view.ts

@@ -0,0 +1,70 @@
+// GENERATED — DO NOT EDIT. Source: adapter-src/pi/extensions/ask-user-question/view/components/option-list-view.ts
+// Regenerate with: python3 scripts/build-adapters.py
+import type { StatefulView } from "../stateful-view.js";
+import { WrappingSelect, type WrappingSelectItem, type WrappingSelectTheme } from "./wrapping-select.js";
+
+/**
+ * Maximum number of option rows visible in the WrappingSelect window. Lifted here from
+ * `preview-pane.ts` so the cap travels with the option-list owner.
+ */
+export const MAX_VISIBLE_OPTIONS = 10;
+
+export interface OptionListViewConfig {
+	items: readonly WrappingSelectItem[];
+	theme: WrappingSelectTheme;
+}
+
+/**
+ * Per-tick projection of OptionListView state. After Phase 11b, `inputBuffer`
+ * is part of the props bag — the session-owned `inlineInput` (a headless
+ * `pi-tui` Input instance) supplies its current `getValue()` here per tick.
+ * `OptionListView` is purely props-driven; the imperative buffer surface and
+ * read-back getters are gone.
+ */
+export interface OptionListViewProps {
+	selectedIndex: number;
+	focused: boolean;
+	inputBuffer: string;
+	inputCursorOffset?: number;
+	/** Optional previously-confirmed indicator. Omit when no marker should be drawn. */
+	confirmed?: { index: number; labelOverride?: string };
+}
+
+/**
+ * Sole owner of the option list's interactive state. Wraps a single
+ * `WrappingSelect`. Implements `StatefulView<OptionListViewProps>`:
+ * `setProps` is the only mutator; render output reflects the last props
+ * received.
+ */
+export class OptionListView implements StatefulView<OptionListViewProps> {
+	private readonly select: WrappingSelect;
+
+	constructor(config: OptionListViewConfig) {
+		this.select = new WrappingSelect(config.items, Math.min(config.items.length, MAX_VISIBLE_OPTIONS), config.theme, {
+			numberStartOffset: 0,
+			totalItemsForNumbering: config.items.length,
+		});
+	}
+
+	setProps(props: OptionListViewProps): void {
+		this.select.setSelectedIndex(props.selectedIndex);
+		this.select.setFocused(props.focused);
+		this.select.setConfirmedIndex(props.confirmed?.index, props.confirmed?.labelOverride);
+		this.select.setInputBuffer(props.inputBuffer);
+		this.select.setInputCursorOffset(props.inputCursorOffset);
+	}
+
+	handleInput(_data: string): void {}
+
+	invalidate(): void {
+		this.select.invalidate();
+	}
+
+	render(width: number): string[] {
+		return this.select.render(width);
+	}
+
+	focusedItemRowRange(width: number): [number, number] {
+		return this.select.focusedItemRowRange(width);
+	}
+}