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

package/src/tools/write.ts

@@ -22,23 +22,47 @@ import {
 	truncateToWidth,
 } from "../render/render-utils";
 import type { CoordinationDetails } from "./wait";
-import { renderAgentWrite, renderProcWrite, type ProcWriteAction, type ProcWriteDetails } from "./proc-render";
-import { renderCfgWrite, type CfgWriteDetails } from "./cfg-render";
+import {
+	describeAgentWrite,
+	describeProcWrite,
+	renderAgentWrite,
+	renderProcWrite,
+	type ProcWriteAction,
+	type ProcWriteDetails,
+} from "./proc-render";
+import type { TspTone } from "@oh-my-pi/pi-wire";
+import { code, compact, node, span } from "../native/describe";
+import type { NativeChild } from "../native/node";
+import { diagnosticsBadge, diagnosticsSection, displayPath, errorText, fileHref, resultText } from "./native-view";
+import { describeCfgWrite, renderCfgWrite, type CfgWriteDetails } from "./cfg-render";
 import type { FileDiagnosticsResult } from "./lsp";
 import type { OutputMeta } from "./output-meta";
 import type { CardToolResult } from "./result-card";
-import type { RenderResultOptions, ToolActivityContext, ToolActivitySummary, ToolRenderer } from "./renderer";
+import type {
+	NativeToolHead,
+	NativeToolView,
+	RenderResultOptions,
+	ToolActivityContext,
+	ToolActivitySummary,
+	ToolRenderer,
+} from "./renderer";
 import { splitUrlScheme } from "./url-scheme-host";
 import { couldBecomeXdUrl, parseXdUrl } from "./xd-url";
 import {
+	describeXdevCall,
+	describeXdevResult,
 	renderXdevCall,
 	renderXdevResult,
 	xdevActivitySummary,
 	type XdevRenderDispatch,
 	type XdevMountedRenderer,
 } from "./xdev";
-import { isResolutionDeviceName, renderResolutionDeviceCall } from "./resolve";
-import { REPORT_ISSUE_DEVICE_NAME, renderReportIssueDeviceCall } from "./report-tool-issue";
+import { describeResolutionDeviceCall, isResolutionDeviceName, renderResolutionDeviceCall } from "./resolve";
+import {
+	describeReportIssueDeviceCall,
+	REPORT_ISSUE_DEVICE_NAME,
+	renderReportIssueDeviceCall,
+} from "./report-tool-issue";
 import { pendingFileLinkPath } from "./read";
 
 /** Details returned by the write tool for transcript rendering. */
@@ -64,6 +88,8 @@ interface WriteRenderArgs {
 }
 
 const WRITE_PREVIEW_LINES = 6;
+/** Collapsed native write body: the first lines of the file (§7.3). */
+const NATIVE_WRITE_PREVIEW = { lines: 8 } as const;
 
 function countLines(text: string): number {
 	if (!text) return 0;
@@ -416,6 +442,48 @@ function couldBecomeWriteCardUrl(lowerPath: string): boolean {
 	return false;
 }
 
+/** Native view of a `proc://`, `agent://` or `cfg://` write. */
+function describeWriteUrl(
+	routed: { card: WriteUrlCard; target: string },
+	url: string,
+	content: unknown,
+	result: CardToolResult | undefined,
+	details: WriteToolDetails | undefined,
+): NativeToolView {
+	const body = typeof content === "string" ? content : undefined;
+	switch (routed.card.detailsKey) {
+		case "message":
+			return describeAgentWrite(routed.target, body ?? "", result, details?.message);
+		case "proc": {
+			const { id, action } = procWriteTarget(routed.target);
+			return describeProcWrite(id, action, body, result, details?.proc);
+		}
+		case "cfg":
+			return describeCfgWrite(url, body, result, details?.cfg);
+	}
+}
+
+/** Native write head shared by the call and result: `Write · path · 22 lines`, executable/diagnostics chips. */
+function writeToolHead(
+	rawPath: string,
+	content: string,
+	details?: Pick<WriteToolDetails, "madeExecutable" | "resolvedPath" | "diagnostics">,
+): NativeToolHead {
+	const lineCount = countLines(content);
+	const badges: { text: string; tone?: TspTone }[] = [];
+	if (details?.madeExecutable) badges.push({ text: "executable", tone: "success" });
+	const diagnostics = diagnosticsBadge([details?.diagnostics]);
+	if (diagnostics) badges.push(diagnostics);
+	return {
+		title: "Write",
+		target: rawPath ? displayPath(rawPath) : undefined,
+		targetKind: "path",
+		href: fileHref(details?.resolvedPath),
+		meta: lineCount > 0 ? [`${lineCount} line${lineCount === 1 ? "" : "s"}`] : undefined,
+		badges: badges.length > 0 ? badges : undefined,
+	};
+}
+
 /** Render file writes and delegated tool-device calls. */
 export const writeToolRenderer = {
 	/** Compact one-line activity: device writes read as the mounted tool (`LSP · references foo`), file writes as `Write · <path>`. */
@@ -618,6 +686,77 @@ export const writeToolRenderer = {
 			};
 		});
 	},
+	describeCall(
+		args: WriteRenderArgs,
+		options: RenderResultOptions & { renderContext?: WriteRenderContext },
+	): NativeToolView | undefined {
+		const rawPath =
+			typeof args.file_path === "string" ? args.file_path : typeof args.path === "string" ? args.path : "";
+		// Same gating as renderCall: nothing until the path provably is not a device/card URL.
+		if (args.path === undefined && args.file_path === undefined) return undefined;
+		const pathSettled = args.content !== undefined || options.argsComplete === true;
+		const hasStringPath = typeof args.file_path === "string" || typeof args.path === "string";
+		if (hasStringPath && !pathSettled && couldBecomeWriteCardUrl(rawPath.toLowerCase())) return undefined;
+		const routed = writeUrlCard(rawPath);
+		if (routed) return describeWriteUrl(routed, rawPath, args.content, undefined, undefined);
+		if (rawPath && couldBecomeXdUrl(rawPath)) {
+			const xdev = parseXdUrl(rawPath);
+			if (!xdev?.name || args.content === undefined) return undefined;
+			if (isResolutionDeviceName(xdev.name)) return describeResolutionDeviceCall(xdev.name, args.content);
+			if (xdev.name === REPORT_ISSUE_DEVICE_NAME) return describeReportIssueDeviceCall(args.content);
+			return describeXdevCall(xdev.name, args.content, options, options.renderContext?.resolveXdevMounted);
+		}
+		const content = normalizeDisplayText(args.content);
+		return {
+			tool: writeToolHead(rawPath, content),
+			body: content
+				? [
+						code(content, {
+							lang: rawPath ? getLanguageFromPath(rawPath) : undefined,
+							numbers: true,
+						}),
+					]
+				: [],
+			preview: NATIVE_WRITE_PREVIEW,
+		};
+	},
+
+	describeResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: WriteToolDetails; isError?: boolean },
+		options: RenderResultOptions & { renderContext?: WriteRenderContext },
+		args?: WriteRenderArgs,
+	): NativeToolView | undefined {
+		const cardPath =
+			typeof args?.path === "string" ? args.path : typeof args?.file_path === "string" ? args.file_path : "";
+		const routed = writeUrlCard(cardPath, result.details);
+		if (routed) return describeWriteUrl(routed, cardPath, args?.content, result, result.details);
+		const xdev = result.details?.xdev;
+		if (xdev) return describeXdevResult(xdev, result, options, options.renderContext?.resolveXdevMounted);
+		const rawPath =
+			typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
+		const fileContent = normalizeDisplayText(args?.content);
+		const isPartial = options.isPartial === true;
+		const diagnostics = isPartial ? undefined : result.details?.diagnostics;
+		const tool = writeToolHead(rawPath, fileContent, {
+			madeExecutable: !isPartial && result.details?.madeExecutable === true,
+			resolvedPath: result.details?.resolvedPath,
+			diagnostics,
+		});
+		if (result.isError) return { tool, tone: "error", body: [errorText(resultText(result))] };
+		const progressText = resultText(result);
+		const body = compact<NativeChild>([
+			isPartial &&
+				progressText.length > 0 &&
+				node("text", { spans: [span(progressText, "muted")], truncate: "end" }),
+			fileContent.length > 0 &&
+				code(fileContent, {
+					lang: rawPath ? getLanguageFromPath(rawPath) : undefined,
+					numbers: true,
+				}),
+			diagnosticsSection(diagnostics),
+		]);
+		return { tool, body, preview: NATIVE_WRITE_PREVIEW };
+	},
 	mergeCallAndResult: true,
 	// The collapsed pending preview follows the streaming edge with a tail
 	// window once the content outgrows it (`… (N earlier lines)` + last rows);

package/src/tools/xdev.ts

@@ -4,12 +4,16 @@ import { type Component, Container, Text } from "../index";
 import type { Theme } from "../theme/theme";
 import { replaceTabs } from "../render/render-utils";
 import type { RenderResultOptions, ToolActivitySummary, ToolRenderer } from "./renderer";
-import { renderDefaultToolExecution } from "./default-renderer";
+import { describeDefaultToolExecution, renderDefaultToolExecution } from "./default-renderer";
+import type { NativeToolView } from "./renderer";
+import { text } from "../native/describe";
 import { parseMCPToolName } from "./mcp";
 
 /** Mounted device display callbacks, independent of tool execution state. */
 export interface XdevMountedRenderer {
 	label?: string;
+	describeCall?: ToolRenderer["describeCall"];
+	describeResult?: ToolRenderer["describeResult"];
 	renderCall?(...args: Parameters<ToolRenderer["renderCall"]>): unknown;
 	renderResult?(...args: Parameters<ToolRenderer["renderResult"]>): unknown;
 	mergeCallAndResult?: boolean;
@@ -162,6 +166,65 @@ export function renderXdevCall(
 	return renderDefaultToolExecution({ label: mounted?.label ?? name, args, options }, theme);
 }
 
+/** Native form of {@link resolveDeviceRenderer}: the first renderer that can describe. */
+function resolveDeviceDescriber(
+	name: string,
+	mounted: XdevMountedRenderer | undefined,
+): XdevMountedRenderer | undefined {
+	if (mounted && (mounted.describeCall || mounted.describeResult)) return mounted;
+	return rendererLookup?.(name);
+}
+
+/** TSP call view for an `xd://` write: queued card until execution, then the device renderer's own view. */
+export function describeXdevCall(
+	name: string,
+	content: unknown,
+	options: RenderResultOptions,
+	resolveMounted?: (name: string) => XdevMountedRenderer | undefined,
+): NativeToolView | undefined {
+	const mounted = resolveMounted?.(name);
+	const args = decodeInnerArgs(content);
+	if (!options.executionStarted) {
+		return describeDefaultToolExecution({
+			label: `queued ${displayDeviceLabel(name, mounted)}`,
+			args: displayDeviceArgs(args),
+			options: { ...options, isPartial: true, spinnerFrame: undefined },
+		});
+	}
+	const renderer = resolveDeviceDescriber(name, mounted);
+	if (renderer?.describeCall) return renderer.describeCall(args, options);
+	return describeDefaultToolExecution({ label: mounted?.label ?? name, args, options });
+}
+
+/** TSP result view for an `xd://` dispatch, forwarded to the device renderer. */
+export function describeXdevResult(
+	dispatch: XdevRenderDispatch,
+	result: { content: Array<{ type: string; text?: string }>; isError?: boolean },
+	options: RenderResultOptions,
+	resolveMounted?: (name: string) => XdevMountedRenderer | undefined,
+): NativeToolView | undefined {
+	const output = result.content
+		.map(block => (block.type === "text" ? block.text : ""))
+		.filter(Boolean)
+		.join("\n");
+	if (dispatch.mode === "help") return output ? { body: [text(output, { wrap: "word" })] } : undefined;
+	const mounted = resolveMounted?.(dispatch.tool);
+	const renderer = resolveDeviceDescriber(dispatch.tool, mounted);
+	if (renderer?.describeResult) {
+		const innerResult = { content: result.content, details: dispatch.inner, isError: result.isError };
+		const view = renderer.describeResult(innerResult, options, dispatch.args ?? {});
+		if (!view || renderer.mergeCallAndResult || !renderer.describeCall) return view;
+		const call = renderer.describeCall(dispatch.args ?? {}, { ...options, isPartial: false });
+		return { ...view, head: view.head ?? call?.head, body: [...(call?.body ?? []), ...(view.body ?? [])] };
+	}
+	return describeDefaultToolExecution({
+		label: mounted?.label ?? dispatch.tool,
+		args: dispatch.args ?? {},
+		result: { output, isError: result.isError },
+		options,
+	});
+}
+
 /** Forward an `xd://` dispatch result to the mounted tool's renderer. */
 export function renderXdevResult(
 	dispatch: XdevRenderDispatch,

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),
@@ -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) {