@oh-my-pi/pi-tui 17.1.8 → 17.2.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [17.2.0] - 2026-07-30
+
+### Added
+
+- Added response-level OSC 11 appearance subscriptions to help terminal consumers distinguish confirmed unchanged background classifications from missing replies.
+
+### Fixed
+
+- Fixed native Windows terminal panes freezing their host during forced closure by skipping the stdout-drain wait after ConPTY disconnects.
+- Fixed high CPU usage in the Loader spinner during idle waits by optimizing text wrapping and caching during frame updates.
+- Fixed hash-prefixed UUIDs in prose being misclassified as 8-digit CSS colors and receiving spurious swatches.
+- Fixed unbounded memory growth and potential host freezes when a PTY consumer stalls by capping the pending stdout backlog and treating undrained consumers as a disconnect.
+
 ## [17.1.8] - 2026-07-28
 
 ### Fixed

package/dist/types/terminal.d.ts

@@ -19,6 +19,36 @@
  * sole production caller.
  */
 export declare function chunkForConPTY(data: string, maxChunkBytes?: number): string[];
+/**
+ * Turns an unbounded, never-draining stdout writable buffer into a bounded
+ * disconnect signal.
+ *
+ * `process.stdout.write()` returns `false` once its buffer exceeds the stream
+ * high-water mark; the bytes stay queued and are only freed when the consumer
+ * drains (the `drain` event). While the consumer keeps up, writes are accepted
+ * and nothing accumulates. When it stalls, every subsequent write piles onto
+ * the buffer — a stalled-but-alive PTY reader never throws, so the write path
+ * has no other signal that output is going nowhere. This guard sums the bytes
+ * queued since backpressure began and reports when that backlog crosses the
+ * cap, at which point the caller treats the terminal as disconnected.
+ *
+ * Exported for unit testing; `ProcessTerminal` is the sole production user.
+ */
+export declare class OutputBacklogGuard {
+    #private;
+    private readonly capBytes;
+    constructor(capBytes?: number);
+    /** True once a refused write started a backlog that has not yet drained. */
+    get tracking(): boolean;
+    /**
+     * Record one `stdout.write()`: `accepted` is that call's return value and
+     * `bytes` its encoded size. Returns true when the pending backlog now
+     * exceeds the cap and the terminal should be treated as disconnected.
+     */
+    record(accepted: boolean, bytes: number): boolean;
+    /** Called on the stdout `drain` event: the buffer emptied, backlog cleared. */
+    reset(): void;
+}
 /** Record alternate-screen state (called by the TUI on `?1049h`/`?1049l` writes). */
 export declare function setAltScreenActive(active: boolean): void;
 /**
@@ -61,6 +91,13 @@ export interface Terminal {
      * already-detected appearance so late subscribers never miss it.
      */
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+    /**
+     * Register a callback fired for every valid OSC 11 appearance report,
+     * including reports whose classification matches the current appearance.
+     * Unlike onAppearanceChange, this does not replay an earlier report.
+     * Optional so custom Terminals built against older pi-tui versions keep working.
+     */
+    onAppearanceReport?(callback: (appearance: TerminalAppearance) => void): (() => void) | void;
     /**
      * Issue a single OSC 11 background-color re-query, driving the appearance
      * callbacks through the same parse/dedup pipeline used at startup and on Mode
@@ -101,13 +138,15 @@ export declare class ProcessTerminal implements Terminal {
     get keyboardEnhancementExitSequence(): string | null;
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+    onAppearanceReport(callback: (appearance: TerminalAppearance) => void): () => void;
     /**
      * Re-query the terminal background via a single OSC 11 probe. Reuses the
      * startup DA1-sentinel FIFO, pending/queued gating, parsing, dedup, and
      * appearance callbacks. Inside tmux, only this explicit path wraps the query
      * and sentinel together for passthrough to the outer terminal; startup and
      * Mode 2031 probes remain direct. Bounded to one probe per call; no timers are
-     * armed. Suppressed while headless or after the terminal is torn down.
+     * armed. Suppressed while inactive, headless, or after the terminal is torn
+     * down.
      */
     refreshAppearance(): void;
     onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "17.1.8",
+	"version": "17.2.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "17.1.8",
-		"@oh-my-pi/pi-utils": "17.1.8",
+		"@oh-my-pi/pi-natives": "17.2.0",
+		"@oh-my-pi/pi-utils": "17.2.0",
 		"lru-cache": "11.5.2",
 		"marked": "^18.0.6"
 	},

package/src/components/loader.ts

@@ -24,6 +24,8 @@ export class Loader extends Text {
 	#lastSpinnerTick = 0;
 	#layoutSource?: readonly string[];
 	#layout?: readonly { leading: string; content: string; trailing: string }[];
+	#layoutFrames: readonly string[];
+	#layoutFrame: string;
 
 	constructor(
 		ui: TUI,
@@ -37,6 +39,17 @@ export class Loader extends Text {
 		if (spinnerFrames && spinnerFrames.length > 0) {
 			this.#frames = spinnerFrames;
 		}
+		const representatives = new Map<number, string>();
+		this.#layoutFrames = this.#frames.map(frame => {
+			const width = visibleWidth(frame);
+			const representative = representatives.get(width);
+			if (representative !== undefined) {
+				return representative;
+			}
+			representatives.set(width, frame);
+			return frame;
+		});
+		this.#layoutFrame = this.#layoutFrames[0];
 		this.start();
 	}
 
@@ -58,12 +71,16 @@ export class Loader extends Text {
 		}
 
 		const frame = this.#frames[this.#currentFrame];
+		// The wrapped text carries one stable representative per frame width.
+		// Same-width frames swap only the visible glyph here; crossing widths
+		// rewraps against the representative selected by #syncText.
+		const sentinel = this.#layoutFrame;
 		const lines = [""];
 		const layout = this.#layout ?? [];
 		for (let i = 0; i < layout.length; i++) {
 			const { leading, content, trailing } = layout[i];
-			if (i === 0 && content.startsWith(frame)) {
-				const remainder = content.slice(frame.length);
+			if (i === 0 && content.startsWith(sentinel)) {
+				const remainder = content.slice(sentinel.length);
 				const separator = remainder.startsWith(" ") ? " " : "";
 				const message = remainder.slice(separator.length);
 				lines.push(
@@ -78,7 +95,8 @@ export class Loader extends Text {
 
 	start() {
 		this.#lastSpinnerTick = performance.now();
-		this.#updateDisplay();
+		this.#syncText();
+		this.#requestPaint();
 		const intervalMs = this.messageColorFn.animated === true ? RENDER_INTERVAL_MS : SPINNER_ADVANCE_MS;
 		this.#intervalId = setInterval(() => {
 			const now = performance.now();
@@ -88,9 +106,10 @@ export class Loader extends Text {
 				const steps = Math.floor(elapsed / SPINNER_ADVANCE_MS);
 				this.#currentFrame = (this.#currentFrame + steps) % this.#frames.length;
 				this.#lastSpinnerTick += steps * SPINNER_ADVANCE_MS;
+				this.#syncText();
 			}
 			if (shouldAdvanceSpinner || this.#ui?.synchronizedOutput === true) {
-				this.#updateDisplay();
+				this.#requestPaint();
 			}
 		}, intervalMs);
 	}
@@ -112,22 +131,29 @@ export class Loader extends Text {
 			return;
 		}
 		this.message = message;
-		this.#updateDisplay();
+		this.#syncText();
+		this.#requestPaint();
 	}
 
-	#updateDisplay() {
-		const frame = this.#frames[this.#currentFrame];
-		const textChanged = this.setText(`${frame} ${this.message}`);
-		if ((textChanged || this.messageColorFn.animated === true) && this.#ui) {
-			// Direct write: a loader tick changes only this component, so the TUI
-			// can update the already-positioned rows without driving the full
-			// compose/prepare/diff pipeline. Lightweight test stubs may not carry
-			// the newer API; keep their legacy component-scoped path working.
-			if (typeof this.#ui.requestDirectWrite === "function") {
-				this.#ui.requestDirectWrite(this);
-			} else {
-				this.#ui.requestComponentRender(this);
-			}
+	/** Re-wrap the underlying Text only when its message or frame width changes. */
+	#syncText(): boolean {
+		const layoutFrame = this.#layoutFrames[this.#currentFrame];
+		this.#layoutFrame = layoutFrame;
+		return this.setText(`${layoutFrame} ${this.message}`);
+	}
+
+	#requestPaint() {
+		if (!this.#ui) {
+			return;
+		}
+		// Direct write: a loader tick changes only this component, so the TUI can
+		// update the already-positioned rows without driving the full
+		// compose/prepare/diff pipeline. Lightweight test stubs may not carry the
+		// newer API; keep their legacy component-scoped path working.
+		if (typeof this.#ui.requestDirectWrite === "function") {
+			this.#ui.requestDirectWrite(this);
+		} else {
+			this.#ui.requestComponentRender(this);
 		}
 	}
 }

package/src/components/markdown.ts

@@ -1284,11 +1284,12 @@ function collapseInlineHtml(tokens: Token[]): Token[] {
 const DEFAULT_COLOR_SWATCH_GLYPH = "■";
 
 // `#` + 3-8 hex digits, not glued to a surrounding word/`#`/`&` (avoids HTML
-// entities like ☃ and paths like foo#fff) and not trailed by more hex
-// (so over-long runs never produce a misleading swatch). Length/letter rules
-// are enforced in classifyHexColor since the alternation can't express "exactly
-// 3, 6, or 8".
-const HEX_COLOR_REGEX = /(?<![\w#&])#([0-9a-fA-F]{3,8})(?![0-9a-fA-F])/g;
+// entities like &#9731; and paths like foo#fff), not the start of a canonical
+// UUID, and not trailed by more hex (so over-long runs never produce a
+// misleading swatch). Length/letter rules are enforced in classifyHexColor
+// since the alternation can't express "exactly 3, 6, or 8".
+const HEX_COLOR_REGEX =
+	/(?<![\w#&])#(?![0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12})([0-9a-fA-F]{3,8})(?![0-9a-fA-F])/g;
 const HEX_COLOR_EXACT_REGEX = /^#([0-9a-fA-F]{3,8})$/;
 
 /**

package/src/terminal.ts

@@ -140,6 +140,66 @@ export function chunkForConPTY(data: string, maxChunkBytes: number = MAX_CONPTY_
 	return chunks;
 }
 
+/**
+ * Hard cap on bytes queued to a stalled stdout before its consumer is declared
+ * gone. A live terminal drains within milliseconds, so a backlog this large —
+ * far above any legitimate paint (a full session resume is a few MiB) — means
+ * the PTY reader has stopped consuming entirely. Without the cap, `#safeWrite`
+ * keeps handing cosmetic frames (the `hub wait` spinner, 500 ms progress
+ * snapshots) to a writable buffer that never drains, growing RSS without bound
+ * until the host runs out of memory. See #6854.
+ */
+const MAX_STDOUT_BACKLOG_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Turns an unbounded, never-draining stdout writable buffer into a bounded
+ * disconnect signal.
+ *
+ * `process.stdout.write()` returns `false` once its buffer exceeds the stream
+ * high-water mark; the bytes stay queued and are only freed when the consumer
+ * drains (the `drain` event). While the consumer keeps up, writes are accepted
+ * and nothing accumulates. When it stalls, every subsequent write piles onto
+ * the buffer — a stalled-but-alive PTY reader never throws, so the write path
+ * has no other signal that output is going nowhere. This guard sums the bytes
+ * queued since backpressure began and reports when that backlog crosses the
+ * cap, at which point the caller treats the terminal as disconnected.
+ *
+ * Exported for unit testing; `ProcessTerminal` is the sole production user.
+ */
+export class OutputBacklogGuard {
+	#bytes = 0;
+	#tracking = false;
+
+	constructor(private readonly capBytes: number = MAX_STDOUT_BACKLOG_BYTES) {}
+
+	/** True once a refused write started a backlog that has not yet drained. */
+	get tracking(): boolean {
+		return this.#tracking;
+	}
+
+	/**
+	 * Record one `stdout.write()`: `accepted` is that call's return value and
+	 * `bytes` its encoded size. Returns true when the pending backlog now
+	 * exceeds the cap and the terminal should be treated as disconnected.
+	 */
+	record(accepted: boolean, bytes: number): boolean {
+		if (!this.#tracking) {
+			// Consumer is keeping up; nothing is queued.
+			if (accepted) return false;
+			// First refused write: backpressure has begun.
+			this.#tracking = true;
+		}
+		this.#bytes += bytes;
+		return this.#bytes > this.capBytes;
+	}
+
+	/** Called on the stdout `drain` event: the buffer emptied, backlog cleared. */
+	reset(): void {
+		this.#bytes = 0;
+		this.#tracking = false;
+	}
+}
+
 /**
  * Minimal terminal interface for TUI
  */
@@ -385,6 +445,13 @@ export interface Terminal {
 	 * already-detected appearance so late subscribers never miss it.
 	 */
 	onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+	/**
+	 * Register a callback fired for every valid OSC 11 appearance report,
+	 * including reports whose classification matches the current appearance.
+	 * Unlike onAppearanceChange, this does not replay an earlier report.
+	 * Optional so custom Terminals built against older pi-tui versions keep working.
+	 */
+	onAppearanceReport?(callback: (appearance: TerminalAppearance) => void): (() => void) | void;
 	/**
 	 * Issue a single OSC 11 background-color re-query, driving the appearance
 	 * callbacks through the same parse/dedup pipeline used at startup and on Mode
@@ -478,6 +545,7 @@ export class ProcessTerminal implements Terminal {
 		this.#markTerminalDisconnected("stdin failed", err);
 	};
 	#dead = false;
+	#active = false;
 	// Last cursor visibility written to the terminal, sniffed from every
 	// outgoing sequence (frame buffers embed their own ?25h/?25l), so
 	// hideCursor()/showCursor() can skip same-state writes. `undefined` =
@@ -493,10 +561,21 @@ export class ProcessTerminal implements Terminal {
 	#stdoutErrorHandler = (err: Error) => {
 		this.#markTerminalDisconnected("stdout failed", err);
 	};
+	// Bounds the stdout writable buffer against a stalled PTY consumer: a
+	// stalled-but-alive reader never throws, so #safeWrite has no error to catch
+	// and the writable buffer grows without bound as cosmetic frames pile up.
+	// See OutputBacklogGuard and #6854.
+	#stdoutBacklog = new OutputBacklogGuard();
+	#stdoutDrainArmed = false;
+	#stdoutDrainHandler = () => {
+		this.#stdoutDrainArmed = false;
+		this.#stdoutBacklog.reset();
+	};
 
 	#windowsVTInputRestore?: () => void;
 	#xtermScrollToBottomRestoreModes = new Set<number>();
 	#appearanceCallbacks: Array<(appearance: TerminalAppearance) => void> = [];
+	#appearanceReportCallbacks: Array<(appearance: TerminalAppearance) => void> = [];
 	#appearance: TerminalAppearance | undefined;
 	#osc11Pending = false;
 	#osc11QueuedRoute?: Osc11QueryRoute;
@@ -560,16 +639,28 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
+	onAppearanceReport(callback: (appearance: TerminalAppearance) => void): () => void {
+		this.#appearanceReportCallbacks.push(callback);
+		let subscribed = true;
+		return () => {
+			if (!subscribed) return;
+			subscribed = false;
+			const index = this.#appearanceReportCallbacks.indexOf(callback);
+			if (index !== -1) this.#appearanceReportCallbacks.splice(index, 1);
+		};
+	}
+
 	/**
 	 * Re-query the terminal background via a single OSC 11 probe. Reuses the
 	 * startup DA1-sentinel FIFO, pending/queued gating, parsing, dedup, and
 	 * appearance callbacks. Inside tmux, only this explicit path wraps the query
 	 * and sentinel together for passthrough to the outer terminal; startup and
 	 * Mode 2031 probes remain direct. Bounded to one probe per call; no timers are
-	 * armed. Suppressed while headless or after the terminal is torn down.
+	 * armed. Suppressed while inactive, headless, or after the terminal is torn
+	 * down.
 	 */
 	refreshAppearance(): void {
-		if (this.#headless || this.#dead) return;
+		if (!this.#active || this.#headless || this.#dead) return;
 		this.#queryBackgroundColor(isInsideTmux() ? "tmux" : "direct");
 	}
 
@@ -651,6 +742,9 @@ export class ProcessTerminal implements Terminal {
 		// The query handler intercepts input temporarily, then installs the user's handler
 		// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
 		this.#queryAndEnableKittyProtocol();
+		// Explicit probes are safe only after their response parser and stdin
+		// data handler are installed. Keep this false throughout temporary stops.
+		this.#active = true;
 		setHangulCompatibilityJamoWidth(TERMINAL.hangulJamoWidth);
 
 		// Query terminal background color via OSC 11 for dark/light detection.
@@ -1152,8 +1246,16 @@ export class ProcessTerminal implements Terminal {
 		};
 		const luminance = 0.299 * normalize(rHex) + 0.587 * normalize(gHex) + 0.114 * normalize(bHex);
 		const mode: TerminalAppearance = luminance < 0.5 ? "dark" : "light";
-		if (mode === this.#appearance) return;
+		const changed = mode !== this.#appearance;
 		this.#appearance = mode;
+		for (const cb of [...this.#appearanceReportCallbacks]) {
+			try {
+				cb(mode);
+			} catch {
+				/* ignore callback errors */
+			}
+		}
+		if (!changed) return;
 		for (const cb of this.#appearanceCallbacks) {
 			try {
 				cb(mode);
@@ -1359,6 +1461,8 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	stop(): void {
+		// Suppress observer/timer callbacks before any teardown can yield or throw.
+		this.#active = false;
 		if (this.#headless) return;
 		// Unregister from emergency cleanup
 		if (activeTerminal === this) {
@@ -1466,6 +1570,11 @@ export class ProcessTerminal implements Terminal {
 			process.stdout.removeListener("resize", this.#stdoutResizeListener);
 			this.#stdoutResizeListener = undefined;
 		}
+		if (this.#stdoutDrainArmed) {
+			process.stdout.removeListener("drain", this.#stdoutDrainHandler);
+			this.#stdoutDrainArmed = false;
+		}
+		this.#stdoutBacklog.reset();
 		this.#resizeHandler = undefined;
 
 		// Pause stdin to prevent any buffered input (e.g., Ctrl+D) from being
@@ -1512,7 +1621,7 @@ export class ProcessTerminal implements Terminal {
 		}
 
 		if (process.platform === "win32") {
-			void postmortem.quit(129);
+			void postmortem.quit(129, { drainStdout: false });
 			return;
 		}
 		try {
@@ -1559,13 +1668,26 @@ export class ProcessTerminal implements Terminal {
 			// `process.stdout.write(string)` UTF-8-encodes before `WriteFile`,
 			// and a code-unit cap would let CJK transcript rows expand past the
 			// threshold. See #2034 and #2095.
-			if (isConPTYHosted() && Buffer.byteLength(data, "utf8") > MAX_CONPTY_WRITE_CHUNK_BYTES) {
+			const bytes = Buffer.byteLength(data, "utf8");
+			let accepted: boolean;
+			if (isConPTYHosted() && bytes > MAX_CONPTY_WRITE_CHUNK_BYTES) {
+				accepted = true;
 				for (const chunk of chunkForConPTY(data, MAX_CONPTY_WRITE_CHUNK_BYTES)) {
 					if (this.#dead) break;
-					process.stdout.write(chunk);
+					accepted = process.stdout.write(chunk);
 				}
 			} else {
-				process.stdout.write(data);
+				accepted = process.stdout.write(data);
+			}
+			// A stalled-but-alive PTY consumer never throws: write() just returns
+			// false and queues the bytes. Bound that never-draining backlog by
+			// declaring the terminal disconnected once it crosses the cap — the
+			// same clean-exit path a dead terminal takes (#6854).
+			if (this.#stdoutBacklog.record(accepted, bytes)) {
+				this.#markTerminalDisconnected("stdout backlog exceeded cap; PTY consumer stalled");
+			} else if (this.#stdoutBacklog.tracking && !this.#stdoutDrainArmed) {
+				this.#stdoutDrainArmed = true;
+				process.stdout.once("drain", this.#stdoutDrainHandler);
 			}
 		} catch (err) {
 			this.#markTerminalDisconnected("stdout failed", err);