@oh-my-pi/pi-tui 18.2.4 → 18.2.6

package/src/setup/scenes/theme.ts

@@ -0,0 +1,343 @@
+import { padding, visibleWidth } from "../../utils";
+import { padToWidth } from "../../render/utils";
+import { type SgrMouseEvent } from "../../mouse";
+import { type SelectItem, SelectList } from "../../components/select-list";
+import { Text } from "../../components/text";
+import { WizardStep } from "../../components/wizard-step";
+import { Container } from "../../tui";
+import {
+	enableAutoTheme,
+	getAvailableThemes,
+	getCurrentThemeName,
+	getSelectListTheme,
+	isLightTheme,
+	previewTheme,
+	type SymbolPreset,
+	setColorBlindMode,
+	setSymbolPreset,
+	theme,
+} from "../../theme/theme";
+import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
+
+type ThemeMode = "curated" | "all";
+
+const CURATED_ITEMS: readonly SelectItem[] = [
+	{ value: "auto", label: "Match terminal", description: "Titanium in dark terminals, Light in light terminals" },
+	{ value: "theme:titanium", label: "Titanium", description: "Default dark theme" },
+	{ value: "theme:light", label: "Light", description: "Default light theme" },
+	{ value: "colorblind", label: "Colorblind colors", description: "Adjust red/green contrast" },
+	{ value: "ansi", label: "ANSI-safe", description: "ASCII glyphs with the dark terminal theme" },
+	{ value: "browse", label: "Browse all…", description: "Show every built-in and custom theme" },
+];
+
+function fillStyledLine(content: string, width: number): string {
+	return content + padding(Math.max(0, width - visibleWidth(content)));
+}
+
+function renderMockStatusLine(width: number): string {
+	const sep = theme.fg("statusLineSep", ` ${theme.sep.pipe} `);
+	const left = [
+		theme.fg("statusLineModel", `${theme.icon.model} sonnet`),
+		theme.fg("statusLinePath", "~/project"),
+		theme.fg("statusLineGitDirty", `${theme.icon.git} main +2`),
+	].join(sep);
+	const right = [
+		theme.fg("statusLineContext", `${theme.icon.context} 42%`),
+		theme.fg("statusLineCost", `${theme.icon.cost} 0.18`),
+	].join(sep);
+	const innerWidth = Math.max(1, width - 2);
+	const leftWidth = visibleWidth(left);
+	const rightWidth = visibleWidth(right);
+	const gap = padding(Math.max(1, innerWidth - leftWidth - rightWidth - 2));
+	return theme.bg("statusLineBg", width > 0 ? padToWidth(` ${left}${gap}${right} `, width) : "");
+}
+
+function renderMockEditor(width: number): string[] {
+	const box = theme.boxRound;
+	const innerWidth = Math.max(1, width - 2);
+	const horizontal = box.horizontal.repeat(innerWidth);
+	const top = theme.fg("borderAccent", `${box.topLeft}${horizontal}${box.topRight}`);
+	const bottom = theme.fg("borderMuted", `${box.bottomLeft}${horizontal}${box.bottomRight}`);
+	const prompt = `${theme.fg("accent", ">")} ${theme.fg("text", "Ask anything, edit files, run tools")}${theme.inverse(" ")}`;
+	const hint = theme.fg("dim", "enter send · shift+enter newline · / commands");
+	return [
+		top,
+		`${theme.fg("borderAccent", box.vertical)}${innerWidth > 0 ? padToWidth(prompt, innerWidth) : ""}${theme.fg("borderAccent", box.vertical)}`,
+		`${theme.fg("borderMuted", box.vertical)}${fillStyledLine(hint, innerWidth)}${theme.fg("borderMuted", box.vertical)}`,
+		bottom,
+	];
+}
+
+function renderThemePreview(width: number): string[] {
+	const previewWidth = Math.max(24, Math.min(width, 88));
+	return [
+		theme.bold("Preview"),
+		`${theme.fg("success", `${theme.status.success} success`)}  ${theme.fg("warning", `${theme.status.warning} warning`)}  ${theme.fg("error", `${theme.status.error} error`)}  ${theme.fg("accent", "accent")}`,
+		"",
+		theme.fg("muted", "Status line"),
+		renderMockStatusLine(previewWidth),
+		theme.fg("muted", "Editor"),
+		...renderMockEditor(previewWidth),
+	];
+}
+
+class ThemeSceneController implements SetupSceneController {
+	title = "Pick a theme";
+	subtitle = "Move through the list to preview; Enter saves the highlighted choice.";
+	#mode: ThemeMode = "curated";
+	#selectList: SelectList;
+	#loadingAllThemes = false;
+	#message: string | undefined;
+	#previewRequest = 0;
+	#disposed = false;
+	#step: WizardStep | undefined;
+	readonly #originalTheme = getCurrentThemeName();
+	readonly #originalSymbolPreset: SymbolPreset;
+	readonly #originalColorBlindMode: boolean;
+
+	readonly #host: SetupSceneHost;
+
+	constructor(host: SetupSceneHost) {
+		this.#host = host;
+		this.#originalSymbolPreset = host.ctx.symbolPreset;
+		this.#originalColorBlindMode = host.ctx.colorBlindMode;
+		this.#selectList = this.#createSelectList(CURATED_ITEMS, this.#currentCuratedIndex());
+	}
+
+	dispose(): void {
+		this.#disposed = true;
+	}
+
+	invalidate(): void {
+		this.#step?.invalidate();
+		this.#selectList.invalidate();
+	}
+
+	handleInput(data: string): void {
+		const quickIndex = data >= "1" && data <= "9" ? Number(data) - 1 : -1;
+		if (quickIndex >= 0) {
+			this.#selectList.setSelectedIndex(quickIndex);
+			this.#previewByIndex(quickIndex);
+			return;
+		}
+		this.#selectList.handleInput(data);
+	}
+
+	/** Wheel moves the highlight (live preview); hover lights the row under the pointer; click confirms it. */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		if (this.#loadingAllThemes) {
+			this.#selectList.routeMouse(event, Number.NEGATIVE_INFINITY, col);
+			return;
+		}
+		this.#step?.routeMouse(event, line, col);
+	}
+
+	render(width: number, maxLines?: number): readonly string[] {
+		const intro = new Container();
+		intro.addChild(
+			new Text(theme.fg("muted", "Theme changes preview live. Nothing is saved until you press Enter."), 0, 0),
+		);
+		intro.addChild(
+			new Text(
+				this.#mode === "all"
+					? theme.fg("dim", "Browsing all themes · Esc returns to curated choices")
+					: theme.fg("dim", "Esc skips this step"),
+				0,
+				0,
+			),
+		);
+		// The mock status-line/editor block is decorative — the wizard itself
+		// re-renders in the highlighted theme — so it yields to the list when
+		// it would squeeze the window below the six curated rows (+1 for the
+		// list's own search-status row).
+		const preview = new Container();
+		for (const line of renderThemePreview(width)) {
+			preview.addChild(new Text(line, 0, 0));
+		}
+		const loading = this.#loadingAllThemes ? new Text(theme.fg("dim", "Loading themes…"), 0, 0) : undefined;
+		const status = this.#message ? new Text(this.#message, 0, 0) : undefined;
+		if (!this.#step) {
+			this.#step = new WizardStep({
+				kind: loading ? "async" : "choice",
+				intro,
+				preview: { component: preview, optional: true },
+				content: loading ?? this.#selectList,
+				status,
+				minContentLines: CURATED_ITEMS.length + 1,
+				fitContent: budget => {
+					if (this.#loadingAllThemes) return;
+					const visible = budget === undefined ? 10 : budget - 1;
+					this.#selectList.setMaxVisible(Math.max(1, Math.min(10, visible)));
+				},
+			});
+		} else {
+			this.#step.setKind(loading ? "async" : "choice");
+			this.#step.setIntro(intro);
+			this.#step.setPreview({ component: preview, optional: true });
+			this.#step.setContent(loading ?? this.#selectList);
+			this.#step.setStatus(status);
+		}
+		this.#step.setMaxHeight(maxLines);
+		return this.#step.render(width);
+	}
+
+	#createSelectList(items: readonly SelectItem[], selectedIndex: number): SelectList {
+		const list = new SelectList(items, Math.min(10, Math.max(1, items.length)), getSelectListTheme());
+		list.setSelectedIndex(selectedIndex);
+		list.onSelectionChange = item => {
+			void this.#preview(item.value);
+		};
+		list.onSelect = item => {
+			void this.#select(item.value);
+		};
+		list.onCancel = () => {
+			if (this.#mode === "all") {
+				this.#mode = "curated";
+				this.#selectList = this.#createSelectList(CURATED_ITEMS, this.#currentCuratedIndex());
+				this.#host.requestRender();
+				return;
+			}
+			this.#restorePreview();
+			this.#host.finish("skipped");
+		};
+		return list;
+	}
+
+	#currentCuratedIndex(): number {
+		const current = getCurrentThemeName();
+		if (current === "titanium") return 1;
+		if (current === "light") return 2;
+		return 0;
+	}
+
+	#previewByIndex(index: number): void {
+		const items = this.#mode === "curated" ? CURATED_ITEMS : undefined;
+		const value = items?.[index]?.value;
+		if (value) void this.#preview(value);
+	}
+
+	async #select(value: string): Promise<void> {
+		if (value === "browse") {
+			await this.#showAllThemes();
+			return;
+		}
+		await this.#commit(value);
+		this.#host.finish("done");
+	}
+
+	async #showAllThemes(): Promise<void> {
+		if (this.#loadingAllThemes) return;
+		this.#loadingAllThemes = true;
+		this.#message = undefined;
+		this.#host.requestRender();
+		try {
+			const themes = await getAvailableThemes();
+			if (this.#disposed) return;
+			const items = themes.map(name => ({
+				value: `theme:${name}`,
+				label: name,
+				description: name === this.#originalTheme ? "current" : undefined,
+			}));
+			const selectedIndex = Math.max(0, themes.indexOf(this.#originalTheme ?? ""));
+			this.#mode = "all";
+			this.#selectList = this.#createSelectList(items, selectedIndex);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			this.#message = theme.fg("error", `Failed to load themes: ${message}`);
+		} finally {
+			this.#loadingAllThemes = false;
+			this.#host.requestRender();
+		}
+	}
+
+	async #commit(value: string): Promise<void> {
+		if (value === "auto") {
+			this.#host.ctx.saveTheme("dark", "titanium");
+			this.#host.ctx.saveTheme("light", "light");
+			await this.#applyPreviewPresentation(this.#originalSymbolPreset, this.#originalColorBlindMode);
+			enableAutoTheme();
+			return;
+		}
+		if (value === "colorblind") {
+			this.#host.ctx.saveColorBlindMode(true);
+			await this.#applyPreviewPresentation(this.#originalSymbolPreset, true);
+			return;
+		}
+		if (value === "ansi") {
+			this.#host.ctx.saveSymbolPreset("ascii");
+			this.#host.ctx.saveTheme("dark", "dark-terminal");
+			await this.#applyPreviewPresentation("ascii", this.#originalColorBlindMode);
+			enableAutoTheme();
+			return;
+		}
+		const themeName = this.#themeNameFromValue(value);
+		if (!themeName) return;
+		await this.#applyPreviewPresentation(this.#originalSymbolPreset, this.#originalColorBlindMode);
+		if (isLightTheme(themeName)) {
+			this.#host.ctx.saveTheme("light", themeName);
+		} else {
+			this.#host.ctx.saveTheme("dark", themeName);
+		}
+		await previewTheme(themeName, { ephemeral: false });
+	}
+
+	async #preview(value: string): Promise<void> {
+		const request = ++this.#previewRequest;
+		this.#message = undefined;
+		if (value === "browse") {
+			this.#host.requestRender();
+			return;
+		}
+
+		let result: { success: boolean; error?: string } = { success: true };
+		if (value === "auto") {
+			await this.#applyPreviewPresentation(this.#originalSymbolPreset, this.#originalColorBlindMode);
+			enableAutoTheme({ ephemeral: true });
+		} else if (value === "colorblind") {
+			await this.#applyPreviewPresentation(this.#originalSymbolPreset, true);
+		} else if (value === "ansi") {
+			await this.#applyPreviewPresentation("ascii", this.#originalColorBlindMode);
+			result = await previewTheme("dark-terminal");
+		} else {
+			const themeName = this.#themeNameFromValue(value);
+			if (themeName) {
+				await this.#applyPreviewPresentation(this.#originalSymbolPreset, this.#originalColorBlindMode);
+				result = await previewTheme(themeName);
+			}
+		}
+		if (request !== this.#previewRequest || this.#disposed) return;
+		if (!result.success) {
+			this.#message = theme.fg("error", result.error ?? "Theme preview failed");
+		}
+		this.#host.ctx.ui.invalidate();
+		this.#host.requestRender();
+	}
+
+	async #applyPreviewPresentation(symbolPreset: SymbolPreset, colorBlindMode: boolean): Promise<void> {
+		await setSymbolPreset(symbolPreset);
+		await setColorBlindMode(colorBlindMode);
+	}
+
+	#restorePreview(): void {
+		void (async () => {
+			await this.#applyPreviewPresentation(this.#originalSymbolPreset, this.#originalColorBlindMode);
+			if (this.#originalTheme) {
+				await previewTheme(this.#originalTheme);
+			}
+			this.#host.ctx.ui.invalidate();
+			this.#host.requestRender();
+		})();
+	}
+
+	#themeNameFromValue(value: string): string | undefined {
+		return value.startsWith("theme:") ? value.slice("theme:".length) : undefined;
+	}
+}
+
+/** Preview and persist the terminal color theme. */
+export const themeSetupScene: SetupScene = {
+	id: "theme",
+	title: "Pick a theme",
+	minVersion: 1,
+	mount: host => new ThemeSceneController(host),
+};

package/src/setup/scenes/types.ts

@@ -0,0 +1,111 @@
+import type { AuthStorage, Model } from "@oh-my-pi/pi-ai";
+import type { OAuthBrowserSessionRequest } from "@oh-my-pi/pi-ai/oauth/types";
+import type { SgrMouseEvent } from "../../mouse";
+import type { ComposerPreviewStatusSource } from "../../overlays/composer-shape-preview";
+import type { ComposerShape } from "../../overlays/composer-shape-registry";
+import type { ModelBrowserSource } from "../../overlays/model-browser";
+import type { SymbolPreset } from "../../theme/theme";
+import type { SearchProviderId } from "../../tools/web-search";
+import type { Component, TUI } from "../../tui";
+
+/** Terminal capabilities used by setup overlays and the startup splash. */
+export interface SetupUiHost {
+	readonly ui: Pick<TUI, "showOverlay" | "setFocus" | "requestRender" | "invalidate"> & {
+		readonly terminal: { readonly rows: number };
+	};
+}
+
+/** Application-owned preferences and effects consumed by setup scenes. */
+export interface SetupHost extends SetupUiHost {
+	readonly statusLine: ComposerPreviewStatusSource | undefined;
+	readonly composerShape: ComposerShape;
+	readonly symbolPreset: SymbolPreset;
+	readonly colorBlindMode: boolean;
+	readonly webSearchOrder: readonly string[];
+	readonly disabledProviders: readonly string[];
+	readonly authStorage: AuthStorage;
+	readonly modelSource: ModelBrowserSource;
+	getModels(): { available: Model[]; all: Model[]; current: Model | undefined };
+	refreshModels(): Promise<void>;
+	selectModel(model: Model, selector: string): Promise<void>;
+	refreshProvider(provider: string): Promise<void>;
+	saveComposerShape(shape: ComposerShape): Promise<void>;
+	saveSymbolPreset(preset: SymbolPreset): void;
+	saveColorBlindMode(enabled: boolean): void;
+	saveTheme(mode: "dark" | "light", name: string): void;
+	isSearchProviderAvailable(id: SearchProviderId): Promise<boolean>;
+	saveSearchProvider(id: SearchProviderId | "auto"): void;
+	captureBrowserSession(request: OAuthBrowserSessionRequest, signal?: AbortSignal): Promise<string>;
+	copyToClipboard(text: string): Promise<void>;
+	openInBrowser(url: string): void;
+	markComplete(version: number): Promise<void>;
+	playWelcomeIntro(): void;
+	showError(message: string): void;
+}
+
+/** Outcome reported when an onboarding scene finishes. */
+export type SetupSceneResult = "done" | "skipped";
+
+/** Per-scene focus, rendering, completion, and application callbacks. */
+export interface SetupSceneHost {
+	ctx: SetupHost;
+	requestRender(): void;
+	finish(result: SetupSceneResult): void;
+	setFocus(component: Component | null): void;
+	restoreFocus(): void;
+}
+
+/** Interactive content hosted inside the setup wizard frame. */
+export interface SetupSceneController extends Component {
+	title: string;
+	subtitle?: string;
+	onMount?(): void | Promise<void>;
+	onUnmount?(): void;
+	dispose?(): void;
+	/**
+	 * Render the scene body. `maxLines` is the number of body rows the wizard
+	 * will actually display (header and footer already subtracted); scenes
+	 * shrink list windows and drop decorative chrome so the selected row stays
+	 * inside the budget. Overflow beyond `maxLines` is clipped by the wizard.
+	 */
+	render(width: number, maxLines?: number): readonly string[];
+	/**
+	 * Route an SGR mouse report (tracking is on while the wizard holds the
+	 * alternate screen). `line`/`col` are 0-based within this controller's
+	 * last rendered output. When absent, the wizard falls back to synthesizing
+	 * arrow keys from wheel notches.
+	 */
+	routeMouse?(event: SgrMouseEvent, line: number, col: number): void;
+}
+
+/**
+ * A single panel inside a tabbed setup scene. The host scene owns the tab bar
+ * and forwards rendering/input to the active tab.
+ */
+export interface SetupTab {
+	readonly id: string;
+	readonly label: string;
+	/**
+	 * While `true` the tab owns all keyboard input (e.g. an in-progress OAuth
+	 * login). The parent scene MUST NOT switch tabs or finish while modal.
+	 */
+	readonly modal: boolean;
+	/** See {@link SetupSceneController.render}: `maxLines` is the tab-local row budget. */
+	render(width: number, maxLines?: number): readonly string[];
+	handleInput(data: string): void;
+	invalidate(): void;
+	/** Called when the tab becomes active (including initial mount). */
+	onActivate?(): void;
+	/** Mouse routing at tab-local coordinates; see {@link SetupSceneController.routeMouse}. */
+	routeMouse?(event: SgrMouseEvent, line: number, col: number): void;
+	dispose(): void;
+}
+
+/** Versioned onboarding scene definition. */
+export interface SetupScene {
+	id: string;
+	title: string;
+	minVersion: number;
+	shouldRun?(ctx: SetupHost): boolean | Promise<boolean>;
+	mount(host: SetupSceneHost): SetupSceneController;
+}

package/src/setup/scenes/web-search.ts

@@ -0,0 +1,165 @@
+import { type SgrMouseEvent } from "../../mouse";
+import { type SelectItem, SelectList } from "../../components/select-list";
+import { Spacer } from "../../components/spacer";
+import { Text } from "../../components/text";
+import { WizardStep } from "../../components/wizard-step";
+import { Container } from "../../tui";
+import { truncateToWidth } from "../../utils";
+import { SEARCH_PROVIDER_OPTIONS, type SearchProviderId } from "../../tools/web-search";
+import { getSelectListTheme, theme } from "../../theme/theme";
+import type { SetupSceneHost, SetupTab } from "./types";
+
+const MAX_VISIBLE = 8;
+
+/** Reuse the shared provider options as the single source of truth for labels/descriptions. */
+const WEB_SEARCH_ITEMS: readonly SelectItem[] = SEARCH_PROVIDER_OPTIONS.map(option => ({
+	value: option.value,
+	label: option.label,
+	description: option.description,
+}));
+
+type Availability = "checking" | boolean;
+
+/**
+ * "Web search" panel: picks the provider the web_search tool should prefer and
+ * reports whether the highlighted provider is ready to use given current
+ * credentials (env keys or OAuth sign-ins from the Sign in tab) or an
+ * unauthenticated fallback.
+ */
+export class WebSearchTab implements SetupTab {
+	readonly id = "web-search";
+	readonly label = "Web search";
+	readonly modal = false;
+
+	#list: SelectList;
+	#availability = new Map<SearchProviderId, Availability>();
+	#status: string[] = [];
+	#disposed = false;
+	#step: WizardStep | undefined;
+
+	readonly #host: SetupSceneHost;
+
+	constructor(host: SetupSceneHost) {
+		this.#host = host;
+		this.#list = new SelectList(WEB_SEARCH_ITEMS, MAX_VISIBLE, getSelectListTheme());
+		const order = host.ctx.webSearchOrder;
+		const current = Array.isArray(order) && typeof order[0] === "string" ? order[0] : "auto";
+		const index = WEB_SEARCH_ITEMS.findIndex(item => item.value === current);
+		if (index >= 0) this.#list.setSelectedIndex(index);
+		this.#list.onSelectionChange = item => this.#onHighlight(item.value);
+		this.#list.onSelect = item => this.#apply(item.value);
+		this.#list.onCancel = () => host.finish("skipped");
+	}
+
+	onActivate(): void {
+		// Auth may have changed in the Sign in tab; re-check from scratch.
+		this.#availability.clear();
+		this.#status = [];
+		const selected = this.#list.getSelectedItem();
+		if (selected) this.#onHighlight(selected.value);
+		this.#host.requestRender();
+	}
+
+	handleInput(data: string): void {
+		if (this.#step) this.#step.handleInput(data);
+		else this.#list.handleInput(data);
+	}
+
+	/** Wheel moves the highlight; hover lights the row under the pointer; click confirms it. */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		this.#step?.routeMouse(event, line, col);
+	}
+
+	invalidate(): void {
+		if (this.#step) this.#step.invalidate();
+		else this.#list.invalidate();
+	}
+
+	dispose(): void {
+		this.#disposed = true;
+	}
+
+	render(width: number, maxLines?: number): readonly string[] {
+		const intro = new Text(theme.fg("muted", "Choose the provider the web_search tool should prefer."), 0, 0);
+		const status = new Container();
+		const selected = this.#list.getSelectedItem();
+		if (selected) {
+			for (const line of this.#readinessLines(selected.value)) {
+				status.addChild(new Text(truncateToWidth(line, width), 0, 0));
+			}
+		}
+		if (selected && this.#status.length > 0) status.addChild(new Spacer(1));
+		for (const line of this.#status) {
+			status.addChild(new Text(truncateToWidth(line, width), 0, 0));
+		}
+		if (!this.#step) {
+			this.#step = new WizardStep({
+				kind: "choice",
+				intro,
+				content: this.#list,
+				status,
+				minContentLines: 1,
+				fitContent: budget => {
+					// Above: hint + blank. Below: the list's own search-status row plus
+					// blank + readiness line. Shrinking keeps the selection centered.
+					const visible = budget === undefined ? MAX_VISIBLE : budget - 1;
+					this.#list.setMaxVisible(Math.max(1, Math.min(MAX_VISIBLE, visible)));
+				},
+			});
+		} else {
+			this.#step.setIntro(intro);
+			this.#step.setStatus(status);
+		}
+		this.#step.setMaxHeight(maxLines);
+		return this.#step.render(width);
+	}
+
+	#onHighlight(value: string): void {
+		this.#status = [];
+		if (value !== "auto") this.#checkAvailability(value as SearchProviderId);
+		this.#host.requestRender();
+	}
+
+	#checkAvailability(id: SearchProviderId): void {
+		if (this.#availability.has(id)) return;
+		this.#availability.set(id, "checking");
+		void (async () => {
+			let ready = false;
+			try {
+				ready = await this.#host.ctx.isSearchProviderAvailable(id);
+			} catch {
+				ready = false;
+			}
+			if (this.#disposed) return;
+			this.#availability.set(id, ready);
+			this.#host.requestRender();
+		})();
+	}
+
+	#apply(value: string): void {
+		const option = SEARCH_PROVIDER_OPTIONS.find(option => option.value === value);
+		if (!option) return;
+		// The wizard picks one favorite; persist it as the head of the priority
+		// list with the remaining providers in their built-in order (auto = reset).
+		this.#host.ctx.saveSearchProvider(option.value);
+		const label = WEB_SEARCH_ITEMS.find(item => item.value === value)?.label ?? value;
+		this.#status = [theme.fg("success", `${theme.status.success} Web search set to ${label}`)];
+		if (value !== "auto" && this.#availability.get(value as SearchProviderId) === false) {
+			this.#status.push(theme.fg("dim", "Not configured yet — add its API key or sign in to enable it."));
+		}
+		this.#host.requestRender();
+	}
+
+	#readinessLines(value: string): string[] {
+		if (value === "auto") {
+			return [theme.fg("dim", "Automatically uses the first configured provider.")];
+		}
+		const state = this.#availability.get(value as SearchProviderId);
+		if (state === undefined || state === "checking") {
+			return [theme.fg("dim", "Checking availability…")];
+		}
+		return state
+			? [theme.fg("success", `${theme.status.success} Ready to use`)]
+			: [theme.fg("warning", `${theme.status.pending} Needs credentials`)];
+	}
+}

package/src/setup/setup-version.ts

@@ -0,0 +1,11 @@
+/**
+ * Setup version the wizard advances a fresh install to. Bump it whenever a new
+ * setup scene lands (or an existing scene raises its `minVersion`).
+ *
+ * Kept in its own dependency-free module so the cold-launch gate in `main.ts`
+ * can answer "is the stored setup version stale?" without statically importing
+ * the full wizard — every scene (sign-in/OAuth, web search, theme previews) plus
+ * the overlay component and their TUI deps. MUST equal `max(scene.minVersion)`
+ * across `ALL_SCENES`; the setup scene selection tests guard this invariant.
+ */
+export const CURRENT_SETUP_VERSION = 2;