@gajae-code/tui 0.8.2 → 0.9.1

package/src/tui.ts

@@ -4,7 +4,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
-import { $flag, getDebugLogPath, logger } from "@gajae-code/utils";
+import { $flag, getDebugLogPath, logger, onDefaultTabWidthChange } from "@gajae-code/utils";
 import { getKeybindings } from "./keybindings";
 import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
@@ -17,8 +17,10 @@ import {
 	normalizeTerminalOutput,
 	sliceByColumn,
 	sliceWithWidth,
+	truncateLinesToWidth,
 	truncateToWidth,
 	visibleWidth,
+	visibleWidths,
 } from "./utils";
 
 const SEGMENT_RESET = "\x1b[0m";
@@ -135,37 +137,83 @@ function parseSizeValue(value: SizeValue | undefined, referenceSize: number): nu
 	return undefined;
 }
 
-function isTermuxSession(): boolean {
-	return Boolean(process.env.TERMUX_VERSION);
+function isTermuxSession(env: Record<string, string | undefined> = Bun.env): boolean {
+	return Boolean(env.TERMUX_VERSION);
 }
 
 const GJC_TMUX_LAUNCHED_ENV = "GJC_TMUX_LAUNCHED";
 const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "no"]);
+const TRUTHY_ENV_VALUES = new Set(["1", "true", "yes", "on", "y"]);
 
 function envIsEnabled(value: string | undefined): boolean {
 	const normalized = value?.trim().toLowerCase();
 	return normalized !== undefined && normalized.length > 0 && !DISABLED_ENV_VALUES.has(normalized);
 }
 
+function envFlagEnabled(value: string | undefined): boolean {
+	const normalized = value?.trim().toLowerCase();
+	return normalized !== undefined && TRUTHY_ENV_VALUES.has(normalized);
+}
+
 function termLooksMultiplexed(value: string | undefined): boolean {
 	const term = value?.trim().toLowerCase() ?? "";
 	return term.startsWith("tmux") || term.startsWith("screen");
 }
 
+function isWindowsTerminalSession(env: Record<string, string | undefined> = Bun.env): boolean {
+	return envIsEnabled(env.WT_SESSION) || env.TERM_PROGRAM === "Windows_Terminal";
+}
+
 /** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
-function isMultiplexerSession(): boolean {
+function isMultiplexerSession(env: Record<string, string | undefined> = Bun.env): boolean {
 	return Boolean(
-		envIsEnabled(Bun.env.TMUX) ||
-			envIsEnabled(Bun.env.TMUX_PANE) ||
-			envIsEnabled(Bun.env.STY) ||
-			envIsEnabled(Bun.env.ZELLIJ) ||
-			envIsEnabled(Bun.env[GJC_TMUX_LAUNCHED_ENV]) ||
-			termLooksMultiplexed(Bun.env.TERM),
+		envIsEnabled(env.TMUX) ||
+			envIsEnabled(env.TMUX_PANE) ||
+			envIsEnabled(env.STY) ||
+			envIsEnabled(env.ZELLIJ) ||
+			envIsEnabled(env[GJC_TMUX_LAUNCHED_ENV]) ||
+			termLooksMultiplexed(env.TERM),
 	);
 }
 
-function useLegacyMultiplexerFullRender(): boolean {
-	return $flag("PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER");
+function useLegacyMultiplexerFullRender(env: Record<string, string | undefined> = Bun.env): boolean {
+	return envFlagEnabled(env.PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER);
+}
+
+function isViewportSensitiveHost(
+	env: Record<string, string | undefined>,
+	platform: NodeJS.Platform,
+	includeNativeWindows: boolean,
+): boolean {
+	return isMultiplexerSession(env) || isWindowsTerminalSession(env) || (includeNativeWindows && platform === "win32");
+}
+/**
+ * True when repainting only the live viewport is safer than clearing/replaying
+ * the full transcript. Native Windows console hosts are included even when
+ * WT_SESSION is absent because PowerShell/ConPTY launch chains can drop terminal
+ * identity variables while keeping the same scroll-jump behavior.
+ */
+export function shouldUseViewportRepaintForHost(
+	env: Record<string, string | undefined> = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+	options: { includeNativeWindows?: boolean } = {},
+): boolean {
+	const multiplexed = isMultiplexerSession(env);
+	const includeNativeWindows = options.includeNativeWindows ?? true;
+	return (
+		isViewportSensitiveHost(env, platform, includeNativeWindows) &&
+		!(multiplexed && useLegacyMultiplexerFullRender(env))
+	);
+}
+
+function useViewportRepaintPath(terminal: Terminal): boolean {
+	return shouldUseViewportRepaintForHost(Bun.env, process.platform, {
+		includeNativeWindows: terminal.isProcessTerminal === true,
+	});
+}
+
+function shouldPreserveScrollbackOnFullClear(terminal: Terminal): boolean {
+	return isViewportSensitiveHost(Bun.env, process.platform, terminal.isProcessTerminal === true);
 }
 
 /**
@@ -323,6 +371,13 @@ function safeRenderComponent(component: Component, width: number, where: string)
 type LineNormalizationCacheEntry = {
 	normalized: string;
 	terminated: string;
+	width: number | undefined;
+};
+
+type TuiRenderCounterSnapshot = {
+	debugRedrawEnvReads: number;
+	debugRedrawAppendWrites: number;
+	differentialGuardVisibleWidthCalls: number;
 };
 
 /**
@@ -339,6 +394,7 @@ export class TUI extends Container {
 	 */
 	#previousRaw: string[] = [];
 	#lineNormalizationCache = new Map<string, LineNormalizationCacheEntry>();
+	#lineEmitWidthCache = new Map<string, number>();
 	#lineTruncationCache = new Map<string, string>();
 	#lineNormalizationCacheLimit = 0;
 	#lineTruncationCacheLimit = 0;
@@ -369,20 +425,58 @@ export class TUI extends Container {
 	#sixelProbeTimeout?: NodeJS.Timeout;
 	#sixelProbeUnsubscribe?: () => void;
 	#showHardwareCursor = $flag("PI_HARDWARE_CURSOR");
+	#debugRedraw = TUI.#readDebugRedrawFlag();
 	// macOS: steady-block cursor anchors CJK IME overlays; disable with GJC_TUI_IME_CURSOR=0.
 	readonly #useImeBlockCursor = $flag("GJC_TUI_IME_CURSOR", process.platform === "darwin");
 	// showHardwareCursor=false but cursor is shown for IME anchoring (macOS).
 	#imeCursorActive = false;
 	#clearOnShrink = $flag("PI_CLEAR_ON_SHRINK"); // Clear empty rows when content shrinks (default: off)
-	// Opt-in: reuse the previous normalized off-screen prefix and only normalize/diff the
-	// visible window, bounding per-frame work on huge transcripts. Output stays byte-identical.
-	#virtualViewport = $flag("PI_TUI_VIRTUAL_VIEWPORT");
+	// Default-on: reuse the previous normalized off-screen prefix and only normalize/diff the
+	// visible window, bounding per-frame work on huge transcripts. Output stays byte-identical;
+	// set PI_TUI_VIRTUAL_VIEWPORT=0 to restore legacy full-transcript normalization.
+	#virtualViewport = $flag("PI_TUI_VIRTUAL_VIEWPORT", true);
 	#maxLinesRendered = 0; // Line count from last render, used for viewport calculation
 	#fullRedrawCount = 0;
 	#stopped = false;
 	#terminalUnavailable = false;
 	#bottomPinnedComponent: Component | null = null;
 
+	#unsubscribeTabWidthChange?: () => void;
+	static #renderCounters: TuiRenderCounterSnapshot = {
+		debugRedrawEnvReads: 0,
+		debugRedrawAppendWrites: 0,
+		differentialGuardVisibleWidthCalls: 0,
+	};
+
+	static resetRenderCountersForTest(): void {
+		TUI.#renderCounters = {
+			debugRedrawEnvReads: 0,
+			debugRedrawAppendWrites: 0,
+			differentialGuardVisibleWidthCalls: 0,
+		};
+	}
+
+	static getRenderCountersForTest(): TuiRenderCounterSnapshot {
+		return { ...TUI.#renderCounters };
+	}
+
+	static #readDebugRedrawFlag(): boolean {
+		TUI.#renderCounters.debugRedrawEnvReads += 1;
+		return $flag("PI_DEBUG_REDRAW");
+	}
+
+	#appendDebugRedrawLog(message: string): void {
+		TUI.#renderCounters.debugRedrawAppendWrites += 1;
+		fs.appendFileSync(getDebugLogPath(), message);
+	}
+
+	#visibleWidthForDifferentialGuard(line: string): number {
+		const cached = this.#lineEmitWidthCache.get(line);
+		if (cached !== undefined) return cached;
+		TUI.#renderCounters.differentialGuardVisibleWidthCalls += 1;
+		return visibleWidth(line);
+	}
+
 	// Overlay stack for modal components rendered on top of base content
 	overlayStack: {
 		component: Component;
@@ -398,6 +492,18 @@ export class TUI extends Container {
 			this.#showHardwareCursor = showHardwareCursor;
 		}
 		this.#imeCursorActive = !this.#showHardwareCursor && this.#useImeBlockCursor;
+		this.#unsubscribeTabWidthChange = onDefaultTabWidthChange(() => {
+			this.#lineTruncationCache.clear();
+			this.#lineNormalizationCache.clear();
+			this.#lineEmitWidthCache.clear();
+			this.requestRender(true, "tab-width-change");
+		});
+	}
+
+	override dispose(): void {
+		this.#unsubscribeTabWidthChange?.();
+		this.#unsubscribeTabWidthChange = undefined;
+		super.dispose();
 	}
 
 	get fullRedraws(): number {
@@ -458,19 +564,13 @@ export class TUI extends Container {
 		const pageStep = Math.max(1, height - 1);
 		const targetViewportTop = Math.max(0, Math.min(maxViewportTop, currentViewportTop + direction * pageStep));
 
-		if (targetViewportTop >= maxViewportTop) {
-			this.#manualViewportTop = undefined;
-		} else {
-			this.#manualViewportTop = targetViewportTop;
-		}
-
-		const cursorPos = this.#manualViewportTop === undefined ? this.#lastCursorPosition : null;
+		this.#manualViewportTop = targetViewportTop;
 		return this.#repaintViewportFromLines(
 			this.#previousLines,
 			width,
 			height,
 			targetViewportTop,
-			cursorPos,
+			null,
 			"manual viewport scroll",
 		);
 	}
@@ -829,24 +929,26 @@ export class TUI extends Container {
 		this.#previousRaw = [];
 		this.#lineNormalizationCache.clear();
 		this.#lineTruncationCache.clear();
+		this.#lineEmitWidthCache.clear();
 		this.#previousWidth = 0;
 		this.#previousHeight = 0;
 	}
 
 	/**
-	 * Multiplexer-aware resize render request.
+	 * Viewport-repaint-aware resize render request.
 	 *
 	 * A forced full redraw (`requestRender(true)`) resets `#previousWidth`/`#previousHeight`
 	 * to -1, which makes `#doRender` treat the frame as a width change and fall into the
 	 * `fullRender` path. In terminal multiplexers that path skips the scrollback-clearing
 	 * `3J` escape (users navigate scrollback history), so replaying every transcript line
 	 * piles it back on top of scrollback — the "top of screen scrolls down to the prompt at
-	 * high speed" resize storm. Here we keep force off in multiplexers so `#doRender`'s
-	 * height-change branch takes the viewport-only `multiplexerViewportRepaint` path instead.
-	 * Set `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy forced redraw.
+	 * high speed" resize storm. Windows Terminal/ConPTY can also visibly jump to
+	 * the transcript top during streaming redraws, so viewport-repaint sessions
+	 * keep force off and let `#doRender` repaint only the live viewport. Set
+	 * `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy tmux redraw.
 	 */
 	requestResizeRender(): void {
-		this.requestRender(!(isMultiplexerSession() && !useLegacyMultiplexerFullRender()), "resize");
+		this.requestRender(!useViewportRepaintPath(this.terminal) && !isTermuxSession(), "resize");
 	}
 
 	requestRender(force = false, source = "unknown"): void {
@@ -856,20 +958,24 @@ export class TUI extends Container {
 		}
 		if (renderMetrics.enabled) renderMetrics.recordRequest(source);
 		if (force) {
+			const preserveViewportCursor = useViewportRepaintPath(this.terminal);
 			// A forced full redraw supersedes any queued input-priority render.
 			this.#inputRenderPending = false;
 			this.#previousLines = [];
 			this.#previousRaw = [];
 			this.#lineNormalizationCache.clear();
 			this.#lineTruncationCache.clear();
+			this.#lineEmitWidthCache.clear();
 			this.#previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
 			this.#previousHeight = -1; // -1 triggers heightChanged, forcing a full clear
 			this.#lineNormalizationCacheLimit = 0;
 			this.#lineTruncationCacheLimit = 0;
-			this.#cursorRow = 0;
-			this.#hardwareCursorRow = 0;
-			this.#viewportTopRow = 0;
-			this.#maxLinesRendered = 0;
+			if (!preserveViewportCursor) {
+				this.#cursorRow = 0;
+				this.#hardwareCursorRow = 0;
+				this.#viewportTopRow = 0;
+				this.#maxLinesRendered = 0;
+			}
 			if (this.#renderTimer) {
 				clearTimeout(this.#renderTimer);
 				this.#renderTimer = undefined;
@@ -1335,24 +1441,9 @@ export class TUI extends Container {
 		if (cached !== undefined) return cached;
 		const normalized = normalizeTerminalOutput(line);
 		const terminated = normalized + (normalized.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
-		this.#lineNormalizationCache.set(line, { normalized, terminated });
-		return { normalized, terminated };
-	}
-
-	#lineFitsWidth(normalizedLine: string, width: number): boolean {
-		return isPrintableAscii(normalizedLine) && normalizedLine.length <= width
-			? true
-			: visibleWidth(normalizedLine) <= width;
-	}
-
-	#truncateNormalizedLine(normalizedLine: string, width: number): string {
-		const key = `${width}\0${normalizedLine}`;
-		const cached = this.#lineTruncationCache.get(key);
-		if (cached !== undefined) return cached;
-		const truncated = truncateToWidth(normalizedLine, width, Ellipsis.Omit);
-		const terminated = truncated + (truncated.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
-		this.#lineTruncationCache.set(key, terminated);
-		return terminated;
+		const entry = { normalized, terminated, width: undefined };
+		this.#lineNormalizationCache.set(line, entry);
+		return entry;
 	}
 
 	#trimLineCachesForRender(lineCount: number): void {
@@ -1362,6 +1453,8 @@ export class TUI extends Container {
 		while (this.#lineNormalizationCache.size > limit) {
 			const key = this.#lineNormalizationCache.keys().next().value;
 			if (key === undefined) break;
+			const entry = this.#lineNormalizationCache.get(key);
+			if (entry !== undefined) this.#lineEmitWidthCache.delete(entry.terminated);
 			this.#lineNormalizationCache.delete(key);
 		}
 		while (this.#lineTruncationCache.size > limit) {
@@ -1369,6 +1462,11 @@ export class TUI extends Container {
 			if (key === undefined) break;
 			this.#lineTruncationCache.delete(key);
 		}
+		while (this.#lineEmitWidthCache.size > limit * 2) {
+			const key = this.#lineEmitWidthCache.keys().next().value;
+			if (key === undefined) break;
+			this.#lineEmitWidthCache.delete(key);
+		}
 	}
 
 	getLineRenderCacheStats(): {
@@ -1385,17 +1483,66 @@ export class TUI extends Container {
 		};
 	}
 
-	/** Normalize + width-fit a single line for emission (image lines pass through). */
-	#normalizeLineForEmit(line: string, width: number): string {
-		if (TERMINAL.isImageLine(line)) return line;
-		const { normalized, terminated } = this.#normalizeLineForRender(line);
-		return this.#lineFitsWidth(normalized, width) ? terminated : this.#truncateNormalizedLine(normalized, width);
+	#normalizeLinesForEmit(lines: string[], width: number, start = 0): string[] {
+		const widthCheckIndexes: number[] = [];
+		const widthCheckLines: string[] = [];
+		for (let i = start; i < lines.length; i++) {
+			const line = lines[i];
+			if (TERMINAL.isImageLine(line)) continue;
+			const entry = this.#normalizeLineForRender(line);
+			const { normalized, terminated } = entry;
+			if (isPrintableAscii(normalized) && normalized.length <= width) {
+				entry.width = normalized.length;
+				this.#lineEmitWidthCache.set(terminated, normalized.length);
+				lines[i] = terminated;
+				continue;
+			}
+			widthCheckIndexes.push(i);
+			widthCheckLines.push(normalized);
+		}
+
+		const widths = widthCheckLines.length === 0 ? [] : visibleWidths(widthCheckLines);
+		const truncateIndexes: number[] = [];
+		const truncateLines: string[] = [];
+		for (let i = 0; i < widthCheckIndexes.length; i++) {
+			const lineIndex = widthCheckIndexes[i];
+			const normalized = widthCheckLines[i];
+			const measuredWidth = widths[i] ?? 0;
+			if (measuredWidth <= width) {
+				const entry = this.#normalizeLineForRender(lines[lineIndex]);
+				entry.width = measuredWidth;
+				this.#lineEmitWidthCache.set(entry.terminated, measuredWidth);
+				lines[lineIndex] = entry.terminated;
+				continue;
+			}
+
+			const key = `${width}\0${normalized}`;
+			const cached = this.#lineTruncationCache.get(key);
+			if (cached !== undefined) {
+				this.#lineEmitWidthCache.set(cached, width);
+				lines[lineIndex] = cached;
+				continue;
+			}
+			truncateIndexes.push(lineIndex);
+			truncateLines.push(normalized);
+		}
+
+		const truncated = truncateLines.length === 0 ? [] : truncateLinesToWidth(truncateLines, width, Ellipsis.Omit);
+		for (let i = 0; i < truncateIndexes.length; i++) {
+			const lineIndex = truncateIndexes[i];
+			const normalized = truncateLines[i];
+			const truncatedLine = truncated[i] ?? "";
+			const terminated = truncatedLine + (truncatedLine.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
+			this.#lineTruncationCache.set(`${width}\0${normalized}`, terminated);
+			this.#lineEmitWidthCache.set(terminated, width);
+			lines[lineIndex] = terminated;
+		}
+
+		return lines;
 	}
 
 	#applyLineResetsAndTruncate(lines: string[], width: number): string[] {
-		for (let i = 0; i < lines.length; i++) {
-			lines[i] = this.#normalizeLineForEmit(lines[i], width);
-		}
+		this.#normalizeLinesForEmit(lines, width);
 		this.#trimLineCachesForRender(lines.length);
 		return lines;
 	}
@@ -1449,7 +1596,7 @@ export class TUI extends Container {
 			if (lineIndex >= lines.length) continue;
 			const line = lines[lineIndex];
 			const isImage = TERMINAL.isImageLine(line);
-			if (!isImage && visibleWidth(line) > width) {
+			if (!isImage && this.#visibleWidthForDifferentialGuard(line) > width) {
 				let truncatedLine = truncateToWidth(line, width, Ellipsis.Omit);
 				truncatedLine += truncatedLine.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET;
 				buffer += truncatedLine;
@@ -1471,10 +1618,9 @@ export class TUI extends Container {
 		buffer += "\x1b[?2026l";
 		if (!this.#writeTerminal(buffer)) return false;
 
-		if ($flag("PI_DEBUG_REDRAW")) {
-			const logPath = getDebugLogPath();
+		if (this.#debugRedraw) {
 			const msg = `[${new Date().toISOString()}] viewportRepaint: ${reason} (lines=${lines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
-			fs.appendFileSync(logPath, msg);
+			this.#appendDebugRedrawLog(msg);
 		}
 
 		this.#cursorRow = Math.max(0, lines.length - 1);
@@ -1551,8 +1697,9 @@ export class TUI extends Container {
 				if (stable) {
 					const windowed = this.#previousLines.slice(0, winTop);
 					for (let i = winTop; i < total; i++) {
-						windowed.push(this.#normalizeLineForEmit(rawLines[i], width));
+						windowed.push(rawLines[i]);
 					}
+					this.#normalizeLinesForEmit(windowed, width, winTop);
 					this.#trimLineCachesForRender(total);
 					newLines = windowed;
 					diffStart = winTop;
@@ -1576,9 +1723,8 @@ export class TUI extends Container {
 		if (this.#manualViewportTop !== undefined) {
 			const maxViewportTop = Math.max(0, newLines.length - height);
 			const nextViewportTop = Math.max(0, Math.min(maxViewportTop, this.#manualViewportTop));
-			const followingLive = nextViewportTop >= maxViewportTop;
-			this.#manualViewportTop = followingLive ? undefined : nextViewportTop;
-			const repaintCursorPos = followingLive ? cursorPos : null;
+			this.#manualViewportTop = nextViewportTop;
+			const repaintCursorPos = null;
 			if (
 				this.#repaintViewportFromLines(
 					newLines,
@@ -1600,8 +1746,10 @@ export class TUI extends Container {
 			this.#fullRedrawCount += 1;
 			if (renderMetrics.enabled) renderMetrics.recordFullRedraw(reason);
 			let buffer = "\x1b[?2026h"; // Begin synchronized output
-			// Skip clearing scrollback (3J) in multiplexers — users actively navigate scrollback history
-			if (clear) buffer += isMultiplexerSession() ? "\x1b[2J\x1b[H" : "\x1b[2J\x1b[H\x1b[3J";
+			// Skip clearing scrollback (3J) in hosts where clear/replay can snap the
+			// native viewport away from the live prompt (tmux/screen, Windows ConPTY).
+			if (clear)
+				buffer += shouldPreserveScrollbackOnFullClear(this.terminal) ? "\x1b[2J\x1b[H" : "\x1b[2J\x1b[H\x1b[3J";
 			for (let i = 0; i < newLines.length; i++) {
 				if (i > 0) buffer += "\r\n";
 				// Lines were pre-terminated/normalized by #applyLineResets; image
@@ -1626,7 +1774,7 @@ export class TUI extends Container {
 			this.#previousHeight = height;
 		};
 
-		const multiplexerViewportRepaint = (reason: string): void => {
+		const viewportRepaint = (reason: string): void => {
 			this.#fullRedrawCount += 1;
 			if (renderMetrics.enabled) renderMetrics.recordFullRedraw(reason);
 			const nextViewportTop = Math.max(0, newLines.length - height);
@@ -1643,7 +1791,7 @@ export class TUI extends Container {
 				if (lineIndex >= newLines.length) continue;
 				const line = newLines[lineIndex];
 				const isImage = TERMINAL.isImageLine(line);
-				if (!isImage && visibleWidth(line) > width) {
+				if (!isImage && this.#visibleWidthForDifferentialGuard(line) > width) {
 					let truncatedLine = truncateToWidth(line, width, Ellipsis.Omit);
 					truncatedLine += truncatedLine.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET;
 					buffer += truncatedLine;
@@ -1665,15 +1813,14 @@ export class TUI extends Container {
 			buffer += "\x1b[?2026l";
 			if (!this.#writeTerminal(buffer)) return;
 
-			if ($flag("PI_DEBUG_REDRAW")) {
-				const logPath = getDebugLogPath();
-				const msg = `[${new Date().toISOString()}] multiplexerViewportRepaint: ${reason} (prev=${this.#previousLines.length}, new=${newLines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
-				fs.appendFileSync(logPath, msg);
+			if (this.#debugRedraw) {
+				const msg = `[${new Date().toISOString()}] viewportRepaint: ${reason} (prev=${this.#previousLines.length}, new=${newLines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
+				this.#appendDebugRedrawLog(msg);
 			}
-			// In multiplexers this deliberately prioritizes the live viewport over
+			// Viewport repaint deliberately prioritizes the live viewport over
 			// historical scrollback repair. After offscreen changes, #previousLines
 			// tracks the desired logical transcript, not every byte emitted into the
-			// multiplexer scrollback.
+			// terminal scrollback.
 			this.#cursorRow = Math.max(0, newLines.length - 1);
 			this.#maxLinesRendered = newLines.length;
 			this.#viewportTopRow = nextViewportTop;
@@ -1682,12 +1829,11 @@ export class TUI extends Container {
 			this.#previousHeight = height;
 		};
 
-		const debugRedraw = $flag("PI_DEBUG_REDRAW");
+		const debugRedraw = this.#debugRedraw;
 		const logRedraw = (reason: string): void => {
 			if (!debugRedraw) return;
-			const logPath = getDebugLogPath();
 			const msg = `[${new Date().toISOString()}] fullRender: ${reason} (prev=${this.#previousLines.length}, new=${newLines.length}, height=${height})\n`;
-			fs.appendFileSync(logPath, msg);
+			this.#appendDebugRedrawLog(msg);
 		};
 
 		// First render - just output everything without clearing (assumes clean screen)
@@ -1700,13 +1846,12 @@ export class TUI extends Container {
 		// Width changes always need a full re-render because wrapping changes.
 		if (widthChanged) {
 			logRedraw(`terminal width changed (${this.#previousWidth} -> ${width})`);
-			if (isMultiplexerSession() && !useLegacyMultiplexerFullRender()) {
-				// In multiplexers a full replay piles the whole transcript back onto
-				// scrollback (3J is intentionally skipped). Repaint the viewport only,
-				// mirroring the height-change branch. This also neutralizes the fake
-				// width change that requestRender(true) injects via #previousWidth = -1,
-				// so every force-render call site is safe in multiplexers too.
-				multiplexerViewportRepaint(`terminal width changed (${this.#previousWidth} -> ${width})`);
+			if (useViewportRepaintPath(this.terminal)) {
+				// In viewport-repaint sessions a full replay can either pile the transcript
+				// back onto scrollback (tmux/screen) or visibly jump to the transcript top
+				// (Windows Terminal). Repaint the viewport only, mirroring the height-change
+				// branch and neutralizing fake width changes from requestRender(true).
+				viewportRepaint(`terminal width changed (${this.#previousWidth} -> ${width})`);
 			} else {
 				fullRender(true, "terminal width changed");
 			}
@@ -1717,8 +1862,8 @@ export class TUI extends Container {
 		// but Termux changes height when the software keyboard shows or hides.
 		// In that environment, a full redraw causes the entire history to replay on every toggle.
 		if (heightChanged) {
-			if (isMultiplexerSession() && !useLegacyMultiplexerFullRender()) {
-				multiplexerViewportRepaint(`terminal height changed (${this.#previousHeight} -> ${height})`);
+			if (useViewportRepaintPath(this.terminal)) {
+				viewportRepaint(`terminal height changed (${this.#previousHeight} -> ${height})`);
 				return;
 			}
 			if (!isTermuxSession() && !isMultiplexerSession()) {
@@ -1733,7 +1878,11 @@ export class TUI extends Container {
 		// Configurable via setClearOnShrink() or PI_CLEAR_ON_SHRINK=0 env var
 		if (this.#clearOnShrink && newLines.length < this.#previousLines.length && this.overlayStack.length === 0) {
 			logRedraw(`clearOnShrink (prev=${this.#previousLines.length}, new=${newLines.length})`);
-			fullRender(true, "clearOnShrink");
+			if (useViewportRepaintPath(this.terminal)) {
+				viewportRepaint(`clearOnShrink (prev=${this.#previousLines.length}, new=${newLines.length})`);
+			} else {
+				fullRender(true, "clearOnShrink");
+			}
 			return;
 		}
 
@@ -1771,6 +1920,11 @@ export class TUI extends Container {
 			return;
 		}
 
+		const nextLiveViewportTop = Math.max(0, newLines.length - height);
+		if (firstChanged >= newLines.length && nextLiveViewportTop !== prevViewportTop) {
+			viewportRepaint(`tail shrink changed viewport top (${prevViewportTop} -> ${nextLiveViewportTop})`);
+			return;
+		}
 		// All changes are in deleted lines (nothing to render, just clear)
 		if (firstChanged >= newLines.length) {
 			if (this.#previousLines.length > newLines.length) {
@@ -1785,8 +1939,8 @@ export class TUI extends Container {
 				const extraLines = this.#previousLines.length - newLines.length;
 				if (extraLines > height) {
 					logRedraw(`extraLines > height (${extraLines} > ${height})`);
-					if (isMultiplexerSession() && !useLegacyMultiplexerFullRender()) {
-						multiplexerViewportRepaint(`extraLines > height (${extraLines} > ${height})`);
+					if (useViewportRepaintPath(this.terminal)) {
+						viewportRepaint(`extraLines > height (${extraLines} > ${height})`);
 					} else {
 						fullRender(true, "extraLines > height");
 					}
@@ -1819,16 +1973,19 @@ export class TUI extends Container {
 			return;
 		}
 
-		// Differential rendering can only touch what was actually visible.
-		// Any change above the previous viewport requires a full redraw so terminal
-		// scrollback ends up consistent with the new transcript state.
+		// Differential rendering can only touch what was actually visible. If a
+		// streaming status/header line changes above a live-following viewport, keep
+		// the terminal pinned by diffing from the visible top instead of clearing and
+		// replaying the transcript. If the user paged away, keep the historical
+		// full-redraw behavior so scrollback is repaired rather than snapping them
+		// back to live.
 		if (firstChanged < prevViewportTop) {
 			logRedraw(`firstChanged < viewportTop (${firstChanged} < ${prevViewportTop})`);
-			if (isMultiplexerSession() && !useLegacyMultiplexerFullRender()) {
-				multiplexerViewportRepaint(`firstChanged < viewportTop (${firstChanged} < ${prevViewportTop})`);
-			} else {
-				fullRender(true, "firstChanged < viewportTop");
+			if (useViewportRepaintPath(this.terminal)) {
+				viewportRepaint(`firstChanged < viewportTop (${firstChanged} < ${prevViewportTop})`);
+				return;
 			}
+			fullRender(true, "firstChanged < viewportTop");
 			return;
 		}
 
@@ -1869,16 +2026,17 @@ export class TUI extends Container {
 			const line = newLines[i];
 			let truncatedLine = line;
 			const isImage = TERMINAL.isImageLine(line);
-			if (!isImage && visibleWidth(line) > width) {
+			const lineWidth = isImage ? 0 : this.#visibleWidthForDifferentialGuard(line);
+			if (!isImage && lineWidth > width) {
 				if (debugRedraw) {
 					const debugData = [
 						`[TUI Truncate] ${new Date().toISOString()}`,
-						`Line ${i} truncated: ${visibleWidth(line)} > ${width}`,
+						`Line ${i} truncated: ${lineWidth} > ${width}`,
 						`Content preview: ${line.slice(0, 100)}...`,
 						"",
 					].join("\n");
 					try {
-						fs.appendFileSync(getDebugLogPath(), debugData);
+						this.#appendDebugRedrawLog(debugData);
 					} catch {
 						// Ignore write errors - truncation should still work
 					}