@sayknow-cli/tui 0.4.4 → 0.4.6

package/dist/types/components/sayknow-pet.d.ts

@@ -124,5 +124,10 @@ export declare function buildSayknowPixelFrames(options: {
     kittyImageId?: number;
     /** Color skin for the sprite palette (default "red"). */
     skin?: PetSkinId;
+    /**
+     * Optional wrapper applied to each encoded sixel frame (e.g. tmux DCS
+     * passthrough). Identity when omitted. Never applied to kitty frames.
+     */
+    wrapSixel?: (frame: string) => string;
 }): SayknowPixelFrames;
 export {};

package/dist/types/terminal-capabilities.d.ts

@@ -58,6 +58,26 @@ export declare function isCursorNeutralImagePermittedInFallback(): boolean;
  * authoritative: runtime capability probes must not override it.
  */
 export declare function isImageProtocolForced(): boolean;
+/**
+ * Returns whether the sixel-through-multiplexer path (passthrough-wrapped probe
+ * + DCS passthrough render) is enabled. On by default; set SKC_SIXEL_MULTIPLEXER=0
+ * to force the pre-0.4.5 behavior (graphics unconditionally off under tmux).
+ */
+export declare function isSixelMultiplexerEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Returns whether the process runs under tmux specifically. Only tmux implements
+ * the DCS passthrough envelope (`\ePtmux;…\e\\`) that forwards graphics escapes to
+ * the outer terminal, so sixel graphics stay suppressed under screen/zellij.
+ */
+export declare function isUnderTmux(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Wrap raw terminal escape bytes in tmux's DCS passthrough envelope so tmux
+ * forwards them verbatim to the outer terminal (requires `allow-passthrough on`,
+ * which SKC-launched tmux sessions set automatically). Each ESC in the payload is
+ * doubled per the tmux protocol. Returns the payload unchanged when not under
+ * tmux, so non-multiplexed, screen, and zellij paths are untouched.
+ */
+export declare function wrapTmuxPassthrough(payload: string, env?: NodeJS.ProcessEnv): string;
 /**
  * Returns true when running in Windows Terminal with known SIXEL support.
  *

package/dist/types/tui.d.ts

@@ -125,11 +125,10 @@ 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.
+ * - Under tmux, probe when the sixel-multiplexer path is enabled (default): the
+ *   query is DCS-passthrough wrapped so the OUTER terminal answers, not tmux's
+ *   unreliable compile-time DA1, making a positive reply genuine end-to-end
+ *   evidence. screen/zellij have no passthrough envelope, so graphics stay off.
  * - Probe Windows Terminal (>=1.22 renders sixel but exposes no env marker).
  */
 export declare function shouldProbeSixelCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.4.4",
+	"version": "0.4.6",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.4.4",
-		"@sayknow-cli/utils": "0.4.4",
+		"@sayknow-cli/natives": "0.4.6",
+		"@sayknow-cli/utils": "0.4.6",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/sayknow-pet.ts

@@ -392,6 +392,11 @@ export function buildSayknowPixelFrames(options: {
 	kittyImageId?: number;
 	/** Color skin for the sprite palette (default "red"). */
 	skin?: PetSkinId;
+	/**
+	 * Optional wrapper applied to each encoded sixel frame (e.g. tmux DCS
+	 * passthrough). Identity when omitted. Never applied to kitty frames.
+	 */
+	wrapSixel?: (frame: string) => string;
 }): SayknowPixelFrames {
 	const targetRows = options.targetRows ?? 2;
 	const gridSize = 16;
@@ -416,7 +421,7 @@ export function buildSayknowPixelFrames(options: {
 	for (const name of Object.keys(PIXEL_GRIDS) as SayknowPixelFrameName[]) {
 		frames[name] =
 			options.protocol === "sixel"
-				? encodeGridSixel(PIXEL_GRIDS[name], scale, topPaddingPx, palette)
+				? (options.wrapSixel ?? (frame => frame))(encodeGridSixel(PIXEL_GRIDS[name], scale, topPaddingPx, palette))
 				: encodeGridKitty(
 						PIXEL_GRIDS[name],
 						scale,

package/src/terminal-capabilities.ts

@@ -143,6 +143,45 @@ export function isImageProtocolForced(): boolean {
 	return getForcedImageProtocol() !== undefined;
 }
 
+const SIXEL_MULTIPLEXER_DISABLED_ENV_VALUES = new Set(["0", "off", "false", "no"]);
+
+/**
+ * Returns whether the sixel-through-multiplexer path (passthrough-wrapped probe
+ * + DCS passthrough render) is enabled. On by default; set SKC_SIXEL_MULTIPLEXER=0
+ * to force the pre-0.4.5 behavior (graphics unconditionally off under tmux).
+ */
+export function isSixelMultiplexerEnabled(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	const raw = env.SKC_SIXEL_MULTIPLEXER?.trim().toLowerCase();
+	return raw === undefined || raw === "" || !SIXEL_MULTIPLEXER_DISABLED_ENV_VALUES.has(raw);
+}
+
+/**
+ * Returns whether the process runs under tmux specifically. Only tmux implements
+ * the DCS passthrough envelope (`\ePtmux;…\e\\`) that forwards graphics escapes to
+ * the outer terminal, so sixel graphics stay suppressed under screen/zellij.
+ */
+export function isUnderTmux(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (
+		multiplexerEnvEnabled(env.TMUX) ||
+		multiplexerEnvEnabled(env.TMUX_PANE) ||
+		multiplexerEnvEnabled(env.SKC_TMUX_LAUNCHED)
+	)
+		return true;
+	return (env.TERM?.trim().toLowerCase() ?? "").startsWith("tmux");
+}
+
+/**
+ * Wrap raw terminal escape bytes in tmux's DCS passthrough envelope so tmux
+ * forwards them verbatim to the outer terminal (requires `allow-passthrough on`,
+ * which SKC-launched tmux sessions set automatically). Each ESC in the payload is
+ * doubled per the tmux protocol. Returns the payload unchanged when not under
+ * tmux, so non-multiplexed, screen, and zellij paths are untouched.
+ */
+export function wrapTmuxPassthrough(payload: string, env: NodeJS.ProcessEnv = Bun.env): string {
+	if (!payload || !isUnderTmux(env)) return payload;
+	return `\x1bPtmux;${payload.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
+}
+
 function parseMajorMinorVersion(versionRaw?: string): { major: number; minor: number } | null {
 	if (!versionRaw) return null;
 	const match = /^(\d+)\.(\d+)/u.exec(versionRaw.trim());
@@ -767,8 +806,10 @@ export function renderImage(
 			const targetWidthPx = Math.max(1, fit.columns * cellDims.widthPx);
 			const targetHeightPx = Math.max(1, fit.rows * cellDims.heightPx);
 			const decoded = new Uint8Array(Buffer.from(base64Data, "base64"));
-			const sequence = encodeSixel(decoded, targetWidthPx, targetHeightPx);
-			return { sequence, rows: fit.rows };
+			const raster = encodeSixel(decoded, targetWidthPx, targetHeightPx);
+			// Under tmux, forward the raster to the outer terminal via the DCS
+			// passthrough envelope (no-op when not under tmux).
+			return { sequence: wrapTmuxPassthrough(raster), rows: fit.rows };
 		} catch {
 			return null;
 		}

package/src/tui.ts

@@ -12,10 +12,13 @@ import type { Terminal } from "./terminal";
 import {
 	ImageProtocol,
 	isImageProtocolForced,
+	isSixelMultiplexerEnabled,
 	isUnderTerminalMultiplexer,
+	isUnderTmux,
 	setCellDimensions,
 	setTerminalImageProtocol,
 	TERMINAL,
+	wrapTmuxPassthrough,
 } from "./terminal-capabilities";
 import {
 	Ellipsis,
@@ -296,11 +299,10 @@ function isMultiplexerSession(env: Record<string, string | undefined> = Bun.env)
  * 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.
+ * - Under tmux, probe when the sixel-multiplexer path is enabled (default): the
+ *   query is DCS-passthrough wrapped so the OUTER terminal answers, not tmux's
+ *   unreliable compile-time DA1, making a positive reply genuine end-to-end
+ *   evidence. screen/zellij have no passthrough envelope, so graphics stay off.
  * - Probe Windows Terminal (>=1.22 renders sixel but exposes no env marker).
  */
 export function shouldProbeSixelCapability(
@@ -308,7 +310,7 @@ export function shouldProbeSixelCapability(
 	platform: NodeJS.Platform = process.platform,
 ): boolean {
 	if (isImageProtocolForced()) return false;
-	if (isUnderTerminalMultiplexer(env)) return false;
+	if (isUnderTerminalMultiplexer(env)) return isUnderTmux(env) && isSixelMultiplexerEnabled(env);
 	return platform === "win32" && Boolean(env.WT_SESSION?.trim());
 }
 
@@ -1145,11 +1147,16 @@ export class TUI extends Container {
 		this.#sixelProbePendingDa = true;
 		this.#sixelProbePendingGraphics = true;
 		this.#sixelProbeUnsubscribe = this.addInputListener(data => this.#handleSixelProbeInput(data));
-		if (!this.#writeTerminal("\x1b[c")) return;
-		if (!this.#writeTerminal("\x1b[?2;1;0S")) return;
-		this.#sixelProbeTimeout = setTimeout(() => {
-			this.#finishSixelProbe(false);
-		}, 250);
+		// Under tmux, wrap the DA1 + XTSMGRAPHICS queries in the DCS passthrough
+		// envelope so the outer terminal answers instead of tmux itself. Round-trip
+		// through the outer terminal is slower, so allow a longer settle window.
+		if (!this.#writeTerminal(wrapTmuxPassthrough("\x1b[c\x1b[?2;1;0S"))) return;
+		this.#sixelProbeTimeout = setTimeout(
+			() => {
+				this.#finishSixelProbe(false);
+			},
+			isUnderTmux() ? 600 : 250,
+		);
 	}
 
 	#isSixelProbeCandidate(): boolean {
@@ -1276,9 +1283,12 @@ export class TUI extends Container {
 		if (!TERMINAL.imageProtocol) {
 			return;
 		}
-		// Query terminal for cell size in pixels: CSI 16 t
-		// Response format: CSI 6 ; height ; width t
-		this.#writeTerminal("\x1b[16t");
+		// Query terminal for cell size in pixels: CSI 16 t → CSI 6 ; height ; width t.
+		// Under tmux, wrap it in the DCS passthrough envelope so the OUTER terminal
+		// reports its real cell size; tmux otherwise answers with a wrong value,
+		// which oversizes the sixel pet and pushes it out of bounds (freezing its
+		// animation because the overflowing position resolves to null).
+		this.#writeTerminal(wrapTmuxPassthrough("\x1b[16t"));
 	}
 
 	stop(): void {