@oh-my-pi/pi-tui 16.1.16 → 16.1.17

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [16.1.17] - 2026-06-24
+
+### Added
+
+- Added runtime resolution of the Hangul Compatibility Jamo (U+3131..U+318E) display width for terminals known to disagree with the platform default (e.g. Ghostty, which renders these at 2 cells). Fixes doubled/ghosted jamo during Korean IME composition; the resolved width is pushed into the native width engine before the first paint. Other terminals keep the platform default (macOS narrow, otherwise UAX#11), so the override is a no-op outside Ghostty. A runtime DSR/CPR probe for unknown terminals is tracked separately.
+- Added `setHangulCompatibilityJamoWidth` / `getHangulCompatibilityJamoWidth` to set the jamo width profile (`"platform" | "unicode" | 1 | 2`); the profile is mirrored into the native `setHangulCompatJamoWidthOverride`.
+
+### Fixed
+
+- Removed the 30-second OSC 11 background-color poll that ran on terminals without DEC Mode 2031 support (macOS Terminal.app, Warp, VS Code's built-in terminal, older Alacritty/WezTerm). Each poll's OSC 11 + DA1 write wiped the user's active text selection on several of those terminals, causing intermittent "can't copy" failures whenever a poll fired mid-drag — most visibly during the Ask tool dialog when the user wants to quote text back from the conversation ([#3297](https://github.com/can1357/oh-my-pi/issues/3297)). Theme detection now relies on the initial startup probe plus Mode 2031 push notifications; affected terminals pick up OS-theme changes on next launch.
+- Fixed `@`-path autocomplete failing on Windows for paths outside the cwd. Windows absolute paths (e.g. `C:\\Users\\...`) were not detected as absolute — only `/` was checked — so they were incorrectly joined with the base directory, producing invalid search paths and empty suggestions. Path-join calls also introduced backslashes into suggestion values, breaking round-trip insertion. Absolute path detection now uses `path.isAbsolute()` (handles drive letters) and suggestion paths are normalized to forward slashes (valid on all platforms).
+- Fixed settings rows crashing native text truncation when a malformed config value reaches the renderer as a non-string ([#3338](https://github.com/can1357/oh-my-pi/issues/3338)).
+- Fixed desktop notifications being silently lost under tmux on the common stack of tmux + kitty/ghostty/wezterm/iTerm2. `TERMINAL_ID` resolves to the inner terminal (whose markers leak into the tmux session env), which maps to `NotifyProtocol.Osc9` / `NotifyProtocol.Osc99`, and `sendNotification()` wrote that raw OSC straight to stdout — tmux dropped it on the floor and `monitor-bell` / `monitor-activity` never fired, so a backgrounded omp pane had no way to flag completion or `ask` blockage. Under `TMUX`, OSC-protocol notifications are now wrapped in tmux's `\x1bPtmux;…\x1b\\` DCS passthrough envelope (so users with `set -g allow-passthrough on` still get the real toast on the outer terminal) and followed by a `\x07` BEL (so `set -g monitor-bell on` reliably flags the window otherwise). The OSC 99 capability probe in `terminal.ts` is wrapped the same way so rich notifications keep working across tmux. `NotifyProtocol.Bell` paths are unchanged. ([#3395](https://github.com/can1357/oh-my-pi/issues/3395))
+
 ## [16.1.10] - 2026-06-21
 
 ### Fixed

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

@@ -34,6 +34,25 @@ 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;
+/**
+ * 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/terminal.d.ts

@@ -1,3 +1,5 @@
+import { type HangulCompatibilityJamoWidth } from "./utils";
+export declare function resolveHangulCompatibilityJamoWidthFromTerminalIdentity(env?: NodeJS.ProcessEnv): HangulCompatibilityJamoWidth;
 /**
  * Split `data` into chunks whose encoded UTF-8 byte length is no greater than
  * `maxChunkBytes`, preferring a line boundary (`\n`) as the cut point so

package/dist/types/utils.d.ts

@@ -1,6 +1,10 @@
 import { Ellipsis, type ExtractSegmentsResult, type SliceResult } from "@oh-my-pi/pi-natives";
 export { Ellipsis } from "@oh-my-pi/pi-natives";
 export { DEFAULT_TAB_WIDTH } from "@oh-my-pi/pi-utils";
+export type HangulCompatibilityJamoWidth = "platform" | "unicode" | 1 | 2;
+export declare function getHangulCompatibilityJamoWidth(): HangulCompatibilityJamoWidth;
+export declare function setHangulCompatibilityJamoWidth(width: HangulCompatibilityJamoWidth): boolean;
+export declare function resetHangulCompatibilityJamoWidthForTests(): void;
 export type TextSizingScale = 1 | 2 | 3;
 export type TextSizingVerticalAlign = "top" | "bottom" | "center";
 export type TextSizingHorizontalAlign = "left" | "right" | "center";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "16.1.16",
+	"version": "16.1.17",
 	"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.1.16",
-		"@oh-my-pi/pi-utils": "16.1.16",
+		"@oh-my-pi/pi-natives": "16.1.17",
+		"@oh-my-pi/pi-utils": "16.1.17",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.5"
 	},

package/src/autocomplete.ts

@@ -678,31 +678,39 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 			const { rawPrefix, isAtPrefix, isQuotedPrefix } = parsePathPrefix(prefix);
 			let expandedPrefix = rawPrefix;
 
+			// Normalize backslashes to forward slashes so Windows native paths
+			// (C:\tmp\foo) work with the /-based splitting/joining below.
+			expandedPrefix = expandedPrefix.replace(/\\/g, "/");
+
+			// Capture the pre-expansion prefix so root checks can still
+			// detect bare "~" and "~/" after #expandHomePath rewrites them.
+			const preExpand = expandedPrefix;
+
 			// Handle home directory expansion
 			if (expandedPrefix.startsWith("~")) {
 				expandedPrefix = this.#expandHomePath(expandedPrefix);
 			}
 
 			const isRootPrefix =
-				rawPrefix === "" ||
-				rawPrefix === "./" ||
-				rawPrefix === "../" ||
-				rawPrefix === "~" ||
-				rawPrefix === "~/" ||
-				rawPrefix === "/" ||
-				(isAtPrefix && rawPrefix === "");
+				preExpand === "" ||
+				preExpand === "./" ||
+				preExpand === "../" ||
+				preExpand === "~" ||
+				preExpand === "~/" ||
+				preExpand === "/" ||
+				(isAtPrefix && preExpand === "");
 
 			if (isRootPrefix) {
 				// Complete from specified position
-				if (rawPrefix.startsWith("~") || expandedPrefix.startsWith("/")) {
+				if (expandedPrefix.startsWith("~") || path.isAbsolute(expandedPrefix)) {
 					searchDir = expandedPrefix;
 				} else {
 					searchDir = path.join(this.#basePath, expandedPrefix);
 				}
 				searchPrefix = "";
-			} else if (rawPrefix.endsWith("/")) {
+			} else if (expandedPrefix.endsWith("/")) {
 				// If prefix ends with /, show contents of that directory
-				if (rawPrefix.startsWith("~") || expandedPrefix.startsWith("/")) {
+				if (expandedPrefix.startsWith("~") || path.isAbsolute(expandedPrefix)) {
 					searchDir = expandedPrefix;
 				} else {
 					searchDir = path.join(this.#basePath, expandedPrefix);
@@ -712,7 +720,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 				// Split into directory and file prefix
 				const dir = path.dirname(expandedPrefix);
 				const file = path.basename(expandedPrefix);
-				if (rawPrefix.startsWith("~") || expandedPrefix.startsWith("/")) {
+				if (expandedPrefix.startsWith("~") || path.isAbsolute(expandedPrefix)) {
 					searchDir = dir;
 				} else {
 					searchDir = path.join(this.#basePath, dir);
@@ -746,7 +754,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 
 				let relativePath: string;
 				const name = entry.name;
-				const displayPrefix = rawPrefix;
+				const displayPrefix = rawPrefix.replace(/\\/g, "/");
 
 				if (displayPrefix.endsWith("/")) {
 					// If prefix ends with /, append entry to the prefix
@@ -757,14 +765,13 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 						const homeRelativeDir = displayPrefix.slice(2); // Remove ~/
 						const dir = path.dirname(homeRelativeDir);
 						relativePath = `~/${dir === "." ? name : path.join(dir, name)}`;
-					} else if (displayPrefix.startsWith("/")) {
-						// Absolute path - construct properly
-						const dir = path.dirname(displayPrefix);
-						if (dir === "/") {
-							relativePath = `/${name}`;
-						} else {
-							relativePath = `${dir}/${name}`;
-						}
+					} else if (path.isAbsolute(displayPrefix)) {
+						// Absolute path — covers both /unix/paths and Windows C:/drive/paths.
+						// Use string concat with / instead of path.join (which uses platform-native
+						// separators and produces drive-relative results like "C:alpha" when
+						// dirname returns "C:" without a trailing slash).
+						const dir = displayPrefix.slice(0, displayPrefix.lastIndexOf("/"));
+						relativePath = dir === "" || dir === "/" ? `/${name}` : `${dir}/${name}`;
 					} else {
 						relativePath = path.join(path.dirname(displayPrefix), name);
 						if (displayPrefix.startsWith("./") && !relativePath.startsWith("./")) {
@@ -780,6 +787,10 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider {
 					}
 				}
 
+				// Normalize backslashes to forward slashes so suggestions are consistent
+				// with the user's input (which uses / on all platforms) and work correctly
+				// when inserted back into the editor. Forward slashes are valid on Windows.
+				relativePath = relativePath.replace(/\\/g, "/");
 				const pathValue = isDirectory ? `${relativePath}/` : relativePath;
 				const value = buildCompletionValue(pathValue, {
 					isDirectory,

package/src/components/settings-list.ts

@@ -498,7 +498,7 @@ export class SettingsList implements Component {
 		const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
 		const separator = "  ";
 		const valueMaxWidth = rowWidth - prefixWidth - maxLabelWidth - visibleWidth(separator) - 2;
-		const valuePlain = truncateToWidth(item.currentValue, valueMaxWidth, Ellipsis.Omit);
+		const valuePlain = truncateToWidth(String(item.currentValue ?? ""), valueMaxWidth, Ellipsis.Omit);
 		const hovered = !isSelected && this.#theme.hovered !== undefined && item.id === this.#hoveredItemId;
 		// De-emphasized rows (outside the active section) render as plain text
 		// under one dim wash so inner label/value colors don't fight it.

package/src/terminal-capabilities.ts

@@ -98,10 +98,49 @@ export class TerminalInfo {
 
 	sendNotification(message: string | TerminalNotification): void {
 		if (isNotificationSuppressed() || isTerminalHeadless()) return;
-		process.stdout.write(this.formatNotification(message));
+		const formatted = this.formatNotification(message);
+		// Under tmux, terminals whose notify protocol is OSC 9 / OSC 99 would
+		// otherwise lose the notification entirely: tmux does not forward bare
+		// OSC 9/99 to the outer terminal, and the bare sequence does not flag
+		// tmux's own `monitor-bell` / `monitor-activity`. Wrap the OSC in tmux's
+		// DCS passthrough envelope so users with `allow-passthrough on` still
+		// get the desktop toast, then append a BEL so `monitor-bell` flags the
+		// pane/window for everyone else — the only signal a backgrounded pane
+		// has that the agent finished or is waiting for input. `Bell` protocol
+		// already self-flags via tmux's bell monitoring, so leave it alone.
+		if (this.notifyProtocol !== NotifyProtocol.Bell && isInsideTmux()) {
+			process.stdout.write(`${wrapTmuxPassthrough(formatted)}\x07`);
+			return;
+		}
+		process.stdout.write(formatted);
 	}
 }
 
+/**
+ * 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);
+}
+
+/**
+ * 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;

package/src/terminal.ts

@@ -3,11 +3,37 @@ import * as fs from "node:fs";
 import { $env, isBunTestRuntime, isTerminalHeadless, logger } from "@oh-my-pi/pi-utils";
 import { setKittyProtocolActive } from "./keys";
 import { StdinBuffer } from "./stdin-buffer";
-import { NotifyProtocol, setCellDimensions, setOsc99Supported, TERMINAL } from "./terminal-capabilities";
+import {
+	isInsideTmux,
+	NotifyProtocol,
+	setCellDimensions,
+	setOsc99Supported,
+	TERMINAL,
+	wrapTmuxPassthrough,
+} from "./terminal-capabilities";
+import { type HangulCompatibilityJamoWidth, setHangulCompatibilityJamoWidth } from "./utils";
 
 const TERMINAL_PROGRESS_KEEPALIVE_MS = 1000;
 const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
 const TERMINAL_PROGRESS_CLEAR_SEQUENCE = "\x1b]9;4;0;\x07";
+// Hangul Compatibility Jamo (U+3131..=U+318E) render width is terminal-dependent:
+// Ghostty follows UAX#11 (2 cells); Terminal.app and iTerm2 render narrow (1),
+// matching the macOS platform default. Override only for terminals known to
+// disagree — the rest keep the platform default (macOS narrow, otherwise UAX#11),
+// so this is a no-op everywhere except Ghostty. A runtime DSR/CPR probe that
+// auto-detects the width on unknown terminals is tracked separately.
+export function resolveHangulCompatibilityJamoWidthFromTerminalIdentity(
+	env: NodeJS.ProcessEnv = Bun.env,
+): HangulCompatibilityJamoWidth {
+	if (
+		env.GHOSTTY_RESOURCES_DIR ||
+		env.TERM_PROGRAM?.toLowerCase() === "ghostty" ||
+		env.TERM?.toLowerCase().includes("ghostty")
+	) {
+		return 2;
+	}
+	return "platform";
+}
 
 /**
  * Maximum encoded UTF-8 bytes per `process.stdout.write` call on Windows.
@@ -435,7 +461,6 @@ export class ProcessTerminal implements Terminal {
 	#inBandResizeBuffer = "";
 	#reportedColumns?: number;
 	#reportedRows?: number;
-	#osc11PollTimer?: Timer;
 	#mode2031DebounceTimer?: Timer;
 	#progressTimer?: Timer;
 
@@ -509,6 +534,7 @@ export class ProcessTerminal implements Terminal {
 		// The query handler intercepts input temporarily, then installs the user's handler
 		// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
 		this.#queryAndEnableKittyProtocol();
+		setHangulCompatibilityJamoWidth(resolveHangulCompatibilityJamoWidthFromTerminalIdentity());
 
 		// Query terminal background color via OSC 11 for dark/light detection.
 		// Uses DA1 (Primary Device Attributes) as a sentinel: terminals process
@@ -527,24 +553,18 @@ export class ProcessTerminal implements Terminal {
 		// actual background color (following Neovim convention) with 100ms debounce.
 		this.#safeWrite("\x1b[?2031h");
 
-		// Start periodic OSC 11 re-query for terminals without Mode 2031
-		// (Warp, Alacritty, older WezTerm). Stops once Mode 2031 support is
-		// confirmed via DECRQM (probed below) or a Mode 2031 change notification
-		// fires — push notifications supersede polling, and the poll's repeated
-		// OSC 11/DA1 writes clear the user's active text selection on some
-		// terminals (copy breaks every 2s).
-		// Windows Terminal under WSL has been observed to close the hosting tab
-		// after repeated OSC 11/DA1 probes. Keep the initial/event-driven probes,
-		// but avoid background polling there.
-		const isWSL = process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
-		if (!isWSL) {
-			this.#startOsc11Poll();
-		}
+		// Theme detection relies on (1) the startup OSC 11 probe above and
+		// (2) DEC Mode 2031 push notifications. Terminals without Mode 2031
+		// (macOS Terminal.app, Warp, VS Code's built-in, older Alacritty/
+		// WezTerm) detect the appearance once at startup and pick up later OS
+		// theme changes on next launch. Earlier builds polled OSC 11 every 30 s
+		// here for those terminals, but each poll's OSC 11/DA1 write wiped the
+		// user's active text selection on several of them (#3297).
 
 		// Probe DEC private-mode support via DECRQM. 2026 (synchronized output)
 		// gates the renderer's begin/end markers; 2048 (in-band resize) is enabled
 		// only after the terminal confirms support; 2031 (appearance change
-		// notifications) stops the OSC 11 poll once confirmed. Xterm ?1010/?1011
+		// notifications) drives mid-session theme tracking. Xterm ?1010/?1011
 		// are disabled while OMP owns the TTY so typing in the editor does not
 		// force a reader scrolled into native history back to the tail. Each probe
 		// rides the shared DA1 sentinel, so terminals that ignore DECRQM resolve as
@@ -869,7 +889,6 @@ export class ProcessTerminal implements Terminal {
 			// (Neovim convention — coalesces rapid notifications during transitions)
 			const appearanceMatch = sequence.match(appearanceDsrPattern);
 			if (appearanceMatch) {
-				this.#stopOsc11Poll();
 				if (this.#mode2031DebounceTimer) clearTimeout(this.#mode2031DebounceTimer);
 				this.#mode2031DebounceTimer = setTimeout(() => {
 					this.#mode2031DebounceTimer = undefined;
@@ -936,7 +955,14 @@ export class ProcessTerminal implements Terminal {
 		const id = `omp-probe-${nextOsc99ProbeId++}`;
 		this.#osc99PendingId = id;
 		this.#da1SentinelOwners.push({ kind: "osc99Probe", id });
-		this.#safeWrite(`\x1b]99;i=${id}:p=?;\x1b\\\x1b[c`);
+		// 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`);
 	}
 
 	#handleOsc99CapabilityResponse(metaRaw: string, payload: string): boolean {
@@ -984,32 +1010,6 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
-	/**
-	 * Start periodic OSC 11 re-queries for terminals without Mode 2031 (Warp, Alacritty, WezTerm).
-	 * Self-disables once Mode 2031 fires (push-based is better than polling).
-	 * The interval is deliberately long: each poll's OSC 11 + DA1 write clears
-	 * an active text selection on several terminals, so polling exists only to
-	 * eventually notice a rare OS theme switch, not to track it promptly.
-	 */
-	#startOsc11Poll(): void {
-		this.#stopOsc11Poll();
-		this.#osc11PollTimer = setInterval(() => {
-			if (this.#dead) {
-				this.#stopOsc11Poll();
-				return;
-			}
-			this.#queryBackgroundColor();
-		}, 30_000);
-		this.#osc11PollTimer.unref();
-	}
-
-	#stopOsc11Poll(): void {
-		if (this.#osc11PollTimer) {
-			clearInterval(this.#osc11PollTimer);
-			this.#osc11PollTimer = undefined;
-		}
-	}
-
 	/**
 	 * Query terminal for Kitty keyboard protocol support and enable if available.
 	 *
@@ -1060,9 +1060,7 @@ export class ProcessTerminal implements Terminal {
 	/**
 	 * Record DECRQM support for a private mode (idempotent — first result wins)
 	 * and notify subscribers. Enables DEC 2048 in-band resize when 2048 resolves
-	 * supported, and stops the OSC 11 poll when 2031 resolves supported (Mode 2031
-	 * push notifications make periodic re-querying redundant — and the poll's
-	 * OSC 11/DA1 writes clobber active text selections on some terminals).
+	 * supported.
 	 */
 	#resolvePrivateMode(mode: number, supported: boolean): void {
 		if (this.#privateModeSupport.has(mode)) return;
@@ -1075,7 +1073,6 @@ export class ProcessTerminal implements Terminal {
 			}
 		}
 		if (mode === 2048 && supported) this.#enableInBandResize();
-		if (mode === 2031 && supported) this.#stopOsc11Poll();
 	}
 
 	#disableXtermScrollToBottomMode(mode: number): void {
@@ -1224,7 +1221,6 @@ export class ProcessTerminal implements Terminal {
 			this.#safeWrite("\x1b[?2048l");
 			this.#inBandResizeActive = false;
 		}
-		this.#stopOsc11Poll();
 		if (this.#mode2031DebounceTimer) {
 			clearTimeout(this.#mode2031DebounceTimer);
 			this.#mode2031DebounceTimer = undefined;

package/src/utils.ts

@@ -2,6 +2,7 @@ import {
 	Ellipsis,
 	type ExtractSegmentsResult,
 	extractSegments as nativeExtractSegments,
+	setHangulCompatJamoWidthOverride as nativeSetHangulCompatJamoWidthOverride,
 	sliceWithWidth as nativeSliceWithWidth,
 	truncateToWidth as nativeTruncateToWidth,
 	wrapTextWithAnsi as nativeWrapTextWithAnsi,
@@ -13,6 +14,34 @@ export { Ellipsis } from "@oh-my-pi/pi-natives";
 
 export { DEFAULT_TAB_WIDTH } from "@oh-my-pi/pi-utils";
 
+export type HangulCompatibilityJamoWidth = "platform" | "unicode" | 1 | 2;
+
+let hangulCompatibilityJamoWidth: HangulCompatibilityJamoWidth = "platform";
+
+// Wire encoding for the native override (see crates/pi-natives text.rs):
+// 0 = platform default, 1 = narrow, 2 = wide, 3 = unicode (no correction).
+function nativeHangulCompatibilityJamoOverride(width: HangulCompatibilityJamoWidth): number {
+	if (width === "unicode") return 3;
+	if (typeof width === "number") return width;
+	return 0;
+}
+
+export function getHangulCompatibilityJamoWidth(): HangulCompatibilityJamoWidth {
+	return hangulCompatibilityJamoWidth;
+}
+
+export function setHangulCompatibilityJamoWidth(width: HangulCompatibilityJamoWidth): boolean {
+	const changed = hangulCompatibilityJamoWidth !== width;
+	hangulCompatibilityJamoWidth = width;
+	nativeSetHangulCompatJamoWidthOverride(nativeHangulCompatibilityJamoOverride(width));
+	return changed;
+}
+
+export function resetHangulCompatibilityJamoWidthForTests(): void {
+	hangulCompatibilityJamoWidth = "platform";
+	nativeSetHangulCompatJamoWidthOverride(0);
+}
+
 export type TextSizingScale = 1 | 2 | 3;
 export type TextSizingVerticalAlign = "top" | "bottom" | "center";
 export type TextSizingHorizontalAlign = "left" | "right" | "center";
@@ -157,6 +186,58 @@ const LONG_WIDTH_FAST_PATH_MIN = 128;
 // non-CJK tables that back truncate/slice/wrap. Hoisted so no per-call alloc.
 const STRING_WIDTH_OPTS = { countAnsiEscapeCodes: false, ambiguousIsNarrow: true } as const;
 
+// Hangul Compatibility Jamo (U+3131..=U+318E). `Bun.stringWidth` follows UAX#11
+// and reports these at 2 cells (the U+3164 HANGUL FILLER at 0), but the actual
+// rendered width is decided by the *client* terminal (1 cell on Terminal.app /
+// iTerm2, 2 on Ghostty and most Linux terminals). The width is resolved from
+// the terminal identity and pushed into the native engine through
+// `setHangulCompatibilityJamoWidth`; mirror the same correction here so the TS
+// width stays in parity with the native truncate/slice/wrap model — and so the
+// hardware cursor column lands on the actual glyph during Korean IME input.
+const HANGUL_COMPAT_JAMO_REGEX = /[\u3131-\u318e]/;
+const HANGUL_COMPAT_JAMO_GLOBAL_REGEX = /[\u3131-\u318e]/g;
+const HANGUL_FILLER_CODE_POINT = 0x3164;
+// `Bun.stringWidth` counts every code point in the Compatibility Jamo block as
+// 2 cells (even the U+3164 filler that `unicode-width` treats as zero-width).
+const HANGUL_COMPAT_JAMO_BUN_WIDTH = 2;
+
+// Effective target cell width for Compatibility Jamo, or `null` to follow the
+// Unicode width (no correction). Mirrors `hangul_compat_jamo_target_width` in
+// crates/pi-natives/src/text.rs.
+function hangulCompatibilityJamoTargetWidth(): 1 | 2 | null {
+	switch (hangulCompatibilityJamoWidth) {
+		case 1:
+			return 1;
+		case 2:
+			return 2;
+		case "unicode":
+			return null;
+		default:
+			// "platform": macOS terminals historically render these narrow.
+			return process.platform === "darwin" ? 1 : null;
+	}
+}
+
+// Reconcile the `Bun.stringWidth` count for Compatibility Jamo to the native
+// width engine: subtract Bun's per-jamo cell count and add back the effective
+// width — the runtime target when one is active, otherwise the `unicode-width`
+// value. Mirrors `char_width_corrected` / `apply_hangul_compat_jamo_delta` in
+// crates/pi-natives/src/text.rs, including the rule that the zero-width filler
+// (U+3164) is never widened past the narrow correction (a wide terminal still
+// renders it at its Unicode width of 0).
+function correctHangulCompatibilityJamoWidth(width: number, str: string): number {
+	if (!HANGUL_COMPAT_JAMO_REGEX.test(str)) return width;
+	const target = hangulCompatibilityJamoTargetWidth();
+	let corrected = width;
+	HANGUL_COMPAT_JAMO_GLOBAL_REGEX.lastIndex = 0;
+	for (let m = HANGUL_COMPAT_JAMO_GLOBAL_REGEX.exec(str); m !== null; m = HANGUL_COMPAT_JAMO_GLOBAL_REGEX.exec(str)) {
+		const unicodeWidth = m[0].codePointAt(0) === HANGUL_FILLER_CODE_POINT ? 0 : 2;
+		const finalWidth = target === null || (unicodeWidth === 0 && target > 1) ? unicodeWidth : target;
+		corrected += finalWidth - HANGUL_COMPAT_JAMO_BUN_WIDTH;
+	}
+	return corrected;
+}
+
 /**
  * Visible width of a string in terminal columns, excluding ANSI/OSC escapes.
  *
@@ -177,7 +258,7 @@ export function visibleWidth(str: string): number {
 			tabCount++;
 		}
 		if (tabCount > 0) width += tabCount * DEFAULT_TAB_WIDTH;
-		return width;
+		return correctHangulCompatibilityJamoWidth(width, str);
 	}
 
 	let tabCount = 0;
@@ -238,7 +319,7 @@ export function visibleWidth(str: string): number {
 		}
 	}
 
-	return width;
+	return correctHangulCompatibilityJamoWidth(width, str);
 }
 
 const THAI_LAO_AM_GLOBAL_REGEX = /[\u0e33\u0eb3]/g;