@oh-my-pi/pi-tui 17.3.7 → 17.4.0

package/src/components/settings-list.ts

@@ -20,6 +20,8 @@ export interface SettingItem {
 	label: string;
 	/** Optional description shown when selected */
 	description?: string;
+	/** Optional risk note shown in warning styling above the description, with a glyph on the row. */
+	warning?: string;
 	/** Current value to display (right side) */
 	currentValue: string;
 	/** If provided, Enter/Space cycles through these values */
@@ -36,6 +38,10 @@ export interface SettingsListTheme {
 	label: (text: string, selected: boolean, changed: boolean) => string;
 	value: (text: string, selected: boolean, changed: boolean) => string;
 	description: (text: string) => string;
+	/** Style for risk notes and the row warning glyph. Falls back to `description` when omitted. */
+	warning?: (text: string) => string;
+	/** Glyph marking rows that carry a `warning`. Omitted hides the row marker. */
+	warningMark?: string;
 	cursor: string;
 	hint: (text: string) => string;
 	/** Style for section heading rows (dimmed when outside the active section). Falls back to `hint` when omitted. */
@@ -78,12 +84,15 @@ export interface SettingsListOptions {
 	sidebarWidth?: number;
 }
 
-/** Searchable text for a setting item: label, id, value, description, and cycle values. */
+/** Searchable text for a setting item: label, id, value, description, warning, and cycle values. */
 export function getSettingItemFilterText(item: SettingItem): string {
 	let text = `${item.label} ${item.id} ${item.currentValue}`;
 	if (item.description) {
 		text += ` ${item.description}`;
 	}
+	if (item.warning) {
+		text += ` ${item.warning}`;
+	}
 	if (item.values) {
 		text += ` ${item.values.join(" ")}`;
 	}
@@ -477,6 +486,11 @@ export class SettingsList implements Component {
 		return this.#padLines(this.#renderMainList(width));
 	}
 
+	/** Warning glyph suffix for a row that carries a risk note, or "" when none applies. */
+	#warningMark(item: SettingItem): string {
+		return item.warning && this.#theme.warningMark ? ` ${this.#theme.warningMark}` : "";
+	}
+
 	#renderItemRow(
 		item: SettingItem,
 		index: number,
@@ -495,7 +509,9 @@ export class SettingsList implements Component {
 		const isSelected = index === this.#selectedIndex && !this.#sectionFocus;
 		const prefix = isSelected ? this.#theme.cursor : "  ";
 		const prefixWidth = visibleWidth(prefix);
-		const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
+		const mark = this.#warningMark(item);
+		const labelPlain = item.label + mark;
+		const labelPad = padding(Math.max(0, maxLabelWidth - visibleWidth(labelPlain)));
 		const separator = "  ";
 		const valueMaxWidth = rowWidth - prefixWidth - maxLabelWidth - visibleWidth(separator) - 2;
 		const valuePlain = truncateToWidth(String(item.currentValue ?? ""), valueMaxWidth, Ellipsis.Omit);
@@ -504,11 +520,13 @@ export class SettingsList implements Component {
 		// under one dim wash so inner label/value colors don't fight it.
 		if (dimmed && !isSelected) {
 			const text = this.#theme.hint(
-				truncateToWidth(`  ${labelPadded}${separator}${valuePlain}`, Math.max(0, rowWidth)),
+				truncateToWidth(`  ${labelPlain}${labelPad}${separator}${valuePlain}`, Math.max(0, rowWidth)),
 			);
 			return hovered && this.#theme.hovered ? this.#theme.hovered(text) : text;
 		}
-		const labelText = this.#theme.label(labelPadded, isSelected, item.changed === true);
+		const warningStyle = this.#theme.warning ?? this.#theme.description;
+		const labelText =
+			this.#theme.label(item.label, isSelected, item.changed === true) + (mark ? warningStyle(mark) : "") + labelPad;
 		const valueText = this.#theme.value(valuePlain, isSelected, item.changed === true);
 		const text = truncateToWidth(prefix + labelText + separator + valueText, Math.max(0, rowWidth));
 		// Pointer hover paints a band behind the whole row, distinct from the
@@ -550,7 +568,9 @@ export class SettingsList implements Component {
 				0,
 				Math.min(this.#selectedIndex - Math.floor(viewportHeight / 2), this.#filteredItems.length - viewportHeight),
 			);
-			const labelWidths = this.#filteredItems.filter(item => !item.heading).map(item => visibleWidth(item.label));
+			const labelWidths = this.#filteredItems
+				.filter(item => !item.heading)
+				.map(item => visibleWidth(item.label + this.#warningMark(item)));
 			const maxLabelWidth = Math.min(30, labelWidths.length > 0 ? Math.max(...labelWidths) : 0);
 			const itemRowsOverflow = this.#filteredItems.length > viewportHeight;
 			const itemRowWidth = Math.max(0, width - (itemRowsOverflow ? 1 : 0));
@@ -589,15 +609,25 @@ export class SettingsList implements Component {
 
 		// Description area: 1 blank + exactly 3 rows, clamped with an ellipsis,
 		// so moving between items with/without descriptions never shifts rows.
+		// The risk note leads so it survives the clamp when both are present.
 		lines.push("");
 		const selectedItem = this.#filteredItems[this.#selectedIndex];
 		const descLines: string[] = [];
-		if (selectedItem?.description && !selectedItem.heading) {
-			const wrappedDesc = wrapTextWithAnsi(selectedItem.description, width - 4);
-			for (const line of wrappedDesc.slice(0, 3)) {
-				descLines.push(this.#theme.description(`  ${line}`));
+		if (selectedItem && !selectedItem.heading) {
+			if (selectedItem.warning) {
+				const warningStyle = this.#theme.warning ?? this.#theme.description;
+				const mark = this.#theme.warningMark ? `${this.#theme.warningMark} ` : "";
+				for (const line of wrapTextWithAnsi(`${mark}${selectedItem.warning}`, width - 4)) {
+					descLines.push(warningStyle(`  ${line}`));
+				}
+			}
+			if (selectedItem.description) {
+				for (const line of wrapTextWithAnsi(selectedItem.description, width - 4)) {
+					descLines.push(this.#theme.description(`  ${line}`));
+				}
 			}
-			if (wrappedDesc.length > 3) {
+			if (descLines.length > 3) {
+				descLines.splice(3);
 				descLines[2] = truncateToWidth(`${descLines[2]}…`, width);
 			}
 		}
@@ -659,7 +689,9 @@ export class SettingsList implements Component {
 			Math.min(this.#selectedIndex - Math.floor(viewportHeight / 2), this.#filteredItems.length - viewportHeight),
 		);
 		// Label column width spans all items so the layout stays stable across sections.
-		const labelWidths = this.#filteredItems.filter(item => !item.heading).map(item => visibleWidth(item.label));
+		const labelWidths = this.#filteredItems
+			.filter(item => !item.heading)
+			.map(item => visibleWidth(item.label + this.#warningMark(item)));
 		const maxLabelWidth = Math.min(30, labelWidths.length > 0 ? Math.max(...labelWidths) : 0);
 		const overflow = this.#filteredItems.length > viewportHeight;
 		const rowWidth = Math.max(0, paneWidth - (overflow ? 1 : 0));

package/src/index.ts

@@ -5,6 +5,7 @@ export * from "./autocomplete";
 // Components
 export * from "./components/box";
 export * from "./components/cancellable-loader";
+export * from "./components/composer";
 export * from "./components/editor";
 export * from "./components/image";
 export * from "./components/input";

package/src/terminal-capabilities.ts

@@ -223,6 +223,16 @@ function getForcedImageProtocol(): ImageProtocol | null | undefined {
 	return null;
 }
 
+/**
+ * Whether `PI_FORCE_IMAGE_PROTOCOL` pins the image protocol, including its
+ * `off`/`none` kill switch. A runtime capability probe must not override an
+ * explicit user choice: a forced protocol is already applied to {@link TERMINAL},
+ * and a forced "off" leaves `imageProtocol` null on purpose.
+ */
+export function isImageProtocolForced(): boolean {
+	return getForcedImageProtocol() !== undefined;
+}
+
 function parseMajorMinorVersion(versionRaw?: string): { major: number; minor: number } | null {
 	if (!versionRaw) return null;
 	const match = /^(\d+)\.(\d+)/u.exec(versionRaw.trim());

package/src/tui.ts

@@ -28,6 +28,7 @@ import {
 	encodeKittyDeletePlacement,
 	encodeKittyPlacementLine,
 	ImageProtocol,
+	isImageProtocolForced,
 	isInsideTerminalMultiplexer,
 	parseKittyDirectPlacementLine,
 	setCellDimensions,
@@ -1249,7 +1250,6 @@ export class TUI extends Container {
 	#hardwareCursorState: HardwareCursorState | null = null;
 	#hardwareCursorVisibilityKnown = false;
 	#hardwareCursorVisible = false;
-	#sixelProbePendingDa = false;
 	#sixelProbePendingGraphics = false;
 	#sixelProbeBuffer = "";
 	#sixelProbeTimeout?: NodeJS.Timeout;
@@ -1332,6 +1332,12 @@ export class TUI extends Container {
 	#previousWindow: string[] = [];
 	#nativeScrollbackLiveRegionStart: number | undefined;
 	#nativeScrollbackLiveRegionPinned = false;
+	// Start row of the topmost live region that pinned itself. The topmost seam
+	// governs the exactness boundary and the frame-wide pin policy, but a pinned
+	// region BELOW an unpinned seam (an anchored HUD/panel under a streaming
+	// transcript) still must never commit its rows to native scrollback. This is
+	// the ceiling no commit may cross, independent of the topmost seam's policy.
+	#nativeScrollbackPinnedBoundary: number | undefined;
 	#fullRedrawCount = 0;
 	// Caps how many inline images render as live graphics; older ones fall back
 	// to text via a purge + full redraw. Cap is configured by the host app.
@@ -1625,6 +1631,7 @@ export class TUI extends Container {
 		width = Math.max(1, width);
 		this.#nativeScrollbackLiveRegionStart = undefined;
 		this.#nativeScrollbackLiveRegionPinned = false;
+		this.#nativeScrollbackPinnedBoundary = undefined;
 		const children = this.children;
 		const previousSegments = this.#frameSegments;
 		const segments: FrameSegment[] = new Array(children.length);
@@ -1705,9 +1712,18 @@ export class TUI extends Container {
 			// transcript) must never overwrite it — moving the boundary down
 			// would commit the earlier child's still-mutable rows as stale
 			// history.
-			if (liveLocalStart !== undefined && this.#nativeScrollbackLiveRegionStart === undefined) {
-				this.#nativeScrollbackLiveRegionStart = offset + liveLocalStart;
-				this.#nativeScrollbackLiveRegionPinned = liveRegionPinned;
+			if (liveLocalStart !== undefined) {
+				const start = offset + liveLocalStart;
+				if (this.#nativeScrollbackLiveRegionStart === undefined) {
+					this.#nativeScrollbackLiveRegionStart = start;
+					this.#nativeScrollbackLiveRegionPinned = liveRegionPinned;
+				}
+				// A pinned region anywhere in the frame caps commits at its start,
+				// even when an earlier unpinned seam won the topmost merge above:
+				// its rows (a growing anchored panel) must never reach scrollback.
+				if (liveRegionPinned && this.#nativeScrollbackPinnedBoundary === undefined) {
+					this.#nativeScrollbackPinnedBoundary = start;
+				}
 			}
 			if (chainStable) {
 				if (previous !== undefined && previous.component === child && previous.start === offset) {
@@ -2200,19 +2216,21 @@ export class TUI extends Container {
 	}
 
 	#querySixelSupport(): void {
+		// A statically known protocol (Kitty/iTerm2 terminals) or an explicit
+		// PI_FORCE_IMAGE_PROTOCOL choice — including its `off` kill switch — wins
+		// over the probe.
 		if (TERMINAL.imageProtocol) return;
-		// win32 native or WSL under Windows Terminal — both are ConPTY-hosted and
-		// reach the same WT graphics negotiation. WSL reports process.platform
-		// "linux", so a bare win32 check silently skips the probe there (#6009).
-		if (!isConPTYHosted()) return;
-		if (!Bun.env.WT_SESSION) return;
+		if (isImageProtocolForced()) return;
 		if (!process.stdin.isTTY || !process.stdout.isTTY) return;
 
 		this.#clearSixelProbeState();
-		this.#sixelProbePendingDa = true;
 		this.#sixelProbePendingGraphics = true;
 		this.#sixelProbeUnsubscribe = this.addInputListener(data => this.#handleSixelProbeInput(data));
-		this.terminal.write("\x1b[c");
+		// XTSMGRAPHICS item 2 reports the terminal's maximum SIXEL geometry. DA1
+		// attribute 4 advertises SIXEL as well, but ProcessTerminal swallows every
+		// `CSI ? … c` reply for the whole session so a late one cannot leak into the
+		// composer (#8542): those bytes never reach an input listener, so this probe
+		// cannot read them.
 		this.terminal.write("\x1b[?2;1;0S");
 		this.#sixelProbeTimeout = setTimeout(() => {
 			this.#finishSixelProbe(false);
@@ -2220,7 +2238,7 @@ export class TUI extends Container {
 	}
 
 	#handleSixelProbeInput(data: string): InputListenerResult {
-		if (!this.#sixelProbePendingDa && !this.#sixelProbePendingGraphics) {
+		if (!this.#sixelProbePendingGraphics) {
 			return undefined;
 		}
 
@@ -2229,47 +2247,24 @@ export class TUI extends Container {
 		let probeOutcome: boolean | null = null;
 
 		while (this.#sixelProbeBuffer.length > 0) {
-			const daMatch = this.#sixelProbeBuffer.match(/\x1b\[\?([0-9;]+)c/u);
 			const graphicsMatch = this.#sixelProbeBuffer.match(/\x1b\[\?2;(\d+);([0-9;]+)S/u);
+			if (!graphicsMatch || graphicsMatch.index === undefined) break;
 
-			if (!daMatch && !graphicsMatch) break;
-
-			const daIndex = daMatch?.index ?? Number.POSITIVE_INFINITY;
-			const graphicsIndex = graphicsMatch?.index ?? Number.POSITIVE_INFINITY;
-			const useDa = daIndex <= graphicsIndex;
-			const match = useDa ? daMatch : graphicsMatch;
-			if (!match || match.index === undefined) break;
-
-			passthrough += this.#sixelProbeBuffer.slice(0, match.index);
-			this.#sixelProbeBuffer = this.#sixelProbeBuffer.slice(match.index + match[0].length);
-
-			if (useDa && this.#sixelProbePendingDa) {
-				this.#sixelProbePendingDa = false;
-				const attributes = (match[1] ?? "")
-					.split(";")
-					.map(value => Number.parseInt(value, 10))
-					.filter(value => Number.isFinite(value));
-				const hasSixelAttribute = attributes.includes(4);
-				if (hasSixelAttribute) {
-					this.#sixelProbePendingGraphics = false;
-					probeOutcome = true;
-				} else if (!this.#sixelProbePendingGraphics) {
-					probeOutcome = false;
-				}
-			} else if (!useDa && this.#sixelProbePendingGraphics) {
+			passthrough += this.#sixelProbeBuffer.slice(0, graphicsMatch.index);
+			this.#sixelProbeBuffer = this.#sixelProbeBuffer.slice(graphicsMatch.index + graphicsMatch[0].length);
+
+			if (this.#sixelProbePendingGraphics) {
 				this.#sixelProbePendingGraphics = false;
-				const status = Number.parseInt(match[1] ?? "", 10);
-				const supportsSixel = !Number.isNaN(status) && status !== 0;
-				if (supportsSixel) {
-					this.#sixelProbePendingDa = false;
-					probeOutcome = true;
-				} else if (!this.#sixelProbePendingDa) {
-					probeOutcome = false;
-				}
+				// Reply shape `CSI ? 2 ; Ps ; Pv S`: per xterm ctlseqs Ps is the status
+				// (0 = success, 1..3 = error/failure) and Pv the maximum SIXEL geometry,
+				// which a terminal without SIXEL reports as zero.
+				const status = Number.parseInt(graphicsMatch[1] ?? "", 10);
+				const hasGeometry = (graphicsMatch[2] ?? "").split(";").some(part => Number.parseInt(part, 10) > 0);
+				probeOutcome = status === 0 && hasGeometry;
 			}
 		}
 
-		if (this.#sixelProbePendingDa || this.#sixelProbePendingGraphics) {
+		if (this.#sixelProbePendingGraphics) {
 			const partialStart = this.#getSixelProbePartialStart(this.#sixelProbeBuffer);
 			if (partialStart >= 0) {
 				passthrough += this.#sixelProbeBuffer.slice(0, partialStart);
@@ -2313,7 +2308,6 @@ export class TUI extends Container {
 			this.#sixelProbeUnsubscribe();
 			this.#sixelProbeUnsubscribe = undefined;
 		}
-		this.#sixelProbePendingDa = false;
 		this.#sixelProbePendingGraphics = false;
 		this.#sixelProbeBuffer = "";
 	}
@@ -3551,6 +3545,11 @@ export class TUI extends Container {
 		// reports no seam (shell semantics).
 		const frameLength = rawFrame.length;
 		const finalBoundary = Math.max(0, Math.min(frameLength, liveRegionStart ?? frameLength));
+		// No commit may cross into a pinned region, even one below an unpinned
+		// topmost seam (an anchored HUD/panel under a streaming transcript). The
+		// topmost seam still governs exactness (finalBoundary); this ceiling only
+		// bars a growing pinned region's scrolled-off rows from native scrollback.
+		const commitCeiling = this.#nativeScrollbackPinnedBoundary ?? frameLength;
 
 		// 2. Transition state captured before any emitter runs.
 		let prevWindowTop = this.#windowTopRow;
@@ -3769,7 +3768,7 @@ export class TUI extends Container {
 		if (fullPaint) {
 			committedPrefixResliced = true;
 			windowTop = Math.max(0, frameLength - height);
-			chunkTo = liveRegionPinned ? Math.min(windowTop, finalBoundary) : windowTop;
+			chunkTo = Math.min(windowTop, commitCeiling);
 		} else if (widthEpochReset) {
 			// A terminal width change ends the physical-row coordinate epoch.
 			// Resolve the last emitted logical source boundary at the new width;
@@ -3789,7 +3788,7 @@ export class TUI extends Container {
 				hasVisibleOverlay || widthEpochCurrentRows === undefined
 					? hasVisibleOverlay
 						? widthEpochAppendFrom
-						: Math.max(widthEpochAppendFrom, liveRegionPinned ? finalBoundary : frameLength)
+						: Math.max(widthEpochAppendFrom, commitCeiling)
 					: Math.max(widthEpochAppendFrom, widthEpochCurrentRows);
 		} else if (this.#widthEpochBaselineRows !== undefined) {
 			// Only rows physically appended after the width epoch may drive the
@@ -3800,7 +3799,7 @@ export class TUI extends Container {
 			windowTop = Math.max(0, frameLength - height);
 			chunkTo = this.#committedRows;
 			widthEpochAppendFrom = this.#widthEpochBaselineRows;
-			const appendBoundary = liveRegionPinned ? finalBoundary : frameLength;
+			const appendBoundary = commitCeiling;
 			widthEpochAppendTo = hasVisibleOverlay ? widthEpochAppendFrom : Math.max(widthEpochAppendFrom, appendBoundary);
 		} else if (
 			frameLength <= this.#committedRows ||
@@ -3821,7 +3820,7 @@ export class TUI extends Container {
 			// "duplication, never loss" is the ED3-unsafe fallback contract.
 			committedPrefixResliced = true;
 			windowTop = Math.max(0, frameLength - height);
-			chunkTo = liveRegionPinned ? Math.min(windowTop, finalBoundary) : windowTop;
+			chunkTo = Math.min(windowTop, commitCeiling);
 			this.#committedRows = chunkTo;
 			this.#committedPrefix = rawFrame.slice(0, chunkTo);
 		} else if (geometryChanged && Math.max(0, frameLength - height) < this.#committedRows) {
@@ -3853,9 +3852,7 @@ export class TUI extends Container {
 			chunkTo =
 				hasVisibleOverlay || geometryChanged
 					? this.#committedRows
-					: liveRegionPinned
-						? Math.min(windowTop, Math.max(this.#committedRows, finalBoundary))
-						: windowTop;
+					: Math.min(windowTop, Math.max(this.#committedRows, commitCeiling));
 			if (geometryChanged) {
 				committedPrefixResliced = true;
 				this.#committedPrefix = rawFrame.slice(0, this.#committedRows);
@@ -3965,7 +3962,7 @@ export class TUI extends Container {
 			let commitTo: number;
 			if (replayUnresolvedWidthEpoch) {
 				commitFrom = 0;
-				commitTo = liveRegionPinned ? Math.min(windowTop, finalBoundary) : windowTop;
+				commitTo = Math.min(windowTop, commitCeiling);
 				scrollRows = commitTo;
 			} else if (logicalAppend && !logicalPrefixAppend) {
 				const sourceWindowTop = Math.max(0, widthEpochSourceBoundary - height);

package/src/utils.ts

@@ -225,9 +225,7 @@ export function getSegmenter(): Intl.Segmenter {
 // added back so width matches the native truncate/slice/wrap helpers.
 const OSC66_SPAN_REGEX = /\x1b\]66;([^;]*);([\s\S]*?)(?:\x07|\x1b\\)/g;
 const OSC66_PREFIX = "\x1b]66;";
-const ESC = "\x1b";
-const TAB = "\t";
-const LONG_WIDTH_FAST_PATH_MIN = 128;
+const PRINTABLE_ASCII_REGEX = /^[\u0020-\u007e]*$/;
 
 // Pin Bun.stringWidth semantics to the native width engine and guard against Bun
 // default drift: strip ANSI/OSC (don't count escape bytes) and treat
@@ -243,8 +241,6 @@ const STRING_WIDTH_OPTS = { countAnsiEscapeCodes: false, ambiguousIsNarrow: true
 // `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).
@@ -274,19 +270,28 @@ function hangulCompatibilityJamoTargetWidth(): 1 | 2 | null {
 // 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;
+function correctHangulCompatibilityJamoWidth(
+	width: number,
+	compatibilityJamoCount: number,
+	fillerCount: number,
+): number {
+	if (compatibilityJamoCount === 0) 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;
+	return target === 1 ? width - compatibilityJamoCount : width - fillerCount * HANGUL_COMPAT_JAMO_BUN_WIDTH;
 }
 
+// Terminal redraws re-measure the same visible lines every frame, usually as
+// the same string objects (JSC caches their hashes, so repeat lookups are
+// O(1) — cheaper than even the ASCII fast scan). Strings longer than the
+// length gate skip the cache entirely: hashing them costs as much as measuring
+// them, and retaining them would pin large render buffers. Worst-case
+// retention is MAX * MAX_LEN UTF-16 units (~2 MiB); cleared when the width
+// configuration epoch changes.
+const VISIBLE_WIDTH_CACHE_MAX = 2048;
+const VISIBLE_WIDTH_CACHE_MAX_LEN = 512;
+const visibleWidthCache = new Map<string, number>();
+let visibleWidthCacheEpoch = widthConfigEpoch;
+
 /**
  * Visible width of a string in terminal columns, excluding ANSI/OSC escapes.
  *
@@ -296,65 +301,51 @@ function correctHangulCompatibilityJamoWidth(width: number, str: string): number
  */
 export function visibleWidth(str: string): number {
 	if (!str) return 0;
-
-	// Long non-escape text is faster through Bun's native scanner than through
-	// a JS printable-ASCII prepass. Escape-bearing strings stay on the scanner
-	// below so CSI/OSC-heavy render output can still bail out at the first ESC.
-	if (str.length >= LONG_WIDTH_FAST_PATH_MIN && !str.includes(ESC)) {
-		let width = Bun.stringWidth(str, STRING_WIDTH_OPTS);
-		let tabCount = 0;
-		for (let tabIndex = str.indexOf(TAB); tabIndex !== -1; tabIndex = str.indexOf(TAB, tabIndex + 1)) {
-			tabCount++;
+	const cacheable = str.length <= VISIBLE_WIDTH_CACHE_MAX_LEN;
+	if (cacheable) {
+		if (visibleWidthCacheEpoch !== widthConfigEpoch) {
+			visibleWidthCache.clear();
+			visibleWidthCacheEpoch = widthConfigEpoch;
 		}
-		if (tabCount > 0) width += tabCount * DEFAULT_TAB_WIDTH;
-		return correctHangulCompatibilityJamoWidth(width, str);
+		const cached = visibleWidthCache.get(str);
+		if (cached !== undefined) return cached;
 	}
 
-	let tabCount = 0;
-	let i = 0;
-	for (; i < str.length; i++) {
-		const code = str.charCodeAt(i);
-		if (code < 0x20 || code > 0x7e) {
-			if (code === 0x09) {
-				tabCount++;
-				continue;
-			}
-			break;
+	// This regex compiles to a native ASCII scan, cheaper than Bun's width
+	// scanner for the overwhelmingly common source-code path.
+	if (PRINTABLE_ASCII_REGEX.test(str)) {
+		if (cacheable) {
+			if (visibleWidthCache.size >= VISIBLE_WIDTH_CACHE_MAX) visibleWidthCache.clear();
+			visibleWidthCache.set(str, str.length);
 		}
-	}
-	if (i === str.length) {
-		return tabCount === 0 ? str.length : str.length + tabCount * (DEFAULT_TAB_WIDTH - 1);
+		return str.length;
 	}
 
-	if (tabCount === 0) {
-		let tabIndex = str.indexOf(TAB, i + 1);
-		if (tabIndex !== -1) {
-			tabCount = 1;
-			for (tabIndex = str.indexOf(TAB, tabIndex + 1); tabIndex !== -1; tabIndex = str.indexOf(TAB, tabIndex + 1)) {
-				tabCount++;
-			}
-		}
-	} else {
-		for (let tabIndex = str.indexOf(TAB, i + 1); tabIndex !== -1; tabIndex = str.indexOf(TAB, tabIndex + 1)) {
+	let tabCount = 0;
+	let compatibilityJamoCount = 0;
+	let fillerCount = 0;
+	let hasEsc = false;
+	for (let i = 0; i < str.length; i++) {
+		const code = str.charCodeAt(i);
+		if (code === 0x09) {
 			tabCount++;
+		} else if (code === 0x1b) {
+			hasEsc = true;
+		} else if (code >= 0x3131 && code <= 0x318e) {
+			compatibilityJamoCount++;
+			if (code === HANGUL_FILLER_CODE_POINT) fillerCount++;
 		}
 	}
 
-	// `Bun.stringWidth` is a JSC builtin (no per-call N-API number box, unlike
-	// the native scanner that traps under Bun 1.3.x GC/N-API load). It strips
-	// CSI/OSC to zero cells and shares the native engine's UAX#11 width tables.
 	let width = Bun.stringWidth(str, STRING_WIDTH_OPTS);
 	if (tabCount > 0) width += tabCount * DEFAULT_TAB_WIDTH;
 
-	// OSC 66: add back each stripped span as `scale * (explicit w ?? payload
-	// width)`. Matched rather than replaced to avoid reallocating the string.
-	if (str.includes(OSC66_PREFIX, i)) {
+	if (hasEsc && str.includes(OSC66_PREFIX)) {
 		OSC66_SPAN_REGEX.lastIndex = 0;
 		for (let m = OSC66_SPAN_REGEX.exec(str); m !== null; m = OSC66_SPAN_REGEX.exec(str)) {
 			let scale = 1;
 			let explicit: number | undefined;
 			for (const part of m[1].split(":")) {
-				// metadata keys are single chars, e.g. `s=2`, `w=5`
 				if (part.indexOf("=") !== 1) continue;
 				const value = Number.parseInt(part.slice(2), 10);
 				if (!Number.isFinite(value)) continue;
@@ -368,11 +359,15 @@ export function visibleWidth(str: string): number {
 		}
 	}
 
-	return correctHangulCompatibilityJamoWidth(width, str);
+	width = correctHangulCompatibilityJamoWidth(width, compatibilityJamoCount, fillerCount);
+	if (cacheable) {
+		if (visibleWidthCache.size >= VISIBLE_WIDTH_CACHE_MAX) visibleWidthCache.clear();
+		visibleWidthCache.set(str, width);
+	}
+	return width;
 }
 
 /**
- * True when a row carries a Kitty OSC 66 text-sizing span (`\x1b]66;…`).
  * Scaled spans must bypass wrapping/padding and, when scaled up, reserve the
  * terminal rows their multicell glyphs flow into.
  */