@oh-my-pi/pi-tui 15.10.1 → 15.10.3

package/CHANGELOG.md

@@ -2,7 +2,32 @@
 
 ## [Unreleased]
 
+## [15.10.3] - 2026-06-08
+
+### Fixed
+
+- Fixed DEC 2048 in-band resize reports (`CSI 48;rows;cols;hpx;wpx t`) leaking into the focused editor as literal text during a rapid resize. When the window is resized quickly the event loop stays busy long enough for the `StdinBuffer` flush timeout to fire mid-report; the `\x1b[48;…` prefix was emitted as one event and the tail (e.g. `8;125;1156;1125t`) arrived as bare printable characters that the editor inserted. `ProcessTerminal` now reassembles a split in-band report (including a split at the bare `\x1b[4` type field) until its terminator and then drives the resize. A reassembled sequence that turns out not to be a resize report — such as a split kitty key like `\x1b[48;5u` (codepoint 48 = `0`) — is forwarded to the input handler as a single escape sequence rather than dropped or leaked.
+- Coalesced terminal-multiplexer SIGWINCH events into a single forced render once the pane stops resizing so closing/dragging a tmux/screen/zellij split no longer flashes the viewport blank before the new geometry repaints ([#2088](https://github.com/can1357/oh-my-pi/issues/2088)).
+
+## [15.10.2] - 2026-06-08
+
+### Added
+
+- Added exported `canonicalKeyId` and `addKeyAliases` keybinding helpers so consumers can share the same canonical shortcut matching semantics as `KeybindingsManager`.
+- Added `super` modifier support to native key parsing/matching and bound `super+alt+backspace` / `super+alt+delete` (and `super+alt+d`) into the word-delete defaults so Ghostty's default macOS Option+Backspace wire (`ESC [127;11u` — kitty modifier 11 = super|alt) deletes a word instead of falling through to single-char delete ([#2064](https://github.com/can1357/oh-my-pi/issues/2064)).
+
+### Fixed
+
+- Fixed focus-changing in-place menus leaving stale Working/menu rows and parking the hardware cursor in the old menu viewport on terminals without a scroll-position oracle.
+- Fixed redundant terminal cursor updates so repeated renders that do not change the cursor row, column, or visibility no longer emit ANSI move/hide sequences
+- Fixed repeated cursor updates during no-op re-renders by reusing the last known cursor state, preventing unnecessary cursor position changes and hide/show sequences
+- Fixed the kitty keyboard progressive-enhancement probe to honor the `CSI ? <flags> u` reply even when the terminal answers the DA1 sentinel first. Previously the kitty reply was discarded once the DA1-driven `modifyOtherKeys` fallback engaged, so terminals like Superset/xterm-on-Electron stayed on the fallback and delivered Shift+Enter as a bare `\r` ([#2042](https://github.com/can1357/oh-my-pi/issues/2042)).
+- Bounded TUI line fitting for oversized raw rows so ANSI-heavy subagent output and zero-width-heavy text cannot grow render buffers independently of the viewport or hide visible suffix text ([#2045](https://github.com/can1357/oh-my-pi/issues/2045)).
+- Fixed tmux offscreen-shrink frames to skip repainting when the visible tail is unchanged, avoiding intermittent blank/refresh flashes in pane terminals ([#2046](https://github.com/can1357/oh-my-pi/issues/2046)).
+- Fixed Windows ConPTY hosts (Windows Terminal, Tabby, Hyper, VS Code) parking the viewport at the top of a full paint after a `/resume` or any long-session repaint. `ProcessTerminal#safeWrite` now splits oversized writes into ≤ 8 KiB pieces at line boundaries on `win32` and inside WSL (where stdout still crosses ConPTY at the `wslhost` boundary) so each underlying `WriteFile` stays below the ~32 KiB threshold where ConPTY stops tracking the cursor; the data was always delivered, but the host UI's scroll position would not follow until any focus event forced a re-query. ([#2034](https://github.com/can1357/oh-my-pi/issues/2034))
+
 ## [15.10.1] - 2026-06-07
+
 ### Breaking Changes
 
 - Removed Kitty temp-file image transmission, its startup support probe, the `PI_KITTY_IMAGE_TRANSMISSION` override, and the temp-file helper exports. Kitty/Ghostty image payloads now stay on in-band base64 before placeholder/direct placement, avoiding blank first renders from temp-file load races.
@@ -69,6 +94,7 @@
 - Fixed DECCARA background-fill optimization running when synchronized output is disabled, which could expose default-background gaps during rapidly updating tool-use panels ([#2000](https://github.com/can1357/oh-my-pi/issues/2000)).
 
 ## [15.9.67] - 2026-06-06
+
 ### Added
 
 - Added `setPaddingX` to `Box` so horizontal padding can be updated programmatically after creation
@@ -1157,4 +1183,4 @@ Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mon
 
 ### Fixed
 
-- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))
+- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))

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

@@ -6,7 +6,7 @@ export declare class Text implements Component {
     #private;
     constructor(text?: string, paddingX?: number, paddingY?: number, customBgFn?: (text: string) => string);
     getText(): string;
-    setText(text: string): void;
+    setText(text: string): boolean;
     setCustomBgFn(customBgFn?: (text: string) => string): void;
     invalidate(): void;
     render(width: number): string[];

package/dist/types/keybindings.d.ts

@@ -102,11 +102,11 @@ export declare const TUI_KEYBINDINGS: {
         readonly description: "Delete character forward";
     };
     readonly "tui.editor.deleteWordBackward": {
-        readonly defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace"];
+        readonly defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace", "super+alt+backspace"];
         readonly description: "Delete word backward";
     };
     readonly "tui.editor.deleteWordForward": {
-        readonly defaultKeys: ["alt+delete", "alt+d"];
+        readonly defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"];
         readonly description: "Delete word forward";
     };
     readonly "tui.editor.deleteToLineStart": {
@@ -174,6 +174,8 @@ export interface KeybindingConflict {
     key: KeyId;
     keybindings: string[];
 }
+export declare function canonicalKeyId(key: string): string;
+export declare function addKeyAliases(keys: Set<string>, key: KeyId): void;
 export declare class KeybindingsManager {
     #private;
     constructor(definitions: KeybindingDefinitions, userBindings?: KeybindingsConfig);

package/dist/types/terminal.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Split `data` into chunks no larger than `maxChunkSize`, preferring a line
+ * boundary (`\n`) as the cut point so escape sequences (which never contain
+ * `\n`) stay intact. The TUI's full-paint buffers are line-structured
+ * (`buffer += "\r\n"` between rows), so a newline almost always exists within
+ * the window. The fallback for a buffer with no newline in range is a hard
+ * cut at `maxChunkSize`: the ConPTY viewport bug from a single oversized
+ * write is strictly worse than a one-frame escape-sequence glitch on a buffer
+ * the renderer effectively never produces.
+ *
+ * Exported for unit testing of the chunking contract; `#safeWrite` is the
+ * sole production caller.
+ */
+export declare function chunkForConPTY(data: string, maxChunkSize?: number): string[];
 /**
  * Emergency terminal restore - call this from signal/crash handlers
  * Resets terminal state without requiring access to the ProcessTerminal instance

package/package.json

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

package/src/components/editor.ts

@@ -1109,12 +1109,18 @@ export class Editor implements Component, Focusable {
 		else if (matchesKey(data, "ctrl+w")) {
 			this.#deleteWordBackwards();
 		}
-		// Option/Alt+Backspace - Delete word backwards
-		else if (matchesKey(data, "alt+backspace")) {
+		// Option/Alt+Backspace - Delete word backwards.
+		// Ghostty on macOS reports Option+Backspace as super+alt (kitty mod 11) — see #2064.
+		else if (matchesKey(data, "alt+backspace") || matchesKey(data, "super+alt+backspace")) {
 			this.#deleteWordBackwards();
 		}
-		// Option/Alt+D - Delete word forwards
-		else if (matchesKey(data, "alt+d") || matchesKey(data, "alt+delete")) {
+		// Option/Alt+D and Option+Delete - Delete word forwards. Same Ghostty quirk applies.
+		else if (
+			matchesKey(data, "alt+d") ||
+			matchesKey(data, "alt+delete") ||
+			matchesKey(data, "super+alt+d") ||
+			matchesKey(data, "super+alt+delete")
+		) {
 			this.#deleteWordForwards();
 		}
 		// Ctrl+Y - Yank from kill ring

package/src/components/loader.ts

@@ -88,8 +88,8 @@ export class Loader extends Text {
 
 	#updateDisplay() {
 		const frame = this.#frames[this.#currentFrame];
-		this.setText(`${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`);
-		if (this.#ui) {
+		const text = `${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`;
+		if (this.setText(text) && this.#ui) {
 			this.#ui.requestRender();
 		}
 	}

package/src/components/text.ts

@@ -26,14 +26,15 @@ export class Text implements Component {
 		return this.#text;
 	}
 
-	setText(text: string): void {
+	setText(text: string): boolean {
 		if (text === this.#text) {
-			return;
+			return false;
 		}
 		this.#text = text;
 		this.#cachedText = undefined;
 		this.#cachedWidth = undefined;
 		this.#cachedLines = undefined;
+		return true;
 	}
 
 	setCustomBgFn(customBgFn?: (text: string) => string): void {

package/src/keybindings.ts

@@ -100,11 +100,11 @@ export const TUI_KEYBINDINGS = {
 		description: "Delete character forward",
 	},
 	"tui.editor.deleteWordBackward": {
-		defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace"],
+		defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace", "super+alt+backspace"],
 		description: "Delete word backward",
 	},
 	"tui.editor.deleteWordForward": {
-		defaultKeys: ["alt+delete", "alt+d"],
+		defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"],
 		description: "Delete word forward",
 	},
 	"tui.editor.deleteToLineStart": {
@@ -182,7 +182,7 @@ function isAsciiUppercaseLetter(key: string): boolean {
 	return code >= 65 && code <= 90;
 }
 
-function canonicalKeyId(key: string): string {
+export function canonicalKeyId(key: string): string {
 	let offset = 0;
 	const modifiers: string[] = [];
 	let foundModifier = true;
@@ -214,7 +214,7 @@ function canonicalKeyId(key: string): string {
 	return `${modifiers.join("+")}+${base}`;
 }
 
-function addKeyAliases(keys: Set<string>, key: KeyId): void {
+export function addKeyAliases(keys: Set<string>, key: KeyId): void {
 	const canonical = canonicalKeyId(key);
 	keys.add(canonical);
 	if (SHIFTED_SYMBOL_KEYS.has(canonical)) {

package/src/terminal.ts

@@ -9,6 +9,58 @@ 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";
 
+/**
+ * Maximum bytes per `process.stdout.write` call on Windows.
+ *
+ * Windows ConPTY ties viewport tracking to per-`WriteFile` boundaries: when a
+ * single write exceeds ~32-64 KB, the pseudo-console stops following the
+ * cursor and the host UI's viewport stays parked at whatever scroll position
+ * the write started from. The visible symptom is that a full-paint of a long
+ * session (resume, history rebuild, large permission dialog) shows only the
+ * first ~30 lines until any focus event forces the host to re-query the
+ * cursor. The data is delivered correctly — it's purely a viewport-sync bug.
+ *
+ * 8 KiB is well below the 32 KiB threshold reported on Windows Terminal and
+ * leaves headroom for the other ConPTY hosts (Tabby, Hyper, VS Code) where
+ * the exact limit is undocumented. The cost is a handful of extra syscalls
+ * per full paint — invisible compared to the cost of the paint itself.
+ */
+const MAX_CONPTY_WRITE_CHUNK = 8 * 1024;
+
+/**
+ * Split `data` into chunks no larger than `maxChunkSize`, preferring a line
+ * boundary (`\n`) as the cut point so escape sequences (which never contain
+ * `\n`) stay intact. The TUI's full-paint buffers are line-structured
+ * (`buffer += "\r\n"` between rows), so a newline almost always exists within
+ * the window. The fallback for a buffer with no newline in range is a hard
+ * cut at `maxChunkSize`: the ConPTY viewport bug from a single oversized
+ * write is strictly worse than a one-frame escape-sequence glitch on a buffer
+ * the renderer effectively never produces.
+ *
+ * Exported for unit testing of the chunking contract; `#safeWrite` is the
+ * sole production caller.
+ */
+export function chunkForConPTY(data: string, maxChunkSize: number = MAX_CONPTY_WRITE_CHUNK): string[] {
+	if (data.length <= maxChunkSize) return [data];
+	const chunks: string[] = [];
+	let pos = 0;
+	while (pos < data.length) {
+		const remaining = data.length - pos;
+		if (remaining <= maxChunkSize) {
+			chunks.push(data.slice(pos));
+			break;
+		}
+		const windowEnd = pos + maxChunkSize;
+		// Prefer the last newline inside the window so escape sequences stay
+		// intact within their chunk; hard-cut at `windowEnd` otherwise.
+		const nl = data.lastIndexOf("\n", windowEnd - 1);
+		const cut = nl >= pos ? nl + 1 : windowEnd;
+		chunks.push(data.slice(pos, cut));
+		pos = cut;
+	}
+	return chunks;
+}
+
 /**
  * Minimal terminal interface for TUI
  */
@@ -203,6 +255,8 @@ export class ProcessTerminal implements Terminal {
 	#privateModeCallbacks: Array<(mode: number, supported: boolean) => void> = [];
 	/** Whether DEC 2048 in-band resize notifications are currently enabled. */
 	#inBandResizeActive = false;
+	/** Reassembly buffer for a DEC 2048 in-band resize report split across stdin reads. */
+	#inBandResizeBuffer = "";
 	#reportedColumns?: number;
 	#reportedRows?: number;
 	#osc11PollTimer?: Timer;
@@ -436,6 +490,46 @@ export class ProcessTerminal implements Terminal {
 				}
 			}
 
+			// In-band resize report (DEC 2048) split across stdin reads. The report
+			// is `\x1b[48;rows;cols;yPx;xPx t`; when the StdinBuffer flush timeout
+			// elapses mid-sequence — common during a rapid resize that keeps the
+			// event loop busy — the `\x1b[48;…` prefix arrives as one event and the
+			// tail (`…;xPx t`) arrives as bare character events that would otherwise
+			// leak into the prompt as literal keystrokes. Reassemble until the
+			// terminator, then fall through to the resize handler below. A
+			// reassembled sequence that turns out not to be a resize report (e.g. a
+			// split kitty `\x1b[48;…u` for a digit key) is forwarded to the input
+			// handler rather than dropped.
+			const inBandResizePartialPattern = /^\x1b\[4[\d;]*$/;
+			const isInBandResizePartial = this.#inBandResizeActive && inBandResizePartialPattern.test(sequence);
+			if (this.#inBandResizeBuffer && sequence.startsWith("\x1b")) {
+				// A new escape interrupted the partial; the stale partial is
+				// unrecoverable. If the new escape is itself an in-band prefix,
+				// restart reassembly with it; otherwise let it flow through below.
+				this.#inBandResizeBuffer = isInBandResizePartial ? sequence : "";
+				if (isInBandResizePartial) return;
+			} else if (this.#inBandResizeBuffer || isInBandResizePartial) {
+				this.#inBandResizeBuffer += sequence;
+				if (this.#inBandResizeBuffer.length > 256) {
+					this.#inBandResizeBuffer = "";
+					return;
+				}
+				const lastCode = this.#inBandResizeBuffer.charCodeAt(this.#inBandResizeBuffer.length - 1);
+				if (lastCode >= 0x40 && lastCode <= 0x7e) {
+					// Terminator arrived: let the resize handler below claim it, or
+					// fall through to the input handler if it is not a resize report.
+					sequence = this.#inBandResizeBuffer;
+					this.#inBandResizeBuffer = "";
+				} else if (!inBandResizePartialPattern.test(this.#inBandResizeBuffer)) {
+					// Diverged from a valid in-band prefix — drop the garbled report.
+					this.#inBandResizeBuffer = "";
+					return;
+				} else {
+					// Still accumulating the report.
+					return;
+				}
+			}
+
 			// In-band resize report (DEC mode 2048). Unsolicited and not tied to a
 			// sentinel: update reported geometry + cell size, then drive the resize
 			// handler so the renderer reflows.
@@ -504,11 +598,20 @@ export class ProcessTerminal implements Terminal {
 			}
 
 			const match = sequence.match(kittyResponsePattern);
-			if (match && !this.#modifyOtherKeysActive) {
+			if (match) {
 				if (this.#modifyOtherKeysTimeout) {
 					clearTimeout(this.#modifyOtherKeysTimeout);
 					this.#modifyOtherKeysTimeout = undefined;
 				}
+				// A DA1 sentinel that beat the kitty reply may have already
+				// engaged the modifyOtherKeys fallback (terminals such as
+				// Superset/xterm-on-Electron answer DA1 before `\x1b[?u`).
+				// Kitty is strictly preferred — undo the fallback so the two
+				// modes do not stack. See #2042.
+				if (this.#modifyOtherKeysActive) {
+					this.#safeWrite("\x1b[>4;0m");
+					this.#modifyOtherKeysActive = false;
+				}
 				// Any reply to `\x1b[?u` means the terminal speaks the kitty keyboard
 				// protocol. The reported flag value is the *current* stack-top — fresh
 				// terminals report 0 — so support is implied by the reply itself, not by
@@ -909,6 +1012,7 @@ export class ProcessTerminal implements Terminal {
 		this.#osc99Capabilities.clear();
 		setOsc99Supported(false);
 		this.#privateCsiResponseBuffer = "";
+		this.#inBandResizeBuffer = "";
 		this.#da1SentinelOwners.length = 0;
 		this.#privateModeCallbacks = [];
 		this.#privateModeSupport.clear();
@@ -978,7 +1082,23 @@ export class ProcessTerminal implements Terminal {
 		// files). They serve no purpose there and would surface as visible noise.
 		if (!process.stdout.isTTY) return;
 		try {
-			process.stdout.write(data);
+			// Windows ConPTY drops viewport tracking when a single write exceeds
+			// ~32-64 KB: the host UI's scroll position stays parked at wherever
+			// the write began, even though every byte landed in scrollback. Split
+			// large paints into newline-aligned chunks so each underlying
+			// `WriteFile` stays well below the threshold. The gate also covers
+			// WSL — `process.platform === "linux"` there, but stdout still
+			// crosses into ConPTY at the `wslhost` boundary, so the same per-
+			// WriteFile cap applies. Non-ConPTY PTYs keep the single-write fast
+			// path. See #2034.
+			const conptyHosted = process.platform === "win32" || isWindowsSubsystemForLinux();
+			if (conptyHosted && data.length > MAX_CONPTY_WRITE_CHUNK) {
+				for (const chunk of chunkForConPTY(data, MAX_CONPTY_WRITE_CHUNK)) {
+					process.stdout.write(chunk);
+				}
+			} else {
+				process.stdout.write(data);
+			}
 		} catch (err) {
 			// Any write failure means terminal is dead - no recovery possible
 			this.#dead = true;

package/src/tui.ts

@@ -47,6 +47,12 @@ const SEGMENT_RESET = "\x1b[0m";
 const LINE_TERMINATOR = "\x1b[0m\x1b]8;;\x07";
 const ERASE_LINE = "\x1b[2K";
 const ERASE_TO_END_OF_LINE = "\x1b[K";
+// Keep the common short-row path out of native width/truncation. Longer rows
+// are fit by visible cells, not source code units, so zero-width-heavy prefixes
+// cannot hide visible suffix text that still belongs in the viewport.
+const LINE_FIT_MIN_SOURCE_CODE_UNITS = 4096;
+const LINE_FIT_MAX_SOURCE_CODE_UNITS = 65536;
+const LINE_FIT_SOURCE_WIDTH_MULTIPLIER = 64;
 // Hide the hardware cursor before each paint/move write. Ghostty-style bar
 // cursors can otherwise leave visual afterimages while the TUI repaints the
 // row under a visible cursor. Paint writes also disable terminal autowrap:
@@ -68,11 +74,13 @@ const CURSOR_BEGIN = `${HIDE_CURSOR}${SYNC_OUTPUT_BEGIN}`;
 const CURSOR_BEGIN_NO_SYNC = HIDE_CURSOR;
 const CURSOR_END = SYNC_OUTPUT_END;
 const CURSOR_END_NO_SYNC = "";
-// Mouse reporting (normal click tracking + SGR extended coordinates), enabled
-// only for the lifetime of a fullscreen overlay so the rest of the app keeps the
-// terminal's native text selection.
-const MOUSE_TRACKING_ON = "\x1b[?1000h\x1b[?1006h";
-const MOUSE_TRACKING_OFF = "\x1b[?1006l\x1b[?1000l";
+// Mouse reporting, enabled only for the lifetime of a fullscreen overlay so the
+// rest of the app keeps the terminal's native text selection. 1000h = button
+// click tracking, 1003h = any-motion tracking so overlays can light up hover
+// targets (the pointer moving with no button held), 1006h = SGR extended
+// coordinates so columns/rows past 223 are reported.
+const MOUSE_TRACKING_ON = "\x1b[?1000h\x1b[?1003h\x1b[?1006h";
+const MOUSE_TRACKING_OFF = "\x1b[?1006l\x1b[?1003l\x1b[?1000l";
 
 type InputListenerResult = { consume?: boolean; data?: string } | undefined;
 type InputListener = (data: string) => InputListenerResult;
@@ -433,6 +441,24 @@ type RenderIntent =
 	| { kind: "shrink" }
 	| { kind: "diff"; firstChanged: number; lastChanged: number; appendedLines: boolean };
 
+interface HardwareCursorState {
+	row: number;
+	col: number;
+	visible: boolean;
+}
+
+interface HardwareCursorUpdate {
+	toRow: number;
+	state: HardwareCursorState | null;
+	visible?: boolean;
+}
+
+interface CursorControlResult extends HardwareCursorUpdate {
+	seq: string;
+	toCol: number;
+	visible: boolean;
+}
+
 interface PreparedLine {
 	raw: string;
 	width: number;
@@ -458,8 +484,21 @@ export class TUI extends Container {
 	#renderScheduler: RenderScheduler;
 	#lastRenderAt = 0;
 	static readonly #MIN_RENDER_INTERVAL_MS = 1000 / 30;
+	// Pane-reflow settle window for tmux/screen/zellij. The host process gets
+	// SIGWINCH (and `process.stdout` already reports the new geometry) before
+	// the multiplexer finishes repainting the pane at the new size, and
+	// drag-resize/pane-close animations fire several events in flight. A forced
+	// render on each SIGWINCH races those mid-reflow paints — the multiplexer's
+	// catch-up paint then partially overwrites the TUI output, which the user
+	// sees as a viewport flash or blank screen before the next throttled frame
+	// arrives (issue #2088). Coalescing every SIGWINCH inside this window into
+	// a single forced render lets the multiplexer settle first.
+	static readonly #MULTIPLEXER_RESIZE_DEBOUNCE_MS = 50;
 	#cursorRow = 0; // Logical cursor row (end of rendered content)
 	#hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
+	#hardwareCursorState: HardwareCursorState | null = null;
+	#hardwareCursorVisibilityKnown = false;
+	#hardwareCursorVisible = false;
 	#viewportTopRow = 0; // Content row currently mapped to screen row 0
 	#sixelProbePendingDa = false;
 	#sixelProbePendingGraphics = false;
@@ -504,6 +543,9 @@ export class TUI extends Container {
 	#clearScrollbackOnNextRender = false;
 	#forceViewportRepaintOnNextRender = false;
 	#allowUnknownViewportMutationOnNextRender = false;
+	// Focus changes are local live chrome (menus/editor/cursor), so the next
+	// frame may repaint an unknown-at-bottom viewport without waiting for a checkpoint.
+	#focusChangedSinceLastRender = false;
 	#eagerNativeScrollbackRebuild = false;
 	// Set when eager mode is switched off; applied after the next frame is
 	// classified so teardown frames from the same event batch still render
@@ -519,6 +561,13 @@ export class TUI extends Container {
 	// between the viewport and scrollback, so the previous frame no longer
 	// describes the screen. Tracking only the dimension delta misses this.
 	#resizeEventPending = false;
+	// Active multiplexer SIGWINCH debounce. Reset on each event so the timer
+	// only fires once the pane stops resizing. Forced renders (resetDisplay,
+	// finishSixelProbe, …) issued during the settle window route through the
+	// same timer; their `clearScrollback` intent is OR'd into the deferred
+	// flag below so the settled paint still honours every caller's request.
+	#multiplexerResizeTimer: RenderTimer | undefined;
+	#deferredForcedClearScrollback = false;
 	#stopped = false;
 
 	// Transient alternate-screen state for a fullscreen overlay. While active, the
@@ -612,6 +661,7 @@ export class TUI extends Container {
 		this.#syncTerminalCursorMode(this.#focusedComponent);
 		if (!enabled) {
 			this.terminal.hideCursor();
+			this.#recordHardwareCursorHidden();
 		}
 		this.requestRender();
 	}
@@ -687,12 +737,16 @@ export class TUI extends Container {
 	}
 
 	setFocus(component: Component | null): void {
+		const previousFocusedComponent = this.#focusedComponent;
 		// Clear focused flag on old component
-		if (isFocusable(this.#focusedComponent)) {
-			this.#focusedComponent.focused = false;
+		if (isFocusable(previousFocusedComponent)) {
+			previousFocusedComponent.focused = false;
 		}
 
 		this.#focusedComponent = component;
+		if (previousFocusedComponent !== component) {
+			this.#focusChangedSinceLastRender = true;
+		}
 
 		// Set focused flag on new component and keep its software/hardware cursor
 		// rendering mode aligned with TUI's single cursor-visibility preference.
@@ -714,6 +768,7 @@ export class TUI extends Container {
 			this.setFocus(component);
 		}
 		this.terminal.hideCursor();
+		this.#recordHardwareCursorHidden();
 		this.requestRender();
 
 		// Return handle for controlling this overlay
@@ -727,7 +782,10 @@ export class TUI extends Container {
 						const topVisible = this.#getTopmostVisibleOverlay();
 						this.setFocus(topVisible?.component ?? entry.preFocus);
 					}
-					if (this.overlayStack.length === 0) this.terminal.hideCursor();
+					if (this.overlayStack.length === 0) {
+						this.terminal.hideCursor();
+						this.#recordHardwareCursorHidden();
+					}
 					this.requestRender();
 				}
 			},
@@ -760,7 +818,10 @@ export class TUI extends Container {
 		// Find topmost visible overlay, or fall back to preFocus
 		const topVisible = this.#getTopmostVisibleOverlay();
 		this.setFocus(topVisible?.component ?? overlay.preFocus);
-		if (this.overlayStack.length === 0) this.terminal.hideCursor();
+		if (this.overlayStack.length === 0) {
+			this.terminal.hideCursor();
+			this.#recordHardwareCursorHidden();
+		}
 		this.requestRender();
 	}
 
@@ -816,12 +877,29 @@ export class TUI extends Container {
 		this.terminal.start(
 			data => this.#handleInput(data),
 			() => {
-				// Repaint immediately rather than via the throttled path: a resize must
-				// clear and replay at the fresh geometry before the terminal's reflow
-				// settles into a state a throttled frame would race. Forced render skips
-				// the 30fps coalescing window, matching resetDisplay()'s prompt repaint.
+				// Real terminals deliver SIGWINCH (and the equivalent ConPTY
+				// notification) atomically with the new `process.stdout` geometry, so
+				// a forced render must fire immediately: it clears and replays at the
+				// fresh size before the terminal's reflow settles into a state a
+				// throttled frame would race. Multiplexer panes (tmux/screen/zellij)
+				// do not give that guarantee. The host receives SIGWINCH while the
+				// multiplexer is still mid-reflow — it has not finished repainting
+				// the pane buffer at the new size — and a drag-resize or pane-close
+				// animation fires several events in flight. Forcing a render on each
+				// event races those mid-reflow paints: the multiplexer's catch-up
+				// paint then partially overwrites the TUI output, which the user sees
+				// as a viewport flash or blank screen before the next throttled
+				// frame arrives (issue #2088). `#armMultiplexerResizeTimer` coalesces
+				// SIGWINCHes (and any forced repaints arriving during the settle
+				// window) into a single render once the pane is quiet —
+				// `#resizeEventPending` is set first so the eventual render still
+				// classifies as a resize.
 				this.#resizeEventPending = true;
-				this.requestRender(true);
+				if (!isMultiplexerSession()) {
+					this.requestRender(true);
+					return;
+				}
+				this.#armMultiplexerResizeTimer(false);
 			},
 		);
 		for (const listener of this.#startListeners) {
@@ -832,6 +910,7 @@ export class TUI extends Container {
 			}
 		}
 		this.terminal.hideCursor();
+		this.#recordHardwareCursorHidden();
 		this.#querySixelSupport();
 		this.#queryCellSize();
 		this.requestRender(true, { clearScrollback: options?.clearScrollback === true });
@@ -1023,6 +1102,11 @@ export class TUI extends Container {
 			this.#renderTimer.cancel();
 			this.#renderTimer = undefined;
 		}
+		if (this.#multiplexerResizeTimer) {
+			this.#multiplexerResizeTimer.cancel();
+			this.#multiplexerResizeTimer = undefined;
+		}
+		this.#deferredForcedClearScrollback = false;
 		// Place the parent shell on the first line after the rendered content. When
 		// that line is still inside the viewport, moving there and writing `\r` is
 		// enough; emitting `\r\n` would create an extra blank row. If the content
@@ -1043,6 +1127,7 @@ export class TUI extends Container {
 		}
 
 		this.terminal.showCursor();
+		this.#forgetHardwareCursorState();
 		this.terminal.stop();
 	}
 
@@ -1096,6 +1181,15 @@ export class TUI extends Container {
 	resetDisplay(): void {
 		if (this.#stopped) return;
 		this.invalidate();
+		// A reset that lands inside a tmux/screen/zellij resize burst would
+		// paint mid-reflow and re-introduce the flash race (issue #2088).
+		// Fold it into the in-flight debounce instead; the settled paint runs
+		// the same `#prepareForcedRender(!isMultiplexerSession())` path via
+		// `requestRender(true)`, so the clear-scrollback intent is preserved.
+		if (this.#multiplexerResizeTimer) {
+			this.#armMultiplexerResizeTimer(!isMultiplexerSession());
+			return;
+		}
 		this.#prepareForcedRender(!isMultiplexerSession());
 		this.#resizeEventPending = true;
 		this.#renderRequested = false;
@@ -1107,6 +1201,19 @@ export class TUI extends Container {
 		const allowUnknownViewportMutation = options?.allowUnknownViewportMutation === true;
 		this.#allowUnknownViewportMutationOnNextRender ||= allowUnknownViewportMutation;
 		if (force) {
+			// Forced repaints landing inside the multiplexer resize debounce
+			// (e.g. `#finishSixelProbe`, image-budget eviction, a programmatic
+			// `requestRender(true)`) would paint into a still-reflowing pane
+			// and reintroduce the flash race. Fold them into the in-flight
+			// debounce while preserving the caller's `clearScrollback` intent
+			// for the settled paint. The timer's own callback clears
+			// `#multiplexerResizeTimer` before re-entering `requestRender(true)`,
+			// so this guard only catches external callers — the deferred render
+			// itself proceeds straight to `#prepareForcedRender`.
+			if (this.#multiplexerResizeTimer) {
+				this.#armMultiplexerResizeTimer(options?.clearScrollback === true);
+				return;
+			}
 			this.#prepareForcedRender(options?.clearScrollback === true);
 			this.#renderRequested = true;
 			this.#renderScheduler.scheduleImmediate(() => {
@@ -1124,6 +1231,37 @@ export class TUI extends Container {
 		this.#renderScheduler.scheduleImmediate(() => this.#scheduleRender());
 	}
 
+	/**
+	 * Arm or extend the multiplexer-resize debounce so a single forced render
+	 * fires once the pane is quiet. Called by the SIGWINCH callback on every
+	 * resize event, and by `requestRender(true)` / `resetDisplay()` when they
+	 * land inside an in-flight settle window. Each call cancels the prior
+	 * timer, supersedes any queued throttled render (otherwise it would race
+	 * tmux's mid-reflow paint), and OR's the caller's `clearScrollback`
+	 * intent into `#deferredForcedClearScrollback` — the timer's callback
+	 * consumes that flag exactly once when it re-enters `requestRender(true)`.
+	 */
+	#armMultiplexerResizeTimer(clearScrollback: boolean): void {
+		this.#deferredForcedClearScrollback ||= clearScrollback;
+		if (this.#renderTimer) {
+			this.#renderTimer.cancel();
+			this.#renderTimer = undefined;
+		}
+		this.#renderRequested = false;
+		if (this.#multiplexerResizeTimer) {
+			this.#multiplexerResizeTimer.cancel();
+		}
+		this.#multiplexerResizeTimer = this.#renderScheduler.scheduleRender(() => {
+			this.#multiplexerResizeTimer = undefined;
+			if (this.#stopped) {
+				this.#deferredForcedClearScrollback = false;
+				return;
+			}
+			const deferredClearScrollback = this.#deferredForcedClearScrollback;
+			this.#deferredForcedClearScrollback = false;
+			this.requestRender(true, { clearScrollback: deferredClearScrollback });
+		}, TUI.#MULTIPLEXER_RESIZE_DEBOUNCE_MS);
+	}
 	#prepareForcedRender(clearScrollback: boolean): void {
 		const geometryChanged =
 			(this.#previousWidth > 0 && this.#previousWidth !== this.terminal.columns) ||
@@ -1147,6 +1285,13 @@ export class TUI extends Container {
 		if (this.#stopped || this.#renderTimer || !this.#renderRequested) {
 			return;
 		}
+		// Defer any new throttled render scheduled inside the multiplexer
+		// resize settle window: it would race tmux's mid-reflow pane repaint.
+		// `#renderRequested` stays set so the eventual forced render — armed
+		// by the SIGWINCH callback — picks up the latest component state.
+		if (this.#multiplexerResizeTimer) {
+			return;
+		}
 		const elapsed = this.#renderScheduler.now() - this.#lastRenderAt;
 		const delay = Math.max(0, TUI.#MIN_RENDER_INTERVAL_MS - elapsed);
 		this.#renderTimer = this.#renderScheduler.scheduleRender(() => {
@@ -1564,12 +1709,15 @@ export class TUI extends Container {
 		if (wantAlt && !this.#altActive) {
 			this.terminal.write(`\x1b[?1049h${MOUSE_TRACKING_ON}`);
 			this.terminal.hideCursor();
+			this.#forgetHardwareCursorState();
+			this.#recordHardwareCursorHidden();
 			this.#altActive = true;
 			this.#altPreviousLines = [];
 			this.#altEnterWidth = width;
 			this.#altEnterHeight = height;
 		} else if (!wantAlt && this.#altActive) {
 			this.terminal.write(`${MOUSE_TRACKING_OFF}\x1b[?1049l`);
+			this.#forgetHardwareCursorState();
 			this.#altActive = false;
 			this.#altPreviousLines = [];
 			// A resize while on the alt buffer reflowed the terminal's saved normal
@@ -1611,6 +1759,9 @@ export class TUI extends Container {
 		const prevHardwareCursorRow = this.#hardwareCursorRow;
 		const resizeEventOccurred = this.#resizeEventPending;
 		this.#resizeEventPending = false;
+		if (resizeEventOccurred) {
+			this.#forgetHardwareCursorState();
+		}
 		const widthChanged = this.#previousWidth > 0 && this.#previousWidth !== width;
 		// A resize event with net-unchanged dimensions still reflowed the terminal
 		// buffer; classify it as a height change so the geometry branches repaint
@@ -1620,7 +1771,9 @@ export class TUI extends Container {
 			(resizeEventOccurred && this.#previousHeight > 0);
 		const eagerEraseScrollbackRisk = this.#hasEagerEraseScrollbackRisk();
 		const eagerRebuildAllowed = this.#eagerNativeScrollbackRebuild && !eagerEraseScrollbackRisk;
-		const explicitViewportMutation = this.#allowUnknownViewportMutationOnNextRender;
+		const focusChanged = this.#focusChangedSinceLastRender;
+		this.#focusChangedSinceLastRender = false;
+		const explicitViewportMutation = this.#allowUnknownViewportMutationOnNextRender || focusChanged;
 		const allowUnknownViewportMutation = explicitViewportMutation || eagerRebuildAllowed;
 		this.#allowUnknownViewportMutationOnNextRender = false;
 
@@ -2049,7 +2202,9 @@ export class TUI extends Container {
 			newLines.length < this.#previousLines.length &&
 			naturalViewportTop !== prevViewportTop
 		) {
-			return { kind: "viewportRepaint" };
+			return this.#bottomAnchoredViewportUnchanged(newLines, height)
+				? { kind: "deferredMutation" }
+				: { kind: "viewportRepaint" };
 		}
 
 		// Direct-input shrink can also move the natural viewport upward even when
@@ -2437,6 +2592,17 @@ export class TUI extends Container {
 		return { kind: "liveRegionPinned", appendFrom, appendTo, renderViewportTop };
 	}
 
+	#bottomAnchoredViewportUnchanged(newLines: string[], height: number): boolean {
+		const previousViewportTop = Math.max(0, this.#previousLines.length - height);
+		const newViewportTop = Math.max(0, newLines.length - height);
+		for (let row = 0; row < height; row++) {
+			if ((newLines[newViewportTop + row] ?? "") !== (this.#previousLines[previousViewportTop + row] ?? "")) {
+				return false;
+			}
+		}
+		return true;
+	}
+
 	#planDeferredTailRepaint(newLines: string[], prevViewportTop: number, height: number): RenderIntent {
 		const row = prevViewportTop + height - 1;
 		if (row < 0 || row >= this.#previousLines.length || newLines.length !== this.#previousLines.length) {
@@ -2478,7 +2644,8 @@ export class TUI extends Container {
 		if (TERMINAL.isImageLine(raw)) {
 			return { raw, width, line: raw };
 		}
-		const normalized = normalizeTerminalOutput(raw);
+		const source = this.#lineFitSource(raw, width);
+		const normalized = normalizeTerminalOutput(source);
 		const asciiWidth = this.#ansiAsciiLineWidth(normalized, width);
 		if ((asciiWidth ?? visibleWidth(normalized)) <= width) {
 			return { raw, width, line: normalized };
@@ -2487,6 +2654,91 @@ export class TUI extends Container {
 		return { raw, width, line };
 	}
 
+	#lineFitSource(raw: string, width: number): string {
+		const safeWidth = Number.isFinite(width) ? Math.max(1, Math.trunc(width)) : 1;
+		const maxSourceLength = Math.min(
+			LINE_FIT_MAX_SOURCE_CODE_UNITS,
+			Math.max(LINE_FIT_MIN_SOURCE_CODE_UNITS, safeWidth * LINE_FIT_SOURCE_WIDTH_MULTIPLIER),
+		);
+		if (raw.length <= maxSourceLength) return raw;
+
+		let output = "";
+		let cells = 0;
+		for (let i = 0; i < raw.length && cells < safeWidth; ) {
+			if (raw.charCodeAt(i) === 0x1b) {
+				const end = this.#ansiSequenceEnd(raw, i);
+				if (end < 0) break;
+				if (this.#ansiSequenceHasVisiblePayload(raw, i)) {
+					const sequence = raw.slice(i, end);
+					if (output.length + sequence.length <= maxSourceLength) {
+						output += sequence;
+						cells += visibleWidth(sequence);
+					}
+				}
+				i = end;
+				continue;
+			}
+
+			const code = raw.charCodeAt(i);
+			const next = code >= 0xd800 && code <= 0xdbff && i + 1 < raw.length ? i + 2 : i + 1;
+			const char = raw.slice(i, next);
+			const charWidth = visibleWidth(char);
+			if (charWidth > 0 && cells + charWidth > safeWidth) break;
+			if (output.length + char.length > maxSourceLength) {
+				if (charWidth > 0) break;
+				i = next;
+				continue;
+			}
+			if (charWidth === 0) {
+				const remainingVisibleCells = safeWidth - cells;
+				const reservedCodeUnits = remainingVisibleCells * 2;
+				if (output.length + char.length > maxSourceLength - reservedCodeUnits) {
+					i = next;
+					continue;
+				}
+			}
+			output += char;
+			cells += charWidth;
+			i = next;
+		}
+
+		return output + SEGMENT_RESET;
+	}
+
+	#ansiSequenceEnd(line: string, start: number): number {
+		const next = line.charCodeAt(start + 1);
+		if (next === 0x5b) {
+			let i = start + 2;
+			while (i < line.length) {
+				const final = line.charCodeAt(i);
+				if (final >= 0x40 && final <= 0x7e) return i + 1;
+				i++;
+			}
+			return -1;
+		}
+		if (next === 0x5d) {
+			let i = start + 2;
+			while (i < line.length) {
+				const osc = line.charCodeAt(i);
+				if (osc === 0x07) return i + 1;
+				if (osc === 0x1b && line.charCodeAt(i + 1) === 0x5c) return i + 2;
+				i++;
+			}
+			return -1;
+		}
+		return start + 2 <= line.length ? start + 2 : -1;
+	}
+
+	#ansiSequenceHasVisiblePayload(line: string, start: number): boolean {
+		// OSC 66 (`\x1b]66;META;TEXT\x1b\\`) carries visible cells inside the payload.
+		return (
+			line.charCodeAt(start + 1) === 0x5d &&
+			line.charCodeAt(start + 2) === 0x36 &&
+			line.charCodeAt(start + 3) === 0x36 &&
+			line.charCodeAt(start + 4) === 0x3b
+		);
+	}
+
 	#ansiAsciiLineWidth(line: string, maxWidth: number): number | undefined {
 		let col = 0;
 		for (let i = 0; i < line.length; ) {
@@ -2553,7 +2805,13 @@ export class TUI extends Container {
 	 * the end so cursor/viewport/scrollback accounting stays consistent.
 	 */
 
-	#commit(lines: string[], width: number, height: number, viewportTop: number, hardwareCursorRow: number): void {
+	#commit(
+		lines: string[],
+		width: number,
+		height: number,
+		viewportTop: number,
+		hardwareCursor: HardwareCursorUpdate,
+	): void {
 		this.#deferredTailLine = undefined;
 		this.#previousLines = lines;
 		this.#previousVisibleOverlayComponents = this.#visibleOverlayComponentsThisRender;
@@ -2562,7 +2820,73 @@ export class TUI extends Container {
 		this.#previousHeight = height;
 		this.#cursorRow = Math.max(0, lines.length - 1);
 		this.#viewportTopRow = viewportTop;
-		this.#hardwareCursorRow = hardwareCursorRow;
+		this.#recordHardwareCursorUpdate(hardwareCursor);
+	}
+
+	#targetHardwareCursorState(
+		cursorPos: { row: number; col: number } | null,
+		totalLines: number,
+	): HardwareCursorState | null {
+		if (!cursorPos || totalLines <= 0) return null;
+		return {
+			row: Math.max(0, Math.min(cursorPos.row, totalLines - 1)),
+			col: Math.max(0, cursorPos.col),
+			visible: this.#showHardwareCursor,
+		};
+	}
+
+	#recordHardwareCursorState(state: HardwareCursorState): void {
+		this.#hardwareCursorRow = state.row;
+		this.#hardwareCursorState = state;
+		this.#hardwareCursorVisible = state.visible;
+		this.#hardwareCursorVisibilityKnown = true;
+	}
+
+	#recordHardwareCursorRowOnly(row: number, visible?: boolean): void {
+		this.#hardwareCursorRow = row;
+		this.#hardwareCursorState = null;
+		if (visible !== undefined) {
+			this.#hardwareCursorVisible = visible;
+			this.#hardwareCursorVisibilityKnown = true;
+		}
+	}
+
+	#recordHardwareCursorUpdate(update: HardwareCursorUpdate): void {
+		if (update.state) {
+			this.#recordHardwareCursorState(update.state);
+			return;
+		}
+		this.#recordHardwareCursorRowOnly(update.toRow, update.visible);
+	}
+
+	#recordHardwareCursorHidden(): void {
+		this.#hardwareCursorVisible = false;
+		this.#hardwareCursorVisibilityKnown = true;
+		if (!this.#hardwareCursorState) return;
+		this.#hardwareCursorState = { ...this.#hardwareCursorState, visible: false };
+	}
+
+	#forgetHardwareCursorState(): void {
+		this.#hardwareCursorState = null;
+		this.#hardwareCursorVisibilityKnown = false;
+	}
+
+	#sameHardwareCursorState(state: HardwareCursorState): boolean {
+		const current = this.#hardwareCursorState;
+		return (
+			current !== null && current.row === state.row && current.col === state.col && current.visible === state.visible
+		);
+	}
+
+	#preserveHardwareCursorUpdate(row: number): HardwareCursorUpdate {
+		if (this.#hardwareCursorState?.row === row) {
+			return { toRow: row, state: this.#hardwareCursorState, visible: this.#hardwareCursorState.visible };
+		}
+		return {
+			toRow: row,
+			state: null,
+			visible: this.#hardwareCursorVisibilityKnown ? this.#hardwareCursorVisible : undefined,
+		};
 	}
 
 	/**
@@ -2625,8 +2949,8 @@ export class TUI extends Container {
 		}
 		buffer += fillSequence;
 		const finalRow = Math.max(0, lines.length - 1);
-		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, finalRow);
-		buffer += seq;
+		const cursorControl = this.#cursorControlSequence(cursorPos, lines.length, finalRow);
+		buffer += cursorControl.seq;
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 
@@ -2639,7 +2963,7 @@ export class TUI extends Container {
 		if (pushedNow > this.#scrollbackHighWater) {
 			this.#scrollbackHighWater = pushedNow;
 		}
-		this.#commit(lines, width, height, Math.max(0, this.#maxLinesRendered - height), toRow);
+		this.#commit(lines, width, height, Math.max(0, this.#maxLinesRendered - height), cursorControl);
 	}
 
 	/**
@@ -2683,14 +3007,14 @@ export class TUI extends Container {
 		const contentBottomRow = Math.min(viewportBottomRow, Math.max(viewportTop, lines.length - 1));
 		const parkUp = viewportBottomRow - contentBottomRow;
 		if (parkUp > 0) buffer += `\x1b[${parkUp}A`;
-		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, contentBottomRow);
-		buffer += seq;
+		const cursorControl = this.#cursorControlSequence(cursorPos, lines.length, contentBottomRow);
+		buffer += cursorControl.seq;
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 
 		this.#maxLinesRendered = Math.max(lines.length, viewportTop + height);
 		this.#scrollbackHighWater = appendTo;
-		this.#commit(lines, width, height, viewportTop, toRow);
+		this.#commit(lines, width, height, viewportTop, cursorControl);
 	}
 	/**
 	 * Rewrite the visible viewport in place. Cursor home, clear each row,
@@ -2756,13 +3080,13 @@ export class TUI extends Container {
 		const contentBottomRow = Math.min(viewportBottomRow, Math.max(viewportTop, lines.length - 1));
 		const parkUp = viewportBottomRow - contentBottomRow;
 		if (parkUp > 0) buffer += `\x1b[${parkUp}A`;
-		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, contentBottomRow);
-		buffer += seq;
+		const cursorControl = this.#cursorControlSequence(cursorPos, lines.length, contentBottomRow);
+		buffer += cursorControl.seq;
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 
 		this.#maxLinesRendered = lines.length;
-		this.#commit(lines, width, height, viewportTop, toRow);
+		this.#commit(lines, width, height, viewportTop, cursorControl);
 	}
 
 	/** Topmost visible overlay requests the alternate-screen buffer. */
@@ -2875,13 +3199,13 @@ export class TUI extends Container {
 				}
 				cursorFromRow = viewportTop + lastChangedScreenRow;
 			}
-			const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, cursorFromRow);
-			buffer += seq;
+			const cursorControl = this.#cursorControlSequence(cursorPos, lines.length, cursorFromRow);
+			buffer += cursorControl.seq;
 			buffer += this.#paintEndSequence;
 			this.terminal.write(buffer);
 
 			this.#maxLinesRendered = Math.max(lines.length, viewportTop + height);
-			this.#commit(lines, width, height, viewportTop, toRow);
+			this.#commit(lines, width, height, viewportTop, cursorControl);
 			return;
 		}
 
@@ -2915,8 +3239,8 @@ export class TUI extends Container {
 		const contentBottomRow = Math.min(viewportBottomRow, Math.max(viewportTop, lines.length - 1));
 		const parkUp = viewportBottomRow - contentBottomRow;
 		if (parkUp > 0) buffer += `\x1b[${parkUp}A`;
-		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, contentBottomRow);
-		buffer += seq;
+		const cursorControl = this.#cursorControlSequence(cursorPos, lines.length, contentBottomRow);
+		buffer += cursorControl.seq;
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 
@@ -2924,7 +3248,7 @@ export class TUI extends Container {
 		if (boundedAppendTo > this.#scrollbackHighWater) {
 			this.#scrollbackHighWater = boundedAppendTo;
 		}
-		this.#commit(lines, width, height, viewportTop, toRow);
+		this.#commit(lines, width, height, viewportTop, cursorControl);
 	}
 
 	/**
@@ -2993,7 +3317,7 @@ export class TUI extends Container {
 		this.#previousWidth = width;
 		this.#previousHeight = height;
 		this.#viewportTopRow = prevViewportTop;
-		this.#hardwareCursorRow = row;
+		this.#recordHardwareCursorRowOnly(row, false);
 	}
 
 	/**
@@ -3012,7 +3336,13 @@ export class TUI extends Container {
 	): void {
 		const extraLines = this.#previousLines.length - lines.length;
 		if (extraLines <= 0) {
-			this.#commit(lines, width, height, Math.max(0, lines.length - height), prevHardwareCursorRow);
+			this.#commit(
+				lines,
+				width,
+				height,
+				Math.max(0, lines.length - height),
+				this.#preserveHardwareCursorUpdate(prevHardwareCursorRow),
+			);
 			this.#maxLinesRendered = lines.length;
 			return;
 		}
@@ -3047,13 +3377,13 @@ export class TUI extends Container {
 			buffer += `\x1b[${moveUp}A`;
 		}
 
-		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, targetRow);
-		buffer += seq;
+		const cursorControl = this.#cursorControlSequence(cursorPos, lines.length, targetRow);
+		buffer += cursorControl.seq;
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 
 		this.#maxLinesRendered = lines.length;
-		this.#commit(lines, width, height, Math.max(0, lines.length - height), toRow);
+		this.#commit(lines, width, height, Math.max(0, lines.length - height), cursorControl);
 	}
 
 	/**
@@ -3165,8 +3495,8 @@ export class TUI extends Container {
 		// so emitting them after the trailing-shrink cursor moves is safe.
 		buffer += fillSequence;
 
-		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, finalCursorRow);
-		buffer += seq;
+		const cursorControl = this.#cursorControlSequence(cursorPos, lines.length, finalCursorRow);
+		buffer += cursorControl.seq;
 		buffer += this.#paintEndSequence;
 
 		this.#writeDiffDebug(
@@ -3179,7 +3509,7 @@ export class TUI extends Container {
 			renderEnd,
 			finalCursorRow,
 			cursorPos,
-			toRow,
+			cursorControl.toRow,
 			buffer,
 		);
 		this.terminal.write(buffer);
@@ -3191,7 +3521,7 @@ export class TUI extends Container {
 				this.#scrollbackHighWater = pushedNow;
 			}
 		}
-		this.#commit(lines, width, height, Math.max(0, lines.length - height), toRow);
+		this.#commit(lines, width, height, Math.max(0, lines.length - height), cursorControl);
 	}
 
 	/** Optional intent log under PI_DEBUG_REDRAW. */
@@ -3270,16 +3600,15 @@ export class TUI extends Container {
 		cursorPos: { row: number; col: number } | null,
 		totalLines: number,
 		fromRow: number,
-	): { seq: string; toRow: number } {
-		// No IME target or no content — hide cursor regardless of preference
-		if (!cursorPos || totalLines <= 0) return { seq: "\x1b[?25l", toRow: fromRow };
-
-		// Clamp cursor position to valid range
-		const targetRow = Math.max(0, Math.min(cursorPos.row, totalLines - 1));
-		const targetCol = Math.max(0, cursorPos.col);
+	): CursorControlResult {
+		// No IME target or no content — hide cursor regardless of preference.
+		const target = this.#targetHardwareCursorState(cursorPos, totalLines);
+		if (!target) {
+			return { seq: "\x1b[?25l", toRow: fromRow, toCol: 0, visible: false, state: null };
+		}
 
-		// Move cursor from current position to target
-		const rowDelta = targetRow - fromRow;
+		// Move cursor from current position to target.
+		const rowDelta = target.row - fromRow;
 		let seq = "";
 		if (rowDelta > 0) {
 			seq += `\x1b[${rowDelta}B`; // Move down
@@ -3287,10 +3616,14 @@ export class TUI extends Container {
 			seq += `\x1b[${-rowDelta}A`; // Move up
 		}
 		// Move to absolute column (1-indexed)
-		seq += `\x1b[${targetCol + 1}G`;
-		seq += this.#showHardwareCursor ? "\x1b[?25h" : "\x1b[?25l";
+		seq += `\x1b[${target.col + 1}G`;
+		seq += target.visible ? "\x1b[?25h" : "\x1b[?25l";
+
+		return { seq, toRow: target.row, toCol: target.col, visible: target.visible, state: target };
+	}
 
-		return { seq, toRow: targetRow };
+	#isHiddenCursorKnown(): boolean {
+		return this.#hardwareCursorVisibilityKnown && !this.#hardwareCursorVisible;
 	}
 
 	/**
@@ -3299,12 +3632,16 @@ export class TUI extends Container {
 	 * to embed the sequences into.
 	 */
 	#writeCursorPosition(cursorPos: { row: number; col: number } | null, totalLines: number): void {
-		if (!cursorPos || totalLines <= 0) {
+		const target = this.#targetHardwareCursorState(cursorPos, totalLines);
+		if (!target) {
+			if (this.#isHiddenCursorKnown()) return;
 			this.terminal.hideCursor();
+			this.#recordHardwareCursorHidden();
 			return;
 		}
-		const { seq, toRow } = this.#cursorControlSequence(cursorPos, totalLines, this.#hardwareCursorRow);
-		this.#hardwareCursorRow = toRow;
-		this.terminal.write(`${this.#cursorBeginSequence}${seq}${this.#cursorEndSequence}`);
+		if (this.#sameHardwareCursorState(target)) return;
+		const cursorControl = this.#cursorControlSequence(cursorPos, totalLines, this.#hardwareCursorRow);
+		this.terminal.write(`${this.#cursorBeginSequence}${cursorControl.seq}${this.#cursorEndSequence}`);
+		this.#recordHardwareCursorUpdate(cursorControl);
 	}
 }