@sayknow-cli/tui 0.3.6 → 0.3.8

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 "@sayknow-cli/utils";
+import { $flag, getDebugLogPath, logger, onDefaultTabWidthChange } from "@sayknow-cli/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";
@@ -139,15 +141,47 @@ function isTermuxSession(): boolean {
 	return Boolean(process.env.TERMUX_VERSION);
 }
 
+const SKC_TMUX_LAUNCHED_ENV = "SKC_TMUX_LAUNCHED";
+const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "no"]);
+
+function envIsEnabled(value: string | undefined): boolean {
+	const normalized = value?.trim().toLowerCase();
+	return normalized !== undefined && normalized.length > 0 && !DISABLED_ENV_VALUES.has(normalized);
+}
+
+function termLooksMultiplexed(value: string | undefined): boolean {
+	const term = value?.trim().toLowerCase() ?? "";
+	return term.startsWith("tmux") || term.startsWith("screen");
+}
+
+function isWindowsTerminalSession(): boolean {
+	return envIsEnabled(Bun.env.WT_SESSION) || Bun.env.TERM_PROGRAM === "Windows_Terminal";
+}
+
+function isViewportRepaintSession(): boolean {
+	return isMultiplexerSession() || isWindowsTerminalSession();
+}
+
 /** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
 function isMultiplexerSession(): boolean {
-	return Boolean(Bun.env.TMUX || Bun.env.STY || Bun.env.ZELLIJ);
+	return Boolean(
+		envIsEnabled(Bun.env.TMUX) ||
+			envIsEnabled(Bun.env.TMUX_PANE) ||
+			envIsEnabled(Bun.env.STY) ||
+			envIsEnabled(Bun.env.ZELLIJ) ||
+			envIsEnabled(Bun.env[SKC_TMUX_LAUNCHED_ENV]) ||
+			termLooksMultiplexed(Bun.env.TERM),
+	);
 }
 
 function useLegacyMultiplexerFullRender(): boolean {
 	return $flag("PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER");
 }
 
+function useViewportRepaintPath(): boolean {
+	return isViewportRepaintSession() && !(isMultiplexerSession() && useLegacyMultiplexerFullRender());
+}
+
 /**
  * Options for overlay positioning and sizing.
  * Values can be absolute numbers or percentage strings (e.g., "50%").
@@ -303,6 +337,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;
 };
 
 /**
@@ -319,6 +360,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;
@@ -341,26 +383,66 @@ export class TUI extends Container {
 	#cursorRow = 0; // Logical cursor row (end of rendered content)
 	#hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
 	#viewportTopRow = 0; // Content row currently mapped to screen row 0
+	#manualViewportTop: number | undefined;
+	#lastCursorPosition: { row: number; col: number } | null = null;
 	#sixelProbePendingDa = false;
 	#sixelProbePendingGraphics = false;
 	#sixelProbeBuffer = "";
 	#sixelProbeTimeout?: NodeJS.Timeout;
 	#sixelProbeUnsubscribe?: () => void;
 	#showHardwareCursor = $flag("PI_HARDWARE_CURSOR");
+	#debugRedraw = TUI.#readDebugRedrawFlag();
 	// macOS: steady-block cursor anchors CJK IME overlays; disable with SKC_TUI_IME_CURSOR=0.
 	readonly #useImeBlockCursor = $flag("SKC_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;
@@ -376,6 +458,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 {
@@ -427,6 +521,47 @@ export class TUI extends Container {
 		this.#bottomPinnedComponent = component;
 		this.requestRender();
 	}
+	scrollViewportPages(direction: -1 | 1): boolean {
+		const height = this.terminal.rows;
+		const width = this.terminal.columns;
+		if (height <= 0 || width <= 0 || this.#previousLines.length === 0) return false;
+		const maxViewportTop = Math.max(0, this.#previousLines.length - height);
+		const currentViewportTop = Math.max(0, Math.min(maxViewportTop, this.#manualViewportTop ?? this.#viewportTopRow));
+		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;
+		return this.#repaintViewportFromLines(
+			this.#previousLines,
+			width,
+			height,
+			targetViewportTop,
+			cursorPos,
+			"manual viewport scroll",
+		);
+	}
+
+	followLiveViewport(): boolean {
+		if (this.#manualViewportTop === undefined) return false;
+		const height = this.terminal.rows;
+		const width = this.terminal.columns;
+		const liveViewportTop = Math.max(0, this.#previousLines.length - height);
+		this.#manualViewportTop = undefined;
+		return this.#repaintViewportFromLines(
+			this.#previousLines,
+			width,
+			height,
+			liveViewportTop,
+			this.#lastCursorPosition,
+			"manual viewport follow live",
+		);
+	}
 
 	/**
 	 * Show an overlay component with configurable positioning and sizing.
@@ -526,7 +661,7 @@ export class TUI extends Container {
 			data => this.#handleInput(data),
 			() => {
 				this.invalidate();
-				this.requestRender(!(isMultiplexerSession() && !useLegacyMultiplexerFullRender()), "resize");
+				this.requestResizeRender();
 			},
 		);
 		this.#hideCursor();
@@ -766,10 +901,28 @@ export class TUI extends Container {
 		this.#previousRaw = [];
 		this.#lineNormalizationCache.clear();
 		this.#lineTruncationCache.clear();
+		this.#lineEmitWidthCache.clear();
 		this.#previousWidth = 0;
 		this.#previousHeight = 0;
 	}
 
+	/**
+	 * 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. Windows Terminal 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(!useViewportRepaintPath() && !isTermuxSession(), "resize");
+	}
+
 	requestRender(force = false, source = "unknown"): void {
 		if (!this.terminalAvailable) {
 			this.#markTerminalUnavailable();
@@ -777,20 +930,24 @@ export class TUI extends Container {
 		}
 		if (renderMetrics.enabled) renderMetrics.recordRequest(source);
 		if (force) {
+			const preserveViewportCursor = useViewportRepaintPath();
 			// 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;
@@ -1256,24 +1413,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 {
@@ -1283,6 +1425,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) {
@@ -1290,6 +1434,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(): {
@@ -1306,17 +1455,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;
 	}
@@ -1345,6 +1543,63 @@ export class TUI extends Container {
 		padded.splice(insertAt, 0, ...Array.from({ length: blankRows }, () => ""));
 		return padded;
 	}
+	#repaintViewportFromLines(
+		lines: string[],
+		width: number,
+		height: number,
+		viewportTop: number,
+		cursorPos: { row: number; col: number } | null,
+		reason: string,
+	): boolean {
+		if (height <= 0 || width <= 0) return false;
+		const maxViewportTop = Math.max(0, lines.length - height);
+		const nextViewportTop = Math.max(0, Math.min(maxViewportTop, viewportTop));
+		const currentScreenRow = Math.max(0, Math.min(height - 1, this.#hardwareCursorRow - this.#viewportTopRow));
+		let buffer = "\x1b[?2026h";
+		if (currentScreenRow > 0) {
+			buffer += `\x1b[${currentScreenRow}A`;
+		}
+		buffer += "\r";
+
+		for (let screenRow = 0; screenRow < height; screenRow++) {
+			if (screenRow > 0) buffer += "\r\n";
+			buffer += "\x1b[2K";
+			const lineIndex = nextViewportTop + screenRow;
+			if (lineIndex >= lines.length) continue;
+			const line = lines[lineIndex];
+			const isImage = TERMINAL.isImageLine(line);
+			if (!isImage && this.#visibleWidthForDifferentialGuard(line) > width) {
+				let truncatedLine = truncateToWidth(line, width, Ellipsis.Omit);
+				truncatedLine += truncatedLine.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET;
+				buffer += truncatedLine;
+			} else {
+				buffer += line;
+			}
+		}
+
+		const finalPhysicalRow = nextViewportTop + Math.max(0, height - 1);
+		let cursorSeq = "\x1b[?25l";
+		let cursorToRow = finalPhysicalRow;
+		if (cursorPos && cursorPos.row >= nextViewportTop && cursorPos.row < nextViewportTop + height) {
+			const cursor = this.#cursorControlSequence(cursorPos, lines.length, finalPhysicalRow);
+			cursorSeq = cursor.seq;
+			cursorToRow = cursor.toRow;
+		}
+		this.#hardwareCursorRow = cursorToRow;
+		buffer += cursorSeq;
+		buffer += "\x1b[?2026l";
+		if (!this.#writeTerminal(buffer)) return false;
+
+		if (this.#debugRedraw) {
+			const msg = `[${new Date().toISOString()}] viewportRepaint: ${reason} (lines=${lines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
+			this.#appendDebugRedrawLog(msg);
+		}
+
+		this.#cursorRow = Math.max(0, lines.length - 1);
+		this.#maxLinesRendered = lines.length;
+		this.#viewportTopRow = nextViewportTop;
+		return true;
+	}
 
 	#doRender(): void {
 		if (this.#stopped || !this.terminalAvailable) return;
@@ -1375,6 +1630,7 @@ export class TUI extends Container {
 
 		// Extract cursor position (marker must be found before diff comparison)
 		const cursorPos = this.#extractCursorPosition(newLines, height);
+		this.#lastCursorPosition = cursorPos;
 
 		// Terminate every non-image line so #previousLines mirrors emitted bytes
 		// (closes SGR + OSC 8 hyperlink state). Must run after cursor extraction
@@ -1413,8 +1669,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;
@@ -1435,6 +1692,28 @@ export class TUI extends Container {
 			if (usedWindowNormalize) renderMetrics.recordLineCount("offscreenScan", diffStart);
 		}
 
+		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;
+			if (
+				this.#repaintViewportFromLines(
+					newLines,
+					width,
+					height,
+					nextViewportTop,
+					repaintCursorPos,
+					"manual viewport render",
+				)
+			) {
+				this.#previousLines = newLines;
+				this.#previousWidth = width;
+				this.#previousHeight = height;
+			}
+			return;
+		}
 		// Helper to clear scrollback and viewport and render all new lines
 		const fullRender = (clear: boolean, reason = "full render"): void => {
 			this.#fullRedrawCount += 1;
@@ -1466,7 +1745,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);
@@ -1483,7 +1762,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;
@@ -1505,15 +1784,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;
@@ -1522,12 +1800,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)
@@ -1540,7 +1817,15 @@ 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})`);
-			fullRender(true, "terminal width changed");
+			if (useViewportRepaintPath()) {
+				// 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");
+			}
 			return;
 		}
 
@@ -1548,8 +1833,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()) {
+				viewportRepaint(`terminal height changed (${this.#previousHeight} -> ${height})`);
 				return;
 			}
 			if (!isTermuxSession() && !isMultiplexerSession()) {
@@ -1564,7 +1849,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()) {
+				viewportRepaint(`clearOnShrink (prev=${this.#previousLines.length}, new=${newLines.length})`);
+			} else {
+				fullRender(true, "clearOnShrink");
+			}
 			return;
 		}
 
@@ -1602,6 +1891,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) {
@@ -1616,8 +1910,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()) {
+						viewportRepaint(`extraLines > height (${extraLines} > ${height})`);
 					} else {
 						fullRender(true, "extraLines > height");
 					}
@@ -1650,16 +1944,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()) {
+				viewportRepaint(`firstChanged < viewportTop (${firstChanged} < ${prevViewportTop})`);
+				return;
 			}
+			fullRender(true, "firstChanged < viewportTop");
 			return;
 		}
 
@@ -1700,16 +1997,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
 					}