@linxiraos/pi-tui 1.1.26 → 1.2.0

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,19 +15,21 @@ 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. */
 export declare function encodeTspJson(verb: TspVerb, value: unknown, params?: TspParams, limit?: number): string;
 /**
  * The `hello` query; callers follow it with a DA1 sentinel. `features: ["edit"]`
- * tells the terminal that zeta applies its `edit` events (TSP §8.5), so it may keep a
- * native selection in zeta's editors; without it, every key stays zeta's.
+#1:  * tells the terminal that zeta applies its `edit` events (Tern SDK,
+ * `protocol/input.md`), so it may keep a native selection in zeta's editors;
+ * without it, every key stays zeta's. `"undo"` says zeta applies `undo` events,
+ * so the terminal may turn ⌃Z in a field into one.
+ * `"send"` accepts an explicit prompt for a live composer without simulating keys.
  */
 export declare function encodeTspHelloQuery(version?: string): string;
 /** One decoded APC message: verb, parameters and raw 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;
 }
@@ -108,11 +135,20 @@ export function encodeTspJson(verb: TspVerb, value: unknown, params?: TspParams,
 
 /**
  * The `hello` query; callers follow it with a DA1 sentinel. `features: ["edit"]`
- * tells the terminal that zeta applies its `edit` events (TSP §8.5), so it may keep a
- * native selection in zeta's editors; without it, every key stays zeta's.
+#1:  * tells the terminal that zeta applies its `edit` events (Tern SDK,
+ * `protocol/input.md`), so it may keep a native selection in zeta's editors;
+ * without it, every key stays zeta's. `"undo"` says zeta applies `undo` events,
+ * so the terminal may turn ⌃Z in a field into one.
+ * `"send"` accepts an explicit prompt for a live composer without simulating keys.
  */
 export function encodeTspHelloQuery(version?: string): string {
-	return encodeTspJson("q", { q: "hello", v: [TSP_VERSION], app: "zeta", features: ["edit"], ver: version });
+	return encodeTspJson("q", {
+		q: "hello",
+		v: [TSP_VERSION],
+		app: "zeta",
+		features: ["edit", "undo", "send"],
+		ver: version,
+	});
 }
 
 /** One decoded APC message: verb, parameters and raw body. */
@@ -172,6 +208,7 @@ const EVENT_REQUIRED: Readonly<Record<string, Readonly<Record<string, "string" |
 	// `value` varies by control (boolean, number, string, string[], null): the handler checks it.
 	change: { id: "string", item: "string" },
 	edit: { id: "string", from: "number", to: "number", text: "string", cursor: "number", len: "number" },
+	undo: { id: "string" },
 	focus: { id: "string" },
 	error: { msg: "string" },
 	gone: { ids: "array" },
@@ -179,6 +216,11 @@ const EVENT_REQUIRED: Readonly<Record<string, Readonly<Record<string, "string" |
 
 function decodeEvent(value: Record<string, unknown>): TspEvent | null {
 	if (typeof value.ev !== "string") return null;
+	if (value.ev === "send") {
+		const { sf, id, text } = value;
+		if (typeof sf !== "string" || !sf || typeof id !== "string" || !id || typeof text !== "string") return null;
+		return { ev: "send", sf, id, text };
+	}
 	const required = EVENT_REQUIRED[value.ev];
 	if (!required) return null;
 	for (const key in required) {

package/src/native/node.d.ts

@@ -11,7 +11,8 @@
  * `rows` fallback node rendered through `render(cx.cols)`.
  *
  * See `packages/wire/src/tsp.ts` for the wire vocabulary and
- * `crates/tern/SURFACE_PROTOCOL.md` (Stencil repository) for the spec.
+ * the Tern SDK's Surface Protocol reference (`docs/sdk/src/protocol` in the
+ * Stencil repository, https://docs.stencil.so/tern/protocol/) for the spec.
  */
 import type { TspEvent, TspKind, TspProps, TspScrollBy, TspSpan } from "@linxiraos/pi-wire";
 import type { Component } from "../tui";
@@ -28,10 +29,12 @@ export type NativeNode = {
          */
         readonly key?: string;
         /**
-         * Scroll the node into view, placed like the `reveal` op, when it is
-         * added. Key a node by what it points at to reveal it again on a move.
+         * Scroll the node into view, placed like the `reveal` op. A placement
+         * reveals it when it is added: key a node by what it points at to
+         * reveal it again on a move. A {@link NativeReveal} reveals it whenever
+         * its `n` differs from the previous description of the same node.
          */
-        readonly reveal?: "start" | "end" | "nearest";
+        readonly reveal?: NativeRevealAt | NativeReveal;
         /**
          * Keyboard scrolling forwarded to the terminal (PgUp/PgDn/End reach the
          * program): moves the scroller at or above the node by `by` whenever
@@ -42,6 +45,17 @@ export type NativeNode = {
         readonly scroll?: NativeScroll;
     };
 }[TspKind];
+/** Where a revealed node lands in its scroller. */
+export type NativeRevealAt = "start" | "end" | "nearest";
+/**
+ * A repeatable {@link NativeNode.reveal}: bump `n` to bring an existing node
+ * into view again (a Contents entry jumping to its section). A freshly added
+ * node is not revealed.
+ */
+export interface NativeReveal {
+    readonly at: NativeRevealAt;
+    readonly n: number;
+}
 /** A {@link NativeNode.scroll} request. */
 export interface NativeScroll {
     readonly by: TspScrollBy;
@@ -57,6 +71,12 @@ export interface DescribeContext {
     readonly reduceMotion: boolean;
     /** The terminal's appearance is dark. */
     readonly dark: boolean;
+    /**
+     * The user's system reads a 12-hour clock (`false`: 24-hour); `undefined`
+     * when the terminal doesn't say. Pass it as `hour12` when formatting times:
+     * the process's own default locale may not know.
+     */
+    readonly hour12?: boolean;
     /** Whether the terminal renders `kind` natively (else describe something simpler or let it fall back). */
     supports(kind: TspKind): boolean;
     /**
@@ -117,7 +137,18 @@ export type NativeUiEvent = {
  | ({
     readonly type: "edit";
     readonly key: string;
-} & NativeTextEdit);
+} & NativeTextEdit)
+/** Undo the last change to an `editor`/`input` node's text (the terminal's ⌃Z); a no-op with no history. */
+ | {
+    readonly type: "undo";
+    readonly key: string;
+}
+/** Submit an explicit prompt through the composer's normal path, preserving the previous draft for recall. */
+ | {
+    readonly type: "send";
+    readonly key: string;
+    readonly text: string;
+};
 /**
  * A primitive edit the terminal made over its own text selection (cut,
  * typing, Backspace/Delete or paste over it, or collapsing it). Offsets are

package/src/native/node.ts

@@ -11,7 +11,8 @@
  * `rows` fallback node rendered through `render(cx.cols)`.
  *
  * See `packages/wire/src/tsp.ts` for the wire vocabulary and
- * `crates/tern/SURFACE_PROTOCOL.md` (Stencil repository) for the spec.
+ * the Tern SDK's Surface Protocol reference (`docs/sdk/src/protocol` in the
+ * Stencil repository, https://docs.stencil.so/tern/protocol/) for the spec.
  */
 import type { TspEvent, TspKind, TspProps, TspScrollBy, TspSpan } from "@linxiraos/pi-wire";
 import type { Component } from "../tui";
@@ -29,10 +30,12 @@ export type NativeNode = {
 		 */
 		readonly key?: string;
 		/**
-		 * Scroll the node into view, placed like the `reveal` op, when it is
-		 * added. Key a node by what it points at to reveal it again on a move.
+		 * Scroll the node into view, placed like the `reveal` op. A placement
+		 * reveals it when it is added: key a node by what it points at to
+		 * reveal it again on a move. A {@link NativeReveal} reveals it whenever
+		 * its `n` differs from the previous description of the same node.
 		 */
-		readonly reveal?: "start" | "end" | "nearest";
+		readonly reveal?: NativeRevealAt | NativeReveal;
 		/**
 		 * Keyboard scrolling forwarded to the terminal (PgUp/PgDn/End reach the
 		 * program): moves the scroller at or above the node by `by` whenever
@@ -44,6 +47,19 @@ export type NativeNode = {
 	};
 }[TspKind];
 
+/** Where a revealed node lands in its scroller. */
+export type NativeRevealAt = "start" | "end" | "nearest";
+
+/**
+ * A repeatable {@link NativeNode.reveal}: bump `n` to bring an existing node
+ * into view again (a Contents entry jumping to its section). A freshly added
+ * node is not revealed.
+ */
+export interface NativeReveal {
+	readonly at: NativeRevealAt;
+	readonly n: number;
+}
+
 /** A {@link NativeNode.scroll} request. */
 export interface NativeScroll {
 	readonly by: TspScrollBy;
@@ -61,6 +77,12 @@ export interface DescribeContext {
 	readonly reduceMotion: boolean;
 	/** The terminal's appearance is dark. */
 	readonly dark: boolean;
+	/**
+	 * The user's system reads a 12-hour clock (`false`: 24-hour); `undefined`
+	 * when the terminal doesn't say. Pass it as `hour12` when formatting times:
+	 * the process's own default locale may not know.
+	 */
+	readonly hour12?: boolean;
 	/** Whether the terminal renders `kind` natively (else describe something simpler or let it fall back). */
 	supports(kind: TspKind): boolean;
 	/**
@@ -113,7 +135,11 @@ export type NativeUiEvent =
 			readonly value: boolean | number | string | readonly string[] | null;
 	  }
 	/** An edit over the terminal's own selection in an `editor`/`input` node (see {@link NativeTextEdit}). */
-	| ({ readonly type: "edit"; readonly key: string } & NativeTextEdit);
+	| ({ readonly type: "edit"; readonly key: string } & NativeTextEdit)
+	/** Undo the last change to an `editor`/`input` node's text (the terminal's ⌃Z); a no-op with no history. */
+	| { readonly type: "undo"; readonly key: string }
+	/** Submit an explicit prompt through the composer's normal path, preserving the previous draft for recall. */
+	| { readonly type: "send"; readonly key: string; readonly text: string };
 
 /**
  * A primitive edit the terminal made over its own text selection (cut,

package/src/native/overlay.d.ts

@@ -7,7 +7,7 @@
  * component's root is a `card` whose `head` carries the title.
  */
 import type { TspProps, TspSpan, TspText } from "@linxiraos/pi-wire";
-import type { KeyName } from "../key-hint-format";
+import { type KeyName } from "../key-hint-format";
 import { type Keybinding } from "../keybindings";
 import type { NativeChild, NativeNode } from "./node";
 /** One footer hint: the keys that trigger it and what it does. */
@@ -44,10 +44,10 @@ export interface ActionButtonOptions {
     /** Sibling identity key (defaults to the action id); `leafKey(event.key)` reports it back. */
     readonly key?: string;
     /** Key id of the keyboard path the button mirrors, drawn as a keycap inside it (`"r"`, `"ctrl+g"`). */
-    readonly keys?: string;
+    readonly keys?: KeyName;
     /** `accent` = the view's hero action, `error` = destructive. */
     readonly tone?: "accent" | "error";
-    /** Tooltip; defaults to the label plus the keycap (`"Refresh  r"`). */
+    /** Tooltip; defaults to the label plus the keycap (`"Refresh  r"`, see {@link formatTooltipKey}). */
     readonly title?: string;
     /** Target of an `open` action (URL or `file://` path). */
     readonly href?: string;
@@ -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

@@ -7,7 +7,7 @@
  * component's root is a `card` whose `head` carries the title.
  */
 import type { TspProps, TspSpan, TspText } from "@linxiraos/pi-wire";
-import type { KeyName } from "../key-hint-format";
+import { formatTooltipKey, type KeyName } from "../key-hint-format";
 import { getKeybindings, type Keybinding } from "../keybindings";
 import { card, kbd, list, node, row, span, text } from "./describe";
 import type { NativeChild, NativeNode } from "./node";
@@ -86,10 +86,10 @@ export interface ActionButtonOptions {
 	/** Sibling identity key (defaults to the action id); `leafKey(event.key)` reports it back. */
 	readonly key?: string;
 	/** Key id of the keyboard path the button mirrors, drawn as a keycap inside it (`"r"`, `"ctrl+g"`). */
-	readonly keys?: string;
+	readonly keys?: KeyName;
 	/** `accent` = the view's hero action, `error` = destructive. */
 	readonly tone?: "accent" | "error";
-	/** Tooltip; defaults to the label plus the keycap (`"Refresh  r"`). */
+	/** Tooltip; defaults to the label plus the keycap (`"Refresh  r"`, see {@link formatTooltipKey}). */
 	readonly title?: string;
 	/** Target of an `open` action (URL or `file://` path). */
 	readonly href?: string;
@@ -110,7 +110,7 @@ export function actionButton(label: string, act: string, options: ActionButtonOp
 			gap: "xs",
 			align: "center",
 			actions: { click: act },
-			title: options.title ?? (options.keys ? `${label}  ${options.keys}` : label),
+			title: options.title ?? (options.keys ? `${label}  ${formatTooltipKey(options.keys)}` : label),
 			...(options.tone ? { tone: options.tone } : {}),
 			...(options.href ? { href: options.href } : {}),
 		},
@@ -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,8 +30,9 @@
 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 } from "./node";
+import type { DescribeContext, NativeChild, NativeNode, NativeRevealAt } from "./node";
 import { isNativeSettled } from "./settle";
 
 /** The regions a frame fills. */
@@ -213,8 +214,11 @@ export class Reconciler {
 	#ops: TspOp[] = [];
 	#dels: Entry[] = [];
 	#settles: string[] = [];
-	/** Selected list items and added `reveal` nodes sent this frame, revealed once the frame's adds have landed. */
-	#reveals: [id: string, at: "start" | "end" | "nearest"][] = [];
+	/**
+	 * Selected list items, added `reveal` nodes and nodes whose reveal `n` moved this frame,
+	 * revealed once the frame's adds have landed.
+	 */
+	#reveals: [id: string, at: NativeRevealAt][] = [];
 	/** `scroll` requests whose `n` moved this frame, sent after the reveals. */
 	#scrolls: [id: string, by: TspScrollBy][] = [];
 	/** Wire ids `list.selected` keys resolved to (an unresolved key names no node to reveal). */
@@ -288,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;
@@ -595,6 +600,11 @@ export class Reconciler {
 			this.#revisitNode(next, inner);
 			return;
 		}
+		const reveal = next.node.reveal;
+		if (typeof reveal === "object") {
+			const was = old.node.reveal;
+			if (reveal.n !== (typeof was === "object" ? was.n : undefined)) this.#reveals.push([next.id, reveal.at]);
+		}
 		if (old.node.k !== next.node.k) {
 			this.#dropSubtree(old);
 			this.#ops.push(["del", next.id]);
@@ -703,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));
 	}
 
@@ -743,7 +755,7 @@ export class Reconciler {
 
 	/** A full wire subtree for an entry; nested components get states (or pending moves when mounted elsewhere). */
 	#materialize(entry: NodeEntry, walk: Walk): TspNode {
-		if (entry.node.reveal) this.#reveals.push([entry.id, entry.node.reveal]);
+		if (typeof entry.node.reveal === "string") this.#reveals.push([entry.id, entry.node.reveal]);
 		const entries = this.#entries(entry.node.c, entry.keypath, entry.owner, entry.hoist, walk);
 		const children: TspNode[] = [];
 		for (let i = 0; i < entries.length; i++) {

package/src/native/settle.d.ts

@@ -1,8 +1,9 @@
 /**
  * Settling: the frame provider marks finalized transcript blocks so the
- * native reconciler stops keeping their description (spec §12 "Settling and
- * program memory"). A settled block stays editable: a later change is sent as
- * targeted ops by id, followed by a fresh `settle` hint.
+ * native reconciler stops keeping their description (Tern SDK,
+ * `protocol/operations.md`, "Settling"). A settled block stays editable: a
+ * later change is sent as targeted ops by id, followed by a fresh `settle`
+ * hint.
  */
 import type { Component } from "../tui";
 /** Mark `component` (and everything it describes) as finalized. Idempotent; a no-op outside a TSP terminal. */

package/src/native/settle.ts

@@ -1,8 +1,9 @@
 /**
  * Settling: the frame provider marks finalized transcript blocks so the
- * native reconciler stops keeping their description (spec §12 "Settling and
- * program memory"). A settled block stays editable: a later change is sent as
- * targeted ops by id, followed by a fresh `settle` hint.
+ * native reconciler stops keeping their description (Tern SDK,
+ * `protocol/operations.md`, "Settling"). A settled block stays editable: a
+ * later change is sent as targeted ops by id, followed by a fresh `settle`
+ * hint.
  */
 import type { Component } from "../tui";
 

package/src/overlays/agent-hub-projection.d.ts

@@ -15,11 +15,12 @@ interface AgentTreeProjection<TRecord extends AgentRecordLike> {
 export declare const STATUS_ORDER: Record<AgentStatus, number>;
 /** Exact observer usage for one roster entry. */
 export declare function progressMetrics(observed: ObservableSession | undefined): AgentMetrics | undefined;
-/** Live session whose own messages back a row's metrics when no observer progress exists. */
+/** Live session used to cache a row's direct assistant usage, including with observer progress. */
 export declare function hubFallbackStatsSession<TRecord extends AgentRecordLike>(ref: TRecord, observed: ObservableSession | undefined): NonNullable<TRecord["session"]> | undefined;
 /**
- * One roster row's usage: live observer progress, then persisted history, then
- * the cached fallback read of a live session (populated by {@link aggregateMetrics}).
+ * Preserve progress/history for non-cost metrics, overlaying cumulative direct-session cost.
+ * Persisted `history.metrics.cost` is a leaf-scoped snapshot, so it never overrides live
+ * progress; only the cumulative direct-cost sources do.
  */
 export declare function hubRowMetrics<TRecord extends AgentRecordLike>(ref: TRecord, observed: ObservableSession | undefined, sessionMetrics: WeakMap<object, {
     metrics: AgentMetrics | undefined;
@@ -37,6 +38,6 @@ export declare function aggregateMetrics<TRecord extends AgentRecordLike>(args:
     metrics: AggregateMetrics;
     hasFallbackLiveSessions: boolean;
 };
-/** Parent-before-child projection preserving the roster's stable sibling order. */
-export declare function projectAgentTree<TRecord extends AgentRecordLike>(refs: readonly TRecord[]): AgentTreeProjection<TRecord>;
+/** Parent-before-child projection preserving initial subtree rank and prepending new siblings. */
+export declare function projectAgentTree<TRecord extends AgentRecordLike>(refs: readonly TRecord[], rosterRank: ReadonlyMap<TRecord, number> | undefined): AgentTreeProjection<TRecord>;
 export {};