@gajae-code/tui 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-07-13
+### Fixed
+
+- 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/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/tui.d.ts

@@ -98,6 +98,18 @@ 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

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.10.0",
+	"version": "0.10.1",
 	"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.1",
+		"@gajae-code/utils": "0.10.1",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

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/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 {
@@ -1008,8 +1027,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 +1041,10 @@ export class TUI extends Container {
 		}, 250);
 	}
 
+	#isSixelProbeCandidate(): boolean {
+		return shouldProbeSixelCapability();
+	}
+
 	#handleSixelProbeInput(data: string): InputListenerResult {
 		if (!this.#sixelProbePendingDa && !this.#sixelProbePendingGraphics) {
 			return undefined;
@@ -1049,11 +1071,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 +1088,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;