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

package/src/tui.ts

@@ -18,11 +18,16 @@ import { getDebugLogPath } from "@oh-my-pi/pi-utils/dirs";
 import { $flag } from "@oh-my-pi/pi-utils/env";
 import * as logger from "@oh-my-pi/pi-utils/logger";
 import * as postmortem from "@oh-my-pi/pi-utils/postmortem";
+import type { TspFrame, TspNode, TspText } from "@oh-my-pi/pi-wire";
 import { DEFAULT_MAX_INLINE_IMAGES, ImageBudget } from "./components/image";
 import { TuiDebugServer } from "./debug-server";
 import { isKeyRelease, matchesKey } from "./keys";
 import { KITTY_PLACEHOLDER } from "./kitty-graphics";
 import { LoopWatchdog } from "./loop-watchdog";
+import { assumedTspHello, NativeBackend, type NativeHost } from "./native/backend";
+import { col } from "./native/describe";
+import { TSP_PREFIX, type TspHello } from "./native/encode";
+import type { DescribeContext, NativeNode, NativeSurfaceProvider, NativeUiEvent } from "./native/node";
 import { STDOUT_BACKLOG_CLEAR_BYTES, setAltScreenActive, type Terminal } from "./terminal";
 import {
 	encodeKittyDeleteAllImages,
@@ -239,6 +244,39 @@ export interface Component {
 	 */
 	render(width: number): readonly string[];
 
+	/**
+	 * Describe the component semantically for a Tern Surface Protocol
+	 * terminal (see `native/node.ts`). Called instead of `render()` when the
+	 * native backend is active. Return the same node object while nothing
+	 * changed; return null to fall back to `render()` rows.
+	 */
+	describe?(cx: DescribeContext): NativeNode | null;
+
+	/**
+	 * Props for the native `overlay` wrapper when this component is shown as
+	 * an overlay: the sheet's `role` (Tern styles `omp.overlay.*` roles as
+	 * glass sheets, so the component's own root must not draw a second frame),
+	 * `head` spans for the sheet's title row, and `size`/`anchor` overriding
+	 * the ones derived from the overlay options.
+	 */
+	nativeOverlay?: {
+		role?: string;
+		head?: TspText;
+		size?: "sm" | "md" | "lg" | "full";
+		anchor?: "center" | "top" | "bottom";
+	};
+
+	/**
+	 * True when this component, shown as an overlay, describes a data-first
+	 * sheet (`picker`, `prefs`) that is its own frame: the backend puts it
+	 * directly in `layer` with no `overlay` wrapper. Usually
+	 * `cx.supports("picker")`, so older terminals keep the wrapped fallback.
+	 */
+	nativeSheet?(cx: DescribeContext): boolean;
+
+	/** User actions on nodes this component described (toggle, select, activate, custom). */
+	handleNativeEvent?(event: NativeUiEvent): void;
+
 	/**
 	 * Optional handler for keyboard input when component has focus
 	 */
@@ -450,6 +488,10 @@ export class Container implements Component {
 	#memoLines: string[] | undefined;
 	#memoChildLines: (readonly string[])[] = [];
 	#memoWidth = -1;
+	// Memoized native description: rebuilt only when the child list changes, so
+	// the reconciler can skip an unchanged container by reference.
+	#nativeNode: NativeNode | undefined;
+	#nativeChildren: readonly Component[] = [];
 
 	#ignoreTight = false;
 
@@ -535,6 +577,17 @@ export class Container implements Component {
 		this.#memoLines = lines;
 		return lines;
 	}
+
+	describe(_cx: DescribeContext): NativeNode | null {
+		const children = this.children;
+		const previous = this.#nativeChildren;
+		let unchanged = this.#nativeNode !== undefined && previous.length === children.length;
+		for (let i = 0; unchanged && i < children.length; i++) unchanged = previous[i] === children[i];
+		if (unchanged) return this.#nativeNode!;
+		this.#nativeChildren = children.slice();
+		this.#nativeNode = col(this.#nativeChildren);
+		return this.#nativeNode;
+	}
 }
 
 interface HardwareCursorState {
@@ -915,6 +968,26 @@ export class TUI extends Container {
 	// atomically. It must survive a deferred Ghostty image frame.
 	#pendingAltExit = "";
 
+	// Tern Surface Protocol backend, created when the terminal answers the
+	// `hello` probe, or at start when the environment names Tern. Kept across
+	// stop/start so a restart adopts the surface.
+	#native: NativeBackend | undefined;
+	#nativeLive = false;
+	// Holds the first paint while the `hello` probe is outstanding, so a TSP
+	// terminal never sees a row paint it would have to erase.
+	#nativeHoldTimer: RenderTimer | undefined;
+	static readonly #NATIVE_PROBE_HOLD_MS = 300;
+	// Optimistic start (`TERM_PROGRAM=tern`): the surface is live on assumed
+	// capabilities until the real `hello` reply confirms it. Without a reply
+	// by the deadline the surface closes and rows repaint.
+	#nativeUnconfirmed = false;
+	#nativeConfirmTimer: RenderTimer | undefined;
+	static readonly #NATIVE_CONFIRM_MS = 1000;
+	// A deadline that fires this late ran after an event-loop stall (module
+	// loading), possibly with the reply already queued on stdin: re-arm for
+	// this long so input gets a turn before giving up.
+	static readonly #NATIVE_CONFIRM_GRACE_MS = 100;
+
 	// Overlay stack for modal components rendered on top of base content
 	overlayStack: {
 		component: Component;
@@ -1246,7 +1319,12 @@ export class TUI extends Container {
 			this.#debugServer = new TuiDebugServer(this, debugPath);
 			this.#debugServer.start();
 		}
-		this.#inputDeferred = options?.deferInput === true;
+		// A terminal expected to speak TSP gets its surface from the first frame,
+		// and a live surface needs raw input from the start: its events (resize,
+		// acks) would otherwise be echoed into the grid by the cooked tty, and the
+		// `hello` query must go out now to confirm the surface.
+		const nativeExpected = this.terminal.tspExpected === true;
+		this.#inputDeferred = options?.deferInput === true && !nativeExpected;
 		this.#watchdog.start();
 		this.#ghosttyInitialImageDelayDone = false;
 		this.#ghosttyImageReadyAtMs = this.#renderScheduler.now() + TUI.#GHOSTTY_INITIAL_IMAGE_DELAY_MS;
@@ -1275,9 +1353,16 @@ export class TUI extends Container {
 			this.invalidate();
 			this.requestRender(true);
 		});
+		this.terminal.onTspHello?.(hello => this.#onTspHello(hello));
 		this.terminal.start(
 			data => this.#handleInput(data),
 			() => {
+				if (this.#nativeLive) {
+					// The terminal lays the surface out: a resize only refreshes the
+					// width `rows` fallback nodes render at. No replay.
+					this.#native!.noteTerminalColumns(this.terminal.columns);
+					return;
+				}
 				if (this.#resizeProbe) {
 					// Warp echoes a height-only ±1 SIGWINCH on CSI ?1049l. The echo
 					// must not restart the alt borrow (that is the flicker loop),
@@ -1328,7 +1413,7 @@ export class TUI extends Container {
 				this.#beginResizeAltPaint();
 			},
 			() => this.stop(),
-			{ deferInput: this.#inputDeferred },
+			{ deferInput: this.#inputDeferred, isLoopStalled: () => this.#watchdog.isStalled() },
 		);
 		if (this.#stopped) return;
 		this.#cancelPostmortemRestore?.();
@@ -1346,8 +1431,191 @@ export class TUI extends Container {
 			this.#querySixelSupport();
 			this.#queryCellSize();
 		}
+		if (nativeExpected && this.terminal.tspProbePending && !this.#nativeLive) {
+			this.#startNative(assumedTspHello(this.terminal));
+			this.#nativeUnconfirmed = true;
+			this.#armNativeConfirm(TUI.#NATIVE_CONFIRM_MS);
+		} else if (this.terminal.tspProbePending && !this.#nativeLive) {
+			this.#nativeHoldTimer = this.#renderScheduler.scheduleRender(() => {
+				this.#nativeHoldTimer = undefined;
+				if (!this.#stopped && !this.#nativeLive) this.requestRender(true);
+			}, TUI.#NATIVE_PROBE_HOLD_MS);
+		}
 		this.requestRender(true, { clearScrollback: options?.clearScrollback === true });
 	}
+
+	/** Whether frames go to a Tern Surface Protocol surface instead of the row renderer. */
+	get nativeRendering(): boolean {
+		return this.#nativeLive;
+	}
+
+	/**
+	 * Close the TSP surfaces ahead of {@link stop}, before the exit drains
+	 * input: the terminal answers nothing once they are closed, and whatever it
+	 * already sent (acks, events) is read and dropped here instead of reaching
+	 * the shell as typed text. A render already requested (the exit's status
+	 * line) goes out first; none is forced, and nothing renders from now until
+	 * `stop()`.
+	 */
+	closeNative(): void {
+		if (!this.#nativeLive) return;
+		if (this.#renderRequested) {
+			this.#renderTimer?.cancel();
+			this.#runScheduledRender();
+		}
+		this.#native!.stop();
+	}
+
+	/** Reference document the TSP terminal should hold (debug mirror only). */
+	getNativeDocument(): TspNode | undefined {
+		return this.#nativeLive ? this.#native?.document() : undefined;
+	}
+
+	/** Most recent TSP frames sent (debug mirror only). */
+	getNativeFrames(count?: number): readonly TspFrame[] {
+		return this.#native?.recentFrames(count) ?? [];
+	}
+
+	/** `rows` fallback nodes in the last native frame. */
+	get nativeFallbackCount(): number {
+		return this.#native?.fallbackCount ?? 0;
+	}
+
+	#onTspHello(hello: TspHello | null): void {
+		const held = this.#nativeHoldTimer !== undefined;
+		this.#nativeHoldTimer?.cancel();
+		this.#nativeHoldTimer = undefined;
+		if (this.#stopped) return;
+		if (this.#nativeUnconfirmed) {
+			if (hello === null) {
+				this.#revokeNative("the DA1 sentinel came before a TSP hello reply, or the reply's version is unsupported");
+				return;
+			}
+			this.#clearNativeConfirm();
+			this.#native!.confirm(hello);
+			return;
+		}
+		if (this.#nativeLive) return;
+		if (hello === null) {
+			if (held) this.requestRender(true);
+			return;
+		}
+		this.#startNative(hello);
+	}
+
+	/** Switch to the surface (adopting the one a stop/start cycle closed). */
+	#startNative(hello: TspHello): void {
+		this.#eraseRowPaintForNative();
+		this.#nativeLive = true;
+		if (this.#native) {
+			this.#native.resume(hello);
+			return;
+		}
+		this.#native = new NativeBackend(this.#nativeHost(), hello, { mirror: this.#debugServer !== undefined });
+		this.#native.start();
+	}
+
+	/**
+	 * Deadline for the `hello` reply after an optimistic start. A deadline that
+	 * fired late ran after an event-loop stall, possibly with the reply already
+	 * queued on stdin, so it re-arms briefly to let input run first.
+	 */
+	#armNativeConfirm(delayMs: number): void {
+		const due = this.#renderScheduler.now() + delayMs;
+		this.#nativeConfirmTimer = this.#renderScheduler.scheduleRender(() => {
+			this.#nativeConfirmTimer = undefined;
+			if (!this.#nativeUnconfirmed || this.#stopped) return;
+			if (this.#renderScheduler.now() - due > TUI.#NATIVE_CONFIRM_GRACE_MS) {
+				this.#armNativeConfirm(TUI.#NATIVE_CONFIRM_GRACE_MS);
+				return;
+			}
+			this.#revokeNative(`no TSP hello reply within ${TUI.#NATIVE_CONFIRM_MS} ms`);
+		}, delayMs);
+	}
+
+	#clearNativeConfirm(): void {
+		this.#nativeUnconfirmed = false;
+		this.#nativeConfirmTimer?.cancel();
+		this.#nativeConfirmTimer = undefined;
+	}
+
+	/**
+	 * The optimistic surface was never confirmed: close it without keeping
+	 * anything and repaint every row. A reply that still arrives later switches
+	 * to a fresh surface the usual way.
+	 */
+	#revokeNative(reason: string): void {
+		this.#clearNativeConfirm();
+		logger.warn("TSP: terminal did not confirm the surface; falling back to rows", { reason });
+		this.#nativeLive = false;
+		this.#native?.stop(false);
+		this.#native = undefined;
+		this.requestRender(true);
+	}
+
+	/**
+	 * The handshake landed after the row renderer painted (deferred input):
+	 * leave the alternate screen if borrowed and erase the painted viewport so
+	 * the surface opens where the rows began.
+	 */
+	#eraseRowPaintForNative(): void {
+		this.#cancelResizeProbe();
+		this.#resizeSettleTimer?.cancel();
+		this.#resizeSettleTimer = undefined;
+		if (this.#altActive || this.#resizeAltActive) {
+			this.terminal.write(`${this.#keyboardEnhancementExit()}\x1b[?1049l`);
+			setAltScreenActive(false);
+			this.#altActive = false;
+			this.#resizeAltActive = false;
+		}
+		this.#setMouseTracking("off");
+		if (this.#previousFrameLength > 0) {
+			const lineDiff = this.#providerViewportTop - this.#hardwareCursorRow;
+			if (lineDiff > 0) this.terminal.write(`\x1b[${lineDiff}B`);
+			else if (lineDiff < 0) this.terminal.write(`\x1b[${-lineDiff}A`);
+			this.terminal.write("\r\x1b[J");
+			this.#previousFrameLength = 0;
+			this.#providerWindow = [];
+			this.#providerPreparedRows = [];
+		}
+		this.terminal.hideCursor();
+		this.#forgetHardwareCursorState();
+	}
+
+	#nativeHost(): NativeHost {
+		return {
+			terminal: this.terminal,
+			describeSurface: cx => {
+				const provider = this.#frameProvider as
+					| (TerminalFrameProvider & Partial<NativeSurfaceProvider>)
+					| undefined;
+				if (provider?.describeSurface) return provider.describeSurface(cx);
+				return { main: this.children, dock: [] };
+			},
+			overlays: () => {
+				const visible = [];
+				for (const entry of this.overlayStack) {
+					if (!this.#isOverlayVisible(entry)) continue;
+					visible.push({
+						component: entry.component,
+						options: entry.options,
+						focused: isOverlayFocusTarget(entry.component, this.#focusedComponent),
+					});
+				}
+				return visible;
+			},
+			focused: () => this.#focusedComponent,
+			requestRender: () => this.requestRender(),
+			appearanceChanged: () => {
+				this.terminal.refreshAppearance?.();
+			},
+			motionChanged: () => {
+				this.invalidate();
+				this.requestRender();
+			},
+			invalidate: () => this.invalidate(),
+		};
+	}
 	/**
 	 * Whether a resize repaints the visible window in place — no alternate-screen
 	 * borrow. Warp-only: Warp re-reports its size on alt-buffer toggles, so borrowing
@@ -1974,6 +2242,14 @@ export class TUI extends Container {
 		this.#cancelPostmortemRestore = undefined;
 		this.#debugServer?.stop();
 		this.#debugServer = undefined;
+		this.#nativeHoldTimer?.cancel();
+		this.#nativeHoldTimer = undefined;
+		this.#clearNativeConfirm();
+		const nativeWasLive = this.#nativeLive;
+		if (nativeWasLive) {
+			this.#native!.stop();
+			this.#nativeLive = false;
+		}
 		this.#resizeSettleTimer?.cancel();
 		this.#resizeSettleTimer = undefined;
 		if (this.#resizeInPlaceActive && this.terminal.rows > 0) {
@@ -2021,7 +2297,8 @@ export class TUI extends Container {
 		// erase native history and re-stream the whole transcript at quit; drop
 		// the latch so the flush below writes only un-retired rows.
 		this.#clearScrollbackOnNextRender = false;
-		this.#flushHistoryBeforeStop();
+		// The surface already holds the transcript; there's no row history to retire.
+		if (!nativeWasLive) this.#flushHistoryBeforeStop();
 		// Deliberately leave transmitted images in the terminal's graphics store:
 		// placeholder cells committed to native scrollback render only while their
 		// image data lives, so a delete-by-id here blanks every transcript image
@@ -2193,7 +2470,9 @@ export class TUI extends Container {
 		const adaptiveFloor = Math.min(TUI.#MAX_ADAPTIVE_RENDER_MS, this.#lastFrameCostMs * 2);
 		const adaptiveDelay = Math.max(0, adaptiveFloor - elapsed);
 		const inputGraceDelay = Math.max(0, this.#inputRenderGraceUntilMs - now);
-		const delay = Math.max(cadenceDelay, adaptiveDelay, inputGraceDelay);
+		// Native frames are paced by the terminal's acknowledgements (credits),
+		// not by the row renderer's cadence.
+		const delay = this.#nativeLive ? 0 : Math.max(cadenceDelay, adaptiveDelay, inputGraceDelay);
 		this.#renderTimer = this.#renderScheduler.scheduleRender(this.#runScheduledRender, delay);
 	}
 
@@ -2227,6 +2506,12 @@ export class TUI extends Container {
 	}
 
 	#handleInput(data: string): void {
+		// Tern Surface Protocol events (acks, pointer actions, resize, theme)
+		// are terminal reports, never keystrokes.
+		if (data.startsWith(TSP_PREFIX)) {
+			if (this.#nativeLive) this.#native!.handleInput(data);
+			return;
+		}
 		// Consume CPR replies (CSI row;col R) while an anchor probe is unanswered;
 		// they are terminal reports, never keystrokes, and must not reach the
 		// focused component.
@@ -2982,6 +3267,12 @@ export class TUI extends Container {
 	/** Render one frame: alt-screen modal, provider plan, or children fallback. */
 	#doRender(): void {
 		if (this.#stopped) return;
+		if (this.#nativeLive) {
+			this.#native!.render();
+			return;
+		}
+		// Awaiting the TSP hello: its resolution (or the hold timeout) repaints.
+		if (this.#nativeHoldTimer) return;
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
 		if (this.#resizeAltActive) {

package/dist/types/setup/scenes/providers.d.ts

@@ -1,3 +0,0 @@
-import type { SetupScene } from "./types.js";
-/** Configure provider sign-in and the preferred web search backend. */
-export declare const providersSetupScene: SetupScene;

package/dist/types/setup/scenes/web-search.d.ts

@@ -1,22 +0,0 @@
-import { type SgrMouseEvent } from "../../mouse.js";
-import type { SetupSceneHost, SetupTab } from "./types.js";
-/**
- * "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 declare class WebSearchTab implements SetupTab {
-    #private;
-    readonly id = "web-search";
-    readonly label = "Web search";
-    readonly modal = false;
-    constructor(host: SetupSceneHost);
-    onActivate(): void;
-    handleInput(data: string): void;
-    /** Wheel moves the highlight; hover lights the row under the pointer; click confirms it. */
-    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
-    invalidate(): void;
-    dispose(): void;
-    render(width: number, maxLines?: number): readonly string[];
-}

package/src/setup/scenes/providers.ts

@@ -1,110 +0,0 @@
-import { type SgrMouseEvent } from "../../mouse";
-import { TabBar } from "../../components/tab-bar";
-import { editorKey } from "../../chrome/keybinding-hints";
-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";
-	get subtitle(): string {
-		return `Sign in and pick a web search provider. Press ${editorKey("tui.select.cancel")} 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),
-};