@nklisch/pi-enhanced 0.1.0

package/node_modules/@juicesharp/rpiv-ask-user-question/state/questionnaire-session.ts

@@ -0,0 +1,232 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { getKeybindings, type Input, type OverlayHandle } from "@earendil-works/pi-tui";
+import type { QuestionData, QuestionnaireResult, QuestionParams } from "../tool/types.js";
+import type { WrappingSelectItem } from "../view/components/wrapping-select.js";
+import { COLLAPSED_HINT } from "../view/dialog-builder.js";
+import type { QuestionnairePropsAdapter } from "../view/props-adapter.js";
+import { buildQuestionnaire } from "./build-questionnaire.js";
+import { t } from "./i18n-bridge.js";
+import { type QuestionnaireAction, routeKey } from "./key-router.js";
+import type { QuestionnaireRuntime, QuestionnaireState } from "./state.js";
+import { type ApplyContext, type Effect, reduce } from "./state-reducer.js";
+
+// Module-level constant; reused for cursor-end mutations after setValue rehydration.
+// Ctrl-E → tui.editor.cursorLineEnd (public path; pi-tui keybindings.js:25-28).
+const CURSOR_END = "\x05";
+
+export interface QuestionnaireSessionConfig {
+	tui: { terminal: { columns: number; rows: number }; requestRender(): void };
+	theme: Theme;
+	params: QuestionParams;
+	itemsByTab: WrappingSelectItem[][];
+	done: (result: QuestionnaireResult) => void;
+	/** Key spec for the collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. */
+	collapseKey: string;
+}
+
+export interface QuestionnaireSessionComponent {
+	render(width: number): string[];
+	invalidate(): void;
+	handleInput(data: string): void;
+}
+
+function initialState(): QuestionnaireState {
+	return {
+		currentTab: 0,
+		optionIndex: 0,
+		inputMode: false,
+		notesVisible: false,
+		answers: new Map(),
+		multiSelectChecked: new Set(),
+		notesByTab: new Map(),
+		submitChoiceIndex: 0,
+		notesDraft: "",
+		collapsed: false,
+	};
+}
+
+/**
+ * Slim runtime: owns the canonical state cell, the input-buffer cell, the
+ * two-pass `notesVisible` dispatch loop, and the effect runner. State
+ * transitions go through the pure `reduce` reducer; UI fan-out goes through
+ * the `QuestionnairePropsAdapter` produced by `buildQuestionnaire`.
+ */
+export class QuestionnaireSession {
+	private state: QuestionnaireState = initialState();
+
+	private readonly questions: readonly QuestionData[];
+	private readonly isMulti: boolean;
+	private readonly itemsByTab: WrappingSelectItem[][];
+
+	private readonly notesInput: Input;
+	private readonly inlineInput: Input;
+	private readonly viewAdapter: QuestionnairePropsAdapter;
+	private readonly collapseKey: string;
+
+	/**
+	 * Overlay handle captured by `ctx.ui.custom`'s `onHandle` callback. Lets the session
+	 * call `setHidden(true/false)` so pi-tui's overlay stack reflects the collapsed state
+	 * and overlay-aware consumers (e.g. `pi-station`) can resume normal behaviour.
+	 */
+	private overlayHandle: OverlayHandle | undefined;
+
+	private readonly tui: QuestionnaireSessionConfig["tui"];
+	private readonly done: QuestionnaireSessionConfig["done"];
+	readonly component: QuestionnaireSessionComponent;
+
+	constructor(config: QuestionnaireSessionConfig) {
+		this.tui = config.tui;
+		this.done = config.done;
+		this.questions = config.params.questions;
+		this.isMulti = this.questions.length > 1;
+		this.itemsByTab = config.itemsByTab;
+		this.collapseKey = config.collapseKey;
+
+		const built = buildQuestionnaire({
+			tui: this.tui,
+			theme: config.theme,
+			questions: this.questions,
+			itemsByTab: this.itemsByTab,
+			isMulti: this.isMulti,
+			initialState: this.state,
+			getCurrentTab: () => this.state.currentTab,
+		});
+
+		this.notesInput = built.notesInput;
+		this.inlineInput = built.inlineInput;
+		this.viewAdapter = built.adapter;
+
+		const theme = config.theme;
+		// Collapsed render: a single dim row at the bottom of the overlay. pi-tui sizes
+		// the overlay to `min(lines.length, maxHeight)`, so returning one line shrinks
+		// the bottom-anchored overlay from full-height to one row and the transcript
+		// behind it becomes readable (#47). The overlay stays focused and in the
+		// stack, so Ctrl+] still routes here to expand.
+		const collapsedRender = (_width: number): string[] => [
+			theme.fg("dim", ` ${t("hint.expand_line", COLLAPSED_HINT)} `),
+		];
+
+		this.component = {
+			render: (width) => (this.state.collapsed ? collapsedRender(width) : built.render(width)),
+			invalidate: built.invalidate,
+			handleInput: (data) => this.dispatch(data),
+		};
+
+		this.viewAdapter.apply(this.state);
+	}
+
+	dispatch(data: string): void {
+		const action = routeKey(data, this.state, this.runtime());
+		if (action.kind === "ignore") {
+			this.handleIgnoreInline(data);
+			return;
+		}
+		this.commit(action);
+	}
+
+	private commit(action: QuestionnaireAction): void {
+		const result = reduce(this.state, action, this.applyContext());
+		this.state = result.state;
+		for (const effect of result.effects) this.runEffect(effect);
+		this.state = this.mirrorNotesDraft(this.state);
+		this.viewAdapter.apply(this.state);
+	}
+
+	private mirrorNotesDraft(s: QuestionnaireState): QuestionnaireState {
+		const draft = this.notesInput.getValue();
+		return s.notesDraft === draft ? s : { ...s, notesDraft: draft };
+	}
+
+	private runEffect(effect: Effect): void {
+		switch (effect.kind) {
+			case "set_input_buffer":
+				this.inlineInput.setValue(effect.value);
+				this.inlineInput.handleInput(CURSOR_END);
+				return;
+			case "clear_input_buffer":
+				this.inlineInput.setValue("");
+				return;
+			case "set_notes_value":
+				this.notesInput.setValue(effect.value);
+				return;
+			case "set_notes_focused":
+				this.notesInput.focused = effect.focused;
+				return;
+			case "forward_notes_keystroke":
+				this.notesInput.handleInput(effect.data);
+				return;
+			case "set_overlay_hidden":
+				// No-op until `setOverlayHandle` has been called (the handle arrives via
+				// `ctx.ui.custom`'s `onHandle` right after the overlay is shown).
+				this.overlayHandle?.setHidden(effect.hidden);
+				return;
+			case "done":
+				this.done(effect.result);
+				return;
+		}
+	}
+
+	/**
+	 * Per-keystroke `ignore` fast path: delegates to the headless `inlineInput`
+	 * Input so bracketed-paste accumulator (`input.js:33-63`) and Kitty CSI-u
+	 * decode (`input.js:155-163`) take effect. Cursor is NOT force-reset here —
+	 * doing so would corrupt split-chunk pastes (a `\x05` byte mid-paste lands
+	 * verbatim in `pasteBuffer` and survives `handlePaste`'s narrow strip).
+	 * Cursor advances naturally via `insertCharacter` on typing/paste; cursor-
+	 * movement keys (Left/Right/Home/End/word-jumps) are now functional, with
+	 * the always-end visual cursor marker drawn independently by
+	 * `WrappingSelect.renderInlineInputRow`. `viewAdapter.apply` is called
+	 * directly without a reducer round-trip — preserves the D3 fast-path
+	 * latency profile from Phase 11.
+	 */
+	private handleIgnoreInline(data: string): void {
+		if (!this.state.inputMode) return;
+		this.inlineInput.handleInput(data);
+		this.viewAdapter.apply(this.state);
+	}
+
+	private runtime(): QuestionnaireRuntime {
+		return {
+			keybindings: getKeybindings(),
+			inputBuffer: this.inlineInput.getValue(),
+			questions: this.questions,
+			isMulti: this.isMulti,
+			currentItem: this.currentItem(),
+			items: this.itemsByTab[this.state.currentTab] ?? [],
+			collapseKey: this.collapseKey,
+		};
+	}
+
+	private applyContext(): ApplyContext {
+		return {
+			questions: this.questions,
+			itemsByTab: this.itemsByTab,
+		};
+	}
+
+	private currentItem(): WrappingSelectItem | undefined {
+		const arr = this.itemsByTab[this.state.currentTab] ?? [];
+		return this.state.optionIndex < arr.length ? arr[this.state.optionIndex] : undefined;
+	}
+
+	/**
+	 * Setter for the overlay handle, called by `ctx.ui.custom`'s `onHandle` callback once
+	 * the TUI has created the overlay. Until this is called, `set_overlay_hidden` effects
+	 * are no-ops — the session still tracks `state.collapsed` for the view layer.
+	 */
+	setOverlayHandle(handle: OverlayHandle): void {
+		this.overlayHandle = handle;
+	}
+
+	/**
+	 * Public toggle used by the raw terminal input listener registered in `execute()`.
+	 * pi-tui does not route input to a hidden overlay's `component.handleInput`, so the
+	 * raw listener (which fires for terminal data regardless of overlay visibility)
+	 * reaches the session through this method instead of the dispatch path. Routed
+	 * through `commit` so the transition stays in the reducer and the overlay hide
+	 * happens via the `set_overlay_hidden` effect like every other side effect.
+	 */
+	toggleCollapsedExternal(): void {
+		this.commit({ kind: "toggle_collapsed" });
+	}
+}

package/node_modules/@juicesharp/rpiv-ask-user-question/state/row-intent.ts

@@ -0,0 +1,143 @@
+import type { QuestionData } from "../tool/types.js";
+import type { WrappingSelectItem } from "../view/components/wrapping-select.js";
+
+/**
+ * Row kind discriminator. Single source of truth — derived from the runtime
+ * `WrappingSelectItem` union (`wrapping-select.ts:18-22`) so adding a new
+ * variant there forces a `ROW_INTENT_META` entry here (compile-time
+ * exhaustiveness via `Record<RowKind, …>`).
+ */
+export type RowKind = WrappingSelectItem["kind"];
+
+/**
+ * Sentinel kinds — the subset of `RowKind` representing protocol-driven rows
+ * (vs author-defined `option` rows). The auto-append walker, the reserved-label
+ * derivation, and `LABELS_BY_KIND` consumers iterate this list.
+ */
+export type SentinelKind = Exclude<RowKind, "option">;
+export const SENTINEL_KINDS: readonly SentinelKind[] = ["other", "next"];
+
+/**
+ * Per-kind static metadata. Pure data — no closures, no per-kind handler
+ * functions. Behavior-bearing branches (answer construction in
+ * `key-router.ts:69-99`, the Next-row render block in `multi-select-view.ts`,
+ * and the inline-Input render branch in `wrapping-select.ts`) keep their
+ * exhaustive switches and READ flags from this table.
+ *
+ * Adding a new sentinel:
+ *   1. Add the variant to `WrappingSelectItem` (`wrapping-select.ts:18-22`).
+ *   2. Add an entry here. Compile fails until both edits are present.
+ *   3. (If user-facing) author wherever the row is synthesized — typically
+ *      `buildItemsForQuestion` for main-list residents.
+ *
+ * Field semantics:
+ * - `label` — user-facing string. For `option` it's an empty placeholder
+ *   (per-instance labels come from `QuestionData.options[i].label`); every
+ *   sentinel uses its META entry as the single source of truth.
+ * - `reserved` — author-facing labels matching this string trigger
+ *   `reserved_label` at validation time. `RESERVED_LABEL_SET` is derived.
+ * - `livesInMainList` — true iff the row appears in `itemsByTab[i]`. Every
+ *   current sentinel lives in the main list (the `next` row is synthesized by
+ *   `sentinelsToAppend`).
+ * - `numbered` — true iff the row contributes to the main-list numbering.
+ *   Multi-select Next is the only `numbered=false` row that lives in the list.
+ * - `activatesInputMode` — true iff focusing the row should toggle
+ *   `state.inputMode = true`. Read by `state-reducer.ts` `nav` case.
+ * - `blocksMultiToggle` — in multiSelect mode, Space (and Enter-as-toggle)
+ *   on this row is suppressed. The Next sentinel is the only true.
+ * - `autoSubmitsInMulti` — in multiSelect mode, Enter on this row commits
+ *   the question (emits `multi_confirm`). The Next sentinel is the only true.
+ * - `autoAppendOnSingleSelect` — `buildItemsForQuestion` appends
+ *   this row when the question is single-select, regardless of whether any
+ *   option carries a `preview`. The "other" sentinel is the only true.
+ * - `autoAppendOnMultiSelect` — `buildItemsForQuestion` appends this row
+ *   when the question is multi-select. The `other` and `next` sentinels are both true.
+ */
+export interface RowIntentMeta {
+	label: string;
+	reserved: boolean;
+	livesInMainList: boolean;
+	numbered: boolean;
+	activatesInputMode: boolean;
+	blocksMultiToggle: boolean;
+	autoSubmitsInMulti: boolean;
+	autoAppendOnSingleSelect: boolean;
+	autoAppendOnMultiSelect: boolean;
+}
+
+export const ROW_INTENT_META: Record<RowKind, RowIntentMeta> = {
+	option: {
+		label: "",
+		reserved: false,
+		livesInMainList: true,
+		numbered: true,
+		activatesInputMode: false,
+		blocksMultiToggle: false,
+		autoSubmitsInMulti: false,
+		autoAppendOnSingleSelect: false,
+		autoAppendOnMultiSelect: false,
+	},
+	other: {
+		label: "Type something.",
+		reserved: true,
+		livesInMainList: true,
+		numbered: true,
+		activatesInputMode: true,
+		blocksMultiToggle: false,
+		autoSubmitsInMulti: false,
+		autoAppendOnSingleSelect: true,
+		autoAppendOnMultiSelect: true,
+	},
+	next: {
+		label: "Next",
+		reserved: true,
+		livesInMainList: true,
+		numbered: false,
+		activatesInputMode: false,
+		blocksMultiToggle: true,
+		autoSubmitsInMulti: true,
+		autoAppendOnSingleSelect: false,
+		autoAppendOnMultiSelect: true,
+	},
+};
+
+/**
+ * Kind-keyed label view. `option` is excluded — its label is per-instance,
+ * not per-kind. `types.ts#SENTINEL_LABELS` re-sources from here.
+ */
+export const LABELS_BY_KIND: { readonly [K in SentinelKind]: string } = {
+	other: ROW_INTENT_META.other.label,
+	next: ROW_INTENT_META.next.label,
+};
+
+/**
+ * Reserved-label set for runtime validation. Includes "Other" (a model-conditioned
+ * label that has no runtime kind) plus every sentinel with `reserved: true`.
+ */
+export const RESERVED_LABEL_SET: ReadonlySet<string> = new Set<string>([
+	"Other",
+	...SENTINEL_KINDS.filter((k) => ROW_INTENT_META[k].reserved).map((k) => ROW_INTENT_META[k].label),
+]);
+
+/**
+ * Walk the META table to synthesize sentinel rows for one question. The two
+ * append predicates are mutually exclusive in practice (`multiSelect` vs
+ * single-select) but the walker doesn't enforce that — adding a third bucket
+ * only requires a new META flag.
+ *
+ * Returns sentinel descriptors in declaration order of `SENTINEL_KINDS`. The
+ * caller wraps each with the `WrappingSelectItem` shape (kind + label).
+ */
+export function sentinelsToAppend(question: QuestionData): SentinelKind[] {
+	const out: SentinelKind[] = [];
+	for (const k of SENTINEL_KINDS) {
+		const meta = ROW_INTENT_META[k];
+		if (!meta.livesInMainList) continue;
+		if (question.multiSelect === true) {
+			if (meta.autoAppendOnMultiSelect) out.push(k);
+		} else {
+			if (meta.autoAppendOnSingleSelect) out.push(k);
+		}
+	}
+	return out;
+}

package/node_modules/@juicesharp/rpiv-ask-user-question/state/selectors/contract.ts

@@ -0,0 +1,24 @@
+import type { QuestionData } from "../../tool/types.js";
+import type { PreviewPaneProps } from "../../view/components/preview/preview-pane.js";
+import type { WrappingSelectItem } from "../../view/components/wrapping-select.js";
+import type { ActiveView, StatefulView } from "../../view/stateful-view.js";
+import type { TabComponents } from "../../view/tab-components.js";
+import type { QuestionnaireState } from "../state.js";
+
+export interface BindingContext {
+	readonly questions: readonly QuestionData[];
+	readonly itemsByTab: ReadonlyArray<readonly WrappingSelectItem[]>;
+	readonly totalQuestions: number;
+	readonly activeView: ActiveView;
+	readonly inputBuffer: string;
+	readonly inputCursorOffset: number | undefined;
+	readonly activePreviewPane: StatefulView<PreviewPaneProps>;
+}
+
+export interface PerTabBindingContext extends BindingContext {
+	readonly tab: TabComponents;
+	readonly i: number;
+}
+
+export type GlobalSelector<P> = (state: QuestionnaireState, ctx: BindingContext) => P;
+export type PerTabSelector<P> = (state: QuestionnaireState, ctx: PerTabBindingContext) => P;

package/node_modules/@juicesharp/rpiv-ask-user-question/state/selectors/derivations.ts

@@ -0,0 +1,40 @@
+import type { QuestionAnswer, QuestionData } from "../../tool/types.js";
+import type { WrappingSelectItem } from "../../view/components/wrapping-select.js";
+
+/**
+ * Which row in the active tab should be marked as "previously confirmed"? Drives the
+ * `WrappingSelect` confirmed-row indicator (label + ` ✔`) when the user navigates back
+ * to a question they already answered. Returns `undefined` when no marker should be drawn —
+ * multi-select handles its own `[✔]` boxes via `multiSelectChecked`, and a missing/non-matching
+ * answer (defensive) silently skips the marker.
+ */
+export function selectConfirmedIndicator(
+	questions: readonly QuestionData[],
+	currentTab: number,
+	answers: ReadonlyMap<number, QuestionAnswer>,
+	items: readonly WrappingSelectItem[],
+): { index: number; labelOverride?: string } | undefined {
+	const q = questions[currentTab];
+	if (!q || q.multiSelect === true) return undefined;
+	const prior = answers.get(currentTab);
+	if (!prior) return undefined;
+	if (prior.kind === "custom") {
+		const otherIndex = items.findIndex((it) => it.kind === "other");
+		if (otherIndex < 0) return undefined;
+		return { index: otherIndex, labelOverride: prior.answer ?? "" };
+	}
+	if (prior.kind !== "option" || typeof prior.answer !== "string") return undefined;
+	const index = items.findIndex((it) => it.kind === "option" && it.label === prior.answer);
+	if (index < 0) return undefined;
+	return { index };
+}
+
+/**
+ * Index of the preview pane to display for the current tab. The Submit tab (currentTab ===
+ * questions.length) reuses the last question's pane purely for layout — the strategy
+ * machinery picks the right body component independently. Defensive against `totalQuestions === 0`.
+ */
+export function selectActivePreviewPaneIndex(currentTab: number, totalQuestions: number): number {
+	if (totalQuestions <= 0) return 0;
+	return Math.min(currentTab, totalQuestions - 1);
+}

package/node_modules/@juicesharp/rpiv-ask-user-question/state/selectors/focus.ts

@@ -0,0 +1,17 @@
+import type { ActiveView } from "../../view/stateful-view.js";
+
+/**
+ * Discriminated focus selector — single source of truth for "which view owns
+ * focus this tick?" Priority order matches the dispatcher cascade
+ * (`key-router.ts`) and the reducer's defensive clears (`state-reducer.ts`).
+ *
+ * Priority: notes > submit > options.
+ */
+export function selectActiveView(
+	state: { notesVisible: boolean; currentTab: number },
+	totalQuestions: number,
+): ActiveView {
+	if (state.notesVisible) return "notes";
+	if (state.currentTab === totalQuestions) return "submit";
+	return "options";
+}

package/node_modules/@juicesharp/rpiv-ask-user-question/state/selectors/projections.ts

@@ -0,0 +1,99 @@
+import { MULTI_SUBMIT_LABEL, type MultiSelectViewProps } from "../../view/components/multi-select-view.js";
+import type { OptionListViewProps } from "../../view/components/option-list-view.js";
+import type { PreviewPaneProps } from "../../view/components/preview/preview-pane.js";
+import type { SubmitPickerProps } from "../../view/components/submit-picker.js";
+import type { TabBarProps } from "../../view/components/tab-bar.js";
+import type { DialogProps } from "../../view/dialog-builder.js";
+import { displayLabel } from "../i18n-bridge.js";
+import type { GlobalSelector, PerTabSelector } from "./contract.js";
+import { selectConfirmedIndicator } from "./derivations.js";
+
+export const selectMultiSelectProps: PerTabSelector<MultiSelectViewProps> = (state, ctx) => {
+	const question = ctx.questions[ctx.i];
+	if (!question) {
+		return {
+			rows: [],
+			other: {
+				active: false,
+				inputMode: false,
+				inputBuffer: ctx.inputBuffer,
+				inputCursorOffset: ctx.inputCursorOffset,
+			},
+			nextActive: false,
+			nextLabel: displayLabel("next"),
+		};
+	}
+	const focused = ctx.activeView === "options";
+	const rows: { checked: boolean; active: boolean }[] = [];
+	for (let i = 0; i < question.options.length; i++) {
+		rows.push({
+			checked: state.multiSelectChecked.has(i),
+			active: focused && i === state.optionIndex,
+		});
+	}
+	const otherActive = focused && state.optionIndex === question.options.length;
+	const nextActive = focused && state.optionIndex === question.options.length + 1;
+	const isLastQuestion = ctx.i === ctx.questions.length - 1;
+	const nextLabel = isLastQuestion ? MULTI_SUBMIT_LABEL : displayLabel("next");
+	return {
+		rows,
+		other: {
+			active: otherActive,
+			inputMode: state.inputMode,
+			inputBuffer: ctx.inputBuffer,
+			inputCursorOffset: ctx.inputCursorOffset,
+		},
+		nextActive,
+		nextLabel,
+	};
+};
+
+export const selectOptionListProps: PerTabSelector<OptionListViewProps> = (state, ctx) => {
+	const items = ctx.itemsByTab[ctx.i] ?? [];
+	const focused = ctx.activeView === "options";
+	const confirmed = selectConfirmedIndicator(ctx.questions, state.currentTab, state.answers, items);
+	return {
+		selectedIndex: state.optionIndex,
+		focused,
+		inputBuffer: ctx.inputBuffer,
+		inputCursorOffset: ctx.inputCursorOffset,
+		...(confirmed ? { confirmed } : {}),
+	};
+};
+
+export const selectSubmitPickerProps: GlobalSelector<SubmitPickerProps> = (state, ctx) => {
+	const focused = ctx.activeView === "submit";
+	return {
+		rows: [
+			{ active: focused && state.submitChoiceIndex === 0 },
+			{ active: focused && state.submitChoiceIndex === 1 },
+		],
+	};
+};
+
+export const selectPreviewPaneProps: PerTabSelector<PreviewPaneProps> = (state, ctx) => ({
+	notesVisible: state.notesVisible,
+	selectedIndex: state.optionIndex,
+	focused: ctx.activeView === "options",
+	inputMode: state.inputMode,
+});
+
+export const selectTabBarProps: GlobalSelector<TabBarProps> = (state, ctx) => {
+	const tabs = ctx.questions.map((q, i) => ({
+		label: q.header && q.header.length > 0 ? q.header : `Q${i + 1}`,
+		answered: state.answers.has(i),
+		active: i === state.currentTab,
+	}));
+	return {
+		tabs,
+		submit: {
+			active: state.currentTab === ctx.questions.length,
+			allAnswered: state.answers.size === ctx.questions.length && ctx.questions.length > 0,
+		},
+	};
+};
+
+export const selectDialogProps: GlobalSelector<DialogProps> = (state, ctx) => ({
+	state,
+	activePreviewPane: ctx.activePreviewPane,
+});