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

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [17.0.0] - 2026-07-15
+
+### Added
+
+- Improved LaTeX rendering for \underbrace, \overbrace, \overset, \underset, and \stackrel to use drawn horizontal braces with centered labels and stacked annotations instead of flat inline glyphs.
+- Improved LaTeX rendering of multi-letter subscripts and superscripts by displaying them as raised or lowered blocks instead of ragged per-character Unicode glyphs.
+- Added an opt-in Editor.setImeSafeCursorLayout() method to protect macOS IME preedit while retaining the compact bordered layout by default.
+
+### Fixed
+
+- Fixed SIXEL image rendering where images with cell heights not divisible by 6 would have their bottom portion overwritten by subsequent content.
+- Fixed an issue where the Kitty OSC 99 desktop-notification capability probe would leak raw text into the terminal pane when running inside a multiplexer like tmux or screen.
+
+## [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/editor.d.ts

@@ -92,6 +92,8 @@ export declare class Editor implements Component, Focusable {
      * Use the real terminal cursor instead of rendering a cursor glyph.
      */
     setUseTerminalCursor(useTerminalCursor: boolean): void;
+    /** Render a dedicated bottom border so terminal-local IME preedit cannot shift editor chrome. */
+    setImeSafeCursorLayout(enabled: boolean): void;
     getUseTerminalCursor(): boolean;
     setMaxHeight(maxHeight: number | undefined): void;
     setPaddingX(paddingX: number): void;

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": "17.0.0",
 	"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": "17.0.0",
+		"@oh-my-pi/pi-utils": "17.0.0",
 		"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

@@ -382,6 +382,7 @@ export class Editor implements Component, Focusable {
 
 	#theme: EditorTheme;
 	#useTerminalCursor = false;
+	#imeSafeCursorLayout = false;
 
 	/** When set, replaces the normal cursor glyph at end-of-text with this ANSI-styled string. */
 	cursorOverride: string | undefined;
@@ -539,6 +540,11 @@ export class Editor implements Component, Focusable {
 		this.#useTerminalCursor = useTerminalCursor;
 	}
 
+	/** Render a dedicated bottom border so terminal-local IME preedit cannot shift editor chrome. */
+	setImeSafeCursorLayout(enabled: boolean): void {
+		this.#imeSafeCursorLayout = enabled;
+	}
+
 	getUseTerminalCursor(): boolean {
 		return this.#useTerminalCursor;
 	}
@@ -866,6 +872,7 @@ export class Editor implements Component, Focusable {
 			let displayWidth = visibleWidth(layoutLine.text);
 			let cursorPaddingOverflow = 0;
 			let decorated = false;
+			let imeSafeCursorTail = false;
 			const showPromptGutter = promptGutter !== undefined && visibleIndex === 0;
 			const gutterText =
 				promptGutter === undefined ? "" : showPromptGutter ? promptGutter.firstLine : promptGutter.continuation;
@@ -922,7 +929,13 @@ export class Editor implements Component, Focusable {
 				if (marker) {
 					const before = displayText.slice(0, layoutLine.cursorPos);
 					const after = displayText.slice(layoutLine.cursorPos);
-					if (after.length === 0 && inlineHint) {
+					if (this.#imeSafeCursorLayout && after.length === 0 && borderVisible) {
+						// Terminal frontends render IME marked text locally before committed bytes
+						// reach the application. Keep the end-of-input cursor row empty to its
+						// right so that insertion cannot shift box chrome onto the next row.
+						displayText = before + marker;
+						imeSafeCursorTail = true;
+					} else if (after.length === 0 && inlineHint) {
 						const availWidth = Math.max(0, lineContentWidth - displayWidth);
 						const hintText = hintStyle(truncateToWidth(inlineHint, availWidth));
 						displayText = before + marker + hintText;
@@ -1022,6 +1035,15 @@ export class Editor implements Component, Focusable {
 			// trailing `─`, but never the corner/vertical bar itself.
 			const isLastLine = visibleIndex === visibleLayoutLines.length - 1;
 			const rightChromeCells = Math.max(1, paddingX + 1 - cursorPaddingOverflow);
+			if (isLastLine && imeSafeCursorTail) {
+				const leftBorder = this.borderColor(`${box.vertical}${padding(paddingX)}`);
+				const bottomBorder = this.borderColor(
+					`${box.bottomLeft}${box.horizontal.repeat(Math.max(0, width - 2))}${box.bottomRight}`,
+				);
+				result.push(leftBorder + displayText);
+				result.push(bottomBorder);
+				continue;
+			}
 			if (isLastLine) {
 				const rightPad = Math.max(0, rightChromeCells - 2);
 				const includeHorizontal = rightChromeCells >= 2;
@@ -1364,21 +1386,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 +2092,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 +2138,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 +3059,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 +3089,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/latex-block.ts

@@ -11,7 +11,8 @@
 // fractions and `\binom`, stretch delimiters (`\left…\right`, tall bare parens,
 // matrix brackets), render matrix/cases/array environments as baseline-aligned
 // grids, place big-operator limits (`\sum`, `\lim`, `\int\limits`) above and
-// below the symbol, draw radicals, raise/lower block scripts, and
+// below the symbol, draw radicals, raise/lower block scripts, draw labeled
+// horizontal braces (`\underbrace{x}_{lbl}`), stack `\overset`/`\underset`, and
 // align `&` columns in `align`-family environments. Flat runs — symbols, fonts,
 // colors, inline scripts — are delegated to `latexToUnicode`.
 //
@@ -126,6 +127,25 @@ const INTEGRAL_OPERATORS: Record<string, true> = {
 	smallint: true,
 };
 
+// Horizontal brace/bracket decorations drawn as a rule row beside the content,
+// with an optional limits-style label beyond the rule (`\underbrace{x}_{lbl}`).
+interface HBraceSpec {
+	left: string;
+	mid: string;
+	center: string;
+	right: string;
+	over: boolean;
+}
+
+const HBRACE_COMMANDS: Record<string, HBraceSpec> = {
+	overbrace: { left: "╭", mid: "─", center: "┴", right: "╮", over: true },
+	underbrace: { left: "╰", mid: "─", center: "┬", right: "╯", over: false },
+	overbracket: { left: "┌", mid: "─", center: "─", right: "┐", over: true },
+	underbracket: { left: "└", mid: "─", center: "─", right: "┘", over: false },
+	overparen: { left: "╭", mid: "─", center: "─", right: "╮", over: true },
+	underparen: { left: "╰", mid: "─", center: "─", right: "╯", over: false },
+};
+
 // Vertical delimiter piece characters: `only` for single-line content, then
 // top/mid/bot columns for stretched forms; `axis` replaces `mid` at the
 // baseline row (the brace point).
@@ -363,6 +383,31 @@ function limitsBox(glyph: Box, sub: Box | null, sup: Box | null): Box {
 	return { lines, baseline, width };
 }
 
+/**
+ * `\underbrace{content}_{label}` / `\overbrace{content}^{label}`: the content
+ * with a drawn horizontal brace beside it and the label centered beyond the
+ * brace. The baseline stays on the content so neighbors align with it.
+ */
+function hbraceBox(content: Box, spec: HBraceSpec, label: Box | null): Box {
+	const braceWidth = Math.max(content.width, 3);
+	const width = Math.max(braceWidth, label?.width ?? 0);
+	const lead = (braceWidth - 3) >> 1;
+	const brace = center(
+		spec.left + spec.mid.repeat(lead) + spec.center + spec.mid.repeat(braceWidth - 3 - lead) + spec.right,
+		width,
+	);
+	const contentLines = content.lines.map(line => center(line, width));
+	const labelLines = label === null ? [] : label.lines.map(line => center(line, width));
+	if (spec.over) {
+		return {
+			lines: [...labelLines, brace, ...contentLines],
+			baseline: labelLines.length + 1 + content.baseline,
+			width,
+		};
+	}
+	return { lines: [...contentLines, brace, ...labelLines], baseline: content.baseline, width };
+}
+
 /**
  * Attach block scripts to `base` as one shared right-hand column: the
  * superscript ends level with the base's top row (raised one row above a
@@ -878,6 +923,59 @@ function parseExpr(src: string, ctx: Ctx = ROOT_CTX): Box {
 				i = bottom.end;
 				continue;
 			}
+			if (name && HBRACE_COMMANDS[name]) {
+				flush();
+				const spec = HBRACE_COMMANDS[name];
+				const arg = readArg(src, j);
+				// Limits-style scripts: the brace-side script is the label; an
+				// opposite-side script attaches as a regular corner script.
+				let subText: string | null = null;
+				let supText: string | null = null;
+				let m = arg.end;
+				for (;;) {
+					let n = m;
+					while (src[n] === " ") n++;
+					if (src[n] === "_" && subText === null) {
+						const s = readArg(src, n + 1);
+						subText = s.text;
+						m = s.end;
+						continue;
+					}
+					if (src[n] === "^" && supText === null) {
+						const s = readArg(src, n + 1);
+						supText = s.text;
+						m = s.end;
+						continue;
+					}
+					break;
+				}
+				const labelText = spec.over ? supText : subText;
+				const otherText = spec.over ? subText : supText;
+				let box = hbraceBox(
+					parseExpr(arg.text, inner()),
+					spec,
+					labelText === null ? null : parseExpr(labelText, inner()),
+				);
+				if (otherText !== null) {
+					const other = parseExpr(otherText, inner());
+					box = attachScripts(box, spec.over ? other : null, spec.over ? null : other);
+				}
+				boxes.push(paint(box));
+				i = m;
+				continue;
+			}
+			if (name === "overset" || name === "underset" || name === "stackrel") {
+				flush();
+				const anno = readArg(src, j);
+				const base = readArg(src, anno.end);
+				const annoBox = parseExpr(anno.text, inner());
+				const baseBox = parseExpr(base.text, inner());
+				boxes.push(
+					paint(limitsBox(baseBox, name === "underset" ? annoBox : null, name === "underset" ? null : annoBox)),
+				);
+				i = base.end;
+				continue;
+			}
 			if (name === "sqrt") {
 				let k = j;
 				while (src[k] === " ") k++;
@@ -1108,8 +1206,18 @@ function parseExpr(src: string, ctx: Ctx = ROOT_CTX): Box {
 				const flat = latexToUnicode(raw);
 				return flat.startsWith("^") || flat.startsWith("_");
 			};
+			// Multi-letter script words (`N_{turns}`) would convert per-char into
+			// Unicode glyphs of uneven height and read ragged; box them too.
+			// Commands are stripped: their output (`\prime` → ′) is not letters.
+			const ragged = (raw: string | undefined): boolean => {
+				if (raw === undefined) return false;
+				const letters = scriptArgOf(raw)
+					.replace(/\\[A-Za-z]+/g, "")
+					.match(/[A-Za-z]/g);
+				return letters !== null && letters.length >= 2;
+			};
 			const tall = (supBox !== null && supBox.lines.length > 1) || (subBox !== null && subBox.lines.length > 1);
-			if (tall || unconvertible(supText) || unconvertible(subText)) {
+			if (tall || unconvertible(supText) || unconvertible(subText) || ragged(supText) || ragged(subText)) {
 				// Block script (`x^{\frac{1}{2}}`, `x^q`): raise/lower the boxes
 				// against the run or box they follow.
 				flush();

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(
@@ -974,11 +952,25 @@ export function renderImage(
 
 	if (TERMINAL.imageProtocol === ImageProtocol.Sixel) {
 		try {
-			const targetWidthPx = Math.max(1, fit.columns * cellDims.widthPx);
-			const targetHeightPx = Math.max(1, fit.rows * cellDims.heightPx);
+			// SIXEL encodes in 6-pixel vertical bands. A height that is not a
+			// multiple of 6 is padded with transparent rows, but the terminal
+			// still allocates cell rows for the padded height. When the padded
+			// height crosses a cell boundary the terminal uses one more row
+			// than fit.rows, so the next line of content overwrites the bottom
+			// of the image — a visible slice stripped from the image. Round the
+			// encode height DOWN to the largest multiple of 6 that fits within
+			// the requested row budget, so the band boundary aligns without
+			// padding and the reserved row count never exceeds fit.rows. Scale
+			// the width by the same ratio so resize_exact preserves the aspect
+			// ratio instead of squashing the image vertically.
+			const rawHeightPx = Math.max(1, fit.rows * cellDims.heightPx);
+			const targetHeightPx = Math.max(6, Math.floor(rawHeightPx / 6) * 6);
+			const heightScale = targetHeightPx / rawHeightPx;
+			const targetWidthPx = Math.max(1, Math.round(fit.columns * cellDims.widthPx * heightScale));
+			const rows = Math.max(1, Math.ceil(targetHeightPx / cellDims.heightPx));
 			const decoded = new Uint8Array(Buffer.from(base64Data, "base64"));
 			const sequence = encodeSixel(decoded, targetWidthPx, targetHeightPx);
-			return { sequence, rows: fit.rows };
+			return { sequence, rows };
 		} catch {
 			return null;
 		}

package/src/terminal.ts

@@ -12,12 +12,12 @@ import {
 import { setKittyProtocolActive } from "./keys";
 import { StdinBuffer } from "./stdin-buffer";
 import {
+	isInsideTerminalMultiplexer,
 	isInsideTmux,
 	NotifyProtocol,
 	setCellDimensions,
 	setOsc99Supported,
 	TERMINAL,
-	wrapTmuxPassthrough,
 } from "./terminal-capabilities";
 import { type HangulCompatibilityJamoWidth, setHangulCompatibilityJamoWidth } from "./utils";
 
@@ -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";
 }
@@ -1041,6 +1042,15 @@ export class ProcessTerminal implements Terminal {
 
 	#shouldQueryOsc99Support(): boolean {
 		if (TERMINAL.notifyProtocol !== NotifyProtocol.Osc99) return false;
+		// Never probe inside a terminal multiplexer. tmux/screen forward the
+		// passthrough-wrapped `p=?` query to the outer terminal, but cannot route
+		// the capability reply back to the pane that sent it (tmux/tmux#4386,
+		// tmux/tmux#3964), so the reply leaks into the pane as literal text and
+		// its bytes perturb input (issue #5582 — the notification sibling of the
+		// graphics-probe leak #5381). Rich notifications fall back to the
+		// single-line OSC 99 form until confirmation, and delivery still uses the
+		// passthrough/BEL path (#3395).
+		if (isInsideTerminalMultiplexer($env)) return false;
 		return !isBunTestRuntime() || $env.PI_TUI_OSC99_PROBE === "1";
 	}
 
@@ -1054,14 +1064,9 @@ export class ProcessTerminal implements Terminal {
 		const id = `omp-probe-${nextOsc99ProbeId++}`;
 		this.#osc99PendingId = id;
 		this.#da1SentinelOwners.push({ kind: "osc99Probe", id });
-		// Wrap the probe under tmux so terminals behind `allow-passthrough on`
-		// can still respond (mirroring how `TerminalInfo.sendNotification`
-		// wraps notification deliveries). Without it the probe is swallowed
-		// inside tmux even when the outer terminal speaks OSC 99, and rich
-		// notifications stay permanently downgraded to the single-line fallback.
-		const probe = `\x1b]99;i=${id}:p=?;\x1b\\`;
-		const sequence = isInsideTmux() ? wrapTmuxPassthrough(probe) : probe;
-		this.#safeWrite(`${sequence}\x1b[c`);
+		// The probe never runs under a multiplexer (see #shouldQueryOsc99Support),
+		// so it is always sent directly to the terminal.
+		this.#safeWrite(`\x1b]99;i=${id}:p=?;\x1b\\\x1b[c`);
 	}
 
 	#handleOsc99CapabilityResponse(metaRaw: string, payload: string): boolean {

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";
 }