pi-cc-extensions 0.8.7 → 0.8.9

package/extensions/ask-user-question/view/components/wrapping-select.ts

@@ -0,0 +1,291 @@
+import type { Component } from "@earendil-works/pi-tui";
+import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { renderInlineInputRow } from "./inline-input.js";
+
+/**
+ * Row-intent discriminated union. `kind` is the single discriminator —
+ * pre-1.0.3 boolean flags have been removed (see `banned-flags.test.ts`).
+ * Modeled after `QuestionnaireAction` (`key-router.ts:13-32`) and `Effect`
+ * (`state-reducer.ts:26-32`) — pure literal-tagged variants, no shared base,
+ * exhaustive-`switch` enforcement via non-`void` returns.
+ *
+ * Variant semantics:
+ * - `option`: a regular author-defined option row.
+ * - `other`: the inline free-text input row appended to every question
+ *   (label is "Type something."). Renders as inline `Input` when active.
+ * - `next`: the explicit commit-and-advance row appended to multi-select questions
+ *   (label is "Next"). Renders without a number / checkbox.
+ */
+export type WrappingSelectItem =
+	| { kind: "option"; label: string; description?: string }
+	| { kind: "other"; label: string; description?: string }
+	| { kind: "next"; label: string; description?: string };
+
+export interface WrappingSelectTheme {
+	selectedText: (text: string) => string;
+	description: (text: string) => string;
+	scrollInfo: (text: string) => string;
+}
+
+/**
+ * Numbering controls.
+ *
+ * Use `numberStartOffset` + `totalItemsForNumbering` when a list is logically a slice of a
+ * larger numbered sequence — e.g. to start numbering at an offset and pad the column as
+ * if the list were part of a longer continuous numbered sequence.
+ */
+export interface WrappingSelectOptions {
+	/** Start numbering at this offset + 1 (default 0 → rows labeled 1, 2, 3 …). */
+	numberStartOffset?: number;
+	/** Override the total used to pad the number column (useful when items span multiple lists). */
+	totalItemsForNumbering?: number;
+}
+
+export class WrappingSelect implements Component {
+	private static readonly ACTIVE_POINTER = "❯ ";
+	private static readonly INACTIVE_POINTER = "  ";
+	private static readonly NUMBER_SEPARATOR = ". ";
+	private static readonly CONFIRMED_MARK = " ✔";
+	private static readonly MIN_CONTENT_WIDTH = 1;
+
+	private readonly items: readonly WrappingSelectItem[];
+	private readonly maxVisible: number;
+	private readonly theme: WrappingSelectTheme;
+	private numberStartOffset: number;
+	private totalItemsForNumbering: number;
+
+	private selectedIndex = 0;
+	private focused = true;
+	private inputBuffer = "";
+	private inputCursorOffset: number | undefined = undefined;
+	/**
+	 * Index of the row that was previously confirmed for this list (e.g. the user's prior
+	 * answer when re-entering a multi-question tab). Renders `<label> ✔` in the active-row
+	 * styling but WITHOUT the `❯` pointer — pointer is reserved for the live cursor. When
+	 * `selectedIndex === confirmedIndex && focused`, the active rendering wins (no double-mark).
+	 */
+	private confirmedIndex: number | undefined = undefined;
+	/**
+	 * When set together with `confirmedIndex`, replaces the row's static label at render time.
+	 * Used for the `kind: "other"` sentinel — its label is "Type something." but if the user's
+	 * prior answer was custom text, we render that text instead (e.g. `4. Hello ✔`).
+	 */
+	private confirmedLabelOverride: string | undefined = undefined;
+
+	constructor(
+		items: readonly WrappingSelectItem[],
+		maxVisible: number,
+		theme: WrappingSelectTheme,
+		options: WrappingSelectOptions = {},
+	) {
+		this.items = items;
+		this.maxVisible = Math.max(1, maxVisible);
+		this.theme = theme;
+		this.numberStartOffset = options.numberStartOffset ?? 0;
+		this.totalItemsForNumbering = options.totalItemsForNumbering ?? items.length;
+	}
+
+	/**
+	 * Update the numbering offset + total padding width without rebuilding the component.
+	 * Lets the host realign the number column when the underlying item set changes.
+	 */
+	setNumbering(numberStartOffset: number, totalItemsForNumbering: number): void {
+		this.numberStartOffset = numberStartOffset;
+		this.totalItemsForNumbering = Math.max(1, totalItemsForNumbering);
+	}
+
+	setSelectedIndex(index: number): void {
+		this.selectedIndex = Math.max(0, Math.min(index, this.items.length - 1));
+	}
+
+	setFocused(focused: boolean): void {
+		this.focused = focused;
+	}
+
+	/**
+	 * Mark a previously-confirmed row. Pass `undefined` to clear. `labelOverride` replaces
+	 * the row's static `item.label` at render time — used for the `kind: "other"` sentinel so
+	 * the row reads `Hello ✔` instead of `Type something. ✔` when the prior answer was custom
+	 * text.
+	 */
+	setConfirmedIndex(index: number | undefined, labelOverride?: string): void {
+		if (index === undefined) {
+			this.confirmedIndex = undefined;
+			this.confirmedLabelOverride = undefined;
+			return;
+		}
+		this.confirmedIndex = Math.max(0, Math.min(index, this.items.length - 1));
+		this.confirmedLabelOverride = labelOverride;
+	}
+
+	setInputBuffer(text: string): void {
+		this.inputBuffer = text;
+	}
+
+	/** Set the cursor offset for the inline input row. `undefined` → end-of-buffer fallback. */
+	setInputCursorOffset(offset: number | undefined): void {
+		this.inputCursorOffset = offset;
+	}
+
+	/** Intentionally empty — input is routed at the container level. */
+	handleInput(_data: string): void {}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		if (this.items.length === 0) return [];
+
+		const { startIndex, endIndex } = this.computeVisibleWindow();
+		const numberWidth = String(Math.max(1, this.totalItemsForNumbering)).length;
+		const lines: string[] = [];
+
+		for (let i = startIndex; i < endIndex; i++) {
+			const item = this.items[i];
+			if (!item) continue;
+			const isActive = i === this.selectedIndex && this.focused;
+			lines.push(...this.renderItem(item, i, isActive, width, numberWidth));
+		}
+
+		if (this.hasItemsOutsideWindow(startIndex, endIndex)) {
+			lines.push(this.theme.scrollInfo(`  (${this.selectedIndex + 1}/${this.items.length})`));
+		}
+		return lines;
+	}
+
+	/**
+	 * Returns the [startRow, endRow) range of the focused (selected) item within
+	 * the output of `render(width)`. Computed by iterating the visible window and
+	 * summing per-item row counts — O(maxVisible) per call.
+	 */
+	focusedItemRowRange(width: number): [number, number] {
+		if (this.items.length === 0) return [0, 0];
+		const { startIndex, endIndex } = this.computeVisibleWindow();
+		const numberWidth = String(Math.max(1, this.totalItemsForNumbering)).length;
+		let row = 0;
+		for (let i = startIndex; i < endIndex; i++) {
+			const item = this.items[i];
+			if (!item) continue;
+			const isActive = i === this.selectedIndex && this.focused;
+			const itemRowCount = this.computeItemRowCount(item, i, isActive, width, numberWidth);
+			if (i === this.selectedIndex) {
+				return [row, row + itemRowCount];
+			}
+			row += itemRowCount;
+		}
+		return [0, 1];
+	}
+
+	/**
+	 * Per-item row count. Delegates to `renderItem().length` so `renderItem` remains
+	 * the single source of truth for per-item row math — eliminates the prior shadow-copy
+	 * that risked silent miscounts when new `kind` values branch in `renderItem` but not here.
+	 */
+	private computeItemRowCount(
+		item: WrappingSelectItem,
+		index: number,
+		isActive: boolean,
+		width: number,
+		numberWidth: number,
+	): number {
+		return this.renderItem(item, index, isActive, width, numberWidth).length;
+	}
+
+	private computeVisibleWindow(): { startIndex: number; endIndex: number } {
+		const half = Math.floor(this.maxVisible / 2);
+		const startIndex = Math.max(0, Math.min(this.selectedIndex - half, this.items.length - this.maxVisible));
+		const endIndex = Math.min(startIndex + this.maxVisible, this.items.length);
+		return { startIndex, endIndex };
+	}
+
+	private hasItemsOutsideWindow(startIndex: number, endIndex: number): boolean {
+		return startIndex > 0 || endIndex < this.items.length;
+	}
+
+	private renderItem(
+		item: WrappingSelectItem,
+		index: number,
+		isActive: boolean,
+		width: number,
+		numberWidth: number,
+	): string[] {
+		const rowPrefix = this.buildRowPrefix(index, isActive, numberWidth);
+		const continuationPrefix = " ".repeat(visibleWidth(rowPrefix));
+		const contentWidth = Math.max(WrappingSelect.MIN_CONTENT_WIDTH, width - visibleWidth(rowPrefix));
+
+		if (this.shouldRenderAsInlineInput(item, isActive)) {
+			return this.renderInlineInputRow(rowPrefix, continuationPrefix, contentWidth);
+		}
+
+		// Confirmed row gets a trailing ` ✔` and accent+bold styling; pointer is independent
+		// (still ❯ when active). When `index === confirmedIndex` AND `isActive`, both `❯` and
+		// `✔` appear on the same row — load-bearing for the case where the prior answer was
+		// row 0 (cursor resets to 0 on tab-back, so the confirmed row IS the active row).
+		// Optional `confirmedLabelOverride` replaces the static label (used for `kind: "other"`
+		// + `kind: "custom"` answer); the inline-input branch above still wins for `kind: "other" + isActive`.
+		const isConfirmed = index === this.confirmedIndex;
+		const label = isConfirmed
+			? `${this.confirmedLabelOverride ?? item.label}${WrappingSelect.CONFIRMED_MARK}`
+			: item.label;
+		const applySelectedStyle = isActive || isConfirmed;
+
+		return [
+			...this.renderLabelBlock(label, rowPrefix, continuationPrefix, contentWidth, applySelectedStyle),
+			...this.renderDescriptionBlock(item.description, continuationPrefix, contentWidth),
+		];
+	}
+
+	private buildRowPrefix(index: number, isActive: boolean, numberWidth: number): string {
+		const pointer = isActive ? WrappingSelect.ACTIVE_POINTER : WrappingSelect.INACTIVE_POINTER;
+		const displayNumber = this.numberStartOffset + index + 1;
+		const paddedNumber = String(displayNumber).padStart(numberWidth, " ");
+		return `${pointer}${paddedNumber}${WrappingSelect.NUMBER_SEPARATOR}`;
+	}
+
+	private shouldRenderAsInlineInput(item: WrappingSelectItem, isActive: boolean): boolean {
+		return item.kind === "other" && isActive;
+	}
+
+	/**
+	 * Render the inline input row across one or more lines, wrapping at `contentWidth`.
+	 * Delegates to the shared `renderInlineInputRow` helper (`./inline-input.ts`) so the
+	 * single-select wrap path and the multi-select single-line path share one cursor-
+	 * building core. The `multiline: true` path is byte-identical to the pre-extraction
+	 * output (cursor rationale lives in `inline-input.ts`).
+	 */
+	private renderInlineInputRow(rowPrefix: string, continuationPrefix: string, contentWidth: number): string[] {
+		return renderInlineInputRow({
+			buffer: this.inputBuffer,
+			cursorOffset: this.inputCursorOffset,
+			rowPrefix,
+			continuationPrefix,
+			contentWidth,
+			selectedText: this.theme.selectedText,
+			multiline: true,
+		});
+	}
+
+	private renderLabelBlock(
+		label: string,
+		rowPrefix: string,
+		continuationPrefix: string,
+		contentWidth: number,
+		applySelectedStyle: boolean,
+	): string[] {
+		const wrapped = wrapTextWithAnsi(label, contentWidth);
+		return wrapped.map((segment, index) => {
+			const prefix = index === 0 ? rowPrefix : continuationPrefix;
+			const line = `${prefix}${segment}`;
+			return applySelectedStyle ? this.theme.selectedText(line) : line;
+		});
+	}
+
+	private renderDescriptionBlock(
+		description: string | undefined,
+		continuationPrefix: string,
+		contentWidth: number,
+	): string[] {
+		if (!description) return [];
+		const wrapped = wrapTextWithAnsi(description, contentWidth);
+		return wrapped.map((segment) => `${continuationPrefix}${this.theme.description(segment)}`);
+	}
+}

package/extensions/ask-user-question/view/dialog-builder.ts

@@ -0,0 +1,205 @@
+import { DynamicBorder, type Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Container, type Input, Spacer } from "@earendil-works/pi-tui";
+import type { QuestionnaireState } from "../state/state.js";
+import type { QuestionData } from "../tool/types.js";
+import type { PreviewPaneProps } from "./components/preview/preview-pane.js";
+import type { TabBar } from "./components/tab-bar.js";
+import type { StatefulView } from "./stateful-view.js";
+import type { TabComponents } from "./tab-components.js";
+import { QuestionTabStrategy, SubmitTabStrategy, type TabContentStrategy } from "./tab-content-strategy.js";
+
+export const HINT_PART_ENTER = "Enter to select";
+export const HINT_PART_NAV = "↑/↓ to navigate";
+export const HINT_PART_TOGGLE = "Space to toggle";
+export const HINT_PART_NOTES = "n to add notes";
+export const HINT_PART_TAB = "Tab to switch questions";
+export const HINT_PART_CANCEL = "Esc to cancel";
+export const HINT_PART_COLLAPSE = "Ctrl+] to collapse";
+export const HINT_PART_EXPAND = "Ctrl+] to expand";
+/**
+ * `HINT_SINGLE` / `HINT_MULTI` are the resting core hint for NON-multiSelect
+ * question tabs only: `buildHintText` drops `NOTES` while the notes editor is
+ * open (`state.notesVisible`) or the "Type something." row is capturing text
+ * (`state.inputMode`), and on multiSelect tabs it interleaves `TOGGLE` between
+ * `NAV` and `NOTES`, so neither composite is a substring there — assert on
+ * `HINT_PART_*` constants in those states instead. The collapse affordance is
+ * appended AFTER cancel by `buildHintText` so the resting core stays a contiguous
+ * prefix substring of the rendered line. On narrow terminals the collapse tail
+ * clips with `…` (`OneLineClippedText`); the core is preserved.
+ */
+export const HINT_SINGLE = [HINT_PART_ENTER, HINT_PART_NAV, HINT_PART_NOTES, HINT_PART_CANCEL].join(" · ");
+export const HINT_MULTI = [HINT_PART_ENTER, HINT_PART_NAV, HINT_PART_NOTES, HINT_PART_TAB, HINT_PART_CANCEL].join(
+	" · ",
+);
+/** Single-line footer shown by `QuestionnaireSession` when `state.collapsed === true`. Bypasses `buildHintText`. */
+export const COLLAPSED_HINT = [HINT_PART_EXPAND, HINT_PART_CANCEL].join(" · ");
+export const REVIEW_HEADING = "Review your answers";
+export const READY_PROMPT = "Ready to submit your answers?";
+export const INCOMPLETE_WARNING_PREFIX = "⚠ Answer remaining questions before submitting:";
+
+const OVERFLOW_UP = "↑";
+const OVERFLOW_DOWN = "↓";
+const OVERFLOW_BOTH = "↕";
+
+export type DialogState = QuestionnaireState;
+
+/** Per-tick projection of dialog state. Written by the adapter; read by the strategy thunk. */
+export interface DialogProps {
+	state: DialogState;
+	activePreviewPane: StatefulView<PreviewPaneProps>;
+}
+
+/** Construction-time config for `DialogView`. Frozen after construction. */
+export interface DialogConfig {
+	theme: Theme;
+	questions: readonly QuestionData[];
+	tabBar: TabBar | undefined;
+	notesInput: Input;
+	isMulti: boolean;
+	tabsByIndex: ReadonlyArray<TabComponents>;
+	/** Optional so single-question mode and non-submit tests can omit it; SubmitTabStrategy falls back to Spacer rows. */
+	submitPicker?: Component;
+	/** Body height of the currently active tab/option. */
+	getCurrentBodyHeight: (width: number) => number;
+	/** Terminal height getter. Mirrors `getTerminalWidth` — reads `tui.terminal.rows` at render time. */
+	getTerminalRows: () => number;
+}
+
+/**
+ * The 7th renderable, promoted from a structural literal to a named class so
+ * all view-layer components share one explicit `implements StatefulView<P>`
+ * contract. `setProps(DialogProps)` writes the live cell read by the
+ * strategy thunk during `render()`. `liveProps.activePreviewPane` is a
+ * resolved pane reference threaded by the adapter per tick — the dialog
+ * itself does not derive it.
+ */
+export class DialogView implements StatefulView<DialogProps> {
+	private liveProps: DialogProps;
+	private readonly config: DialogConfig;
+	private readonly questionStrategy: TabContentStrategy;
+	private readonly submitStrategy: TabContentStrategy | undefined;
+
+	constructor(config: DialogConfig, initialProps: DialogProps) {
+		this.config = config;
+		this.liveProps = initialProps;
+		this.questionStrategy = new QuestionTabStrategy({
+			theme: config.theme,
+			questions: config.questions,
+			getPreviewPane: () => this.liveProps.activePreviewPane,
+			tabsByIndex: config.tabsByIndex,
+			notesInput: config.notesInput,
+			isMulti: config.isMulti,
+			getCurrentBodyHeight: config.getCurrentBodyHeight,
+		});
+		this.submitStrategy = config.isMulti
+			? new SubmitTabStrategy({
+					theme: config.theme,
+					questions: config.questions,
+					submitPicker: config.submitPicker,
+				})
+			: undefined;
+	}
+
+	setProps(props: DialogProps): void {
+		this.liveProps = props;
+	}
+
+	handleInput(_data: string): void {}
+
+	// Invalidation is driven by `QuestionnairePropsAdapter.invalidate()`, which
+	// owns the full set of renderables (binding registries + extras like
+	// `notesInput`). DialogView has no cached layout of its own.
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const state = this.liveProps.state;
+		const onSubmit = this.config.isMulti && state.currentTab === this.config.questions.length;
+		const strategy = onSubmit && this.submitStrategy ? this.submitStrategy : this.questionStrategy;
+
+		// Cache heading rows (avoid double construction in render and container build).
+		const headingRowCache = strategy.headingRows(state);
+		const headingCount = headingRowCache.length;
+
+		// Render only the active tab's natural content; blank height equalization would
+		// unnecessarily consume transcript rows above this full-width editor component.
+		const natural = this.buildContainerFromStrategy(strategy, headingRowCache).render(width);
+
+		// Fixed region sizes (deterministic from structure).
+		// TabBar.render() returns [tabLine, ""] — always 2 rows.
+		const topFixed = 1 + (this.config.isMulti && this.config.tabBar ? 2 : 0) + 1;
+		const bottomFixed = 1 + strategy.footerRowCount;
+		const middleRows = natural.length - topFixed - bottomFixed;
+
+		const termRows = this.config.getTerminalRows();
+		if (natural.length <= termRows) return natural;
+
+		// OVERFLOW — apply 3-region partition with scroll-to-focus.
+		const availableMiddle = Math.max(0, termRows - topFixed - bottomFixed);
+		if (availableMiddle === 0) {
+			// Terminal too small for any middle content — show just chrome.
+			const chromeOnly = [...natural.slice(0, topFixed), ...natural.slice(natural.length - bottomFixed)];
+			return chromeOnly.length > termRows ? chromeOnly.slice(0, termRows) : chromeOnly;
+		}
+
+		const bodyRange = strategy.focusedItemRowRange(width, state);
+
+		// Compute scroll window centered on the focused option.
+		let scrollStart: number;
+		if (bodyRange) {
+			const focusedRowInMiddle = headingCount + bodyRange[0];
+			const focusedHeight = bodyRange[1] - bodyRange[0];
+			// Center the focused item vertically in the available middle space.
+			const idealStart = focusedRowInMiddle - Math.floor(Math.max(0, availableMiddle - focusedHeight) / 2);
+			scrollStart = Math.max(0, Math.min(idealStart, middleRows - availableMiddle));
+		} else {
+			// No interactive focus (submit tab) — top-anchor the middle.
+			scrollStart = 0;
+		}
+
+		const scrollableMiddle = natural.slice(topFixed + scrollStart, topFixed + scrollStart + availableMiddle);
+
+		const hasUp = scrollStart > 0;
+		const hasDown = scrollStart + availableMiddle < middleRows;
+		if (hasUp && hasDown && scrollableMiddle.length === 1) {
+			// Single-row middle: combined ↕ avoids the prior collision where ↓ overwrote ↑.
+			scrollableMiddle[0] = this.config.theme.fg("dim", OVERFLOW_BOTH);
+		} else {
+			if (hasUp && scrollableMiddle.length > 0) {
+				scrollableMiddle[0] = this.config.theme.fg("dim", OVERFLOW_UP);
+			}
+			if (hasDown && scrollableMiddle.length > 0) {
+				scrollableMiddle[scrollableMiddle.length - 1] = this.config.theme.fg("dim", OVERFLOW_DOWN);
+			}
+		}
+
+		const result = [
+			...natural.slice(0, topFixed),
+			...scrollableMiddle,
+			...natural.slice(natural.length - bottomFixed),
+		];
+		// Safety: never exceed terminal rows (covers the availableMiddle === 0 case
+		// where topFixed + bottomFixed > termRows).
+		return result.length > termRows ? result.slice(0, termRows) : result;
+	}
+
+	private buildContainerFromStrategy(strategy: TabContentStrategy, headingRowCache: Component[]): Container {
+		const { theme, isMulti, tabBar } = this.config;
+		const state = this.liveProps.state;
+		const container = new Container();
+		const border = () => new DynamicBorder((s) => theme.fg("accent", s));
+
+		container.addChild(border());
+		if (isMulti && tabBar) container.addChild(tabBar);
+		container.addChild(new Spacer(1));
+
+		for (const c of headingRowCache) container.addChild(c);
+		container.addChild(strategy.bodyComponent(state));
+		container.addChild(new Spacer(1));
+		for (const c of strategy.midRows(state)) container.addChild(c);
+
+		container.addChild(border());
+		for (const c of strategy.footerRows(state)) container.addChild(c);
+
+		return container;
+	}
+}

package/extensions/ask-user-question/view/props-adapter.ts

@@ -0,0 +1,123 @@
+import type { Input } from "@earendil-works/pi-tui";
+import type { BindingContext, PerTabBindingContext } from "../state/selectors/contract.js";
+import { selectActivePreviewPaneIndex } from "../state/selectors/derivations.js";
+import { selectActiveView } from "../state/selectors/focus.js";
+import type { QuestionnaireState } from "../state/state.js";
+import type { QuestionData } from "../tool/types.js";
+import type { BoundGlobalBinding, BoundPerTabBinding } from "./component-binding.js";
+import type { WrappingSelectItem } from "./components/wrapping-select.js";
+import type { TabComponents } from "./tab-components.js";
+
+/** Cache-invalidation contract used by the adapter. `pi-tui` `Component` already satisfies it. */
+interface Invalidatable {
+	invalidate(): void;
+}
+
+/**
+ * Reads pi-tui Input's private `cursor` field via type escape with full runtime validation.
+ * Returns `undefined` on any failure → graceful degradation to end-of-buffer cursor.
+ * Follow-up: replace with Input.getCursorOffset() when pi-tui exposes a public API.
+ */
+function getInputCursorOffset(input: Input): number | undefined {
+	const raw = (input as unknown as { cursor?: unknown }).cursor;
+	if (typeof raw !== "number") return undefined;
+	if (!Number.isSafeInteger(raw)) return undefined;
+	const value = input.getValue();
+	if (raw < 0 || raw > value.length) return undefined;
+	return raw;
+}
+
+export interface QuestionnairePropsAdapterConfig {
+	tui: { requestRender(): void };
+	questions: readonly QuestionData[];
+	itemsByTab: ReadonlyArray<readonly WrappingSelectItem[]>;
+	tabsByIndex: ReadonlyArray<TabComponents>;
+	inlineInput: Input;
+	globalBindings: ReadonlyArray<BoundGlobalBinding>;
+	perTabBindings: ReadonlyArray<BoundPerTabBinding>;
+	/**
+	 * Renderables not reached by the binding registries (e.g. the notes
+	 * `Input`, which is typed into directly and has no props). Walked by
+	 * `invalidate()` after the binding-driven components.
+	 */
+	extraInvalidatables?: ReadonlyArray<Invalidatable>;
+}
+
+/**
+ * View fan-out: drives every component setter from the canonical state via
+ * two binding registries. `globalBindings` covers the cross-tab components
+ * (dialog, submitPicker?, tabBar?); `perTabBindings` covers the
+ * per-tab kinds (optionList, preview, multiSelect?). The hand-coded fan-out
+ * collapses to one global loop + one nested per-tab loop. The inline-Other
+ * value is read from the headless `inlineInput` instance per tick into ctx so
+ * `selectOptionListProps` sees the live value.
+ */
+export class QuestionnairePropsAdapter {
+	private readonly tui: QuestionnairePropsAdapterConfig["tui"];
+	private readonly questions: readonly QuestionData[];
+	private readonly itemsByTab: ReadonlyArray<readonly WrappingSelectItem[]>;
+	private readonly tabsByIndex: ReadonlyArray<TabComponents>;
+	private readonly inlineInput: Input;
+	private readonly globalBindings: ReadonlyArray<BoundGlobalBinding>;
+	private readonly perTabBindings: ReadonlyArray<BoundPerTabBinding>;
+	private readonly extraInvalidatables: ReadonlyArray<Invalidatable>;
+
+	constructor(config: QuestionnairePropsAdapterConfig) {
+		this.tui = config.tui;
+		this.questions = config.questions;
+		this.itemsByTab = config.itemsByTab;
+		this.tabsByIndex = config.tabsByIndex;
+		this.inlineInput = config.inlineInput;
+		this.globalBindings = config.globalBindings;
+		this.perTabBindings = config.perTabBindings;
+		this.extraInvalidatables = config.extraInvalidatables ?? [];
+	}
+
+	apply(state: QuestionnaireState): void {
+		const totalQuestions = this.questions.length;
+		const activeView = selectActiveView(state, totalQuestions);
+		const paneIndex = selectActivePreviewPaneIndex(state.currentTab, totalQuestions);
+		const activePreviewPane = this.tabsByIndex[paneIndex]?.preview ?? this.tabsByIndex[0]!.preview;
+
+		const ctx: BindingContext = {
+			questions: this.questions,
+			itemsByTab: this.itemsByTab,
+			totalQuestions,
+			activeView,
+			inputBuffer: this.inlineInput.getValue(),
+			inputCursorOffset: getInputCursorOffset(this.inlineInput),
+			activePreviewPane,
+		};
+
+		for (const binding of this.globalBindings) {
+			binding.apply(state, ctx);
+		}
+
+		for (let i = 0; i < this.tabsByIndex.length; i++) {
+			const tab = this.tabsByIndex[i]!;
+			const tabCtx: PerTabBindingContext = { ...ctx, tab, i };
+			for (const binding of this.perTabBindings) {
+				binding.apply(state, tabCtx);
+			}
+		}
+
+		this.tui.requestRender();
+	}
+
+	/**
+	 * Invalidates every owned renderable. Called by the session in place of
+	 * the old `dialog.invalidate()` forwarding chain — DialogView no longer
+	 * reaches into siblings (tabBar, notesInput, activePreviewPane).
+	 * Iterates the same registries used by `apply()` plus
+	 * `extraInvalidatables` for components outside the binding system.
+	 */
+	invalidate(): void {
+		for (const b of this.globalBindings) b.invalidate();
+		for (const tab of this.tabsByIndex) {
+			tab.optionList.invalidate();
+			tab.preview.invalidate();
+			tab.multiSelect?.invalidate();
+		}
+		for (const x of this.extraInvalidatables) x.invalidate();
+	}
+}

package/extensions/ask-user-question/view/stateful-view.ts

@@ -0,0 +1,24 @@
+import type { Component } from "@earendil-works/pi-tui";
+
+/**
+ * Generic prop-driven component contract. Every renderable owns its own `P` shape;
+ * the adapter computes `P` from canonical state via per-component selectors and
+ * pushes it via `setProps`. `focused: boolean` is a field on `P` only where the
+ * component needs it.
+ */
+export interface StatefulView<P> extends Component {
+	setProps(props: P): void;
+}
+
+/**
+ * Discriminated focus union — encodes the three-cell focus invariant
+ * (`notesVisible`, submit-tab, options). Dispatcher cascade (`key-router.ts`)
+ * and reducer's defensive clears (`state-reducer.ts`) enforce mutual exclusion;
+ * this type makes it explicit so per-component `focused: boolean` flags
+ * derive from one equality check against this discriminant rather than
+ * parallel boolean reads.
+ *
+ * Priority order: notes > submit > options. Matches the dispatcher
+ * cascade exactly so the union is observably equivalent to today's reads.
+ */
+export type ActiveView = "notes" | "options" | "submit";

package/extensions/ask-user-question/view/tab-components.ts

@@ -0,0 +1,16 @@
+import type { MultiSelectView } from "./components/multi-select-view.js";
+import type { OptionListViewProps } from "./components/option-list-view.js";
+import type { PreviewPane } from "./components/preview/preview-pane.js";
+import type { StatefulView } from "./stateful-view.js";
+
+export interface TabBodyHeights {
+	current: number;
+	max: number;
+}
+
+export interface TabComponents {
+	optionList: StatefulView<OptionListViewProps>;
+	preview: PreviewPane;
+	multiSelect?: MultiSelectView;
+	bodyHeights: (width: number) => TabBodyHeights;
+}