@oh-my-pi/pi-tui 16.4.8 → 16.5.1

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [16.5.1] - 2026-07-14
+
+### Fixed
+
+- Optimized the Markdown rendering cache to prevent large documents from indefinitely occupying cache slots, improving memory usage and performance ([#4820](https://github.com/can1357/oh-my-pi/issues/4820)).
+- Fixed viewport corruption on macOS caused by unmanaged stderr writes (such as libmalloc or framework diagnostics) while the terminal is active.
+- Fixed an issue where streamed diff code fences retained unhighlighted rows in native scrollback when long transient blocks left the viewport before finalization ([#5126](https://github.com/can1357/oh-my-pi/issues/5126)).
+- Fixed native Windows Terminal sessions failing to detect mid-run light/dark theme changes when Mode 2031 appearance notifications are unavailable ([#5091](https://github.com/can1357/oh-my-pi/issues/5091)).
+- Hid empty HTML comment separators in Markdown-rendered TUI output instead of displaying them literally ([#4911](https://github.com/can1357/oh-my-pi/issues/4911)).
+
+## [16.5.0] - 2026-07-13
+
+### Changed
+
+ - Improved native scrollback history management by introducing an optional erase-and-replay mechanism to rebuild scrollback when mutated rows (such as finalized tool blocks or collapsed transcripts) diverge. This is now gated behind the `tui.scrollbackRebuild` setting and defaults to off.
+
+### Fixed
+
+- Fixed a rendering issue where resizing the terminal during forced renders (such as tool finalization or image reconciliation) caused the entire transcript to visibly replay and flicker. Forced renders are now consolidated into a single paint once the resize settles.
+
 ## [16.4.7] - 2026-07-12
 
 ### Fixed

package/dist/types/tui.d.ts

@@ -97,6 +97,13 @@ export interface NativeScrollbackLiveRegion {
 export interface NativeScrollbackCommittedRows {
     setNativeScrollbackCommittedRows(rows: number): void;
 }
+/**
+ * A component that discards rows after they enter native scrollback implements
+ * this hook so a destructive full replay can rehydrate its complete frame.
+ */
+export interface NativeScrollbackReplay {
+    prepareNativeScrollbackReplay(): void;
+}
 /**
  * Opt-in stability report for components that mutate their returned render
  * array in place across frames (instead of returning a fresh array per
@@ -280,9 +287,11 @@ export declare function coalesceAdjacentSgr(line: string): string;
  *       source just became declared-final (the block finalized / a barrier
  *       cleared). Hard-scanned in FULL with no tolerance: any content change
  *       (a pending header settling, a preview replaced by its result, a tail
- *       shifting up after a barrier removal) re-anchors so the final content
- *       recommits below the frozen snapshot — duplication, never loss —
- *       instead of being committed nowhere and painted nowhere.
+ *       shifting up after a barrier removal) re-anchors so the engine can
+ *       erase-and-replay history with the final content exactly once (or, on
+ *       ED3-unsafe multiplexers, recommit it below the frozen snapshot —
+ *       duplication, never loss) instead of committing it nowhere and
+ *       painting it nowhere.
  *   [finalTo, prefix.length) FROZEN visual snapshots of still-live rows —
  *       exempt: their drift is expected (a collapsing preview, a ticking
  *       progress tree) and must never spray re-anchors mid-run.
@@ -335,6 +344,17 @@ export declare class TUI extends Container {
      * plus a full redraw on the frame after a new image exceeds the cap.
      */
     setMaxInlineImages(cap: number): void;
+    /**
+     * Get whether scrollback divergence rebuild is enabled.
+     */
+    getScrollbackRebuild(): boolean;
+    /**
+     * Enable or disable scrollback divergence rebuild (default off).
+     * When enabled, the engine will erase and replay the terminal's
+     * scrollback (using ED3 / alt buffer / scrollback replay) to avoid
+     * duplicate blocks when a block's final form replaces its live preview.
+     */
+    setScrollbackRebuild(enabled: boolean): void;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "16.4.8",
+	"version": "16.5.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,10 +37,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.4.8",
-		"@oh-my-pi/pi-utils": "16.4.8",
-		"lru-cache": "11.5.1",
-		"marked": "^18.0.5"
+		"@oh-my-pi/pi-natives": "16.5.1",
+		"@oh-my-pi/pi-utils": "16.5.1",
+		"lru-cache": "11.5.2",
+		"marked": "^18.0.6"
 	},
 	"devDependencies": {
 		"chalk": "^5.6.2",

package/src/components/markdown.ts

@@ -86,6 +86,7 @@ function createHtmlNormalizationState(): HtmlNormalizationState {
 	return { lists: [], openItems: [], itemHasContent: [] };
 }
 
+const HTML_COMMENT_REGEX = /<!--[\s\S]*?-->/g;
 const HTML_TAG_REGEX = /<\/?(?:br|p|ol|ul|li|span|text|code|hr|blockquote)\b(?:\s[^>]*)?\s*\/?>/gi;
 // Block-level HTML that needs structural (not just textual) rendering: standalone
 // `<hr>` becomes a rule and balanced `<blockquote>…</blockquote>` renders with
@@ -136,11 +137,12 @@ function normalizeHtmlForTerminal(
 	let output = "";
 	let lastIndex = 0;
 	let inCode = false;
+	const withoutComments = raw.replace(HTML_COMMENT_REGEX, "");
 
-	for (const match of raw.matchAll(HTML_TAG_REGEX)) {
+	for (const match of withoutComments.matchAll(HTML_TAG_REGEX)) {
 		const tag = match[0];
 		const index = match.index ?? 0;
-		const textBeforeTag = normalizeHtmlEntitiesForTerminal(raw.slice(lastIndex, index));
+		const textBeforeTag = normalizeHtmlEntitiesForTerminal(withoutComments.slice(lastIndex, index));
 		const name = htmlTagName(tag);
 		// Most tags handled here are block-level. Inline contexts — span, text, and
 		// the content inside a `<code>` run — keep their surrounding whitespace
@@ -238,7 +240,7 @@ function normalizeHtmlForTerminal(
 		}
 	}
 
-	const remainingText = normalizeHtmlEntitiesForTerminal(raw.slice(lastIndex));
+	const remainingText = normalizeHtmlEntitiesForTerminal(withoutComments.slice(lastIndex));
 	markCurrentHtmlItemContent(state, remainingText);
 	return output + (inCode && codeHook ? codeHook(remainingText) : remainingText);
 }
@@ -602,8 +604,21 @@ markdownParser.use({ extensions: [customHrExtension, mathBlockExtension, mathEnv
 // (Rust FFI) work for content/layout combinations already seen this session.
 
 const RENDER_CACHE_MAX = 256; // sane cap: ~256 distinct message × width combos
+const RENDER_CACHE_MAX_SIZE = 512 * 1024;
+const RENDER_CACHE_MAX_ENTRY_SIZE = 32 * 1024;
 const EMPTY_RENDER_LINES: readonly string[] = [];
-const renderCache = new LRUCache<string, readonly string[]>({ max: RENDER_CACHE_MAX });
+const renderCache = new LRUCache<string, readonly string[]>({
+	max: RENDER_CACHE_MAX,
+	maxSize: RENDER_CACHE_MAX_SIZE,
+	maxEntrySize: RENDER_CACHE_MAX_ENTRY_SIZE,
+	sizeCalculation: renderedLinesCacheSize,
+});
+
+function renderedLinesCacheSize(lines: readonly string[]): number {
+	let size = lines.length;
+	for (let i = 0; i < lines.length; i++) size += lines[i]!.length;
+	return Math.max(1, size);
+}
 
 // A reference-link definition (`[label]: dest`) resolves across the whole
 // document, so a split lex cannot reproduce it — disable the streaming fast path
@@ -937,6 +952,11 @@ interface StreamPrefixLineCache extends RenderSignature {
 	tokenCount: number;
 	lines: readonly string[];
 }
+interface StreamingDiffLineCache extends RenderSignature {
+	lang: string | undefined;
+	text: string;
+	lines: readonly string[];
+}
 
 export class Markdown implements Component {
 	#text: string;
@@ -979,8 +999,12 @@ export class Markdown implements Component {
 	// True while #renderStreamingContentLines renders the frozen token range:
 	// frozen code blocks highlight even in transient mode so their bytes match
 	// the finalized render (they render once into the prefix line cache, so
-	// the FFI cost is amortized); the volatile tail stays unhighlighted.
+	// the FFI cost is amortized). The volatile tail normally stays
+	// unhighlighted; streaming diff fences line-highlight completed rows so
+	// semantic colors reach native scrollback before rows leave the viewport.
 	#renderingFrozenPrefix = false;
+	#streamingDiffLineCache?: StreamingDiffLineCache;
+	#activeRenderSignature?: RenderSignature;
 
 	#ignoreTight = false;
 
@@ -1190,9 +1214,15 @@ export class Markdown implements Component {
 
 		// Parse markdown to HTML-like tokens
 		const tokens = this.#lexTokens(normalizedText);
-		const contentLines = this.transientRenderCache
-			? this.#renderStreamingContentLines(tokens, normalizedText, signature, contentWidth)
-			: this.#renderContentLines(tokens, 0, tokens.length, contentWidth, signature);
+		let contentLines: string[];
+		this.#activeRenderSignature = signature;
+		try {
+			contentLines = this.transientRenderCache
+				? this.#renderStreamingContentLines(tokens, normalizedText, signature, contentWidth)
+				: this.#renderContentLines(tokens, 0, tokens.length, contentWidth, signature);
+		} finally {
+			this.#activeRenderSignature = undefined;
+		}
 		const emptyLines = this.#renderEmptyPaddingLines(signature);
 
 		// Combine top padding, content, and bottom padding
@@ -1386,6 +1416,122 @@ export class Markdown implements Component {
 		return contentLines;
 	}
 
+	#renderCodeBodyLines(token: Token, codeIndent: string): string[] {
+		const bodyLines: string[] = [];
+		const tokenText = "text" in token && typeof token.text === "string" ? token.text : "";
+		const lang = "lang" in token && typeof token.lang === "string" ? token.lang : undefined;
+		const normalizedLang = lang?.toLowerCase();
+		const canStreamDiff =
+			this.transientRenderCache &&
+			!this.#renderingFrozenPrefix &&
+			this.#theme.highlightCode &&
+			(normalizedLang === "diff" || normalizedLang === "patch" || normalizedLang === "udiff");
+
+		if (this.#theme.highlightCode && (!this.transientRenderCache || this.#renderingFrozenPrefix)) {
+			const highlightedLines = this.#theme.highlightCode(tokenText, lang);
+			for (const hlLine of highlightedLines) {
+				bodyLines.push(`${codeIndent}${hlLine}`);
+			}
+			return bodyLines;
+		}
+
+		if (canStreamDiff) {
+			const closedFence = this.#codeTokenHasClosingFence(token);
+			const lineEnd = tokenText.lastIndexOf("\n");
+			if (closedFence || lineEnd >= 0) {
+				const completedText = closedFence ? tokenText : tokenText.slice(0, lineEnd);
+				for (const hlLine of this.#highlightStreamingDiffLines(completedText, lang)) {
+					bodyLines.push(`${codeIndent}${hlLine}`);
+				}
+				if (!closedFence) {
+					for (const codeLine of tokenText.slice(lineEnd + 1).split("\n")) {
+						bodyLines.push(`${codeIndent}${this.#theme.codeBlock(codeLine)}`);
+					}
+				}
+				return bodyLines;
+			}
+		}
+
+		for (const codeLine of tokenText.split("\n")) {
+			bodyLines.push(`${codeIndent}${this.#theme.codeBlock(codeLine)}`);
+		}
+		return bodyLines;
+	}
+
+	#codeTokenHasClosingFence(token: Token): boolean {
+		const raw = "raw" in token && typeof token.raw === "string" ? token.raw : "";
+		const firstLineEnd = raw.indexOf("\n");
+		if (firstLineEnd < 0) return false;
+		const openingLine = raw.slice(0, firstLineEnd);
+		const openingTrimmed = openingLine.trimStart();
+		const openingIndent = openingLine.length - openingTrimmed.length;
+		if (openingIndent > 3) return false;
+		const fenceChar = openingTrimmed.charAt(0);
+		if (fenceChar !== "`" && fenceChar !== "~") return false;
+		let fenceLength = 0;
+		while (openingTrimmed.charAt(fenceLength) === fenceChar) fenceLength++;
+		if (fenceLength < 3) return false;
+
+		let lineStart = firstLineEnd + 1;
+		while (lineStart <= raw.length) {
+			const lineEnd = raw.indexOf("\n", lineStart);
+			const line = lineEnd >= 0 ? raw.slice(lineStart, lineEnd) : raw.slice(lineStart);
+			const trimmed = line.trimStart();
+			const indent = line.length - trimmed.length;
+			let closingLength = 0;
+			while (trimmed.charAt(closingLength) === fenceChar) closingLength++;
+			if (indent <= 3 && closingLength >= fenceLength && trimmed.slice(closingLength).trim().length === 0) {
+				return true;
+			}
+			if (lineEnd < 0) break;
+			lineStart = lineEnd + 1;
+		}
+		return false;
+	}
+
+	#highlightStreamingDiffLines(completedText: string, lang: string | undefined): readonly string[] {
+		const highlightCode = this.#theme.highlightCode;
+		if (!highlightCode) return [];
+		const signature = this.#activeRenderSignature;
+		const cache = this.#streamingDiffLineCache;
+		if (
+			signature &&
+			cache &&
+			completedText.startsWith(cache.text) &&
+			(cache.text.length === completedText.length || completedText.charCodeAt(cache.text.length) === 0x0a) &&
+			cache.lang === lang &&
+			cache.width === signature.width &&
+			cache.paddingX === signature.paddingX &&
+			cache.paddingY === signature.paddingY &&
+			cache.codeBlockIndent === signature.codeBlockIndent &&
+			cache.themeId === signature.themeId &&
+			cache.defaultTextStyleId === signature.defaultTextStyleId &&
+			cache.imageProtocol === signature.imageProtocol &&
+			cache.hyperlinks === signature.hyperlinks &&
+			cache.textSizing === signature.textSizing &&
+			cache.bgColorProbe === signature.bgColorProbe &&
+			cache.headingProbe === signature.headingProbe
+		) {
+			if (completedText.length === cache.text.length) return cache.lines;
+			const lines = cache.lines.slice();
+			const addedText = completedText.slice(cache.text.length + 1);
+			for (const codeLine of addedText.split("\n")) {
+				lines.push(...highlightCode(codeLine, lang));
+			}
+			this.#streamingDiffLineCache = { ...signature, lang, text: completedText, lines };
+			return lines;
+		}
+
+		const lines: string[] = [];
+		for (const codeLine of completedText.split("\n")) {
+			lines.push(...highlightCode(codeLine, lang));
+		}
+		if (signature) {
+			this.#streamingDiffLineCache = { ...signature, lang, text: completedText, lines };
+		}
+		return lines;
+	}
+
 	#renderEmptyPaddingLines(signature: RenderSignature): string[] {
 		const emptyLine = padding(signature.width);
 		const emptyLines: string[] = [];
@@ -1563,17 +1709,8 @@ export class Markdown implements Component {
 
 				const codeIndent = padding(this.#codeBlockIndent);
 				lines.push(this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`));
-				if (this.#theme.highlightCode && (!this.transientRenderCache || this.#renderingFrozenPrefix)) {
-					const highlightedLines = this.#theme.highlightCode(token.text, token.lang);
-					for (const hlLine of highlightedLines) {
-						lines.push(`${codeIndent}${hlLine}`);
-					}
-				} else {
-					// Split code by newlines and style each line
-					const codeLines = token.text.split("\n");
-					for (const codeLine of codeLines) {
-						lines.push(`${codeIndent}${this.#theme.codeBlock(codeLine)}`);
-					}
+				for (const bodyLine of this.#renderCodeBodyLines(token, codeIndent)) {
+					lines.push(bodyLine);
 				}
 				lines.push(this.#theme.codeBlockBorder("```"));
 				if (nextTokenType && nextTokenType !== "space") {
@@ -1953,16 +2090,8 @@ export class Markdown implements Component {
 				// Code block in list item
 				const codeIndent = padding(this.#codeBlockIndent);
 				lines.push({ text: this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`), nested: false });
-				if (this.#theme.highlightCode && (!this.transientRenderCache || this.#renderingFrozenPrefix)) {
-					const highlightedLines = this.#theme.highlightCode(token.text, token.lang);
-					for (const hlLine of highlightedLines) {
-						lines.push({ text: `${codeIndent}${hlLine}`, nested: false });
-					}
-				} else {
-					const codeLines = token.text.split("\n");
-					for (const codeLine of codeLines) {
-						lines.push({ text: `${codeIndent}${this.#theme.codeBlock(codeLine)}`, nested: false });
-					}
+				for (const bodyLine of this.#renderCodeBodyLines(token, codeIndent)) {
+					lines.push({ text: bodyLine, nested: false });
 				}
 				lines.push({ text: this.#theme.codeBlockBorder("```"), nested: false });
 			} else if (isMathToken(token)) {

package/src/terminal.ts

@@ -1,6 +1,14 @@
 import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as fs from "node:fs";
-import { $env, isBunTestRuntime, isTerminalHeadless, logger, postmortem } from "@oh-my-pi/pi-utils";
+import {
+	$env,
+	isBunTestRuntime,
+	isTerminalHeadless,
+	logger,
+	postmortem,
+	restoreTerminalStderr,
+	suppressTerminalStderr,
+} from "@oh-my-pi/pi-utils";
 import { setKittyProtocolActive } from "./keys";
 import { StdinBuffer } from "./stdin-buffer";
 import {
@@ -16,6 +24,7 @@ import { type HangulCompatibilityJamoWidth, setHangulCompatibilityJamoWidth } fr
 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";
+const WINDOWS_TERMINAL_OSC11_POLL_MS = 30_000;
 // Hangul Compatibility Jamo (U+3131..=U+318E) render width is terminal-dependent:
 // Ghostty follows UAX#11 (2 cells); Terminal.app and iTerm2 render narrow (1),
 // matching the macOS platform default. Override only for terminals known to
@@ -40,6 +49,11 @@ function shouldEnableModifyOtherKeysFallback(env: NodeJS.ProcessEnv = Bun.env):
 	return TERMINAL.id !== "base" && TERMINAL.id !== "trueColor";
 }
 
+function shouldPollWindowsTerminalAppearance(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	if (process.platform !== "win32") return false;
+	if (!env.WT_SESSION) return false;
+	return !env.TERM_PROGRAM || env.TERM_PROGRAM.toLowerCase() === "windows_terminal";
+}
 /**
  * Maximum encoded UTF-8 bytes per `process.stdout.write` call on Windows.
  *
@@ -275,6 +289,9 @@ function createConsoleCodepageGuard(): (() => void) | null {
  */
 export function emergencyTerminalRestore(): void {
 	try {
+		// Crash paths must surface subsequent stderr (fatal reports) on the
+		// real terminal; no-op when the stderr guard is inactive.
+		restoreTerminalStderr();
 		const terminal = activeTerminal;
 		if (terminal) {
 			terminal.stop();
@@ -488,6 +505,7 @@ export class ProcessTerminal implements Terminal {
 	#reportedColumns?: number;
 	#reportedRows?: number;
 	#mode2031DebounceTimer?: Timer;
+	#windowsTerminalAppearancePollTimer?: Timer;
 	#progressTimer?: Timer;
 
 	get kittyProtocolActive(): boolean {
@@ -551,6 +569,11 @@ export class ProcessTerminal implements Terminal {
 		activeTerminal = this;
 		terminalEverStarted = true;
 
+		// Keep unmanaged fd-2 writes (macOS libmalloc/framework diagnostics) off
+		// the viewport while we own the terminal; released in stop(). See
+		// stderr-guard in pi-utils (mirrors openai/codex#24459).
+		suppressTerminalStderr();
+
 		// Save previous state and enable raw mode
 		this.#wasRaw = process.stdin.isRaw || false;
 		if (process.stdin.setRawMode) {
@@ -611,7 +634,8 @@ export class ProcessTerminal implements Terminal {
 		// WezTerm) detect the appearance once at startup and pick up later OS
 		// theme changes on next launch. Earlier builds polled OSC 11 every 30 s
 		// here for those terminals, but each poll's OSC 11/DA1 write wiped the
-		// user's active text selection on several of them (#3297).
+		// user's active text selection on several of them (#3297). Native Windows
+		// Terminal gets a scoped fallback after DECRQM confirms 2031 is unsupported.
 
 		// Probe DEC private-mode support via DECRQM. 2026 (synchronized output)
 		// gates the renderer's begin/end markers; 2048 (in-band resize) is enabled
@@ -1151,8 +1175,25 @@ export class ProcessTerminal implements Terminal {
 			}
 		}
 		if (mode === 2048 && supported) this.#enableInBandResize();
+		if (mode === 2031) this.#syncWindowsTerminalAppearancePolling(supported);
 	}
 
+	#syncWindowsTerminalAppearancePolling(mode2031Supported: boolean): void {
+		if (mode2031Supported || !shouldPollWindowsTerminalAppearance() || this.#dead) {
+			this.#clearWindowsTerminalAppearancePoll();
+			return;
+		}
+		if (this.#windowsTerminalAppearancePollTimer) return;
+		this.#windowsTerminalAppearancePollTimer = setInterval(() => {
+			this.#queryBackgroundColor();
+		}, WINDOWS_TERMINAL_OSC11_POLL_MS);
+	}
+
+	#clearWindowsTerminalAppearancePoll(): void {
+		if (!this.#windowsTerminalAppearancePollTimer) return;
+		clearInterval(this.#windowsTerminalAppearancePollTimer);
+		this.#windowsTerminalAppearancePollTimer = undefined;
+	}
 	#disableXtermScrollToBottomMode(mode: number): void {
 		if (this.#xtermScrollToBottomRestoreModes.has(mode) || this.#dead) return;
 		this.#xtermScrollToBottomRestoreModes.add(mode);
@@ -1269,6 +1310,11 @@ export class ProcessTerminal implements Terminal {
 			activeTerminal = null;
 		}
 
+		// Release terminal ownership of fd 2 first so external programs,
+		// suspend, and shutdown see the real stderr even if a later teardown
+		// step throws.
+		restoreTerminalStderr();
+
 		if (this.#clearProgressTimer()) {
 			this.#safeWrite(TERMINAL_PROGRESS_CLEAR_SEQUENCE);
 		}
@@ -1305,6 +1351,7 @@ export class ProcessTerminal implements Terminal {
 		}
 		this.#appearanceCallbacks = [];
 		this.#osc11Pending = false;
+		this.#clearWindowsTerminalAppearancePoll();
 		this.#osc11QueryQueued = false;
 		this.#osc11ResponseBuffer = "";
 		this.#osc99PendingId = undefined;

package/src/tui.ts

@@ -5,11 +5,15 @@
  * immutable — the tape is the terminal's visual record. Whatever scrolls
  * above the window enters history exactly once, in order: as exact-final
  * bytes when the component seam (`NativeScrollbackLiveRegion`) declared them
- * final, else as a frozen snapshot of what was on screen. ED3 (`CSI 3 J`) is
- * emitted only for gesture-driven replays (session replace, resize,
- * resetDisplay) where snapping the viewport is acceptable. The engine never
- * probes or guesses the terminal's scroll position, and the hot path clamps
- * over-wide lines instead of throwing. See `docs/tui-core-renderer.md`.
+ * final, else as a frozen snapshot of what was on screen. When recorded
+ * history diverges from the frame (a finalized block replacing its
+ * scrolled-off live render), the engine erases and replays (ED3, `CSI 3 J`)
+ * so history holds the content exactly once — the same replay used for
+ * gestures (session replace, resize, resetDisplay). Multiplexer panes, where
+ * ED3 is unsafe, instead re-anchor and recommit below the stale fragment —
+ * duplication, never loss. The engine never probes or guesses the terminal's
+ * scroll position, and the hot path clamps over-wide lines instead of
+ * throwing. See `docs/tui-core-renderer.md`.
  */
 import * as fs from "node:fs";
 import { performance } from "node:perf_hooks";
@@ -207,6 +211,18 @@ export interface NativeScrollbackCommittedRows {
 	setNativeScrollbackCommittedRows(rows: number): void;
 }
 
+/**
+ * A component that discards rows after they enter native scrollback implements
+ * this hook so a destructive full replay can rehydrate its complete frame.
+ */
+export interface NativeScrollbackReplay {
+	prepareNativeScrollbackReplay(): void;
+}
+
+function prepareNativeScrollbackReplay(component: Component): void {
+	(component as Component & Partial<NativeScrollbackReplay>).prepareNativeScrollbackReplay?.();
+}
+
 function setNativeScrollbackCommittedRows(component: Component, rows: number): void {
 	(component as Component & Partial<NativeScrollbackCommittedRows>).setNativeScrollbackCommittedRows?.(rows);
 }
@@ -783,9 +799,11 @@ const RESYNC_TAIL_SAMPLES = 8;
  *       source just became declared-final (the block finalized / a barrier
  *       cleared). Hard-scanned in FULL with no tolerance: any content change
  *       (a pending header settling, a preview replaced by its result, a tail
- *       shifting up after a barrier removal) re-anchors so the final content
- *       recommits below the frozen snapshot — duplication, never loss —
- *       instead of being committed nowhere and painted nowhere.
+ *       shifting up after a barrier removal) re-anchors so the engine can
+ *       erase-and-replay history with the final content exactly once (or, on
+ *       ED3-unsafe multiplexers, recommit it below the frozen snapshot —
+ *       duplication, never loss) instead of committing it nowhere and
+ *       painting it nowhere.
  *   [finalTo, prefix.length) FROZEN visual snapshots of still-live rows —
  *       exempt: their drift is expected (a collapsing preview, a ticking
  *       progress tree) and must never spray re-anchors mid-run.
@@ -1001,6 +1019,8 @@ export class TUI extends Container {
 	#clearScrollbackOnNextRender = false;
 	#forceViewportRepaintOnNextRender = false;
 	#hasEverRendered = false;
+	#scrollbackRebuildEnabled =
+		Bun.env.PI_TUI_SCROLLBACK_REBUILD === "1" || Bun.env.PI_TUI_SCROLLBACK_REBUILD === "true";
 	// Set by the terminal resize callback; consumed by the next render. A resize
 	// event invalidates the committed screen even when the dimensions net out
 	// unchanged by render time (e.g. a 6→4→6 round trip coalesced into one frame
@@ -1290,6 +1310,23 @@ export class TUI extends Container {
 		this.#imageBudget.setCap(cap);
 	}
 
+	/**
+	 * Get whether scrollback divergence rebuild is enabled.
+	 */
+	getScrollbackRebuild(): boolean {
+		return this.#scrollbackRebuildEnabled;
+	}
+
+	/**
+	 * Enable or disable scrollback divergence rebuild (default off).
+	 * When enabled, the engine will erase and replay the terminal's
+	 * scrollback (using ED3 / alt buffer / scrollback replay) to avoid
+	 * duplicate blocks when a block's final form replaces its live preview.
+	 */
+	setScrollbackRebuild(enabled: boolean): void {
+		this.#scrollbackRebuildEnabled = enabled;
+	}
+
 	getShowHardwareCursor(): boolean {
 		return this.#showHardwareCursor;
 	}
@@ -2696,23 +2733,39 @@ export class TUI extends Container {
 		//     alternate screen to repaint the whole transcript on the normal
 		//     screen — then the next SIGWINCH re-enters the alt screen and paints
 		//     only the tail, so the block flashes in for one frame and vanishes.
-		// A forced render (tool finalization, reset, image reconciliation) must
-		// still preempt: it set #forceViewportRepaintOnNextRender via
-		// #prepareForcedRender and owns the next authoritative paint, so it falls
-		// through. A visible overlay composites over the transcript and needs the
-		// whole window, so it also falls through (overlay resizes are not on the
-		// drag-cost hot path).
-		if (
-			this.#resizeViewportActive &&
-			!this.#forceViewportRepaintOnNextRender &&
-			this.#hasEverRendered &&
-			this.#getTopmostVisibleOverlay() === undefined
-		) {
+		// A FORCED render mid-drag (tool finalization, resetDisplay, image
+		// reconciliation) also stays on the fast path: preempting would leave
+		// the borrowed alternate screen and run the geometry-rebuild full paint
+		// on the normal screen — ED3 plus an O(history) replay that visibly
+		// scrolls the whole transcript through the viewport, once per forced
+		// render and once more at settle. The forced intent is not lost: the
+		// fast path consumes neither #forceViewportRepaintOnNextRender nor
+		// #clearScrollbackOnNextRender, and the settle's authoritative
+		// requestRender(true) honors both — same fold-into-the-settle contract
+		// as the multiplexer resize debounce. A visible overlay composites over
+		// the transcript and needs the whole window, so it falls through
+		// (overlay resizes are not on the drag-cost hot path).
+		if (this.#resizeViewportActive && this.#hasEverRendered && this.#getTopmostVisibleOverlay() === undefined) {
 			this.#componentRenderTargets.clear();
 			this.#renderResizeViewport(width, height);
 			return;
 		}
 
+		// A destructive replay erases native history and must receive the complete
+		// component frame. Give virtualized roots one compose to rehydrate rows
+		// they dropped after commit. Height-only and net-unchanged resize events
+		// count too: both enter the geometry rebuild path below.
+		const replayFullHistory =
+			this.#hasEverRendered &&
+			!resizeRepaintsInPlace() &&
+			(this.#clearScrollbackOnNextRender ||
+				this.#resizeEventPending ||
+				(this.#previousWidth > 0 && this.#previousWidth !== width) ||
+				(this.#previousHeight > 0 && this.#previousHeight !== height));
+		if (replayFullHistory) {
+			for (const child of this.children) prepareNativeScrollbackReplay(child);
+		}
+
 		// 1. Compose the frame. Bracket the render so the image budget observes
 		// every inline image in display order (overlays carry none). A
 		// component-scoped frame skips the budget pass instead — it is gated on
@@ -2777,8 +2830,9 @@ export class TUI extends Container {
 		// verified once (a pending header settling, a barrier clearing above a
 		// shifted tail); rows past the boundary are still-live frozen snapshots,
 		// exempt so a collapsing preview can never spray re-anchors mid-run. A
-		// divergence re-anchors and recommits — duplication, never loss —
-		// instead of silently skipping rows (committed nowhere, painted
+		// divergence re-anchors — feeding the divergenceRebuild erase-and-replay
+		// below (mux fallback: recommit below the stale copy; duplication, never
+		// loss) — instead of silently skipping rows (committed nowhere, painted
 		// nowhere). Skipped on geometry frames (a rewrap legitimately reflows
 		// every row), and skipped when the composed frame's stable prefix
 		// covers every verified row and no rows newly became final.
@@ -2851,7 +2905,21 @@ export class TUI extends Container {
 		const firstPaint = !this.#hasEverRendered;
 		const replaceRequested = this.#clearScrollbackOnNextRender;
 		const geometryRebuild = geometryChanged && !resizeRepaintsInPlace();
-		const fullPaint = firstPaint || replaceRequested || geometryRebuild;
+		// Committed history no longer matches the frame: a finalized block
+		// replaced its scrolled-off live render, or the frame collapsed into
+		// recorded rows. Native scrollback is a render cache, not a court
+		// record — erase and replay so history holds the content exactly once,
+		// instead of recommitting the final form below the stale fragment
+		// (a visibly duplicated block). Multiplexer panes cannot ED3 safely
+		// and keep the repair-below fallback in the branches under this one.
+		const divergenceRebuild =
+			this.#scrollbackRebuildEnabled &&
+			!firstPaint &&
+			!replaceRequested &&
+			!geometryChanged &&
+			!isMultiplexerSession() &&
+			(committedRowsResynced || frameLength <= this.#committedRows);
+		const fullPaint = firstPaint || replaceRequested || geometryRebuild || divergenceRebuild;
 		let windowTop: number;
 		let chunkTo: number;
 		if (fullPaint) {
@@ -2864,16 +2932,17 @@ export class TUI extends Container {
 				frameLength - this.#committedRows < height &&
 				cursorMarkers.some(marker => marker.row >= this.#committedRows))
 		) {
-			// Either the frame shrank into the committed prefix, or a
-			// committed-prefix resync left a focused cursor tail shorter than the
-			// viewport. The latter happens when a streaming/live block had an
-			// append-only prefix committed, then collapses on abort/finalize:
-			// the audit re-anchors #committedRows at the first divergent row, but
-			// flooring windowTop there would pin the editor near the top and
-			// leave blank rows underneath. Re-show the frame tail instead. The
-			// stale committed copy stays in native history; duplicating a few rows
-			// is preferable to a live editor gap and matches the existing
-			// "duplication, never loss" resync contract.
+			// Multiplexer fallback (a direct terminal takes the divergenceRebuild
+			// full paint above): either the frame shrank into the committed
+			// prefix, or a committed-prefix resync left a focused cursor tail
+			// shorter than the viewport. The latter happens when a streaming/live
+			// block had an append-only prefix committed, then collapses on
+			// abort/finalize: the audit re-anchors #committedRows at the first
+			// divergent row, but flooring windowTop there would pin the editor
+			// near the top and leave blank rows underneath. Re-show the frame
+			// tail instead. The stale committed copy stays in native history;
+			// duplicating a few rows is preferable to a live editor gap —
+			// "duplication, never loss" is the ED3-unsafe fallback contract.
 			committedPrefixResliced = true;
 			windowTop = Math.max(0, frameLength - height);
 			chunkTo = windowTop;
@@ -2926,7 +2995,10 @@ export class TUI extends Container {
 		const cursorTrackingLineCount = hasVisibleOverlay ? Math.max(frame.length, windowTop + height) : frame.length;
 
 		const intent: RenderIntent = fullPaint
-			? { kind: "fullPaint", clearScrollback: replaceRequested || geometryRebuild ? !isMultiplexerSession() : false }
+			? {
+					kind: "fullPaint",
+					clearScrollback: divergenceRebuild || ((replaceRequested || geometryRebuild) && !isMultiplexerSession()),
+				}
 			: { kind: "update", chunkTo, windowTop };
 		this.#logRedraw(intent, frameLength, height);