@gajae-code/tui 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [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.
+
 ## [0.10.0] - 2026-07-12
 ### Fixed
 

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-capabilities.d.ts

@@ -22,6 +22,15 @@ export declare class TerminalInfo {
     sendNotification(message: string): void;
 }
 export declare function isNotificationSuppressed(): boolean;
+/**
+ * Returns whether the process runs under a terminal multiplexer (tmux, GNU
+ * screen, or zellij). Recognizes the same host markers as the renderer's
+ * multiplexer predicate in tui.ts so capability selection and viewport-repaint
+ * policy agree on what counts as a multiplexed host. Multiplexers intercept
+ * graphics escapes and OSC 8 hyperlinks instead of forwarding them to the
+ * outer terminal.
+ */
+export declare function isUnderTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
 export interface TerminalGraphicsFallbackOptions {
     /**
      * Permit cursor-neutral image escapes (kitty `a=p,C=1` placements) to render
@@ -43,6 +52,12 @@ export declare function isTerminalGraphicsFallbackActive(): boolean;
  * graphics-fallback scope. True only when every active fallback scope opted in.
  */
 export declare function isCursorNeutralImagePermittedInFallback(): boolean;
+/**
+ * Returns whether PI_FORCE_IMAGE_PROTOCOL explicitly configures the image
+ * protocol, including an explicit "off". An explicit configuration is
+ * authoritative: runtime capability probes must not override it.
+ */
+export declare function isImageProtocolForced(): boolean;
 /**
  * Returns true when running in Windows Terminal with known SIXEL support.
  *
@@ -51,6 +66,13 @@ export declare function isCursorNeutralImagePermittedInFallback(): boolean;
 export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 export declare const TERMINAL_ID: TerminalId;
 export declare const TERMINAL: TerminalInfo;
+type ImageProtocolChangeListener = (imageProtocol: ImageProtocol | null) => void;
+/**
+ * Subscribe to runtime image-protocol changes (e.g. the asynchronous sixel
+ * capability probe enabling graphics after startup). Returns an unsubscribe
+ * function. Listeners fire only on actual changes.
+ */
+export declare function onImageProtocolChanged(listener: ImageProtocolChangeListener): () => void;
 /**
  * Override terminal image protocol at runtime after capability probes complete.
  */
@@ -162,3 +184,4 @@ export interface RenderedImage {
 }
 export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): RenderedImage | null;
 export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;
+export {};

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

@@ -98,14 +98,28 @@ export interface OverlayMargin {
 }
 /** Value that can be absolute (number) or percentage (string like "50%") */
 export type SizeValue = number | `${number}%`;
+/**
+ * Startup sixel capability probe policy (pure; exported for tests):
+ * - Never probe when PI_FORCE_IMAGE_PROTOCOL is set — an explicit
+ *   configuration (including "off") is authoritative.
+ * - Never probe inside a terminal multiplexer: tmux advertises DA1 ";4"
+ *   whenever it was compiled with sixel support, regardless of whether the
+ *   attached client terminal can render sixel, so a positive reply is not
+ *   end-to-end evidence. Graphics under a multiplexer are strictly opt-in
+ *   via PI_FORCE_IMAGE_PROTOCOL=sixel.
+ * - Probe Windows Terminal (>=1.22 renders sixel but exposes no env marker).
+ */
+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.
@@ -247,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.0",
+	"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.0",
-		"@gajae-code/utils": "0.10.0",
+		"@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-capabilities.ts

@@ -53,6 +53,35 @@ export function isNotificationSuppressed(): boolean {
 	return value === "off" || value === "0" || value === "false";
 }
 
+const MULTIPLEXER_DISABLED_ENV_VALUES = new Set(["0", "false", "off", "no"]);
+
+function multiplexerEnvEnabled(value: string | undefined): boolean {
+	const normalized = value?.trim().toLowerCase();
+	return normalized !== undefined && normalized.length > 0 && !MULTIPLEXER_DISABLED_ENV_VALUES.has(normalized);
+}
+
+/**
+ * Returns whether the process runs under a terminal multiplexer (tmux, GNU
+ * screen, or zellij). Recognizes the same host markers as the renderer's
+ * multiplexer predicate in tui.ts so capability selection and viewport-repaint
+ * policy agree on what counts as a multiplexed host. Multiplexers intercept
+ * graphics escapes and OSC 8 hyperlinks instead of forwarding them to the
+ * outer terminal.
+ */
+export function isUnderTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (
+		multiplexerEnvEnabled(env.TMUX) ||
+		multiplexerEnvEnabled(env.TMUX_PANE) ||
+		multiplexerEnvEnabled(env.STY) ||
+		multiplexerEnvEnabled(env.ZELLIJ) ||
+		multiplexerEnvEnabled(env.GJC_TMUX_LAUNCHED)
+	) {
+		return true;
+	}
+	const term = env.TERM?.trim().toLowerCase() ?? "";
+	return term.startsWith("tmux") || term.startsWith("screen");
+}
+
 let terminalGraphicsFallbackDepth = 0;
 let cursorNeutralImageAllowedDepth = 0;
 
@@ -105,6 +134,15 @@ function getForcedImageProtocol(): ImageProtocol | null | undefined {
 	return null;
 }
 
+/**
+ * Returns whether PI_FORCE_IMAGE_PROTOCOL explicitly configures the image
+ * protocol, including an explicit "off". An explicit configuration is
+ * authoritative: runtime capability probes must not override it.
+ */
+export function isImageProtocolForced(): boolean {
+	return getForcedImageProtocol() !== undefined;
+}
+
 function parseMajorMinorVersion(versionRaw?: string): { major: number; minor: number } | null {
 	if (!versionRaw) return null;
 	const match = /^(\d+)\.(\d+)/u.exec(versionRaw.trim());
@@ -137,7 +175,7 @@ function getFallbackImageProtocol(terminalId: TerminalId): ImageProtocol | null
 	if (!process.stdout.isTTY) return null;
 	if (terminalId === "vscode" || terminalId === "alacritty") return null;
 	const term = Bun.env.TERM?.toLowerCase() ?? "";
-	if (term.includes("screen") || term.includes("tmux") || term.includes("ghostty")) {
+	if (term.includes("ghostty")) {
 		return ImageProtocol.Kitty;
 	}
 	return null;
@@ -220,10 +258,10 @@ export const TERMINAL = (() => {
 			);
 		}
 	}
+	const underMultiplexer = isUnderTerminalMultiplexer();
 	// tmux and screen multiplexers do not reliably forward OSC 8 hyperlinks
 	// to the outer terminal, so force them off regardless of detected terminal.
-	const term = Bun.env.TERM?.toLowerCase() ?? "";
-	if (resolved.hyperlinks && (Bun.env.TMUX || term.startsWith("tmux") || term.startsWith("screen"))) {
+	if (resolved.hyperlinks && underMultiplexer) {
 		resolved = new TerminalInfo(
 			resolved.id,
 			resolved.imageProtocol,
@@ -232,6 +270,17 @@ export const TERMINAL = (() => {
 			resolved.notifyProtocol,
 		);
 	}
+	// Multiplexers (tmux/screen/zellij) consume raw kitty/iTerm2 graphics
+	// escapes instead of forwarding them (no DCS passthrough wrapping is
+	// emitted), so a detected image protocol draws nothing while its
+	// out-of-band cursor writes corrupt the frame. Graphics are therefore
+	// unconditionally suppressed under a multiplexer; the runtime sixel probe
+	// never runs there (tmux advertises DA1 ";4" from compile-time support
+	// regardless of the attached client), and PI_FORCE_IMAGE_PROTOCOL=sixel
+	// is the only opt-in for chains that render sixel end-to-end.
+	if (resolved.imageProtocol && forcedImageProtocol === undefined && underMultiplexer) {
+		resolved = new TerminalInfo(resolved.id, null, resolved.trueColor, resolved.hyperlinks, resolved.notifyProtocol);
+	}
 	return resolved;
 })();
 
@@ -239,11 +288,35 @@ type MutableTerminalInfo = {
 	imageProtocol: ImageProtocol | null;
 };
 
+type ImageProtocolChangeListener = (imageProtocol: ImageProtocol | null) => void;
+const imageProtocolChangeListeners = new Set<ImageProtocolChangeListener>();
+
+/**
+ * Subscribe to runtime image-protocol changes (e.g. the asynchronous sixel
+ * capability probe enabling graphics after startup). Returns an unsubscribe
+ * function. Listeners fire only on actual changes.
+ */
+export function onImageProtocolChanged(listener: ImageProtocolChangeListener): () => void {
+	imageProtocolChangeListeners.add(listener);
+	return () => {
+		imageProtocolChangeListeners.delete(listener);
+	};
+}
+
 /**
  * Override terminal image protocol at runtime after capability probes complete.
  */
 export function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): void {
-	(TERMINAL as unknown as MutableTerminalInfo).imageProtocol = imageProtocol;
+	const mutable = TERMINAL as unknown as MutableTerminalInfo;
+	if (mutable.imageProtocol === imageProtocol) return;
+	mutable.imageProtocol = imageProtocol;
+	for (const listener of imageProtocolChangeListeners) {
+		try {
+			listener(imageProtocol);
+		} catch {
+			// Listener failures must not break protocol switching.
+		}
+	}
 }
 
 export function getTerminalInfo(terminalId: TerminalId): TerminalInfo {

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

@@ -9,7 +9,14 @@ import { getKeybindings } from "./keybindings";
 import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
 import type { Terminal } from "./terminal";
-import { ImageProtocol, setCellDimensions, setTerminalImageProtocol, TERMINAL } from "./terminal-capabilities";
+import {
+	ImageProtocol,
+	isImageProtocolForced,
+	isUnderTerminalMultiplexer,
+	setCellDimensions,
+	setTerminalImageProtocol,
+	TERMINAL,
+} from "./terminal-capabilities";
 import {
 	Ellipsis,
 	extractSegments,
@@ -217,7 +224,6 @@ function isTermuxSession(env: Record<string, string | undefined> = Bun.env): boo
 	return Boolean(env.TERMUX_VERSION);
 }
 
-const GJC_TMUX_LAUNCHED_ENV = "GJC_TMUX_LAUNCHED";
 const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "no"]);
 const TRUTHY_ENV_VALUES = new Set(["1", "true", "yes", "on", "y"]);
 
@@ -231,25 +237,38 @@ function envFlagEnabled(value: string | undefined): boolean {
 	return normalized !== undefined && TRUTHY_ENV_VALUES.has(normalized);
 }
 
-function termLooksMultiplexed(value: string | undefined): boolean {
-	const term = value?.trim().toLowerCase() ?? "";
-	return term.startsWith("tmux") || term.startsWith("screen");
-}
-
 function isWindowsTerminalSession(env: Record<string, string | undefined> = Bun.env): boolean {
 	return envIsEnabled(env.WT_SESSION) || env.TERM_PROGRAM === "Windows_Terminal";
 }
 
-/** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
+/**
+ * Detect terminal multiplexers where scrollback clearing and height-change
+ * redraws are hostile. Delegates to the shared capability predicate so the
+ * renderer and graphics-protocol selection agree on what counts as a
+ * multiplexed host.
+ */
 function isMultiplexerSession(env: Record<string, string | undefined> = Bun.env): boolean {
-	return Boolean(
-		envIsEnabled(env.TMUX) ||
-			envIsEnabled(env.TMUX_PANE) ||
-			envIsEnabled(env.STY) ||
-			envIsEnabled(env.ZELLIJ) ||
-			envIsEnabled(env[GJC_TMUX_LAUNCHED_ENV]) ||
-			termLooksMultiplexed(env.TERM),
-	);
+	return isUnderTerminalMultiplexer(env as NodeJS.ProcessEnv);
+}
+
+/**
+ * Startup sixel capability probe policy (pure; exported for tests):
+ * - Never probe when PI_FORCE_IMAGE_PROTOCOL is set — an explicit
+ *   configuration (including "off") is authoritative.
+ * - Never probe inside a terminal multiplexer: tmux advertises DA1 ";4"
+ *   whenever it was compiled with sixel support, regardless of whether the
+ *   attached client terminal can render sixel, so a positive reply is not
+ *   end-to-end evidence. Graphics under a multiplexer are strictly opt-in
+ *   via PI_FORCE_IMAGE_PROTOCOL=sixel.
+ * - Probe Windows Terminal (>=1.22 renders sixel but exposes no env marker).
+ */
+export function shouldProbeSixelCapability(
+	env: NodeJS.ProcessEnv = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (isImageProtocolForced()) return false;
+	if (isUnderTerminalMultiplexer(env)) return false;
+	return platform === "win32" && Boolean(env.WT_SESSION?.trim());
 }
 
 function useLegacyMultiplexerFullRender(env: Record<string, string | undefined> = Bun.env): boolean {
@@ -260,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,
 	});
 }
 
@@ -300,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);
 }
 
 /**
@@ -599,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 = {
@@ -943,6 +974,7 @@ export class TUI extends Container {
 				this.requestResizeRender();
 			},
 		);
+		this.flushTerminalCleanup();
 		this.#hideCursor();
 		this.#querySixelSupport();
 		this.#queryCellSize();
@@ -1008,8 +1040,7 @@ export class TUI extends Container {
 
 	#querySixelSupport(): void {
 		if (TERMINAL.imageProtocol) return;
-		if (process.platform !== "win32") return;
-		if (!Bun.env.WT_SESSION) return;
+		if (!this.#isSixelProbeCandidate()) return;
 		if (!process.stdin.isTTY || !process.stdout.isTTY) return;
 
 		this.#clearSixelProbeState();
@@ -1023,6 +1054,10 @@ export class TUI extends Container {
 		}, 250);
 	}
 
+	#isSixelProbeCandidate(): boolean {
+		return shouldProbeSixelCapability();
+	}
+
 	#handleSixelProbeInput(data: string): InputListenerResult {
 		if (!this.#sixelProbePendingDa && !this.#sixelProbePendingGraphics) {
 			return undefined;
@@ -1049,11 +1084,15 @@ export class TUI extends Container {
 
 			if (useDa && this.#sixelProbePendingDa) {
 				this.#sixelProbePendingDa = false;
-				const attributes = (match[1] ?? "")
+				const params = (match[1] ?? "")
 					.split(";")
 					.map(value => Number.parseInt(value, 10))
 					.filter(value => Number.isFinite(value));
-				const hasSixelAttribute = attributes.includes(4);
+				// The first DA1 parameter is the device/operating class (e.g. 1,
+				// 62, 64), not an extension attribute: `CSI ?4;6c` identifies a
+				// VT132, it does not advertise sixel. Only the parameters after
+				// the class carry attributes like 4 (sixel graphics).
+				const hasSixelAttribute = params.slice(1).includes(4);
 				if (hasSixelAttribute) {
 					this.#sixelProbePendingGraphics = false;
 					probeOutcome = true;
@@ -1062,8 +1101,11 @@ export class TUI extends Container {
 				}
 			} else if (!useDa && this.#sixelProbePendingGraphics) {
 				this.#sixelProbePendingGraphics = false;
+				// XTSMGRAPHICS reply is `CSI ? 2 ; Ps ; ... S` where Ps=0 means
+				// success and 1/2/3 are errors (tmux answers our unsupported
+				// read with `CSI ?2;3;0S`). Only a success reply proves sixel.
 				const status = Number.parseInt(match[1] ?? "", 10);
-				const supportsSixel = !Number.isNaN(status) && status !== 0;
+				const supportsSixel = status === 0;
 				if (supportsSixel) {
 					this.#sixelProbePendingDa = false;
 					probeOutcome = true;
@@ -1142,6 +1184,7 @@ export class TUI extends Container {
 	}
 
 	stop(): void {
+		this.flushTerminalCleanup();
 		this.#clearSixelProbeState();
 		this.#stopped = true;
 		if (this.#renderTimer) {
@@ -1200,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 {
@@ -2245,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
@@ -2304,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)
@@ -2551,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).