@oh-my-pi/pi-tui 16.5.1 → 16.5.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [16.5.2] - 2026-07-14
+
+### Fixed
+
+- Fixed animated Loader ANSI updates causing unnecessary text layout invalidation and re-wrapping on shimmer-only frames (#5230).
+- Fixed Ctrl+W (delete word backward) stopping at underscores in snake_case identifiers, treating them as single words (#4776).
+- Fixed automatic file completion incorrectly treating punctuation, trailing spaces, and slash-command text as paths, and improved autocomplete dismissal behavior (#5376).
+- Fixed Kitty graphics rendering under tmux, ensuring images correctly follow pane scrolling and reflow (#5381).
+- Fixed tmux sessions becoming unresponsive after terminal capability replies by falling back to legacy keyboard input mode when the Kitty protocol is unavailable (#5378).
+- Fixed PageUp and PageDown keys on an empty prompt editor incorrectly navigating prompt history instead of scrolling the editor viewport (#4754).
+
 ## [16.5.1] - 2026-07-14
 
 ### Fixed

package/dist/types/components/loader.d.ts

@@ -1,9 +1,14 @@
 import type { TUI } from "../tui.js";
 import { Text } from "./text.js";
 type ColorFn = (str: string) => string;
+/**
+ * Styles Loader message fragments without changing their visible text or width.
+ * Set `animated` for colorizers whose ANSI output changes over time.
+ */
 export type LoaderMessageColorFn = ColorFn & {
     readonly animated?: true;
 };
+/** Animates a spinner and colorized message while asynchronous work is pending. */
 export declare class Loader extends Text {
     #private;
     private spinnerColorFn;

package/dist/types/kitty-graphics.d.ts

@@ -26,18 +26,15 @@ export interface KittyGraphicsFeatures {
  * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
  * U+10EEEE with row/column diacritics).
  *
- * Only `kitty` (the protocol's origin) and `ghostty` ship a working
- * implementation; WezTerm advertises Kitty graphics but treats placeholder
- * cells as literal PUA glyphs (see wezterm/wezterm#986, "placeholder support"
- * still unchecked), and the tmux/screen fallback can land on any outer
- * terminal. Enabling placeholders on those paths emits a `columns × rows`
- * grid of U+10EEEE per image per frame; the cells render as boxed fallback
- * glyphs and re-emit on every repaint, which is exactly the
- * "stuck/laggy scrolling + ASCII artifact" symptom reported in #1877.
+ * Kitty and Ghostty advertise placeholder support directly. A tmux session
+ * cannot use cursor-positioned placements because the outer terminal does not
+ * know pane scroll/reflow state, so an explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
+ * also opts into placeholders there — matching `timg -pk`. Automatic tmux
+ * fallback stays off because the unknown outer terminal may render U+10EEEE as
+ * literal PUA boxes (#1877).
  *
- * `PI_NO_KITTY_PLACEHOLDERS=1` forces off (e.g. for tmux passthrough to a
- * non-supporting outer terminal); `PI_KITTY_PLACEHOLDERS=1` forces on (e.g.
- * for a wezterm nightly that has merged placeholder support).
+ * `PI_NO_KITTY_PLACEHOLDERS=1` and `PI_KITTY_PLACEHOLDERS=0` remain hard
+ * opt-outs; `PI_KITTY_PLACEHOLDERS=1` explicitly opts in anywhere else.
  */
 export declare function detectKittyUnicodePlaceholdersSupport(terminalId: string, env?: NodeJS.ProcessEnv): boolean;
 export declare function getKittyGraphics(): Readonly<KittyGraphicsFeatures>;

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

@@ -1,3 +1,4 @@
+export { isInsideTmux, wrapTmuxPassthrough } from "./tmux.js";
 export declare enum ImageProtocol {
     Kitty = "\u001B_G",
     Iterm2 = "\u001B]1337;File=",
@@ -34,12 +35,6 @@ export declare class TerminalInfo {
     formatNotification(message: string | TerminalNotification): string;
     sendNotification(message: string | TerminalNotification): void;
 }
-/**
- * Whether the agent process is running inside a tmux session. Read fresh on
- * each call so tests can toggle `Bun.env.TMUX` per case without re-importing
- * the module and so a tmux session attached/detached mid-run is observed.
- */
-export declare function isInsideTmux(env?: NodeJS.ProcessEnv): boolean;
 /** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
 export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
 /**
@@ -48,19 +43,6 @@ export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): bo
  * is observed and tests can toggle `Bun.env.ZELLIJ` per case.
  */
 export declare function isInsideZellij(env?: NodeJS.ProcessEnv): boolean;
-/**
- * Wrap a control-sequence payload in tmux's DCS passthrough envelope. Each
- * ESC byte inside `payload` is doubled per tmux's escape rules. tmux strips
- * the envelope and forwards the unwrapped payload to the outer terminal only
- * when the user opts in with `set -g allow-passthrough on`; otherwise tmux
- * silently consumes the envelope, which is identical to the pre-wrap baseline
- * (tmux already swallowed the bare OSC).
- *
- * Used by `TerminalInfo.sendNotification` and the OSC 99 capability probe in
- * `terminal.ts` to keep notifications alive for terminals that understand
- * OSC 9 / OSC 99 (kitty, ghostty, wezterm, iterm2) when running under tmux.
- */
-export declare function wrapTmuxPassthrough(payload: string): string;
 export declare function isNotificationSuppressed(): boolean;
 /**
  * Returns true when running in Windows Terminal with known SIXEL support.

package/dist/types/tmux.d.ts

@@ -0,0 +1,6 @@
+/** Whether the process is running inside a tmux session. */
+export declare function isInsideTmux(env?: NodeJS.ProcessEnv): boolean;
+/** Wrap a control sequence in tmux's DCS passthrough envelope. */
+export declare function wrapTmuxPassthrough(payload: string): string;
+/** Pass a control sequence through tmux, leaving direct-terminal output unchanged. */
+export declare function wrapTmuxPassthroughIfNeeded(payload: string, env?: NodeJS.ProcessEnv): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "16.5.1",
+	"version": "16.5.2",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.5.1",
-		"@oh-my-pi/pi-utils": "16.5.1",
+		"@oh-my-pi/pi-natives": "16.5.2",
+		"@oh-my-pi/pi-utils": "16.5.2",
 		"lru-cache": "11.5.2",
 		"marked": "^18.0.6"
 	},

package/src/autocomplete.ts

@@ -456,6 +456,10 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 						prefix: isMidPromptSkillLookup ? commandText : textBeforeCursor,
 					};
 				}
+				if (!isMidPromptSkillLookup && slashStart === leadingSlashStart && !commandText.slice(1).includes("/")) {
+					return null;
+				}
+
 				// A slash token with no matching command may still be an absolute
 				// path (`/tmp/fo` at prompt start, `see /tmp` mid-prompt); fall
 				// through to file-path completion.
@@ -679,15 +683,14 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 			return pathPrefix;
 		}
 
-		// For natural triggers, return if it looks like a path, ends with /, starts with ~/, .
-		// Only return empty string if the text looks like it's starting a path context
-		if (pathPrefix.includes("/") || pathPrefix.startsWith(".") || pathPrefix.startsWith("~/")) {
-			return pathPrefix;
-		}
-
-		// Return empty string only after a space (not for completely empty text)
-		// Empty text should not trigger file suggestions - that's for forced Tab completion
-		if (pathPrefix === "" && text.endsWith(" ")) {
+		// Automatic updates complete only unambiguous path syntax. Bare relative
+		// tokens remain available through explicit Tab completion.
+		if (
+			pathPrefix.startsWith("/") ||
+			pathPrefix.startsWith("./") ||
+			pathPrefix.startsWith("../") ||
+			pathPrefix.startsWith("~/")
+		) {
 			return pathPrefix;
 		}
 

package/src/components/editor.ts

@@ -1364,21 +1364,14 @@ export class Editor implements Component, Focusable {
 		} else if (kb.matches(data, "tui.editor.cursorLineEnd")) {
 			this.#moveToLineEnd();
 		}
-		// Page navigation (PageUp/PageDown)
+		// Page navigation (PageUp/PageDown): page the editor viewport only. On a
+		// short draft this is a no-op — it never steps prompt history (that stays
+		// on Up/Down), so an idle empty editor swallows the keys instead of
+		// surprising the user by loading the previous prompt (#4754).
 		else if (kb.matches(data, "tui.editor.pageUp")) {
-			if (this.#isEditorEmpty()) {
-				this.#navigateHistory(-1);
-			} else if (this.#historyIndex > -1 && this.#isOnFirstVisualLine()) {
-				this.#navigateHistory(-1);
-			} else {
-				this.#pageScroll(-1);
-			}
+			this.#pageScroll(-1);
 		} else if (kb.matches(data, "tui.editor.pageDown")) {
-			if (this.#historyIndex > -1 && this.#isOnLastVisualLine()) {
-				this.#navigateHistory(1);
-			} else {
-				this.#pageScroll(1);
-			}
+			this.#pageScroll(1);
 		}
 		// Forward delete (Fn+Backspace or Delete key, including Shift+Delete)
 		else if (kb.matches(data, "tui.editor.deleteCharForward") || matchesKey(data, "shift+delete")) {
@@ -2077,15 +2070,13 @@ export class Editor implements Component, Focusable {
 		this.#resetKillSequence();
 		this.#recordUndoState();
 
-		let removedMidPromptSlashTrigger = false;
+		let removedSlashTrigger = false;
 
 		if (this.#state.cursorCol > 0) {
 			const line = this.#state.lines[this.#state.cursorLine] || "";
 			const textBeforeCursor = line.slice(0, this.#state.cursorCol);
 			const trailingSlashStart = findTrailingSlashCommandStart(textBeforeCursor);
-			removedMidPromptSlashTrigger =
-				trailingSlashStart === this.#state.cursorCol - 1 &&
-				(!this.#hasOnlyWhitespaceBeforeCursorLine() || textBeforeCursor.slice(0, trailingSlashStart).trim() !== "");
+			removedSlashTrigger = trailingSlashStart === this.#state.cursorCol - 1;
 			// An atomic placeholder token (image/paste marker) deletes as a unit, so a single
 			// backspace never leaves a half-eaten `[Paste #1, +30 lines` behind as stray text.
 			const token = this.#atomicTokenAt(line, this.#state.cursorCol - 1);
@@ -2125,7 +2116,7 @@ export class Editor implements Component, Focusable {
 
 		// Update or re-trigger autocomplete after backspace
 		if (this.#autocompleteState) {
-			if (removedMidPromptSlashTrigger) {
+			if (removedSlashTrigger) {
 				this.#cancelAutocomplete();
 				this.onAutocompleteUpdate?.();
 			} else {
@@ -3046,17 +3037,17 @@ export class Editor implements Component, Focusable {
 		} else if (this.#isInMidPromptSkillSlashContext()) {
 			await this.#handleSlashCommandCompletion();
 			if (!this.#autocompleteState) {
-				await this.#forceFileAutocomplete(true);
+				await this.#forceFileAutocomplete();
 			}
 		} else {
-			await this.#forceFileAutocomplete(true);
+			await this.#forceFileAutocomplete();
 		}
 	}
 	async #handleSlashCommandCompletion(): Promise<void> {
 		await this.#tryTriggerAutocomplete();
 	}
 
-	async #forceFileAutocomplete(explicitTab: boolean = false): Promise<void> {
+	async #forceFileAutocomplete(): Promise<void> {
 		if (!this.#autocompleteProvider) return;
 
 		// File-aware providers expose getForceFileSuggestions; slash-only ones fall back to regular completion.
@@ -3076,27 +3067,6 @@ export class Editor implements Component, Focusable {
 		if (requestId !== this.#autocompleteRequestId) return;
 
 		if (suggestions && Array.isArray(suggestions.items) && suggestions.items.length > 0) {
-			// If there's exactly one suggestion and this was an explicit Tab press, apply it immediately
-			if (explicitTab && suggestions.items.length === 1) {
-				const item = suggestions.items[0]!;
-				const result = this.#autocompleteProvider.applyCompletion(
-					this.#state.lines,
-					this.#state.cursorLine,
-					this.#state.cursorCol,
-					item,
-					suggestions.prefix,
-				);
-
-				this.#state.lines = result.lines;
-				this.#state.cursorLine = result.cursorLine;
-				this.#setCursorCol(result.cursorCol);
-
-				if (this.onChange) {
-					this.onChange(this.getText());
-				}
-				return;
-			}
-
 			this.#autocompletePrefix = suggestions.prefix;
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
 			this.#autocompleteState = "force";

package/src/components/loader.ts

@@ -1,28 +1,29 @@
 import type { TUI } from "../tui";
-import { sliceByColumn, visibleWidth } from "../utils";
+import { getPaddingX, sliceByColumn, visibleWidth } from "../utils";
 import { Text } from "./text";
 
-/**
- * Loader component. Spinner frames advance at `SPINNER_ADVANCE_MS`.
- *
- * Message colorizers that are time-dependent can opt into 30fps redraws by
- * setting `animated` to `true` on the function object.
- */
 const RENDER_INTERVAL_MS = 1000 / 30;
 const SPINNER_ADVANCE_MS = 80;
 
 type ColorFn = (str: string) => string;
 
+/**
+ * Styles Loader message fragments without changing their visible text or width.
+ * Set `animated` for colorizers whose ANSI output changes over time.
+ */
 export type LoaderMessageColorFn = ColorFn & {
 	readonly animated?: true;
 };
 
+/** Animates a spinner and colorized message while asynchronous work is pending. */
 export class Loader extends Text {
 	#frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 	#currentFrame = 0;
 	#intervalId?: NodeJS.Timeout;
 	#ui: TUI | null = null;
 	#lastSpinnerTick = 0;
+	#layoutSource?: readonly string[];
+	#layout?: readonly { leading: string; content: string; trailing: string }[];
 
 	constructor(
 		ui: TUI,
@@ -40,11 +41,36 @@ export class Loader extends Text {
 	}
 
 	render(width: number): readonly string[] {
-		const lines = ["", ...super.render(width)];
-		for (let i = 0; i < lines.length; i++) {
-			const line = lines[i];
-			if (visibleWidth(line) > width) {
-				lines[i] = sliceByColumn(line, 0, width, true);
+		const source = super.render(width);
+		if (source !== this.#layoutSource) {
+			const paddingX = getPaddingX(1);
+			this.#layoutSource = source;
+			this.#layout = source.map(line => {
+				const clamped = visibleWidth(line) > width ? sliceByColumn(line, 0, width, true) : line;
+				const body = clamped.slice(paddingX);
+				const content = body.trimEnd();
+				return {
+					leading: clamped.slice(0, paddingX),
+					content,
+					trailing: body.slice(content.length),
+				};
+			});
+		}
+
+		const frame = this.#frames[this.#currentFrame];
+		const lines = [""];
+		const layout = this.#layout ?? [];
+		for (let i = 0; i < layout.length; i++) {
+			const { leading, content, trailing } = layout[i];
+			if (i === 0 && content.startsWith(frame)) {
+				const remainder = content.slice(frame.length);
+				const separator = remainder.startsWith(" ") ? " " : "";
+				const message = remainder.slice(separator.length);
+				lines.push(
+					`${leading}${this.spinnerColorFn(frame)}${separator}${message ? this.messageColorFn(message) : ""}${trailing}`,
+				);
+			} else {
+				lines.push(`${leading}${content ? this.messageColorFn(content) : ""}${trailing}`);
 			}
 		}
 		return lines;
@@ -91,8 +117,8 @@ export class Loader extends Text {
 
 	#updateDisplay() {
 		const frame = this.#frames[this.#currentFrame];
-		const text = `${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`;
-		if (this.setText(text) && this.#ui) {
+		const textChanged = this.setText(`${frame} ${this.message}`);
+		if ((textChanged || this.messageColorFn.animated === true) && this.#ui) {
 			// Direct write: a loader tick changes only this component, so the TUI
 			// can update the already-positioned rows without driving the full
 			// compose/prepare/diff pipeline. Lightweight test stubs may not carry

package/src/kitty-graphics.ts

@@ -15,6 +15,8 @@
  * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
  */
 
+import { wrapTmuxPassthroughIfNeeded } from "./tmux";
+
 /** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
 export const KITTY_PLACEHOLDER = "\u{10eeee}";
 
@@ -60,18 +62,15 @@ export interface KittyGraphicsFeatures {
  * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
  * U+10EEEE with row/column diacritics).
  *
- * Only `kitty` (the protocol's origin) and `ghostty` ship a working
- * implementation; WezTerm advertises Kitty graphics but treats placeholder
- * cells as literal PUA glyphs (see wezterm/wezterm#986, "placeholder support"
- * still unchecked), and the tmux/screen fallback can land on any outer
- * terminal. Enabling placeholders on those paths emits a `columns × rows`
- * grid of U+10EEEE per image per frame; the cells render as boxed fallback
- * glyphs and re-emit on every repaint, which is exactly the
- * "stuck/laggy scrolling + ASCII artifact" symptom reported in #1877.
+ * Kitty and Ghostty advertise placeholder support directly. A tmux session
+ * cannot use cursor-positioned placements because the outer terminal does not
+ * know pane scroll/reflow state, so an explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
+ * also opts into placeholders there — matching `timg -pk`. Automatic tmux
+ * fallback stays off because the unknown outer terminal may render U+10EEEE as
+ * literal PUA boxes (#1877).
  *
- * `PI_NO_KITTY_PLACEHOLDERS=1` forces off (e.g. for tmux passthrough to a
- * non-supporting outer terminal); `PI_KITTY_PLACEHOLDERS=1` forces on (e.g.
- * for a wezterm nightly that has merged placeholder support).
+ * `PI_NO_KITTY_PLACEHOLDERS=1` and `PI_KITTY_PLACEHOLDERS=0` remain hard
+ * opt-outs; `PI_KITTY_PLACEHOLDERS=1` explicitly opts in anywhere else.
  */
 export function detectKittyUnicodePlaceholdersSupport(terminalId: string, env: NodeJS.ProcessEnv = Bun.env): boolean {
 	const offRaw = env.PI_NO_KITTY_PLACEHOLDERS?.trim().toLowerCase();
@@ -79,6 +78,7 @@ export function detectKittyUnicodePlaceholdersSupport(terminalId: string, env: N
 	const force = env.PI_KITTY_PLACEHOLDERS?.trim().toLowerCase();
 	if (force === "1" || force === "true" || force === "on" || force === "yes" || force === "y") return true;
 	if (force === "0" || force === "false" || force === "off" || force === "no" || force === "n") return false;
+	if (env.TMUX && env.PI_FORCE_IMAGE_PROTOCOL?.trim().toLowerCase() === "kitty") return true;
 	return terminalId === "kitty" || terminalId === "ghostty";
 }
 
@@ -120,7 +120,7 @@ export function encodeKittyVirtualPlacement(opts: {
 	const params = ["a=p", "U=1", "q=2", `i=${opts.imageId}`];
 	if (opts.placementId) params.push(`p=${opts.placementId}`);
 	params.push(`c=${opts.columns}`, `r=${opts.rows}`);
-	return `\x1b_G${params.join(",")}\x1b\\`;
+	return wrapTmuxPassthroughIfNeeded(`\x1b_G${params.join(",")}\x1b\\`);
 }
 
 /**

package/src/terminal-capabilities.ts

@@ -9,6 +9,9 @@ import {
 	renderKittyPlaceholderLines,
 	setKittyGraphics,
 } from "./kitty-graphics";
+import { isInsideTmux, wrapTmuxPassthrough, wrapTmuxPassthroughIfNeeded } from "./tmux";
+
+export { isInsideTmux, wrapTmuxPassthrough } from "./tmux";
 
 export enum ImageProtocol {
 	Kitty = "\x1b_G",
@@ -142,15 +145,6 @@ export class TerminalInfo {
 	}
 }
 
-/**
- * Whether the agent process is running inside a tmux session. Read fresh on
- * each call so tests can toggle `Bun.env.TMUX` per case without re-importing
- * the module and so a tmux session attached/detached mid-run is observed.
- */
-export function isInsideTmux(env: NodeJS.ProcessEnv = Bun.env): boolean {
-	return Boolean(env.TMUX);
-}
-
 /** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
 export function isInsideTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): boolean {
 	// TMUX/STY/ZELLIJ/CMUX workspace+surface ids are authoritative session
@@ -172,22 +166,6 @@ export function isInsideZellij(env: NodeJS.ProcessEnv = Bun.env): boolean {
 	return Boolean(env.ZELLIJ);
 }
 
-/**
- * Wrap a control-sequence payload in tmux's DCS passthrough envelope. Each
- * ESC byte inside `payload` is doubled per tmux's escape rules. tmux strips
- * the envelope and forwards the unwrapped payload to the outer terminal only
- * when the user opts in with `set -g allow-passthrough on`; otherwise tmux
- * silently consumes the envelope, which is identical to the pre-wrap baseline
- * (tmux already swallowed the bare OSC).
- *
- * Used by `TerminalInfo.sendNotification` and the OSC 99 capability probe in
- * `terminal.ts` to keep notifications alive for terminals that understand
- * OSC 9 / OSC 99 (kitty, ghostty, wezterm, iterm2) when running under tmux.
- */
-export function wrapTmuxPassthrough(payload: string): string {
-	return `\x1bPtmux;${payload.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
-}
-
 export function isNotificationSuppressed(): boolean {
 	const value = $env.PI_NOTIFICATIONS;
 	if (!value) return false;
@@ -628,7 +606,7 @@ export function setCellDimensions(dims: CellDimensions): void {
 function chunkKittyApc(leadParams: string, base64Data: string): string {
 	const CHUNK_SIZE = 4096;
 	if (base64Data.length <= CHUNK_SIZE) {
-		return `\x1b_G${leadParams};${base64Data}\x1b\\`;
+		return wrapTmuxPassthroughIfNeeded(`\x1b_G${leadParams};${base64Data}\x1b\\`);
 	}
 
 	const chunks: string[] = [];
@@ -640,12 +618,12 @@ function chunkKittyApc(leadParams: string, base64Data: string): string {
 		const isLast = offset + CHUNK_SIZE >= base64Data.length;
 
 		if (isFirst) {
-			chunks.push(`\x1b_G${leadParams},m=1;${chunk}\x1b\\`);
+			chunks.push(wrapTmuxPassthroughIfNeeded(`\x1b_G${leadParams},m=1;${chunk}\x1b\\`));
 			isFirst = false;
 		} else if (isLast) {
-			chunks.push(`\x1b_Gm=0;${chunk}\x1b\\`);
+			chunks.push(wrapTmuxPassthroughIfNeeded(`\x1b_Gq=2,m=0;${chunk}\x1b\\`));
 		} else {
-			chunks.push(`\x1b_Gm=1;${chunk}\x1b\\`);
+			chunks.push(wrapTmuxPassthroughIfNeeded(`\x1b_Gq=2,m=1;${chunk}\x1b\\`));
 		}
 
 		offset += CHUNK_SIZE;
@@ -699,7 +677,7 @@ export function encodeKittyPlacement(options: {
 	if (options.placementId) params.push(`p=${options.placementId}`);
 	if (options.columns) params.push(`c=${options.columns}`);
 	if (options.rows) params.push(`r=${options.rows}`);
-	return `\x1b_G${params.join(",")}\x1b\\`;
+	return wrapTmuxPassthroughIfNeeded(`\x1b_G${params.join(",")}\x1b\\`);
 }
 
 /**
@@ -710,7 +688,7 @@ export function encodeKittyPlacement(options: {
  * this is the only way to actually purge a placed image.
  */
 export function encodeKittyDeleteImage(imageId: number): string {
-	return `\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`;
+	return wrapTmuxPassthroughIfNeeded(`\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`);
 }
 
 export function encodeITerm2(

package/src/terminal.ts

@@ -45,6 +45,7 @@ export function resolveHangulCompatibilityJamoWidthFromTerminalIdentity(
 }
 
 function shouldEnableModifyOtherKeysFallback(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (isInsideTmux(env)) return false;
 	if (!env.SSH_CONNECTION && !env.SSH_TTY && !env.SSH_CLIENT) return true;
 	return TERMINAL.id !== "base" && TERMINAL.id !== "trueColor";
 }

package/src/tmux.ts

@@ -0,0 +1,14 @@
+/** Whether the process is running inside a tmux session. */
+export function isInsideTmux(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	return Boolean(env.TMUX);
+}
+
+/** Wrap a control sequence in tmux's DCS passthrough envelope. */
+export function wrapTmuxPassthrough(payload: string): string {
+	return `\x1bPtmux;${payload.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
+}
+
+/** Pass a control sequence through tmux, leaving direct-terminal output unchanged. */
+export function wrapTmuxPassthroughIfNeeded(payload: string, env: NodeJS.ProcessEnv = Bun.env): string {
+	return isInsideTmux(env) ? wrapTmuxPassthrough(payload) : payload;
+}

package/src/utils.ts

@@ -394,6 +394,7 @@ export function getWordNavKind(grapheme: string): WordNavKind {
 	const ch = firstCodePointChar(grapheme);
 	if (!ch) return "other";
 	if (WORD_NAV_RE_WHITESPACE.test(ch)) return "whitespace";
+	if (ch === "_") return "word";
 	if (WORD_NAV_RE_PUNCT.test(ch) || WORD_NAV_RE_SYMBOL.test(ch)) return "delimiter";
 	if (
 		WORD_NAV_RE_HAN.test(ch) ||
@@ -403,7 +404,7 @@ export function getWordNavKind(grapheme: string): WordNavKind {
 	) {
 		return "cjk";
 	}
-	if (ch === "_" || WORD_NAV_RE_LETTER.test(ch) || WORD_NAV_RE_NUMBER.test(ch)) return "word";
+	if (WORD_NAV_RE_LETTER.test(ch) || WORD_NAV_RE_NUMBER.test(ch)) return "word";
 	return "other";
 }