@oh-my-pi/pi-tui 18.2.3 → 18.2.5

package/src/setup/scenes/providers.ts

@@ -0,0 +1,107 @@
+import { type SgrMouseEvent } from "../../mouse";
+import { TabBar } from "../../components/tab-bar";
+import { getTabBarTheme } from "../../chrome/shared";
+import { SignInTab } from "./sign-in";
+import type { SetupScene, SetupSceneController, SetupSceneHost, SetupTab } from "./types";
+import { WebSearchTab } from "./web-search";
+
+/**
+ * Tabbed "Set up your providers" scene. Composes independent panels (model
+ * sign-in, web search) behind a {@link TabBar}; the active panel owns
+ * rendering and input, while modal panels (e.g. an in-flight OAuth login)
+ * temporarily suppress tab switching.
+ */
+class ProvidersSceneController implements SetupSceneController {
+	title = "Set up your providers";
+	subtitle = "Sign in and pick a web search provider. Press Esc when you're done.";
+
+	#tabs: SetupTab[];
+	#tabBar: TabBar;
+	/** Lines the tab bar occupied in the last render (body starts one blank line below). */
+	#tabRowCount = 1;
+
+	constructor(host: SetupSceneHost) {
+		this.#tabs = [new SignInTab(host), new WebSearchTab(host)];
+		this.#tabBar = new TabBar(
+			"Providers",
+			this.#tabs.map(tab => ({ id: tab.id, label: tab.label })),
+			getTabBarTheme(),
+		);
+		this.#tabBar.onTabChange = () => {
+			this.#activeTab().onActivate?.();
+			host.requestRender();
+		};
+	}
+
+	#activeTab(): SetupTab {
+		return this.#tabs[this.#tabBar.getActiveIndex()] ?? this.#tabs[0];
+	}
+
+	onMount(): void {
+		this.#activeTab().onActivate?.();
+	}
+
+	invalidate(): void {
+		for (const tab of this.#tabs) tab.invalidate();
+	}
+
+	handleInput(data: string): void {
+		const tab = this.#activeTab();
+		if (tab.modal) {
+			tab.handleInput(data);
+			return;
+		}
+		if (this.#tabBar.handleInput(data)) return;
+		tab.handleInput(data);
+	}
+
+	/**
+	 * Hit-test mouse reports against the last render: rows inside the tab bar
+	 * hover/switch tabs (suppressed while the active panel is modal, matching
+	 * keyboard tab cycling); everything else forwards to the active panel at
+	 * panel-local coordinates. Wheel always goes to the panel so scrolling
+	 * works regardless of pointer position.
+	 */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		const tab = this.#activeTab();
+		if (event.wheel === null && line >= 0 && line < this.#tabRowCount) {
+			if (tab.modal) return;
+			const hit = this.#tabBar.tabAt(line, col);
+			if (event.motion) {
+				this.#tabBar.setHoverTab(hit && !hit.muted ? hit.id : null);
+			} else if (event.leftClick && hit) {
+				this.#tabBar.selectTab(hit.id);
+			}
+			return;
+		}
+		if (event.motion) this.#tabBar.setHoverTab(null);
+		const spacerRowsAfterTabs = 1;
+		const bodyLine = line - this.#tabRowCount - spacerRowsAfterTabs;
+		if (tab.routeMouse) {
+			tab.routeMouse(event, bodyLine, col);
+			return;
+		}
+		if (event.wheel !== null && !tab.modal) {
+			tab.handleInput(event.wheel === -1 ? "\x1b[A" : "\x1b[B");
+		}
+	}
+
+	render(width: number, maxLines?: number): readonly string[] {
+		const tabLines = this.#tabBar.render(width);
+		this.#tabRowCount = tabLines.length;
+		const tabBudget = maxLines === undefined ? undefined : Math.max(1, maxLines - tabLines.length - 1);
+		return [...tabLines, "", ...this.#activeTab().render(width, tabBudget)];
+	}
+
+	dispose(): void {
+		for (const tab of this.#tabs) tab.dispose();
+	}
+}
+
+/** Configure provider sign-in and the preferred web search backend. */
+export const providersSetupScene: SetupScene = {
+	id: "providers",
+	title: "Set up your providers",
+	minVersion: 1,
+	mount: host => new ProvidersSceneController(host),
+};

package/src/setup/scenes/sign-in.ts

@@ -0,0 +1,373 @@
+import type { AuthStorage } from "@oh-my-pi/pi-ai";
+import { PASTE_CODE_LOGIN_PROVIDERS } from "@oh-my-pi/pi-ai";
+import type { OAuthPrompt, OAuthProvider } from "@oh-my-pi/pi-ai/oauth/types";
+import { type Component, type Focusable, Container } from "../../tui";
+import { Spacer } from "../../components/spacer";
+import { Text } from "../../components/text";
+import { WizardStep } from "../../components/wizard-step";
+import { Input } from "../../components/input";
+import { matchesKey } from "../../keys";
+import { type SgrMouseEvent } from "../../mouse";
+import { wrapTextWithAnsi } from "../../utils";
+import { getAgentDbPath } from "@oh-my-pi/pi-utils";
+import { OAuthSelectorComponent } from "../../overlays/oauth-selector";
+import { theme } from "../../theme/theme";
+import type { SetupSceneHost, SetupTab } from "./types";
+
+function loginUrlLink(url: string): string {
+	return `\x1b]8;;${url}\x07Open login URL\x1b]8;;\x07`;
+}
+
+function loginCopyHint(): string {
+	return theme.fg("dim", "(clipboard copy attempted; Alt+C retries)");
+}
+
+class CopyablePromptInput implements Component, Focusable {
+	#input: Input;
+	#onCopy: () => void;
+
+	constructor(input: Input, onCopy: () => void) {
+		this.#input = input;
+		this.#onCopy = onCopy;
+	}
+
+	get focused(): boolean {
+		return this.#input.focused;
+	}
+
+	set focused(value: boolean) {
+		this.#input.focused = value;
+	}
+
+	setUseTerminalCursor(useTerminalCursor: boolean): void {
+		this.#input.setUseTerminalCursor(useTerminalCursor);
+	}
+
+	render(width: number): readonly string[] {
+		return this.#input.render(width);
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "alt+c")) {
+			this.#onCopy();
+			return;
+		}
+		this.#input.handleInput(data);
+	}
+
+	invalidate(): void {
+		this.#input.invalidate();
+	}
+}
+
+interface PromptState {
+	message: string;
+	placeholder?: string;
+	input: CopyablePromptInput;
+}
+
+/**
+ * "Sign in" panel: lets the user authenticate one or more model providers via
+ * OAuth. Unlike a standalone scene it never auto-advances the wizard — the user
+ * may sign in to several providers and then continue with Esc.
+ */
+export class SignInTab implements SetupTab {
+	readonly id = "sign-in";
+	readonly label = "Sign in";
+
+	#authStorage: AuthStorage;
+	#selector: OAuthSelectorComponent;
+	#statusLines: string[] = [];
+	#authUrl: string | undefined;
+	#authLaunchUrl: string | undefined;
+	#prompt: PromptState | undefined;
+	#promptResolve: ((value: string) => void) | undefined;
+	#promptReject: ((error: Error) => void) | undefined;
+	#promptAbortCleanup: (() => void) | undefined;
+	#loginAbort: AbortController | undefined;
+	#loggingInProvider: string | undefined;
+	#disposed = false;
+	#step: WizardStep | undefined;
+
+	readonly #host: SetupSceneHost;
+
+	constructor(host: SetupSceneHost) {
+		this.#host = host;
+		this.#authStorage = host.ctx.authStorage;
+		this.#selector = this.#createSelector();
+	}
+
+	/** Modal while an OAuth flow is running so the scene won't switch tabs or finish. */
+	get modal(): boolean {
+		return this.#loggingInProvider !== undefined;
+	}
+
+	dispose(): void {
+		this.#disposed = true;
+		this.#selector.stopValidation();
+		this.#loginAbort?.abort();
+		this.#resolvePrompt("");
+	}
+
+	invalidate(): void {
+		this.#step?.invalidate();
+		this.#selector.invalidate();
+		this.#prompt?.input.invalidate();
+	}
+
+	handleInput(data: string): void {
+		if (this.#loggingInProvider) {
+			if (this.#authUrl && (matchesKey(data, "alt+c") || (data === "c" && !this.#prompt))) {
+				void this.#copyAuthUrl();
+				return;
+			}
+			if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+				this.#loginAbort?.abort();
+			}
+			return;
+		}
+		this.#selector.handleInput(data);
+	}
+
+	/** Forward mouse to the provider selector; pointer is inert during an active login or code prompt. */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		if (this.#loggingInProvider || this.#prompt) return;
+		this.#step?.routeMouse(event, line, col);
+	}
+
+	render(width: number, maxLines?: number): readonly string[] {
+		// Hint + blank cost two rows; the wizard subtitle already explains
+		// this panel, so on short screens the rows go to the provider list
+		// instead (17 = full selector: 4 chrome above, 10 rows, 3 below).
+		let intro: Container | undefined;
+		if (this.#loggingInProvider === undefined && (maxLines === undefined || maxLines >= 17 + 2)) {
+			intro = new Container();
+			intro.addChild(
+				new Text(theme.fg("muted", "Pick a provider to sign in — you can connect more than one."), 0, 0),
+			);
+			intro.addChild(new Spacer(1));
+		}
+		const tail = new Container();
+		const urlLines = this.#authUrl ? wrapTextWithAnsi(theme.fg("dim", this.#authUrl), width) : [];
+		if (this.#authUrl) {
+			tail.addChild(
+				new Text(theme.fg("accent", `Browser login: ${loginUrlLink(this.#authUrl)} ${loginCopyHint()}`), 0, 0),
+			);
+			// Keep one URL row above the prompt; repeat the complete wrapped URL
+			// below so the input remains visible in the wizard's short viewport.
+			if (urlLines[0]) tail.addChild(new Text(urlLines[0], 0, 0));
+			if (this.#authLaunchUrl) {
+				tail.addChild(
+					new Text(theme.fg("dim", `Local shortcut (this machine only): ${this.#authLaunchUrl}`), 0, 0),
+				);
+			}
+		}
+		if (this.#prompt) {
+			tail.addChild(new Text(theme.fg("warning", this.#prompt.message), 0, 0));
+			if (this.#prompt.placeholder) {
+				tail.addChild(new Text(theme.fg("dim", this.#prompt.placeholder), 0, 0));
+			}
+			tail.addChild(this.#prompt.input);
+		}
+		if (urlLines.length > 1) {
+			for (const line of urlLines) {
+				tail.addChild(new Text(line, 0, 0));
+			}
+		}
+		for (const line of this.#statusLines) {
+			for (const wrapped of wrapTextWithAnsi(line, width)) {
+				tail.addChild(new Text(wrapped, 0, 0));
+			}
+		}
+		if (!this.#step) {
+			this.#step = new WizardStep({
+				kind: "choice",
+				content: this.#selector,
+				gap: 0,
+				fitContent: budget => {
+					if (budget !== undefined) this.#selector.setMaxHeight(budget);
+				},
+			});
+		}
+		if (this.#loggingInProvider) {
+			this.#step.setKind("async");
+			this.#step.setHeading(new Text(theme.bold(`Signing in to ${this.#loggingInProvider}`), 0, 0));
+			this.#step.setIntro(undefined);
+			this.#step.setContent(tail);
+			this.#step.setStatus(undefined);
+		} else {
+			this.#step.setKind("choice");
+			this.#step.setHeading(undefined);
+			this.#step.setIntro(intro);
+			this.#step.setContent(this.#selector);
+			this.#step.setStatus(tail);
+		}
+		this.#step.setMaxHeight(maxLines);
+		return this.#step.render(width);
+	}
+
+	#createSelector(): OAuthSelectorComponent {
+		return new OAuthSelectorComponent(
+			"login",
+			this.#authStorage,
+			providerId => {
+				void this.#login(providerId);
+			},
+			() => this.#host.finish("skipped"),
+			{ requestRender: () => this.#host.requestRender(), disabledProviders: this.#host.ctx.disabledProviders },
+		);
+	}
+
+	async #login(providerId: string): Promise<void> {
+		if (this.#loggingInProvider || this.#disposed) return;
+		const useManualInput = PASTE_CODE_LOGIN_PROVIDERS.has(providerId);
+		this.#selector.stopValidation();
+		this.#loggingInProvider = providerId;
+		this.#statusLines = [theme.fg("dim", "Starting OAuth flow…")];
+		this.#authUrl = undefined;
+		this.#authLaunchUrl = undefined;
+		this.#loginAbort = new AbortController();
+		this.#host.restoreFocus();
+		this.#host.requestRender();
+		try {
+			await this.#authStorage.login(providerId as OAuthProvider, {
+				signal: this.#loginAbort.signal,
+				onBrowserSession: (request, signal) => this.#host.ctx.captureBrowserSession(request, signal),
+				onAuth: info => {
+					// Store the full authorization URL as the primary copy/display
+					// target: it works from any machine, including SSH boxes where
+					// the OMP-hosted `launchUrl` would resolve against the user's
+					// local browser and fail. The wizard render uses
+					// `wrapTextWithAnsi`, so long URLs wrap across lines rather
+					// than getting truncated — the RFC 7636 §4.3 PKCE-downgrade
+					// bug that motivated `launchUrl` is unreachable through this
+					// surface. `launchUrl` is still surfaced as an optional local
+					// shortcut for wide-terminal local users.
+					this.#authUrl = info.url;
+					this.#authLaunchUrl = info.launchUrl && info.launchUrl !== info.url ? info.launchUrl : undefined;
+					this.#statusLines = [];
+					if (info.instructions) {
+						this.#statusLines.push(theme.fg("warning", info.instructions));
+					}
+					if (useManualInput) {
+						this.#statusLines.push(theme.fg("dim", "Paste the returned code or redirect URL when prompted."));
+					}
+					void this.#copyAuthUrl();
+					this.#host.ctx.openInBrowser(info.url);
+					this.#host.requestRender();
+				},
+				onPrompt: prompt => this.#showPrompt(prompt),
+				onProgress: message => {
+					this.#statusLines.push(theme.fg("dim", message));
+					this.#host.requestRender();
+				},
+				onManualCodeInput: signal =>
+					this.#showPrompt({ message: "Paste the authorization code (or full redirect URL):" }, signal),
+			});
+			// Provider-scoped online refresh so the just-persisted credential re-runs
+			// discovery instead of reusing a fresh authoritative cache row (#5780).
+			await this.#host.ctx.refreshProvider(providerId);
+			if (this.#disposed) return;
+			this.#statusLines = [
+				theme.fg("success", `${theme.status.success} Signed in to ${providerId}`),
+				theme.fg("dim", `Credentials saved to ${getAgentDbPath()}`),
+			];
+			this.#authUrl = undefined;
+			this.#authLaunchUrl = undefined;
+			this.#loggingInProvider = undefined;
+			this.#loginAbort = undefined;
+			this.#selector.stopValidation();
+			this.#selector = this.#createSelector();
+			this.#host.restoreFocus();
+			this.#host.requestRender();
+		} catch (error) {
+			if (this.#disposed) return;
+			if (this.#loginAbort?.signal.aborted) {
+				this.#statusLines = [theme.fg("dim", "Login cancelled.")];
+				this.#authUrl = undefined;
+				this.#authLaunchUrl = undefined;
+			} else {
+				const message = error instanceof Error ? error.message : String(error);
+				this.#statusLines = [
+					theme.fg("error", `Login failed: ${message}`),
+					theme.fg("dim", "Choose another provider or press Esc to continue."),
+				];
+				this.#authUrl = undefined;
+				this.#authLaunchUrl = undefined;
+			}
+			this.#loggingInProvider = undefined;
+			this.#loginAbort = undefined;
+			this.#host.restoreFocus();
+			this.#host.requestRender();
+		}
+	}
+
+	async #copyAuthUrl(): Promise<void> {
+		const url = this.#authUrl;
+		if (!url) return;
+		try {
+			await this.#host.ctx.copyToClipboard(url);
+		} catch {
+			// Clipboard integration is best-effort; the full URL remains rendered below.
+		}
+		this.#host.requestRender();
+	}
+
+	#showPrompt(prompt: OAuthPrompt, signal?: AbortSignal): Promise<string> {
+		this.#resolvePrompt("");
+		if (signal?.aborted) {
+			return Promise.reject(signal.reason instanceof Error ? signal.reason : new Error("Login input cancelled"));
+		}
+		const input = new Input();
+		input.mask = prompt.secret === true;
+		const focusInput = new CopyablePromptInput(input, () => {
+			void this.#copyAuthUrl();
+		});
+		const pending = Promise.withResolvers<string>();
+		this.#promptResolve = pending.resolve;
+		this.#promptReject = pending.reject;
+		this.#prompt = { message: prompt.message, placeholder: prompt.placeholder, input: focusInput };
+		if (signal) {
+			const onAbort = () => {
+				if (this.#promptReject !== pending.reject) return;
+				this.#rejectPrompt(signal.reason instanceof Error ? signal.reason : new Error("Login input cancelled"));
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+			this.#promptAbortCleanup = () => signal.removeEventListener("abort", onAbort);
+		}
+		input.onSubmit = value => {
+			this.#resolvePrompt(value);
+		};
+		input.onEscape = () => {
+			this.#loginAbort?.abort();
+			this.#resolvePrompt("");
+		};
+		this.#host.setFocus(focusInput);
+		this.#host.requestRender();
+		return pending.promise;
+	}
+
+	#resolvePrompt(value: string): void {
+		const resolve = this.#promptResolve;
+		if (!resolve) return;
+		this.#clearPrompt();
+		resolve(value);
+	}
+
+	#rejectPrompt(error: Error): void {
+		const reject = this.#promptReject;
+		if (!reject) return;
+		this.#clearPrompt();
+		reject(error);
+	}
+
+	#clearPrompt(): void {
+		this.#promptAbortCleanup?.();
+		this.#promptAbortCleanup = undefined;
+		this.#promptResolve = undefined;
+		this.#promptReject = undefined;
+		this.#prompt = undefined;
+		this.#host.restoreFocus();
+		this.#host.requestRender();
+	}
+}

package/src/setup/scenes/splash.ts

@@ -0,0 +1,192 @@
+import { centerLine, visibleWidth } from "../../utils";
+import { padToWidth } from "../../render/utils";
+import { gradientEscape, gradientLogo, PI_LOGO, type ShineConfig } from "../../prompt/welcome";
+import { theme } from "../../theme/theme";
+
+export const SETUP_SPLASH_MS = 2600;
+export const SETUP_TICK_MS = 33;
+
+/** Brand mark at 2x: every glyph doubled horizontally, every row doubled vertically. */
+const LARGE_LOGO = PI_LOGO.flatMap(line => {
+	let wide = "";
+	for (const char of line) {
+		wide += char === " " ? "  " : `${char}${char}`;
+	}
+	return [wide, wide];
+});
+const LOGO_WIDTH = Math.max(...LARGE_LOGO.map(line => visibleWidth(line)));
+const LOGO_HEIGHT = LARGE_LOGO.length;
+const RESET = "\x1b[0m";
+
+/** Full scene needs comfortable room; below this we drop to a centered mark. */
+const MIN_SCENE_WIDTH = 56;
+const MIN_SCENE_HEIGHT = 22;
+
+const SKIP_HINT = "press enter to skip";
+
+/** Density ramp for the rippling water, lightest → heaviest. */
+const WATER_RAMP = [
+	{ min: 0.62, char: "█" },
+	{ min: 0.5, char: "▓" },
+	{ min: 0.36, char: "▒" },
+	{ min: 0.24, char: "░" },
+];
+
+function starAt(x: number, y: number, frame: number): string {
+	const hash = (x * 73856093) ^ (y * 19349663) ^ (frame * 83492791);
+	const bucket = Math.abs(hash) % 97;
+	if (bucket === 0) return theme.fg("accent", "✦");
+	if (bucket === 1) return theme.fg("muted", "·");
+	return " ";
+}
+
+export function renderStarfield(width: number, height: number, frame: number): string[] {
+	const lines: string[] = [];
+	for (let y = 0; y < height; y++) {
+		let line = "";
+		for (let x = 0; x < width; x++) {
+			line += starAt(x, y, frame >> 3);
+		}
+		lines.push(line);
+	}
+	return lines;
+}
+
+/** Continuous diagonal gradient position (bottom-left → top-right) across the whole screen. */
+function screenGradientT(x: number, y: number, width: number, height: number, phase: number): number {
+	const span = Math.max(1, width + height - 1);
+	const base = (x + (height - 1 - y)) / span;
+	return (((base + phase) % 1) + 1) % 1;
+}
+
+/** Twinkling sparkle for the upper "sky". Returns a styled glyph, or null for empty space. */
+function skyGlyph(x: number, y: number, frame: number): string | null {
+	const hash = (x * 73856093) ^ (y * 19349663) ^ (frame * 83492791);
+	const bucket = Math.abs(hash) % 150;
+	if (bucket === 0) return theme.fg("accent", "✦");
+	if (bucket === 1) return theme.fg("border", "✧");
+	if (bucket === 2) return theme.fg("border", "·");
+	return null;
+}
+
+/** Static value-jitter in [0,1) that softens the water's threshold banding. */
+function waterJitter(x: number, y: number): number {
+	let h = Math.imul(x, 374761393) + Math.imul(y, 668265263);
+	h = Math.imul(h ^ (h >>> 13), 1274126177);
+	h ^= h >>> 16;
+	return (h >>> 0) / 4294967296;
+}
+
+/**
+ * Rippling water amplitude in [0,1] at (x, y): three travelling sine waves
+ * interfere, then a radial edge falloff and a downward fade concentrate the
+ * ripples beneath the mark and dissolve them toward the edges/bottom. `t`
+ * advances each tick, so the surface drifts.
+ */
+function waterAmplitude(
+	x: number,
+	y: number,
+	cx: number,
+	waterTop: number,
+	waterHeight: number,
+	width: number,
+	t: number,
+): number {
+	const dx = (x - cx) / 2;
+	const dy = y - waterTop;
+	const dist = Math.sqrt(dx * dx + dy * dy);
+	const wave =
+		0.5 * Math.sin(dist * 0.55 - t) +
+		0.3 * Math.sin(x * 0.22 + y * 0.45 - t * 0.7) +
+		0.2 * Math.sin(Math.abs(dx) * 0.8 + dy * 0.5 - t * 1.4);
+	const level = 0.5 + 0.5 * wave;
+	const edge = Math.max(0, 1 - Math.abs(x - cx) / (width * 0.5));
+	const fade = Math.max(0, 1 - (dy / Math.max(1, waterHeight)) * 0.55);
+	return level * edge ** 0.7 * fade;
+}
+
+/**
+ * Animated setup splash, in the spirit of the omp landing page: the brand π
+ * mark rendered with the live diagonal gradient + shine sweep, rising out of a
+ * rippling, gradient-lit water surface, under a faint twinkling starfield. The
+ * mark and water share one continuous gradient so the sweep reads across the
+ * whole scene; the water surface drifts each frame.
+ */
+export function renderSetupSplash(width: number, height: number, elapsedMs: number): string[] {
+	const w = Math.max(1, width);
+	const h = Math.max(1, height);
+	const progress = Math.max(0, Math.min(1, elapsedMs / SETUP_SPLASH_MS));
+	const phase = progress * 1.8;
+	const shine: ShineConfig = { pos: (progress * 2.5) % 1, strength: Math.max(0, 1 - progress * 0.35) };
+
+	if (w < MIN_SCENE_WIDTH || h < MIN_SCENE_HEIGHT) return renderCompactSplash(w, h, phase, shine);
+
+	const frame = Math.floor(elapsedMs / SETUP_TICK_MS);
+	const cx = Math.floor(w / 2);
+	const surfaceTime = frame * 0.13;
+
+	// oxlint-disable-next-line unicorn/no-new-array -- length preallocation
+	const cells: string[][] = Array.from({ length: h }, () => new Array<string>(w).fill(" "));
+	const put = (x: number, y: number, glyph: string): void => {
+		if (y >= 0 && y < h && x >= 0 && x < w) cells[y][x] = glyph;
+	};
+
+	const hx = Math.floor((w - LOGO_WIDTH) / 2);
+	const hy = Math.max(2, Math.floor(h * 0.16));
+	const waterTop = hy + LOGO_HEIGHT;
+	const waterHeight = Math.max(1, h - waterTop);
+
+	// 1. rippling water surface (shares the screen-wide gradient with the mark)
+	for (let y = waterTop; y < h; y++) {
+		for (let x = 0; x < w; x++) {
+			const amp = waterAmplitude(x, y, cx, waterTop, waterHeight, w, surfaceTime) + (waterJitter(x, y) - 0.5) * 0.06;
+			const cell = WATER_RAMP.find(step => amp > step.min);
+			if (cell) put(x, y, gradientEscape(screenGradientT(x, y, w, h, phase), shine) + cell.char + RESET);
+		}
+	}
+	// 2. twinkling starfield in the sky above the water
+	for (let y = 0; y < waterTop - 1; y++) {
+		for (let x = 0; x < w; x++) {
+			const star = skyGlyph(x, y, frame >> 3);
+			if (star) put(x, y, star);
+		}
+	}
+	// 3. hero — the brand mark with the live gradient + shine sweep
+	LARGE_LOGO.forEach((line, row) => {
+		let col = 0;
+		for (const ch of line) {
+			if (ch !== " ") {
+				put(
+					hx + col,
+					hy + row,
+					gradientEscape(screenGradientT(hx + col, hy + row, w, h, phase), shine) + ch + RESET,
+				);
+			}
+			col++;
+		}
+	});
+	// 4. skip hint on a cleared strip at the bottom so it stays legible over the water
+	const hintWidth = visibleWidth(SKIP_HINT);
+	const hintStart = Math.floor((w - hintWidth) / 2);
+	const hintRow = h - 1;
+	for (let x = hintStart - 1; x <= hintStart + hintWidth; x++) put(x, hintRow, " ");
+	let col = hintStart;
+	for (const ch of SKIP_HINT) put(col++, hintRow, ch === " " ? " " : theme.fg("dim", ch));
+
+	return cells.map(row => row.join(""));
+}
+
+/** Centered fallback for windows too small to hold the full scene. */
+function renderCompactSplash(width: number, height: number, phase: number, shine: ShineConfig): string[] {
+	const art = height >= 14 ? LARGE_LOGO : PI_LOGO;
+	const content = [...gradientLogo(art, phase, shine), "", theme.bold("O h   M y   P i")];
+	const start = Math.max(0, Math.floor((height - content.length) / 2));
+	const lines: string[] = [];
+	for (let y = 0; y < height; y++) {
+		const item = content[y - start];
+		lines.push(width > 0 ? padToWidth(item !== undefined ? centerLine(item, width) : "", width) : "");
+	}
+	if (height > 2)
+		lines[height - 2] = width > 0 ? padToWidth(centerLine(theme.fg("dim", SKIP_HINT), width), width) : "";
+	return lines;
+}