@linxiraos/pi-tui 1.1.27 → 1.2.0

package/src/chat/user-message.ts

@@ -1,4 +1,5 @@
-import { applyBackgroundToLine, padding, visibleWidth } from "../utils";
+import { applyBackgroundToLine, padding, stripTerminalSequences, visibleWidth } from "../utils";
+import type { AnimationFrame, TranscriptPresentationTarget } from "../chrome/transcript-container";
 import { type Component, Container } from "../tui";
 import { Disclosure } from "../components/disclosure";
 import { Markdown } from "../components/markdown";
@@ -57,7 +58,7 @@ const OSC133_ZONE_CLOSE = OSC133_ZONE_END + OSC133_COMMAND_START + OSC133_COMMAN
 
 /** How a user bubble styles its prose and chips (see {@link userBubbleColor}). */
 export interface UserBubbleOptions {
-	/** Materialized `file://` targets per attached image, indexed by chip number. */
+	/** Filesystem paths for attached image chips, indexed by chip number. */
 	imageLinks?: readonly (string | undefined)[];
 	/** The message's attached images in chip order (`#1` first); a native bubble shows them. */
 	images?: readonly ImageContent[];
@@ -124,7 +125,8 @@ export function userBubbleColor(
  * (see {@link ReactionTarget}) drawn right-aligned in the bubble's top padding row;
  * a live-steered message carries a `*` marker left-aligned in the same row.
  */
-export class UserMessageComponent extends Container implements ReactionTarget {
+export class UserMessageComponent extends Container implements ReactionTarget, TranscriptPresentationTarget {
+	#allocation = Number.POSITIVE_INFINITY;
 	// Memoized OSC 133 zone wrapping keyed on the underlying container render
 	// (same source ref ⇒ identical rows ⇒ reuse the wrapped copy). Keeps this
 	// component reference-stable for the transcript's incremental assembly and
@@ -177,6 +179,12 @@ export class UserMessageComponent extends Container implements ReactionTarget {
 		this.addChild(markdown);
 	}
 
+	override releaseRenderCaches(): void {
+		this.#zoneSource = undefined;
+		this.#zoneLines = undefined;
+		super.releaseRenderCaches();
+	}
+
 	setReaction(emoji: string): void {
 		if (this.#reaction === emoji) return;
 		this.#reaction = emoji;
@@ -281,11 +289,47 @@ export class UserMessageComponent extends Container implements ReactionTarget {
 		return applyBackgroundToLine(` ${marker}${padding(gap)}${emoji}`, width, this.#bgColor);
 	}
 
+	/** Apply the transcript allocator's current viewport reservation. */
+	setTranscriptAllocation(rows: number, _frame?: AnimationFrame): void {
+		this.#allocation = Math.max(0, Math.trunc(rows));
+	}
+
+	isTranscriptBlockFinalized(): boolean {
+		return true;
+	}
+
+	/**
+	 * Single-row emergency representation for the overflow transcript layout:
+	 * renders the first content line instead of the blank top padding row, and
+	 * omits OSC 133 shell integration markers so moving live blocks across the
+	 * viewport does not leave stale prompt marks on lines it no longer occupies.
+	 */
+	renderTranscriptBlockEmergencyRow(width: number): string | undefined {
+		return this.#selectEmergencyRow(super.render(width));
+	}
+
+	#selectEmergencyRow(lines: readonly string[]): string | undefined {
+		if (lines.length === 0) return undefined;
+		if (lines.length >= 3) {
+			for (let i = 1; i < lines.length - 1; i++) {
+				if (stripTerminalSequences(lines[i]!).trim().length > 0) {
+					return lines[i];
+				}
+			}
+			return lines[1];
+		}
+		return lines[0];
+	}
+
 	override render(width: number): readonly string[] {
 		const lines = super.render(width);
 		if (lines.length === 0) {
 			return lines;
 		}
+		if (this.#allocation === 1) {
+			const emergency = this.#selectEmergencyRow(lines);
+			if (emergency !== undefined) return [emergency];
+		}
 		if (this.#zoneSource === lines && this.#zoneLines !== undefined) {
 			return this.#zoneLines;
 		}
@@ -337,6 +381,10 @@ class SyntheticSummary implements Component {
 		this.#summary = summary;
 	}
 
+	releaseRenderCaches(): void {
+		this.#cache = undefined;
+	}
+
 	invalidate(): void {
 		this.#cache = undefined;
 	}
@@ -425,6 +473,10 @@ export class CollapsedSyntheticMessageComponent implements Component {
 		this.#disclosure.invalidate();
 	}
 
+	releaseRenderCaches(): void {
+		this.#disclosure.releaseRenderCaches();
+	}
+
 	dispose(): void {
 		this.#disclosure.dispose();
 	}

package/src/chrome/shared.ts

@@ -10,6 +10,59 @@ export function sanitizeStatusText(text: string): string {
 	return sanitizeDisplaySingleLine(text).replace(/ +/g, " ").trim();
 }
 
+/** 7-bit SGR (`ESC [ <params> m`) — the one escape family a hook status may keep. */
+const SGR_RE = /\x1b\[[0-9;:]*m/g;
+const SGR_RESET = "\x1b[0m";
+const WHITESPACE_RE = /\s/;
+
+/**
+ * Like {@link sanitizeStatusText}, but keeps 7-bit SGR so extensions can colour
+ * `ctx.ui.setStatus` text. Every other escape (OSC links/titles, DCS/PM/APC,
+ * 7- and 8-bit CSI), C0/C1, lone surrogates, newlines and tabs are sanitized at
+ * least as strictly as in `sanitizeStatusText`; space runs collapse and edges
+ * trim (`String#trim` whitespace) by visible text, regardless of SGR placement.
+ * A styled result always ends with `\x1b[0m`.
+ */
+export function sanitizeHookStatusText(input: string): string {
+	// Drop lone surrogates before splitting, as `sanitizeText` does, so stripped escapes
+	// cannot fuse surrogate halves from neighbouring chunks into a new character.
+	const wellFormed = input.toWellFormed();
+	const text = wellFormed === input ? input : wellFormed.replaceAll("\ufffd", "");
+	SGR_RE.lastIndex = 0;
+	if (!SGR_RE.test(text)) return sanitizeStatusText(text); // byte-identical for unstyled input
+	let out = "";
+	// SGR codes and whitespace seen since the last visible char, in source order.
+	let pending = "";
+	let lastWasSpace = false;
+	let hasVisible = false;
+	let cursor = 0;
+	SGR_RE.lastIndex = 0;
+	for (;;) {
+		const match = SGR_RE.exec(text);
+		// `sanitizeText` runs `Bun.stripANSI` only when an ESC is present; a chunk between SGR
+		// codes often has none, so strip explicitly to drop 8-bit (C1) sequence payloads.
+		const chunk = sanitizeDisplaySingleLine(Bun.stripANSI(text.slice(cursor, match ? match.index : text.length)));
+		for (const ch of chunk) {
+			if (WHITESPACE_RE.test(ch)) {
+				// Leading whitespace drops; ASCII space runs collapse even across SGR codes.
+				if (hasVisible && !(ch === " " && lastWasSpace)) pending += ch;
+				lastWasSpace = ch === " ";
+				continue;
+			}
+			out += pending + ch;
+			pending = "";
+			lastWasSpace = false;
+			hasVisible = true;
+		}
+		if (!match) break;
+		pending += match[0];
+		cursor = match.index + match[0].length;
+	}
+	if (!hasVisible) return "";
+	// Trailing whitespace trims; trailing SGR codes stay (they never contain whitespace).
+	return out + pending.replace(/\s+/g, "") + SGR_RESET;
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Tab Bar Theme
 // ═══════════════════════════════════════════════════════════════════════════

package/src/chrome/transcript-container.d.ts

@@ -63,6 +63,12 @@ export interface TranscriptViewportSpan {
 export declare class TranscriptContainer extends Container {
     #private;
     addChild(component: Component): void;
+    /**
+     * `#entries` mirrors `children`; move both together or the next `#syncEntries`
+     * pays a full O(n) rebuild.
+     */
+    insertChildAt(component: Component, index: number): void;
+    /** Removes `component` if {@link canRemoveBlock} allows it; otherwise does nothing. */
     removeChild(component: Component): void;
     clear(): void;
     setToolActivityVisible(visible: boolean): void;

package/src/chrome/transcript-container.ts

@@ -58,6 +58,12 @@ export interface AppendOnlyTranscriptBlock {
 
 interface FinalizableBlock {
 	isTranscriptBlockFinalized?(): boolean;
+	/**
+	 * A finalized block whose rows still wait on async work (an SVG figure's
+	 * raster). Retirement holds until it lands: committed rows can never be
+	 * repainted, so retiring early would freeze a placeholder into scrollback.
+	 */
+	isTranscriptBlockPending?(): boolean;
 	/** Render the row that must remain represented under emergency viewport pressure. */
 	renderTranscriptBlockEmergencyRow?(width: number): string | undefined;
 }
@@ -129,7 +135,7 @@ const EMPTY_STABLE_ROWS: readonly TranscriptStableRow[] = [];
 
 function isFinalized(component: Component): boolean {
 	const block = component as Component & FinalizableBlock;
-	return block.isTranscriptBlockFinalized?.() ?? true;
+	return (block.isTranscriptBlockFinalized?.() ?? true) && block.isTranscriptBlockPending?.() !== true;
 }
 
 function blockMode(component: Component): TranscriptBlockMode {
@@ -208,6 +214,7 @@ export class TranscriptContainer extends Container {
 	 */
 	#frameRows = new Map<TranscriptEntry, readonly string[]>();
 	#frameRowsWidth = 0;
+	#releaseFailures = new WeakSet<Component>();
 	/** The `children` array `#entries` last mirrored; see {@link #syncEntries}. */
 	#syncedChildren: Component[] | undefined;
 	/** Forces the next {@link #syncEntries} to compare every entry, not just the live tail. */
@@ -229,15 +236,40 @@ export class TranscriptContainer extends Container {
 			stableFrozen: false,
 			imageScan: undefined,
 		});
-		// Callers may splice a just-added block into place (insert after an
-		// anchor); re-check the whole list once instead of trusting positions.
+		// `children` is public and may be edited externally; re-check the whole
+		// list once instead of trusting positions. Insert-after-anchor callers
+		// use insertChildAt, which keeps both arrays in lockstep.
 		this.#entriesUnverified = true;
 	}
 
+	/**
+	 * `#entries` mirrors `children`; move both together or the next `#syncEntries`
+	 * pays a full O(n) rebuild.
+	 */
+	insertChildAt(component: Component, index: number): void {
+		this.addChild(component);
+		const from = this.children.length - 1;
+		if (index >= from) {
+			this.#entriesUnverified = false;
+			return;
+		}
+		const [moved] = this.children.splice(from, 1);
+		if (moved) this.children.splice(index, 0, moved);
+		const [entry] = this.#entries.splice(this.#entries.length - 1, 1);
+		if (entry) this.#entries.splice(index, 0, entry);
+		// Both arrays moved in lockstep, so the live-tail check applies again.
+		this.#entriesUnverified = false;
+	}
+
+	/** Removes `component` if {@link canRemoveBlock} allows it; otherwise does nothing. */
 	override removeChild(component: Component): void {
-		if (this.children.indexOf(component) < 0 || !this.canRemoveBlock(component)) return;
-		super.removeChild(component);
-		this.#entries = this.#entries.filter(candidate => candidate.component !== component);
+		const index = this.#removableIndex(component);
+		if (index < 0) return;
+		// #removableIndex synced entries, which now mirror children index for
+		// index. This class renders through its own entries, never Container's
+		// memoized render, so splicing children directly is the whole removal.
+		this.children.splice(index, 1);
+		this.#entries.splice(index, 1);
 		this.#frontier = Math.min(this.#frontier, this.#entries.length);
 		this.#childStartRows.delete(component);
 	}
@@ -292,14 +324,24 @@ export class TranscriptContainer extends Container {
 
 	/** Whether a transient block may be discarded without leaving tape history. */
 	canRemoveBlock(component: Component): boolean {
+		return this.#removableIndex(component) >= 0;
+	}
+
+	/**
+	 * Syncs entries, then returns `component`'s index if it can be discarded
+	 * without leaving tape history (not committed, not emitted, not in an
+	 * offered batch), else -1.
+	 */
+	#removableIndex(component: Component): number {
 		this.#syncEntries();
-		const index = this.#entries.findIndex(entry => entry.component === component);
-		if (index < 0) return false;
+		// Removable blocks are transient ones near the live tail, so search from there.
+		const index = this.#entries.findLastIndex(entry => entry.component === component);
+		if (index < 0) return -1;
 		const entry = this.#entries[index]!;
-		if (entry.state === "committed" || entry.emitted > 0) return false;
-		if (this.#offered?.kind === "commit" && index < this.#offered.end) return false;
-		if (this.#offered?.kind === "append" && index === this.#offered.entry) return false;
-		return true;
+		if (entry.state === "committed" || entry.emitted > 0) return -1;
+		if (this.#offered?.kind === "commit" && index < this.#offered.end) return -1;
+		if (this.#offered?.kind === "append" && index === this.#offered.entry) return -1;
+		return index;
 	}
 
 	/**
@@ -586,7 +628,10 @@ export class TranscriptContainer extends Container {
 			popLoopPhase();
 		}
 		this.#replayPending = false;
-		if (rows.length === 0) return undefined;
+		if (rows.length === 0) {
+			this.#releaseCommittedRenderCaches();
+			return undefined;
+		}
 		const batch: HistoryBatch = { id: this.#nextBatchId++, rows, kind: "replay" };
 		this.#offered = { batch, kind: "replay" };
 		return batch;
@@ -764,6 +809,8 @@ export class TranscriptContainer extends Container {
 				this.#retireEntry(this.#entries[index]!);
 			}
 			this.#frontier = offered.end;
+		} else {
+			this.#releaseCommittedRenderCaches();
 		}
 		this.#offered = undefined;
 		if (this.#replayRequested) this.#startReplay();
@@ -783,6 +830,7 @@ export class TranscriptContainer extends Container {
 			const entry = this.#entries[index]!;
 			this.#setAllocation(entry.component, Number.MAX_SAFE_INTEGER, this.#lastFrame);
 			const block = trimBlankEdges(entry.component.render(width));
+			if (entry.state === "committed") this.#releaseRenderCaches(entry);
 			if (block.length === 0) continue;
 			if (rows.length > 0) rows.unshift("");
 			rows.unshift(...block);
@@ -830,6 +878,7 @@ export class TranscriptContainer extends Container {
 		for (const entry of this.#entries) {
 			this.#setAllocation(entry.component, Number.MAX_SAFE_INTEGER, this.#lastFrame);
 			const block = this.#renderEntry(entry, width);
+			if (entry.state === "committed") this.#releaseRenderCaches(entry);
 			if (block.length === 0) continue;
 			if (rows.length > 0) rows.push("");
 			this.#childStartRows.set(entry.component, rows.length);
@@ -1071,6 +1120,29 @@ export class TranscriptContainer extends Container {
 		entry.stableRows = EMPTY_STABLE_ROWS;
 		entry.renderedStableByWidth = new Map();
 		entry.stableRowCountByWidth = new Map();
+		this.#frameRows.delete(entry);
+		this.#releaseRenderCaches(entry);
+	}
+
+	#releaseCommittedRenderCaches(): void {
+		for (let index = 0; index < this.#frontier; index++) {
+			this.#releaseRenderCaches(this.#entries[index]!);
+		}
+	}
+
+	#releaseRenderCaches(entry: TranscriptEntry): void {
+		const release = entry.component.releaseRenderCaches;
+		if (release === undefined) return;
+		try {
+			release.call(entry.component);
+		} catch (err) {
+			if (this.#releaseFailures.has(entry.component)) return;
+			this.#releaseFailures.add(entry.component);
+			logger.warn("Transcript block failed to release render caches", {
+				component: entry.component.constructor.name,
+				error: String(err),
+			});
+		}
 	}
 
 	#startReplay(): void {
@@ -1172,6 +1244,14 @@ export class TranscriptContainer extends Container {
 				continue;
 			}
 			this.#setAllocation(candidate.entry.component, 1, frame);
+			const emergency = (
+				candidate.entry.component as Component & FinalizableBlock
+			).renderTranscriptBlockEmergencyRow?.(width);
+			if (emergency !== undefined) {
+				output.push(emergency);
+				owners.push(candidate.entry.component);
+				continue;
+			}
 			const rendered = this.#renderEntry(candidate.entry, width).slice(
 				this.#projectedEmittedRowCount(candidate.entry, candidate.index, width),
 			);

package/src/components/box.d.ts

@@ -30,6 +30,7 @@ export declare class Box implements Component {
     setBgFn(bgFn?: (text: string) => string): void;
     setBorder(border?: BoxBorder): void;
     invalidate(): void;
+    releaseRenderCaches(): void;
     /**
      * A `card` when the box has a border or background: the background token
      * picks tone/role (user message, tool state, selection), a border colour

package/src/components/box.ts

@@ -135,6 +135,11 @@ export class Box implements Component {
 		}
 	}
 
+	releaseRenderCaches(): void {
+		this.#invalidateCache();
+		for (const child of this.children) child.releaseRenderCaches?.();
+	}
+
 	/**
 	 * A `card` when the box has a border or background: the background token
 	 * picks tone/role (user message, tool state, selection), a border colour

package/src/components/disclosure.d.ts

@@ -36,6 +36,7 @@ export declare class Disclosure implements Component {
     setExpanded(expanded: boolean): void;
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
+    releaseRenderCaches(): void;
     dispose(): void;
     debugState(): Record<string, unknown>;
     get debugChildren(): readonly Component[];

package/src/components/disclosure.ts

@@ -100,6 +100,14 @@ export class Disclosure implements Component {
 		this.#body?.invalidate?.();
 	}
 
+	releaseRenderCaches(): void {
+		this.#cache = undefined;
+		this.#boundedCache = undefined;
+		this.#summary?.releaseRenderCaches?.();
+		this.#collapsedBody?.releaseRenderCaches?.();
+		this.#body?.releaseRenderCaches?.();
+	}
+
 	dispose(): void {
 		if (this.#disposed) return;
 		this.#disposed = true;

package/src/components/editor.d.ts

@@ -1,5 +1,5 @@
 import { type AutocompleteProvider } from "../autocomplete";
-import type { TspEditorDecoration, TspTone } from "@linxiraos/pi-wire";
+import type { TspEditorDecoration, TspText, TspTone } from "@linxiraos/pi-wire";
 import { type DescribeContext, type NativeChild, type NativeNode, type NativeTextEdit, type NativeUiEvent } from "../native/node";
 import type { SymbolTheme } from "../symbols";
 import { type Component, type Focusable } from "../tui";
@@ -106,8 +106,11 @@ export declare class Editor implements Component, Focusable {
      * dialog's text field; only the prompt composer claims `zeta.editor`).
      */
     describeLayout: ((input: NativeNode, cx: DescribeContext) => NativeEditorLayout) | undefined;
-    /** TSP placeholder for the empty buffer; natively it replaces the rotating ANSI {@link placeholder} hints. */
-    describePlaceholder: (() => string) | undefined;
+    /**
+     * TSP placeholder for the empty buffer; natively it replaces the rotating ANSI {@link placeholder} hints.
+     * Return a stable value (the same spans array) while it is unchanged: the editor node is reused by identity.
+     */
+    describePlaceholder: (() => TspText) | undefined;
     /** Called with the selected text when Visual mode yanks, so hosts can reach the system
      *  clipboard — `packages/tui` deliberately has no clipboard dependency of its own. */
     onYank?: (text: string) => void;
@@ -146,6 +149,12 @@ export declare class Editor implements Component, Focusable {
      *  cursor. The host styles it (ANSI allowed). Re-evaluated on every render, so hosts can derive
      *  it from live state. */
     placeholder?: () => string | undefined;
+    /** Whole-message prediction for the next prompt, painted as ghost text after the cursor while
+     *  the single-line buffer is a strict prefix of it, the cursor sits at its end, and no
+     *  autocomplete is open. A shown prediction replaces the {@link placeholder}; Tab or Right inserts
+     *  the rest without submitting. Must be a single line. Re-evaluated on every render, so hosts can
+     *  derive it from live state. */
+    prediction?: () => string | undefined;
     constructor(theme: EditorTheme);
     /** Return bounded editor content, cursor, and transient child state for debug inspection. */
     debugState(): Record<string, unknown>;
@@ -250,6 +259,8 @@ export declare class Editor implements Component, Focusable {
     get atoms(): ReadonlyMap<string, string>;
     /** Monotonic buffer-content revision for render caches. Cursor-only movement does not advance it. */
     get textRevision(): number;
+    /** Monotonic atom-table revision for render caches: advances whenever {@link atoms} is mutated or replaced. */
+    get atomsRevision(): number;
     /** Whether the buffer text equals `value`, without `getText()`'s full join —
      *  O(1) for the hot per-keystroke probes against short single-line values. */
     textEquals(value: string): boolean;
@@ -285,7 +296,7 @@ export declare class Editor implements Component, Focusable {
      *  Mirrors the transient state the key dispatch tears down before this action so the two
      *  cannot diverge: a pending character jump is cancelled by any other key, and an open
      *  spelling-assist popup is dismissed by anything that is not one of its accept keys (its
-     *  debounced refresh skips assist mode, so a surviving list would hang around forever).
+     *  refresh skips assist mode, so a surviving list would hang around forever).
      *  While Vim owns the buffer (Normal or Visual) the operation is Vim's `x` — deleting the
      *  selection and returning to Normal in Visual mode, the grapheme under the cursor
      *  otherwise. Only Insert mode and Vim-off editors delete straight through. */