@linxiraos/pi-tui 1.2.1 → 1.3.1

package/src/debug-server.d.ts

@@ -22,6 +22,8 @@ export interface TuiDebugTree {
 export declare class TuiDebugServer {
     #private;
     constructor(tui: TUI, path: string);
+    /** Resolves true once the socket accepts connections, false if listen failed or the server stopped first. */
+    get ready(): Promise<boolean>;
     start(): void;
     stop(): void;
 }

package/src/debug-server.ts

@@ -1,5 +1,4 @@
-import { existsSync, unlinkSync } from "node:fs";
-import { createServer, type Server, type Socket } from "node:net";
+import { type IpcConnection, IpcServer } from "@linxiraos/pi-natives";
 import { type Component, isFocusable, type OverlayOptions, type TUI } from "./tui";
 import { plainText } from "./native/spans";
 
@@ -209,72 +208,60 @@ function mouseSequence(x: number, y: number, action: string): string {
 export class TuiDebugServer {
 	readonly #tui: TUI;
 	readonly #path: string;
-	#server: Server | undefined;
-	#sockets = new Set<Socket>();
+	#server: IpcServer | undefined;
+	#listening: Promise<boolean> | undefined;
+	#stopped = false;
+	#connections = new Set<IpcConnection>();
 
 	constructor(tui: TUI, path: string) {
 		this.#tui = tui;
 		this.#path = path;
 	}
 
+	/** Resolves true once the socket accepts connections, false if listen failed or the server stopped first. */
+	get ready(): Promise<boolean> {
+		return this.#listening ?? Promise.resolve(false);
+	}
+
 	start(): void {
-		if (this.#server !== undefined) return;
-		try {
-			if (existsSync(this.#path)) unlinkSync(this.#path);
-		} catch {
-			// The listen error below is isolated from the host application.
-		}
-		const server = createServer(socket => this.#accept(socket));
-		this.#server = server;
-		server.on("error", error => {
-			void error;
-		});
-		try {
-			server.listen(this.#path);
-		} catch {
-			this.#server = undefined;
-			server.close();
-		}
+		if (this.#listening !== undefined) return;
+		this.#stopped = false;
+		this.#listening = IpcServer.listen(this.#path, { framing: "lines" }, connection => this.#accept(connection)).then(
+			server => {
+				if (this.#stopped) {
+					void server.close().catch(() => {});
+					return false;
+				}
+				this.#server = server;
+				return true;
+			},
+			() => false, // A live peer or unusable path disables the debug socket; the host application is unaffected.
+		);
 	}
 
 	stop(): void {
+		this.#stopped = true;
 		const server = this.#server;
 		this.#server = undefined;
-		for (const socket of this.#sockets) socket.destroy();
-		this.#sockets.clear();
-		try {
-			server?.close();
-		} catch {
-			// A failed or already-closed listener still needs its stale path removed.
-		}
-		try {
-			if (existsSync(this.#path)) unlinkSync(this.#path);
-		} catch {
-			// Teardown must not affect the host application.
-		}
+		this.#listening = undefined;
+		for (const connection of this.#connections) connection.destroy();
+		this.#connections.clear();
+		void server?.close().catch(() => {});
 	}
 
-	#accept(socket: Socket): void {
-		this.#sockets.add(socket);
-		let buffer = "";
-		socket.setEncoding("utf8");
-		socket.on("data", chunk => {
-			buffer += chunk;
-			let newline = buffer.indexOf("\n");
-			while (newline !== -1) {
-				const line = buffer.slice(0, newline).replace(/\r$/, "");
-				buffer = buffer.slice(newline + 1);
-				if (line.length > 0) this.#handleLine(socket, line);
-				newline = buffer.indexOf("\n");
-			}
-		});
-		socket.on("error", error => {
-			void error;
-		});
-		socket.on("close", () => this.#sockets.delete(socket));
+	#accept(connection: IpcConnection): void {
+		if (this.#stopped) {
+			connection.destroy();
+			return;
+		}
+		this.#connections.add(connection);
+		connection.start(
+			line => void this.#handleLine(connection, line),
+			() => this.#connections.delete(connection),
+		);
 	}
 
-	#handleLine(socket: Socket, line: string): void {
+	async #handleLine(connection: IpcConnection, line: string): Promise<void> {
 		let request: DebugRequest;
 		try {
 			const parsed: unknown = JSON.parse(line);
@@ -282,36 +269,31 @@ export class TuiDebugServer {
 				throw new Error("request must be an object");
 			request = parsed as DebugRequest;
 		} catch (error) {
-			this.#write(socket, { ok: false, error: `malformed JSON: ${errorMessage(error)}` });
+			this.#write(connection, { ok: false, error: `malformed JSON: ${errorMessage(error)}` });
 			return;
 		}
+		let response: DebugResponse;
 		try {
-			const response = this.#dispatch(request);
-			if (request.op === "quit" && response.ok) {
-				this.#write(socket, response, () => {
-					this.#tui.stop();
-					process.exit(0);
-				});
-				return;
-			}
-			this.#write(socket, response);
+			response = this.#dispatch(request);
 		} catch (error) {
-			this.#write(socket, { ok: false, error: errorMessage(error) });
+			response = { ok: false, error: errorMessage(error) };
+		}
+		this.#write(connection, response);
+		if (request.op === "quit" && response.ok) {
+			await connection.drained();
+			this.#tui.stop();
+			process.exit(0);
 		}
 	}
 
-	#write(socket: Socket, response: DebugResponse, flushed?: () => void): void {
+	#write(connection: IpcConnection, response: DebugResponse): void {
 		let line: string;
 		try {
 			line = JSON.stringify(response);
 		} catch (error) {
 			line = JSON.stringify({ ok: false, error: errorMessage(error) });
 		}
-		try {
-			socket.write(`${line}\n`, flushed);
-		} catch {
-			// Broken clients cannot affect the TUI.
-		}
+		connection.send(line);
 	}
 
 	#dispatch(request: DebugRequest): DebugResponse {

package/src/hotkeys-markdown.ts

@@ -135,6 +135,8 @@ function hotkeyGroups(bindings: HotkeysMarkdownBindings): HotkeyGroup[] {
 				{ keys: [act("app.history.search")], action: "Search prompt history" },
 				{ keys: [act("app.tools.expand")], action: "Toggle tool output expansion" },
 				{ keys: [act("app.tools.toggleVisibility")], action: "Toggle tool activity visibility" },
+				{ keys: [act("app.ask.hide")], action: "Hide/show a pending ask question" },
+				{ keys: [act("app.approval.approve")], action: "Approve a pending tool call" },
 				{ keys: [act("app.thinking.toggle")], action: "Toggle thinking block visibility" },
 				{ keys: [act("app.editor.external")], action: "Edit message in external editor" },
 				{ keys: [act("app.retry")], action: "Retry last failed assistant turn" },

package/src/keybinding-matchers.d.ts

@@ -9,6 +9,8 @@ import type { KeyId } from "./app-keybindings";
 export declare function matchesAppInterrupt(data: string): boolean;
 /** Match `app.tools.expand`, falling back to Ctrl+O when the action is unbound. */
 export declare function matchesAppToolsExpand(data: string): boolean;
+/** Effective tools-expand key: the first bound key, or Ctrl+O when unbound. */
+export declare function appToolsExpandKey(): KeyId;
 /** Match the generic selector cancel keybinding. */
 export declare function matchesSelectCancel(data: string): boolean;
 /** Match the generic selector up-navigation keybinding. */
@@ -36,3 +38,7 @@ export declare function matchesAppExternalEditor(data: string): boolean;
  * effective follow-up binding.
  */
 export declare function matchesAppFollowUp(data: string): boolean;
+/** Effective tool-approval keys: the `app.approval.approve` bindings, or Ctrl+Enter/Ctrl+Q when unbound. */
+export declare function appApproveKeys(): readonly KeyId[];
+/** Match the tool-approval key, recognizing modifier-tagged LF as Ctrl+Enter like {@link matchesAppFollowUp}. */
+export declare function matchesAppApprove(data: string): boolean;

package/src/keybinding-matchers.ts

@@ -28,6 +28,11 @@ export function matchesAppToolsExpand(data: string): boolean {
 	return matchesKey(data, "ctrl+o");
 }
 
+/** Effective tools-expand key: the first bound key, or Ctrl+O when unbound. */
+export function appToolsExpandKey(): KeyId {
+	return getKeybindings().getKeys("app.tools.expand")[0] ?? "ctrl+o";
+}
+
 /** Match the generic selector cancel keybinding. */
 export function matchesSelectCancel(data: string): boolean {
 	return getKeybindings().matches(data, "tui.select.cancel");
@@ -101,3 +106,17 @@ export function matchesAppFollowUp(data: string): boolean {
 	}
 	return matchesEffectiveKeys(data, ["ctrl+enter", "ctrl+q"]);
 }
+
+/** Approve-key defaults when `app.approval.approve` is unbound: approval must stay reachable by keyboard. */
+const APPROVE_DEFAULT_KEYS: readonly KeyId[] = ["ctrl+enter", "ctrl+q"];
+
+/** Effective tool-approval keys: the `app.approval.approve` bindings, or Ctrl+Enter/Ctrl+Q when unbound. */
+export function appApproveKeys(): readonly KeyId[] {
+	const keys = getKeybindings().getKeys("app.approval.approve");
+	return keys.length > 0 ? keys : APPROVE_DEFAULT_KEYS;
+}
+
+/** Match the tool-approval key, recognizing modifier-tagged LF as Ctrl+Enter like {@link matchesAppFollowUp}. */
+export function matchesAppApprove(data: string): boolean {
+	return matchesEffectiveKeys(data, appApproveKeys());
+}

package/src/multiplexers/tmux.d.ts

@@ -22,6 +22,7 @@ export declare const tmuxMultiplexer: {
         readonly passthrough: typeof wrapTmuxPassthrough;
         readonly settleMs: 100;
     };
+    readonly gatesBracketedPaste: true;
     readonly expandsRepPadding: true;
     readonly expiresSynchronizedOutput: true;
     readonly altRestoreEndsSynchronizedOutput: true;

package/src/multiplexers/tmux.ts

@@ -32,6 +32,9 @@ export const tmuxMultiplexer = {
 	// An explicit appearance refresh passes OSC 11 to the outer terminal, then
 	// re-reads tmux's cache once it has consumed the reply.
 	backgroundColorCache: { passthrough: wrapTmuxPassthrough, settleMs: 100 },
+	// tmux drops paste markers for a pane whose own DEC 2004 flag another
+	// writer cleared, and only answers DECRQM 2004 since 3.6.
+	gatesBracketedPaste: true,
 	expandsRepPadding: true,
 	// tmux expires synchronized output after one second.
 	expiresSynchronizedOutput: true,

package/src/multiplexers/types.d.ts

@@ -73,6 +73,12 @@ export interface TerminalMultiplexerModule<Id extends string = string> {
      * session, and an unrecognized report does not turn it off.
      */
     readonly honorsSynchronizedOutput?: boolean;
+    /**
+     * Tracks DEC 2004 per pane and forwards paste markers only while it is set,
+     * yet may leave DECRQM 2004 unanswered, so bracketed paste is reasserted
+     * without waiting for a DECRPM confirmation.
+     */
+    readonly gatesBracketedPaste?: boolean;
     /**
      * The session does not reveal whether its client renders graphics while
      * outer-terminal identity variables leak in, so images and Kitty

package/src/multiplexers/types.ts

@@ -83,6 +83,12 @@ export interface TerminalMultiplexerModule<Id extends string = string> {
 	 * session, and an unrecognized report does not turn it off.
 	 */
 	readonly honorsSynchronizedOutput?: boolean;
+	/**
+	 * Tracks DEC 2004 per pane and forwards paste markers only while it is set,
+	 * yet may leave DECRQM 2004 unanswered, so bracketed paste is reasserted
+	 * without waiting for a DECRPM confirmation.
+	 */
+	readonly gatesBracketedPaste?: boolean;
 	/**
 	 * The session does not reveal whether its client renders graphics while
 	 * outer-terminal identity variables leak in, so images and Kitty

package/src/native/backend.d.ts

@@ -47,10 +47,11 @@ 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 omp
- * already detected, full motion, and `blobs`, so a resumed session's images
- * are asked about rather than resent before the reply comes.
+ * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary except
+ * {@link UNASSUMED_KINDS}, the 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

@@ -202,12 +202,20 @@ function sameSet(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
 	return true;
 }
 
+/**
+ * Kinds newer than some Tern builds that answer `TERM_PROGRAM=tern`: used only
+ * once the real `hello` lists them, so the optimistic start never emits a node
+ * an older terminal cannot draw (`media`: files Tern loads by path).
+ */
+const UNASSUMED_KINDS: Partial<Record<TspKind, true>> = { media: true };
+
 /**
  * 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 omp
- * already detected, full motion, and `blobs`, so a resumed session's images
- * are asked about rather than resent before the reply comes.
+ * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary except
+ * {@link UNASSUMED_KINDS}, the 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;
@@ -215,7 +223,7 @@ export function assumedTspHello(terminal: Terminal): TspHello {
 		r: "hello",
 		v: TSP_VERSION,
 		term: "tern",
-		kinds: TSP_KINDS,
+		kinds: TSP_KINDS.filter(kind => !UNASSUMED_KINDS[kind]),
 		features: ["blobs"],
 		apc: TSP_DEFAULT_APC_LIMIT,
 		credits: TSP_DEFAULT_CREDITS,

package/src/native/blobs.d.ts

@@ -1,14 +1,5 @@
-/**
- * Content-addressed binary blobs (images) for `image` nodes.
- *
- * `describe()` registers the bytes and puts the returned id in `image.p.blob`;
- * 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";
+import type { NativeChild, NativeNode } from "./node";
 export interface NativeBlob {
     readonly id: string;
     readonly mime: string;
@@ -26,8 +17,29 @@ export declare function nativeImageNode(bytes: Uint8Array, mime: string, p?: Omi
  * so callers cache the node per payload ({@link NativeImageCache}).
  */
 export declare function base64ImageNode(data: string, mimeType: string, p?: Omit<TspProps<"image">, "blob" | "builtin" | "w" | "h">, key?: string): NativeNode;
-/** `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload changes. */
+/**
+ * Props that make an `image` node open the file at `filePath` (as a `file://` URL, the TSP
+ * open-target form): a click zooms the image in the terminal, and the file opens from its
+ * context menu. Empty without a file.
+ */
+export declare function openableImageProps(filePath: string | undefined): Pick<TspProps<"image">, "href" | "actions">;
+/**
+ * `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload
+ * or the link policy changes. Each opens its file (`sourcePath`, else a blob copy).
+ */
 export declare class NativeImageCache {
     #private;
-    get(key: string, data: string, mimeType: string): NativeNode;
+    get(key: string, data: string, mimeType: string, sourcePath?: string): NativeNode;
 }
+/** The disk file a tool result's image was read from (`read` details `mediaPath`), when it has one. */
+export declare function readMediaPath(details: unknown): string | undefined;
+/**
+ * A `media` node the host loads by path, capped at the inline image preview
+ * height. Callers check `cx.supports("media")` first.
+ */
+export declare function nativeMediaNode(path: string, key: string): NativeNode;
+/** Blob ids of the `image` nodes and paths of the `media` nodes under `children` (described nodes only). */
+export declare function shownMedia(children: readonly NativeChild[] | undefined): {
+    blobs: Set<string>;
+    paths: Set<string>;
+};

package/src/native/blobs.ts

@@ -7,10 +7,13 @@
  * cache), else uploads it with verb `b` before the frame that first
  * references it.
  */
+import * as url from "node:url";
 import type { TspProps } from "@linxiraos/pi-wire";
+import { resolveImageOptions } from "../render/render-utils";
 import { getImageDimensions } from "../terminal-capabilities";
 import { node } from "./describe";
-import type { NativeNode } from "./node";
+import { imageLinksEnabled, transcriptImageLink } from "../prompt/image-references";
+import type { NativeChild, NativeNode } from "./node";
 
 export interface NativeBlob {
 	readonly id: string;
@@ -91,15 +94,61 @@ export function base64ImageNode(
 	);
 }
 
-/** `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload changes. */
+/**
+ * Props that make an `image` node open the file at `filePath` (as a `file://` URL, the TSP
+ * open-target form): a click zooms the image in the terminal, and the file opens from its
+ * context menu. Empty without a file.
+ */
+export function openableImageProps(filePath: string | undefined): Pick<TspProps<"image">, "href" | "actions"> {
+	return filePath ? { href: url.pathToFileURL(filePath).href, actions: { menu: ["open"] } } : {};
+}
+
+/**
+ * `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload
+ * or the link policy changes. Each opens its file (`sourcePath`, else a blob copy).
+ */
 export class NativeImageCache {
-	#entries = new Map<string, { data: string; node: NativeNode }>();
+	#entries = new Map<string, { data: string; linked: boolean; node: NativeNode }>();
 
-	get(key: string, data: string, mimeType: string): NativeNode {
+	get(key: string, data: string, mimeType: string, sourcePath?: string): NativeNode {
+		const linked = imageLinksEnabled();
 		const cached = this.#entries.get(key);
-		if (cached?.data === data) return cached.node;
-		const image = base64ImageNode(data, mimeType, { alt: mimeType }, key);
-		this.#entries.set(key, { data, node: image });
+		if (cached?.data === data && cached.linked === linked) return cached.node;
+		const open = openableImageProps(transcriptImageLink({ data, mimeType }, sourcePath));
+		const image = base64ImageNode(data, mimeType, { alt: mimeType, ...open }, key);
+		this.#entries.set(key, { data, linked, node: image });
 		return image;
 	}
 }
+
+/** The disk file a tool result's image was read from (`read` details `mediaPath`), when it has one. */
+export function readMediaPath(details: unknown): string | undefined {
+	if (typeof details !== "object" || details === null) return undefined;
+	const mediaPath = (details as { mediaPath?: unknown }).mediaPath;
+	return typeof mediaPath === "string" && mediaPath.length > 0 ? mediaPath : undefined;
+}
+
+/**
+ * A `media` node the host loads by path, capped at the inline image preview
+ * height. Callers check `cx.supports("media")` first.
+ */
+export function nativeMediaNode(path: string, key: string): NativeNode {
+	const maxRows = resolveImageOptions().maxHeightCells;
+	return node("media", { path, max: maxRows && maxRows > 0 ? { h: `${maxRows}lines` } : undefined }, undefined, key);
+}
+
+/** Blob ids of the `image` nodes and paths of the `media` nodes under `children` (described nodes only). */
+export function shownMedia(children: readonly NativeChild[] | undefined): { blobs: Set<string>; paths: Set<string> } {
+	const shown = { blobs: new Set<string>(), paths: new Set<string>() };
+	const visit = (list: readonly NativeChild[] | undefined): void => {
+		for (const child of list ?? []) {
+			if (!("k" in child)) continue;
+			const p = child.p as { blob?: unknown; path?: unknown } | undefined;
+			if (child.k === "image" && typeof p?.blob === "string") shown.blobs.add(p.blob);
+			else if (child.k === "media" && typeof p?.path === "string") shown.paths.add(p.path);
+			visit(child.c);
+		}
+	};
+	visit(children);
+	return shown;
+}

package/src/native/reconcile.ts

@@ -405,13 +405,31 @@ export class Reconciler {
 		return this.#findEditorIn(node, state.id, "", state.owner, depth);
 	}
 
-	#findEditorIn(node: NativeNode, id: string, keypath: string, owner: Owner, depth: number): string | null {
+	/**
+	 * The first editor under `node`. An `overlay`/`picker` child outside a hoisted
+	 * sheet is hoisted into `layer` under its `^` keypath (see {@link #entries}), so
+	 * a field in a sheet a dock component describes is found under that id.
+	 */
+	#findEditorIn(
+		node: NativeNode,
+		id: string,
+		keypath: string,
+		owner: Owner,
+		depth: number,
+		hoist = true,
+	): string | null {
 		if (node.k === "editor" || node.k === "input") return id;
-		for (const entry of this.#entries(node.c, keypath, owner, true, null)) {
-			const found =
-				entry.comp === undefined
-					? this.#findEditorIn(entry.node, entry.id, entry.keypath, owner, depth)
-					: this.#findEditorOf(entry.comp, depth + 1);
+		for (const entry of this.#entries(node.c, keypath, owner, false, null)) {
+			let found: string | null;
+			if (entry.comp !== undefined) {
+				found = this.#findEditorOf(entry.comp, depth + 1);
+			} else if (hoist && (entry.node.k === "overlay" || entry.node.k === "picker")) {
+				const path = entry.keypath;
+				const portalPath = keypath === "" ? `^${path}` : `${keypath}/^${path.slice(keypath.length + 1)}`;
+				found = this.#findEditorIn(entry.node, nodeId(owner.base, portalPath), portalPath, owner, depth, false);
+			} else {
+				found = this.#findEditorIn(entry.node, entry.id, entry.keypath, owner, depth, hoist);
+			}
 			if (found !== null) return found;
 		}
 		return null;
@@ -682,24 +700,28 @@ export class Reconciler {
 			this.#ops.push(["text", id, "append", newText.slice(oldText.length)]);
 			return;
 		}
-		if ((kind === "editor" || kind === "input") && oldText.length > 0) {
+		// A streaming `md` node rewrites only its tail (the speculatively closed span it ends in), so an
+		// edit past a shared head splices too instead of resending the whole text.
+		if ((kind === "editor" || kind === "input" || kind === "md") && oldText.length > 0) {
 			const limit = Math.min(oldText.length, newText.length);
 			let prefix = 0;
 			while (prefix < limit && oldText.charCodeAt(prefix) === newText.charCodeAt(prefix)) prefix++;
-			let suffix = 0;
-			while (
-				suffix < limit - prefix &&
-				oldText.charCodeAt(oldText.length - 1 - suffix) === newText.charCodeAt(newText.length - 1 - suffix)
-			)
-				suffix++;
-			this.#ops.push([
-				"splice",
-				id,
-				prefix,
-				oldText.length - prefix - suffix,
-				newText.slice(prefix, newText.length - suffix),
-			]);
-			return;
+			if (kind !== "md" || prefix > 0) {
+				let suffix = 0;
+				while (
+					suffix < limit - prefix &&
+					oldText.charCodeAt(oldText.length - 1 - suffix) === newText.charCodeAt(newText.length - 1 - suffix)
+				)
+					suffix++;
+				this.#ops.push([
+					"splice",
+					id,
+					prefix,
+					oldText.length - prefix - suffix,
+					newText.slice(prefix, newText.length - suffix),
+				]);
+				return;
+			}
 		}
 		this.#ops.push(["text", id, "replace", newText]);
 	}