@linxiraos/pi-tui 1.1.27 → 1.2.1

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/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 {

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,6 +125,44 @@ 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;
@@ -157,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;
@@ -167,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,
@@ -186,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;
 
@@ -256,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;
@@ -369,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 = [];
 	}
 
 	/**
@@ -383,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);
@@ -491,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);
 	}
 
@@ -505,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;
 	}
 
@@ -530,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);
 	}
 
@@ -583,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);
+	}
+
+	/** 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", body: unknown): void {
+	#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));
 	}
@@ -665,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();

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,

package/src/native/blobs.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 { getImageDimensions } from "../terminal-capabilities";
@@ -16,7 +18,13 @@ export interface NativeBlob {
 	readonly bytes: Uint8Array;
 }
 
-const blobs = new Map<string, NativeBlob>();
+const blobs = new Map<string, WeakRef<NativeBlob>>();
+const registeredBlobs = new Map<string, NativeBlob>();
+const releasedBlobs = new FinalizationRegistry<{ id: string; reference: WeakRef<NativeBlob> }>(({ id, reference }) => {
+	if (blobs.get(id) === reference) blobs.delete(id);
+});
+// Props spreads preserve ownership; wire serialization omits symbol keys.
+const kBlob = Symbol("native.blob");
 // Registration usually repeats with the same bytes object on every describe;
 // the tag skips rehashing it.
 const kBlobId = Symbol("native.blobId");
@@ -25,19 +33,42 @@ interface BlobTagged {
 	[kBlobId]?: string;
 }
 
-/** Register `bytes` and return their content address (sha256 hex) for `image.p.blob`. */
-export function registerNativeBlob(bytes: Uint8Array, mime: string): string {
+function getOrCreateBlob(bytes: Uint8Array, mime: string): NativeBlob {
 	const known = (bytes as BlobTagged)[kBlobId];
-	if (known !== undefined) return known;
-	const id = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+	const id = known ?? new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
 	(bytes as BlobTagged)[kBlobId] = id;
-	if (!blobs.has(id)) blobs.set(id, { id, mime, bytes });
-	return id;
+	let blob = blobs.get(id)?.deref();
+	if (!blob) {
+		blob = { id, mime, bytes };
+		const reference = new WeakRef(blob);
+		blobs.set(id, reference);
+		releasedBlobs.register(blob, { id, reference });
+	}
+	return blob;
+}
+
+/** Register bytes for process-lifetime, id-only use. Prefer {@link nativeImageNode} for owned images. */
+export function registerNativeBlob(bytes: Uint8Array, mime: string): string {
+	const blob = getOrCreateBlob(bytes, mime);
+	registeredBlobs.set(blob.id, blob);
+	return blob.id;
 }
 
 /** A registered blob by id. */
 export function getNativeBlob(id: string): NativeBlob | undefined {
-	return blobs.get(id);
+	return blobs.get(id)?.deref();
+}
+
+/** An image whose props own its bytes, including while hidden, unmounted, or awaiting upload. */
+export function nativeImageNode(
+	bytes: Uint8Array,
+	mime: string,
+	p?: Omit<TspProps<"image">, "blob" | "builtin">,
+	key?: string,
+): NativeNode {
+	const blob = getOrCreateBlob(bytes, mime);
+	const props = { ...p, blob: blob.id, [kBlob]: blob };
+	return node("image", props, undefined, key);
 }
 
 /**
@@ -51,9 +82,13 @@ export function base64ImageNode(
 	p?: Omit<TspProps<"image">, "blob" | "builtin" | "w" | "h">,
 	key?: string,
 ): NativeNode {
-	const blob = registerNativeBlob(Buffer.from(data, "base64"), mimeType);
 	const size = getImageDimensions(data, mimeType);
-	return node("image", size ? { ...p, blob, w: size.widthPx, h: size.heightPx } : { ...p, blob }, undefined, key);
+	return nativeImageNode(
+		Buffer.from(data, "base64"),
+		mimeType,
+		size ? { ...p, w: size.widthPx, h: size.heightPx } : p,
+		key,
+	);
 }
 
 /** `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload changes. */

package/src/native/encode.d.ts

@@ -15,11 +15,10 @@ export type TspIncoming = {
 };
 /** Message parameters (`k=v`, ASCII, never containing `;`). */
 export type TspParams = Readonly<Record<string, string | number>>;
-/** Split `body` into pieces of at most `limit` UTF-8 bytes, never inside a code point. */
-export declare function splitUtf8(body: string, limit: number): string[];
 /**
- * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes.
- * Returns the complete byte string to write (all chunks, in order).
+ * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes:
+ * the first chunk carries `params`, every chunk `c=<id>` and all but the last
+ * `m=1`. Returns the complete byte string to write (all chunks, in order).
  */
 export declare function encodeTspMessage(verb: TspVerb, body: string, params?: TspParams, limit?: number): string;
 /** Encode a JSON message body. */

package/src/native/encode.ts

@@ -6,7 +6,9 @@
  * negotiated `apc` limit is split across messages with the same verb, tagged
  * `c=<chunk-id>`, with `m=1` on every chunk but the last; the receiver joins
  * the bodies byte-wise. Chunks split on code-point boundaries, so every chunk
- * is valid UTF-8 on its own and the joined bytes equal the original body.
+ * is valid UTF-8 on its own and the joined bytes equal the original body, and
+ * never where the next chunk would lead with a `key=value;` segment the
+ * receiver would read as a parameter (Tern's `tsp_chunks`).
  */
 import { isRecord } from "@linxiraos/pi-utils/type-guards";
 import {
@@ -34,36 +36,58 @@ export type TspParams = Readonly<Record<string, string | number>>;
 
 let nextChunkId = 1;
 
-/** UTF-8 byte length of one UTF-16 code unit sequence starting at `i`, and its unit count. */
-function codePointBytes(text: string, i: number): { bytes: number; units: number } {
-	const c = text.charCodeAt(i);
-	if (c < 0x80) return { bytes: 1, units: 1 };
-	if (c < 0x800) return { bytes: 2, units: 1 };
-	if (c >= 0xd800 && c <= 0xdbff && i + 1 < text.length) {
-		const next = text.charCodeAt(i + 1);
-		if (next >= 0xdc00 && next <= 0xdfff) return { bytes: 4, units: 2 };
+/** Whether `bytes` from `at` leads with a `key=value;` segment, which a receiver reads as one more parameter. */
+function leadsWithParameter(bytes: Uint8Array, at: number): boolean {
+	let i = at;
+	// Key bytes: `[A-Za-z0-9_-]`.
+	for (; i < bytes.length; i++) {
+		const b = bytes[i]!;
+		if (
+			!((b >= 0x30 && b <= 0x39) || (b >= 0x41 && b <= 0x5a) || (b >= 0x61 && b <= 0x7a) || b === 0x5f || b === 0x2d)
+		)
+			break;
 	}
-	return { bytes: 3, units: 1 };
+	if (i === at || bytes[i] !== 0x3d) return false;
+	i++;
+	// Value bytes: printable ASCII other than `;`.
+	while (i < bytes.length && bytes[i]! >= 0x21 && bytes[i]! <= 0x7e && bytes[i] !== 0x3b) i++;
+	return bytes[i] === 0x3b;
 }
 
-/** Split `body` into pieces of at most `limit` UTF-8 bytes, never inside a code point. */
-export function splitUtf8(body: string, limit: number): string[] {
-	const max = Math.max(4, Math.trunc(limit));
+/**
+ * Where the chunk of `bytes` starting at `start` ends: the safe cut nearest
+ * below `start + limit` (above `start`), else the nearest above it, else the
+ * end. A cut is safe on a UTF-8 character boundary where the rest doesn't
+ * lead with a parameter-shaped segment.
+ */
+function chunkEnd(bytes: Uint8Array, start: number, limit: number): number {
+	const target = start + limit;
+	if (target >= bytes.length) return bytes.length;
+	const safe = (at: number): boolean => (bytes[at]! & 0xc0) !== 0x80 && !leadsWithParameter(bytes, at);
+	for (let at = target; at > start; at--) if (safe(at)) return at;
+	for (let at = target + 1; at < bytes.length; at++) if (safe(at)) return at;
+	return bytes.length;
+}
+
+/**
+ * Chunk bodies for `body` of `byteLength` UTF-8 bytes, cut as Tern's
+ * `tsp_chunks` cuts. Pure ASCII without `;` (every base64 blob) has no
+ * parameter-shaped segment and no multibyte character, so it is cut every
+ * `limit` characters.
+ */
+function chunkBodies(body: string, byteLength: number, limit: number): string[] {
+	const max = Math.max(1, Math.trunc(limit));
 	const pieces: string[] = [];
-	let start = 0;
-	let bytes = 0;
-	let i = 0;
-	while (i < body.length) {
-		const step = codePointBytes(body, i);
-		if (bytes + step.bytes > max) {
-			pieces.push(body.slice(start, i));
-			start = i;
-			bytes = 0;
-		}
-		bytes += step.bytes;
-		i += step.units;
+	if (byteLength === body.length && !body.includes(";")) {
+		for (let at = 0; at < body.length; at += max) pieces.push(body.slice(at, at + max));
+		return pieces;
+	}
+	const bytes = Buffer.from(body, "utf8");
+	for (let start = 0; start < bytes.length;) {
+		const end = chunkEnd(bytes, start, max);
+		pieces.push(bytes.toString("utf8", start, end));
+		start = end;
 	}
-	pieces.push(body.slice(start));
 	return pieces;
 }
 
@@ -79,8 +103,9 @@ function encodeParams(params: TspParams | undefined): string {
 }
 
 /**
- * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes.
- * Returns the complete byte string to write (all chunks, in order).
+ * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes:
+ * the first chunk carries `params`, every chunk `c=<id>` and all but the last
+ * `m=1`. Returns the complete byte string to write (all chunks, in order).
  */
 export function encodeTspMessage(
 	verb: TspVerb,
@@ -90,13 +115,15 @@ export function encodeTspMessage(
 ): string {
 	const base = encodeParams(params);
 	// Fast path: ASCII-length bound first, exact byte count only near the limit.
-	if (body.length * 3 <= limit || Buffer.byteLength(body, "utf8") <= limit) return frame(verb, base, body);
+	if (body.length * 3 <= limit) return frame(verb, base, body);
+	const byteLength = Buffer.byteLength(body, "utf8");
+	if (byteLength <= limit) return frame(verb, base, body);
 	const chunkId = (nextChunkId++).toString(36);
-	const pieces = splitUtf8(body, limit);
+	const pieces = chunkBodies(body, byteLength, limit);
 	let out = "";
 	for (let i = 0; i < pieces.length; i++) {
 		const more = i < pieces.length - 1 ? ";m=1" : "";
-		out += frame(verb, `${base};c=${chunkId}${more}`, pieces[i]!);
+		out += frame(verb, `${i === 0 ? base : ""};c=${chunkId}${more}`, pieces[i]!);
 	}
 	return out;
 }

package/src/native/overlay.d.ts

@@ -58,6 +58,11 @@ export interface ActionButtonOptions {
  * which the component routes to the same code path as the key.
  */
 export declare function actionButton(label: string, act: string, options?: ActionButtonOptions): NativeNode;
+/**
+ * A bare `esc` keycap button for a view's top-right corner: a click sends
+ * `act` (default `close`), which the component routes to its Esc path.
+ */
+export declare function escCloseButton(act?: string, key?: string): NativeNode;
 /** A row of {@link actionButton}s (role `zeta.actions`); `null` entries become the spacer that end-aligns what follows. */
 export declare function actionBar(buttons: readonly (NativeNode | null)[], key?: string): NativeNode;
 /** Spans of an annotation callout: a dim `label:` then the note. */

package/src/native/overlay.ts

@@ -119,6 +119,19 @@ export function actionButton(label: string, act: string, options: ActionButtonOp
 	);
 }
 
+/**
+ * A bare `esc` keycap button for a view's top-right corner: a click sends
+ * `act` (default `close`), which the component routes to its Esc path.
+ */
+export function escCloseButton(act = "close", key = "esc-close"): NativeNode {
+	return node(
+		"row",
+		{ role: "zeta.btn", align: "center", actions: { click: act }, title: `Close  ${formatTooltipKey("escape")}` },
+		[kbd("escape")],
+		key,
+	);
+}
+
 /** A row of {@link actionButton}s (role `zeta.actions`); `null` entries become the spacer that end-aligns what follows. */
 export function actionBar(buttons: readonly (NativeNode | null)[], key = "actions"): NativeNode {
 	const children = buttons.map(button => button ?? node("spacer", { grow: 1 }));

package/src/native/reconcile.ts

@@ -30,6 +30,7 @@
 import * as logger from "@linxiraos/pi-utils/logger";
 import { TSP_TEXT_KINDS, type TspKind, type TspNode, type TspOp, type TspScrollBy } from "@linxiraos/pi-wire";
 import { type Component, Container, CURSOR_MARKER } from "../tui";
+import { getNativeBlob } from "./blobs";
 import { normalizeIconProps } from "./icons";
 import type { DescribeContext, NativeChild, NativeNode, NativeRevealAt } from "./node";
 import { isNativeSettled } from "./settle";
@@ -291,6 +292,7 @@ export class Reconciler {
 		this.#prevPortals = portals;
 		this.#regions = next;
 		for (const entry of this.#dels) this.#deleteEntry(entry);
+		this.#dels = [];
 		// Parked to survive a parent/child swap but absent from the new description.
 		for (const state of this.#parked) {
 			if (!state.parked) continue;
@@ -711,6 +713,8 @@ export class Reconciler {
 		owner: Owner,
 		entries: readonly Entry[],
 	): Readonly<Record<string, unknown>> | undefined {
+		// Dereferencing pins the blob through this synchronous reconcile/upload job, even after settling drops its node.
+		if (node.k === "image" && node.p?.blob) getNativeBlob(node.p.blob);
 		return normalizeIconProps(node.k, this.#resolveRefs(node, owner, entries));
 	}