@bingjiang0611/rotom 0.1.0-alpha.0

package/extensions/third-party/node_modules/@juicesharp/rpiv-ask-user-question/state/key-router.ts

@@ -0,0 +1,310 @@
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import type { QuestionAnswer } from "../tool/types.js";
+import { ROW_INTENT_META } from "./row-intent.js";
+import type { QuestionnaireRuntime, QuestionnaireState } from "./state.js";
+
+const KEYBIND_UP = "tui.select.up";
+const KEYBIND_DOWN = "tui.select.down";
+const KEYBIND_CONFIRM = "tui.select.confirm";
+const KEYBIND_SUBMIT = "tui.input.submit";
+const KEYBIND_CANCEL = "tui.select.cancel";
+const KEYBIND_NEW_LINE = "tui.input.newLine";
+const KEYBIND_EDITOR_UP = "tui.editor.cursorUp";
+const KEYBIND_EDITOR_DOWN = "tui.editor.cursorDown";
+const KEYBIND_CLEAR = "tui.editor.deleteToLineStart";
+const KEYBIND_EXTERNAL_EDITOR = "app.editor.external";
+
+const NOTES_ACTIVATE_KEY = "n";
+const SPACE_KEY = " ";
+
+export type QuestionnaireAction =
+	| { kind: "nav"; nextIndex: number; inputValue: string }
+	| { kind: "input_clear" }
+	| { kind: "input_edit"; value: string }
+	| { kind: "input_replace"; value: string }
+	| { kind: "tab_switch"; nextTab: number }
+	| { kind: "confirm"; answer: QuestionAnswer; autoAdvanceTab?: number }
+	| { kind: "toggle"; index: number }
+	| { kind: "multi_confirm"; selected: string[]; autoAdvanceTab?: number }
+	| { kind: "cancel" }
+	| { kind: "notes_enter" }
+	| { kind: "notes_exit" }
+	| { kind: "submit" }
+	| { kind: "submit_nav"; nextIndex: 0 | 1 }
+	| { kind: "notes_forward"; data: string }
+	/** Flip `state.collapsed`. Always available, regardless of inner mode (see top intercept in `routeKey`). */
+	| { kind: "toggle_collapsed" }
+	| { kind: "ignore" };
+
+export interface QuestionnaireKeybindings {
+	matches(data: string, name: string): boolean;
+}
+
+// Confirm has two semantic sources: `tui.select.confirm` (the select-list default)
+// and `tui.input.submit` (the user's "send" key). A Slack-style configuration folds
+// `enter` into `tui.input.newLine` and moves submit elsewhere (e.g. `ctrl+enter`);
+// the newline checks below stay first, so without the submit source every confirm
+// branch would be shadowed by the collision and no key could confirm (#156). With
+// pi defaults both names resolve to `enter`, so matching either is equivalent.
+function isConfirm(kb: QuestionnaireKeybindings, data: string): boolean {
+	return kb.matches(data, KEYBIND_CONFIRM) || kb.matches(data, KEYBIND_SUBMIT);
+}
+
+export function wrapTab(index: number, total: number): number {
+	if (total <= 0) return 0;
+	return ((index % total) + total) % total;
+}
+
+export function allAnswered(state: QuestionnaireState, runtime: QuestionnaireRuntime): boolean {
+	if (runtime.questions.length === 0) return false;
+	for (let i = 0; i < runtime.questions.length; i++) {
+		if (!state.answers.has(i)) return false;
+	}
+	return true;
+}
+
+function totalTabs(runtime: QuestionnaireRuntime): number {
+	return runtime.isMulti ? runtime.questions.length + 1 : 1;
+}
+
+function computeAutoAdvanceTab(state: QuestionnaireState, runtime: QuestionnaireRuntime): number | undefined {
+	if (!runtime.isMulti) return undefined;
+	if (state.currentTab < runtime.questions.length - 1) return state.currentTab + 1;
+	return runtime.questions.length;
+}
+
+function buildSingleSelectAnswer(state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionAnswer | null {
+	const q = runtime.questions[state.currentTab];
+	if (!q) return null;
+
+	const item = runtime.currentItem;
+
+	if (state.inputMode) {
+		const label = runtime.inputBuffer;
+		return {
+			questionIndex: state.currentTab,
+			question: q.question,
+			kind: "custom",
+			answer: label.length > 0 ? label : null,
+		};
+	}
+	if (!item) return null;
+	if (item.kind === "other") {
+		return null;
+	}
+	if (item.kind === "next") {
+		return null;
+	}
+	return {
+		questionIndex: state.currentTab,
+		question: q.question,
+		kind: "option",
+		answer: item.label,
+	};
+}
+
+function buildMultiSelected(state: QuestionnaireState, runtime: QuestionnaireRuntime): string[] {
+	const q = runtime.questions[state.currentTab];
+	if (!q) return [];
+	const out: string[] = [];
+	for (let i = 0; i < q.options.length; i++) {
+		if (state.multiSelectChecked.has(i)) {
+			const label = q.options[i]?.label;
+			if (typeof label === "string") out.push(label);
+		}
+	}
+	return out;
+}
+
+function tabSwitchAction(
+	data: string,
+	state: QuestionnaireState,
+	runtime: QuestionnaireRuntime,
+): QuestionnaireAction | null {
+	if (!runtime.isMulti) return null;
+	const total = totalTabs(runtime);
+	if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+		return { kind: "tab_switch", nextTab: wrapTab(state.currentTab + 1, total) };
+	}
+	if (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)) {
+		return { kind: "tab_switch", nextTab: wrapTab(state.currentTab - 1, total) };
+	}
+	return null;
+}
+
+// DOWN at the last item wraps to the first (cycle through [option0, …, optionLast]).
+function nextNavOnDown(state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionnaireAction {
+	return {
+		kind: "nav",
+		nextIndex: wrapTab(state.optionIndex + 1, Math.max(1, runtime.items.length)),
+		inputValue: runtime.inputBuffer,
+	};
+}
+
+// UP at the first item wraps to the last (symmetric with nextNavOnDown).
+function prevNavOnUp(state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionnaireAction {
+	return {
+		kind: "nav",
+		nextIndex: wrapTab(state.optionIndex - 1, Math.max(1, runtime.items.length)),
+		inputValue: runtime.inputBuffer,
+	};
+}
+
+export function routeKey(data: string, state: QuestionnaireState, runtime: QuestionnaireRuntime): QuestionnaireAction {
+	const kb = runtime.keybindings;
+
+	// Collapse/expand toggle is a UI-level affordance — intercepted at the top so it
+	// works from every inner state (notes, inputMode, submit tab, multi-select)
+	// without reaching any branch that would otherwise consume the keystroke. The
+	// questionnaire overlay is fully hidden via `OverlayHandle.setHidden(true)` while
+	// collapsed; pi-tui's overlay stack updates accordingly, so overlay-aware consumers
+	// (e.g. `pi-station`) see no visible modal and chat scroll resumes. The toggle key is
+	// also captured at the raw terminal level via `ctx.ui.onTerminalInput` so it still
+	// routes here when the overlay is hidden (pi-tui does not deliver input to a hidden
+	// overlay's `component.handleInput`).
+	//
+	// The default `ctrl+]` is free in every mainstream macOS terminal (Terminal.app,
+	// iTerm2, Warp), every multiplexer (tmux, zellij, screen — none use it as a prefix),
+	// and the legacy telnet/ssh escape role doesn't apply because our overlay runs
+	// in-process. It is, however, awkward on keyboard layouts where `]` is on the
+	// shifted layer (Latin American `es-AR`/`es-MX` require `Ctrl+Shift+}` for `Ctrl+]`)
+	// — use the `collapseKey` config field to override.
+	// Treat a missing/non-string key as disabled. This can occur at runtime when
+	// a long-lived Pi process retains an older outer module while a package update
+	// replaces the lazily imported QuestionnaireSession graph on disk. Passing
+	// undefined into matchesKey reaches parseKeyId().toLowerCase() and crashes the
+	// entire host process, so keep the runtime boundary defensive even though the
+	// TypeScript contract requires a string.
+	if (
+		typeof runtime.collapseKey === "string" &&
+		runtime.collapseKey !== "off" &&
+		matchesKey(data, runtime.collapseKey as Parameters<typeof matchesKey>[1])
+	) {
+		return { kind: "toggle_collapsed" };
+	}
+
+	// Collapsed-mode lockout: while collapsed, swallow every keystroke except cancel so
+	// the user can read the now-uncovered transcript without accidentally mutating
+	// answers or notes. The collapse toggle itself is already handled above.
+	if (state.collapsed) {
+		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+		return { kind: "ignore" };
+	}
+
+	if (state.notesVisible) {
+		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "notes_exit" };
+		if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "notes_forward", data };
+		if (isConfirm(kb, data)) return { kind: "notes_exit" };
+		return { kind: "notes_forward", data };
+	}
+
+	if (state.inputMode) {
+		// Newline takes precedence over confirmation if a user configuration binds
+		// the same physical key to both semantic actions.
+		if (kb.matches(data, KEYBIND_NEW_LINE)) return { kind: "ignore" };
+		if (isConfirm(kb, data)) {
+			const answer = buildSingleSelectAnswer(state, runtime);
+			if (!answer) return { kind: "ignore" };
+			return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
+		}
+		// Treat Pi's Ctrl+U line-kill binding as an explicit whole-draft clear,
+		// independent of the current cursor position.
+		if (kb.matches(data, KEYBIND_CLEAR)) return { kind: "input_clear" };
+		if (kb.matches(data, KEYBIND_EXTERNAL_EDITOR)) return { kind: "input_edit", value: runtime.inputBuffer };
+		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+		if (kb.matches(data, KEYBIND_EDITOR_UP) && runtime.canMoveInputUp) return { kind: "ignore" };
+		if (kb.matches(data, KEYBIND_EDITOR_DOWN) && runtime.canMoveInputDown) {
+			return { kind: "ignore" };
+		}
+		if (kb.matches(data, KEYBIND_UP)) return prevNavOnUp(state, runtime);
+		if (kb.matches(data, KEYBIND_DOWN)) return nextNavOnDown(state, runtime);
+		return { kind: "ignore" };
+	}
+
+	if (runtime.isMulti && state.currentTab === runtime.questions.length) {
+		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+		const tab = tabSwitchAction(data, state, runtime);
+		if (tab) return tab;
+		if (kb.matches(data, KEYBIND_UP) || kb.matches(data, KEYBIND_DOWN)) {
+			const delta = kb.matches(data, KEYBIND_DOWN) ? 1 : -1;
+			const next = wrapTab(state.submitChoiceIndex + delta, 2);
+			return { kind: "submit_nav", nextIndex: (next === 1 ? 1 : 0) as 0 | 1 };
+		}
+		if (isConfirm(kb, data)) {
+			// D1 (revised): Submit always submits; Cancel always cancels. The warning header
+			// is informational only — `allAnswered(state)` no longer gates submission. Partial
+			// answers flow through `orderedAnswers()` in the host.
+			return state.submitChoiceIndex === 1 ? { kind: "cancel" } : { kind: "submit" };
+		}
+		return { kind: "ignore" };
+	}
+
+	const tab = tabSwitchAction(data, state, runtime);
+	if (tab) return tab;
+
+	const q = runtime.questions[state.currentTab];
+	if (!q) return { kind: "ignore" };
+
+	// Universal `n` activation (FR-1): the notes editor opens on every question tab
+	// (single- or multi-select, preview or no-preview). The blocks above already
+	// swallow `n` when it should NOT reach here — notesVisible forwards to the
+	// notes Input, inputMode forwards to the inline Input, the submit-tab block
+	// ignores it, and tabSwitchAction ignores it — so by the time we reach this
+	// gate, `n` is unambiguously a notes-enter request. Row intent (Next sentinel,
+	// "Type something.") is irrelevant: the gate sits ABOVE the multi-select
+	// toggle block and the Next sentinel never activates inputMode, so `n` is
+	// neither swallowed earlier nor blocked by `blocksMultiToggle`.
+	if (data === NOTES_ACTIVATE_KEY) {
+		return { kind: "notes_enter" };
+	}
+
+	if (kb.matches(data, KEYBIND_UP)) {
+		return prevNavOnUp(state, runtime);
+	}
+	if (kb.matches(data, KEYBIND_DOWN)) {
+		return nextNavOnDown(state, runtime);
+	}
+
+	if (q.multiSelect) {
+		const focusedKind = runtime.currentItem?.kind;
+		const focusedMeta = focusedKind ? ROW_INTENT_META[focusedKind] : undefined;
+		// Space toggles the focused row's checkbox. Suppressed on rows whose META declares
+		// `blocksMultiToggle` (the Next sentinel) or `activatesInputMode` (the "Type
+		// something." row — it is an inline input, not a checkable option).
+		if (data === SPACE_KEY) {
+			if (focusedMeta?.blocksMultiToggle) return { kind: "ignore" };
+			if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
+			return { kind: "toggle", index: state.optionIndex };
+		}
+		if (isConfirm(kb, data)) {
+			// Enter on the "Type something." row is handled by the inputMode block above
+			// (→ confirm kind:"custom"). Defensive: never enter the toggle/multi_confirm
+			// path for an inputMode-activating row.
+			if (focusedMeta?.activatesInputMode) return { kind: "ignore" };
+			// Enter on a regular row toggles (matching Space) — committing the question is now
+			// gated behind explicit focus on a row whose META declares `autoSubmitsInMulti`
+			// (the Next sentinel), so Enter on options is a no-cost way to flip checkboxes
+			// without leaving the keyboard home row.
+			if (!focusedMeta?.autoSubmitsInMulti) return { kind: "toggle", index: state.optionIndex };
+			// Enter on Next: carry autoAdvanceTab so the host can advance to the next tab in
+			// multi-question mode, OR submit the dialog in single-question mode
+			// (autoAdvanceTab === undefined when !isMulti). Without this, a single multi-select
+			// question would have no way to commit at all.
+			return {
+				kind: "multi_confirm",
+				selected: buildMultiSelected(state, runtime),
+				autoAdvanceTab: computeAutoAdvanceTab(state, runtime),
+			};
+		}
+		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+		return { kind: "ignore" };
+	}
+
+	if (isConfirm(kb, data)) {
+		const answer = buildSingleSelectAnswer(state, runtime);
+		if (!answer) return { kind: "ignore" };
+		return { kind: "confirm", answer, autoAdvanceTab: computeAutoAdvanceTab(state, runtime) };
+	}
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	return { kind: "ignore" };
+}

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

@@ -0,0 +1,250 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Editor, OverlayHandle, TUI } 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";
+
+export interface QuestionnaireSessionConfig {
+	tui: TUI;
+	theme: Theme;
+	params: QuestionParams;
+	itemsByTab: WrappingSelectItem[][];
+	done: (result: QuestionnaireResult) => void;
+	keybindings: QuestionnaireRuntime["keybindings"];
+	/** Opens Pi's configured external editor. Resolve `undefined` on a reported launch failure. */
+	editInput: (value: string) => Promise<string | undefined>;
+	/** 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(),
+		customDraftsByTab: new Map(),
+		notesByTab: new Map(),
+		submitChoiceIndex: 0,
+		notesDraft: "",
+		collapsed: false,
+	};
+}
+
+/**
+ * Slim runtime: owns the canonical state cell, the headless editor cells, the
+ * notes-draft mirror, 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: Editor;
+	private readonly inlineInput: Editor;
+	private readonly viewAdapter: QuestionnairePropsAdapter;
+	private readonly keybindings: QuestionnaireRuntime["keybindings"];
+	private readonly editInput: QuestionnaireSessionConfig["editInput"];
+	private readonly collapseKey: string;
+	private inputEditorOpen = false;
+
+	/**
+	 * 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.keybindings = config.keybindings;
+		this.editInput = config.editInput;
+		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 {
+		if (this.inputEditorOpen) return;
+		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 {
+		// Drafts restore through Editor.setText, which clears the backing paste map —
+		// read expanded so stored drafts never orphan a paste marker.
+		const draft = this.notesInput.getExpandedText?.() ?? this.notesInput.getText();
+		return s.notesDraft === draft ? s : { ...s, notesDraft: draft };
+	}
+
+	private runEffect(effect: Effect): void {
+		switch (effect.kind) {
+			case "set_input_buffer":
+				this.inlineInput.setText(effect.value);
+				return;
+			case "clear_input_buffer":
+				this.inlineInput.setText("");
+				return;
+			case "open_input_editor":
+				if (this.inputEditorOpen) return;
+				this.inputEditorOpen = true;
+				void this.editInput(effect.value).then(
+					(value) => {
+						this.inputEditorOpen = false;
+						if (value !== undefined) this.commit({ kind: "input_replace", value });
+					},
+					() => {
+						// The host callback reports launch errors; retain the draft and restore input handling.
+						this.inputEditorOpen = false;
+					},
+				);
+				return;
+			case "set_notes_value":
+				this.notesInput.setText(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 text editing to Pi's headless
+	 * multiline `Editor`, including paste, undo, cursor movement, and configured
+	 * `tui.input.newLine` handling. `viewAdapter.apply` then projects its public
+	 * text/cursor state without a reducer round-trip.
+	 */
+	private handleIgnoreInline(data: string): void {
+		if (!this.state.inputMode) return;
+		this.inlineInput.handleInput(data);
+		this.viewAdapter.apply(this.state);
+	}
+
+	private runtime(): QuestionnaireRuntime {
+		const cursor = this.inlineInput.getCursor();
+		const lastLine = this.inlineInput.getLines().length - 1;
+		return {
+			keybindings: this.keybindings,
+			inputBuffer: this.inlineInput.getExpandedText?.() ?? this.inlineInput.getText(),
+			canMoveInputUp: cursor.line > 0,
+			canMoveInputDown: cursor.line < lastLine,
+			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 {
+		if (!this.inputEditorOpen) this.commit({ kind: "toggle_collapsed" });
+	}
+}