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

package/src/setup/startup-splash.ts

@@ -0,0 +1,107 @@
+import { type Component, type OverlayFocusOwner } from "../tui";
+import { matchesKey } from "../keys";
+import type { SetupUiHost } from "./scenes/types";
+import { renderSetupSplash, SETUP_SPLASH_MS, SETUP_TICK_MS } from "./scenes/splash";
+
+/** Timing controls for the standalone startup animation. */
+export interface RunStartupSplashOptions {
+	readonly durationMs?: number;
+	readonly tickMs?: number;
+	readonly now?: () => number;
+}
+
+class StartupSplashComponent implements Component, OverlayFocusOwner {
+	#phaseStartedAt = 0;
+	#timer: NodeJS.Timeout | undefined;
+	#done = Promise.withResolvers<void>();
+	#disposed = false;
+	readonly #durationMs: number;
+	readonly #tickMs: number;
+	readonly #now: () => number;
+
+	constructor(
+		readonly ctx: SetupUiHost,
+		options: RunStartupSplashOptions = {},
+	) {
+		this.#durationMs = options.durationMs ?? SETUP_SPLASH_MS;
+		this.#tickMs = options.tickMs ?? SETUP_TICK_MS;
+		this.#now = options.now ?? (() => performance.now());
+	}
+
+	run(): Promise<void> {
+		this.#phaseStartedAt = this.#now();
+		this.#startTimer();
+		this.ctx.ui.requestRender();
+		return this.#done.promise;
+	}
+
+	dispose(): void {
+		this.#disposed = true;
+		this.#stopTimer();
+	}
+
+	ownsOverlayFocusTarget(component: Component): boolean {
+		return component === this;
+	}
+
+	handleInput(data: string): void {
+		if (
+			matchesKey(data, "enter") ||
+			matchesKey(data, "return") ||
+			matchesKey(data, "space") ||
+			matchesKey(data, "escape")
+		) {
+			this.#complete();
+		}
+	}
+
+	render(width: number): readonly string[] {
+		const elapsedMs = Math.min(this.#durationMs, Math.max(0, this.#now() - this.#phaseStartedAt));
+		return renderSetupSplash(Math.max(1, width), Math.max(1, this.ctx.ui.terminal.rows), elapsedMs);
+	}
+
+	#startTimer(): void {
+		if (this.#timer) return;
+		this.#timer = setInterval(() => {
+			if (this.#disposed) return;
+			const elapsed = this.#now() - this.#phaseStartedAt;
+			if (elapsed >= this.#durationMs) {
+				this.#complete();
+				return;
+			}
+			this.ctx.ui.requestRender();
+		}, this.#tickMs);
+	}
+
+	#stopTimer(): void {
+		if (!this.#timer) return;
+		clearInterval(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#complete(): void {
+		if (this.#disposed) return;
+		this.#stopTimer();
+		this.#done.resolve();
+	}
+}
+
+/** Show the startup animation and restore the previous overlay focus afterward. */
+export async function runStartupSplash(ctx: SetupUiHost, options: RunStartupSplashOptions = {}): Promise<void> {
+	const component = new StartupSplashComponent(ctx, options);
+	const overlay = ctx.ui.showOverlay(component, {
+		width: "100%",
+		maxHeight: "100%",
+		anchor: "top-left",
+		margin: 0,
+		fullscreen: true,
+	});
+	try {
+		ctx.ui.setFocus(component);
+		await component.run();
+	} finally {
+		component.dispose();
+		ctx.ui.setFocus(component);
+		overlay.hide();
+	}
+}

package/src/setup/wizard-overlay.ts

@@ -0,0 +1,319 @@
+import { type Component, type OverlayFocusOwner } from "../tui";
+import { matchesKey } from "../keys";
+import { centerLine, padding } from "../utils";
+import { padToWidth } from "../render/utils";
+import { routeSgrMouseInput, type SgrMouseEvent } from "../mouse";
+import { APP_NAME } from "@oh-my-pi/pi-utils";
+import { gradientLogo, PI_LOGO } from "../prompt/welcome";
+import { theme } from "../theme/theme";
+import type { SetupHost } from "./scenes/types";
+import { renderSetupOutro, SETUP_OUTRO_MS } from "./scenes/outro";
+import { renderSetupSplash, SETUP_SPLASH_MS, SETUP_TICK_MS } from "./scenes/splash";
+import type { SetupScene, SetupSceneController, SetupSceneHost, SetupSceneResult } from "./scenes/types";
+
+type WizardPhase = "splash" | "transition" | "scene" | "outro" | "done";
+
+const SCENE_MARGIN_X = 4;
+const MIN_CONTENT_WIDTH = 20;
+/** Cross-dissolve duration from the splash into the first scene. */
+const SCENE_TRANSITION_MS = 420;
+
+function indentLine(line: string, width: number, indent: number): string {
+	const prefix = padding(Math.min(indent, Math.max(0, width - 1)));
+	return width > 0 ? padToWidth(prefix + line, width) : "";
+}
+/** Stable per-row jitter in [0,1) for the dissolve reveal order. */
+function rowNoise(y: number): number {
+	const h = Math.imul(y ^ 0x9e3779b9, 2654435761);
+	return ((h ^ (h >>> 15)) >>> 0) / 4294967296;
+}
+
+/**
+ * Top-biased cross-dissolve between two equal-height frames. As `progress`
+ * (0..1) advances, each row flips from `from` to `to` once it crosses a per-row
+ * threshold — top rows reveal first (so the scene's mark/header materializes
+ * before the splash water below it), with a little jitter for an organic edge.
+ */
+function dissolveFrames(from: string[], to: string[], progress: number, height: number): string[] {
+	const eased = progress * progress * (3 - 2 * progress);
+	const denom = Math.max(1, height - 1);
+	const out: string[] = [];
+	for (let y = 0; y < height; y++) {
+		const threshold = 0.78 * (y / denom) + 0.22 * rowNoise(y);
+		out.push((eased >= threshold ? to[y] : from[y]) ?? "");
+	}
+	return out;
+}
+
+/** Fullscreen onboarding presentation with scene focus and mouse routing. */
+export class SetupWizardComponent implements Component, OverlayFocusOwner {
+	#phase: WizardPhase = "splash";
+	#phaseStartedAt = performance.now();
+	#sceneIndex = 0;
+	#activeScene: SetupSceneController | undefined;
+	#timer: NodeJS.Timeout | undefined;
+	#done = Promise.withResolvers<void>();
+	#disposed = false;
+	/** Screen row where the active scene's body began in the last rendered frame. */
+	#bodyRowStart = 0;
+	#sceneFocusTarget: Component | undefined;
+
+	constructor(
+		readonly ctx: SetupHost,
+		readonly scenes: readonly SetupScene[],
+	) {}
+
+	run(): Promise<void> {
+		this.#phase = this.scenes.length === 0 ? "outro" : "splash";
+		this.#phaseStartedAt = performance.now();
+		this.#startTimer();
+		this.ctx.ui.requestRender();
+		return this.#done.promise;
+	}
+
+	dispose(): void {
+		this.#disposed = true;
+		this.#stopTimer();
+		this.#unmountActiveScene();
+	}
+
+	invalidate(): void {
+		this.#activeScene?.invalidate?.();
+	}
+
+	ownsOverlayFocusTarget(component: Component): boolean {
+		if (this.#sceneFocusTarget !== component) return false;
+		return true;
+	}
+
+	handleInput(data: string): void {
+		if (this.#phase === "done") return;
+		if (data.startsWith("\x1b[<")) {
+			routeSgrMouseInput(data, event => {
+				this.#routeMouseEvent(event);
+			});
+			return;
+		}
+		if (matchesKey(data, "ctrl+c")) {
+			this.#beginOutro();
+			return;
+		}
+		if (this.#phase === "splash") {
+			if (
+				matchesKey(data, "enter") ||
+				matchesKey(data, "return") ||
+				matchesKey(data, "space") ||
+				matchesKey(data, "escape")
+			) {
+				this.#beginScene();
+			}
+			return;
+		}
+		if (this.#phase === "outro") {
+			if (
+				matchesKey(data, "enter") ||
+				matchesKey(data, "return") ||
+				matchesKey(data, "space") ||
+				matchesKey(data, "escape")
+			) {
+				this.#complete();
+			}
+			return;
+		}
+		this.#activeScene?.handleInput?.(data);
+	}
+
+	/**
+	 * Mouse handling for the fullscreen wizard (SGR tracking is on while the
+	 * overlay holds the alternate screen). The frame paints from screen row 0,
+	 * so report coordinates index directly into the last rendered lines: scene
+	 * body rows start at #bodyRowStart, indented by SCENE_MARGIN_X. Scenes
+	 * that implement routeMouse get hit-tested events (wheel, hover, click);
+	 * for the rest a wheel notch falls back to an arrow key. A left click
+	 * advances the splash/outro like Enter. Raw reports never reach scene
+	 * keyboard input.
+	 */
+	#routeMouseEvent(event: SgrMouseEvent): void {
+		if (this.#phase === "splash" || this.#phase === "outro") {
+			if (!event.leftClick) return;
+			if (this.#phase === "splash") this.#beginScene();
+			else this.#complete();
+			return;
+		}
+		const scene = this.#activeScene;
+		if (!scene) return;
+		if (scene.routeMouse) {
+			scene.routeMouse(event, event.row - this.#bodyRowStart, event.col - SCENE_MARGIN_X);
+			return;
+		}
+		if (event.wheel !== null) {
+			scene.handleInput?.(event.wheel === -1 ? "\x1b[A" : "\x1b[B");
+		}
+	}
+
+	render(width: number): readonly string[] {
+		const safeWidth = Math.max(1, width);
+		const height = Math.max(1, this.ctx.ui.terminal.rows);
+		let lines: string[];
+		switch (this.#phase) {
+			case "splash":
+				lines = renderSetupSplash(safeWidth, height, performance.now() - this.#phaseStartedAt);
+				break;
+			case "transition": {
+				const elapsed = performance.now() - this.#phaseStartedAt;
+				const progress = Math.min(1, elapsed / SCENE_TRANSITION_MS);
+				const splash = renderSetupSplash(safeWidth, height, SETUP_SPLASH_MS + elapsed);
+				const scene = this.#renderScene(safeWidth, height);
+				lines = dissolveFrames(splash, scene, progress, height);
+				break;
+			}
+			case "outro":
+				lines = renderSetupOutro(safeWidth, height, performance.now() - this.#phaseStartedAt);
+				break;
+			case "scene":
+				lines = this.#renderScene(safeWidth, height);
+				break;
+			case "done":
+				lines = [];
+				break;
+		}
+		return this.#fitToScreen(lines, safeWidth, height);
+	}
+
+	#renderScene(width: number, height: number): string[] {
+		const scene = this.scenes[this.#sceneIndex];
+		const title = this.#activeScene?.title ?? scene?.title ?? "Setup";
+		const subtitle = this.#activeScene?.subtitle;
+		const contentWidth = Math.max(MIN_CONTENT_WIDTH, width - SCENE_MARGIN_X * 2);
+		const logo = gradientLogo(PI_LOGO, 0);
+		const header = [
+			"",
+			...logo.map(line => centerLine(line, width)),
+			centerLine(theme.bold(theme.fg("accent", APP_NAME)), width),
+			centerLine(theme.fg("muted", `Setup step ${this.#sceneIndex + 1} of ${this.scenes.length}`), width),
+			"",
+			indentLine(theme.bold(title), width, SCENE_MARGIN_X),
+		];
+		if (subtitle) {
+			header.push(indentLine(theme.fg("muted", subtitle), width, SCENE_MARGIN_X));
+		}
+		header.push("");
+		this.#bodyRowStart = header.length;
+
+		const footer = [
+			"",
+			centerLine(theme.fg("dim", "↑/↓ select · enter confirm · esc skip · ctrl+c exit setup"), width),
+		];
+		const maxBodyLines = Math.max(0, height - header.length - footer.length);
+		const body = this.#activeScene?.render(contentWidth, maxBodyLines).slice(0, maxBodyLines) ?? [];
+		const lines = [...header, ...body.map(line => indentLine(line, width, SCENE_MARGIN_X))];
+		while (lines.length + footer.length < height) {
+			lines.push("");
+		}
+		lines.push(...footer);
+		return lines;
+	}
+
+	#fitToScreen(lines: string[], width: number, height: number): string[] {
+		const fitted = lines.slice(0, height).map(line => (width > 0 ? padToWidth(line, width) : ""));
+		while (fitted.length < height) {
+			fitted.push(padding(width));
+		}
+		return fitted;
+	}
+
+	#startTimer(): void {
+		if (this.#timer) return;
+		this.#timer = setInterval(() => {
+			if (this.#disposed) return;
+			const elapsed = performance.now() - this.#phaseStartedAt;
+			if (this.#phase === "splash" && elapsed >= SETUP_SPLASH_MS) {
+				this.#beginScene();
+			} else if (this.#phase === "transition" && elapsed >= SCENE_TRANSITION_MS) {
+				this.#phase = "scene";
+				this.#phaseStartedAt = performance.now();
+				this.ctx.ui.requestRender();
+			} else if (this.#phase === "outro" && elapsed >= SETUP_OUTRO_MS) {
+				this.#complete();
+			} else {
+				this.ctx.ui.requestRender();
+			}
+		}, SETUP_TICK_MS);
+	}
+
+	#stopTimer(): void {
+		if (!this.#timer) return;
+		clearInterval(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#mountSceneController(targetPhase: "scene" | "transition"): void {
+		if (this.#disposed) return;
+		this.#unmountActiveScene();
+		if (this.#sceneIndex >= this.scenes.length) {
+			this.#beginOutro();
+			return;
+		}
+		const scene = this.scenes[this.#sceneIndex];
+		const host: SetupSceneHost = {
+			ctx: this.ctx,
+			requestRender: () => this.ctx.ui.requestRender(),
+			finish: (_result: SetupSceneResult) => this.#finishScene(),
+			setFocus: component => {
+				this.#sceneFocusTarget = component ?? undefined;
+				this.ctx.ui.setFocus(component);
+			},
+			restoreFocus: () => {
+				this.#sceneFocusTarget = undefined;
+				this.ctx.ui.setFocus(this);
+			},
+		};
+		this.#activeScene = scene.mount(host);
+		this.#phase = targetPhase;
+		this.#phaseStartedAt = performance.now();
+		this.#sceneFocusTarget = undefined;
+		this.ctx.ui.setFocus(this);
+		void this.#activeScene.onMount?.();
+		this.ctx.ui.requestRender();
+	}
+
+	/** Enter the first scene through a dissolve from the splash. */
+	#beginScene(): void {
+		this.#mountSceneController("transition");
+	}
+
+	#mountCurrentScene(): void {
+		this.#mountSceneController("scene");
+	}
+
+	#finishScene(): void {
+		if (this.#phase !== "scene" && this.#phase !== "transition") return;
+		this.#unmountActiveScene();
+		this.#sceneIndex += 1;
+		this.#mountCurrentScene();
+	}
+
+	#unmountActiveScene(): void {
+		this.#sceneFocusTarget = undefined;
+		this.#activeScene?.onUnmount?.();
+		this.#activeScene?.dispose?.();
+		this.#activeScene = undefined;
+	}
+
+	#beginOutro(): void {
+		if (this.#phase === "done") return;
+		this.#unmountActiveScene();
+		this.#phase = "outro";
+		this.#phaseStartedAt = performance.now();
+		this.ctx.ui.setFocus(this);
+		this.#startTimer();
+		this.ctx.ui.requestRender();
+	}
+
+	#complete(): void {
+		if (this.#phase === "done") return;
+		this.#phase = "done";
+		this.#stopTimer();
+		this.#done.resolve();
+	}
+}

package/src/setup/wizard.ts

@@ -0,0 +1,101 @@
+import { CURRENT_SETUP_VERSION } from "./setup-version";
+import type { SetupHost } from "./scenes/types";
+import { composerSetupScene } from "./scenes/composer";
+import { glyphSetupScene } from "./scenes/glyph";
+import { modelSetupScene } from "./scenes/model";
+import { providersSetupScene } from "./scenes/providers";
+import { themeSetupScene } from "./scenes/theme";
+import type { SetupScene } from "./scenes/types";
+import { SetupWizardComponent } from "./wizard-overlay";
+
+export type { SetupScene, SetupSceneController, SetupSceneHost, SetupSceneResult } from "./scenes/types";
+
+export { runStartupSplash } from "./startup-splash";
+export { CURRENT_SETUP_VERSION };
+
+/** Ordered onboarding scenes with independent version gates. */
+export const ALL_SCENES = [
+	providersSetupScene,
+	modelSetupScene,
+	glyphSetupScene,
+	composerSetupScene,
+	themeSetupScene,
+] as const satisfies readonly SetupScene[];
+
+/** Environment and invocation gates for onboarding scene selection. */
+export interface SetupSceneSelectionOptions {
+	resuming?: boolean;
+	isTTY?: boolean;
+	skipEnv?: string;
+	setupWizardEnabled?: boolean;
+	force?: boolean;
+}
+
+function setupSkipEnvEnabled(value: string | undefined): boolean {
+	if (value === undefined) return false;
+	const normalized = value.trim().toLowerCase();
+	return normalized !== "" && normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+
+/** Select scenes newer than the stored version, honoring hard environment gates. */
+export async function selectSetupScenes(
+	storedVersion: number,
+	scenes: readonly SetupScene[],
+	ctx?: SetupHost,
+	options: SetupSceneSelectionOptions = {},
+): Promise<SetupScene[]> {
+	const isTTY = options.isTTY ?? (process.stdin.isTTY && process.stdout.isTTY);
+	if (!isTTY) return [];
+	if (!options.force) {
+		if (options.resuming) return [];
+		if (setupSkipEnvEnabled(options.skipEnv ?? Bun.env.OMP_SKIP_SETUP)) return [];
+		if (options.setupWizardEnabled === false) return [];
+	}
+
+	const selected: SetupScene[] = [];
+	for (const scene of scenes) {
+		if (!options.force && scene.minVersion <= storedVersion) continue;
+		if (scene.shouldRun) {
+			if (!ctx) continue;
+			if (!(await scene.shouldRun(ctx))) continue;
+		}
+		selected.push(scene);
+	}
+	return selected;
+}
+
+/** Control completion persistence and the post-setup welcome animation. */
+export interface RunSetupWizardOptions {
+	markComplete?: boolean;
+	playWelcomeIntro?: boolean;
+}
+
+/** Own the fullscreen setup overlay until its scenes and outro finish. */
+export async function runSetupWizard(
+	ctx: SetupHost,
+	scenes: readonly SetupScene[] = ALL_SCENES,
+	options: RunSetupWizardOptions = {},
+): Promise<void> {
+	if (scenes.length === 0) return;
+	const component = new SetupWizardComponent(ctx, scenes);
+	const overlay = ctx.ui.showOverlay(component, {
+		width: "100%",
+		maxHeight: "100%",
+		anchor: "top-left",
+		margin: 0,
+		fullscreen: true,
+	});
+	try {
+		await component.run();
+		if (options.markComplete !== false) {
+			await ctx.markComplete(CURRENT_SETUP_VERSION);
+		}
+	} finally {
+		component.dispose();
+		ctx.ui.setFocus(component);
+		overlay.hide();
+	}
+	if (options.playWelcomeIntro !== false) {
+		ctx.playWelcomeIntro();
+	}
+}