@oh-my-pi/pi-tui 15.11.0 → 15.11.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [15.11.1] - 2026-06-11
+### Added
+
+- Added `TUI.requestComponentRender(component)` to schedule component-scoped renders for self-contained updates
+
+### Changed
+
+- Changed the render pipeline to reuse only affected root subtrees for component-scoped updates, avoiding full-tree compose when animations or other isolated component changes occur
+
+### Fixed
+
+- Fixed component-scoped renders to preserve prior live scrollback seam data for skipped root children, preventing duplicate or missing rows during spinner-only updates
+- Reported committed native scrollback row counts to interested child components so immutable history can be skipped without breaking live-region commit bookkeeping.
+- Fixed `ProcessTerminal` treating asynchronous stdout `EIO` errors as uncaught exceptions: stdout `error` events now mark the terminal dead, disable future renders, and keep the active session process alive ([#2284](https://github.com/can1357/oh-my-pi/issues/2284)).
+
 ## [15.11.0] - 2026-06-10
 ### Added
 

package/README.md

@@ -51,6 +51,7 @@ tui.removeChild(component);
 tui.start();
 tui.stop();
 tui.requestRender(); // Request a re-render
+tui.requestComponentRender(component); // Re-render only the root subtree containing `component` when safe (falls back to a full render on resize, overlays, images, or concurrent full requests)
 
 // Global debug key handler (Shift+Ctrl+D)
 tui.onDebug = () => console.log("Debug triggered");

package/dist/types/components/image.d.ts

@@ -75,6 +75,13 @@ export declare class ImageBudget {
     enqueueTransmit(imageId: number, sequence: string): void;
     /** Whether a frame has image data queued but not yet written to the terminal. */
     hasPendingTransmits(): boolean;
+    /**
+     * True when the budget has nothing in flight: no live images observed on
+     * the last pass, no queued transmits, no pending purges, and no stricter
+     * threshold left to apply. A component-scoped frame may skip the observe
+     * pass only then — a partial tree walk would under-count display order.
+     */
+    get quiescent(): boolean;
     /** Transmit sequences to write before this frame's placements; clears the queue. */
     takeTransmits(): readonly string[];
 }

package/dist/types/tui.d.ts

@@ -88,6 +88,9 @@ export interface NativeScrollbackLiveRegion {
     getNativeScrollbackLiveRegionStart(): number | undefined;
     getNativeScrollbackCommitSafeEnd?(): number | undefined;
 }
+export interface NativeScrollbackCommittedRows {
+    setNativeScrollbackCommittedRows(rows: number): void;
+}
 /**
  * Opt-in stability report for components that mutate their returned render
  * array in place across frames (instead of returning a fresh array per
@@ -314,4 +317,20 @@ export declare class TUI extends Container {
      */
     resetDisplay(): void;
     requestRender(force?: boolean, options?: RenderRequestOptions): void;
+    /**
+     * Schedule a render on behalf of `component` after a self-contained change
+     * (spinner frame, blink) that cannot have affected any other component.
+     *
+     * When every request since the last frame is component-scoped and the
+     * frame is otherwise quiet — no resize or geometry change, no overlays, no
+     * live inline images, no forced repaint, unchanged root child list — the
+     * next compose re-renders only the root subtrees containing the requesting
+     * components and reuses the previous frame's rows (and seam reports) for
+     * every other root child, skipping the full component-tree walk that makes
+     * long transcripts expensive to repaint at animation rate. Any concurrent
+     * full request or unsafe condition downgrades the frame to a normal full
+     * compose, so this is never less correct than `requestRender()` — only
+     * cheaper.
+     */
+    requestComponentRender(component: Component): void;
 }

package/package.json

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

package/src/components/image.ts

@@ -196,6 +196,21 @@ export class ImageBudget {
 		return this.#pendingTransmits.length > 0;
 	}
 
+	/**
+	 * True when the budget has nothing in flight: no live images observed on
+	 * the last pass, no queued transmits, no pending purges, and no stricter
+	 * threshold left to apply. A component-scoped frame may skip the observe
+	 * pass only then — a partial tree walk would under-count display order.
+	 */
+	get quiescent(): boolean {
+		return (
+			this.#lastTotal === 0 &&
+			this.#pendingTransmits.length === 0 &&
+			this.#purgeIds.length === 0 &&
+			this.#planned === this.#onTerminal
+		);
+	}
+
 	/** Transmit sequences to write before this frame's placements; clears the queue. */
 	takeTransmits(): readonly string[] {
 		if (this.#pendingTransmits.length === 0) return EMPTY_TRANSMITS;

package/src/components/loader.ts

@@ -90,7 +90,11 @@ export class Loader extends Text {
 		const frame = this.#frames[this.#currentFrame];
 		const text = `${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`;
 		if (this.setText(text) && this.#ui) {
-			this.#ui.requestRender();
+			// Component-scoped: a spinner tick changes only this component, so
+			// the TUI may reuse every other root subtree instead of re-walking
+			// the whole tree (full repaints at 12.5 Hz made huge transcripts
+			// lag as soon as the loader appeared).
+			this.#ui.requestComponentRender(this);
 		}
 	}
 }

package/src/terminal.ts

@@ -123,6 +123,24 @@ let activeTerminal: ProcessTerminal | null = null;
 // Track if a terminal was ever started (for emergency restore logic)
 let terminalEverStarted = false;
 
+const stdoutErrorHandlers = new Set<(err: Error) => void>();
+let stdoutErrorListenerInstalled = false;
+
+function onStdoutError(err: Error): void {
+	for (const handler of stdoutErrorHandlers) handler(err);
+}
+
+function registerStdoutErrorHandler(handler: (err: Error) => void): () => void {
+	stdoutErrorHandlers.add(handler);
+	if (!stdoutErrorListenerInstalled) {
+		process.stdout.on("error", onStdoutError);
+		stdoutErrorListenerInstalled = true;
+	}
+	return () => {
+		stdoutErrorHandlers.delete(handler);
+	};
+}
+
 const STD_INPUT_HANDLE = -10;
 const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
 /** UTF-8 codepage id for SetConsoleCP/SetConsoleOutputCP. */
@@ -344,6 +362,11 @@ export class ProcessTerminal implements Terminal {
 	#stdinDataHandler?: (data: string) => void;
 	#dead = false;
 	#writeLogPath = $env.PI_TUI_WRITE_LOG || "";
+	#stdoutErrorCleanup?: () => void;
+	#stdoutErrorHandler = (err: Error) => {
+		this.#markTerminalWriteFailed(err);
+	};
+
 	#windowsVTInputRestore?: () => void;
 	#appearanceCallbacks: Array<(appearance: TerminalAppearance) => void> = [];
 	#appearance: TerminalAppearance | undefined;
@@ -1182,6 +1205,18 @@ export class ProcessTerminal implements Terminal {
 		if (process.stdin.setRawMode) {
 			process.stdin.setRawMode(this.#wasRaw);
 		}
+		this.#stdoutErrorCleanup?.();
+		this.#stdoutErrorCleanup = undefined;
+	}
+
+	#ensureStdoutErrorHandler(): void {
+		this.#stdoutErrorCleanup ??= registerStdoutErrorHandler(this.#stdoutErrorHandler);
+	}
+
+	#markTerminalWriteFailed(err: unknown): void {
+		if (this.#dead) return;
+		this.#dead = true;
+		logger.warn("terminal write failed; disabling terminal rendering", { err });
 	}
 
 	write(data: string): void {
@@ -1200,6 +1235,7 @@ export class ProcessTerminal implements Terminal {
 		// Skip control sequences when stdout isn't a TTY (piped output, tests, log
 		// files). They serve no purpose there and would surface as visible noise.
 		if (!process.stdout.isTTY) return;
+		this.#ensureStdoutErrorHandler();
 		// A console-sharing child process may have flipped the console codepage
 		// away from UTF-8; repair it before any bytes hit WriteFile so no frame
 		// is ever translated through an OEM codepage. See ensureWindowsConsoleUtf8.
@@ -1219,15 +1255,14 @@ export class ProcessTerminal implements Terminal {
 			// threshold. See #2034 and #2095.
 			if (isConPTYHosted() && Buffer.byteLength(data, "utf8") > MAX_CONPTY_WRITE_CHUNK_BYTES) {
 				for (const chunk of chunkForConPTY(data, MAX_CONPTY_WRITE_CHUNK_BYTES)) {
+					if (this.#dead) break;
 					process.stdout.write(chunk);
 				}
 			} else {
 				process.stdout.write(data);
 			}
 		} catch (err) {
-			// Any write failure means terminal is dead - no recovery possible
-			this.#dead = true;
-			logger.warn("terminal is dead - no recovery possible", { error: err, data });
+			this.#markTerminalWriteFailed(err);
 		}
 	}
 

package/src/tui.ts

@@ -191,6 +191,14 @@ export interface NativeScrollbackLiveRegion {
 	getNativeScrollbackCommitSafeEnd?(): number | undefined;
 }
 
+export interface NativeScrollbackCommittedRows {
+	setNativeScrollbackCommittedRows(rows: number): void;
+}
+
+function setNativeScrollbackCommittedRows(component: Component, rows: number): void {
+	(component as Component & Partial<NativeScrollbackCommittedRows>).setNativeScrollbackCommittedRows?.(rows);
+}
+
 function getNativeScrollbackLiveRegionStart(component: Component): number | undefined {
 	return (component as Component & Partial<NativeScrollbackLiveRegion>).getNativeScrollbackLiveRegionStart?.();
 }
@@ -490,14 +498,29 @@ interface CursorControlResult extends HardwareCursorUpdate {
 
 /**
  * One root child's contribution to the composed frame: the array reference its
- * render() returned, the frame row it starts at, and the row count recorded at
- * compose time (in-place mutators keep the reference but may change length).
+ * render() returned, the frame row it starts at, the row count recorded at
+ * compose time (in-place mutators keep the reference but may change length),
+ * and the child-local seam reports captured at render time — replayed verbatim
+ * when a component-scoped frame reuses this segment without re-rendering.
  */
 interface FrameSegment {
 	component: Component;
 	lines: readonly string[];
 	start: number;
 	rowCount: number;
+	liveLocalStart?: number;
+	commitLocalEnd?: number;
+}
+
+/** Depth-first identity search through `Container`-shaped children. */
+function subtreeContains(root: Component, target: Component): boolean {
+	if (root === target) return true;
+	const children = (root as Partial<Container>).children;
+	if (!Array.isArray(children)) return false;
+	for (let i = 0; i < children.length; i++) {
+		if (subtreeContains(children[i]!, target)) return true;
+	}
+	return false;
 }
 
 interface PreparedLine {
@@ -711,6 +734,21 @@ export class TUI extends Container {
 	// Leading rows of #composedFrame byte-identical to the previous compose.
 	#renderStablePrefixRows = 0;
 
+	// Component-scoped render accumulation. Targets are the components handed
+	// to requestComponentRender() since the last frame; the flag stays true
+	// only while EVERY pending request is component-scoped. Both are consumed
+	// once per frame by #doRender.
+	#componentRenderTargets = new Set<Component>();
+	#pendingRenderComponentsOnly = false;
+	// Root children that must re-render during the current compose; null for a
+	// full compose. Non-null only for the duration of a component-scoped
+	// render() call inside #doRender (the scratch set below, reused per frame).
+	#partialComposeRoots: Set<Component> | null = null;
+	#partialComposeRootsScratch = new Set<Component>();
+	// Target component -> containing root child, so animation-rate requests do
+	// not re-walk a huge transcript subtree every frame.
+	#componentRootCache = new WeakMap<Component, Component>();
+
 	// Persistent prepared frame, row-aligned with #composedFrame. Entries store
 	// normalized, width-fitted content rows without the per-line terminal
 	// terminator; terminators are appended only at write time so width checks
@@ -750,30 +788,58 @@ export class TUI extends Container {
 		this.#composeWidth = width;
 		let offset = 0;
 		let stableRows = 0;
+		const partialRoots = this.#partialComposeRoots;
 		for (let index = 0; index < children.length; index++) {
 			const child = children[index]!;
-			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;
-				const commitSafeEnd = getNativeScrollbackCommitSafeEnd(child);
-				if (commitSafeEnd !== undefined) {
-					const boundedEnd = Number.isFinite(commitSafeEnd)
-						? Math.max(boundedStart, Math.min(childLines.length, Math.trunc(commitSafeEnd)))
+			const previous = previousSegments[index];
+			// Component-scoped frame: a root child outside every requested
+			// subtree provably did not change (content mutations route through
+			// a render request, which would have made this frame a full one) —
+			// reuse its previous rows and seam report without calling render().
+			const reuse =
+				partialRoots !== null && previous !== undefined && previous.component === child && !partialRoots.has(child);
+			let childLines: readonly string[];
+			let liveLocalStart: number | undefined;
+			let commitLocalEnd: number | undefined;
+			let reported: number | undefined;
+			if (reuse) {
+				childLines = previous.lines;
+				liveLocalStart = previous.liveLocalStart;
+				commitLocalEnd = previous.commitLocalEnd;
+			} else {
+				// Feed the engine's committed-row claim (from the previous frame's
+				// emit) before rendering so the child can skip re-deriving blocks
+				// that already live in immutable native scrollback. Reused segments
+				// skip this: they never call render(), so the signal is moot.
+				setNativeScrollbackCommittedRows(child, Math.max(0, this.#committedRows - offset));
+				childLines = child.render(width);
+				const liveRegionStart = getNativeScrollbackLiveRegionStart(child);
+				if (liveRegionStart !== undefined) {
+					liveLocalStart = Number.isFinite(liveRegionStart)
+						? Math.max(0, Math.min(childLines.length, Math.trunc(liveRegionStart)))
 						: childLines.length;
-					this.#nativeScrollbackCommitSafeEnd = offset + boundedEnd;
+					const commitSafeEnd = getNativeScrollbackCommitSafeEnd(child);
+					if (commitSafeEnd !== undefined) {
+						commitLocalEnd = Number.isFinite(commitSafeEnd)
+							? Math.max(liveLocalStart, Math.min(childLines.length, Math.trunc(commitSafeEnd)))
+							: childLines.length;
+					}
+				}
+				// Consume the stability report unconditionally for implementers:
+				// reading re-bases the component's baseline to the state this
+				// compose is about to ingest (used or not, the current rows are
+				// what ends up in the composed frame). Reused segments are
+				// deliberately NOT read — their baseline must stay anchored to
+				// the last render the engine actually observed.
+				reported = getRenderStablePrefixRows(child);
+			}
+			if (liveLocalStart !== undefined) {
+				this.#nativeScrollbackLiveRegionStart = offset + liveLocalStart;
+				if (commitLocalEnd !== undefined) {
+					this.#nativeScrollbackCommitSafeEnd = offset + commitLocalEnd;
 				}
 			}
-			// Consume the stability report unconditionally for implementers:
-			// reading re-bases the component's baseline to the state this
-			// compose is about to ingest (used or not, the current rows are
-			// what ends up in the composed frame).
-			const reported = getRenderStablePrefixRows(child);
 			if (chainStable) {
-				const previous = previousSegments[index];
 				if (previous !== undefined && previous.component === child && previous.start === offset) {
 					let stableCount = 0;
 					if (reported !== undefined) {
@@ -794,7 +860,14 @@ export class TUI extends Container {
 					chainStable = false;
 				}
 			}
-			segments[index] = { component: child, lines: childLines, start: offset, rowCount: childLines.length };
+			segments[index] = {
+				component: child,
+				lines: childLines,
+				start: offset,
+				rowCount: childLines.length,
+				liveLocalStart,
+				commitLocalEnd,
+			};
 			offset += childLines.length;
 		}
 		this.#frameSegments = segments;
@@ -1335,6 +1408,8 @@ export class TUI extends Container {
 	}
 
 	requestRender(force = false, options?: RenderRequestOptions): void {
+		// Any non-component-scoped request makes the pending frame a full one.
+		this.#pendingRenderComponentsOnly = false;
 		if (force) {
 			// Forced repaints landing inside the multiplexer resize debounce
 			// (e.g. `#finishSixelProbe`, image-budget eviction, a programmatic
@@ -1365,6 +1440,38 @@ export class TUI extends Container {
 			});
 			return;
 		}
+		this.#requestOrdinaryRender();
+	}
+
+	/**
+	 * Schedule a render on behalf of `component` after a self-contained change
+	 * (spinner frame, blink) that cannot have affected any other component.
+	 *
+	 * When every request since the last frame is component-scoped and the
+	 * frame is otherwise quiet — no resize or geometry change, no overlays, no
+	 * live inline images, no forced repaint, unchanged root child list — the
+	 * next compose re-renders only the root subtrees containing the requesting
+	 * components and reuses the previous frame's rows (and seam reports) for
+	 * every other root child, skipping the full component-tree walk that makes
+	 * long transcripts expensive to repaint at animation rate. Any concurrent
+	 * full request or unsafe condition downgrades the frame to a normal full
+	 * compose, so this is never less correct than `requestRender()` — only
+	 * cheaper.
+	 */
+	requestComponentRender(component: Component): void {
+		if (this.#stopped) return;
+		// Start a component-scoped accumulation only when nothing else is in
+		// flight (a pending throttled request or a deferred ConPTY settle
+		// replay may carry full-render intent that must not be narrowed).
+		if (!this.#renderRequested && this.#postFullPaintSettleTimer === undefined) {
+			this.#pendingRenderComponentsOnly = true;
+		}
+		this.#componentRenderTargets.add(component);
+		this.#requestOrdinaryRender();
+	}
+
+	/** Ordinary (non-forced) scheduling shared by full and component-scoped requests. */
+	#requestOrdinaryRender(): void {
 		// Coalesce non-forced renders inside the post-full-paint ConPTY settle
 		// window into one trailing render. Spinner/blink/streaming components
 		// otherwise fire `requestRender(false)` at 30 Hz while the host is still
@@ -1379,7 +1486,7 @@ export class TUI extends Container {
 						this.#postFullPaintSettleTimer = undefined;
 						this.#postFullPaintSettleUntilMs = 0;
 						if (this.#stopped) return;
-						this.requestRender(false);
+						this.#requestOrdinaryRender();
 					}, this.#postFullPaintSettleUntilMs - now);
 				}
 				return;
@@ -1391,6 +1498,56 @@ export class TUI extends Container {
 		this.#renderScheduler.scheduleImmediate(() => this.#scheduleRender());
 	}
 
+	/**
+	 * Decide whether this frame may compose component-scoped, and resolve the
+	 * requested components to the root children that must re-render. Returns
+	 * null — full compose — whenever a global condition could invalidate rows
+	 * the partial compose would reuse, or when a requested component is not
+	 * reachable from the current root child list.
+	 */
+	#resolvePartialComposeRoots(width: number, height: number): Set<Component> | null {
+		if (this.#componentRenderTargets.size === 0) return null;
+		if (!this.#hasEverRendered || this.#resizeEventPending) return null;
+		if (width !== this.#previousWidth || height !== this.#previousHeight || width !== this.#composeWidth) return null;
+		if (this.#clearScrollbackOnNextRender || this.#forceViewportRepaintOnNextRender) return null;
+		if (this.overlayStack.length > 0) return null;
+		// The image budget audits display order across the whole frame; a
+		// partial walk would under-count it. Engage only on image-free frames.
+		if (!this.#imageBudget.quiescent) return null;
+		// The root child list must match the segment ledger exactly — a
+		// structural change shifts offsets under every reused segment.
+		const children = this.children;
+		const segments = this.#frameSegments;
+		if (segments.length !== children.length) return null;
+		for (let i = 0; i < children.length; i++) {
+			if (segments[i]!.component !== children[i]) return null;
+		}
+		const roots = this.#partialComposeRootsScratch;
+		roots.clear();
+		for (const target of this.#componentRenderTargets) {
+			const root = this.#resolveComponentRoot(target);
+			if (root === null) return null;
+			roots.add(root);
+		}
+		return roots;
+	}
+
+	/** Root child whose subtree contains `target`, memoized per component. */
+	#resolveComponentRoot(target: Component): Component | null {
+		const cached = this.#componentRootCache.get(target);
+		if (cached !== undefined && this.children.includes(cached) && subtreeContains(cached, target)) {
+			return cached;
+		}
+		for (const child of this.children) {
+			if (subtreeContains(child, target)) {
+				this.#componentRootCache.set(target, child);
+				return child;
+			}
+		}
+		this.#componentRootCache.delete(target);
+		return null;
+	}
+
 	/**
 	 * Arm or extend the multiplexer-resize debounce so a single forced render
 	 * fires once the pane is quiet. Called by the SIGWINCH callback on every
@@ -1468,7 +1625,7 @@ export class TUI extends Container {
 				this.#postFullPaintSettleTimer = undefined;
 				this.#postFullPaintSettleUntilMs = 0;
 				if (this.#stopped) return;
-				this.requestRender(false);
+				this.#requestOrdinaryRender();
 			}, TUI.#CONPTY_POST_FULL_PAINT_SETTLE_MS);
 		}
 	}
@@ -1881,6 +2038,11 @@ export class TUI extends Container {
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
 
+		// Consume the component-scoped accumulation: it describes the render
+		// requests made up to this frame, whichever path the frame takes.
+		const componentScopedOnly = this.#pendingRenderComponentsOnly;
+		this.#pendingRenderComponentsOnly = false;
+
 		// Fullscreen alt-screen short-circuit. While the topmost visible overlay
 		// requests it, borrow the terminal's alternate buffer and paint only the
 		// modal there; the normal screen and all accounting stay untouched.
@@ -1907,15 +2069,32 @@ export class TUI extends Container {
 			}
 		}
 		if (this.#altActive) {
+			this.#componentRenderTargets.clear();
 			this.#renderAltFrame(width, height);
 			return;
 		}
 
 		// 1. Compose the frame. Bracket the render so the image budget observes
-		// every inline image in display order (overlays carry none).
-		this.#imageBudget.beginPass();
-		const rawFrame = this.render(width);
-		this.#imageBudget.endPass();
+		// every inline image in display order (overlays carry none). A
+		// component-scoped frame skips the budget pass instead — it is gated on
+		// a quiescent budget, and a partial tree walk would under-count display
+		// order — and re-renders only the requested root subtrees, reusing the
+		// previous segment of every other root child.
+		const partialRoots = componentScopedOnly ? this.#resolvePartialComposeRoots(width, height) : null;
+		this.#componentRenderTargets.clear();
+		let rawFrame: readonly string[];
+		if (partialRoots !== null) {
+			this.#partialComposeRoots = partialRoots;
+			try {
+				rawFrame = this.render(width);
+			} finally {
+				this.#partialComposeRoots = null;
+			}
+		} else {
+			this.#imageBudget.beginPass();
+			rawFrame = this.render(width);
+			this.#imageBudget.endPass();
+		}
 		// Ghostty initial-image deferral must run before any render state is
 		// consumed (#resizeEventPending, hardware-cursor state, commit
 		// re-anchoring): the early return abandons this frame and the deferred
@@ -1958,13 +2137,16 @@ export class TUI extends Container {
 		// composed frame's stable prefix covers every committed row — bytes
 		// that provably did not change since the last (aligned) frame cannot
 		// have diverged.
+		let committedRowsResynced = false;
 		if (
 			this.#hasEverRendered &&
 			!geometryChanged &&
 			!this.#clearScrollbackOnNextRender &&
 			this.#renderStablePrefixRows < this.#committedRows
 		) {
+			const committedRowsBeforeAudit = this.#committedRows;
 			this.#auditCommittedPrefix(rawFrame);
+			committedRowsResynced = this.#committedRows !== committedRowsBeforeAudit;
 		}
 
 		// 3. Window and commit math (lengths only; content prepared below).
@@ -1995,14 +2177,22 @@ export class TUI extends Container {
 		if (fullPaint) {
 			windowTop = Math.max(0, frameLength - height);
 			chunkTo = Math.min(commitBoundary, windowTop);
-		} else if (frameLength <= this.#committedRows) {
-			// The frame shrank into (or below) the committed prefix: the app
-			// replaced content it had already let scroll into history without
-			// requesting a session replace. History is immutable without a
-			// gesture, so the stale committed copy stays in scrollback;
-			// re-anchor the window at the tail and restart commit bookkeeping
-			// there so the live grid shows the real content instead of a blank
-			// pinned window.
+		} else if (
+			frameLength <= this.#committedRows ||
+			(committedRowsResynced &&
+				frameLength - this.#committedRows < height &&
+				cursorMarkers.some(marker => marker.row >= this.#committedRows))
+		) {
+			// Either the frame shrank into the committed prefix, or a
+			// committed-prefix resync left a focused cursor tail shorter than the
+			// viewport. The latter happens when a streaming/live block had an
+			// append-only prefix committed, then collapses on abort/finalize:
+			// the audit re-anchors #committedRows at the first divergent row, but
+			// flooring windowTop there would pin the editor near the top and
+			// leave blank rows underneath. Re-show the frame tail instead. The
+			// stale committed copy stays in native history; duplicating a few rows
+			// is preferable to a live editor gap and matches the existing
+			// "duplication, never loss" resync contract.
 			windowTop = Math.max(0, frameLength - height);
 			chunkTo = Math.min(commitBoundary, windowTop);
 			this.#committedRows = chunkTo;