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

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [15.11.2] - 2026-06-11
+
+### Fixed
+
+- Fixed Ctrl+C/exit corrupting the parent shell on Windows: `emergencyTerminalRestore()` wrote `\x1b[?1049l` (leave alternate screen) unconditionally on every exit path, and conhost/Windows Terminal execute an unconditional cursor restore for it even when the alt buffer was never entered — with no prior save the cursor jumped to the viewport home, so the shell prompt landed on top of the dead frame. The leave sequence is now gated on tracked alt-screen state (set/cleared by the TUI's fullscreen-overlay enter/leave and stop paths).
+- Skipped native syntax highlighting for transient markdown streaming renders, including nested list code blocks, leaving code blocks plain until their content stabilizes to avoid main-thread highlighter spikes.
+
+## [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/components/markdown.d.ts

@@ -49,13 +49,11 @@ export interface MarkdownTheme {
 }
 export declare class Markdown implements Component {
     #private;
-    /** When true, skip the module-level LRU (lookup and insert) for this instance's
-     *  renders. Set for in-flight streaming partials whose text changes every frame —
-     *  caching those churns the LRU with near-duplicate full-message snapshots. */
-    transientRenderCache: boolean;
     constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
     setText(text: string): void;
     invalidate(): void;
+    get transientRenderCache(): boolean;
+    set transientRenderCache(value: boolean);
     render(width: number): readonly string[];
 }
 /**

package/dist/types/terminal.d.ts

@@ -19,6 +19,8 @@
  * sole production caller.
  */
 export declare function chunkForConPTY(data: string, maxChunkBytes?: number): string[];
+/** Record alternate-screen state (called by the TUI on `?1049h`/`?1049l` writes). */
+export declare function setAltScreenActive(active: boolean): void;
 /**
  * Emergency terminal restore - call this from signal/crash handlers
  * Resets terminal state without requiring access to the ProcessTerminal instance

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.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.11.0",
-		"@oh-my-pi/pi-utils": "15.11.0",
+		"@oh-my-pi/pi-natives": "15.11.2",
+		"@oh-my-pi/pi-utils": "15.11.2",
 		"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/components/markdown.ts

@@ -295,10 +295,7 @@ export class Markdown implements Component {
 	#cachedText?: string;
 	#cachedWidth?: number;
 	#cachedLines?: readonly string[];
-	/** When true, skip the module-level LRU (lookup and insert) for this instance's
-	 *  renders. Set for in-flight streaming partials whose text changes every frame —
-	 *  caching those churns the LRU with near-duplicate full-message snapshots. */
-	transientRenderCache = false;
+	#transientRenderCache = false;
 
 	constructor(
 		text: string,
@@ -326,6 +323,16 @@ export class Markdown implements Component {
 		this.#cachedWidth = undefined;
 		this.#cachedLines = undefined;
 	}
+	get transientRenderCache(): boolean {
+		return this.#transientRenderCache;
+	}
+
+	set transientRenderCache(value: boolean) {
+		const next = value === true;
+		if (this.#transientRenderCache === next) return;
+		this.#transientRenderCache = next;
+		this.invalidate();
+	}
 
 	render(width: number): readonly string[] {
 		// L1: per-instance cache — fastest path for repeated renders of the same
@@ -618,7 +625,7 @@ export class Markdown implements Component {
 
 				const codeIndent = padding(this.#codeBlockIndent);
 				lines.push(this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`));
-				if (this.#theme.highlightCode) {
+				if (this.#theme.highlightCode && !this.transientRenderCache) {
 					const highlightedLines = this.#theme.highlightCode(token.text, token.lang);
 					for (const hlLine of highlightedLines) {
 						lines.push(`${codeIndent}${hlLine}`);
@@ -909,7 +916,7 @@ export class Markdown implements Component {
 				// Code block in list item
 				const codeIndent = padding(this.#codeBlockIndent);
 				lines.push({ text: this.#theme.codeBlockBorder(`\`\`\`${token.lang || ""}`), nested: false });
-				if (this.#theme.highlightCode) {
+				if (this.#theme.highlightCode && !this.transientRenderCache) {
 					const highlightedLines = this.#theme.highlightCode(token.text, token.lang);
 					for (const hlLine of highlightedLines) {
 						lines.push({ text: `${codeIndent}${hlLine}`, nested: false });

package/src/terminal.ts

@@ -122,6 +122,37 @@ export function chunkForConPTY(data: string, maxChunkBytes: number = MAX_CONPTY_
 let activeTerminal: ProcessTerminal | null = null;
 // Track if a terminal was ever started (for emergency restore logic)
 let terminalEverStarted = false;
+// Whether the alternate screen buffer is currently active (mirrors the TUI's
+// overlay enter/leave writes). Consulted by emergencyTerminalRestore: DECRST
+// 1049 must never be written blindly, because Windows' shared VT dispatcher
+// (conhost and Windows Terminal both use AdaptDispatch) executes an
+// unconditional cursor restore on it — with no prior DECSC save the cursor
+// jumps to the viewport home, dropping the parent shell prompt on top of the
+// dead frame after exit.
+let altScreenActive = false;
+
+/** Record alternate-screen state (called by the TUI on `?1049h`/`?1049l` writes). */
+export function setAltScreenActive(active: boolean): void {
+	altScreenActive = active;
+}
+
+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;
@@ -208,10 +239,15 @@ export function emergencyTerminalRestore(): void {
 		if (terminal) {
 			terminal.stop();
 			// stop() never touches the alternate screen — the TUI owns that
-			// state and exits it on the normal shutdown path. A crash while a
-			// fullscreen overlay is up would otherwise strand the shell on the
-			// alt buffer. Safe no-op when the alt screen is not active.
-			terminal.write("\x1b[?1049l");
+			// state and exits it on the normal shutdown path. Only crash paths
+			// with a fullscreen overlay still hold the alt buffer here. The
+			// leave sequence is gated on the tracked state because it is NOT a
+			// universally safe no-op: Windows' VT dispatcher homes the cursor
+			// on DECRST 1049 even when the alt buffer is inactive.
+			if (altScreenActive) {
+				terminal.write("\x1b[?1049l");
+				altScreenActive = false;
+			}
 			terminal.showCursor();
 		} else if (terminalEverStarted) {
 			// Blind restore only if we know a terminal was started but lost track of it
@@ -226,9 +262,14 @@ export function emergencyTerminalRestore(): void {
 					"\x1b[<u" + // Pop kitty keyboard protocol
 					"\x1b[>4;0m" + // Disable modifyOtherKeys fallback
 					"\x1b[?1006l\x1b[?1003l\x1b[?1000l" + // Disable mouse tracking (fullscreen overlays)
-					"\x1b[?1049l" + // Leave the alternate screen (fullscreen overlays)
+					// Leave the alternate screen only when a fullscreen overlay
+					// actually holds it — on Windows, DECRST 1049 on the main
+					// buffer homes the cursor (unconditional CursorRestoreState
+					// with no prior save), corrupting the shell handoff on exit.
+					(altScreenActive ? "\x1b[?1049l" : "") +
 					"\x1b[?25h", // Show cursor
 			);
+			altScreenActive = false;
 			if (process.stdin.setRawMode) {
 				process.stdin.setRawMode(false);
 			}
@@ -344,6 +385,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 +1228,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 +1258,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 +1278,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

@@ -16,7 +16,7 @@ import { $flag, getDebugLogPath } from "@oh-my-pi/pi-utils";
 import { DEFAULT_MAX_INLINE_IMAGES, ImageBudget } from "./components/image";
 import { planDeccaraFills } from "./deccara";
 import { isKeyRelease, matchesKey } from "./keys";
-import { isConPTYHosted, type Terminal } from "./terminal";
+import { isConPTYHosted, setAltScreenActive, type Terminal } from "./terminal";
 import {
 	encodeKittyDeleteImage,
 	ImageProtocol,
@@ -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;
@@ -1253,6 +1326,7 @@ export class TUI extends Container {
 		// the restored normal screen (which #previousLines still describes).
 		if (this.#altActive) {
 			this.terminal.write(`${MOUSE_TRACKING_OFF}\x1b[?1049l`);
+			setAltScreenActive(false);
 			this.#altActive = false;
 			this.#altPreviousLines = [];
 		}
@@ -1335,6 +1409,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 +1441,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 +1487,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 +1499,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 +1626,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,12 +2039,18 @@ 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.
 		const wantAlt = this.#wantsAltScreen();
 		if (wantAlt && !this.#altActive) {
 			this.terminal.write(`\x1b[?1049h${MOUSE_TRACKING_ON}`);
+			setAltScreenActive(true);
 			this.terminal.hideCursor();
 			this.#forgetHardwareCursorState();
 			this.#recordHardwareCursorHidden();
@@ -1896,6 +2060,7 @@ export class TUI extends Container {
 			this.#altEnterHeight = height;
 		} else if (!wantAlt && this.#altActive) {
 			this.terminal.write(`${MOUSE_TRACKING_OFF}\x1b[?1049l`);
+			setAltScreenActive(false);
 			this.#forgetHardwareCursorState();
 			this.#altActive = false;
 			this.#altPreviousLines = [];
@@ -1907,15 +2072,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 +2140,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 +2180,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;