@oh-my-pi/pi-tui 18.4.2 → 18.4.4

package/src/overlays/model-picker.ts

@@ -9,7 +9,13 @@ import { addKeyAliases, canonicalKeyId } from "../keybindings";
 import { type KeyId, parseKey } from "../keys";
 import type { Component, TUI } from "../tui";
 import { type ThemeColor, theme } from "../theme/theme";
-import { buildSessionModelScope, ModelBrowser, type ModelBrowserItem } from "./model-browser";
+import {
+	buildSessionModelScope,
+	MODEL_PICKER_COLUMNS,
+	ModelBrowser,
+	type ModelBrowserItem,
+	type ModelPickerCatalogue,
+} from "./model-browser";
 import type { ModelBrowserRegistry, ModelBrowserSource } from "./model-browser";
 import type { ConfiguredThinkingLevel } from "../thinking";
 import type { ScopedModelItem } from "./model-hub";
@@ -17,6 +23,11 @@ import { bottomBorder, row, topBorder } from "../chrome/overlay-box";
 import { resolveSegmentPalette } from "../chrome/segment-track";
 import { formatKeyHint } from "../app-keybindings";
 import { editorKey, editorKeys } from "../chrome/keybinding-hints";
+import { card, compact, span, text } from "../native/describe";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
+import { CLOSE_ACTION, picker, pickerAction, pickerEvent } from "../native/picker";
+import type { TspPickerProps } from "@oh-my-pi/pi-wire";
+import { actionHint, hintsRow, type NativeHint } from "../native/overlay";
 
 /** Configured role resolved to a concrete model. */
 export interface ResolvedRoleModel {
@@ -28,7 +39,8 @@ export interface ResolvedRoleModel {
 
 /** Catalog refresh capability used by the session picker. */
 export interface ModelPickerRegistry extends ModelBrowserRegistry {
-	refresh(strategy: "offline"): Promise<void>;
+	/** Bring the catalog up to date without rebuilding a current one; `true` when the picker must re-read it. */
+	refreshIfStale(): Promise<boolean>;
 }
 
 export interface ModelPickerCallbacks {
@@ -116,6 +128,16 @@ export class ModelPickerComponent implements Component {
 	#taskMatchKeys = new Set<string>();
 	#taskModeKey: KeyId | undefined;
 	#taskSelector: string | undefined;
+	#nativeRoot: { memo: string; node: NativeNode } | undefined;
+	#pickerRoot:
+		| {
+				memo: string;
+				catalogue: ModelPickerCatalogue;
+				order: object;
+				preview: readonly NativeChild[];
+				node: NativeNode;
+		  }
+		| undefined;
 
 	constructor(
 		tui: TUI,
@@ -172,13 +194,15 @@ export class ModelPickerComponent implements Component {
 			this.#browser.selectSelector(options.currentSelector);
 		}
 
-		// Reconcile with cached discovery state in the background. A --models
-		// scope is registry-independent, so the offline reload would only repeat
-		// the synchronous hydration above.
+		// Re-read only if the catalog moves (startup discovery landing, a
+		// models.yml edit): rebuilding a current catalog on every open blocks
+		// the first paint for seconds. A --models scope is registry-independent.
 		if (this.#scopedModels.length === 0) {
 			this.#registry
-				.refresh("offline")
-				.then(() => this.#syncFromRegistryState())
+				.refreshIfStale()
+				.then(changed => {
+					if (changed) this.#syncFromRegistryState();
+				})
 				.catch(error => {
 					this.#configError = error instanceof Error ? error.message : String(error);
 				})
@@ -297,4 +321,157 @@ export class ModelPickerComponent implements Component {
 		out.push(bottomBorder(width, borderColor));
 		return out;
 	}
+
+	/** A `picker` is its own sheet: the backend mounts it in `layer` without an `overlay` wrapper. */
+	nativeSheet(cx: DescribeContext): boolean {
+		return cx.supports("picker");
+	}
+
+	/** Picker pointer events, each on the path of the key it stands for. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		const picked = pickerEvent(event);
+		if (!picked) return;
+		if (picked.kind !== "action") {
+			this.#browser.routePickerItem(picked.item, picked.kind === "activate");
+			return;
+		}
+		switch (picked.act) {
+			case CLOSE_ACTION.id:
+				this.#browser.handleCancel();
+				return;
+			case "clear":
+				if (this.#browser.query.length > 0) this.#browser.handleCancel();
+				return;
+			case "use": {
+				const selected = this.#browser.pickerSelected;
+				if (selected) this.#browser.routePickerItem(selected, true);
+				return;
+			}
+			case "task":
+				if (this.#taskModeKey !== undefined && !this.#roleMode) this.#toggleTaskMode();
+				return;
+		}
+	}
+
+	/** The `md` picker sheet, or the fallback card when the terminal lacks the kind. */
+	describe(cx?: DescribeContext): NativeNode {
+		return cx?.supports("picker") ? this.#describePicker() : this.#describeCard();
+	}
+
+	#describePicker(): NativeNode {
+		const mode = this.#taskMode ? "task" : this.#roleMode ? "role" : "session";
+		const query = this.#browser.query;
+		const view = this.#browser.pickerOrder({
+			providers: false,
+			rest: mode === "role" ? null : query.trim() ? "Matches" : "All",
+		});
+		const catalogue = this.#browser.pickerItems(this.#roleMode ? this.#quickRoleItems : this.#modelItems);
+		const current =
+			mode === "role"
+				? this.#currentQuickRoleSelector
+				: mode === "task"
+					? this.#taskSelector
+					: this.#currentSelector;
+		const preview = this.#browser.pickerPreview("compact", current);
+		const selected = this.#browser.pickerSelected;
+		const cursor = this.#browser.cursor;
+		const memo = `${mode}\0${this.#configError ?? ""}\0${query}\0${cursor}\0${selected ?? ""}`;
+		const cached = this.#pickerRoot;
+		if (
+			cached !== undefined &&
+			cached.memo === memo &&
+			cached.catalogue === catalogue &&
+			cached.order === view &&
+			cached.preview === preview
+		) {
+			return cached.node;
+		}
+		const subtitle: TspPickerProps["subtitle"] = this.#configError
+			? [span(this.#configError, "error")]
+			: mode === "task"
+				? [span(TASK_STATUS_HINT, "warning")]
+				: mode === "role"
+					? QUICK_ROLE_STATUS_HINT
+					: STATUS_HINT;
+		const cycleKey = editorKey("app.model.cycleForward") || formatKeyHint("ctrl+p");
+		const node = picker(
+			{
+				title: mode === "task" ? "Switch task model" : "Switch model",
+				subtitle,
+				icon: "cpu",
+				noun: mode === "role" ? "roles" : "models",
+				size: "md",
+				layout: "rows",
+				preview: "below",
+				query,
+				cursor,
+				placeholder: mode === "task" ? "Search models…" : "Search models, @ for quick roles…",
+				columns: MODEL_PICKER_COLUMNS,
+				...catalogue,
+				order: view.order,
+				...(view.hits ? { hits: view.hits } : {}),
+				selected,
+				...(current ? { current: [current] } : {}),
+				total: this.#browser.baseCount,
+				empty: mode === "role" ? `No quick roles in the ${cycleKey} cycle` : "No models available",
+				actions: compact([
+					pickerAction(
+						"use",
+						mode === "role" ? "Apply role" : mode === "task" ? "Use for Task subagents" : "Use for session",
+						"enter",
+						{ primary: true },
+					),
+					this.#taskModeKey !== undefined && mode !== "role"
+						? pickerAction("task", "Task model", this.#taskModeKey, { on: mode === "task" })
+						: undefined,
+					query.length > 0 ? { ...CLOSE_ACTION, label: "Clear search" } : CLOSE_ACTION,
+				]),
+			},
+			preview,
+		);
+		this.#pickerRoot = { memo, catalogue, order: view, preview, node };
+		return node;
+	}
+
+	/** Root card over the status line, the embedded browser, and the mode's key hints. */
+	#describeCard(): NativeNode {
+		const mode = this.#taskMode ? "task" : this.#roleMode ? "role" : "session";
+		const memo = `${mode}\0${this.#configError ?? ""}\0${this.#taskModeKey ?? ""}`;
+		if (this.#nativeRoot?.memo === memo) return this.#nativeRoot.node;
+
+		const status = this.#configError
+			? span(this.#configError, "error")
+			: this.#taskMode
+				? span(TASK_STATUS_HINT, "error")
+				: span(this.#roleMode ? QUICK_ROLE_STATUS_HINT : STATUS_HINT, "muted");
+		const hints: (NativeHint | undefined)[] = [
+			actionHint(["tui.select.up", "tui.select.down"], mode === "role" ? "roles" : "models"),
+			{
+				keys: ["enter"],
+				label:
+					mode === "role"
+						? "apply role model"
+						: mode === "task"
+							? "use for Task subagents"
+							: "use for this session",
+			},
+			{ keys: [], label: "type to search" },
+		];
+		if (mode === "session") hints.push({ keys: ["@"], label: "quick roles" });
+		hints.push(actionHint("tui.select.cancel", "close"));
+		if (this.#taskModeKey !== undefined && !this.#roleMode) {
+			hints.push({ keys: [this.#taskModeKey], label: this.#taskMode ? "session model" : "task model" });
+		}
+		// `card` directly: the task-mode tone is a common prop `overlayCard` doesn't take.
+		const node = card(
+			{
+				role: "omp.overlay.model-picker",
+				head: this.#taskMode ? "Switch Task Model" : "Switch Model",
+				tone: this.#taskMode ? "error" : undefined,
+			},
+			[text([status], { wrap: "word" }), this.#browser, hintsRow(hints)],
+		);
+		this.#nativeRoot = { memo, node };
+		return node;
+	}
 }

package/src/overlays/move-overlay.ts

@@ -13,6 +13,9 @@ import { bottomBorder, row, topBorder } from "../chrome/overlay-box";
 import { TextFormField } from "../components/form";
 import { formatKeyHint } from "../app-keybindings";
 import { editorKey, editorKeys } from "../chrome/keybinding-hints";
+import type { NativeNode, NativeUiEvent } from "../native/node";
+import { node, span } from "../native/describe";
+import { actionHint, overlayCard, statusHintsRow } from "../native/overlay";
 
 export interface MoveOverlayResult {
 	directory: string;
@@ -51,6 +54,7 @@ export class MoveOverlay implements Component, Focusable {
 	#renderMemo:
 		| { width: number; fieldLines: readonly string[]; revision: number; lines: readonly string[] }
 		| undefined;
+	#native: { revision: number; node: NativeNode } | undefined;
 
 	constructor(cwd: string, done: (result: MoveOverlayResult | undefined) => void, source: MoveDirectorySource) {
 		this.#cwd = cwd;
@@ -171,6 +175,47 @@ export class MoveOverlay implements Component, Focusable {
 		return lines;
 	}
 
+	describe(): NativeNode {
+		const memo = this.#native;
+		if (memo?.revision === this.#revision) return memo.node;
+		const items = this.#results
+			.slice(0, MAX_RESULTS)
+			.map(item => node("item", { label: item.label, detail: [span(item.value, "path")] }, undefined, item.value));
+		const list = node(
+			"list",
+			{
+				selected: this.#results[this.#selectedIndex]?.value ?? null,
+				empty: this.#field.getValue().length > 0 ? [span("No matching directories", "dim")] : undefined,
+			},
+			items,
+			"results",
+		);
+		const hints = statusHintsRow(
+			[span("Type to filter", "dim")],
+			[
+				actionHint(["tui.select.up", "tui.select.down"], "navigate"),
+				{ keys: ["tab"], label: "accept" },
+				{ keys: ["enter"], label: "confirm" },
+				actionHint("tui.select.cancel", "cancel"),
+			],
+		);
+		const described = overlayCard("omp.dialog.move", "Move to directory", [this.#field, list, hints]);
+		this.#native = { revision: this.#revision, node: described };
+		return described;
+	}
+
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type !== "select" && event.type !== "activate") return;
+		const index = this.#results.findIndex(result => result.value === event.item);
+		if (index === -1) return;
+		if (index !== this.#selectedIndex) {
+			this.#selectedIndex = index;
+			this.#revision++;
+		}
+		// Enter submits the field, which confirms the highlighted suggestion.
+		if (event.type === "activate") this.#field.submit();
+	}
+
 	invalidate(): void {
 		this.#field.input.prompt = theme.fg("dim", "Path: ");
 		this.#field.invalidate();

package/src/overlays/oauth-selector.ts

@@ -9,12 +9,20 @@ import {
 	type SgrMouseEvent,
 	Spacer,
 	TruncatedText,
+	visibleWidth,
 } from "../index";
 import { theme } from "../theme/theme";
 import { matchesSelectCancel, matchesSelectDown, matchesSelectUp } from "../keybinding-matchers";
 import { OverlayPanel } from "../chrome/overlay-box";
+import { Input } from "../components/input";
 import { MenuSelection } from "../components/menu-selection";
 import { centeredViewportRange } from "../components/scroll-viewport";
+import type { TspPickerItem, TspSpan, TspTone } from "@oh-my-pi/pi-wire";
+import { node, span, text } from "../native/describe";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node";
+import { CLOSE_ACTION, dockedPicker, PICKER_KEY, pickerAction, pickerEvent, pickerQuery } from "../native/picker";
+import { overlayCard } from "../native/overlay";
+import { isNativeRendering } from "../native/state";
 
 const OAUTH_SELECTOR_MAX_VISIBLE = 10;
 
@@ -44,6 +52,8 @@ const ORIGIN_LABELS = {
 export class OAuthSelectorComponent extends OverlayPanel {
 	#listContainer: Container;
 	#menu: MenuSelection<OAuthProviderInfo>;
+	/** The provider search field; its value drives `#menu`'s query. */
+	#search = Object.assign(new Input(), { prompt: "" });
 	#hoveredIndex: number | null = null;
 	/** First provider index of the visible ScrollView window (last #updateList). */
 	#scrollStart = 0;
@@ -61,6 +71,13 @@ export class OAuthSelectorComponent extends OverlayPanel {
 	#spinnerFrame: number = 0;
 	#spinnerInterval?: NodeJS.Timeout;
 	#validationGeneration: number = 0;
+	#nativeItems: readonly NativeNode[] | undefined;
+	/** The `visibleItems` array {@link #nativeItems} was built from. */
+	#nativeItemsSource: readonly OAuthProviderInfo[] | undefined;
+	#nativeRoot: NativeNode | undefined;
+	/** Picker rows for the whole catalogue; dropped when an auth state changes. */
+	#pickerItems: readonly TspPickerItem[] | undefined;
+	#pickerRoot: NativeNode | undefined;
 	constructor(
 		mode: "login" | "logout",
 		authStorage: OAuthSelectorAuthSource,
@@ -72,7 +89,7 @@ export class OAuthSelectorComponent extends OverlayPanel {
 			requestRender?: () => void;
 		},
 	) {
-		super(mode === "login" ? "Select provider to login" : "Select provider to logout");
+		super(mode === "login" ? "Select provider to login" : "Select provider to logout", "omp.overlay.oauth");
 		this.#mode = mode;
 		this.#authStorage = authStorage;
 		this.#onSelectCallback = onSelect;
@@ -155,6 +172,8 @@ export class OAuthSelectorComponent extends OverlayPanel {
 				continue;
 			}
 			this.#authState.set(provider.id, "checking");
+			this.#nativeItems = undefined;
+			this.#pickerItems = undefined;
 			pending += 1;
 			void this.#validateProvider(provider.id, generation);
 		}
@@ -177,6 +196,8 @@ export class OAuthSelectorComponent extends OverlayPanel {
 
 		if (generation !== this.#validationGeneration) return;
 		this.#authState.set(providerId, isValid ? "valid" : "invalid");
+		this.#nativeItems = undefined;
+		this.#pickerItems = undefined;
 		if (![...this.#authState.values()].includes("checking")) {
 			this.#stopSpinner();
 		}
@@ -185,7 +206,8 @@ export class OAuthSelectorComponent extends OverlayPanel {
 	}
 
 	#startSpinner(): void {
-		if (this.#spinnerInterval) return;
+		// Natively the "checking" status pulses on the terminal's clock.
+		if (this.#spinnerInterval || isNativeRendering()) return;
 		this.#spinnerInterval = setInterval(() => {
 			const frameCount = theme.spinnerFrames.length;
 			if (frameCount > 0) {
@@ -243,8 +265,9 @@ export class OAuthSelectorComponent extends OverlayPanel {
 
 	#renderStatusLine(_total: number): string {
 		const query = this.#menu.query.trim();
-		const suffix = query ? `Search: ${this.#menu.query}` : "Type to search";
-		return theme.fg("muted", suffix);
+		if (!query) return theme.fg("muted", "Type to search");
+		const width = visibleWidth(this.#search.getValue()) + 1;
+		return theme.fg("muted", "Search: ") + (this.#search.render(width)[0] ?? "");
 	}
 
 	#getProviderSearchText(provider: OAuthProviderInfo): string {
@@ -260,32 +283,32 @@ export class OAuthSelectorComponent extends OverlayPanel {
 		return text;
 	}
 
-	#setSearchQuery(query: string): void {
-		this.#menu.setQuery(query, false);
+	/** Applies the search field's value to the filter; clears any stale status. */
+	#syncSearchQuery(): void {
+		this.#menu.setQuery(this.#search.getValue(), false);
 		this.#statusMessage = undefined;
 		this.#updateList();
 	}
 
+	/** Feeds keys the selector does not bind to the search field. Backspace on an empty query and a leading space bubble. */
 	#handleSearchInput(keyData: string): boolean {
 		if (!this.#isSearchEnabled()) return false;
-
-		if (matchesKey(keyData, "backspace")) {
-			if (this.#menu.query.length === 0) return false;
-			const chars = [...this.#menu.query];
-			chars.pop();
-			this.#setSearchQuery(chars.join(""));
-			return true;
+		const before = this.#search.getValue();
+		if (before.length === 0) {
+			if (matchesKey(keyData, "backspace")) return false;
+			const printableText = extractPrintableText(keyData);
+			if (printableText !== undefined && printableText.trim().length === 0) return false;
 		}
-
-		const printableText = extractPrintableText(keyData);
-		if (printableText === undefined) return false;
-		if (this.#menu.query.length === 0 && printableText.trim().length === 0) return false;
-
-		this.#setSearchQuery(this.#menu.query + printableText);
+		const cursorBefore = this.#search.getCursor();
+		if (!this.#search.handleInput(keyData)) return false;
+		if (this.#search.getValue() !== before) this.#syncSearchQuery();
+		else if (this.#search.getCursor() !== cursorBefore) this.#updateList();
 		return true;
 	}
 
 	#updateList(): void {
+		this.#nativeRoot = undefined;
+		this.#pickerRoot = undefined;
 		this.#listContainer.clear();
 
 		const items = this.#menu.visibleItems;
@@ -356,10 +379,6 @@ export class OAuthSelectorComponent extends OverlayPanel {
 			return;
 		}
 
-		if (this.#handleSearchInput(keyData)) {
-			return;
-		}
-
 		// Up arrow
 		if (matchesSelectUp(keyData)) {
 			this.#menu.move(-1, true);
@@ -388,6 +407,8 @@ export class OAuthSelectorComponent extends OverlayPanel {
 		else if (matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n") {
 			this.#confirmSelection();
 		}
+		// Everything else edits the search field
+		else this.#handleSearchInput(keyData);
 	}
 
 	/** Confirm the selected provider (Enter or mouse click). */
@@ -403,6 +424,189 @@ export class OAuthSelectorComponent extends OverlayPanel {
 		}
 	}
 
+	/** Credential status of a provider row: `value` (state) and `detail` (origin) spans. */
+	#describeStatus(providerId: string): { value?: readonly TspSpan[]; detail?: readonly TspSpan[] } {
+		const origin = this.#authStorage.keys.source(providerId);
+		const detail = origin
+			? [
+					span(
+						origin.kind === "env" && origin.envVar ? `env: ${origin.envVar}` : ORIGIN_LABELS[origin.kind],
+						"muted",
+					),
+				]
+			: undefined;
+		const state = this.#authState.get(providerId);
+		if (state === "checking") return { value: [span("checking", "warning", { fx: "pulse" })], detail };
+		if (state === "invalid") return { value: [span("invalid", "error")], detail };
+		if (state === "valid" || this.#hasSelectableAuth(providerId)) {
+			return { value: [span("logged in", "success")], detail };
+		}
+		return { detail };
+	}
+
+	/** One provider card: initials mark, origin detail, auth-state dot, disabled reason. */
+	#pickerItem(provider: OAuthProviderInfo): TspPickerItem {
+		const origin = this.#authStorage.keys.source(provider.id);
+		const state = this.#authState.get(provider.id);
+		const dot: TspTone =
+			state === "checking"
+				? "pending"
+				: state === "invalid"
+					? "error"
+					: state === "valid" || this.#hasSelectableAuth(provider.id)
+						? "success"
+						: "muted";
+		const source = origin
+			? origin.kind === "env" && origin.envVar
+				? `env: ${origin.envVar}`
+				: ORIGIN_LABELS[origin.kind]
+			: undefined;
+		const detail = !source
+			? "Not configured"
+			: origin?.kind === "oauth"
+				? `Signed in · ${source}`
+				: `API key · ${source}`;
+		const initials = provider.name
+			.split(/[^\p{L}\p{N}]+/u)
+			.filter(word => word.length > 0)
+			.slice(0, 2)
+			.map(word => word[0]!.toUpperCase())
+			.join("");
+		return {
+			id: provider.id,
+			label: provider.name,
+			detail,
+			mark: { text: initials, seed: provider.id },
+			dot,
+			...(provider.available ? {} : { disabled: "Provider unavailable in this environment" }),
+		};
+	}
+
+	#describePicker(): NativeNode {
+		if (this.#pickerRoot) return this.#pickerRoot;
+		const all = this.#menu.items;
+		this.#pickerItems ??= all.map(provider => this.#pickerItem(provider));
+		const query = this.#menu.query;
+		const login = this.#mode === "login";
+		const search = this.#shouldRenderSearchStatus() ? pickerQuery(this.#search) : pickerQuery(null);
+		this.#pickerRoot = dockedPicker({
+			title: login ? "Sign in" : "Sign out",
+			subtitle: login ? "Pick a provider" : "Remove stored credentials",
+			icon: "key-round",
+			noun: "providers",
+			size: "md",
+			layout: "cards",
+			preview: "none",
+			...search,
+			placeholder: "Search providers…",
+			items: this.#pickerItems,
+			...(query.length > 0 ? { order: this.#menu.visibleItems.map(provider => provider.id) } : {}),
+			selected: this.#menu.selectedKey ?? null,
+			total: all.length,
+			empty: login ? "No OAuth providers available" : "No stored provider credentials to log out",
+			...(this.#statusMessage ? { message: this.#statusMessage } : {}),
+			actions: [
+				pickerAction(
+					"confirm",
+					login ? "Sign in" : "Sign out",
+					"enter",
+					login ? { primary: true } : { primary: true, danger: true },
+				),
+				CLOSE_ACTION,
+			],
+		});
+		return this.#pickerRoot;
+	}
+
+	override describe(cx: DescribeContext): NativeNode {
+		if (cx.supports("picker")) return this.#describePicker();
+		if (this.#nativeRoot) return this.#nativeRoot;
+		const items = this.#menu.visibleItems;
+		if (!this.#nativeItems || this.#nativeItemsSource !== items) {
+			this.#nativeItemsSource = items;
+			this.#nativeItems = items.map(provider =>
+				node(
+					"item",
+					{
+						label: provider.name,
+						tone: provider.available ? undefined : "muted",
+						...this.#describeStatus(provider.id),
+					},
+					undefined,
+					provider.id,
+				),
+			);
+		}
+		const query = this.#menu.query;
+		const children: NativeNode[] = [];
+		if (this.#shouldRenderSearchStatus()) {
+			children.push(
+				node(
+					"input",
+					{ text: this.#search.getValue(), cursor: this.#search.getCursor(), placeholder: "Type to search" },
+					undefined,
+					"search",
+				),
+			);
+		}
+		const empty =
+			this.#menu.items.length === 0
+				? this.#mode === "login"
+					? "No OAuth providers available"
+					: "No stored provider credentials to log out"
+				: "No matching providers";
+		children.push(
+			node(
+				"list",
+				{
+					selected: this.#menu.selectedKey ?? null,
+					filter: query.trim() || undefined,
+					empty: [span(empty, "muted")],
+					max: { lines: OAUTH_SELECTOR_MAX_VISIBLE },
+				},
+				this.#nativeItems,
+				"list",
+			),
+		);
+		if (this.#statusMessage) children.push(text([span(this.#statusMessage, "warning")]));
+		this.#nativeRoot = overlayCard(this.nativeRole, this.title, children);
+		return this.#nativeRoot;
+	}
+
+	/** A click (or double-click) on a provider selects and confirms it, like the SGR click in {@link routeMouse}. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		const ev = pickerEvent(event, PICKER_KEY);
+		if (ev?.kind === "action") {
+			if (ev.act === "confirm") this.#confirmSelection();
+			else if (ev.act === "clear") {
+				this.#search.setValue("");
+				this.#syncSearchQuery();
+			} else if (ev.act === "close" || ev.act === "cancel") {
+				this.stopValidation();
+				this.#onCancelCallback();
+			}
+			return;
+		}
+		if (ev?.kind === "select") {
+			const index = this.#menu.visibleItems.findIndex(provider => provider.id === ev.item);
+			if (index < 0 || index === this.#menu.selectedIndex) return;
+			this.#menu.setSelectedIndex(index);
+			this.#statusMessage = undefined;
+			this.#updateList();
+			return;
+		}
+		if ((event.type !== "select" && event.type !== "activate") || (event.key !== "list" && ev?.kind !== "activate"))
+			return;
+		const index = this.#menu.visibleItems.findIndex(provider => provider.id === event.item);
+		if (index < 0) return;
+		if (index !== this.#menu.selectedIndex) {
+			this.#menu.setSelectedIndex(index);
+			this.#statusMessage = undefined;
+			this.#updateList();
+		}
+		this.#confirmSelection();
+	}
+
 	/** Move the selection one step for a wheel notch (clamped, no wrap). */
 	handleWheel(delta: -1 | 1): void {
 		if (this.#menu.visibleItems.length === 0) return;