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

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

@@ -14,7 +14,10 @@ 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";
+import { col, node, span, text } from "../../native/describe";
+import type { NativeChild, NativeNode } from "../../native/node";
+import { Memo } from "../../native/memo";
+import type { SetupScene, SetupSceneController, SetupSceneHost, StyledLine } from "./types";
 
 function loginUrlLink(url: string): string {
 	return `\x1b]8;;${url}\x07Open login URL\x1b]8;;\x07`;
@@ -27,10 +30,12 @@ function loginCopyHint(): string {
 class CopyablePromptInput implements Component, Focusable {
 	#input: Input;
 	#onCopy: () => void;
+	readonly #native: NativeNode;
 
 	constructor(input: Input, onCopy: () => void) {
 		this.#input = input;
 		this.#onCopy = onCopy;
+		this.#native = col([input]);
 	}
 
 	get focused(): boolean {
@@ -49,6 +54,11 @@ class CopyablePromptInput implements Component, Focusable {
 		return this.#input.render(width);
 	}
 
+	/** The wrapped field describes itself (`input`, caret while focused); alt+c stays a key here. */
+	describe(): NativeNode {
+		return this.#native;
+	}
+
 	handleInput(data: string): void {
 		if (matchesKey(data, "alt+c")) {
 			this.#onCopy();
@@ -69,17 +79,20 @@ interface PromptState {
 }
 
 /**
- * "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.
+ * "Sign in" scene: lets the user authenticate one or more model providers via
+ * OAuth. 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";
+export class SignInScene implements SetupSceneController {
+	readonly title = "Sign in to your providers";
+	get subtitle(): string {
+		return `Sign in to one or more providers. Press ${editorKey("tui.select.cancel")} when you're done.`;
+	}
 
 	#authStorage: AuthStorage;
 	#selector: OAuthSelectorComponent;
-	#statusLines: string[] = [];
+	/** Status copy under the selector or login flow; replaced (never mutated) on change. */
+	#statusLines: readonly StyledLine[] = [];
 	#authUrl: string | undefined;
 	#authLaunchUrl: string | undefined;
 	#prompt: PromptState | undefined;
@@ -90,6 +103,7 @@ export class SignInTab implements SetupTab {
 	#loggingInProvider: string | undefined;
 	#disposed = false;
 	#step: WizardStep | undefined;
+	#native = new Memo();
 
 	readonly #host: SetupSceneHost;
 
@@ -99,11 +113,6 @@ export class SignInTab implements SetupTab {
 		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();
@@ -112,6 +121,7 @@ export class SignInTab implements SetupTab {
 	}
 
 	invalidate(): void {
+		this.#native.clear();
 		this.#step?.invalidate();
 		this.#selector.invalidate();
 		this.#prompt?.input.invalidate();
@@ -177,7 +187,7 @@ export class SignInTab implements SetupTab {
 			}
 		}
 		for (const line of this.#statusLines) {
-			for (const wrapped of wrapTextWithAnsi(line, width)) {
+			for (const wrapped of wrapTextWithAnsi(theme.fg(line.color, line.text), width)) {
 				tail.addChild(new Text(wrapped, 0, 0));
 			}
 		}
@@ -208,6 +218,98 @@ export class SignInTab implements SetupTab {
 		return this.#step.render(width);
 	}
 
+	/**
+	 * Picking: intro, the provider selector (describes itself) and the last
+	 * outcome. Signing in: a spinner heading, the login link (with the full
+	 * URL once, char-wrapped), any code prompt and the flow's progress lines.
+	 */
+	describe(): NativeNode {
+		const provider = this.#loggingInProvider;
+		const authUrl = this.#authUrl;
+		const launchUrl = this.#authLaunchUrl;
+		const prompt = this.#prompt;
+		const statusLines = this.#statusLines;
+		const copyKey = formatKeyHint("alt+c");
+		return this.#native.get([provider, authUrl, launchUrl, prompt, statusLines, this.#selector, copyKey], () => {
+			const tail: NativeChild[] = [];
+			if (authUrl) {
+				tail.push(
+					node(
+						"text",
+						{
+							spans: [
+								span("Browser login: ", "accent"),
+								span("Open login URL", "accent link", { href: authUrl }),
+								span(` (clipboard copy attempted; ${copyKey} retries)`, "dim"),
+							],
+						},
+						undefined,
+						"login",
+					),
+					node(
+						"text",
+						{ spans: [span(authUrl, "dim link", { href: authUrl })], wrap: "char", actions: { menu: ["copy"] } },
+						undefined,
+						"url",
+					),
+				);
+				if (launchUrl) {
+					tail.push(
+						node(
+							"text",
+							{
+								spans: [
+									span("Local shortcut (this machine only): ", "dim"),
+									span(launchUrl, "dim link", { href: launchUrl }),
+								],
+								wrap: "char",
+							},
+							undefined,
+							"launch",
+						),
+					);
+				}
+			}
+			if (prompt) {
+				const promptChildren: NativeChild[] = [text([span(prompt.message, "warning")])];
+				if (prompt.placeholder) promptChildren.push(text([span(prompt.placeholder, "dim")]));
+				promptChildren.push(prompt.input);
+				tail.push(node("col", {}, promptChildren, "prompt"));
+			}
+			statusLines.forEach((line, index) => {
+				tail.push(node("text", { spans: [span(line.text, line.color)] }, undefined, `status:${index}`));
+			});
+
+			if (provider) {
+				return col(
+					[
+						node(
+							"row",
+							{ gap: "sm", align: "center" },
+							[node("spinner", {}), text([span(`Signing in to ${provider}`, "strong")])],
+							"heading",
+						),
+						...tail,
+					],
+					{ gap: "sm", role: "omp.setup.sign-in", tone: "pending" },
+				);
+			}
+			return col(
+				[
+					node(
+						"text",
+						{ spans: [span("Pick a provider to sign in — you can connect more than one.", "muted")] },
+						undefined,
+						"intro",
+					),
+					this.#selector,
+					...tail,
+				],
+				{ gap: "sm", role: "omp.setup.sign-in" },
+			);
+		});
+	}
+
 	#createSelector(): OAuthSelectorComponent {
 		return new OAuthSelectorComponent(
 			"login",
@@ -225,7 +327,7 @@ export class SignInTab implements SetupTab {
 		const useManualInput = PASTE_CODE_LOGIN_PROVIDERS.has(providerId);
 		this.#selector.stopValidation();
 		this.#loggingInProvider = providerId;
-		this.#statusLines = [theme.fg("dim", "Starting OAuth flow…")];
+		this.#statusLines = [{ text: "Starting OAuth flow…", color: "dim" }];
 		this.#authUrl = undefined;
 		this.#authLaunchUrl = undefined;
 		this.#loginAbort = new AbortController();
@@ -247,20 +349,21 @@ export class SignInTab implements SetupTab {
 					// shortcut for wide-terminal local users.
 					this.#authUrl = info.url;
 					this.#authLaunchUrl = info.launchUrl && info.launchUrl !== info.url ? info.launchUrl : undefined;
-					this.#statusLines = [];
+					const statusLines: StyledLine[] = [];
 					if (info.instructions) {
-						this.#statusLines.push(theme.fg("warning", info.instructions));
+						statusLines.push({ text: info.instructions, color: "warning" });
 					}
 					if (useManualInput) {
-						this.#statusLines.push(theme.fg("dim", "Paste the returned code or redirect URL when prompted."));
+						statusLines.push({ text: "Paste the returned code or redirect URL when prompted.", color: "dim" });
 					}
+					this.#statusLines = statusLines;
 					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.#statusLines = [...this.#statusLines, { text: message, color: "dim" }];
 					this.#host.requestRender();
 				},
 				onManualCodeInput: signal =>
@@ -271,8 +374,8 @@ export class SignInTab implements SetupTab {
 			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()}`),
+				{ text: `${theme.status.success} Signed in to ${providerId}`, color: "success" },
+				{ text: `Credentials saved to ${getAgentDbPath()}`, color: "dim" },
 			];
 			this.#authUrl = undefined;
 			this.#authLaunchUrl = undefined;
@@ -285,14 +388,17 @@ export class SignInTab implements SetupTab {
 		} catch (error) {
 			if (this.#disposed) return;
 			if (this.#loginAbort?.signal.aborted) {
-				this.#statusLines = [theme.fg("dim", "Login cancelled.")];
+				this.#statusLines = [{ text: "Login cancelled.", color: "dim" }];
 				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 ${editorKey("tui.select.cancel")} to continue.`),
+					{ text: `Login failed: ${message}`, color: "error" },
+					{
+						text: `Choose another provider or press ${editorKey("tui.select.cancel")} to continue.`,
+						color: "dim",
+					},
 				];
 				this.#authUrl = undefined;
 				this.#authLaunchUrl = undefined;
@@ -373,3 +479,11 @@ export class SignInTab implements SetupTab {
 		this.#host.requestRender();
 	}
 }
+
+/** Onboarding scene for provider sign-in. */
+export const providersSetupScene: SetupScene = {
+	id: "providers",
+	title: "Sign in to your providers",
+	minVersion: 1,
+	mount: host => new SignInScene(host),
+};

package/src/setup/scenes/splash.ts

@@ -1,8 +1,11 @@
 import { centerLine, visibleWidth } from "../../utils";
 import { padToWidth } from "../../render/utils";
-import { gradientEscape, gradientLogo, PI_LOGO, type ShineConfig } from "../../prompt/welcome";
+import { gradientEscape, gradientLogo, logoNode, PI_LOGO, type ShineConfig } from "../../prompt/welcome";
 import { theme } from "../../theme/theme";
 import { formatKeyHint } from "../../app-keybindings";
+import { col, node, span, text } from "../../native/describe";
+import type { NativeNode } from "../../native/node";
+import { Memo } from "../../native/memo";
 
 export const SETUP_SPLASH_MS = 2600;
 export const SETUP_TICK_MS = 33;
@@ -181,6 +184,30 @@ export function renderSetupSplash(width: number, height: number, elapsedMs: numb
 	return cells.map(row => row.join(""));
 }
 
+const splashMemo = new Memo();
+
+/**
+ * Native splash: the 2x brand mark with a terminal-clocked shimmer, the
+ * wordmark, and the skip hint pinned to the bottom. The water and starfield
+ * are cell paintings with no semantic counterpart. A click on the splash
+ * sends the `skip` action.
+ */
+export function describeSetupSplash(): NativeNode {
+	const hint = skipHint();
+	return splashMemo.get([hint], () =>
+		col(
+			[
+				node("spacer", { grow: 1 }),
+				logoNode(LARGE_LOGO, true),
+				text([span("O h   M y   P i", "strong")], { wrap: "none" }),
+				node("spacer", { grow: 1 }),
+				text([span(hint, "dim")], { wrap: "none" }),
+			],
+			{ align: "center", gap: "md", grow: 1, role: "omp.setup.splash", actions: { click: "skip" } },
+		),
+	);
+}
+
 /** 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;

package/src/setup/scenes/theme.ts

@@ -18,6 +18,9 @@ import {
 	setSymbolPreset,
 	theme,
 } from "../../theme/theme";
+import { col, node, span, text } from "../../native/describe";
+import type { NativeChild, NativeNode } from "../../native/node";
+import { Memo } from "../../native/memo";
 import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
 
 type ThemeMode = "curated" | "all";
@@ -85,6 +88,50 @@ function renderThemePreview(width: number): string[] {
 	];
 }
 
+/**
+ * Native theme preview: status samples, a status bar and a read-only editor
+ * in the highlighted theme's tokens. The terminal draws the bar and editor
+ * chrome, so none of the ANSI mock's box or fill math applies.
+ */
+function describeThemePreview(): NativeNode {
+	return col(
+		[
+			text([span("Preview", "strong")]),
+			text([
+				span(`${theme.status.success} success`, "success"),
+				span("  "),
+				span(`${theme.status.warning} warning`, "warning"),
+				span("  "),
+				span(`${theme.status.error} error`, "error"),
+				span("  "),
+				span("accent", "accent"),
+			]),
+			text([span("Status line", "muted")]),
+			node("status", {}, [
+				node("seg", { spans: [span(`${theme.icon.model} sonnet`, "statusLineModel")], side: "left" }),
+				node("seg", { spans: [span("~/project", "statusLinePath")], side: "left" }),
+				node("seg", { spans: [span(`${theme.icon.git} main +2`, "statusLineGitDirty")], side: "left" }),
+				node("seg", { spans: [span(`${theme.icon.context} 42%`, "statusLineContext")], side: "right" }),
+				node("seg", { spans: [span(`${theme.icon.cost} 0.18`, "statusLineCost")], side: "right" }),
+			]),
+			text([span("Editor", "muted")]),
+			node("input", {
+				text: "Ask anything, edit files, run tools",
+				cursor: "Ask anything, edit files, run tools".length,
+				prompt: [span(">", "accent")],
+				readonly: true,
+			}),
+			text([
+				span(
+					`${editorKey("tui.input.submit")} send · ${editorKey("tui.input.newLine")} newline · / commands`,
+					"dim",
+				),
+			]),
+		],
+		{ role: "omp.setup.theme.preview" },
+	);
+}
+
 class ThemeSceneController implements SetupSceneController {
 	title = "Pick a theme";
 	get subtitle(): string {
@@ -93,10 +140,12 @@ class ThemeSceneController implements SetupSceneController {
 	#mode: ThemeMode = "curated";
 	#selectList: SelectList;
 	#loadingAllThemes = false;
+	/** Error copy shown under the list (raw text; styled at render/describe time). */
 	#message: string | undefined;
 	#previewRequest = 0;
 	#disposed = false;
 	#step: WizardStep | undefined;
+	#native = new Memo();
 	readonly #originalTheme = getCurrentThemeName();
 	readonly #originalSymbolPreset: SymbolPreset;
 	readonly #originalColorBlindMode: boolean;
@@ -115,6 +164,7 @@ class ThemeSceneController implements SetupSceneController {
 	}
 
 	invalidate(): void {
+		this.#native.clear();
 		this.#step?.invalidate();
 		this.#selectList.invalidate();
 	}
@@ -168,7 +218,7 @@ class ThemeSceneController implements SetupSceneController {
 			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;
+		const status = this.#message ? new Text(theme.fg("error", this.#message), 0, 0) : undefined;
 		if (!this.#step) {
 			this.#step = new WizardStep({
 				kind: loading ? "async" : "choice",
@@ -194,6 +244,41 @@ class ThemeSceneController implements SetupSceneController {
 		return this.#step.render(width);
 	}
 
+	/**
+	 * Intro hints, the live preview, the theme list (a spinner while every
+	 * theme loads) and any preview error. Theme switches re-describe through
+	 * `invalidate()`, so the preview's tokens follow the highlighted theme.
+	 */
+	describe(): NativeNode {
+		const confirm = editorKey("tui.select.confirm");
+		const cancel = editorKey("tui.select.cancel");
+		return this.#native.get(
+			[this.#mode, this.#loadingAllThemes, this.#selectList, this.#message, confirm, cancel],
+			() => {
+				const children: NativeChild[] = [
+					col([
+						text([span(`Theme changes preview live. Nothing is saved until you press ${confirm}.`, "muted")]),
+						text([
+							span(
+								this.#mode === "all"
+									? `Browsing all themes · ${cancel} returns to curated choices`
+									: `${cancel} skips this step`,
+								"dim",
+							),
+						]),
+					]),
+					describeThemePreview(),
+					this.#loadingAllThemes
+						? node("spinner", { label: [span("Loading themes…", "dim")] }, undefined, "loading")
+						: this.#selectList,
+				];
+				if (this.#message)
+					children.push(node("text", { spans: [span(this.#message, "error")] }, undefined, "status"));
+				return col(children, { gap: "sm", role: "omp.setup.theme" });
+			},
+		);
+	}
+
 	#createSelectList(items: readonly SelectItem[], selectedIndex: number): SelectList {
 		const list = new SelectList(items, Math.min(10, Math.max(1, items.length)), getSelectListTheme());
 		list.setSelectedIndex(selectedIndex);
@@ -256,7 +341,7 @@ class ThemeSceneController implements SetupSceneController {
 			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}`);
+			this.#message = `Failed to load themes: ${message}`;
 		} finally {
 			this.#loadingAllThemes = false;
 			this.#host.requestRender();
@@ -320,7 +405,7 @@ class ThemeSceneController implements SetupSceneController {
 		}
 		if (request !== this.#previewRequest || this.#disposed) return;
 		if (!result.success) {
-			this.#message = theme.fg("error", result.error ?? "Theme preview failed");
+			this.#message = result.error ?? "Theme preview failed";
 		}
 		this.#host.ctx.ui.invalidate();
 		this.#host.requestRender();

package/src/setup/scenes/types.ts

@@ -4,10 +4,15 @@ 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 { SymbolPreset, ThemeColor } from "../../theme/theme";
 import type { Component, TUI } from "../../tui";
 
+/** One line of status copy kept as raw text plus its theme colour, never as pre-styled ANSI. */
+export interface StyledLine {
+	readonly text: string;
+	readonly color: ThemeColor;
+}
+
 /** Terminal capabilities used by setup overlays and the startup splash. */
 export interface SetupUiHost {
 	readonly ui: Pick<TUI, "showOverlay" | "setFocus" | "requestRender" | "invalidate"> & {
@@ -21,7 +26,6 @@ export interface SetupHost extends SetupUiHost {
 	readonly composerShape: ComposerShape;
 	readonly symbolPreset: SymbolPreset;
 	readonly colorBlindMode: boolean;
-	readonly webSearchOrder: readonly string[];
 	readonly disabledProviders: readonly string[];
 	readonly authStorage: AuthStorage;
 	readonly modelSource: ModelBrowserSource;
@@ -33,8 +37,6 @@ export interface SetupHost extends SetupUiHost {
 	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;
@@ -78,29 +80,6 @@ export interface SetupSceneController extends Component {
 	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;

package/src/setup/startup-splash.ts

@@ -1,7 +1,11 @@
 import { type Component, type OverlayFocusOwner } from "../tui";
 import { matchesKey } from "../keys";
+import { col } from "../native/describe";
+import type { NativeNode, NativeUiEvent } from "../native/node";
+import { Memo } from "../native/memo";
+import { isNativeRendering } from "../native/state";
 import type { SetupUiHost } from "./scenes/types";
-import { renderSetupSplash, SETUP_SPLASH_MS, SETUP_TICK_MS } from "./scenes/splash";
+import { describeSetupSplash, renderSetupSplash, SETUP_SPLASH_MS, SETUP_TICK_MS } from "./scenes/splash";
 
 /** Timing controls for the standalone startup animation. */
 export interface RunStartupSplashOptions {
@@ -13,6 +17,9 @@ export interface RunStartupSplashOptions {
 class StartupSplashComponent implements Component, OverlayFocusOwner {
 	#phaseStartedAt = 0;
 	#timer: NodeJS.Timeout | undefined;
+	/** Native path: one-shot at the end of the splash; the terminal clocks the motion. */
+	#deadline: NodeJS.Timeout | undefined;
+	#native = new Memo();
 	#done = Promise.withResolvers<void>();
 	#disposed = false;
 	readonly #durationMs: number;
@@ -60,20 +67,50 @@ class StartupSplashComponent implements Component, OverlayFocusOwner {
 		return renderSetupSplash(Math.max(1, width), Math.max(1, this.ctx.ui.terminal.rows), elapsedMs);
 	}
 
+	describe(): NativeNode {
+		const splash = describeSetupSplash();
+		return this.#native.get([splash], () => col([splash], { grow: 1, role: "omp.app.startup-splash" }));
+	}
+
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action" && event.act === "skip") this.#complete();
+	}
+
+	/**
+	 * ANSI: repaint every tick. Native: no repaint loop, only a one-shot at
+	 * the end of the splash (re-armed if it fires early).
+	 */
 	#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;
+		if (isNativeRendering()) {
+			if (this.#timer) {
+				clearInterval(this.#timer);
+				this.#timer = undefined;
 			}
+			clearTimeout(this.#deadline);
+			const remaining = this.#durationMs - (this.#now() - this.#phaseStartedAt);
+			this.#deadline = setTimeout(() => this.#tick(), Math.max(0, remaining));
+			return;
+		}
+		if (this.#timer) return;
+		this.#timer = setInterval(() => this.#tick(), this.#tickMs);
+	}
+
+	#tick(): void {
+		if (this.#disposed) return;
+		const elapsed = this.#now() - this.#phaseStartedAt;
+		if (elapsed >= this.#durationMs) {
+			this.#complete();
+		} else if (isNativeRendering() || !this.#timer) {
+			// Re-arm the deadline, or switch loops when the native surface opened/closed.
+			this.#startTimer();
+		} else {
 			this.ctx.ui.requestRender();
-		}, this.#tickMs);
+		}
 	}
 
 	#stopTimer(): void {
+		clearTimeout(this.#deadline);
+		this.#deadline = undefined;
 		if (!this.#timer) return;
 		clearInterval(this.#timer);
 		this.#timer = undefined;