@gajae-code/tui 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -2,9 +2,20 @@
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-07-14
+### Fixed
+
+- Shared the temporary stdout error listener across terminal instances, preventing `MaxListenersExceededWarning` during repeated TUI start/stop cycles while retaining late detached-PTY error handling.
+- Added a TUI-lifetime terminal cleanup queue so component-owned escape cleanup can be retried after terminal recovery even when the originating component has already been disposed.
+
+### Added
+
+- Added opt-in disabled items to `SelectList` (`SelectItem.disabled`): disabled entries render dimmed; arrow navigation wraps while page navigation clamps and both skip disabled targets; filter resets choose the first enabled item; and programmatic selection searches forward from the requested index before falling back backward. Callbacks never receive disabled entries, while enabled-only arrow/page inputs preserve their existing notification behavior. All-disabled lists keep a null selection while an independent viewport remains navigable, with no cursor and a `(-/N)` scroll position.
+
 ## [0.10.1] - 2026-07-13
 ### Fixed
 
+- Real interactive terminals now repaint only the visible viewport during forced renders instead of clearing and replaying native scrollback.
 - Terminal graphics protocols are no longer assumed under terminal multiplexers: the blind Kitty fallback for `TERM=tmux-*`/`screen-*` (and detected kitty/iTerm2 protocols leaking through multiplexer env) emitted raw graphics escapes the multiplexer consumed, leaving the Gajae composer pet invisible while its out-of-band cursor writes intermittently corrupted the TUI frame. Image protocols are now unconditionally dropped under tmux/screen/zellij (shared multiplexer predicate with the renderer host policy, including `$TMUX_PANE`, `$STY`, `$ZELLIJ`, and `GJC_TMUX_LAUNCHED`) unless `PI_FORCE_IMAGE_PROTOCOL` explicitly forces a protocol, which remains an expert override.
 - Fixed the startup sixel capability probe's response parsing and authority: XTSMGRAPHICS replies are read per spec (`Ps=0` success; `1/2/3` errors — tmux's `CSI ?2;3;0S` error no longer counts as support), the DA1 device-class parameter is no longer misread as the sixel extension attribute (`CSI ?4;6c` identifies a VT132, not sixel), an explicit `PI_FORCE_IMAGE_PROTOCOL` (including `off`) suppresses probing entirely, and the probe never runs inside a multiplexer because tmux advertises DA1 `;4` from compile-time support regardless of the attached client.
 - A configured Gajae pet now re-applies automatically when the asynchronous sixel probe enables graphics after startup (new `onImageProtocolChanged` subscription), instead of staying hidden until `/pet` is re-run; `/pet` also reports multiplexer graphics suppression explicitly instead of suggesting a different terminal.

package/README.md

@@ -328,6 +328,8 @@ interface SelectItem {
 	value: string;
 	label: string;
 	description?: string;
+	hint?: string; // Autocomplete hint consumed by Editor; SelectList does not render it
+	disabled?: boolean; // Dimmed, unselectable entry (see "Disabled items")
 }
 
 interface SelectListTheme {
@@ -352,14 +354,29 @@ list.onSelect = (item) => console.log("Selected:", item);
 list.onCancel = () => console.log("Cancelled");
 list.onSelectionChange = (item) => console.log("Highlighted:", item);
 list.setFilter("opt"); // Filter items
+list.setSelectedIndex(1); // Select first enabled item at/after index 1, then search backward
 ```
 
 **Controls:**
 
-- Arrow keys: Navigate
+- Arrow keys: Navigate and wrap at list edges
+- PageUp/PageDown: Move by a visible page and clamp at list boundaries
 - Enter: Select
 - Escape: Cancel
 
+**Disabled items:**
+
+Items with `disabled: true` stay visible but can never be selected:
+
+- They render dimmed (via `theme.description`) and never show the selection cursor.
+- Arrow keys wrap while skipping disabled entries; PageUp/PageDown skip disabled targets and clamp at list boundaries.
+- Filtering (`setFilter`) resets the selection to the first *enabled* item.
+- `setSelectedIndex(i)` selects the first enabled item at or after the clamped index, falling back backward.
+- `onSelect` and `onSelectionChange` never receive a disabled item.
+- When every visible item is disabled, `getSelectedItem()` returns `null` and no
+  row shows a cursor. Arrow keys wrap the viewport, PageUp/PageDown clamp it,
+  and the scroll indicator reports `(-/N)` without claiming a selected row.
+
 ### SettingsList
 
 Settings panel with value cycling and submenus.

package/dist/types/components/select-list.d.ts

@@ -4,8 +4,14 @@ export interface SelectItem {
     value: string;
     label: string;
     description?: string;
-    /** Dim hint text shown inline after cursor when this item is selected */
+    /** Autocomplete hint consumed by Editor; SelectList does not render it. */
     hint?: string;
+    /**
+     * Renders dimmed and can never be selected: navigation skips it, selection
+     * callbacks never fire for it, and a list whose visible items are all
+     * disabled reports no selection (`getSelectedItem()` returns `null`).
+     */
+    disabled?: boolean;
 }
 export interface SelectListTheme {
     selectedPrefix: (text: string) => string;

package/dist/types/terminal.d.ts

@@ -58,6 +58,13 @@ interface TerminalSizeStream {
 }
 export declare function resolveTerminalColumns(stream?: TerminalSizeStream, envColumns?: string | undefined): number;
 export declare function resolveTerminalRows(stream?: TerminalSizeStream, envRows?: string | undefined): number;
+/**
+ * Test-only: reset the shared stdout-error dispatcher to a clean slate.
+ * Used by tests to avoid cross-test leakage of the module-level subscriber set
+ * (a leaked subscriber otherwise keeps `size > 0`, so a later subscribe no longer
+ * re-arms the process.stdout listener). Not part of the public runtime contract.
+ */
+export declare function __resetStdoutErrorHandlingForTest(): void;
 /**
  * Real terminal using process.stdin/stdout
  */

package/dist/types/tui.d.ts

@@ -112,12 +112,14 @@ export type SizeValue = number | `${number}%`;
 export declare function shouldProbeSixelCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
  * True when repainting only the live viewport is safer than clearing/replaying
- * the full transcript. Native Windows console hosts are included even when
- * WT_SESSION is absent because PowerShell/ConPTY launch chains can drop terminal
- * identity variables while keeping the same scroll-jump behavior.
+ * the full transcript. Real process terminals are viewport-sensitive because
+ * their native scrollback position is not observable by the renderer. Native
+ * Windows console hosts are also recognized from platform identity when that
+ * process-terminal capability is unavailable.
  */
 export declare function shouldUseViewportRepaintForHost(env?: Record<string, string | undefined>, platform?: NodeJS.Platform, options?: {
     includeNativeWindows?: boolean;
+    includeProcessTerminal?: boolean;
 }): boolean;
 /**
  * Options for overlay positioning and sizing.
@@ -259,6 +261,10 @@ export declare class TUI extends Container {
         normalizationLimit: number;
         truncationLimit: number;
     };
+    /** Retain terminal cleanup until a write succeeds, even after its component is disposed. */
+    queueTerminalCleanup(payload: string, onDelivered?: () => void): void;
+    /** Retry queued terminal cleanup after terminal recovery or before shutdown. */
+    flushTerminalCleanup(): void;
     /**
      * Register an emitter whose escape payload is appended to every render
      * write (inside its own synchronized-output block, cursor saved/restored).

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.10.1",
+	"version": "0.10.2",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -35,8 +35,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.10.1",
-		"@gajae-code/utils": "0.10.1",
+		"@gajae-code/natives": "0.10.2",
+		"@gajae-code/utils": "0.10.2",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/select-list.ts

@@ -20,8 +20,14 @@ export interface SelectItem {
 	value: string;
 	label: string;
 	description?: string;
-	/** Dim hint text shown inline after cursor when this item is selected */
+	/** Autocomplete hint consumed by Editor; SelectList does not render it. */
 	hint?: string;
+	/**
+	 * Renders dimmed and can never be selected: navigation skips it, selection
+	 * callbacks never fire for it, and a list whose visible items are all
+	 * disabled reports no selection (`getSelectedItem()` returns `null`).
+	 */
+	disabled?: boolean;
 }
 
 export interface SelectListTheme {
@@ -49,7 +55,10 @@ export interface SelectListLayoutOptions {
 
 export class SelectList implements Component {
 	#filteredItems: ReadonlyArray<SelectItem>;
+	/** Index of the selected enabled item, or `-1` when no enabled item exists. */
 	#selectedIndex: number = 0;
+	/** First rendered item while selection is absent. */
+	#viewportStartIndex: number = 0;
 
 	onSelect?: (item: SelectItem) => void;
 	onCancel?: () => void;
@@ -62,16 +71,26 @@ export class SelectList implements Component {
 		private readonly layout: SelectListLayoutOptions = {},
 	) {
 		this.#filteredItems = items;
+		this.#selectedIndex = this.#firstEnabledIndex();
+		this.#syncViewportToIndex(Math.max(0, this.#selectedIndex));
 	}
 
 	setFilter(filter: string): void {
 		this.#filteredItems = this.items.filter(item => item.value.toLowerCase().startsWith(filter.toLowerCase()));
-		// Reset selection when filter changes
-		this.#selectedIndex = 0;
+		this.#selectedIndex = this.#firstEnabledIndex();
+		this.#syncViewportToIndex(Math.max(0, this.#selectedIndex));
 	}
 
 	setSelectedIndex(index: number): void {
-		this.#selectedIndex = Math.max(0, Math.min(index, this.#filteredItems.length - 1));
+		if (this.#filteredItems.length === 0) {
+			this.#selectedIndex = -1;
+			this.#viewportStartIndex = 0;
+			return;
+		}
+		const clamped = Math.max(0, Math.min(index, this.#filteredItems.length - 1));
+		this.#selectedIndex =
+			this.#findEnabledIndex(clamped, 1, false) ?? this.#findEnabledIndex(clamped, -1, false) ?? -1;
+		this.#syncViewportToIndex(this.#selectedIndex >= 0 ? this.#selectedIndex : clamped);
 	}
 
 	invalidate(): void {
@@ -89,11 +108,10 @@ export class SelectList implements Component {
 
 		const primaryColumnWidth = this.#getPrimaryColumnWidth();
 
-		// Calculate visible range with scrolling
-		const startIndex = Math.max(
-			0,
-			Math.min(this.#selectedIndex - Math.floor(this.maxVisible / 2), this.#filteredItems.length - this.maxVisible),
-		);
+		// Calculate visible range with scrolling. Selection owns the viewport when
+		// present; otherwise navigation moves an independent viewport anchor.
+		const startIndex =
+			this.#selectedIndex >= 0 ? this.#startIndexForSelection(this.#selectedIndex) : this.#clampedViewportStart();
 		const endIndex = Math.min(startIndex + this.maxVisible, this.#filteredItems.length);
 
 		// Render visible items
@@ -101,14 +119,16 @@ export class SelectList implements Component {
 			const item = this.#filteredItems[i];
 			if (!item) continue;
 
-			const isSelected = i === this.#selectedIndex;
+			const isSelected = i === this.#selectedIndex && !item.disabled;
 			const descriptionText = item.description ? sanitizeSingleLine(item.description) : undefined;
 			lines.push(this.#renderItem(item, isSelected, width, descriptionText, primaryColumnWidth));
 		}
 
-		// Add scroll indicators if needed
+		// Add scroll indicators if needed. With no selectable item the position
+		// is reported as "-" so an all-disabled list never claims a selection.
 		if (startIndex > 0 || endIndex < this.#filteredItems.length) {
-			const scrollText = `  (${this.#selectedIndex + 1}/${this.#filteredItems.length})`;
+			const position = this.#selectedIndex >= 0 ? `${this.#selectedIndex + 1}` : "-";
+			const scrollText = `  (${position}/${this.#filteredItems.length})`;
 			// Truncate if too long for terminal
 			lines.push(this.theme.scrollInfo(truncateToWidth(scrollText, width - 2, Ellipsis.Omit)));
 		}
@@ -126,30 +146,19 @@ export class SelectList implements Component {
 			}
 			return;
 		}
-		// Up arrow - wrap to bottom when at top
 		if (kb.matches(keyData, "tui.select.up")) {
-			this.#selectedIndex = this.#selectedIndex === 0 ? this.#filteredItems.length - 1 : this.#selectedIndex - 1;
-			this.#notifySelectionChange();
-		}
-		// Down arrow - wrap to top when at bottom
-		else if (kb.matches(keyData, "tui.select.down")) {
-			this.#selectedIndex = this.#selectedIndex === this.#filteredItems.length - 1 ? 0 : this.#selectedIndex + 1;
-			this.#notifySelectionChange();
-		}
-		// PageUp - jump up by one visible page
-		else if (kb.matches(keyData, "tui.select.pageUp")) {
-			this.#selectedIndex = Math.max(0, this.#selectedIndex - this.maxVisible);
-			this.#notifySelectionChange();
-		}
-		// PageDown - jump down by one visible page
-		else if (kb.matches(keyData, "tui.select.pageDown")) {
-			this.#selectedIndex = Math.min(this.#filteredItems.length - 1, this.#selectedIndex + this.maxVisible);
-			this.#notifySelectionChange();
+			this.#moveSelection(-1);
+		} else if (kb.matches(keyData, "tui.select.down")) {
+			this.#moveSelection(1);
+		} else if (kb.matches(keyData, "tui.select.pageUp")) {
+			this.#movePage(-1);
+		} else if (kb.matches(keyData, "tui.select.pageDown")) {
+			this.#movePage(1);
 		}
 		// Enter
 		else if (kb.matches(keyData, "tui.select.confirm") || keyData === "\n") {
 			const selectedItem = this.#filteredItems[this.#selectedIndex];
-			if (selectedItem && this.onSelect) {
+			if (selectedItem && !selectedItem.disabled && this.onSelect) {
 				this.onSelect(selectedItem);
 			}
 		}
@@ -184,6 +193,9 @@ export class SelectList implements Component {
 
 			if (remainingWidth > MIN_DESCRIPTION_WIDTH) {
 				const truncatedDesc = truncateToWidth(descriptionSingleLine, remainingWidth, Ellipsis.Omit);
+				if (item.disabled) {
+					return this.theme.description(`${prefix}${truncatedValue}${spacing}${truncatedDesc}`);
+				}
 				if (isSelected) {
 					return this.theme.selectedText(`${prefix}${truncatedValue}${spacing}${truncatedDesc}`);
 				}
@@ -195,6 +207,9 @@ export class SelectList implements Component {
 
 		const maxWidth = width - prefixWidth - 2;
 		const truncatedValue = this.#truncatePrimary(item, isSelected, maxWidth, maxWidth);
+		if (item.disabled) {
+			return this.theme.description(`${prefix}${truncatedValue}`);
+		}
 		if (isSelected) {
 			return this.theme.selectedText(`${prefix}${truncatedValue}`);
 		}
@@ -242,15 +257,105 @@ export class SelectList implements Component {
 		return sanitizeSingleLine(item.label || item.value);
 	}
 
+	/** First enabled index, or `-1` when every filtered item is disabled. */
+	#firstEnabledIndex(): number {
+		return this.#filteredItems.findIndex(item => !item.disabled);
+	}
+
+	#findEnabledIndex(start: number, direction: 1 | -1, wrap: boolean): number | undefined {
+		for (let step = 0; step < this.#filteredItems.length; step++) {
+			let index = start + step * direction;
+			if (index < 0 || index >= this.#filteredItems.length) {
+				if (!wrap) return undefined;
+				index = (index + this.#filteredItems.length) % this.#filteredItems.length;
+			}
+			if (!this.#filteredItems[index]?.disabled) return index;
+		}
+		return undefined;
+	}
+
+	#moveSelection(direction: 1 | -1): void {
+		if (this.#filteredItems.length === 0) return;
+		if (this.#selectedIndex < 0 && this.#firstEnabledIndex() < 0) {
+			this.#moveViewport(direction, true);
+			return;
+		}
+		const start =
+			this.#selectedIndex < 0
+				? direction === 1
+					? 0
+					: this.#filteredItems.length - 1
+				: (this.#selectedIndex + direction + this.#filteredItems.length) % this.#filteredItems.length;
+		const next = this.#findEnabledIndex(start, direction, true);
+		if (next === undefined) return;
+		if (next === this.#selectedIndex) {
+			// Preserve the legacy enabled-only callback contract while suppressing
+			// no-op previews when disabled entries collapse navigation to one item.
+			if (this.#allItemsEnabled()) this.#notifySelectionChange();
+			return;
+		}
+		this.#selectedIndex = next;
+		this.#syncViewportToIndex(next);
+		this.#notifySelectionChange();
+	}
+
+	#movePage(direction: 1 | -1): void {
+		if (this.#filteredItems.length === 0) return;
+		if (this.#selectedIndex < 0 && this.#firstEnabledIndex() < 0) {
+			this.#moveViewport(direction * this.maxVisible, false);
+			return;
+		}
+		const from = this.#selectedIndex < 0 ? (direction === 1 ? -1 : this.#filteredItems.length) : this.#selectedIndex;
+		const target = Math.max(0, Math.min(this.#filteredItems.length - 1, from + direction * this.maxVisible));
+		const next =
+			this.#findEnabledIndex(target, direction, false) ??
+			this.#findEnabledIndex(target, direction === 1 ? -1 : 1, false);
+		if (next === undefined) return;
+		if (next === this.#selectedIndex) {
+			if (this.#allItemsEnabled()) this.#notifySelectionChange();
+			return;
+		}
+		this.#selectedIndex = next;
+		this.#syncViewportToIndex(next);
+		this.#notifySelectionChange();
+	}
+
+	#allItemsEnabled(): boolean {
+		return this.#filteredItems.every(item => !item.disabled);
+	}
+
+	#maxViewportStart(): number {
+		return Math.max(0, this.#filteredItems.length - this.maxVisible);
+	}
+
+	#clampedViewportStart(): number {
+		return Math.max(0, Math.min(this.#viewportStartIndex, this.#maxViewportStart()));
+	}
+
+	#startIndexForSelection(index: number): number {
+		return Math.max(0, Math.min(index - Math.floor(this.maxVisible / 2), this.#maxViewportStart()));
+	}
+
+	#syncViewportToIndex(index: number): void {
+		this.#viewportStartIndex = this.#startIndexForSelection(index);
+	}
+
+	#moveViewport(delta: number, wrap: boolean): void {
+		const maxStart = this.#maxViewportStart();
+		if (maxStart === 0) return;
+		const next = this.#viewportStartIndex + delta;
+		this.#viewportStartIndex = wrap ? (next + maxStart + 1) % (maxStart + 1) : Math.max(0, Math.min(next, maxStart));
+	}
+
 	#notifySelectionChange(): void {
 		const selectedItem = this.#filteredItems[this.#selectedIndex];
-		if (selectedItem && this.onSelectionChange) {
+		if (selectedItem && !selectedItem.disabled && this.onSelectionChange) {
 			this.onSelectionChange(selectedItem);
 		}
 	}
 
 	getSelectedItem(): SelectItem | null {
 		const item = this.#filteredItems[this.#selectedIndex];
-		return item || null;
+		return item && !item.disabled ? item : null;
 	}
 }

package/src/terminal.ts

@@ -171,6 +171,31 @@ function isWindowsSubsystemForLinux(): boolean {
 	return process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
 }
 const STDOUT_ERROR_HANDLER_GRACE_MS = 250;
+const stdoutErrorSubscribers = new Set<(err: Error) => void>();
+const dispatchStdoutError = (err: Error): void => {
+	for (const subscriber of stdoutErrorSubscribers) subscriber(err);
+};
+
+function subscribeToStdoutErrors(subscriber: (err: Error) => void): void {
+	if (stdoutErrorSubscribers.size === 0) process.stdout.on("error", dispatchStdoutError);
+	stdoutErrorSubscribers.add(subscriber);
+}
+
+function unsubscribeFromStdoutErrors(subscriber: (err: Error) => void): void {
+	stdoutErrorSubscribers.delete(subscriber);
+	if (stdoutErrorSubscribers.size === 0) process.stdout.removeListener("error", dispatchStdoutError);
+}
+
+/**
+ * Test-only: reset the shared stdout-error dispatcher to a clean slate.
+ * Used by tests to avoid cross-test leakage of the module-level subscriber set
+ * (a leaked subscriber otherwise keeps `size > 0`, so a later subscribe no longer
+ * re-arms the process.stdout listener). Not part of the public runtime contract.
+ */
+export function __resetStdoutErrorHandlingForTest(): void {
+	stdoutErrorSubscribers.clear();
+	process.stdout.removeListener("error", dispatchStdoutError);
+}
 
 /**
  * Real terminal using process.stdin/stdout
@@ -250,7 +275,7 @@ export class ProcessTerminal implements Terminal {
 			this.#stdoutErrorHandler = (err: Error) => {
 				this.#markUnavailable(err, "stdout-error");
 			};
-			process.stdout.on("error", this.#stdoutErrorHandler);
+			subscribeToStdoutErrors(this.#stdoutErrorHandler);
 		}
 
 		// Refresh terminal dimensions - they may be stale after suspend/resume
@@ -743,7 +768,7 @@ export class ProcessTerminal implements Terminal {
 		// of surfacing as uncaught exceptions that kill the tmux pane.
 		this.#stdoutErrorHandlerCleanupTimer = setTimeout(() => {
 			if (this.#stdoutErrorHandler) {
-				process.stdout.removeListener("error", this.#stdoutErrorHandler);
+				unsubscribeFromStdoutErrors(this.#stdoutErrorHandler);
 				this.#stdoutErrorHandler = undefined;
 			}
 			this.#stdoutErrorHandlerCleanupTimer = undefined;

package/src/tui.ts

@@ -279,31 +279,41 @@ function isViewportSensitiveHost(
 	env: Record<string, string | undefined>,
 	platform: NodeJS.Platform,
 	includeNativeWindows: boolean,
+	includeProcessTerminal: boolean,
 ): boolean {
-	return isMultiplexerSession(env) || isWindowsTerminalSession(env) || (includeNativeWindows && platform === "win32");
+	return (
+		isMultiplexerSession(env) ||
+		isWindowsTerminalSession(env) ||
+		includeProcessTerminal ||
+		(includeNativeWindows && platform === "win32")
+	);
 }
 /**
  * True when repainting only the live viewport is safer than clearing/replaying
- * the full transcript. Native Windows console hosts are included even when
- * WT_SESSION is absent because PowerShell/ConPTY launch chains can drop terminal
- * identity variables while keeping the same scroll-jump behavior.
+ * the full transcript. Real process terminals are viewport-sensitive because
+ * their native scrollback position is not observable by the renderer. Native
+ * Windows console hosts are also recognized from platform identity when that
+ * process-terminal capability is unavailable.
  */
 export function shouldUseViewportRepaintForHost(
 	env: Record<string, string | undefined> = Bun.env,
 	platform: NodeJS.Platform = process.platform,
-	options: { includeNativeWindows?: boolean } = {},
+	options: { includeNativeWindows?: boolean; includeProcessTerminal?: boolean } = {},
 ): boolean {
 	const multiplexed = isMultiplexerSession(env);
 	const includeNativeWindows = options.includeNativeWindows ?? true;
+	const includeProcessTerminal = options.includeProcessTerminal ?? false;
 	return (
-		isViewportSensitiveHost(env, platform, includeNativeWindows) &&
+		isViewportSensitiveHost(env, platform, includeNativeWindows, includeProcessTerminal) &&
 		!(multiplexed && useLegacyMultiplexerFullRender(env))
 	);
 }
 
 function useViewportRepaintPath(terminal: Terminal): boolean {
+	if (terminal.isProcessTerminal !== true) return false;
 	return shouldUseViewportRepaintForHost(Bun.env, process.platform, {
-		includeNativeWindows: terminal.isProcessTerminal === true,
+		includeNativeWindows: true,
+		includeProcessTerminal: true,
 	});
 }
 
@@ -319,7 +329,8 @@ function allowsHostNeutralOverflowRepaint(
 }
 
 function shouldPreserveScrollbackOnFullClear(terminal: Terminal): boolean {
-	return isViewportSensitiveHost(Bun.env, process.platform, terminal.isProcessTerminal === true);
+	if (terminal.isProcessTerminal !== true) return false;
+	return isViewportSensitiveHost(Bun.env, process.platform, true, true);
 }
 
 /**
@@ -618,6 +629,7 @@ export class TUI extends Container {
 	#stopped = false;
 	#terminalUnavailable = false;
 	#bottomPinnedComponent: Component | null = null;
+	#pendingTerminalCleanup: Array<{ payload: string; onDelivered?: () => void }> = [];
 
 	#unsubscribeTabWidthChange?: () => void;
 	static #renderCounters: TuiRenderCounterSnapshot = {
@@ -962,6 +974,7 @@ export class TUI extends Container {
 				this.requestResizeRender();
 			},
 		);
+		this.flushTerminalCleanup();
 		this.#hideCursor();
 		this.#querySixelSupport();
 		this.#queryCellSize();
@@ -1171,6 +1184,7 @@ export class TUI extends Container {
 	}
 
 	stop(): void {
+		this.flushTerminalCleanup();
 		this.#clearSixelProbeState();
 		this.#stopped = true;
 		if (this.#renderTimer) {
@@ -1229,7 +1243,7 @@ export class TUI extends Container {
 	 * `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy tmux redraw.
 	 */
 	requestResizeRender(): void {
-		this.requestRender(!useViewportRepaintPath(this.terminal) && !isTermuxSession(), "resize");
+		this.requestRender(!useViewportRepaintPath(this.terminal), "resize");
 	}
 
 	requestRender(force = false, source = "unknown"): void {
@@ -2274,11 +2288,9 @@ export class TUI extends Container {
 				viewportRepaint(`terminal height changed (${this.#previousHeight} -> ${height})`);
 				return;
 			}
-			if (!isTermuxSession() && !isMultiplexerSession()) {
-				logRedraw(`terminal height changed (${this.#previousHeight} -> ${height})`);
-				fullRender(true, "terminal height changed");
-				return;
-			}
+			logRedraw(`terminal height changed (${this.#previousHeight} -> ${height})`);
+			fullRender(true, "terminal height changed");
+			return;
 		}
 
 		// Content shrunk below the previous render and no overlays - re-render to clear empty rows
@@ -2333,8 +2345,8 @@ export class TUI extends Container {
 		}
 
 		const nextLiveViewportTop = Math.max(0, newLines.length - height);
-		if (firstChanged >= newLines.length && nextLiveViewportTop !== prevViewportTop) {
-			viewportRepaint(`tail shrink changed viewport top (${prevViewportTop} -> ${nextLiveViewportTop})`);
+		if (newLines.length < this.#previousLines.length && nextLiveViewportTop !== prevViewportTop) {
+			viewportRepaint(`content contraction changed viewport top (${prevViewportTop} -> ${nextLiveViewportTop})`);
 			return;
 		}
 		// All changes are in deleted lines (nothing to render, just clear)
@@ -2580,6 +2592,22 @@ export class TUI extends Container {
 		return { seq, toRow: targetRow };
 	}
 
+	/** Retain terminal cleanup until a write succeeds, even after its component is disposed. */
+	queueTerminalCleanup(payload: string, onDelivered?: () => void): void {
+		this.#pendingTerminalCleanup.push({ payload, onDelivered });
+		this.flushTerminalCleanup();
+	}
+
+	/** Retry queued terminal cleanup after terminal recovery or before shutdown. */
+	flushTerminalCleanup(): void {
+		while (this.#pendingTerminalCleanup.length > 0) {
+			const pending = this.#pendingTerminalCleanup[0];
+			if (!this.#writeTerminal(pending.payload)) return;
+			this.#pendingTerminalCleanup.shift();
+			pending.onDelivered?.();
+		}
+	}
+
 	/**
 	 * Register an emitter whose escape payload is appended to every render
 	 * write (inside its own synchronized-output block, cursor saved/restored).