@oh-my-pi/pi-tui 15.8.0 → 15.8.2

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## [Unreleased]
 
+## [15.8.2] - 2026-06-03
+
+### Added
+
+- Added `PI_NO_SYNC_OUTPUT=1` to disable DEC 2026 synchronized-output wrappers for terminals whose implementation is buggy or visually worse, while keeping the renderer's autowrap guards active during paints ([#1765](https://github.com/can1357/oh-my-pi/issues/1765)).
+
+### Fixed
+
+- Fixed terminal resizes that land in the same render frame as streamed output splicing a phantom blank row into native scrollback and offsetting every later row by one. A height shrink (or width change carrying an append) with content overflowing the viewport fell through to the differential emitter, whose scroll math is anchored to the pre-resize viewport top and hardware-cursor row — both invalidated by the terminal's own resize reflow. Geometry-changed frames now rebuild native history when the viewport is at (or possibly at) the bottom, and defer non-destructively for a reader confirmed scrolled into history.
+- Fixed Ghostty/kitty/Alacritty-style ED3-risk terminals freezing the prompt after a deferred shrink; focused keyboard input now uses the same explicit user-input viewport opt-in as autocomplete and can repaint immediately instead of waiting for a resize.
+- Deferred eager live scrollback rebuilds under WSL fronted by Windows Terminal (`WT_SESSION` present in a Linux environment) so foreground streaming no longer emits ED3 (`CSI 3 J`) and yanks a reader scrolled into Windows Terminal's host scrollback; deferred rewrites still reconcile at the next prompt-submit checkpoint ([#1610](https://github.com/can1357/oh-my-pi/issues/1610)).
+- Fixed tmux (and screen/zellij) pane history gaining a complete duplicate copy of the transcript every time a deferred offscreen edit was followed by another render. Multiplexer panes never receive a destructive scrollback clear, so the dirty-scrollback rebuild path only appended the full transcript on top of preserved pane history — repeatedly. Live frames inside multiplexers now keep repainting the viewport and leave history reconciliation to explicit checkpoints, which also removes the O(transcript) write amplification per frame.
+- Fixed tmux pane viewports corrupting and pane history duplicating when a resize coincides with rendering: a resize racing a streamed append reached the stale-anchor diff emitters (phantom rows in the pane), a forced render racing a resize replayed the whole transcript into preserved pane history, and the prompt-submit checkpoint did the same after any deferred offscreen edit. Geometry-changed frames inside multiplexers now repaint the viewport in place, and forced-render geometry replays plus checkpoint replays are disabled there — tmux reflows its own pane grid and its history cannot be cleared, only duplicated.
+- Fixed terminal resize events whose dimensions net out unchanged by render time (rapid SIGWINCH round trips during a window drag, coalesced into one 16ms frame) being invisible to the renderer. The terminal reflows its buffer on every resize event — rows move between the viewport and scrollback and can be evicted at the scrollback cap — so diffing against the pre-resize screen splices blank phantom rows into the viewport. The renderer now tracks the resize event itself, not just the dimension delta, and routes such frames through the geometry-change repaint/rebuild paths.
+- Fixed Termux terminal resizes (screen rotation or software-keyboard toggles) displacing or hiding output after the viewport height changed. Content-bearing resizes were routed to the differential emitter, whose scroll math is anchored to the pre-resize viewport, so appended rows landed too low; pure height changes were treated as no-ops, exposing blank rows that later appends could fill without growing native scrollback. Termux resizes now repaint or rebuild at the new geometry like every other non-multiplexer terminal.
+- Fixed the turn-end teardown frame freezing on ED3-risk terminals (Ghostty/kitty/Alacritty/iTerm2): disabling eager scrollback rebuild now takes effect only after the in-flight frame is classified, so the loader/status removal still paints instead of deferring and leaving a stale spinner until the next keystroke.
+- Fixed non-WT ConPTY terminals on Windows (Tabby, Hyper, VS Code, conhost) clearing scrollback and yanking the viewport to the top whenever streaming output or a prompt-submit rebuild arrived while the user was scrolled up. The kernel32 viewport probe describes the ConPTY pseudo-console buffer — which is pinned to the visible grid, invisible to host-UI scrollback — so it reported "at bottom" no matter where the user had scrolled, and the [#1635](https://github.com/can1357/oh-my-pi/issues/1635) fix only distrusted it under `WT_SESSION`, which Tabby and other ConPTY hosts never set. The probe is now removed entirely: every Windows host is treated as viewport-unobservable, live mutations defer destructive rebuilds (no `\x1b[3J`, no viewport movement), and native scrollback reconciles at the prompt-submit checkpoint where the Enter keystroke has already pinned the host viewport to the bottom ([#1746](https://github.com/can1357/oh-my-pi/issues/1746)).
+- Fixed emoji-presentation symbols (a default-text symbol followed by variation-selector-16 `U+FE0F`, e.g. `⚠️`, `ℹ️`, `❤️`, keycaps) measuring as 1 cell instead of 2 in the native width engine on macOS. The native scanner now keeps `UnicodeWidthStr` as the source of truth for multi-codepoint graphemes and applies only the local macOS Hangul Compatibility Jamo character-width delta, preserving VS16/keycap sequence widths without reintroducing jamo cursor drift.
+- Deferred eager live scrollback rebuilds on macOS Terminal.app and iTerm2 so assistant/tool streaming no longer emits ED3 (`CSI 3 J`) while their native viewport position is unobservable, preserving readers scrolled into terminal history ([#1300](https://github.com/can1357/oh-my-pi/issues/1300)).
+- Fixed width-shrink reflow leaving old-width rows in native history so later appends no longer undercount scrollback growth or duplicate wrapped content.
+- Fixed hiding overlays after terminal reflow so stale dialog rows are scrubbed from native scrollback on non-multiplexer terminals.
+
+### Removed
+
+- Removed `shouldTrustNativeViewportProbe` and `ProcessTerminal`'s kernel32 `GetConsoleScreenBufferInfo` viewport probe. No Windows environment can answer "is the user's viewport at the bottom" truthfully — under ConPTY (every modern host) the pseudo-console buffer is pinned to the visible grid so the probe always read "at bottom", and under legacy conhost the window tracks the output cursor rather than the buffer tail so it always read "scrolled up" — so the probe and its trust gate are gone; `ProcessTerminal` no longer implements the optional `Terminal.isNativeViewportAtBottom`.
+
+## [15.8.1] - 2026-06-02
+
+### Fixed
+
+- Deferred eager live scrollback rebuilds on VTE terminals so GNOME-style Linux terminals do not flash or erase readable scrollback during streaming ([#1719](https://github.com/can1357/oh-my-pi/issues/1719)).
+
 ## [15.8.0] - 2026-06-02
 
 ### Fixed

package/README.md

@@ -513,7 +513,7 @@ The TUI uses three rendering strategies:
 2. **Width Changed or Change Above Viewport**: Clear screen and full re-render
 3. **Normal Update**: Move cursor to first changed line, clear to end, render changed lines
 
-All updates are wrapped in **synchronized output** (`\x1b[?2026h` ... `\x1b[?2026l`) for atomic, flicker-free rendering.
+All updates are wrapped in **synchronized output** (`\x1b[?2026h` ... `\x1b[?2026l`) for atomic, flicker-free rendering unless `PI_NO_SYNC_OUTPUT=1` is set. The opt-out removes only the DEC 2026 wrapper; paint writes still guard terminal autowrap to avoid pending-wrap cursor artifacts.
 
 ## Terminal Interface
 

package/dist/types/terminal-capabilities.d.ts

@@ -16,7 +16,8 @@ export declare class TerminalInfo {
     readonly trueColor: boolean;
     readonly hyperlinks: boolean;
     readonly notifyProtocol: NotifyProtocol;
-    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol);
+    readonly eagerEraseScrollbackRisk: boolean;
+    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, eagerEraseScrollbackRisk?: boolean);
     isImageLine(line: string): boolean;
     formatNotification(message: string): string;
     sendNotification(message: string): void;
@@ -28,6 +29,29 @@ export declare function isNotificationSuppressed(): boolean;
  * Windows Terminal introduced SIXEL support in preview 1.22.
  */
 export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * Whether eager live-frame native scrollback rebuilds are unsafe when the
+ * terminal viewport position is unobservable.
+ *
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). On the
+ * terminals below, ED3 can disturb a reader parked in native scrollback during
+ * streaming: kitty/ghostty/alacritty/VTE clamp the scroll offset back to the
+ * active tail when saved lines are erased. WezTerm, macOS Terminal.app, and
+ * iTerm2 expose scrollback-only clears via ED3/terminfo E3; that still
+ * invalidates a reader's scrollback position during live streaming.
+ *
+ * Windows Terminal erases its host scrollback on ED3 and repositions the
+ * viewport against the shortened buffer, so a scrolled-up reader is yanked.
+ * Native win32 is excluded here because the renderer guards it with dedicated
+ * platform checks (the viewport position is never observable on Windows — see
+ * `Terminal.isNativeViewportAtBottom`); a `WT_SESSION` sighting on any other
+ * platform means the outer host is Windows Terminal fronting a WSL distro (WT
+ * propagates the variable into the Linux environment), where the same ED3
+ * yank applies. See #1610.
+ *
+ * Pure helper for tests and `TERMINAL` trait construction. See #1682 and #1719.
+ */
+export declare function detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 export declare const TERMINAL_ID: TerminalId;
 export declare const TERMINAL: TerminalInfo;
 /**

package/dist/types/terminal.d.ts

@@ -30,6 +30,32 @@ export interface Terminal {
     /**
      * Returns whether the native terminal viewport is at the scrollback tail when
      * the host exposes that state. `undefined` means the terminal cannot report it.
+     *
+     * `ProcessTerminal` deliberately does not implement this — no real terminal
+     * can answer it truthfully:
+     *
+     * - POSIX terminals expose no scrollback-position API at all.
+     * - Every modern Windows terminal host (Windows Terminal, VS Code, Tabby,
+     *   Hyper, Alacritty, WezTerm, JetBrains, …) fronts console apps through
+     *   ConPTY, where kernel32's `GetConsoleScreenBufferInfo` describes the
+     *   pseudo-console buffer. That buffer is pinned to the visible grid —
+     *   scrollback lives in the host UI, invisible to console APIs
+     *   (microsoft/terminal#10191) — so a probe reads "at bottom" no matter
+     *   where the user scrolled. Trusting it let streaming-time rebuilds emit
+     *   `\x1b[3J` and yank scrolled readers: #1635 (Windows Terminal), #1746
+     *   (Tabby and other ConPTY hosts). No env var distinguishes these hosts
+     *   (Tabby sets none), so trust cannot be conditional on the environment.
+     * - Legacy conhost (the only non-ConPTY host) keeps a real scrollback
+     *   buffer, but its window follows the output cursor: a probe comparing
+     *   `srWindow.Bottom` against `dwSize.Y - 1` reads "scrolled up" for a user
+     *   following live output until all ~9001 buffer rows fill, permanently
+     *   blocking checkpoint scrollback reconciliation.
+     *
+     * The renderer treats a missing implementation / `undefined` as "unknown":
+     * live mutations defer destructive rebuilds and reconcile native scrollback
+     * at explicit checkpoints (prompt submit), where the user's keystroke has
+     * already pinned the host viewport to the bottom. Only test terminals
+     * (xterm.js-backed) implement this with a real answer.
      */
     isNativeViewportAtBottom?(): boolean | undefined;
     /**
@@ -41,43 +67,6 @@ export interface Terminal {
     /** The last detected terminal appearance, or undefined if not yet known. */
     get appearance(): TerminalAppearance | undefined;
 }
-/**
- * Whether the native console viewport-position probe should be consulted.
- *
- * Returns `true` only on native Windows that is *not* fronted by Windows
- * Terminal. The kernel32 `GetConsoleScreenBufferInfo` API answers about the
- * ConPTY pseudo-console — which is always pinned to its tail — and not about
- * the user-visible scrollback in modern hosts. Treat any such host as
- * unreportable so the renderer falls back to the deferred-rebuild path.
- *
- * Pure helper for unit testing; the runtime call site reads `$env` /
- * `process.platform`. See #1635.
- */
-export declare function shouldTrustNativeViewportProbe(env?: {
-    WT_SESSION?: string | undefined;
-}, platform?: NodeJS.Platform): boolean;
-/**
- * Whether eager live-frame native scrollback rebuilds are unsafe for the
- * current POSIX terminal when its viewport position is unobservable.
- *
- * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). On the
- * terminals below, ED3 can disturb a reader parked in native scrollback during
- * streaming: kitty/ghostty/alacritty clamp the scroll offset back to the active
- * tail when saved lines are erased, and WezTerm is the reported POSIX host for
- * #1682. Defer only the eager streaming opt-in on these hosts; direct
- * user-input renders and explicit checkpoint rebuilds still pass their own
- * `allowUnknownViewportMutation` / `allowUnknownViewport` flags.
- *
- * Pure helper for unit testing; the runtime call site reads `$env` /
- * `process.platform`. See #1682.
- */
-export declare function terminalHasEagerEraseScrollbackRisk(env?: {
-    WEZTERM_PANE?: string | undefined;
-    KITTY_WINDOW_ID?: string | undefined;
-    GHOSTTY_RESOURCES_DIR?: string | undefined;
-    ALACRITTY_WINDOW_ID?: string | undefined;
-    TERM_PROGRAM?: string | undefined;
-}, platform?: NodeJS.Platform): boolean;
 /**
  * Real terminal using process.stdin/stdout
  */
@@ -87,20 +76,6 @@ export declare class ProcessTerminal implements Terminal {
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
     start(onInput: (data: string) => void, onResize: () => void): void;
-    /**
-     * Returns true when Windows' active console viewport is at the scrollback tail.
-     * POSIX terminals do not expose native scrollback position through a standard API.
-     *
-     * On native Windows running under Windows Terminal (the default modern
-     * host), the `kernel32` probe answers about the ConPTY pseudo-console — not
-     * the user-visible WT viewport — so it would always read "at bottom" while
-     * the user is scrolled up. Return `undefined` there so the renderer falls
-     * back to the POSIX-style deferred-rebuild path: streaming mutations stay
-     * non-destructive (no `\x1b[3J`), and the rebuild fires at the next prompt
-     * checkpoint via {@link TUI.refreshNativeScrollbackIfDirty} where the user
-     * is already pinned to the bottom by the editor keystroke. See #1635.
-     */
-    isNativeViewportAtBottom(): boolean | undefined;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     stop(): void;
     write(data: string): void;

package/dist/types/tui.d.ts

@@ -1,4 +1,4 @@
-import { type Terminal } from "./terminal";
+import type { Terminal } from "./terminal";
 import { visibleWidth } from "./utils";
 type InputListenerResult = {
     consume?: boolean;
@@ -172,10 +172,19 @@ export declare class TUI extends Container {
      * duplicate-free history and is meant for windows where output above the fold
      * is actively re-rendering — e.g. a tool whose result is still streaming and
      * re-laying-out rows that have already scrolled into history. A terminal that
-     * can report a *known*-scrolled viewport (Windows) still defers; only the
-     * unknown case is forced to rebuild. POSIX hosts known to disturb scrolled
-     * readers on xterm ED3 (`CSI 3 J`, erase saved lines) also defer the eager
-     * opt-in; checkpoint and direct user-input rebuilds are unaffected.
+     * reports a *known*-scrolled viewport still defers, as does native Windows
+     * (the viewport is never observable there and ConPTY hosts erase host
+     * scrollback on ED3 — #1635/#1746); only the unknown POSIX case is forced to
+     * rebuild. POSIX hosts known to disturb scrolled readers on xterm ED3
+     * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint and
+     * direct user-input rebuilds are unaffected.
+     *
+     * Disabling does not take effect until the next frame has been classified:
+     * the event batch that ends a foreground stream both removes its UI rows
+     * (loader/status teardown — a shrink) and clears this flag before the
+     * throttled render timer fires. If the flag dropped immediately, that
+     * teardown frame would hit the ED3-risk idle deferral and freeze on screen
+     * (stale spinner) until the next keystroke.
      */
     setEagerNativeScrollbackRebuild(enabled: boolean): void;
     setFocus(component: Component | null): void;

package/package.json

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

package/src/terminal-capabilities.ts

@@ -24,6 +24,7 @@ export class TerminalInfo {
 		public readonly trueColor: boolean,
 		public readonly hyperlinks: boolean,
 		public readonly notifyProtocol: NotifyProtocol = NotifyProtocol.Bell,
+		public readonly eagerEraseScrollbackRisk: boolean = false,
 	) {}
 
 	isImageLine(line: string): boolean {
@@ -91,6 +92,57 @@ export function isWindowsTerminalPreviewSixelSupported(
 	if (!version) return false;
 	return version.major > 1 || (version.major === 1 && version.minor >= 22);
 }
+
+/**
+ * Whether eager live-frame native scrollback rebuilds are unsafe when the
+ * terminal viewport position is unobservable.
+ *
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). On the
+ * terminals below, ED3 can disturb a reader parked in native scrollback during
+ * streaming: kitty/ghostty/alacritty/VTE clamp the scroll offset back to the
+ * active tail when saved lines are erased. WezTerm, macOS Terminal.app, and
+ * iTerm2 expose scrollback-only clears via ED3/terminfo E3; that still
+ * invalidates a reader's scrollback position during live streaming.
+ *
+ * Windows Terminal erases its host scrollback on ED3 and repositions the
+ * viewport against the shortened buffer, so a scrolled-up reader is yanked.
+ * Native win32 is excluded here because the renderer guards it with dedicated
+ * platform checks (the viewport position is never observable on Windows — see
+ * `Terminal.isNativeViewportAtBottom`); a `WT_SESSION` sighting on any other
+ * platform means the outer host is Windows Terminal fronting a WSL distro (WT
+ * propagates the variable into the Linux environment), where the same ED3
+ * yank applies. See #1610.
+ *
+ * Pure helper for tests and `TERMINAL` trait construction. See #1682 and #1719.
+ */
+export function detectTerminalEagerEraseScrollbackRisk(
+	env: NodeJS.ProcessEnv = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (platform === "win32") return false;
+	if (env.WT_SESSION) return true;
+	if (
+		env.WEZTERM_PANE ||
+		env.KITTY_WINDOW_ID ||
+		env.GHOSTTY_RESOURCES_DIR ||
+		env.ALACRITTY_WINDOW_ID ||
+		env.VTE_VERSION ||
+		env.ITERM_SESSION_ID
+	) {
+		return true;
+	}
+	switch (env.TERM_PROGRAM?.toLowerCase()) {
+		case "alacritty":
+		case "apple_terminal":
+		case "ghostty":
+		case "iterm.app":
+		case "kitty":
+		case "wezterm":
+			return true;
+		default:
+			return false;
+	}
+}
 function getFallbackImageProtocol(terminalId: TerminalId): ImageProtocol | null {
 	if (!process.stdout.isTTY) return null;
 	if (terminalId === "vscode" || terminalId === "alacritty") return null;
@@ -105,12 +157,12 @@ const KNOWN_TERMINALS = Object.freeze({
 	base: new TerminalInfo("base", null, false, false, NotifyProtocol.Bell),
 	trueColor: new TerminalInfo("trueColor", null, true, false, NotifyProtocol.Bell),
 	// Recognized terminals
-	kitty: new TerminalInfo("kitty", ImageProtocol.Kitty, true, true, NotifyProtocol.Osc99),
-	ghostty: new TerminalInfo("ghostty", ImageProtocol.Kitty, true, true, NotifyProtocol.Osc9),
-	wezterm: new TerminalInfo("wezterm", ImageProtocol.Kitty, true, true, NotifyProtocol.Osc9),
-	iterm2: new TerminalInfo("iterm2", ImageProtocol.Iterm2, true, true, NotifyProtocol.Osc9),
+	kitty: new TerminalInfo("kitty", ImageProtocol.Kitty, true, true, NotifyProtocol.Osc99, true),
+	ghostty: new TerminalInfo("ghostty", ImageProtocol.Kitty, true, true, NotifyProtocol.Osc9, true),
+	wezterm: new TerminalInfo("wezterm", ImageProtocol.Kitty, true, true, NotifyProtocol.Osc9, true),
+	iterm2: new TerminalInfo("iterm2", ImageProtocol.Iterm2, true, true, NotifyProtocol.Osc9, true),
 	vscode: new TerminalInfo("vscode", null, true, true, NotifyProtocol.Bell),
-	alacritty: new TerminalInfo("alacritty", null, true, true, NotifyProtocol.Bell),
+	alacritty: new TerminalInfo("alacritty", null, true, true, NotifyProtocol.Bell, true),
 });
 
 export const TERMINAL_ID: TerminalId = (() => {
@@ -155,26 +207,39 @@ export const TERMINAL_ID: TerminalId = (() => {
 })();
 
 export const TERMINAL = (() => {
-	const terminal = getTerminalInfo(TERMINAL_ID);
+	let resolved = getTerminalInfo(TERMINAL_ID);
+	const eagerEraseScrollbackRisk = detectTerminalEagerEraseScrollbackRisk(Bun.env, process.platform);
+	if (resolved.eagerEraseScrollbackRisk !== eagerEraseScrollbackRisk) {
+		resolved = new TerminalInfo(
+			resolved.id,
+			resolved.imageProtocol,
+			resolved.trueColor,
+			resolved.hyperlinks,
+			resolved.notifyProtocol,
+			eagerEraseScrollbackRisk,
+		);
+	}
+
 	const forcedImageProtocol = getForcedImageProtocol();
-	let resolved = terminal;
 	if (forcedImageProtocol !== undefined) {
 		resolved = new TerminalInfo(
-			terminal.id,
+			resolved.id,
 			forcedImageProtocol,
-			terminal.trueColor,
-			terminal.hyperlinks,
-			terminal.notifyProtocol,
+			resolved.trueColor,
+			resolved.hyperlinks,
+			resolved.notifyProtocol,
+			resolved.eagerEraseScrollbackRisk,
 		);
-	} else if (!terminal.imageProtocol) {
-		const fallbackImageProtocol = getFallbackImageProtocol(terminal.id);
+	} else if (!resolved.imageProtocol) {
+		const fallbackImageProtocol = getFallbackImageProtocol(resolved.id);
 		if (fallbackImageProtocol) {
 			resolved = new TerminalInfo(
-				terminal.id,
+				resolved.id,
 				fallbackImageProtocol,
-				terminal.trueColor,
-				terminal.hyperlinks,
-				terminal.notifyProtocol,
+				resolved.trueColor,
+				resolved.hyperlinks,
+				resolved.notifyProtocol,
+				resolved.eagerEraseScrollbackRisk,
 			);
 		}
 	}
@@ -188,6 +253,7 @@ export const TERMINAL = (() => {
 			resolved.trueColor,
 			false,
 			resolved.notifyProtocol,
+			resolved.eagerEraseScrollbackRisk,
 		);
 	}
 	return resolved;

package/src/terminal.ts

@@ -18,7 +18,6 @@ let activeTerminal: ProcessTerminal | null = null;
 let terminalEverStarted = false;
 
 const STD_INPUT_HANDLE = -10;
-const STD_OUTPUT_HANDLE = -11;
 const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
 /**
  * Emergency terminal restore - call this from signal/crash handlers
@@ -96,6 +95,32 @@ export interface Terminal {
 	/**
 	 * Returns whether the native terminal viewport is at the scrollback tail when
 	 * the host exposes that state. `undefined` means the terminal cannot report it.
+	 *
+	 * `ProcessTerminal` deliberately does not implement this — no real terminal
+	 * can answer it truthfully:
+	 *
+	 * - POSIX terminals expose no scrollback-position API at all.
+	 * - Every modern Windows terminal host (Windows Terminal, VS Code, Tabby,
+	 *   Hyper, Alacritty, WezTerm, JetBrains, …) fronts console apps through
+	 *   ConPTY, where kernel32's `GetConsoleScreenBufferInfo` describes the
+	 *   pseudo-console buffer. That buffer is pinned to the visible grid —
+	 *   scrollback lives in the host UI, invisible to console APIs
+	 *   (microsoft/terminal#10191) — so a probe reads "at bottom" no matter
+	 *   where the user scrolled. Trusting it let streaming-time rebuilds emit
+	 *   `\x1b[3J` and yank scrolled readers: #1635 (Windows Terminal), #1746
+	 *   (Tabby and other ConPTY hosts). No env var distinguishes these hosts
+	 *   (Tabby sets none), so trust cannot be conditional on the environment.
+	 * - Legacy conhost (the only non-ConPTY host) keeps a real scrollback
+	 *   buffer, but its window follows the output cursor: a probe comparing
+	 *   `srWindow.Bottom` against `dwSize.Y - 1` reads "scrolled up" for a user
+	 *   following live output until all ~9001 buffer rows fill, permanently
+	 *   blocking checkpoint scrollback reconciliation.
+	 *
+	 * The renderer treats a missing implementation / `undefined` as "unknown":
+	 * live mutations defer destructive rebuilds and reconcile native scrollback
+	 * at explicit checkpoints (prompt submit), where the user's keystroke has
+	 * already pinned the host viewport to the bottom. Only test terminals
+	 * (xterm.js-backed) implement this with a real answer.
 	 */
 	isNativeViewportAtBottom?(): boolean | undefined;
 
@@ -113,60 +138,6 @@ function isWindowsSubsystemForLinux(): boolean {
 	return process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
 }
 
-/**
- * Whether the native console viewport-position probe should be consulted.
- *
- * Returns `true` only on native Windows that is *not* fronted by Windows
- * Terminal. The kernel32 `GetConsoleScreenBufferInfo` API answers about the
- * ConPTY pseudo-console — which is always pinned to its tail — and not about
- * the user-visible scrollback in modern hosts. Treat any such host as
- * unreportable so the renderer falls back to the deferred-rebuild path.
- *
- * Pure helper for unit testing; the runtime call site reads `$env` /
- * `process.platform`. See #1635.
- */
-export function shouldTrustNativeViewportProbe(
-	env: { WT_SESSION?: string | undefined } = $env,
-	platform: NodeJS.Platform = process.platform,
-): boolean {
-	if (platform !== "win32") return false;
-	if (env.WT_SESSION) return false;
-	return true;
-}
-
-/**
- * Whether eager live-frame native scrollback rebuilds are unsafe for the
- * current POSIX terminal when its viewport position is unobservable.
- *
- * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). On the
- * terminals below, ED3 can disturb a reader parked in native scrollback during
- * streaming: kitty/ghostty/alacritty clamp the scroll offset back to the active
- * tail when saved lines are erased, and WezTerm is the reported POSIX host for
- * #1682. Defer only the eager streaming opt-in on these hosts; direct
- * user-input renders and explicit checkpoint rebuilds still pass their own
- * `allowUnknownViewportMutation` / `allowUnknownViewport` flags.
- *
- * Pure helper for unit testing; the runtime call site reads `$env` /
- * `process.platform`. See #1682.
- */
-export function terminalHasEagerEraseScrollbackRisk(
-	env: {
-		WEZTERM_PANE?: string | undefined;
-		KITTY_WINDOW_ID?: string | undefined;
-		GHOSTTY_RESOURCES_DIR?: string | undefined;
-		ALACRITTY_WINDOW_ID?: string | undefined;
-		TERM_PROGRAM?: string | undefined;
-	} = $env,
-	platform: NodeJS.Platform = process.platform,
-): boolean {
-	if (platform === "win32") return false;
-	if (env.WEZTERM_PANE || env.KITTY_WINDOW_ID || env.GHOSTTY_RESOURCES_DIR || env.ALACRITTY_WINDOW_ID) {
-		return true;
-	}
-	const termProgram = env.TERM_PROGRAM?.toLowerCase();
-	return termProgram === "ghostty";
-}
-
 /**
  * Real terminal using process.stdin/stdout
  */
@@ -265,42 +236,6 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
-	/**
-	 * Returns true when Windows' active console viewport is at the scrollback tail.
-	 * POSIX terminals do not expose native scrollback position through a standard API.
-	 *
-	 * On native Windows running under Windows Terminal (the default modern
-	 * host), the `kernel32` probe answers about the ConPTY pseudo-console — not
-	 * the user-visible WT viewport — so it would always read "at bottom" while
-	 * the user is scrolled up. Return `undefined` there so the renderer falls
-	 * back to the POSIX-style deferred-rebuild path: streaming mutations stay
-	 * non-destructive (no `\x1b[3J`), and the rebuild fires at the next prompt
-	 * checkpoint via {@link TUI.refreshNativeScrollbackIfDirty} where the user
-	 * is already pinned to the bottom by the editor keystroke. See #1635.
-	 */
-	isNativeViewportAtBottom(): boolean | undefined {
-		if (!shouldTrustNativeViewportProbe()) return undefined;
-		try {
-			const kernel32 = dlopen("kernel32.dll", {
-				GetStdHandle: { args: [FFIType.i32], returns: FFIType.ptr },
-				GetConsoleScreenBufferInfo: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.bool },
-			});
-			try {
-				const handle = kernel32.symbols.GetStdHandle(STD_OUTPUT_HANDLE);
-				const info = new Uint8Array(22);
-				const infoPtr = ptr(info);
-				if (!infoPtr || !kernel32.symbols.GetConsoleScreenBufferInfo(handle, infoPtr)) return undefined;
-				const viewBottom = new DataView(info.buffer, info.byteOffset, info.byteLength).getInt16(16, true);
-				const bufferHeight = new DataView(info.buffer, info.byteOffset, info.byteLength).getInt16(2, true);
-				return viewBottom >= bufferHeight - 1;
-			} finally {
-				kernel32.close();
-			}
-		} catch {
-			return undefined;
-		}
-	}
-
 	/**
 	 * On Windows, add ENABLE_VIRTUAL_TERMINAL_INPUT to the stdin console mode
 	 * so modified keys (for example Shift+Tab) arrive as VT escape sequences.

package/src/tui.ts

@@ -6,7 +6,7 @@ import * as path from "node:path";
 import { performance } from "node:perf_hooks";
 import { $flag, getDebugLogPath } from "@oh-my-pi/pi-utils";
 import { isKeyRelease, matchesKey } from "./keys";
-import { type Terminal, terminalHasEagerEraseScrollbackRisk } from "./terminal";
+import type { Terminal } from "./terminal";
 import { ImageProtocol, setCellDimensions, setTerminalImageProtocol, TERMINAL } from "./terminal-capabilities";
 import {
 	Ellipsis,
@@ -31,11 +31,22 @@ const LINE_TERMINATOR = "\x1b[0m\x1b]8;;\x07";
 // row under a visible cursor. Paint writes also disable terminal autowrap:
 // several terminals keep a "pending wrap" flag after an exact-width row, so a
 // following cursor move can first wrap to the next row and produce staircase
-// trails. The TUI emits explicit CRLFs and restores autowrap before leaving
-// synchronized output mode.
+// trails. The TUI emits explicit CRLFs and restores autowrap before leaving the
+// paint. Synchronized output can be disabled for terminals with broken DEC 2026
+// implementations; autowrap discipline stays on either way.
 const HIDE_CURSOR = "\x1b[?25l";
-const PAINT_BEGIN = `${HIDE_CURSOR}\x1b[?2026h\x1b[?7l`;
-const PAINT_END = "\x1b[?7h\x1b[?2026l";
+const SYNC_OUTPUT_BEGIN = "\x1b[?2026h";
+const SYNC_OUTPUT_END = "\x1b[?2026l";
+const DISABLE_AUTOWRAP = "\x1b[?7l";
+const ENABLE_AUTOWRAP = "\x1b[?7h";
+const PAINT_BEGIN = `${HIDE_CURSOR}${SYNC_OUTPUT_BEGIN}${DISABLE_AUTOWRAP}`;
+const PAINT_END = `${ENABLE_AUTOWRAP}${SYNC_OUTPUT_END}`;
+const PAINT_BEGIN_NO_SYNC = `${HIDE_CURSOR}${DISABLE_AUTOWRAP}`;
+const PAINT_END_NO_SYNC = ENABLE_AUTOWRAP;
+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 = "";
 
 type InputListenerResult = { consume?: boolean; data?: string } | undefined;
 type InputListener = (data: string) => InputListenerResult;
@@ -157,10 +168,6 @@ function parseSizeValue(value: SizeValue | undefined, referenceSize: number): nu
 	return undefined;
 }
 
-function isTermuxSession(): boolean {
-	return Boolean(process.env.TERMUX_VERSION);
-}
-
 /** 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);
@@ -316,6 +323,11 @@ export class TUI extends Container {
 	#sixelProbeUnsubscribe?: () => void;
 	#showHardwareCursor = $flag("PI_HARDWARE_CURSOR");
 	#clearOnShrink = $flag("PI_CLEAR_ON_SHRINK"); // Clear empty rows when content shrinks (default: off)
+	#synchronizedOutputEnabled = !$flag("PI_NO_SYNC_OUTPUT");
+	#paintBeginSequence = this.#synchronizedOutputEnabled ? PAINT_BEGIN : PAINT_BEGIN_NO_SYNC;
+	#paintEndSequence = this.#synchronizedOutputEnabled ? PAINT_END : PAINT_END_NO_SYNC;
+	#cursorBeginSequence = this.#synchronizedOutputEnabled ? CURSOR_BEGIN : CURSOR_BEGIN_NO_SYNC;
+	#cursorEndSequence = this.#synchronizedOutputEnabled ? CURSOR_END : CURSOR_END_NO_SYNC;
 	#maxLinesRendered = 0; // Line count from last render, used for viewport calculation
 	// Highest count of content rows currently sitting in terminal scrollback
 	// above the visible viewport. Used to detect shrink-across-viewport-boundary
@@ -332,7 +344,20 @@ export class TUI extends Container {
 	#forceViewportRepaintOnNextRender = false;
 	#allowUnknownViewportMutationOnNextRender = 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
+	// eagerly (see setEagerNativeScrollbackRebuild).
+	#eagerNativeScrollbackRebuildDisablePending = false;
+	#previousVisibleOverlayComponents: Component[] = [];
+	#visibleOverlayComponentsThisRender: Component[] = [];
 	#hasEverRendered = false;
+	// 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
+	// budget): the terminal reflowed its buffer on each event, moving rows
+	// between the viewport and scrollback, so the previous frame no longer
+	// describes the screen. Tracking only the dimension delta misses this.
+	#resizeEventPending = false;
 	#stopped = false;
 
 	// Overlay stack for modal components rendered on top of base content
@@ -387,13 +412,28 @@ export class TUI extends Container {
 	 * duplicate-free history and is meant for windows where output above the fold
 	 * is actively re-rendering — e.g. a tool whose result is still streaming and
 	 * re-laying-out rows that have already scrolled into history. A terminal that
-	 * can report a *known*-scrolled viewport (Windows) still defers; only the
-	 * unknown case is forced to rebuild. POSIX hosts known to disturb scrolled
-	 * readers on xterm ED3 (`CSI 3 J`, erase saved lines) also defer the eager
-	 * opt-in; checkpoint and direct user-input rebuilds are unaffected.
+	 * reports a *known*-scrolled viewport still defers, as does native Windows
+	 * (the viewport is never observable there and ConPTY hosts erase host
+	 * scrollback on ED3 — #1635/#1746); only the unknown POSIX case is forced to
+	 * rebuild. POSIX hosts known to disturb scrolled readers on xterm ED3
+	 * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint and
+	 * direct user-input rebuilds are unaffected.
+	 *
+	 * Disabling does not take effect until the next frame has been classified:
+	 * the event batch that ends a foreground stream both removes its UI rows
+	 * (loader/status teardown — a shrink) and clears this flag before the
+	 * throttled render timer fires. If the flag dropped immediately, that
+	 * teardown frame would hit the ED3-risk idle deferral and freeze on screen
+	 * (stale spinner) until the next keystroke.
 	 */
 	setEagerNativeScrollbackRebuild(enabled: boolean): void {
-		this.#eagerNativeScrollbackRebuild = enabled;
+		if (enabled) {
+			this.#eagerNativeScrollbackRebuild = true;
+			this.#eagerNativeScrollbackRebuildDisablePending = false;
+			return;
+		}
+		if (!this.#eagerNativeScrollbackRebuild) return;
+		this.#eagerNativeScrollbackRebuildDisablePending = true;
 	}
 
 	setFocus(component: Component | null): void {
@@ -496,6 +536,14 @@ export class TUI extends Container {
 		return undefined;
 	}
 
+	#overlayVisibilityReduced(visibleComponents: readonly Component[]): boolean {
+		if (this.#previousVisibleOverlayComponents.length === 0) return false;
+		for (const component of this.#previousVisibleOverlayComponents) {
+			if (!visibleComponents.includes(component)) return true;
+		}
+		return false;
+	}
+
 	override invalidate(): void {
 		super.invalidate();
 		for (const overlay of this.overlayStack) overlay.component.invalidate?.();
@@ -505,7 +553,10 @@ export class TUI extends Container {
 		this.#stopped = false;
 		this.terminal.start(
 			data => this.#handleInput(data),
-			() => this.requestRender(),
+			() => {
+				this.#resizeEventPending = true;
+				this.requestRender();
+			},
 		);
 		this.terminal.hideCursor();
 		this.#querySixelSupport();
@@ -696,6 +747,14 @@ export class TUI extends Container {
 	 */
 	refreshNativeScrollbackIfDirty(options?: NativeScrollbackRefreshOptions): boolean {
 		if (!this.#nativeScrollbackDirty || this.#stopped) return false;
+		// Multiplexer panes preserve their own history and never receive a
+		// destructive clear, so a checkpoint "replay" cannot reconcile anything —
+		// it would only append a duplicate copy of the transcript to pane
+		// history. Drop the dirty flag; there is nothing actionable behind it.
+		if (isMultiplexerSession()) {
+			this.#clearNativeScrollbackDirty();
+			return false;
+		}
 		const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
 		if (
 			!this.#canReplayNativeScrollbackAtCheckpoint(nativeViewportAtBottom, options?.allowUnknownViewport === true)
@@ -734,8 +793,12 @@ export class TUI extends Container {
 		const geometryChanged =
 			(this.#previousWidth > 0 && this.#previousWidth !== this.terminal.columns) ||
 			(this.#previousHeight > 0 && this.#previousHeight !== this.terminal.rows);
+		// A geometry replay rewraps clearable native scrollback at the new size.
+		// Inside a multiplexer the pane reflows its own history and a replay only
+		// duplicates it, so never promote forced renders to sessionReplace there.
 		const replayGeometry =
 			geometryChanged &&
+			!isMultiplexerSession() &&
 			this.#canReplayNativeScrollbackAtCheckpoint(this.#readNativeViewportAtBottom(), allowUnknownViewportMutation);
 		this.#clearScrollbackOnNextRender ||= clearScrollback || replayGeometry;
 		this.#forceViewportRepaintOnNextRender = true;
@@ -816,7 +879,7 @@ export class TUI extends Container {
 				return;
 			}
 			this.#focusedComponent.handleInput(data);
-			this.requestRender();
+			this.requestRender(false, { allowUnknownViewportMutation: true });
 		}
 	}
 
@@ -1173,10 +1236,15 @@ export class TUI extends Container {
 
 		// 1. Compose the frame.
 		let baseLines = this.render(width);
-		let lines = baseLines;
-		if (this.overlayStack.length > 0) {
-			lines = this.#compositeOverlays(baseLines, width, height);
+		const visibleOverlayComponents: Component[] = [];
+		if (this.overlayStack.length > 0 || this.#previousVisibleOverlayComponents.length > 0) {
+			for (const entry of this.overlayStack) {
+				if (this.#isOverlayVisible(entry)) visibleOverlayComponents.push(entry.component);
+			}
 		}
+		this.#visibleOverlayComponentsThisRender = visibleOverlayComponents;
+		const overlayVisibilityReduced = this.#overlayVisibilityReduced(visibleOverlayComponents);
+		let lines = visibleOverlayComponents.length > 0 ? this.#compositeOverlays(baseLines, width, height) : baseLines;
 		const cursorPos = this.#extractCursorPosition(lines, height);
 		lines = this.#fitLinesToWidth(this.#applyLineResets(lines), width);
 		if (lines !== baseLines) {
@@ -1187,9 +1255,17 @@ export class TUI extends Container {
 		// 2. Capture transition + pre-render state before any emitter runs.
 		const prevViewportTop = this.#viewportTopRow;
 		const prevHardwareCursorRow = this.#hardwareCursorRow;
+		const resizeEventOccurred = this.#resizeEventPending;
+		this.#resizeEventPending = false;
 		const widthChanged = this.#previousWidth > 0 && this.#previousWidth !== width;
-		const heightChanged = this.#previousHeight > 0 && this.#previousHeight !== height;
-		const eagerRebuildAllowed = this.#eagerNativeScrollbackRebuild && !terminalHasEagerEraseScrollbackRisk();
+		// A resize event with net-unchanged dimensions still reflowed the terminal
+		// buffer; classify it as a height change so the geometry branches repaint
+		// or rebuild instead of diffing against a screen that no longer exists.
+		const heightChanged =
+			(this.#previousHeight > 0 && this.#previousHeight !== height) ||
+			(resizeEventOccurred && this.#previousHeight > 0);
+		const eagerEraseScrollbackRisk = process.platform !== "win32" && TERMINAL.eagerEraseScrollbackRisk;
+		const eagerRebuildAllowed = this.#eagerNativeScrollbackRebuild && !eagerEraseScrollbackRisk;
 		const allowUnknownViewportMutation = this.#allowUnknownViewportMutationOnNextRender || eagerRebuildAllowed;
 		this.#allowUnknownViewportMutationOnNextRender = false;
 
@@ -1200,8 +1276,14 @@ export class TUI extends Container {
 			heightChanged,
 			prevViewportTop,
 			height,
+			visibleOverlayComponents.length > 0,
+			overlayVisibilityReduced,
 			allowUnknownViewportMutation,
 		);
+		if (this.#eagerNativeScrollbackRebuildDisablePending) {
+			this.#eagerNativeScrollbackRebuildDisablePending = false;
+			this.#eagerNativeScrollbackRebuild = false;
+		}
 		this.#logRedraw(intent, lines.length, height);
 		// 4. Execute.
 		switch (intent.kind) {
@@ -1287,6 +1369,8 @@ export class TUI extends Container {
 		heightChanged: boolean,
 		prevViewportTop: number,
 		height: number,
+		hasVisibleOverlay: boolean,
+		overlayVisibilityReduced: boolean,
 		allowUnknownViewportMutation: boolean,
 	): RenderIntent {
 		// Initial paint after start(): scrollback must keep its prior shell
@@ -1298,10 +1382,20 @@ export class TUI extends Container {
 		if (this.#clearScrollbackOnNextRender) return { kind: "sessionReplace" };
 
 		const forceViewportRepaint = this.#forceViewportRepaintOnNextRender;
-		if (this.hasOverlay()) {
+		const eagerEraseScrollbackRisk = process.platform !== "win32" && TERMINAL.eagerEraseScrollbackRisk;
+		if (overlayVisibilityReduced && !isMultiplexerSession()) {
+			return hasVisibleOverlay ? { kind: "overlayRebuild" } : { kind: "historyRebuild" };
+		}
+		if (hasVisibleOverlay) {
 			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+			// Multiplexer panes never get a destructive scrollback clear
+			// (clearScrollback is forced off inside them), so a dirty-scrollback
+			// "rebuild" would only append a full duplicate copy of the transcript
+			// to pane history on every dirty frame. Keep repainting the viewport
+			// and leave reconciliation to explicit checkpoints.
 			if (
 				this.#nativeScrollbackDirty &&
+				!isMultiplexerSession() &&
 				this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, allowUnknownViewportMutation)
 			) {
 				return { kind: "overlayRebuild" };
@@ -1310,7 +1404,11 @@ export class TUI extends Container {
 			return { kind: "viewportRepaint" };
 		}
 
-		if (this.#nativeScrollbackDirty && this.#nativeViewportIsAtBottom(this.#readNativeViewportAtBottom())) {
+		if (
+			this.#nativeScrollbackDirty &&
+			!isMultiplexerSession() &&
+			this.#canRebuildNativeScrollbackLive(this.#readNativeViewportAtBottom(), allowUnknownViewportMutation)
+		) {
 			return { kind: "historyRebuild" };
 		}
 
@@ -1359,29 +1457,64 @@ export class TUI extends Container {
 				return { kind: "viewportRepaint" };
 			}
 			// The shrunk transcript still overflows the viewport. A plain viewport
-			// repaint would re-emit the rows between the new and old viewport tops on top
-			// of the copies the terminal already kept in native scrollback; `deferredShrink`
-			// pads to the previous row count so no committed row is re-emitted, and the
-			// next checkpoint rebuild cleans up.
-			//
-			// That deferral only carries real content when `newLines.length` reaches the
-			// padded viewport top (`previousLines.length - height`) — otherwise every row
-			// the padded repaint draws is past the end of `newLines` and renders blank,
-			// hiding the prompt until the next checkpoint. This can happen even when
-			// `scrollbackHighWater` is far below `previousLines.length - height`, because
-			// prior unknown-POSIX viewport repaints commit longer logical frames without
-			// moving the native scrollback boundary. For a shrink that large a blank,
-			// uninteractable viewport is the greater evil, so yank with `historyRebuild`.
-			// Real win32 unknown probes defer as scrolled above and never reach this; the
-			// yank only lands on non-win32 hosts whose probe is genuinely unavailable.
+			// repaint can duplicate stale rows in native scrollback, while a destructive
+			// history rebuild (`CSI 3 J`) can yank readers in ED3-risk terminals whose
+			// viewport position is unobservable. Outside foreground-tool streaming,
+			// keep the old visible history frozen and reconcile at the next explicit
+			// checkpoint. During a foreground tool, a literal no-op freezes the live
+			// command/status view; continue with a non-destructive repaint path instead.
+			if (nativeViewportAtBottom === undefined && eagerEraseScrollbackRisk && !this.#eagerNativeScrollbackRebuild) {
+				this.#markNativeScrollbackDirty();
+				return { kind: "deferredMutation" };
+			}
+
+			// If the shrink still leaves enough rows to cover the previous viewport
+			// top, `deferredShrink` can repaint that stable slice without committing
+			// duplicate rows to native scrollback. When the shrink jumps above that
+			// padded viewport top, `deferredShrink` would draw only blank padding and
+			// hide the live prompt. Ordinary POSIX terminals rebuild history in that
+			// case; ED3-risk foreground-tool frames use a non-destructive viewport
+			// repaint and leave stale scrollback queued for the next checkpoint.
 			const paddedViewportTop = Math.max(0, this.#previousLines.length - height);
 			if (newLines.length <= paddedViewportTop) {
+				if (nativeViewportAtBottom === undefined && eagerEraseScrollbackRisk) {
+					this.#markNativeScrollbackDirty();
+					return { kind: "viewportRepaint" };
+				}
 				return { kind: "historyRebuild" };
 			}
 			this.#markNativeScrollbackDirty();
 			return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
 		}
 
+		// Multiplexer panes do not give us a safe native-history rebuild path, but
+		// a shrink can still move the logical viewport upward (for example hiding an
+		// overlay that extended past the base frame). A row-diff from the old
+		// viewport top would only clear the old suffix and leave the newly exposed
+		// base rows stale/blank, so repaint the live viewport in place.
+		if (
+			isMultiplexerSession() &&
+			diff.firstChanged !== -1 &&
+			newLines.length < this.#previousLines.length &&
+			naturalViewportTop !== prevViewportTop
+		) {
+			return { kind: "viewportRepaint" };
+		}
+
+		// Direct-input shrink can also move the natural viewport upward even when
+		// no stale high-water scrollback is involved (for example slash autocomplete
+		// filtering from many rows to a few). The diff emitter is anchored to the
+		// previous viewport top and would only clear the old suffix, hiding the
+		// editor above the live window.
+		if (
+			allowUnknownViewportMutation &&
+			diff.firstChanged !== -1 &&
+			newLines.length < this.#previousLines.length &&
+			naturalViewportTop !== prevViewportTop
+		) {
+			return { kind: "viewportRepaint" };
+		}
+
 		const suppressSuffixScroll = this.#suppressNextSuffixScroll;
 		this.#suppressNextSuffixScroll = false;
 		if (
@@ -1418,27 +1551,29 @@ export class TUI extends Container {
 			// viewport, but it must keep the existing diff basis so later coalesced
 			// content mutations can still update native scrollback correctly.
 			if (forceViewportRepaint) return { kind: "viewportRepaint" };
-			// Width change still alters wrapping geometry; height change shifts the
-			// visible window. Either needs a repaint (outside hostile environments).
+			// Width changes alter wrapping geometry; height changes expose or hide
+			// viewport rows. Repaint any non-multiplexer resize, including Termux
+			// software-keyboard toggles: leaving the new rows blank creates phantom
+			// viewport space that later appends can fill without growing scrollback.
 			if (widthChanged) return { kind: "viewportRepaint" };
-			if (heightChanged && !isTermuxSession() && !isMultiplexerSession()) return { kind: "viewportRepaint" };
+			if (heightChanged && !isMultiplexerSession()) return { kind: "viewportRepaint" };
 			return { kind: "noop" };
 		}
 
-		// Width changes rewrap the whole transcript. An offscreen edit leaves
-		// native history at the old width, so rebuild it now — the terminal already
-		// reflowed and the user is at the terminal to resize. Pure appends fall
-		// through to the diff path so the append handler scrolls them into history.
+		// Width changes rewrap native history. Any non-append content change must
+		// rebuild the committed transcript when the viewport is safe; a viewport
+		// repaint can leave old-width wrapped fragments above the live frame, and
+		// later appends then splice new rows onto stale history.
 		if (widthChanged) {
-			if (diff.firstChanged < prevViewportTop) {
-				if (this.#nativeViewportIsScrolled(this.#readNativeViewportAtBottom(), allowUnknownViewportMutation)) {
+			const pureAppend = diff.appendedLines && diff.firstChanged === this.#previousLines.length;
+			if (!pureAppend) {
+				const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+				if (this.#nativeViewportIsScrolled(nativeViewportAtBottom, allowUnknownViewportMutation)) {
 					this.#markNativeScrollbackDirty();
 					return { kind: "viewportRepaint" };
 				}
-				return { kind: "historyRebuild" };
+				return isMultiplexerSession() ? { kind: "viewportRepaint" } : { kind: "historyRebuild" };
 			}
-			const pureAppend = diff.appendedLines && diff.firstChanged === this.#previousLines.length;
-			if (!pureAppend) return { kind: "viewportRepaint" };
 		}
 
 		const contentGrew = newLines.length > this.#previousLines.length;
@@ -1505,10 +1640,13 @@ export class TUI extends Container {
 			}
 		}
 
-		// Height changes shift the visible window. Repaint when content didn't
-		// grow, but skip in Termux (software keyboard toggles height) and inside
-		// multiplexers (panes manage their own redraws).
-		if (heightChanged && !contentGrew && !isTermuxSession() && !isMultiplexerSession()) {
+		// Height changes shift the visible window. Repaint when content didn't grow,
+		// but skip inside multiplexers (panes manage their own redraws — handled by
+		// the multiplexer geometry branch below). Termux is deliberately included:
+		// a resize with no content change still exposes or hides viewport rows, and
+		// leaving those rows blank lets later appends fill phantom space instead of
+		// growing native scrollback.
+		if (heightChanged && !contentGrew && !isMultiplexerSession()) {
 			return { kind: "viewportRepaint" };
 		}
 
@@ -1519,7 +1657,47 @@ export class TUI extends Container {
 		// tail lands `height`-delta rows too low. With no overflow there is no
 		// native scrollback to preserve, so repaint the viewport at the new
 		// geometry. (Height changes with overflow keep the existing deferral.)
-		if (heightChanged && newLines.length <= height && !isTermuxSession() && !isMultiplexerSession()) {
+		if (heightChanged && newLines.length <= height && !isMultiplexerSession()) {
+			return { kind: "viewportRepaint" };
+		}
+
+		// Any other geometry change (height shrink with content overflowing the
+		// viewport, or a width change carrying a pure append) must not reach the
+		// anchor-relative diff/append emitters below either. The terminal reflowed
+		// its own buffer on resize — a height shrink moves committed rows between
+		// scrollback and viewport — so the previous frame's viewport-top and
+		// hardware-cursor anchors no longer describe the screen, and scrolling
+		// relative to them splices phantom blank rows into native scrollback
+		// (stress repro: darwin-normal-large seed 0x5eed1234 op 1062, a
+		// resizeHeight coalesced with a streamed append). A resize is an explicit
+		// user action, so rebuilding history at the new geometry is the
+		// established tradeoff (see the width-change branch above); a reader
+		// confirmed scrolled into history is still never yanked. Termux is included
+		// (it is not a multiplexer and ED3 clears its own scrollback): a content-
+		// bearing resize must not reach the stale-anchor emitters below.
+		if ((heightChanged || widthChanged) && !isMultiplexerSession()) {
+			// No overflow → nothing of ours in native scrollback to reconcile; an
+			// in-place repaint also keeps preexisting shell scrollback intact.
+			if (newLines.length <= height) {
+				return { kind: "viewportRepaint" };
+			}
+			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+			if (this.#nativeViewportIsKnownScrolled(nativeViewportAtBottom)) {
+				this.#markNativeScrollbackDirty();
+				return { kind: "viewportRepaint" };
+			}
+			return { kind: "historyRebuild" };
+		}
+
+		// The same geometry hazard inside a multiplexer: tmux reflows the pane
+		// grid (visible rows AND pane history) on resize, so the anchor-relative
+		// diff/append emitters below are equally invalid — but a destructive
+		// rebuild is impossible there (pane history cannot be cleared; a full
+		// replay only appends a duplicate transcript copy). Repaint the visible
+		// window in place at the new geometry. Applies even under Termux: a
+		// repaint per keyboard-toggle resize is cheaper than splicing phantom
+		// rows into the pane.
+		if ((heightChanged || widthChanged) && isMultiplexerSession()) {
 			return { kind: "viewportRepaint" };
 		}
 
@@ -1635,7 +1813,12 @@ export class TUI extends Container {
 	}
 
 	#readNativeViewportAtBottom(): boolean | undefined {
-		return this.terminal.isNativeViewportAtBottom?.();
+		// A stale positive is destructive: live history rebuilds clear native
+		// scrollback. Require two consecutive at-bottom probes before trusting it.
+		const first = this.terminal.isNativeViewportAtBottom?.();
+		if (first !== true) return first;
+		const second = this.terminal.isNativeViewportAtBottom?.();
+		return second === true ? true : second;
 	}
 
 	#nativeViewportIsScrolled(
@@ -1652,10 +1835,6 @@ export class TUI extends Container {
 		return nativeViewportAtBottom === false;
 	}
 
-	#nativeViewportIsAtBottom(nativeViewportAtBottom: boolean | undefined): boolean {
-		return nativeViewportAtBottom === true;
-	}
-
 	#canReplayNativeScrollbackAtCheckpoint(
 		nativeViewportAtBottom: boolean | undefined,
 		allowUnknownViewport: boolean,
@@ -1680,15 +1859,18 @@ export class TUI extends Container {
 	 * this, every offscreen transcript edit while streaming wiped scrollback and
 	 * yanked a scrolled-up reader out of their current context.
 	 * `allowUnknownViewportMutation` (autocomplete/IME) opts directly
-	 * user-driven frames back into the rebuild. Unlike the checkpoint predicate
-	 * this carries no `process.platform` optimism — resize and checkpoint replays
-	 * keep using that one.
+	 * user-driven POSIX frames back into the rebuild. Native Windows and Windows
+	 * Terminal still cannot trust an unknown probe during live rendering — ConPTY
+	 * may be fronting host scrollback we cannot observe — so they keep deferring.
 	 */
 	#canRebuildNativeScrollbackLive(
 		nativeViewportAtBottom: boolean | undefined,
 		allowUnknownViewportMutation: boolean,
 	): boolean {
-		return nativeViewportAtBottom === true || (nativeViewportAtBottom === undefined && allowUnknownViewportMutation);
+		return (
+			nativeViewportAtBottom === true ||
+			(nativeViewportAtBottom === undefined && allowUnknownViewportMutation && process.platform !== "win32")
+		);
 	}
 
 	#padDeferredShrinkLines(lines: string[], paddedLength: number): string[] {
@@ -1720,8 +1902,10 @@ export class TUI extends Container {
 	 * Single state-transition point. Every emitter calls this exactly once at
 	 * the end so cursor/viewport/scrollback accounting stays consistent.
 	 */
+
 	#commit(lines: string[], width: number, height: number, viewportTop: number, hardwareCursorRow: number): void {
 		this.#previousLines = lines;
+		this.#previousVisibleOverlayComponents = this.#visibleOverlayComponentsThisRender;
 		this.#forceViewportRepaintOnNextRender = false;
 		this.#previousWidth = width;
 		this.#previousHeight = height;
@@ -1742,7 +1926,7 @@ export class TUI extends Container {
 		options: { clearViewport: boolean; clearScrollback: boolean },
 	): void {
 		this.#fullRedrawCount += 1;
-		let buffer = PAINT_BEGIN;
+		let buffer = this.#paintBeginSequence;
 		if (options.clearViewport) {
 			buffer += options.clearScrollback ? "\x1b[2J\x1b[H\x1b[3J" : "\x1b[2J\x1b[H";
 		}
@@ -1753,7 +1937,7 @@ export class TUI extends Container {
 		const finalRow = Math.max(0, lines.length - 1);
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, finalRow);
 		buffer += seq;
-		buffer += PAINT_END;
+		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 
 		this.#maxLinesRendered = options.clearViewport ? lines.length : Math.max(this.#maxLinesRendered, lines.length);
@@ -1780,7 +1964,7 @@ export class TUI extends Container {
 	): void {
 		this.#fullRedrawCount += 1;
 		const viewportTop = Math.max(0, lines.length - height);
-		let buffer = `${PAINT_BEGIN}\x1b[H`;
+		let buffer = `${this.#paintBeginSequence}\x1b[H`;
 		for (let screenRow = 0; screenRow < height; screenRow++) {
 			if (screenRow > 0) buffer += "\r\n";
 			buffer += "\x1b[2K";
@@ -1797,7 +1981,7 @@ export class TUI extends Container {
 		const finalRow = viewportTop + height - 1;
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, finalRow);
 		buffer += seq;
-		buffer += PAINT_END;
+		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 
 		this.#maxLinesRendered = lines.length;
@@ -1819,7 +2003,7 @@ export class TUI extends Container {
 		prevHardwareCursorRow: number,
 	): void {
 		if (start >= lines.length) return;
-		let buffer = PAINT_BEGIN;
+		let buffer = this.#paintBeginSequence;
 		// Clamp tracked cursor to the visible viewport bottom — terminals clamp
 		// on resize, so a prior frame may have committed a row that no longer
 		// exists. Without this the scroll math points outside the viewport.
@@ -1831,7 +2015,7 @@ export class TUI extends Container {
 			buffer += "\r\n";
 			buffer += this.#fitLineToWidth(lines[i], width);
 		}
-		buffer += PAINT_END;
+		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 		const pushedNow = Math.max(0, lines.length - height);
 		if (pushedNow > this.#scrollbackHighWater) {
@@ -1867,7 +2051,7 @@ export class TUI extends Container {
 		const viewportTop = Math.max(0, this.#maxLinesRendered - height);
 		const targetRow = Math.max(0, lines.length - 1);
 
-		let buffer = PAINT_BEGIN;
+		let buffer = this.#paintBeginSequence;
 
 		const clampedCursor = Math.min(prevHardwareCursorRow, prevViewportTop + height - 1);
 		const currentScreenRow = clampedCursor - prevViewportTop;
@@ -1892,7 +2076,7 @@ export class TUI extends Container {
 
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, targetRow);
 		buffer += seq;
-		buffer += PAINT_END;
+		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 
 		this.#maxLinesRendered = lines.length;
@@ -1926,7 +2110,7 @@ export class TUI extends Container {
 		const appendStart = appendedLines && firstChanged === this.#previousLines.length && firstChanged > 0;
 		const moveTargetRow = appendStart ? firstChanged - 1 : firstChanged;
 
-		let buffer = PAINT_BEGIN;
+		let buffer = this.#paintBeginSequence;
 
 		// Scroll-down branch: target row is past the bottom of the previous
 		// viewport (a pure append). Emit `\r\n`s so the terminal pushes the
@@ -1977,7 +2161,7 @@ export class TUI extends Container {
 
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, finalCursorRow);
 		buffer += seq;
-		buffer += PAINT_END;
+		buffer += this.#paintEndSequence;
 
 		this.#writeDiffDebug(
 			lines,
@@ -2107,6 +2291,6 @@ export class TUI extends Container {
 		}
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, totalLines, this.#hardwareCursorRow);
 		this.#hardwareCursorRow = toRow;
-		this.terminal.write(`${HIDE_CURSOR}\x1b[?2026h${seq}\x1b[?2026l`);
+		this.terminal.write(`${this.#cursorBeginSequence}${seq}${this.#cursorEndSequence}`);
 	}
 }