@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/multiplexers/types.ts

@@ -0,0 +1,110 @@
+import type { TerminalNotification } from "../terminal-capabilities";
+
+/**
+ * Classification tier. `session` markers outrank the TERM fallback; `outerApp`
+ * hosts rank below it so a multiplexer nested inside them still wins.
+ */
+export type TerminalMultiplexerPrecedence = "session" | "outerApp";
+
+/**
+ * Notification delivery tier, tried in this order so the innermost target wins:
+ * a `pane` notifier addresses the exact pane through the multiplexer's CLI, a
+ * `surface` notifier addresses the containing app surface, and an `inBand`
+ * notifier rewrites the terminal's own notification sequence.
+ */
+export type TerminalMultiplexerNotificationTier = "pane" | "surface" | "inBand";
+
+/** One notification offered to a multiplexer notifier. */
+export interface TerminalMultiplexerNotificationRequest {
+	readonly message: string | TerminalNotification;
+	readonly env: NodeJS.ProcessEnv;
+	/** The host terminal's formatted OSC notification, or `null` when it notifies with a bare BEL. */
+	readonly sequence: string | null;
+	/** Write a sequence through the active terminal. */
+	write(data: string): void;
+}
+
+export interface TerminalMultiplexerNotifier {
+	readonly tier: TerminalMultiplexerNotificationTier;
+	/** Deliver the notification. `false` leaves it to the next notifier and then the terminal fallback. */
+	send(request: TerminalMultiplexerNotificationRequest): boolean;
+}
+
+/**
+ * OSC 8 handling inside a multiplexer session:
+ * - `render`: the multiplexer draws and opens links itself, so links work
+ *   whatever the outer terminal supports, unless another session with a
+ *   hyperlink policy sits in the path.
+ * - `drop`: never forwards OSC 8; its session anywhere in the path disables links.
+ * - `forward`: forwards OSC 8 once it self-reports (`TERM_PROGRAM`/`TERM_PROGRAM_VERSION`)
+ *   at least `major.minor`; older or unreported versions stay off.
+ */
+export type TerminalMultiplexerHyperlinks =
+	| "render"
+	| "drop"
+	| {
+			readonly forward: {
+				/** Lowercase `TERM_PROGRAM` the multiplexer sets inside its panes. */
+				readonly termProgram: string;
+				readonly major: number;
+				readonly minor: number;
+			};
+	  };
+
+/** A multiplexer that answers OSC 11 from a cached copy of the outer terminal's background color. */
+export interface TerminalMultiplexerBackgroundColorCache {
+	/** Wrap a query so it reaches the outer terminal and refreshes the cache. */
+	passthrough(query: string): string;
+	/** How long the multiplexer needs to store the outer reply before the cache is re-read. */
+	readonly settleMs: number;
+}
+
+/** Everything omp needs to recognize one terminal multiplexer and adapt to it. */
+export interface TerminalMultiplexerModule<Id extends string = string> {
+	readonly id: Id;
+	readonly precedence: TerminalMultiplexerPrecedence;
+	/** Every environment variable `isInside()` reads. */
+	readonly sessionEnvKeys: readonly string[];
+	/** Lowercase TERM prefix that identifies the multiplexer when its session markers were stripped. */
+	readonly termPrefix?: string;
+	/**
+	 * Whether the multiplexer owns the screen grid. When true, rendering takes the
+	 * multiplexer path (no scrollback rebuild, anchored resize, skipped probes).
+	 */
+	readonly ownsScreenGrid: boolean;
+	isInside(env?: NodeJS.ProcessEnv): boolean;
+	/** Routes notifications the multiplexer would otherwise swallow. */
+	readonly notifier?: TerminalMultiplexerNotifier;
+	/** OSC 8 policy inside a session; unset defers to the outer terminal. */
+	readonly hyperlinks?: TerminalMultiplexerHyperlinks;
+	/**
+	 * The pane's VTE honors DEC 2026 even when DECRQM is unanswered or reports
+	 * the mode unrecognized (status 0): synchronized output starts on inside a
+	 * session, and an unrecognized report does not turn it off.
+	 */
+	readonly honorsSynchronizedOutput?: boolean;
+	/**
+	 * The session does not reveal whether its client renders graphics while
+	 * outer-terminal identity variables leak in, so images and Kitty
+	 * placeholders stay off unless the user forces them.
+	 */
+	readonly imagesRequireOverride?: boolean;
+	/** Platforms where the multiplexer breaks OSC 11 passthrough, so host appearance is used instead. */
+	readonly backgroundQueryBrokenOn?: readonly NodeJS.Platform[];
+	/** Present when OSC 11 replies come from a cache an explicit refresh must update first. */
+	readonly backgroundColorCache?: TerminalMultiplexerBackgroundColorCache;
+	/** Expands REP into identical styled cells, so destructive replays REP-encode their padding. */
+	readonly expandsRepPadding?: boolean;
+	/** Expires a synchronized update after a deadline, so large rebuild replays renew DEC 2026 as they stream. */
+	readonly expiresSynchronizedOutput?: boolean;
+	/**
+	 * Restoring the alternate buffer schedules a redraw that ends a synchronized
+	 * update early, so a synchronized resize rebuild stays on the main buffer.
+	 */
+	readonly altRestoreEndsSynchronizedOutput?: boolean;
+	/**
+	 * May grow its grid before SIGWINCH reaches the app, so a rebuild-mode grow
+	 * whose full viewport no longer reaches the bottom replays history.
+	 */
+	readonly growsBeforeSigwinch?: boolean;
+}

package/src/multiplexers/wmux.d.ts

@@ -0,0 +1,12 @@
+/**
+ * wmux is a Windows multiplexer (Electron + xterm.js) modeled on cmux/herdr that
+ * repaints its pane in place. WMUX_CLI / WMUX_PIPE are CLI path overrides and can
+ * be set outside a wmux terminal.
+ */
+export declare const wmuxMultiplexer: {
+    readonly id: "wmux";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["WMUX", "WMUX_SURFACE_ID"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+};

package/src/multiplexers/wmux.ts

@@ -0,0 +1,16 @@
+import type { TerminalMultiplexerModule } from "./types";
+
+/**
+ * wmux is a Windows multiplexer (Electron + xterm.js) modeled on cmux/herdr that
+ * repaints its pane in place. WMUX_CLI / WMUX_PIPE are CLI path overrides and can
+ * be set outside a wmux terminal.
+ */
+export const wmuxMultiplexer = {
+	id: "wmux",
+	precedence: "session",
+	sessionEnvKeys: ["WMUX", "WMUX_SURFACE_ID"],
+	ownsScreenGrid: true,
+	isInside(env: NodeJS.ProcessEnv = Bun.env): boolean {
+		return env.WMUX === "1" || Boolean(env.WMUX_SURFACE_ID);
+	},
+} as const satisfies TerminalMultiplexerModule;

package/src/multiplexers/zellij.d.ts

@@ -0,0 +1,12 @@
+export declare const zellijMultiplexer: {
+    readonly id: "zellij";
+    readonly precedence: "session";
+    readonly sessionEnvKeys: readonly ["ZELLIJ"];
+    readonly ownsScreenGrid: true;
+    readonly isInside: (env?: NodeJS.ProcessEnv) => boolean;
+    readonly notifier: {
+        readonly tier: "inBand";
+        readonly send: ({ sequence, write }: import("./types").TerminalMultiplexerNotificationRequest) => boolean;
+    };
+    readonly backgroundQueryBrokenOn: readonly ["darwin"];
+};

package/src/multiplexers/zellij.ts

@@ -0,0 +1,24 @@
+import type { TerminalMultiplexerModule } from "./types";
+
+export const zellijMultiplexer = {
+	id: "zellij",
+	precedence: "session",
+	sessionEnvKeys: ["ZELLIJ"],
+	ownsScreenGrid: true,
+	isInside(env: NodeJS.ProcessEnv = Bun.env): boolean {
+		return Boolean(env.ZELLIJ);
+	},
+	notifier: {
+		tier: "inBand",
+		// Zellij drops OSCs and has no DCS passthrough; a bare BEL raises its bell
+		// flag. Bell notifications already provide that signal.
+		send({ sequence, write }) {
+			if (sequence === null) return false;
+			write(`${sequence}\x07`);
+			return true;
+		},
+	},
+	// Zellij currently breaks OSC 11 passthrough on macOS, so terminal-derived
+	// appearance cannot be trusted there.
+	backgroundQueryBrokenOn: ["darwin"],
+} as const satisfies TerminalMultiplexerModule;

package/src/native/apply.d.ts

@@ -1,8 +1,9 @@
 /**
  * Reference document applier: applies TSP frames to a node tree the way the
- * spec says the terminal does (§5.1). Ops are validated and applied one by
- * one; a rejected op is reported and skipped without affecting the rest of
- * the frame. `settle` is recorded as a hint and never restricts later ops.
+ * spec says the terminal does (Tern SDK, `protocol/documents.md`, frame ops).
+ * Ops are validated and applied one by one; a rejected op is reported and
+ * skipped without affecting the rest of the frame. `settle` is recorded as a
+ * hint and never restricts later ops.
  *
  * Used by tests, the debug server's `doc` op, and the TSP test harness.
  */

package/src/native/apply.ts

@@ -1,8 +1,9 @@
 /**
  * Reference document applier: applies TSP frames to a node tree the way the
- * spec says the terminal does (§5.1). Ops are validated and applied one by
- * one; a rejected op is reported and skipped without affecting the rest of
- * the frame. `settle` is recorded as a hint and never restricts later ops.
+ * spec says the terminal does (Tern SDK, `protocol/documents.md`, frame ops).
+ * Ops are validated and applied one by one; a rejected op is reported and
+ * skipped without affecting the rest of the frame. `settle` is recorded as a
+ * hint and never restricts later ops.
  *
  * Used by tests, the debug server's `doc` op, and the TSP test harness.
  */

package/src/native/backend.d.ts

@@ -48,8 +48,9 @@ export interface NativeBackendOptions {
 /**
  * The reply a v1 terminal is assumed to give before its real `hello` arrives
  * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary, the
- * default APC limit and credits, the terminal's width, the appearance zeta
- * already detected, and full motion.
+ * default APC limit and credits, the terminal's width, the appearance omp
+ * already detected, full motion, and `blobs`, so a resumed session's images
+ * are asked about rather than resent before the reply comes.
  */
 export declare function assumedTspHello(terminal: Terminal): TspHello;
 export declare class NativeBackend {
@@ -83,8 +84,8 @@ export declare class NativeBackend {
      * The terminal's real `hello` reply after an optimistic start: adopt its
      * APC limit, credits, cell size, kinds, appearance and motion preference.
      * A width the terminal already reported in a `resize` event wins over the
-     * reply's. A different vocabulary or motion preference re-describes every
-     * component, so kinds the terminal lacks fall back.
+     * reply's. A different vocabulary, motion preference or clock re-describes
+     * every component, so kinds the terminal lacks fall back.
      */
     confirm(hello: TspHello): void;
     /** SIGWINCH: refresh the width used for `rows` fallback until the terminal reports one. */

package/src/native/backend.ts

@@ -14,8 +14,18 @@
  * render while blocked only marks the surface dirty; the next `ack` reconciles
  * once against the last sent state, so every intermediate change coalesces
  * into one frame (`set`s merged, `text append`s joined).
+ *
+ * Blobs. Each image's bytes reach the terminal once per connection. A
+ * terminal with the `blobs` feature is asked first which it already holds:
+ * under `TERN_BLOB_DIR` (Tern's on-disk blob cache, on this machine) every new
+ * blob is written there and then asked about, so its bytes never cross the
+ * pty; otherwise the first pass after (re)connecting asks, so a resumed
+ * session doesn't resend what the terminal kept. Whatever the reply lacks
+ * (or a reply that never comes) is sent inline with `b`. Frames never wait:
+ * the terminal draws an image whose blob arrives after the frame.
  */
 import * as fs from "node:fs";
+import * as path from "node:path";
 import * as logger from "@linxiraos/pi-utils/logger";
 import {
 	TSP_DEFAULT_APC_LIMIT,
@@ -40,7 +50,7 @@ import {
 } from "../theme/theme";
 import type { Component, OverlayOptions, RenderScheduler, RenderTimer } from "../tui";
 import { TspDocument } from "./apply";
-import { getNativeBlob } from "./blobs";
+import { getNativeBlob, type NativeBlob } from "./blobs";
 import { node } from "./describe";
 import { encodeTspJson, encodeTspMessage, type TspHello, TspReader, splitTspMessage } from "./encode";
 import type { DescribeContext, NativeChild, NativeNode, NativeSurface, NativeUiEvent } from "./node";
@@ -115,11 +125,50 @@ const RECENT_FRAMES = 64;
 const STALLED_ACK_MS = 5000;
 /** Role of the session's surfaces; a screen page may name its own. */
 const SESSION_ROLE = "zeta.session";
+/** A `blobs` query unanswered this long counts its ids as missing: they go inline. */
+const BLOB_REPLY_MS = 3000;
+/** Expired queries kept to pair late replies with their queries, at most. */
+const MAX_BLOB_QUERIES = 16;
+
+/** A `blobs` query awaiting its reply; `timer` is unset once its ids no longer depend on it. */
+interface BlobQuery {
+	readonly ids: readonly string[];
+	timer: RenderTimer | undefined;
+}
+
+/**
+ * Save `blob` in the terminal's blob cache as `<dir>/<id>` (written aside,
+ * then renamed; skipped when present). A failure only means the terminal
+ * won't find it, so the blob goes inline.
+ */
+async function cacheBlob(dir: string, blob: NativeBlob): Promise<void> {
+	const target = path.join(dir, blob.id);
+	const temp = `${target}.tmp${process.pid}`;
+	try {
+		if (await Bun.file(target).exists()) return;
+		// Not `Bun.write`: it would create a missing folder, which only Tern may.
+		await fs.promises.writeFile(temp, blob.bytes);
+		await fs.promises.rename(temp, target);
+	} catch (error) {
+		logger.debug("TSP: could not save a blob to the terminal's cache", { dir, id: blob.id, error: String(error) });
+		await fs.promises.rm(temp, { force: true }).catch(() => {});
+	}
+}
+
+/**
+ * A `b` message's parameters. Tern names a blob by the sha256 of the bytes it
+ * receives and ignores `id`, but Tern 0.5.3 and earlier reject a blob without
+ * it, so it stays until those are gone.
+ */
+function blobParams(blob: NativeBlob): Record<string, string> {
+	return { id: blob.id, mime: blob.mime };
+}
 
 class NativeContext implements DescribeContext {
 	cols: number;
 	reduceMotion: boolean;
 	dark: boolean;
+	hour12: boolean | undefined;
 	#kinds: ReadonlySet<string>;
 	#features: ReadonlySet<string>;
 
@@ -127,6 +176,7 @@ class NativeContext implements DescribeContext {
 		this.cols = cols;
 		this.reduceMotion = hello.reduceMotion === true;
 		this.dark = hello.dark !== false;
+		this.hour12 = hello.hour12;
 		this.#kinds = new Set(hello.kinds);
 		this.#features = new Set(hello.features);
 	}
@@ -155,8 +205,9 @@ function sameSet(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
 /**
  * The reply a v1 terminal is assumed to give before its real `hello` arrives
  * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary, the
- * default APC limit and credits, the terminal's width, the appearance zeta
- * already detected, and full motion.
+ * default APC limit and credits, the terminal's width, the appearance omp
+ * already detected, full motion, and `blobs`, so a resumed session's images
+ * are asked about rather than resent before the reply comes.
  */
 export function assumedTspHello(terminal: Terminal): TspHello {
 	const appearance = terminal.appearance;
@@ -165,6 +216,7 @@ export function assumedTspHello(terminal: Terminal): TspHello {
 		v: TSP_VERSION,
 		term: "tern",
 		kinds: TSP_KINDS,
+		features: ["blobs"],
 		apc: TSP_DEFAULT_APC_LIMIT,
 		credits: TSP_DEFAULT_CREDITS,
 		cols: terminal.columns,
@@ -184,7 +236,6 @@ class Surface {
 	acked = 0;
 	/** Send times of unacknowledged frames, oldest first. */
 	unacked: number[] = [];
-	uploaded = new Set<string>();
 	focus: string | null = null;
 	dirty = false;
 
@@ -254,6 +305,14 @@ export class NativeBackend {
 	#paletteKey: string | undefined;
 	/** Serialized palette last sent, to skip resends of an unchanged theme. */
 	#paletteSent: string | undefined;
+	/** Pending delivery owns bytes until sent or confirmed held; settled descriptions may already be released. */
+	#blobs = new Map<string, NativeBlob | "sent">();
+	/** `blobs` queries sent, oldest first: the terminal answers each once, in order. */
+	#blobQueries: BlobQuery[] = [];
+	/** The next pass with new blobs asks the terminal which it holds (a fresh connection). */
+	#askHeld = true;
+	/** Bumped when the connection resets or stops, so blob cache writes finishing later are dropped. */
+	#blobEpoch = 0;
 
 	constructor(host: NativeHost, hello: TspHello, options: NativeBackendOptions = {}) {
 		this.#host = host;
@@ -367,6 +426,9 @@ export class NativeBackend {
 		this.#unbindTheme = undefined;
 		this.#useNerdSymbols(false);
 		this.#clearStallTimer();
+		// Replies no longer reach the backend: forget the queries outright.
+		this.#resetBlobs();
+		this.#blobQueries = [];
 	}
 
 	/**
@@ -381,13 +443,14 @@ export class NativeBackend {
 		this.#live = true;
 		this.#useNerdSymbols(true);
 		this.#watchTheme();
+		this.#resetBlobs();
 		const surface = this.#inline;
 		surface.reconciler.detachLive();
 		surface.unacked = [];
 		surface.acked = surface.seq;
 		surface.focus = null;
 		surface.dirty = false;
-		this.#write("o", { id: surface.id, mode: "inline", title: "zeta", role: SESSION_ROLE, adopt: true });
+		this.#write("o", { id: surface.id, mode: "inline", title: "omp", role: SESSION_ROLE, adopt: true });
 		this.#sendPalette(surface);
 		// After the `o`, as in `start()`.
 		setNativeRendering(true);
@@ -398,8 +461,8 @@ export class NativeBackend {
 	 * The terminal's real `hello` reply after an optimistic start: adopt its
 	 * APC limit, credits, cell size, kinds, appearance and motion preference.
 	 * A width the terminal already reported in a `resize` event wins over the
-	 * reply's. A different vocabulary or motion preference re-describes every
-	 * component, so kinds the terminal lacks fall back.
+	 * reply's. A different vocabulary, motion preference or clock re-describes
+	 * every component, so kinds the terminal lacks fall back.
 	 */
 	confirm(hello: TspHello): void {
 		const before = this.#cx;
@@ -411,7 +474,12 @@ export class NativeBackend {
 			this.#sawResize = true;
 		}
 		if (this.#cx.dark !== before.dark) this.#host.appearanceChanged(this.#cx.dark);
-		if (this.#cx.reduceMotion !== before.reduceMotion || !this.#cx.sameVocabulary(before)) this.#host.invalidate();
+		if (
+			this.#cx.reduceMotion !== before.reduceMotion ||
+			this.#cx.hour12 !== before.hour12 ||
+			!this.#cx.sameVocabulary(before)
+		)
+			this.#host.invalidate();
 		this.#host.requestRender();
 	}
 
@@ -484,7 +552,7 @@ export class NativeBackend {
 			logger.debug("TSP frame", { sf: surface.id, ops: ops.length, rows: surface.reconciler.fallbackCount });
 		}
 		if (ops.length === 0) return;
-		this.#uploadBlobs(surface, ops);
+		this.#uploadBlobs(ops);
 		this.#sendFrame(surface, ops);
 	}
 
@@ -498,6 +566,7 @@ export class NativeBackend {
 		this.#record("in", raw.verb, raw.params, raw.body);
 		const message = this.#reader.feed(sequence);
 		if (message?.verb === "e") this.#handleEvent(message.event);
+		else if (message?.reply.r === "blobs") this.#onBlobsReply(message.reply.have);
 		return true;
 	}
 
@@ -523,7 +592,7 @@ export class NativeBackend {
 	}
 
 	#open(surface: Surface): void {
-		this.#write("o", { id: surface.id, mode: surface.mode, title: "zeta", role: surface.role });
+		this.#write("o", { id: surface.id, mode: surface.mode, title: "omp", role: surface.role });
 		this.#sendPalette(surface);
 	}
 
@@ -576,25 +645,118 @@ export class NativeBackend {
 		this.#write("f", frame);
 	}
 
-	#uploadBlobs(surface: Surface, ops: readonly TspOp[]): void {
+	/** Deliver the blobs `ops` reference that this connection hasn't handled yet (see the module doc). */
+	#uploadBlobs(ops: readonly TspOp[]): void {
 		const ids = new Set<string>();
 		for (const op of ops) collectBlobs(op, ids);
+		const fresh: NativeBlob[] = [];
 		for (const id of ids) {
-			if (surface.uploaded.has(id)) continue;
+			if (this.#blobs.has(id)) continue;
 			const blob = getNativeBlob(id);
-			if (!blob) {
-				logger.warn("TSP: image references an unregistered blob", { id });
-				continue;
+			if (blob) fresh.push(blob);
+			else logger.warn("TSP: image references an unregistered blob", { id });
+		}
+		if (fresh.length === 0) return;
+		if (!this.#cx.feature("blobs")) {
+			for (const blob of fresh) this.#sendBlob(blob);
+			return;
+		}
+		const dir = Bun.env.TERN_BLOB_DIR;
+		if (dir) {
+			for (const blob of fresh) this.#blobs.set(blob.id, blob);
+			void this.#cacheBlobs(dir, fresh);
+			return;
+		}
+		if (this.#askHeld) {
+			this.#askHeld = false;
+			this.#askBlobs(fresh);
+			return;
+		}
+		for (const blob of fresh) this.#sendBlob(blob);
+	}
+
+	/** Write `blobs` to the terminal's cache, then ask about the ones still pending. */
+	async #cacheBlobs(dir: string, blobs: readonly NativeBlob[]): Promise<void> {
+		const epoch = this.#blobEpoch;
+		await Promise.all(blobs.map(blob => cacheBlob(dir, blob)));
+		if (epoch !== this.#blobEpoch) return;
+		const pending = blobs.filter(blob => this.#blobs.get(blob.id) === blob);
+		if (pending.length > 0) this.#askBlobs(pending);
+	}
+
+	/** Ask the terminal which of `blobs` it holds; the reply (or its absence) settles them. */
+	#askBlobs(blobs: readonly NativeBlob[]): void {
+		for (const blob of blobs) this.#blobs.set(blob.id, blob);
+		const ids = blobs.map(blob => blob.id);
+		const query: BlobQuery = { ids, timer: undefined };
+		query.timer = this.#scheduler.scheduleRender(() => {
+			query.timer = undefined;
+			logger.warn("TSP: no reply to a blobs query; sending its blobs inline", { ids: ids.length });
+			this.#sendMissing(ids);
+		}, BLOB_REPLY_MS);
+		// Expired queries stay only to pair late replies; a terminal that never answers mustn't grow the list.
+		while (this.#blobQueries.length >= MAX_BLOB_QUERIES && !this.#blobQueries[0]!.timer) this.#blobQueries.shift();
+		this.#blobQueries.push(query);
+		this.#write("q", { q: "blobs", ids });
+	}
+
+	/**
+	 * The reply to the oldest outstanding query. Any `have` id still asked
+	 * about is held by the terminal (whichever query asked); the query's other
+	 * ids go inline.
+	 */
+	#onBlobsReply(have: readonly string[]): void {
+		const query = this.#blobQueries.shift();
+		for (const id of have) {
+			const blob = this.#blobs.get(id);
+			if (blob === undefined || blob === "sent") continue;
+			// The bytes went another way; a recording still carries them so a replay without them shows the image.
+			if (this.#recordPath) {
+				const body = Buffer.from(blob.bytes.buffer, blob.bytes.byteOffset, blob.bytes.byteLength).toString(
+					"base64",
+				);
+				this.#record("out", "b", blobParams(blob), body);
 			}
-			surface.uploaded.add(id);
-			const body = Buffer.from(blob.bytes.buffer, blob.bytes.byteOffset, blob.bytes.byteLength).toString("base64");
-			// The full body, so a replay (Tern's `surface-play`) shows the image.
-			this.#record("out", "b", { id, mime: blob.mime }, body);
-			this.#host.terminal.write(encodeTspMessage("b", body, { id, mime: blob.mime }, this.#limit));
+			this.#blobs.set(id, "sent");
 		}
+		if (!query?.timer) return;
+		query.timer.cancel();
+		query.timer = undefined;
+		this.#sendMissing(query.ids);
 	}
 
-	#write(verb: "o" | "f" | "t" | "x", body: unknown): void {
+	/** Send inline every id of `ids` still waiting on a query. */
+	#sendMissing(ids: readonly string[]): void {
+		for (const id of ids) {
+			const blob = this.#blobs.get(id);
+			if (blob !== undefined && blob !== "sent") this.#sendBlob(blob);
+		}
+	}
+
+	#sendBlob(blob: NativeBlob): void {
+		this.#blobs.set(blob.id, "sent");
+		const body = Buffer.from(blob.bytes.buffer, blob.bytes.byteOffset, blob.bytes.byteLength).toString("base64");
+		// The full body, so a replay (Tern's `surface-play`) shows the image.
+		this.#record("out", "b", blobParams(blob), body);
+		this.#host.terminal.write(encodeTspMessage("b", body, blobParams(blob), this.#limit));
+	}
+
+	/**
+	 * A new connection (resume, or a fresh inline surface after `gone`): the
+	 * terminal is asked again. Outstanding queries stay, without their
+	 * deadlines, only to pair their replies.
+	 */
+	#resetBlobs(): void {
+		this.#blobEpoch++;
+		this.#blobs.clear();
+		this.#askHeld = true;
+		for (const query of this.#blobQueries) {
+			query.timer?.cancel();
+			query.timer = undefined;
+		}
+	}
+
+	#write(verb: "o" | "f" | "t" | "x" | "q", body: unknown): void {
 		this.#record("out", verb, undefined, body);
 		this.#host.terminal.write(encodeTspJson(verb, body, undefined, this.#limit));
 	}
@@ -658,6 +820,7 @@ export class NativeBackend {
 			case "gone":
 				if (event.ids.includes(this.#inline.id)) {
 					// Adopt found nothing (evicted, or another pane): start over.
+					this.#resetBlobs();
 					this.#inline = this.#newSurface("inline");
 					if (this.#live) this.#open(this.#inline);
 					this.#host.requestRender();
@@ -671,6 +834,8 @@ export class NativeBackend {
 			case "action":
 			case "change":
 			case "edit":
+			case "undo":
+			case "send":
 				this.#routeUiEvent(event);
 				return;
 			case "focus": {
@@ -687,11 +852,17 @@ export class NativeBackend {
 	}
 
 	#routeUiEvent(
-		event: Extract<TspEvent, { ev: "toggle" | "select" | "activate" | "action" | "change" | "edit" }>,
+		event: Extract<
+			TspEvent,
+			{ ev: "toggle" | "select" | "activate" | "action" | "change" | "edit" | "undo" | "send" }
+		>,
 	): void {
 		const reconciler = this.#surfaceFor(event.sf)?.reconciler;
 		const target = reconciler?.target(event.id);
 		if (!reconciler || !target?.component.handleNativeEvent) return;
+		// Explicit sends must address the live editor, not a stale or invented
+		// descendant id that merely shares the component's namespace.
+		if (event.ev === "send" && (!this.#live || reconciler.focusTarget(target.component) !== event.id)) return;
 		// A list's items are nodes (`<list>/<key>`, or a component's root id) and
 		// map back to their described key. Data-first kinds (picker, prefs) send
 		// the program's own item ids (model ids, paths), which pass through.
@@ -721,6 +892,12 @@ export class NativeBackend {
 				ui = { type: "edit", key: target.keypath, from, to, text, cursor, len };
 				break;
 			}
+			case "undo":
+				ui = { type: "undo", key: target.keypath };
+				break;
+			case "send":
+				ui = { type: "send", key: target.keypath, text: event.text };
+				break;
 		}
 		target.component.handleNativeEvent(ui);
 		this.#host.requestRender();

package/src/native/blobs.d.ts

@@ -2,8 +2,10 @@
  * Content-addressed binary blobs (images) for `image` nodes.
  *
  * `describe()` registers the bytes and puts the returned id in `image.p.blob`;
- * the native backend uploads each referenced blob once per surface with verb
- * `b` before the frame that first references it.
+ * the native backend delivers each referenced blob once per terminal
+ * connection (asking the terminal first which it holds, or through its blob
+ * cache), else uploads it with verb `b` before the frame that first
+ * references it.
  */
 import type { TspProps } from "@linxiraos/pi-wire";
 import type { NativeNode } from "./node";
@@ -12,10 +14,12 @@ export interface NativeBlob {
     readonly mime: string;
     readonly bytes: Uint8Array;
 }
-/** Register `bytes` and return their content address (sha256 hex) for `image.p.blob`. */
+/** Register bytes for process-lifetime, id-only use. Prefer {@link nativeImageNode} for owned images. */
 export declare function registerNativeBlob(bytes: Uint8Array, mime: string): string;
 /** A registered blob by id. */
 export declare function getNativeBlob(id: string): NativeBlob | undefined;
+/** An image whose props own its bytes, including while hidden, unmounted, or awaiting upload. */
+export declare function nativeImageNode(bytes: Uint8Array, mime: string, p?: Omit<TspProps<"image">, "blob" | "builtin">, key?: string): NativeNode;
 /**
  * An `image` node for a base64 payload: the bytes are registered as a blob and
  * the pixel size probed from the header. Decoding and hashing cost real time,