@oh-my-pi/pi-tui 15.9.0 → 15.9.3

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [15.9.3] - 2026-06-05
+
+### Fixed
+
+- Fixed ED3-risk foreground streaming erasing the head of any block that alone overflows the viewport (a tall tool result drawn in one frame, or a multi-line assistant reply growing past the viewport as it streams). The live-region pin committed native scrollback only up to the sealed-prefix boundary (`liveRegionStart`), so rows of the live block that had physically scrolled above the viewport top were neither pushed into scrollback nor kept in the repainted viewport — they vanished. The commit boundary is now the viewport top: every row above the viewport enters scrollback (only the tail still visible in the viewport stays transient and deferred to the checkpoint).
+- Fixed the same ED3-risk live-region pin duplicating already-committed scrollback rows when a foreground stream's live region collapsed mid-turn (a tool preview shrinking to its compact result, an assistant block re-wrapping shorter, a late tool completion). Because growth commits every row above the viewport top to native scrollback, a subsequent shrink moved the bottom-anchored viewport back across those committed rows and the repaint re-drew them into the viewport — so they appeared twice on scroll-up, and with no prompt-submit checkpoint to reconcile (autonomous multi-turn runs, or the session ending into the welcome screen) the duplicate was baked permanently into terminal history. The pinned repaint now separates commit geometry from repaint geometry: a collapse clamps the repaint to the committed sealed boundary (`min(#scrollbackHighWater, liveRegionStart)`) instead of re-exposing those rows, leaving native scrollback un-duplicated without emitting ED3 under a possibly-scrolled reader; stale mutable live-region saved lines still reconcile at the next checkpoint.
+- Fixed hiding overlays during ED3-risk foreground streaming on unknown-viewport terminals leaving the overlay's transient rows in native scrollback. Overlay visibility reductions now bypass the streaming deferral path and rebuild once, so hidden dialog/notification sentinels are scrubbed immediately.
+- Fixed ED3-risk / unknown-viewport terminals (including WSL fronted by Windows Terminal) keeping the foreground-stream eager-rebuild mode active after the stream had already settled. A later scrolled content shrink or resize-with-append could then bypass the anti-yank deferral and repaint from stale geometry, jumping the viewport or replaying the wrong rows. The eager opt-in now drops immediately when no teardown render is pending, and the one-frame post-checkpoint suffix-suppression path no longer overrides geometry reflow handling.
+
+## [15.9.2] - 2026-06-05
+
+### Changed
+
+- Changed foreground-stream rendering on ED3-risk terminals (Ghostty/kitty/Alacritty/VTE/iTerm2 on POSIX) to defer native-scrollback commits for unpinned transient frames: while a turn streams, generic frames repaint only the viewport and suppress `\r\n` scroll growth, so transient output (spinner ticks, partial lines, status rows) never pollutes terminal history. Components that report a `NativeScrollbackLiveRegion` still commit newly sealed prefix rows while keeping the active suffix dirty for checkpoint replay. Native scrollback is reconciled in a single ED3 (`CSI 3 J`) + re-emit at the next checkpoint (prompt submit) or on an explicit user-input/IME opt-in; an erase is never emitted mid-stream under a possibly-scrolled reader. Non-ED3-risk terminals keep their eager live rebuild. ([#1895](https://github.com/can1357/oh-my-pi/pull/1895))
+
+### Fixed
+
+- Fixed ED3-risk foreground streaming dropping sealed transcript rows above the live block until the next prompt-submit checkpoint, which made scrollback beyond the viewport appear duplicated or out of order. The renderer restores native-scrollback live-region pinning so newly sealed rows are appended once while active live rows remain deferred.
+- Fixed inline images (added in 15.9) rendering as a wall of empty PUA box glyphs and producing laggy scrolling on Kitty-protocol terminals that do not implement Unicode placeholders — most notably WezTerm (per upstream wezterm/wezterm#986, placeholder support is still unchecked) and the tmux/screen `getFallbackImageProtocol` path that forces Kitty mode even on non-supporting outer terminals (Terminal.app, etc.). `unicodePlaceholders` now defaults on only for `kitty` and `ghostty`; everything else falls back to direct `a=p,i=…,p=…` placement, which those paths already render correctly. `PI_NO_KITTY_PLACEHOLDERS=1` is still honored as a hard opt-out, and a new `PI_KITTY_PLACEHOLDERS=1` opts in on otherwise-unsupported terminals (e.g. a wezterm nightly that has merged placeholder support) ([#1877](https://github.com/can1357/oh-my-pi/issues/1877)).
+
+## [15.9.1] - 2026-06-04
+
+### Fixed
+
+- Fixed the OSC 11 appearance poll re-querying every 2s forever on terminals that support Mode 2031 but never change theme, whose repeated OSC 11/DA1 writes cleared the user's active text selection (breaking copy every 2 seconds). The poll now stops as soon as DECRQM confirms Mode 2031 support, since push notifications make polling redundant.
+
 ## [15.9.0] - 2026-06-04
 
 ### Added

package/dist/types/kitty-graphics.d.ts

@@ -9,6 +9,24 @@ export interface KittyGraphicsFeatures {
     /** How image data reaches the terminal: in-band base64 or a temp file. */
     transmissionMedium: KittyTransmissionMedium;
 }
+/**
+ * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
+ * U+10EEEE with row/column diacritics).
+ *
+ * Only `kitty` (the protocol's origin) and `ghostty` ship a working
+ * implementation; WezTerm advertises Kitty graphics but treats placeholder
+ * cells as literal PUA glyphs (see wezterm/wezterm#986, "placeholder support"
+ * still unchecked), and the tmux/screen fallback can land on any outer
+ * terminal. Enabling placeholders on those paths emits a `columns × rows`
+ * grid of U+10EEEE per image per frame; the cells render as boxed fallback
+ * glyphs and re-emit on every repaint, which is exactly the
+ * "stuck/laggy scrolling + ASCII artifact" symptom reported in #1877.
+ *
+ * `PI_NO_KITTY_PLACEHOLDERS=1` forces off (e.g. for tmux passthrough to a
+ * non-supporting outer terminal); `PI_KITTY_PLACEHOLDERS=1` forces on (e.g.
+ * for a wezterm nightly that has merged placeholder support).
+ */
+export declare function detectKittyUnicodePlaceholdersSupport(terminalId: string, env?: NodeJS.ProcessEnv): boolean;
 export declare function getKittyGraphics(): Readonly<KittyGraphicsFeatures>;
 export declare function setKittyGraphics(partial: Partial<KittyGraphicsFeatures>): void;
 /**

package/dist/types/tui.d.ts

@@ -42,6 +42,16 @@ export interface Component {
      */
     invalidate(): void;
 }
+/**
+ * Optional component seam for native-scrollback pinning. A component that
+ * renders a stable prefix followed by a live/transient suffix reports the local
+ * line index where that suffix begins after each render. TUI treats that suffix
+ * — and every root child rendered below it — as not yet safe to commit to native
+ * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ */
+export interface NativeScrollbackLiveRegion {
+    getNativeScrollbackLiveRegionStart(): number | undefined;
+}
 /**
  * Interface for components that can receive focus and display a cursor.
  * When focused, the component should emit CURSOR_MARKER at the cursor position
@@ -173,6 +183,7 @@ export declare class TUI extends Container {
         hidden: boolean;
     }[];
     constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: TUIOptions);
+    render(width: number): string[];
     get fullRedraws(): number;
     /** Shared budget that caps how many inline images render as live graphics. */
     get imageBudget(): ImageBudget;
@@ -212,12 +223,13 @@ export declare class TUI extends Container {
      * (`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.
+     * Disabling stays active through one already-requested frame: 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. When no render is pending, disable immediately so a later
+     * unrelated content mutation does not inherit foreground-stream privileges.
      */
     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.9.0",
+	"version": "15.9.3",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.9.0",
-		"@oh-my-pi/pi-utils": "15.9.0",
+		"@oh-my-pi/pi-natives": "15.9.3",
+		"@oh-my-pi/pi-utils": "15.9.3",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/kitty-graphics.ts

@@ -17,7 +17,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { $env, $flag, logger } from "@oh-my-pi/pi-utils";
+import { $env, logger } from "@oh-my-pi/pi-utils";
 
 /** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
 export const KITTY_PLACEHOLDER = "\u{10eeee}";
@@ -76,8 +76,36 @@ function transmissionOverride(): KittyTransmissionMedium | "auto" {
 	return "auto";
 }
 
+/**
+ * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
+ * U+10EEEE with row/column diacritics).
+ *
+ * Only `kitty` (the protocol's origin) and `ghostty` ship a working
+ * implementation; WezTerm advertises Kitty graphics but treats placeholder
+ * cells as literal PUA glyphs (see wezterm/wezterm#986, "placeholder support"
+ * still unchecked), and the tmux/screen fallback can land on any outer
+ * terminal. Enabling placeholders on those paths emits a `columns × rows`
+ * grid of U+10EEEE per image per frame; the cells render as boxed fallback
+ * glyphs and re-emit on every repaint, which is exactly the
+ * "stuck/laggy scrolling + ASCII artifact" symptom reported in #1877.
+ *
+ * `PI_NO_KITTY_PLACEHOLDERS=1` forces off (e.g. for tmux passthrough to a
+ * non-supporting outer terminal); `PI_KITTY_PLACEHOLDERS=1` forces on (e.g.
+ * for a wezterm nightly that has merged placeholder support).
+ */
+export function detectKittyUnicodePlaceholdersSupport(terminalId: string, env: NodeJS.ProcessEnv = Bun.env): boolean {
+	const offRaw = env.PI_NO_KITTY_PLACEHOLDERS?.trim().toLowerCase();
+	if (offRaw === "1" || offRaw === "true" || offRaw === "on" || offRaw === "yes" || offRaw === "y") return false;
+	const force = env.PI_KITTY_PLACEHOLDERS?.trim().toLowerCase();
+	if (force === "1" || force === "true" || force === "on" || force === "yes" || force === "y") return true;
+	if (force === "0" || force === "false" || force === "off" || force === "no" || force === "n") return false;
+	return terminalId === "kitty" || terminalId === "ghostty";
+}
+
 let features: KittyGraphicsFeatures = {
-	unicodePlaceholders: !$flag("PI_NO_KITTY_PLACEHOLDERS"),
+	// Off until `terminal-capabilities` seeds it from the detected terminal id —
+	// the default-on path corrupts wezterm and tmux-passthrough sessions.
+	unicodePlaceholders: false,
 	// Start direct; a successful probe (or explicit `temp-file` override) promotes.
 	transmissionMedium: transmissionOverride() === "temp-file" ? "temp-file" : "direct",
 };

package/src/terminal-capabilities.ts

@@ -1,12 +1,14 @@
 import { encodeSixel } from "@oh-my-pi/pi-natives";
 import { $env, isBunTestRuntime } from "@oh-my-pi/pi-utils";
 import {
+	detectKittyUnicodePlaceholdersSupport,
 	encodeKittyTempFileTransmit,
 	getKittyGraphics,
 	isPngBase64,
 	KITTY_PLACEHOLDER,
 	kittyPlaceholdersFit,
 	renderKittyPlaceholderLines,
+	setKittyGraphics,
 } from "./kitty-graphics";
 
 export enum ImageProtocol {
@@ -321,6 +323,12 @@ export const TERMINAL = (() => {
 	return resolved;
 })();
 
+// Seed Kitty Unicode placeholder support from the resolved terminal id. Only
+// kitty/ghostty are known to honor `U=1` placement; other Kitty-protocol paths
+// (wezterm, tmux/screen fallback) treat the placeholder cells as literal PUA
+// glyphs, which is the "ASCII artifact + laggy scrolling" reported in #1877.
+setKittyGraphics({ unicodePlaceholders: detectKittyUnicodePlaceholdersSupport(TERMINAL.id, Bun.env) });
+
 type MutableTerminalInfo = {
 	imageProtocol: ImageProtocol | null;
 	deccara: boolean;

package/src/terminal.ts

@@ -281,7 +281,11 @@ export class ProcessTerminal implements Terminal {
 		this.#safeWrite("\x1b[?2031h");
 
 		// Start periodic OSC 11 re-query for terminals without Mode 2031
-		// (Warp, Alacritty, WezTerm, iTerm2). Self-disables once Mode 2031 fires.
+		// (Warp, Alacritty, older WezTerm). Stops once Mode 2031 support is
+		// confirmed via DECRQM (probed below) or a Mode 2031 change notification
+		// fires — push notifications supersede polling, and the poll's repeated
+		// OSC 11/DA1 writes clear the user's active text selection on some
+		// terminals (copy breaks every 2s).
 		// Windows Terminal under WSL has been observed to close the hosting tab
 		// after repeated OSC 11/DA1 probes. Keep the initial/event-driven probes,
 		// but avoid background polling there.
@@ -291,11 +295,14 @@ export class ProcessTerminal implements Terminal {
 
 		// Probe DEC private-mode support via DECRQM. 2026 (synchronized output)
 		// gates the renderer's begin/end markers; 2048 (in-band resize) is enabled
-		// only after the terminal confirms support. Each probe rides the shared DA1
+		// only after the terminal confirms support; 2031 (appearance change
+		// notifications) stops the OSC 11 poll once confirmed, since push
+		// notifications make polling redundant. Each probe rides the shared DA1
 		// sentinel FIFO, so a terminal that ignores DECRQM still resolves (as
 		// unsupported) when the DA1 reply arrives.
 		this.#queryPrivateMode(2026);
 		this.#queryPrivateMode(2048);
+		this.#queryPrivateMode(2031);
 	}
 
 	/**
@@ -785,7 +792,9 @@ export class ProcessTerminal implements Terminal {
 	/**
 	 * Record DECRQM support for a private mode (idempotent — first result wins)
 	 * and notify subscribers. Enables DEC 2048 in-band resize when 2048 resolves
-	 * supported.
+	 * supported, and stops the OSC 11 poll when 2031 resolves supported (Mode 2031
+	 * push notifications make periodic re-querying redundant — and the poll's
+	 * OSC 11/DA1 writes clobber active text selections on some terminals).
 	 */
 	#resolvePrivateMode(mode: number, supported: boolean): void {
 		if (this.#privateModeSupport.has(mode)) return;
@@ -798,6 +807,7 @@ export class ProcessTerminal implements Terminal {
 			}
 		}
 		if (mode === 2048 && supported) this.#enableInBandResize();
+		if (mode === 2031 && supported) this.#stopOsc11Poll();
 	}
 
 	/**

package/src/tui.ts

@@ -117,6 +117,21 @@ export interface Component {
 	invalidate(): void;
 }
 
+/**
+ * Optional component seam for native-scrollback pinning. A component that
+ * renders a stable prefix followed by a live/transient suffix reports the local
+ * line index where that suffix begins after each render. TUI treats that suffix
+ * — and every root child rendered below it — as not yet safe to commit to native
+ * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ */
+export interface NativeScrollbackLiveRegion {
+	getNativeScrollbackLiveRegionStart(): number | undefined;
+}
+
+function getNativeScrollbackLiveRegionStart(component: Component): number | undefined {
+	return (component as Component & Partial<NativeScrollbackLiveRegion>).getNativeScrollbackLiveRegionStart?.();
+}
+
 /**
  * Interface for components that can receive focus and display a cursor.
  * When focused, the component should emit CURSOR_MARKER at the cursor position
@@ -317,6 +332,9 @@ export class Container implements Component {
  * - `historyRebuild`: a geometry change (terminal resize) left native history
  *   wrapped at the old size — clear viewport and scrollback so it rewraps at the
  *   new geometry. Also flushes deferred content-only rewrites.
+ * - `liveRegionPinned`: ED3-risk/unknown foreground stream with a reported live
+ *   suffix — optionally append newly sealed rows, then repaint the live/mutable
+ *   tail without letting transient rows enter native history.
  * - `viewportRepaint`: rewrite the visible viewport in place. If `appendFrom`
  *   is set, emit those tail rows as scrollback growth first so streaming
  *   output reaches terminal history before the corrected viewport is drawn.
@@ -334,6 +352,7 @@ type RenderIntent =
 	| { kind: "sessionReplace" }
 	| { kind: "historyRebuild" }
 	| { kind: "overlayRebuild" }
+	| { kind: "liveRegionPinned"; appendFrom: number; appendTo: number; renderViewportTop: number }
 	| { kind: "viewportRepaint"; appendFrom?: number }
 	| { kind: "deferredShrink"; paddedLength: number }
 	| { kind: "deferredMutation" }
@@ -383,7 +402,18 @@ export class TUI extends Container {
 	// Set after a clear+full replay so the next insert-above-suffix frame does
 	// not scroll replayed live chrome (status/editor) into fresh history.
 	#suppressNextSuffixScroll = false;
+	#nativeScrollbackLiveRegionStart: number | undefined;
 	#nativeScrollbackDirty = false;
+	// Highest `#maxLinesRendered` reached during a foreground tool turn while
+	// intermediate frames were prevented from committing to terminal scrollback.
+	// Used after the tool finishes to push the settled content into scrollback
+	// via a non-destructive full paint (no ED 3). Reset to 0 once rows are
+	// committed (via any `#emitFullPaint`, `#emitDiff`, or `#emitAppendTail`
+	// path).
+	#streamingHighWater = 0;
+	// Tracks whether the previous frame was inside a foreground tool streaming
+	// turn. Used to reset `#streamingHighWater` on fresh streaming starts.
+	#previousStreamingActive = false;
 	#fullRedrawCount = 0;
 	// Caps how many inline images render as live graphics; older ones fall back
 	// to text via a purge + full redraw. Cap is configured by the host app.
@@ -423,6 +453,25 @@ export class TUI extends Container {
 		this.#showHardwareCursor = showHardwareCursor === undefined ? this.#showHardwareCursor : showHardwareCursor;
 	}
 
+	override render(width: number): string[] {
+		width = Math.max(1, width);
+		this.#nativeScrollbackLiveRegionStart = undefined;
+		const lines: string[] = [];
+		for (const child of this.children) {
+			const offset = lines.length;
+			const childLines = child.render(width);
+			const liveRegionStart = getNativeScrollbackLiveRegionStart(child);
+			if (liveRegionStart !== undefined) {
+				const boundedStart = Number.isFinite(liveRegionStart)
+					? Math.max(0, Math.min(childLines.length, Math.trunc(liveRegionStart)))
+					: childLines.length;
+				this.#nativeScrollbackLiveRegionStart = offset + boundedStart;
+			}
+			lines.push(...childLines);
+		}
+		return lines;
+	}
+
 	#syncTerminalCursorMode(component: Component | null): void {
 		if (isFocusable(component)) {
 			component.setUseTerminalCursor?.(this.#showHardwareCursor);
@@ -498,12 +547,13 @@ export class TUI extends Container {
 	 * (`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.
+	 * Disabling stays active through one already-requested frame: 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. When no render is pending, disable immediately so a later
+	 * unrelated content mutation does not inherit foreground-stream privileges.
 	 */
 	setEagerNativeScrollbackRebuild(enabled: boolean): void {
 		if (enabled) {
@@ -512,7 +562,16 @@ export class TUI extends Container {
 			return;
 		}
 		if (!this.#eagerNativeScrollbackRebuild) return;
-		this.#eagerNativeScrollbackRebuildDisablePending = true;
+		if (this.#renderRequested || this.#renderTimer !== undefined) {
+			this.#eagerNativeScrollbackRebuildDisablePending = true;
+			return;
+		}
+		if (process.platform !== "win32" && TERMINAL.eagerEraseScrollbackRisk) {
+			this.#streamingHighWater = 0;
+			this.#markNativeScrollbackDirty();
+		}
+		this.#eagerNativeScrollbackRebuild = false;
+		this.#eagerNativeScrollbackRebuildDisablePending = false;
 	}
 
 	setFocus(component: Component | null): void {
@@ -1383,11 +1442,12 @@ export class TUI extends Container {
 			(resizeEventOccurred && this.#previousHeight > 0);
 		const eagerEraseScrollbackRisk = process.platform !== "win32" && TERMINAL.eagerEraseScrollbackRisk;
 		const eagerRebuildAllowed = this.#eagerNativeScrollbackRebuild && !eagerEraseScrollbackRisk;
-		const allowUnknownViewportMutation = this.#allowUnknownViewportMutationOnNextRender || eagerRebuildAllowed;
+		const explicitViewportMutation = this.#allowUnknownViewportMutationOnNextRender;
+		const allowUnknownViewportMutation = explicitViewportMutation || eagerRebuildAllowed;
 		this.#allowUnknownViewportMutationOnNextRender = false;
 
 		// 3. Classify intent.
-		const intent = this.#planRender(
+		let intent = this.#planRender(
 			lines,
 			widthChanged,
 			heightChanged,
@@ -1396,7 +1456,62 @@ export class TUI extends Container {
 			visibleOverlayComponents.length > 0,
 			overlayVisibilityReduced,
 			allowUnknownViewportMutation,
+			this.#nativeScrollbackLiveRegionStart,
 		);
+		// 3b. Defer scrollback commits during foreground streaming, but only on
+		// ED3-risk terminals whose committed scrollback cannot be rewritten without
+		// yanking a scrolled reader. There the eager rebuild is gated off and the
+		// diff emitter would otherwise `\r\n`-scroll every transient frame (spinner
+		// ticks, partial output) into native history. Non-ED3-risk terminals keep
+		// their eager live rebuild, which already commits cleanly. Explicit
+		// reconciles — the prompt-submit checkpoint (`clearScrollbackOnNextRender`),
+		// user-input/IME opt-ins (`explicitViewportMutation`), and overlay visibility
+		// reductions that must scrub transient overlay cells from native history —
+		// are never deferred: the triggering interaction pins the host to the bottom.
+		const streamingWasActive = this.#eagerNativeScrollbackRebuild;
+		if (streamingWasActive && !this.#previousStreamingActive) {
+			this.#streamingHighWater = 0;
+		}
+		this.#previousStreamingActive = streamingWasActive;
+		if (streamingWasActive && eagerEraseScrollbackRisk) {
+			const streamingActive =
+				this.#eagerNativeScrollbackRebuild && !this.#eagerNativeScrollbackRebuildDisablePending;
+			const explicitReconcile =
+				explicitViewportMutation || this.#clearScrollbackOnNextRender || overlayVisibilityReduced;
+			// The defer below exists only to avoid `\r\n`-scrolling transient frames
+			// past a reader parked in native scrollback. When the terminal can report
+			// that the viewport is at the tail, there is no scrolled reader to yank,
+			// so the planned intent must stand and commit normally — otherwise a row
+			// that scrolls above the viewport top is dropped (neither pushed to
+			// history nor kept in the capped viewport). Production POSIX ED3-risk
+			// terminals cannot report this and stay `undefined`, so they still defer.
+			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+			if (!streamingActive) {
+				// Streaming just ended. Keep native scrollback dirty so the next
+				// checkpoint reconciles the settled transcript; never erase here.
+				this.#streamingHighWater = 0;
+				this.#markNativeScrollbackDirty();
+			} else if (
+				!explicitReconcile &&
+				nativeViewportAtBottom !== true &&
+				(intent.kind === "sessionReplace" ||
+					intent.kind === "historyRebuild" ||
+					intent.kind === "overlayRebuild" ||
+					(intent.kind === "diff" && intent.appendedLines))
+			) {
+				// Cap the frame to the viewport and keep scrollback dirty: transient
+				// rows never enter history, and the checkpoint reconciles later.
+				this.#markNativeScrollbackDirty();
+				this.#streamingHighWater = Math.max(this.#streamingHighWater, lines.length);
+				this.#scrollbackHighWater = 0;
+				lines = lines.slice(-height);
+				intent = { kind: "viewportRepaint" };
+			} else {
+				// Explicit reconcile or a non-committing frame (noop): let the
+				// planned intent stand, but keep tracking the streaming peak.
+				this.#streamingHighWater = Math.max(this.#streamingHighWater, lines.length);
+			}
+		}
 		if (this.#eagerNativeScrollbackRebuildDisablePending) {
 			this.#eagerNativeScrollbackRebuildDisablePending = false;
 			this.#eagerNativeScrollbackRebuild = false;
@@ -1448,6 +1563,19 @@ export class TUI extends Container {
 				});
 				this.#emitViewportRepaint(lines, width, height, cursorPos);
 				return;
+			case "liveRegionPinned":
+				this.#emitLiveRegionPinnedRepaint(
+					lines,
+					width,
+					height,
+					cursorPos,
+					intent.appendFrom,
+					intent.appendTo,
+					intent.renderViewportTop,
+					prevViewportTop,
+					prevHardwareCursorRow,
+				);
+				return;
 			case "viewportRepaint":
 				if (intent.appendFrom !== undefined) {
 					this.#emitAppendTail(lines, intent.appendFrom, height, width, prevViewportTop, prevHardwareCursorRow);
@@ -1500,6 +1628,7 @@ export class TUI extends Container {
 		hasVisibleOverlay: boolean,
 		overlayVisibilityReduced: boolean,
 		allowUnknownViewportMutation: boolean,
+		liveRegionStart: number | undefined,
 	): RenderIntent {
 		// Initial paint after start(): scrollback must keep its prior shell
 		// content, but the viewport must be cleared so stale rows do not bleed
@@ -1532,6 +1661,29 @@ export class TUI extends Container {
 			return { kind: "viewportRepaint" };
 		}
 
+		const liveRegionPinnedIntent = this.#planLiveRegionPinnedRender(
+			newLines,
+			height,
+			liveRegionStart,
+			eagerEraseScrollbackRisk,
+			allowUnknownViewportMutation,
+			widthChanged || heightChanged,
+		);
+		if (liveRegionPinnedIntent) return liveRegionPinnedIntent;
+
+		// After foreground tool streaming: when content finally shrinks from the
+		// streaming peak, rebuild with ED 3 to commit the settled state cleanly.
+		// The check uses `#streamingHighWater` (the real peak) rather than
+		// `#previousLines.length` because unpinned ED3-risk streaming frames may
+		// commit only a viewport slice while native history is deferred.
+		if (this.#streamingHighWater > height && newLines.length < this.#streamingHighWater && newLines.length > height) {
+			this.#streamingHighWater = 0;
+			return { kind: "historyRebuild" };
+		}
+		if (this.#streamingHighWater > 0 && newLines.length <= height) {
+			this.#streamingHighWater = 0;
+		}
+
 		if (
 			this.#nativeScrollbackDirty &&
 			!isMultiplexerSession() &&
@@ -1584,17 +1736,12 @@ export class TUI extends Container {
 			// stale rows until the next input even though the frame has a fresh bottom
 			// viewport to show (issues #1682, foreground-stream fidelity on collapse).
 			// Native history stays dirty and reconciles at the next checkpoint. With no
-			// active eager turn the reader may be scrolled, so defer rather than
-			// repainting over their history.
+			// active eager turn the reader may be scrolled; even a padded shrink repaint
+			// can move ED3-risk unknown host scrollback (WSL/Ghostty-style), so defer
+			// completely rather than repainting over their history.
 			if (nativeViewportAtBottom === undefined && eagerEraseScrollbackRisk) {
 				this.#markNativeScrollbackDirty();
-				if (this.#eagerNativeScrollbackRebuild) {
-					return { kind: "viewportRepaint" };
-				}
-				if (newLines.length <= paddedViewportTop) {
-					return { kind: "deferredMutation" };
-				}
-				return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
+				return this.#eagerNativeScrollbackRebuild ? { kind: "viewportRepaint" } : { kind: "deferredMutation" };
 			}
 
 			// Non-ED3-risk POSIX with an unobservable viewport. If the shrink still
@@ -1666,6 +1813,8 @@ export class TUI extends Container {
 		this.#suppressNextSuffixScroll = false;
 		if (
 			suppressSuffixScroll &&
+			!widthChanged &&
+			!heightChanged &&
 			diff.appendedLines &&
 			diff.firstChanged < this.#previousLines.length &&
 			!isMultiplexerSession()
@@ -1760,7 +1909,10 @@ export class TUI extends Container {
 				return { kind: "viewportRepaint" };
 			}
 		}
-		if (!pureAppend && structuralMutation && !isMultiplexerSession()) {
+		// Geometry changes invalidate the terminal's cursor and viewport anchors;
+		// even if the same coalesced frame also edits offscreen content for a scrolled
+		// reader, the resize-specific branch below must repaint/clamp at the new size.
+		if (!pureAppend && structuralMutation && !heightChanged && !widthChanged && !isMultiplexerSession()) {
 			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
 			if (this.#nativeViewportIsScrolled(nativeViewportAtBottom, allowUnknownViewportMutation)) {
 				this.#markNativeScrollbackDirty();
@@ -2036,6 +2188,56 @@ export class TUI extends Container {
 		);
 	}
 
+	#planLiveRegionPinnedRender(
+		newLines: string[],
+		height: number,
+		liveRegionStart: number | undefined,
+		eagerEraseScrollbackRisk: boolean,
+		allowUnknownViewportMutation: boolean,
+		geometryChanged: boolean,
+	): RenderIntent | undefined {
+		// A width/height change reflows the whole terminal: the relative cursor
+		// positioning this emitter relies on is computed from the pre-resize
+		// geometry and would land on the wrong rows. Defer to the geometry branch
+		// (a full reflow rebuild), which is the established behavior for resizes.
+		if (
+			liveRegionStart === undefined ||
+			liveRegionStart >= newLines.length ||
+			!this.#eagerNativeScrollbackRebuild ||
+			!eagerEraseScrollbackRisk ||
+			allowUnknownViewportMutation ||
+			geometryChanged ||
+			isMultiplexerSession()
+		) {
+			return undefined;
+		}
+		if (newLines.length <= height && this.#scrollbackHighWater === 0) return undefined;
+		if (this.#readNativeViewportAtBottom() !== undefined) return undefined;
+
+		this.#markNativeScrollbackDirty();
+		const naturalViewportTop = Math.max(0, newLines.length - height);
+		// Rows before the live-region boundary are sealed. If a live-region
+		// collapse moves the bottom-anchored viewport back across rows already
+		// written to native scrollback, repainting those sealed rows duplicates
+		// them in history. Clamp only to the committed sealed boundary: mutable
+		// rows inside the live region must remain visible even when an earlier
+		// taller live frame pushed their old contents into native scrollback. The
+		// dirty checkpoint later reconciles those stale mutable saved lines.
+		const committedSealedEnd = Math.min(this.#scrollbackHighWater, liveRegionStart);
+		const renderViewportTop = Math.max(naturalViewportTop, committedSealedEnd);
+		// Every row above the natural viewport top has physically scrolled out of
+		// the live viewport, so the terminal has already pushed it into native
+		// scrollback — there is nowhere else for an off-screen row to live. It must
+		// therefore be committed as real content, *including the head of the live
+		// block itself* when that block alone overflows the viewport (a tall tool
+		// result, a long streamed reply). Only the live tail that remains *within*
+		// the natural viewport stays transient (repainted in place, deferred to the
+		// checkpoint rebuild).
+		const appendTo = naturalViewportTop;
+		const appendFrom = Math.min(this.#scrollbackHighWater, appendTo);
+		return { kind: "liveRegionPinned", appendFrom, appendTo, renderViewportTop };
+	}
+
 	#padDeferredShrinkLines(lines: string[], paddedLength: number): string[] {
 		if (lines.length >= paddedLength) return lines;
 		return [...lines, ...new Array<string>(paddedLength - lines.length).fill("")];
@@ -2208,6 +2410,76 @@ export class TUI extends Container {
 		this.#commit(lines, width, height, viewportTop, toRow);
 	}
 
+	/**
+	 * Foreground-stream live-region paint for ED3-risk terminals with an
+	 * unobservable viewport. Commits the newly-sealed chunk to native scrollback
+	 * (so finished blocks stay scrollable) and repaints the live tail in place,
+	 * leaving the transient live region out of saved lines.
+	 *
+	 * Uses only the no-scroll-snap vocabulary of {@link #emitDiff}: relative
+	 * cursor moves, per-line `\x1b[2K`, and `\r\n` to push the sealed chunk into
+	 * history. It deliberately avoids a full-screen erase (`\x1b[2J`) and absolute
+	 * cursor home (`\x1b[H`): on Ghostty those snap a reader scrolled into history
+	 * back to the bottom on every frame.
+	 */
+	#emitLiveRegionPinnedRepaint(
+		lines: string[],
+		width: number,
+		height: number,
+		cursorPos: { row: number; col: number } | null,
+		appendFrom: number,
+		appendTo: number,
+		renderViewportTop: number,
+		prevViewportTop: number,
+		prevHardwareCursorRow: number,
+	): void {
+		this.#fullRedrawCount += 1;
+		const naturalViewportTop = Math.max(0, lines.length - height);
+		const viewportTop = Math.max(0, Math.min(renderViewportTop, lines.length));
+		const boundedAppendTo = Math.max(0, Math.min(appendTo, naturalViewportTop, lines.length));
+		const boundedAppendFrom = Math.max(0, Math.min(appendFrom, boundedAppendTo));
+
+		// Position at the top visible row with a relative move. Terminals clamp the
+		// hardware cursor to the viewport on resize, so clamp our tracking to match
+		// before computing the delta (mirrors #emitDiff).
+		const clampedCursor = Math.min(prevHardwareCursorRow, prevViewportTop + height - 1);
+		const currentScreenRow = Math.max(0, Math.min(height - 1, clampedCursor - prevViewportTop));
+		let buffer = this.#paintBeginSequence;
+		if (currentScreenRow > 0) buffer += `\x1b[${currentScreenRow}A`;
+		buffer += "\r";
+
+		// Write the sealed chunk followed by the full viewport from the top row.
+		// The first (boundedAppendTo - boundedAppendFrom) rows scroll into native
+		// history; the trailing `height` rows fill the viewport. Each row clears
+		// itself with `\x1b[2K` instead of relying on a screen-wide erase.
+		let wroteLine = false;
+		for (let i = boundedAppendFrom; i < boundedAppendTo; i++) {
+			if (wroteLine) buffer += "\r\n";
+			buffer += `\x1b[2K${this.#fitLineToWidth(lines[i] ?? "", width)}`;
+			wroteLine = true;
+		}
+		for (let screenRow = 0; screenRow < height; screenRow++) {
+			if (wroteLine) buffer += "\r\n";
+			buffer += `\x1b[2K${this.#fitLineToWidth(lines[viewportTop + screenRow] ?? "", width)}`;
+			wroteLine = true;
+		}
+
+		const viewportBottomRow = viewportTop + height - 1;
+		const contentBottomRow = Math.min(viewportBottomRow, Math.max(viewportTop, lines.length - 1));
+		const parkUp = viewportBottomRow - contentBottomRow;
+		if (parkUp > 0) buffer += `\x1b[${parkUp}A`;
+		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, contentBottomRow);
+		buffer += seq;
+		buffer += this.#paintEndSequence;
+		this.terminal.write(buffer);
+
+		this.#maxLinesRendered = Math.max(lines.length, viewportTop + height);
+		if (boundedAppendTo > this.#scrollbackHighWater) {
+			this.#scrollbackHighWater = boundedAppendTo;
+		}
+		this.#commit(lines, width, height, viewportTop, toRow);
+	}
+
 	/**
 	 * Push the appended tail into terminal scrollback by `\r\n`-ing past the
 	 * previous viewport bottom. Used as a prefix to {@link #emitViewportRepaint}
@@ -2443,9 +2715,11 @@ export class TUI extends Container {
 		const detail =
 			intent.kind === "diff"
 				? `${intent.kind}(first=${intent.firstChanged}, last=${intent.lastChanged}, appended=${intent.appendedLines})`
-				: intent.kind === "viewportRepaint" && intent.appendFrom !== undefined
-					? `${intent.kind}(appendFrom=${intent.appendFrom})`
-					: intent.kind;
+				: intent.kind === "liveRegionPinned"
+					? `${intent.kind}(append=${intent.appendFrom}..${intent.appendTo}, viewportTop=${intent.renderViewportTop})`
+					: intent.kind === "viewportRepaint" && intent.appendFrom !== undefined
+						? `${intent.kind}(appendFrom=${intent.appendFrom})`
+						: intent.kind;
 		const msg = `[${new Date().toISOString()}] render: ${detail} (prev=${this.#previousLines.length}, new=${newLength}, height=${height})\n`;
 		fs.appendFileSync(getDebugLogPath(), msg);
 	}