@sayknow-cli/tui 0.5.1 → 0.5.2

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

@@ -64,6 +64,25 @@ export declare function isImageProtocolForced(): boolean;
  * to force the pre-0.4.5 behavior (graphics unconditionally off under tmux).
  */
 export declare function isSixelMultiplexerEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Returns whether the kitty-graphics-through-tmux path (passthrough-wrapped
+ * capability query + DCS passthrough overlay render) is enabled. On by default;
+ * set SKC_KITTY_MULTIPLEXER=0 to keep overlay graphics off under tmux for
+ * kitty-protocol terminals (Ghostty, kitty, WezTerm).
+ */
+export declare function isKittyMultiplexerEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Image id reserved for the kitty capability query. It is never placed, so a
+ * terminal that answers `OK` leaves nothing on screen.
+ */
+export declare const KITTY_PROBE_IMAGE_ID = 1936417537;
+/**
+ * Kitty graphics capability query: transmit one black RGB pixel with `a=q`
+ * (query only, never displayed). A terminal that implements the protocol
+ * answers `\x1b_Gi=<id>;OK\x1b\\`; one that does not stays silent, which is the
+ * end-to-end evidence tmux's own DA1 sixel claim can never provide.
+ */
+export declare const KITTY_CAPABILITY_QUERY = "\u001B_Gi=1936417537,s=1,v=1,a=q,t=d,f=24;AAAA\u001B\\";
 /**
  * Returns whether the process runs under tmux specifically. Only tmux implements
  * the DCS passthrough envelope (`\ePtmux;…\e\\`) that forwards graphics escapes to
@@ -81,6 +100,39 @@ export declare function wrapTmuxPassthrough(payload: string, env?: NodeJS.Proces
 export declare function tmuxOwnsSixel(env?: NodeJS.ProcessEnv): boolean;
 /** Testing seam: drop the cached tmux sixel-ownership answer. */
 export declare function resetTmuxSixelOwnershipCache(): void;
+/**
+ * Screen-absolute origin of this tmux pane: what has to be added to a
+ * pane-relative cell position to hit the same cell in the OUTER terminal.
+ *
+ * Passthrough payloads bypass tmux entirely, so a cursor-position escape inside
+ * the envelope addresses the outer terminal's screen, not the pane. Without the
+ * offset a split window or a top status line draws the overlay in the wrong
+ * place. tmux never repositions the real cursor before forwarding a passthrough
+ * payload (`tty_cmd_rawstring` only invalidates its cursor state), so absolute
+ * positioning inside the envelope is the only reliable placement.
+ *
+ * Cached because it shells out to tmux; every pane geometry change that matters
+ * also resizes the pane, and the TUI drops the cache on resize.
+ */
+export interface TmuxPaneOffset {
+    top: number;
+    left: number;
+}
+export declare function tmuxPaneOffset(env?: NodeJS.ProcessEnv): TmuxPaneOffset;
+/** Drop the cached pane origin (pane geometry changed, or a test needs a clean slate). */
+export declare function resetTmuxPaneOffsetCache(): void;
+/**
+ * Ask tmux to forward DCS passthrough for THIS pane.
+ *
+ * SKC-launched sessions already carry the option from their tmux profile, but a
+ * pane the user created by hand inherits the server default (`off`), and then
+ * every passthrough payload — including the capability query — is swallowed.
+ * `-p` keeps the change pane-local (never global server state) and `-q` stays
+ * quiet on tmux < 3.3 where the option does not exist. Runs at most once.
+ */
+export declare function enableTmuxPanePassthrough(env?: NodeJS.ProcessEnv): boolean;
+/** Testing seam: allow the pane passthrough request to run again. */
+export declare function resetTmuxPanePassthroughRequest(): void;
 /**
  * Returns true when running in Windows Terminal with known SIXEL support.
  *
@@ -100,6 +152,16 @@ export declare function onImageProtocolChanged(listener: ImageProtocolChangeList
  * Override terminal image protocol at runtime after capability probes complete.
  */
 export declare function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): void;
+/**
+ * Protocol available for absolutely-positioned overlays that reach the outer
+ * terminal through tmux's DCS passthrough envelope, when inline graphics are
+ * suppressed by the multiplexer. Set by the startup capability probes on proof
+ * that the outer terminal answered end to end; never inferred from env vars.
+ */
+export declare function getTmuxOverlayImageProtocol(): ImageProtocol | null;
+export declare function setTmuxOverlayImageProtocol(imageProtocol: ImageProtocol | null): void;
+/** Effective protocol for overlay drawing: inline graphics first, passthrough second. */
+export declare function getOverlayImageProtocol(): ImageProtocol | null;
 export declare function getTerminalInfo(terminalId: TerminalId): TerminalInfo;
 export interface CellDimensions {
     widthPx: number;

package/dist/types/tui.d.ts

@@ -130,16 +130,27 @@ export interface OverlayMargin {
 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
+ * - Never probe when SKC_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 through the DCS passthrough envelope: the query reaches
+ *   the OUTER terminal, so its DA1 ";4" is genuine end-to-end evidence. A bare
+ *   query would only reach tmux, which advertises sixel whenever it was
+ *   compiled with support, regardless of the attached client.
+ * - Never probe under screen/zellij: no passthrough envelope exists there, so
+ *   no answer can be trusted and nothing can be drawn anyway.
  * - Probe Windows Terminal (>=1.22 renders sixel but exposes no env marker).
  */
 export declare function shouldProbeSixelCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * Startup kitty-graphics probe policy for tmux panes (pure; exported for tests).
+ *
+ * Kitty-protocol terminals (Ghostty, kitty, WezTerm) never answer a sixel query,
+ * so the sixel probe alone leaves them without graphics inside tmux. The kitty
+ * capability query has the property the sixel path lacks: tmux itself does not
+ * implement the protocol and cannot fake the reply, so an `OK` coming back
+ * through passthrough proves the outer terminal drew it.
+ */
+export declare function shouldProbeKittyPassthrough(env?: NodeJS.ProcessEnv): boolean;
 /**
  * True when repainting only the live viewport is safer than clearing/replaying
  * the full transcript. Real process terminals are viewport-sensitive because

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.5.1",
+	"version": "0.5.2",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -38,14 +38,15 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.5.1",
-		"@sayknow-cli/utils": "0.5.1",
+		"@sayknow-cli/natives": "0.5.2",
+		"@sayknow-cli/utils": "0.5.2",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},
 	"devDependencies": {
 		"chalk": "^5.6.2",
-		"@xterm/headless": "^6.0.0"
+		"@xterm/headless": "^6.0.0",
+		"node-pty": "^1.0.0"
 	},
 	"engines": {
 		"bun": ">=1.3.14"

package/src/components/settings-list.ts

@@ -213,9 +213,12 @@ export class SettingsList implements Component {
 
 	#closeSubmenu(): void {
 		this.#submenuComponent = null;
-		// Restore selection to the item that opened the submenu
+		// Restore selection to the item that opened the submenu. `setItems` leaves an
+		// open submenu untouched, so the list may have shrunk past that index while it
+		// was open — clamp or the restored selection points at nothing and the main
+		// list renders with no cursor at all.
 		if (this.#submenuItemIndex !== null) {
-			this.#selectedIndex = this.#submenuItemIndex;
+			this.#selectedIndex = Math.min(this.#submenuItemIndex, Math.max(0, this.#items.length - 1));
 			this.#submenuItemIndex = null;
 			this.#notifySelectionChange();
 		}

package/src/terminal-capabilities.ts

@@ -143,7 +143,7 @@ export function isImageProtocolForced(): boolean {
 	return getForcedImageProtocol() !== undefined;
 }
 
-const SIXEL_MULTIPLEXER_DISABLED_ENV_VALUES = new Set(["0", "off", "false", "no"]);
+const MULTIPLEXER_GRAPHICS_DISABLED_ENV_VALUES = new Set(["0", "off", "false", "no"]);
 
 /**
  * Returns whether the sixel-through-multiplexer path (passthrough-wrapped probe
@@ -152,9 +152,34 @@ const SIXEL_MULTIPLEXER_DISABLED_ENV_VALUES = new Set(["0", "off", "false", "no"
  */
 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);
+	return raw === undefined || raw === "" || !MULTIPLEXER_GRAPHICS_DISABLED_ENV_VALUES.has(raw);
 }
 
+/**
+ * Returns whether the kitty-graphics-through-tmux path (passthrough-wrapped
+ * capability query + DCS passthrough overlay render) is enabled. On by default;
+ * set SKC_KITTY_MULTIPLEXER=0 to keep overlay graphics off under tmux for
+ * kitty-protocol terminals (Ghostty, kitty, WezTerm).
+ */
+export function isKittyMultiplexerEnabled(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	const raw = env.SKC_KITTY_MULTIPLEXER?.trim().toLowerCase();
+	return raw === undefined || raw === "" || !MULTIPLEXER_GRAPHICS_DISABLED_ENV_VALUES.has(raw);
+}
+
+/**
+ * Image id reserved for the kitty capability query. It is never placed, so a
+ * terminal that answers `OK` leaves nothing on screen.
+ */
+export const KITTY_PROBE_IMAGE_ID = 0x736b_6301;
+
+/**
+ * Kitty graphics capability query: transmit one black RGB pixel with `a=q`
+ * (query only, never displayed). A terminal that implements the protocol
+ * answers `\x1b_Gi=<id>;OK\x1b\\`; one that does not stays silent, which is the
+ * end-to-end evidence tmux's own DA1 sixel claim can never provide.
+ */
+export const KITTY_CAPABILITY_QUERY = `\x1b_Gi=${KITTY_PROBE_IMAGE_ID},s=1,v=1,a=q,t=d,f=24;AAAA\x1b\\`;
+
 /**
  * Returns whether the process runs under tmux specifically. Only tmux implements
  * the DCS passthrough envelope (`\ePtmux;…\e\\`) that forwards graphics escapes to
@@ -222,6 +247,113 @@ export function resetTmuxSixelOwnershipCache(): void {
 	tmuxSixelOwnershipCache = undefined;
 }
 
+/**
+ * Screen-absolute origin of this tmux pane: what has to be added to a
+ * pane-relative cell position to hit the same cell in the OUTER terminal.
+ *
+ * Passthrough payloads bypass tmux entirely, so a cursor-position escape inside
+ * the envelope addresses the outer terminal's screen, not the pane. Without the
+ * offset a split window or a top status line draws the overlay in the wrong
+ * place. tmux never repositions the real cursor before forwarding a passthrough
+ * payload (`tty_cmd_rawstring` only invalidates its cursor state), so absolute
+ * positioning inside the envelope is the only reliable placement.
+ *
+ * Cached because it shells out to tmux; every pane geometry change that matters
+ * also resizes the pane, and the TUI drops the cache on resize.
+ */
+export interface TmuxPaneOffset {
+	top: number;
+	left: number;
+}
+const NO_PANE_OFFSET: TmuxPaneOffset = Object.freeze({ top: 0, left: 0 });
+let tmuxPaneOffsetCache: TmuxPaneOffset | undefined;
+
+function parseStatusLines(raw: string | undefined): number {
+	const value = raw?.trim().toLowerCase() ?? "";
+	if (value === "on") return 1;
+	if (value === "off" || value === "") return 0;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export function tmuxPaneOffset(env: NodeJS.ProcessEnv = Bun.env): TmuxPaneOffset {
+	if (!isUnderTmux(env)) return NO_PANE_OFFSET;
+	if (tmuxPaneOffsetCache) return tmuxPaneOffsetCache;
+	let offset = NO_PANE_OFFSET;
+	try {
+		const probe = Bun.spawnSync({
+			cmd: [
+				env.SKC_TMUX_COMMAND?.trim() || "tmux",
+				"display",
+				"-p",
+				// Status lines only shift the window down when they sit on top.
+				"#{pane_top} #{pane_left} #{?#{==:#{status-position},top},#{status},0}",
+			],
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		if (probe.success) {
+			const [topRaw, leftRaw, statusRaw] = new TextDecoder().decode(probe.stdout).trim().split(/\s+/u);
+			const top = Number.parseInt(topRaw ?? "", 10);
+			const left = Number.parseInt(leftRaw ?? "", 10);
+			offset = {
+				top: (Number.isFinite(top) && top > 0 ? top : 0) + parseStatusLines(statusRaw),
+				left: Number.isFinite(left) && left > 0 ? left : 0,
+			};
+		}
+	} catch {
+		offset = NO_PANE_OFFSET;
+	}
+	tmuxPaneOffsetCache = offset;
+	return offset;
+}
+
+/** Drop the cached pane origin (pane geometry changed, or a test needs a clean slate). */
+export function resetTmuxPaneOffsetCache(): void {
+	tmuxPaneOffsetCache = undefined;
+}
+
+let tmuxPanePassthroughRequested = false;
+
+/**
+ * Ask tmux to forward DCS passthrough for THIS pane.
+ *
+ * SKC-launched sessions already carry the option from their tmux profile, but a
+ * pane the user created by hand inherits the server default (`off`), and then
+ * every passthrough payload — including the capability query — is swallowed.
+ * `-p` keeps the change pane-local (never global server state) and `-q` stays
+ * quiet on tmux < 3.3 where the option does not exist. Runs at most once.
+ */
+export function enableTmuxPanePassthrough(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (!isUnderTmux(env)) return false;
+	if (tmuxPanePassthroughRequested) return true;
+	tmuxPanePassthroughRequested = true;
+	try {
+		const target = env.TMUX_PANE?.trim();
+		Bun.spawnSync({
+			cmd: [
+				env.SKC_TMUX_COMMAND?.trim() || "tmux",
+				"set-option",
+				"-pq",
+				...(target ? ["-t", target] : []),
+				"allow-passthrough",
+				"on",
+			],
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+	} catch {
+		// tmux missing or refusing the option: the probe simply gets no answer
+		// and graphics stay off, which is the correct conservative outcome.
+	}
+	return true;
+}
+
+/** Testing seam: allow the pane passthrough request to run again. */
+export function resetTmuxPanePassthroughRequest(): void {
+	tmuxPanePassthroughRequested = false;
+}
+
 function parseMajorMinorVersion(versionRaw?: string): { major: number; minor: number } | null {
 	if (!versionRaw) return null;
 	const match = /^(\d+)\.(\d+)/u.exec(versionRaw.trim());
@@ -350,13 +482,15 @@ export const TERMINAL = (() => {
 		);
 	}
 	// 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.
+	// escapes instead of forwarding them, so an inline image protocol draws
+	// nothing while its out-of-band cursor writes corrupt the frame. Inline
+	// graphics stay suppressed under a multiplexer; only an explicit
+	// SKC_FORCE_IMAGE_PROTOCOL opts back in.
+	//
+	// Absolutely-positioned OVERLAYS are a separate channel: they can be
+	// smuggled to the outer terminal through tmux's DCS passthrough envelope
+	// with their own cursor addressing, so the runtime probes enable them via
+	// setTmuxOverlayImageProtocol() instead of touching TERMINAL.imageProtocol.
 	if (resolved.imageProtocol && forcedImageProtocol === undefined && underMultiplexer) {
 		resolved = new TerminalInfo(resolved.id, null, resolved.trueColor, resolved.hyperlinks, resolved.notifyProtocol);
 	}
@@ -389,6 +523,10 @@ export function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): v
 	const mutable = TERMINAL as unknown as MutableTerminalInfo;
 	if (mutable.imageProtocol === imageProtocol) return;
 	mutable.imageProtocol = imageProtocol;
+	notifyImageProtocolChanged(imageProtocol);
+}
+
+function notifyImageProtocolChanged(imageProtocol: ImageProtocol | null): void {
 	for (const listener of imageProtocolChangeListeners) {
 		try {
 			listener(imageProtocol);
@@ -398,6 +536,32 @@ export function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): v
 	}
 }
 
+let tmuxOverlayImageProtocol: ImageProtocol | null = null;
+
+/**
+ * Protocol available for absolutely-positioned overlays that reach the outer
+ * terminal through tmux's DCS passthrough envelope, when inline graphics are
+ * suppressed by the multiplexer. Set by the startup capability probes on proof
+ * that the outer terminal answered end to end; never inferred from env vars.
+ */
+export function getTmuxOverlayImageProtocol(): ImageProtocol | null {
+	return tmuxOverlayImageProtocol;
+}
+
+export function setTmuxOverlayImageProtocol(imageProtocol: ImageProtocol | null): void {
+	if (tmuxOverlayImageProtocol === imageProtocol) return;
+	tmuxOverlayImageProtocol = imageProtocol;
+	// Overlay owners (the pet) subscribe through the same channel: for them a
+	// passthrough overlay protocol arriving late is the same event as inline
+	// graphics arriving late.
+	notifyImageProtocolChanged(imageProtocol);
+}
+
+/** Effective protocol for overlay drawing: inline graphics first, passthrough second. */
+export function getOverlayImageProtocol(): ImageProtocol | null {
+	return TERMINAL.imageProtocol ?? tmuxOverlayImageProtocol;
+}
+
 export function getTerminalInfo(terminalId: TerminalId): TerminalInfo {
 	return KNOWN_TERMINALS[terminalId];
 }
@@ -847,9 +1011,23 @@ export function renderImage(
 			const targetHeightPx = Math.max(1, fit.rows * cellDims.heightPx);
 			const decoded = new Uint8Array(Buffer.from(base64Data, "base64"));
 			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 };
+			// An INLINE image has no cursor addressing of its own: it is drawn wherever
+			// the cursor currently sits. That only works when the multiplexer is the one
+			// placing it.
+			//
+			// tmux 3.4+ with the sixel terminal-feature parses the raster into its own
+			// screen model, so it owns the placement and every later scroll / erase /
+			// resize moves or clears the image with the text around it.
+			if (!isUnderTmux() || tmuxOwnsSixel()) return { sequence: raster, rows: fit.rows };
+			// Otherwise the only route out is DCS passthrough, which writes pixels
+			// straight into the OUTER terminal's image plane at its PHYSICAL cursor.
+			// tmux neither positions that cursor for the pane nor records the pixels, so
+			// inline passthrough lands in the wrong row and survives every repaint —
+			// transcript images pile up over the text and never clear. The absolutely
+			// positioned overlay channel (the pet) carries its own coordinates and is
+			// the only inline-free user of passthrough. A text placeholder beats an
+			// image welded to the wrong part of the screen.
+			return null;
 		} catch {
 			return null;
 		}

package/src/tui.ts

@@ -10,12 +10,22 @@ import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
 import type { Terminal } from "./terminal";
 import {
+	enableTmuxPanePassthrough,
+	getTmuxOverlayImageProtocol,
 	ImageProtocol,
 	isImageProtocolForced,
+	isKittyMultiplexerEnabled,
+	isSixelMultiplexerEnabled,
 	isUnderTerminalMultiplexer,
+	isUnderTmux,
+	KITTY_CAPABILITY_QUERY,
+	KITTY_PROBE_IMAGE_ID,
+	resetTmuxPaneOffsetCache,
 	setCellDimensions,
 	setTerminalImageProtocol,
+	setTmuxOverlayImageProtocol,
 	TERMINAL,
+	wrapTmuxPassthrough,
 } from "./terminal-capabilities";
 import {
 	Ellipsis,
@@ -321,13 +331,14 @@ 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
+ * - Never probe when SKC_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 through the DCS passthrough envelope: the query reaches
+ *   the OUTER terminal, so its DA1 ";4" is genuine end-to-end evidence. A bare
+ *   query would only reach tmux, which advertises sixel whenever it was
+ *   compiled with support, regardless of the attached client.
+ * - Never probe under screen/zellij: no passthrough envelope exists there, so
+ *   no answer can be trusted and nothing can be drawn anyway.
  * - Probe Windows Terminal (>=1.22 renders sixel but exposes no env marker).
  */
 export function shouldProbeSixelCapability(
@@ -335,10 +346,25 @@ 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());
 }
 
+/**
+ * Startup kitty-graphics probe policy for tmux panes (pure; exported for tests).
+ *
+ * Kitty-protocol terminals (Ghostty, kitty, WezTerm) never answer a sixel query,
+ * so the sixel probe alone leaves them without graphics inside tmux. The kitty
+ * capability query has the property the sixel path lacks: tmux itself does not
+ * implement the protocol and cannot fake the reply, so an `OK` coming back
+ * through passthrough proves the outer terminal drew it.
+ */
+export function shouldProbeKittyPassthrough(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (isImageProtocolForced()) return false;
+	if (!isUnderTmux(env)) return false;
+	return isKittyMultiplexerEnabled(env);
+}
+
 function useLegacyMultiplexerFullRender(env: Record<string, string | undefined> = Bun.env): boolean {
 	return envFlagEnabled(env.PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER);
 }
@@ -709,6 +735,10 @@ export class TUI extends Container {
 	#sixelProbeBuffer = "";
 	#sixelProbeTimeout?: NodeJS.Timeout;
 	#sixelProbeUnsubscribe?: () => void;
+	#kittyProbePending = false;
+	#kittyProbeBuffer = "";
+	#kittyProbeTimeout?: NodeJS.Timeout;
+	#kittyProbeUnsubscribe?: () => void;
 	#showHardwareCursor = $pickflag("SKC_HARDWARE_CURSOR", "PI_HARDWARE_CURSOR");
 	#debugRedraw = TUI.#readDebugRedrawFlag();
 	// macOS: steady-block cursor anchors CJK IME overlays; disable with SKC_TUI_IME_CURSOR=0.
@@ -1294,12 +1324,16 @@ export class TUI extends Container {
 		this.terminal.start(
 			data => this.#handleInput(data),
 			() => {
+				// A resize can also mean the pane moved or split: passthrough
+				// overlays address the outer screen, so their pane origin is stale.
+				resetTmuxPaneOffsetCache();
 				this.invalidate();
 				this.requestResizeRender();
 			},
 		);
 		this.flushTerminalCleanup();
 		this.#hideCursor();
+		this.#queryKittyPassthroughSupport();
 		this.#querySixelSupport();
 		this.#queryCellSize();
 		this.requestRender(true);
@@ -1423,17 +1457,128 @@ 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 both queries travel in ONE passthrough envelope so the outer
+		// terminal answers for itself; tmux would otherwise answer for a client it
+		// knows nothing about. A pane that never had passthrough enabled swallows
+		// the payload silently, hence the request first.
+		if (isUnderTmux()) enableTmuxPanePassthrough();
+		if (!this.#writeTerminal(wrapTmuxPassthrough("\x1b[c\x1b[?2;1;0S"))) return;
+		this.#sixelProbeTimeout = setTimeout(
+			() => {
+				this.#finishSixelProbe(false);
+			},
+			// The passthrough round trip adds tmux's own input latency on top of the
+			// outer terminal's reply time.
+			isUnderTmux() ? 600 : 250,
+		);
 	}
 
 	#isSixelProbeCandidate(): boolean {
 		return shouldProbeSixelCapability();
 	}
 
+	/**
+	 * Ask the terminal attached to this tmux client whether it speaks the kitty
+	 * graphics protocol, through the passthrough envelope.
+	 *
+	 * Unlike sixel there is no way for tmux to answer on the terminal's behalf:
+	 * tmux does not implement kitty graphics, so a reply can only come from the
+	 * outer terminal that received the forwarded query. Success enables the
+	 * passthrough OVERLAY channel (absolutely positioned, cursor-neutral art such
+	 * as the pet) and deliberately leaves inline image rendering suppressed,
+	 * since inline placements would land at tmux's stale physical cursor.
+	 */
+	#queryKittyPassthroughSupport(): void {
+		if (TERMINAL.imageProtocol || getTmuxOverlayImageProtocol()) return;
+		if (!shouldProbeKittyPassthrough()) return;
+		if (!process.stdin.isTTY || !process.stdout.isTTY) return;
+
+		this.#clearKittyProbeState();
+		this.#kittyProbePending = true;
+		this.#kittyProbeUnsubscribe = this.addInputListener(data => this.#handleKittyProbeInput(data));
+		enableTmuxPanePassthrough();
+		if (!this.#writeTerminal(wrapTmuxPassthrough(KITTY_CAPABILITY_QUERY))) return;
+		this.#kittyProbeTimeout = setTimeout(() => {
+			this.#finishKittyProbe(false);
+		}, 600);
+	}
+
+	/**
+	 * Consume the kitty graphics reply (`ESC _ G i=<id>;OK ESC \`) so it never
+	 * reaches the editor as keystrokes, and pass everything else through.
+	 */
+	#handleKittyProbeInput(data: string): InputListenerResult {
+		if (!this.#kittyProbePending) return undefined;
+
+		this.#kittyProbeBuffer += data;
+		let passthrough = "";
+		let probeOutcome: boolean | null = null;
+
+		while (this.#kittyProbeBuffer.length > 0) {
+			const match = this.#kittyProbeBuffer.match(/\x1b_G([^\x1b]*)\x1b\\/u);
+			if (!match || match.index === undefined) break;
+			passthrough += this.#kittyProbeBuffer.slice(0, match.index);
+			this.#kittyProbeBuffer = this.#kittyProbeBuffer.slice(match.index + match[0].length);
+			const body = match[1] ?? "";
+			const [keys, status] = body.split(";");
+			// Only our own probe id answers the capability question; any other
+			// graphics response is still swallowed rather than typed into the editor.
+			if (!(keys ?? "").split(",").includes(`i=${KITTY_PROBE_IMAGE_ID}`)) continue;
+			probeOutcome = (status ?? "").trim() === "OK";
+			break;
+		}
+
+		if (probeOutcome === null) {
+			// Hold back anything that could still become our reply; release the rest.
+			const start = this.#kittyProbeBuffer.indexOf("\x1b_G");
+			if (start >= 0) {
+				passthrough += this.#kittyProbeBuffer.slice(0, start);
+				this.#kittyProbeBuffer = this.#kittyProbeBuffer.slice(start);
+			} else {
+				const lastEsc = this.#kittyProbeBuffer.lastIndexOf("\x1b");
+				const tail = lastEsc >= 0 ? this.#kittyProbeBuffer.slice(lastEsc) : "";
+				if (tail && "\x1b_G".startsWith(tail)) {
+					passthrough += this.#kittyProbeBuffer.slice(0, lastEsc);
+					this.#kittyProbeBuffer = tail;
+				} else {
+					passthrough += this.#kittyProbeBuffer;
+					this.#kittyProbeBuffer = "";
+				}
+			}
+		} else {
+			passthrough += this.#kittyProbeBuffer;
+			this.#kittyProbeBuffer = "";
+			this.#finishKittyProbe(probeOutcome);
+		}
+
+		if (passthrough.length === 0) {
+			return { consume: true };
+		}
+
+		return { data: passthrough };
+	}
+
+	#finishKittyProbe(supported: boolean): void {
+		this.#clearKittyProbeState();
+		if (!supported || TERMINAL.imageProtocol || getTmuxOverlayImageProtocol()) return;
+
+		setTmuxOverlayImageProtocol(ImageProtocol.Kitty);
+		this.#queryCellSize();
+		this.invalidate();
+		this.requestRender(true);
+	}
+
+	#clearKittyProbeState(): void {
+		if (this.#kittyProbeTimeout) {
+			clearTimeout(this.#kittyProbeTimeout);
+			this.#kittyProbeTimeout = undefined;
+		}
+		this.#kittyProbeUnsubscribe?.();
+		this.#kittyProbeUnsubscribe = undefined;
+		this.#kittyProbePending = false;
+		this.#kittyProbeBuffer = "";
+	}
+
 	#handleSixelProbeInput(data: string): InputListenerResult {
 		if (!this.#sixelProbePendingDa && !this.#sixelProbePendingGraphics) {
 			return undefined;
@@ -1550,18 +1695,22 @@ export class TUI extends Container {
 		this.requestRender(true);
 	}
 	#queryCellSize(): void {
-		// Only query if terminal supports images (cell size is only used for image rendering)
-		if (!TERMINAL.imageProtocol) {
+		// Cell size is only used for image rendering — inline or passthrough overlay.
+		if (!TERMINAL.imageProtocol && !getTmuxOverlayImageProtocol()) {
 			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 the query is passthrough-wrapped so the OUTER terminal reports
+		// its real cell size; tmux otherwise answers with a value of its own, which
+		// oversizes the pet sprite and pushes it out of bounds (an out-of-range
+		// position resolves to a null overlay payload, freezing the animation).
+		this.#writeTerminal(wrapTmuxPassthrough("\x1b[16t"));
 	}
 
 	stop(): void {
 		this.flushTerminalCleanup();
 		this.#clearSixelProbeState();
+		this.#clearKittyProbeState();
 		this.#stopped = true;
 		this.#settleRenderCommitWaiters(false);
 		if (this.#renderTimer) {