@estebanforge/pi-tui-dialogs 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 EstebanForge
+
+Portions of the dialog pattern (frame, menu, and input dialog structure) are
+adapted from pi-subagent-manager, MIT License, Copyright (c) 2026
+pi-subagent contributors (https://github.com/championswimmer/pi-subagent-manager).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @estebanforge/pi-tui-dialogs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framed TUI dialog kit for `@estebanforge` Pi Coding Agent extensions. One
+settings/picker pattern for every extension instead of one per package.
+
+Dialog pattern adapted from
+[pi-subagent-manager](https://github.com/championswimmer/pi-subagent-manager)
+(MIT); tabs and type-to-search follow the Zellij modal they replace.
+
+## What it ships
+
+- `frameDialog` / `dialogHeight` / `DIALOG_OPTIONS` — shared rounded frame:
+  title in the top border, body, footer line above the bottom border, padded to
+  a stable height so centered overlays do not jump between views.
+- `DialogMenu` / `dialogMenu` — framed menu with `label │ value` rows, a
+  counter line, a muted help panel for the selected row, optional tab groups
+  (left/right to switch) and type-to-search within the active tab. Rows with
+  `values` cycle in place on Enter; rows with `onEdit` run a custom action and
+  keep the menu open; plain rows resolve the menu with their id.
+- `dialogInput` — framed single-line input with placeholder, help lines, and
+  optional `validate`: return an error string to keep the dialog open with the
+  message inline, return `undefined` to accept.
+- `dialogChoice` — framed single-choice modal: one decision statement (wraps),
+  a closed option list of 1 to `MAX_CHOICE_OPTIONS` (10) options with unique
+  values and an optional preselect. Enter resolves the chosen option's value;
+  esc resolves `undefined` (the escape hatch). Caller-contract violations (0
+  or >10 options, duplicate values, unknown preselect) throw before any
+  overlay opens.
+- `canOpenDialog` — headless guard for non-TUI modes.
+
+## Usage
+
+```ts
+import { canOpenDialog, dialogChoice, dialogInput, dialogMenu, DialogMenu } from "@estebanforge/pi-tui-dialogs";
+
+await ctx.ui.custom(
+	(host, theme, _keys, done) =>
+		new DialogMenu(
+			host,
+			theme,
+			{
+				title: "My extension",
+				subtitle: "Project file: .pi/my-extension.json",
+				tabs: [
+					{ label: "General", rows: [{ id: "enabled", label: "Enabled", value: "on", values: ["on", "off"], help: "Master switch." }] },
+					{ label: "Limits", rows: [{ id: "cap", label: "Cap", value: "100", onEdit: () => void dialogInput(ctx, "Cap", { initial: "100", validate: (raw) => (/^\d+$/.test(raw) ? undefined : "must be a number") }) }] },
+				],
+				onChange: (id, value) => save(id, value),
+			},
+			() => done(),
+		),
+	// DIALOG_OPTIONS centers the dialog near fullscreen
+);
+```
+
+A closed choice reads the same way:
+
+```ts
+const engine = await dialogChoice(ctx, "Choose your engine", {
+	description: "Which engine runs your turns? Switch anytime with /engine.",
+	options: [
+		{ value: "fast", label: "Fast", description: "default · lighter" },
+		{ value: "deep", label: "Deep", description: "downloads a big binary" },
+	],
+	selected: "fast",
+});
+// engine === undefined means esc: decide later, persist nothing.
+```
+
+Plain library, no Pi entrypoint: depend on it and Pi installs it transitively.
+
+## License
+
+MIT. See LICENSE for the pi-subagent-manager attribution.

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@estebanforge/pi-tui-dialogs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Framed TUI dialog kit for @estebanforge Pi extensions: bordered settings menus with label/value columns, help panel, tabs, type-to-search, and validated input dialogs. Dialog pattern adapted from pi-subagent-manager (MIT). Plain library, no Pi entrypoint: consumers depend on it and Pi installs it transitively.",
+  "keywords": [
+    "pi",
+    "tui",
+    "dialog",
+    "settings"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "EstebanForge",
+    "email": "esteban@attitude.cl",
+    "url": "https://actitud.xyz"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EstebanForge/pi-extensions.git",
+    "directory": "packages/pi-tui-dialogs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "sideEffects": "false"
+}

package/src/choice.ts

@@ -0,0 +1,153 @@
+// Framed single-choice modal: one decision statement plus a closed list of
+// options, esc cancels. SelectList inside the shared frame. Pattern extracted
+// from pi-antigravity-bridge's first-run engine picker.
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { wrapTextWithAnsi, type SelectItem, SelectList } from "@earendil-works/pi-tui";
+import { DIALOG_OPTIONS, dialogHeight, dialogText, frameDialog, type DialogHost } from "./frame.js";
+import type { DialogContext } from "./menu.js";
+
+/** Hard cap on the option list. A closed choice stays scannable; past ten
+ *  options the caller should filter or paginate before asking. */
+export const MAX_CHOICE_OPTIONS = 10;
+
+/** One closed choice. Values are the resolved contract: they must be unique
+ *  and stable across releases (callers persist them). */
+export interface ChoiceOption {
+	value: string;
+	label: string;
+	/** One-line hint under the label; the list truncates long lines. */
+	description?: string;
+}
+
+export interface ChoiceDialogOptions {
+	/** Options in answer order; the first is preselected unless `selected`. */
+	options: ChoiceOption[];
+	/** What the user is deciding; wraps to the frame width. */
+	description?: string;
+	/** Preselected option value; must match one option. */
+	selected?: string;
+	/** Footer hint; default "↑↓ navigate · enter select · esc cancel". */
+	footer?: string | readonly string[];
+}
+
+/** Caller-contract validation. Throws before any overlay opens: a choice
+ *  modal rendered with 0 options, duplicate values, or a bogus preselect is
+ *  a programming error, not a user-facing state. Used directly by ChoiceView
+ *  (sync throw) and by dialogChoice (which rejects). */
+export function assertChoiceOptions(options: ChoiceOption[], selected?: string): void {
+	if (options.length < 1) {
+		throw new RangeError(`dialogChoice needs at least 1 option, got ${options.length}`);
+	}
+	if (options.length > MAX_CHOICE_OPTIONS) {
+		throw new RangeError(`dialogChoice takes at most ${MAX_CHOICE_OPTIONS} options, got ${options.length}`);
+	}
+	const seen = new Set<string>();
+	for (const option of options) {
+		if (seen.has(option.value)) {
+			throw new RangeError(`dialogChoice options have duplicate value "${option.value}"`);
+		}
+		seen.add(option.value);
+	}
+	if (selected !== undefined && !seen.has(selected)) {
+		throw new RangeError(`dialogChoice selected "${selected}" matches no option`);
+	}
+}
+
+/** Hostable framed choice component. `done` resolves the decision: the
+ *  chosen value, or undefined on esc. Render it inside your own overlay and
+ *  route input to it while it is active. */
+export class ChoiceView {
+	private readonly list: SelectList;
+	private settled = false;
+
+	constructor(
+		private host: DialogHost,
+		private theme: Theme,
+		readonly title: string,
+		readonly options: ChoiceDialogOptions,
+		private readonly done: (value: string | undefined) => void,
+	) {
+		assertChoiceOptions(options.options, options.selected);
+		const items: SelectItem[] = options.options.map((option) => ({
+			value: option.value,
+			label: dialogText(option.label),
+			description: option.description === undefined ? undefined : dialogText(option.description),
+		}));
+		this.list = new SelectList(items, items.length, {
+			selectedPrefix: (t: string) => theme.fg("accent", t),
+			selectedText: (t: string) => theme.fg("accent", t),
+			description: (t: string) => theme.fg("muted", t),
+			scrollInfo: (t: string) => theme.fg("dim", t),
+			noMatch: (t: string) => theme.fg("warning", t),
+		});
+		if (options.selected !== undefined) {
+			this.list.setSelectedIndex(items.findIndex((item) => item.value === options.selected));
+		}
+		this.list.onSelect = (item) => this.finish(item.value);
+		this.list.onCancel = () => this.finish(undefined);
+	}
+
+	private finish(value: string | undefined): void {
+		if (this.settled) return;
+		this.settled = true;
+		this.done(value);
+	}
+
+	handleInput(data: string): void {
+		this.list.handleInput(data);
+		this.host.requestRender();
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const inner = Math.max(1, width - 4);
+		const height = dialogHeight(this.host);
+		const descriptionLines = this.options.description
+			? wrapTextWithAnsi(dialogText(this.options.description), inner).map((line) =>
+					this.theme.fg("muted", ` ${line}`),
+				)
+			: [];
+		// Window the list to what the frame can actually show (DialogMenu's
+		// viewport rule). frameDialog clips the body to height - 4; without
+		// this the SelectList would render all options and let the selection
+		// move into clipped, invisible lines on short terminals or with long
+		// descriptions. The - 3 covers the two blank separators plus the
+		// "(n/m)" scroll line SelectList appends whenever the list is windowed
+		// (clipping that line hides the position hint). maxVisible is
+		// compile-time private on SelectList but a plain field at runtime;
+		// re-assigning it per render is the intended windowing knob (the
+		// constructor value only sized the initial view).
+		const listBudget = Math.max(1, height - 4 - descriptionLines.length - 3);
+		(this.list as unknown as { maxVisible: number }).maxVisible = listBudget;
+		return frameDialog(
+			this.theme,
+			width,
+			dialogHeight(this.host),
+			this.title,
+			[
+				"",
+				...descriptionLines,
+				"",
+				...this.list.render(inner).map((line) => ` ${line}`),
+			],
+			this.options.footer ?? "↑↓ navigate · enter select · esc cancel",
+		);
+	}
+}
+
+/** Run one framed choice overlay. Resolves with the chosen option value, or
+ *  undefined when cancelled (esc). Contract violations reject the promise
+ *  before the overlay opens. */
+export async function dialogChoice(
+	ctx: DialogContext,
+	title: string,
+	options: ChoiceDialogOptions,
+): Promise<string | undefined> {
+	// Fail before the overlay opens so a bad caller contract cannot flash UI.
+	assertChoiceOptions(options.options, options.selected);
+	return ctx.ui.custom<string | undefined>(
+		(host, theme, _keys, done) => new ChoiceView(host, theme, title, options, done),
+		DIALOG_OPTIONS,
+	);
+}

package/src/frame.ts

@@ -0,0 +1,86 @@
+// Framed dialog primitives. Dialog pattern adapted from pi-subagent-manager
+// (MIT, Copyright (c) 2026 pi-subagent contributors); see LICENSE.
+import {
+	stripTerminalSequences,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+
+/** Minimal host a dialog needs: re-render requests plus terminal rows. */
+export interface DialogHost {
+	requestRender(force?: boolean): void;
+	terminal?: { rows: number };
+}
+
+/** Overlay options shared by every dialog: centered, near-fullscreen. */
+export const DIALOG_OPTIONS = {
+	overlay: true,
+	overlayOptions: {
+		anchor: "center",
+		width: "90%",
+		maxHeight: "90%",
+		margin: 1,
+	},
+} as const;
+
+/** Strip ANSI and control characters from untrusted row text. */
+export function dialogText(text: string): string {
+	return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
+}
+
+/** Match Pi's overlay height calculation; maxHeight alone would clip the bottom border. */
+export function dialogHeight(host: { terminal?: { rows: number } }): number {
+	const rows = host.terminal?.rows ?? 24;
+	return Math.max(1, Math.min(rows - 2, Math.floor(rows * 0.9)));
+}
+
+/** Render the shared rounded frame: title in the top border, body lines, footer above the bottom border.
+ *  A string-array footer picks the first variant that fits the width (RTK undertitle behavior). */
+export function frameDialog(
+	theme: FrameTheme,
+	width: number,
+	height: number,
+	title: string,
+	body: string[],
+	footer: string | readonly string[],
+): string[] {
+	if (width <= 0 || height <= 0) return [];
+	const fit = (text: string, columns: number) => {
+		const clipped = truncateToWidth(text, Math.max(0, columns), "", true);
+		return clipped + " ".repeat(Math.max(0, columns - visibleWidth(clipped)));
+	};
+	if (width < 4 || height < 4) {
+		return [fit(theme.fg("muted", dialogText(title)), width)];
+	}
+	const inner = width - 2;
+	const line = (text: string) => theme.fg("border", "│") + fit(text, inner) + theme.fg("border", "│");
+	const footerText = pickFooterVariant(footer, inner - 3);
+	const heading = truncateToWidth(` ${dialogText(title)} `, inner, "");
+	const top = theme.fg("border", "╭" + heading + "─".repeat(Math.max(0, inner - visibleWidth(heading))) + "╮");
+	// Pad to the full frame so centered overlays keep the same bounds between views.
+	const budget = height - 4;
+	const padded = body.slice(0, budget);
+	while (padded.length < budget) padded.push("");
+	const content = padded.map(line);
+	return [
+		top,
+		...content,
+		theme.fg("border", "├" + "─".repeat(inner) + "┤"),
+		line(theme.fg("dim", dialogText(footerText))),
+		theme.fg("border", "╰" + "─".repeat(inner) + "╯"),
+	];
+}
+
+/** The theme color slots dialogs use, a subset of Pi's Theme fg names. */
+export type FrameTheme = {
+	fg(color: "border" | "muted" | "dim", text: string): string;
+};
+
+function pickFooterVariant(footer: string | readonly string[], maxWidth: number): string {
+	if (typeof footer === "string") return footer;
+	if (footer.length === 0) return "";
+	for (const variant of footer) {
+		if (visibleWidth(variant) <= maxWidth) return variant;
+	}
+	return footer[footer.length - 1]!;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Framed TUI dialog kit for @estebanforge Pi extensions. Dialog pattern
+// adapted from pi-subagent-manager (MIT); see LICENSE for attribution.
+export {
+	DIALOG_OPTIONS,
+	dialogHeight,
+	dialogText,
+	frameDialog,
+	type DialogHost,
+	type FrameTheme,
+} from "./frame.js";
+export {
+	canOpenDialog,
+	dialogMenu,
+	DialogMenu,
+	type DialogContext,
+	type DialogRow,
+	type DialogTab,
+} from "./menu.js";
+export { dialogInput, InputView, type DialogInputOptions } from "./input.js";
+export {
+	assertChoiceOptions,
+	ChoiceView,
+	dialogChoice,
+	MAX_CHOICE_OPTIONS,
+	type ChoiceDialogOptions,
+	type ChoiceOption,
+} from "./choice.js";

package/src/input.ts

@@ -0,0 +1,107 @@
+// Framed single-line input with optional inline validation. Hostable view for
+// composing inside an existing overlay (settings menu editor slot) plus a
+// ctx-level dialogInput wrapper. Pattern adapted from pi-subagent-manager
+// (MIT, Copyright (c) 2026 pi-subagent contributors).
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Input, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { DIALOG_OPTIONS, dialogHeight, dialogText, frameDialog, type DialogHost } from "./frame.js";
+import type { DialogContext } from "./menu.js";
+
+export interface DialogInputOptions {
+	/** Starting value (cursor lands at its end). */
+	initial?: string;
+	/** Muted help lines under the field. */
+	help?: string;
+	/** Placeholder while the field is empty. */
+	placeholder?: string;
+	/** Return an error string to keep the editor open with the message inline;
+	 *  return undefined to accept. */
+	validate?: (raw: string) => string | undefined;
+}
+
+/** Hostable framed input component. `done` resolves the editing session:
+ *  accepted string, or undefined on esc. Render it inside your own overlay
+ *  and route input to it while it is active. */
+export class InputView {
+	private readonly input: Input;
+	private errorText = "";
+	private settled = false;
+
+	constructor(
+		private host: DialogHost,
+		private theme: Theme,
+		readonly title: string,
+		readonly options: DialogInputOptions,
+		private readonly done: (value: string | undefined) => void,
+	) {
+		this.input = new Input(options.placeholder ? { placeholder: options.placeholder } : undefined);
+		this.input.setValue(dialogText(options.initial ?? ""));
+		// pi-tui Input starts the cursor at column 0; place it at the end of the
+		// prefilled value (ctrl+e is the cursor-end binding) so editing behaves
+		// the way the prefilled field looks.
+		this.input.handleInput("\x05");
+		this.input.focused = true;
+		this.input.onSubmit = (value) => {
+			const message = this.options.validate?.(value);
+			if (message) {
+				this.errorText = message;
+				this.host.requestRender();
+				return;
+			}
+			this.finish(value);
+		};
+		this.input.onEscape = () => this.finish(undefined);
+	}
+
+	private finish(value: string | undefined): void {
+		if (this.settled) return;
+		this.settled = true;
+		this.done(value);
+	}
+
+	handleInput(data: string): void {
+		this.input.handleInput(data);
+		this.host.requestRender();
+	}
+
+	invalidate(): void {
+		this.input.invalidate();
+	}
+
+	render(width: number): string[] {
+		const helpLines = this.options.help
+			? wrapTextWithAnsi(dialogText(this.options.help), Math.max(1, width - 5))
+				.map((line) => this.theme.fg("muted", ` ${line}`))
+			: [];
+		const errorLines = this.errorText
+			? [this.theme.fg("error", ` ${dialogText(this.errorText)}`)]
+			: [];
+		return frameDialog(
+			this.theme,
+			width,
+			dialogHeight(this.host),
+			this.title,
+			[
+				"",
+				...this.input.render(Math.max(1, width - 4)).map((line) => ` ${line}`),
+				...errorLines,
+				"",
+				...helpLines,
+			],
+			"Enter apply · Esc cancel",
+		);
+	}
+}
+
+/** Run one framed input overlay. Resolves with the accepted value, or
+ *  undefined when cancelled. */
+export function dialogInput(
+	ctx: DialogContext,
+	title: string,
+	options: DialogInputOptions = {},
+): Promise<string | undefined> {
+	return ctx.ui.custom<string | undefined>(
+		(host, theme, _keys, done) => new InputView(host, theme, title, options, done),
+		DIALOG_OPTIONS,
+	);
+}

package/src/menu.ts

@@ -0,0 +1,282 @@
+// Framed settings/picker menu: RTK optimizer's modal contract (SettingItem
+// rows, tabs, type-to-search, Enter/Space cycle, live onChange + updateValue
+// sync) rendered with the pi-subagent-manager dialog pattern (framed rows,
+// help panel). Subagent-manager portions MIT, Copyright (c) 2026 pi-subagent
+// contributors.
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { getKeybindings, matchesKey, Key, truncateToWidth, visibleWidth, wrapTextWithAnsi, type SettingItem } from "@earendil-works/pi-tui";
+import { DIALOG_OPTIONS, dialogHeight, dialogText, frameDialog, type DialogHost } from "./frame.js";
+
+/** A menu row is a pi-tui SettingItem; `onEdit` additionally opens a custom
+ *  editor (input dialog, submenu) on Enter and keeps the menu open. Rows with
+ *  `values` cycle in place on Enter/Space; rows with neither resolve the menu
+ *  with their id. */
+export interface DialogRow extends SettingItem {
+	onEdit?: () => void;
+}
+
+export interface DialogTab {
+	label: string;
+	rows: DialogRow[];
+}
+
+export interface DialogMenuOptions {
+	title: string;
+	/** Muted line under the tab bar / counter (e.g. the settings file path). */
+	subtitle?: string;
+	/** Flat rows; ignored when `tabs` is provided. */
+	rows?: DialogRow[];
+	/** Row groups; left/right switch the active tab. */
+	tabs?: DialogTab[];
+	selectedId?: string;
+	/** Footer hint; a string array picks the first variant that fits the width. */
+	footer?: string | readonly string[];
+	/** Type-to-filter within the active tab. Default on. */
+	search?: boolean;
+	/** Called after an in-place cycle commits a new value. */
+	onChange?: (id: string, value: string) => void;
+}
+
+const DEFAULT_FOOTER = "↑↓ navigate · Enter select · Esc close";
+
+export class DialogMenu {
+	private selected = 0;
+	private viewport = 1;
+	private query = "";
+	private activeTab = 0;
+
+	constructor(
+		private host: DialogHost,
+		private theme: Theme,
+		readonly options: DialogMenuOptions,
+		private done: (selectedId: string | undefined) => void,
+	) {}
+
+	private get tabs(): DialogTab[] {
+		return this.options.tabs ?? (this.options.rows ? [{ label: "", rows: this.options.rows }] : []);
+	}
+
+	private get rows(): DialogRow[] {
+		const tab = this.tabs[this.activeTab];
+		return tab ? tab.rows : [];
+	}
+
+	private get filtered(): DialogRow[] {
+		const rows = this.rows;
+		const q = this.query.trim().toLowerCase();
+		if (!q) return rows;
+		return rows.filter((row) =>
+			`${row.label} ${row.currentValue} ${row.id}`.toLowerCase().includes(q),
+		);
+	}
+
+	getSelectedId(): string | undefined {
+		return this.filtered[this.selected]?.id;
+	}
+
+	/** External value sync: patch one row's displayed value by id, all tabs. */
+	updateValue(id: string, value: string): void {
+		for (const tab of this.tabs) {
+			const row = tab.rows.find((r) => r.id === id);
+			if (row) row.currentValue = value;
+		}
+	}
+
+	private clampSelection(): void {
+		const count = this.filtered.length;
+		this.selected = Math.max(0, Math.min(count - 1, this.selected));
+	}
+
+	private move(offset: number): void {
+		this.clampSelection();
+		const count = this.filtered.length;
+		this.selected = Math.max(0, Math.min(count - 1, this.selected + offset));
+		this.host.requestRender();
+	}
+
+	private cycle(): void {
+		const row = this.filtered[this.selected];
+		if (!row?.values?.length) return;
+		const current = row.currentValue;
+		const at = row.values.indexOf(current);
+		const next = row.values[(at + 1) % row.values.length] ?? row.values[0] ?? current;
+		row.currentValue = next;
+		this.options.onChange?.(row.id, next);
+		this.host.requestRender();
+	}
+
+	private switchTab(direction: number): void {
+		if (this.tabs.length < 2) return;
+		const count = this.tabs.length;
+		this.activeTab = ((this.activeTab + direction) % count + count) % count;
+		this.query = "";
+		this.selected = 0;
+		this.host.requestRender();
+	}
+
+	private activate(): void {
+		const row = this.filtered[this.selected];
+		if (!row) return this.done(undefined);
+		if (row.values?.length) return this.cycle();
+		if (row.onEdit) {
+			row.onEdit();
+			return;
+		}
+		this.done(this.getSelectedId());
+	}
+
+	handleInput(data: string): void {
+		const keys = getKeybindings();
+		if (keys.matches(data, "tui.select.cancel")) {
+			if (this.query) {
+				this.query = "";
+				this.clampSelection();
+				this.host.requestRender();
+				return;
+			}
+			return this.done(undefined);
+		}
+		if (this.query && matchesKey(data, Key.backspace)) {
+			this.query = this.query.slice(0, -1);
+			this.clampSelection();
+			this.host.requestRender();
+			return;
+		}
+		if (keys.matches(data, "tui.select.confirm") || (!this.query && data === " ")) {
+			return this.activate();
+		}
+		if (matchesKey(data, "left")) return this.switchTab(-1);
+		if (matchesKey(data, "right")) return this.switchTab(1);
+		let offset = 0;
+		if (keys.matches(data, "tui.select.up")) offset = -1;
+		else if (keys.matches(data, "tui.select.down") || matchesKey(data, Key.tab)) offset = 1;
+		else if (matchesKey(data, Key.pageUp)) offset = -this.viewport;
+		else if (matchesKey(data, Key.pageDown)) offset = this.viewport;
+		else if (matchesKey(data, Key.home)) offset = -this.filtered.length;
+		else if (matchesKey(data, Key.end)) offset = this.filtered.length;
+		if (offset !== 0) return this.move(offset);
+		if (this.options.search !== false && data.length === 1 && data >= " ") {
+			this.query += data;
+			this.clampSelection();
+			this.host.requestRender();
+		}
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const height = dialogHeight(this.host);
+		const inner = Math.max(0, width - 4);
+		const rows = this.filtered;
+		this.clampSelection();
+
+		const tabCount = this.tabs.length;
+		const body: string[] = [];
+		if (tabCount > 1) body.push(this.renderTabBar(width));
+		body.push(
+			this.theme.fg(
+				"dim",
+				` ${rows.length ? this.selected + 1 : 0}/${rows.length} · Field / Value${this.query ? ` · /${this.query}` : ""}`,
+			),
+		);
+		if (this.options.subtitle) {
+			body.push(this.theme.fg("muted", ` ${truncateToWidth(dialogText(this.options.subtitle), Math.max(1, inner), "…")}`));
+		}
+
+		const helpLines = wrapHelp(this.theme, rows[this.selected]?.description ?? "", inner, height);
+		const reserved = helpLines.length + (this.options.subtitle ? 1 : 0) + (tabCount > 1 ? 1 : 0);
+		this.viewport = Math.max(1, height - 6 - reserved);
+		const start = Math.max(0, Math.min(this.selected - this.viewport + 1, rows.length - this.viewport));
+
+		const hasValueColumn = rows.some((row) => row.currentValue !== undefined);
+		const labelWidth = Math.min(
+			28,
+			Math.max(8, Math.floor(inner * 0.35)),
+			hasValueColumn ? Math.max(0, inner - 2 - 3 - 1) : Infinity,
+		);
+		for (let i = start; i < Math.min(rows.length, start + this.viewport); i++) {
+			body.push(this.renderRow(rows[i]!, start + i === this.selected, labelWidth));
+		}
+		body.push("");
+		body.push(...helpLines);
+
+		return frameDialog(
+			this.theme,
+			width,
+			height,
+			this.options.title + (this.query ? ` · /${this.query}` : ""),
+			body,
+			this.options.footer ?? DEFAULT_FOOTER,
+		);
+	}
+
+	private renderRow(row: DialogRow, isSelected: boolean, labelWidth: number): string {
+		const color = (text: string) => (isSelected ? this.theme.fg("accent", text) : text);
+		const label = truncateToWidth(dialogText(row.label), labelWidth, "", true);
+		const padding = " ".repeat(Math.max(0, labelWidth - visibleWidth(label)));
+		return (
+			color(`${isSelected ? "›" : " "} `) +
+			color(label) +
+			color(`${padding} │ `) +
+			color(dialogText(row.currentValue))
+		);
+	}
+
+	private renderTabBar(width: number): string {
+		const parts = this.tabs.map((tab, i) =>
+			i === this.activeTab
+				? this.theme.fg("accent", `[ ${tab.label} ]`)
+				: this.theme.fg("muted", `  ${tab.label}  `),
+		);
+		return truncateToWidth(parts.join(""), Math.max(1, width), "…");
+	}
+}
+
+function wrapHelp(theme: Theme, help: string, inner: number, height: number): string[] {
+	if (!help) return [];
+	return wrapTextWithAnsi(dialogText(help), Math.max(1, inner - 1))
+		.slice(0, Math.max(1, height - 8))
+		.map((line) => theme.fg("muted", ` ${line}`));
+}
+
+/** Run one framed menu overlay. Resolves with the accepted row id, or
+ *  undefined when closed. */
+export function dialogMenu(
+	ctx: DialogContext,
+	title: string,
+	rows: DialogRow[],
+	options: Partial<Pick<DialogMenuOptions, "subtitle" | "tabs" | "selectedId" | "footer" | "search" | "onChange">> = {},
+): Promise<string | undefined> {
+	return ctx.ui.custom(
+		(host, theme, _keys, done) =>
+			new DialogMenu(host, theme, { title, rows, ...options }, done),
+		DIALOG_OPTIONS,
+	);
+}
+
+/** Structural subset of an extension context: what dialogs actually touch. */
+export interface DialogContext {
+	hasUI: boolean;
+	mode?: string;
+	ui: {
+		notify(message: string, level?: "info" | "warning" | "error"): void;
+		custom<T>(factory: CustomFactory<T>, options?: unknown): Promise<T>;
+	};
+}
+
+type CustomFactory<T> = (
+	host: DialogHost & Record<string, unknown>,
+	theme: Theme,
+	keys: unknown,
+	done: (value: T) => void,
+) => { render(width: number): string[]; invalidate(): void; handleInput?(data: string): void };
+
+/** Headless guard: dialogs need the interactive TUI. */
+export function canOpenDialog(ctx: DialogContext): boolean {
+	if (!ctx.hasUI) return false;
+	if (ctx.mode && ctx.mode !== "tui") {
+		ctx.ui.notify("Dialogs require interactive TUI mode.", "warning");
+		return false;
+	}
+	return true;
+}