@sayknow-cli/tui 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.7.8] - 2026-06-30
+
+### Fixed
+
+- The render loop now isolates a component whose `render()` throws: the failure is logged once and replaced with a `[render error: <Name>]` fallback line instead of escaping the frame and tripping the process-level fail-fast `uncaughtException` exit. Previously any unguarded renderer fault (e.g. a tool renderer fed an undefined field) crashed the whole app on whatever triggered the next frame — a keystroke, resize, or command such as `/background` (#1291).
+
+- Resolved terminal dimensions from the live TTY window size before stream defaults so wide Windows Terminal/PowerShell sessions render against the actual viewport width (#1239).
+
 ## [0.7.4] - 2026-06-27
 
 ### Fixed

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

@@ -39,6 +39,11 @@ export declare class Editor implements Component, Focusable {
     onChange?: (text: string) => void;
     onAutocompleteCancel?: () => void;
     onTabDeclined?: (text: string) => void;
+    /**
+     * Called before Tab opens/applies autocomplete. Return true to consume Tab
+     * for app-level behavior (for example, queueing a draft while a turn runs).
+     */
+    onTab?: (text: string) => boolean | undefined;
     disableSubmit: boolean;
     constructor(theme: EditorTheme);
     setAutocompleteProvider(provider: AutocompleteProvider): void;

package/dist/types/components/settings-list.d.ts

@@ -22,7 +22,7 @@ export interface SettingsListTheme {
 }
 export declare class SettingsList implements Component {
     #private;
-    constructor(items: SettingItem[], maxVisible: number, theme: SettingsListTheme, onChange: (id: string, newValue: string) => void, onCancel: () => void);
+    constructor(items: SettingItem[], maxVisible: number, theme: SettingsListTheme, onChange: (id: string, newValue: string) => void, onCancel: () => void, onSelectionChange?: (item: SettingItem | undefined) => void);
     /** Update an item's currentValue */
     updateValue(id: string, newValue: string): void;
     /**

package/dist/types/terminal.d.ts

@@ -52,6 +52,13 @@ export interface Terminal {
     /** The last detected terminal appearance, or undefined if not yet known. */
     get appearance(): TerminalAppearance | undefined;
 }
+interface TerminalSizeStream {
+    columns?: number;
+    rows?: number;
+    getWindowSize?: () => [number, number] | number[];
+}
+export declare function resolveTerminalColumns(stream?: TerminalSizeStream, envColumns?: string | undefined): number;
+export declare function resolveTerminalRows(stream?: TerminalSizeStream, envRows?: string | undefined): number;
 /**
  * Real terminal using process.stdin/stdout
  */
@@ -78,3 +85,4 @@ export declare class ProcessTerminal implements Terminal {
     setTitle(title: string): void;
     setProgress(active: boolean): void;
 }
+export {};

package/dist/types/tui.d.ts

@@ -157,6 +157,8 @@ export declare class TUI extends Container {
     setClearOnShrink(enabled: boolean): void;
     setFocus(component: Component | null): void;
     setBottomPinnedComponent(component: Component | null): void;
+    scrollViewportPages(direction: -1 | 1): boolean;
+    followLiveViewport(): boolean;
     /**
      * Show an overlay component with configurable positioning and sizing.
      * Returns a handle to control the overlay's visibility.
@@ -172,6 +174,19 @@ export declare class TUI extends Container {
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
     stop(): void;
+    /**
+     * Multiplexer-aware resize render request.
+     *
+     * A forced full redraw (`requestRender(true)`) resets `#previousWidth`/`#previousHeight`
+     * to -1, which makes `#doRender` treat the frame as a width change and fall into the
+     * `fullRender` path. In terminal multiplexers that path skips the scrollback-clearing
+     * `3J` escape (users navigate scrollback history), so replaying every transcript line
+     * piles it back on top of scrollback — the "top of screen scrolls down to the prompt at
+     * high speed" resize storm. Here we keep force off in multiplexers so `#doRender`'s
+     * height-change branch takes the viewport-only `multiplexerViewportRepaint` path instead.
+     * Set `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy forced redraw.
+     */
+    requestResizeRender(): void;
     requestRender(force?: boolean, source?: string): void;
     getLineRenderCacheStats(): {
         normalizationSize: number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.3.5",
+	"version": "0.3.7",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
 	"author": "jaybeyond",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.3.5",
-		"@sayknow-cli/utils": "0.3.5",
+		"@sayknow-cli/natives": "0.3.7",
+		"@sayknow-cli/utils": "0.3.7",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/editor.ts

@@ -450,6 +450,11 @@ export class Editor implements Component, Focusable {
 	onChange?: (text: string) => void;
 	onAutocompleteCancel?: () => void;
 	onTabDeclined?: (text: string) => void;
+	/**
+	 * Called before Tab opens/applies autocomplete. Return true to consume Tab
+	 * for app-level behavior (for example, queueing a draft while a turn runs).
+	 */
+	onTab?: (text: string) => boolean | undefined;
 	disableSubmit: boolean = false;
 
 	// Custom top border (for status line integration)
@@ -1080,6 +1085,10 @@ export class Editor implements Component, Focusable {
 			return;
 		}
 
+		if (kb.matches(data, "tui.input.tab") && this.onTab?.(this.getText())) {
+			return;
+		}
+
 		// Handle autocomplete special keys first (but don't block other input)
 		if (this.#autocompleteState && this.#autocompleteList) {
 			// Escape - cancel autocomplete
@@ -1147,7 +1156,7 @@ export class Editor implements Component, Focusable {
 					// Check for stale autocomplete state due to debounce
 					const currentLine = this.#state.lines[this.#state.cursorLine] ?? "";
 					const currentTextBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-					if (currentTextBeforeCursor !== this.#autocompletePrefix) {
+					if (!currentTextBeforeCursor.endsWith(this.#autocompletePrefix)) {
 						// Autocomplete is stale - cancel and fall through to normal submission
 						this.#cancelAutocomplete();
 					} else {
@@ -1285,8 +1294,8 @@ export class Editor implements Component, Focusable {
 				const currentLine = this.#state.lines[this.#state.cursorLine] ?? "";
 				const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
 				if (
-					textBeforeCursor.startsWith("/") &&
-					this.#isInSubmittedSlashCommandContext() &&
+					(this.#isInSubmittedSlashCommandContext() ||
+						this.#getSlashTokenBeforeCursor()?.startsWith("/skill") === true) &&
 					this.#autocompleteProvider?.trySyncSlashCompletion
 				) {
 					const syncResult = this.#autocompleteProvider.trySyncSlashCompletion(textBeforeCursor);
@@ -1509,10 +1518,34 @@ export class Editor implements Component, Focusable {
 					}
 
 					if (hasCursorInChunk) {
+						let displayChunkText = chunk.text;
+						let displayCursorPos = adjustedCursorPos;
+						if (displayCursorPos > displayChunkText.length) {
+							let hiddenWhitespaceWidth = displayCursorPos - displayChunkText.length;
+							const displayChunkWidth = visibleWidth(displayChunkText);
+							if (displayChunkWidth + hiddenWhitespaceWidth <= contentWidth) {
+								displayChunkText += padding(hiddenWhitespaceWidth);
+							} else {
+								layoutLines.push({
+									text: displayChunkText,
+									hasCursor: false,
+								});
+								hiddenWhitespaceWidth -= Math.max(0, contentWidth - displayChunkWidth);
+								while (hiddenWhitespaceWidth > contentWidth) {
+									layoutLines.push({
+										text: padding(contentWidth),
+										hasCursor: false,
+									});
+									hiddenWhitespaceWidth -= contentWidth;
+								}
+								displayChunkText = padding(hiddenWhitespaceWidth);
+								displayCursorPos = hiddenWhitespaceWidth;
+							}
+						}
 						layoutLines.push({
-							text: chunk.text,
+							text: displayChunkText,
 							hasCursor: true,
-							cursorPos: adjustedCursorPos,
+							cursorPos: displayCursorPos,
 						});
 					} else {
 						layoutLines.push({
@@ -1699,7 +1732,8 @@ export class Editor implements Component, Focusable {
 
 		// Check if we should trigger or update autocomplete
 		if (!this.#autocompleteState) {
-			// Auto-trigger for "/" at the start of a line (slash commands)
+			// Auto-trigger for "/" at the start of a submitted command.
+			// Inline skill autocomplete starts after the token becomes "/skill...".
 			if (char === "/" && this.#isAtStartOfSubmittedMessage()) {
 				this.#tryTriggerAutocomplete();
 			}
@@ -1721,8 +1755,8 @@ export class Editor implements Component, Focusable {
 			else if (/[a-zA-Z0-9.\-_/]/.test(char)) {
 				const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 				const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-				// Check if we're in a slash command (with or without space for arguments)
-				if (this.#isInSubmittedSlashCommandContext()) {
+				// Check if we're in a slash command or inline slash token
+				if (this.#isInSubmittedSlashCommandContext() || this.#isInSlashTokenContext()) {
 					this.#tryTriggerAutocomplete();
 				}
 				// Check if we're in an @ file reference context
@@ -1917,8 +1951,8 @@ export class Editor implements Component, Focusable {
 			// If autocomplete was cancelled (no matches), re-trigger if we're in a completable context
 			const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 			const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-			// Slash command context
-			if (this.#isInSubmittedSlashCommandContext()) {
+			// Slash command or inline slash token context
+			if (this.#isInSubmittedSlashCommandContext() || this.#isInSlashTokenContext()) {
 				this.#tryTriggerAutocomplete();
 			}
 			// @ file reference context
@@ -2074,7 +2108,7 @@ export class Editor implements Component, Focusable {
 		} else {
 			const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 			const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-			if (this.#isInSubmittedSlashCommandContext()) {
+			if (this.#isInSubmittedSlashCommandContext() || this.#isInSlashTokenContext()) {
 				this.#tryTriggerAutocomplete();
 			} else if (textBeforeCursor.match(/(?:^|[\s])@[^\s]*$/)) {
 				this.#tryTriggerAutocomplete();
@@ -2388,8 +2422,8 @@ export class Editor implements Component, Focusable {
 		} else {
 			const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 			const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-			// Slash command context
-			if (this.#isInSubmittedSlashCommandContext()) {
+			// Slash command or inline slash token context
+			if (this.#isInSubmittedSlashCommandContext() || this.#isInSlashTokenContext()) {
 				this.#tryTriggerAutocomplete();
 			}
 			// @ file reference context
@@ -2618,6 +2652,17 @@ export class Editor implements Component, Focusable {
 		return this.#hasOnlyWhitespaceBeforeCursorLine() && beforeCursor.trimStart().startsWith("/");
 	}
 
+	#getSlashTokenBeforeCursor(): string | null {
+		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
+		const beforeCursor = currentLine.slice(0, this.#state.cursorCol);
+		const match = beforeCursor.match(/(?:^|\s)(\/[^\s]*)$/);
+		return match?.[1] ?? null;
+	}
+
+	#isInSlashTokenContext(): boolean {
+		return this.#getSlashTokenBeforeCursor()?.startsWith("/skill") === true;
+	}
+
 	#isSlashCommandNameAutocompleteSelection(): boolean {
 		if (this.#autocompleteState !== "regular") {
 			return false;

package/src/components/input.ts

@@ -58,7 +58,8 @@ export class Input implements Component, Focusable {
 	setValue(value: string): void {
 		const normalized = value.normalize("NFC");
 		this.#value = normalized;
-		this.#cursor = Math.min(this.#cursor, normalized.length);
+		this.#cursor = normalized.length;
+		this.#lastAction = null;
 	}
 
 	handleInput(data: string): void {

package/src/components/select-list.ts

@@ -117,8 +117,15 @@ export class SelectList implements Component {
 	}
 
 	handleInput(keyData: string): void {
-		if (this.#filteredItems.length === 0) return;
 		const kb = getKeybindings();
+		if (this.#filteredItems.length === 0) {
+			if (kb.matches(keyData, "tui.select.cancel")) {
+				if (this.onCancel) {
+					this.onCancel();
+				}
+			}
+			return;
+		}
 		// Up arrow - wrap to bottom when at top
 		if (kb.matches(keyData, "tui.select.up")) {
 			this.#selectedIndex = this.#selectedIndex === 0 ? this.#filteredItems.length - 1 : this.#selectedIndex - 1;

package/src/components/settings-list.ts

@@ -32,6 +32,7 @@ export class SettingsList implements Component {
 	#maxVisible: number;
 	#onChange: (id: string, newValue: string) => void;
 	#onCancel: () => void;
+	#onSelectionChange?: (item: SettingItem | undefined) => void;
 
 	// Submenu state
 	#submenuComponent: Component | null = null;
@@ -43,12 +44,15 @@ export class SettingsList implements Component {
 		theme: SettingsListTheme,
 		onChange: (id: string, newValue: string) => void,
 		onCancel: () => void,
+		onSelectionChange?: (item: SettingItem | undefined) => void,
 	) {
 		this.#items = items;
 		this.#maxVisible = maxVisible;
 		this.#theme = theme;
 		this.#onChange = onChange;
 		this.#onCancel = onCancel;
+		this.#onSelectionChange = onSelectionChange;
+		this.#notifySelectionChange();
 	}
 
 	/** Update an item's currentValue */
@@ -73,12 +77,17 @@ export class SettingsList implements Component {
 		} else if (this.#selectedIndex >= this.#items.length) {
 			this.#selectedIndex = this.#items.length - 1;
 		}
+		this.#notifySelectionChange();
 	}
 
 	invalidate(): void {
 		this.#submenuComponent?.invalidate?.();
 	}
 
+	#notifySelectionChange(): void {
+		this.#onSelectionChange?.(this.#items[this.#selectedIndex]);
+	}
+
 	render(width: number): string[] {
 		// If submenu is active, render it instead
 		if (this.#submenuComponent) {
@@ -167,8 +176,10 @@ export class SettingsList implements Component {
 		const kb = getKeybindings();
 		if (kb.matches(data, "tui.select.up")) {
 			this.#selectedIndex = this.#selectedIndex === 0 ? this.#items.length - 1 : this.#selectedIndex - 1;
+			this.#notifySelectionChange();
 		} else if (kb.matches(data, "tui.select.down")) {
 			this.#selectedIndex = this.#selectedIndex === this.#items.length - 1 ? 0 : this.#selectedIndex + 1;
+			this.#notifySelectionChange();
 		} else if (kb.matches(data, "tui.select.confirm") || data === " " || data === "\n") {
 			this.#activateItem();
 		} else if (kb.matches(data, "tui.select.cancel")) {
@@ -206,6 +217,7 @@ export class SettingsList implements Component {
 		if (this.#submenuItemIndex !== null) {
 			this.#selectedIndex = this.#submenuItemIndex;
 			this.#submenuItemIndex = null;
+			this.#notifySelectionChange();
 		}
 	}
 }

package/src/terminal.ts

@@ -164,9 +164,50 @@ export interface Terminal {
 	get appearance(): TerminalAppearance | undefined;
 }
 
+interface TerminalSizeStream {
+	columns?: number;
+	rows?: number;
+	getWindowSize?: () => [number, number] | number[];
+}
+
+function positiveDimension(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+	const dimension = Math.trunc(value);
+	return dimension > 0 ? dimension : undefined;
+}
+
+export function resolveTerminalColumns(
+	stream: TerminalSizeStream = process.stdout,
+	envColumns: string | undefined = Bun.env.COLUMNS,
+): number {
+	try {
+		const windowSize = stream.getWindowSize?.();
+		const liveColumns = positiveDimension(windowSize?.[0]);
+		if (liveColumns !== undefined) return liveColumns;
+	} catch {
+		// Fall back below when the stream cannot report a live TTY size.
+	}
+	return positiveDimension(stream.columns) ?? positiveDimension(Number(envColumns)) ?? 80;
+}
+
+export function resolveTerminalRows(
+	stream: TerminalSizeStream = process.stdout,
+	envRows: string | undefined = Bun.env.LINES,
+): number {
+	try {
+		const windowSize = stream.getWindowSize?.();
+		const liveRows = positiveDimension(windowSize?.[1]);
+		if (liveRows !== undefined) return liveRows;
+	} catch {
+		// Fall back below when the stream cannot report a live TTY size.
+	}
+	return positiveDimension(stream.rows) ?? positiveDimension(Number(envRows)) ?? 24;
+}
+
 function isWindowsSubsystemForLinux(): boolean {
 	return process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
 }
+const STDOUT_ERROR_HANDLER_GRACE_MS = 250;
 
 /**
  * Real terminal using process.stdin/stdout
@@ -185,6 +226,7 @@ export class ProcessTerminal implements Terminal {
 	#detachLogPath = $env.PI_TUI_TERMINAL_DETACH_LOG || "";
 	#windowsVTInputRestore?: () => void;
 	#stdoutErrorHandler?: (err: Error) => void;
+	#stdoutErrorHandlerCleanupTimer?: Timer;
 	#appearanceCallbacks: Array<(appearance: TerminalAppearance) => void> = [];
 	#appearance: TerminalAppearance | undefined;
 	#osc11Pending = false;
@@ -237,10 +279,16 @@ export class ProcessTerminal implements Terminal {
 
 		// Set up resize handler immediately
 		process.stdout.on("resize", this.#resizeHandler);
-		this.#stdoutErrorHandler = (err: Error) => {
-			this.#markUnavailable(err, "stdout-error");
-		};
-		process.stdout.on("error", this.#stdoutErrorHandler);
+		if (this.#stdoutErrorHandlerCleanupTimer) {
+			clearTimeout(this.#stdoutErrorHandlerCleanupTimer);
+			this.#stdoutErrorHandlerCleanupTimer = undefined;
+		}
+		if (!this.#stdoutErrorHandler) {
+			this.#stdoutErrorHandler = (err: Error) => {
+				this.#markUnavailable(err, "stdout-error");
+			};
+			process.stdout.on("error", this.#stdoutErrorHandler);
+		}
 
 		// Refresh terminal dimensions - they may be stale after suspend/resume
 		// (SIGWINCH is lost while process is stopped). Unix only.
@@ -582,6 +630,20 @@ export class ProcessTerminal implements Terminal {
 			return;
 		}
 		this.#safeWrite("\x1b[?u");
+		// Windows Terminal and conhost do not implement the Kitty keyboard
+		// protocol, so the query above never activates it there. They do honor the
+		// modifyOtherKeys fallback below — but that mode breaks Windows CJK/Hangul
+		// IME composition: Alt+Enter (and other chords) bypass the IME commit, so
+		// the syllable still being composed is never delivered to the app and the
+		// action fires on empty text (e.g. queue-message no-ops unless the user
+		// types a trailing space to force a commit first). Skip the fallback on
+		// win32; legacy encodings still deliver Alt+Enter (ESC CR) and the newline
+		// chords, and IME composition works again. Opt back in with
+		// SKC_TUI_KEYBOARD_PROTOCOL=0 disabling all enhancement, or force-enable
+		// elsewhere if a Kitty-capable Windows terminal appears.
+		if (process.platform === "win32") {
+			return;
+		}
 		this.#modifyOtherKeysTimeout = setTimeout(() => {
 			this.#modifyOtherKeysTimeout = undefined;
 			if (this.#kittyProtocolActive || this.#modifyOtherKeysActive) {
@@ -696,10 +758,7 @@ export class ProcessTerminal implements Terminal {
 			process.stdout.removeListener("resize", this.#resizeHandler);
 			this.#resizeHandler = undefined;
 		}
-		if (this.#stdoutErrorHandler) {
-			process.stdout.removeListener("error", this.#stdoutErrorHandler);
-			this.#stdoutErrorHandler = undefined;
-		}
+		this.#scheduleStdoutErrorHandlerCleanup();
 
 		// Pause stdin to prevent any buffered input (e.g., Ctrl+D) from being
 		// re-interpreted after raw mode is disabled. This fixes a race condition
@@ -712,6 +771,23 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
+	#scheduleStdoutErrorHandlerCleanup(): void {
+		if (!this.#stdoutErrorHandler) return;
+		if (this.#stdoutErrorHandlerCleanupTimer) clearTimeout(this.#stdoutErrorHandlerCleanupTimer);
+		// Terminal restore writes above can fail asynchronously after stop() returns
+		// when an SSH/Windows Terminal PTY disappears. Keep the stdout error listener
+		// armed briefly so late EIO/EPIPE events mark the terminal unavailable instead
+		// of surfacing as uncaught exceptions that kill the tmux pane.
+		this.#stdoutErrorHandlerCleanupTimer = setTimeout(() => {
+			if (this.#stdoutErrorHandler) {
+				process.stdout.removeListener("error", this.#stdoutErrorHandler);
+				this.#stdoutErrorHandler = undefined;
+			}
+			this.#stdoutErrorHandlerCleanupTimer = undefined;
+		}, STDOUT_ERROR_HANDLER_GRACE_MS);
+		this.#stdoutErrorHandlerCleanupTimer.unref?.();
+	}
+
 	write(data: string): void {
 		this.#safeWrite(data);
 		if (this.#writeLogPath) {
@@ -789,11 +865,11 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	get columns(): number {
-		return process.stdout.columns || Number(Bun.env.COLUMNS) || 80;
+		return resolveTerminalColumns();
 	}
 
 	get rows(): number {
-		return process.stdout.rows || Number(Bun.env.LINES) || 24;
+		return resolveTerminalRows();
 	}
 
 	moveBy(lines: number): void {

package/src/tui.ts

@@ -4,7 +4,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
-import { $flag, getDebugLogPath } from "@sayknow-cli/utils";
+import { $flag, getDebugLogPath, logger } from "@sayknow-cli/utils";
 import { getKeybindings } from "./keybindings";
 import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
@@ -257,7 +257,7 @@ export class Container implements Component {
 		width = Math.max(1, width);
 		const lines: string[] = [];
 		for (const child of this.children) {
-			const childLines = child.render(width);
+			const childLines = safeRenderComponent(child, width, "container-child");
 			for (let i = 0; i < childLines.length; i++) {
 				lines.push(childLines[i]);
 			}
@@ -266,6 +266,40 @@ export class Container implements Component {
 	}
 }
 
+const MAX_REPORTED_RENDER_ERRORS = 200;
+const reportedRenderErrors = new Set<string>();
+
+/**
+ * Render a component's lines without letting a thrown error escape the frame.
+ *
+ * The TUI render loop ({@link TUI.#doRender}) runs inside a `nextTick`/`setTimeout`
+ * with no try/catch, and the process installs a fail-fast `uncaughtException`
+ * handler that exits. So a single component whose `render()` throws (e.g. a tool
+ * renderer fed an optional/undefined field) used to take down the whole app —
+ * fatal on whatever happened to trigger the frame (a keystroke, resize, or a
+ * command such as `/background`). Isolate the failure: log it once, emit a
+ * visible fallback line, and keep rendering the rest of the tree.
+ */
+function safeRenderComponent(component: Component, width: number, where: string): string[] {
+	try {
+		return component.render(width);
+	} catch (err) {
+		const name = component?.constructor?.name ?? "Component";
+		const key = `${where}:${name}:${err instanceof Error ? err.message : String(err)}`;
+		if (!reportedRenderErrors.has(key)) {
+			if (reportedRenderErrors.size >= MAX_REPORTED_RENDER_ERRORS) reportedRenderErrors.clear();
+			reportedRenderErrors.add(key);
+			logger.error("Component render failed; emitting fallback line", {
+				where,
+				component: name,
+				error: err instanceof Error ? err.message : String(err),
+				stack: err instanceof Error ? err.stack : undefined,
+			});
+		}
+		return [`[render error: ${name}]`];
+	}
+}
+
 type LineNormalizationCacheEntry = {
 	normalized: string;
 	terminated: string;
@@ -307,6 +341,8 @@ export class TUI extends Container {
 	#cursorRow = 0; // Logical cursor row (end of rendered content)
 	#hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
 	#viewportTopRow = 0; // Content row currently mapped to screen row 0
+	#manualViewportTop: number | undefined;
+	#lastCursorPosition: { row: number; col: number } | null = null;
 	#sixelProbePendingDa = false;
 	#sixelProbePendingGraphics = false;
 	#sixelProbeBuffer = "";
@@ -393,6 +429,47 @@ export class TUI extends Container {
 		this.#bottomPinnedComponent = component;
 		this.requestRender();
 	}
+	scrollViewportPages(direction: -1 | 1): boolean {
+		const height = this.terminal.rows;
+		const width = this.terminal.columns;
+		if (height <= 0 || width <= 0 || this.#previousLines.length === 0) return false;
+		const maxViewportTop = Math.max(0, this.#previousLines.length - height);
+		const currentViewportTop = Math.max(0, Math.min(maxViewportTop, this.#manualViewportTop ?? this.#viewportTopRow));
+		const pageStep = Math.max(1, height - 1);
+		const targetViewportTop = Math.max(0, Math.min(maxViewportTop, currentViewportTop + direction * pageStep));
+
+		if (targetViewportTop >= maxViewportTop) {
+			this.#manualViewportTop = undefined;
+		} else {
+			this.#manualViewportTop = targetViewportTop;
+		}
+
+		const cursorPos = this.#manualViewportTop === undefined ? this.#lastCursorPosition : null;
+		return this.#repaintViewportFromLines(
+			this.#previousLines,
+			width,
+			height,
+			targetViewportTop,
+			cursorPos,
+			"manual viewport scroll",
+		);
+	}
+
+	followLiveViewport(): boolean {
+		if (this.#manualViewportTop === undefined) return false;
+		const height = this.terminal.rows;
+		const width = this.terminal.columns;
+		const liveViewportTop = Math.max(0, this.#previousLines.length - height);
+		this.#manualViewportTop = undefined;
+		return this.#repaintViewportFromLines(
+			this.#previousLines,
+			width,
+			height,
+			liveViewportTop,
+			this.#lastCursorPosition,
+			"manual viewport follow live",
+		);
+	}
 
 	/**
 	 * Show an overlay component with configurable positioning and sizing.
@@ -492,7 +569,7 @@ export class TUI extends Container {
 			data => this.#handleInput(data),
 			() => {
 				this.invalidate();
-				this.requestRender(!(isMultiplexerSession() && !useLegacyMultiplexerFullRender()), "resize");
+				this.requestResizeRender();
 			},
 		);
 		this.#hideCursor();
@@ -736,6 +813,22 @@ export class TUI extends Container {
 		this.#previousHeight = 0;
 	}
 
+	/**
+	 * Multiplexer-aware resize render request.
+	 *
+	 * A forced full redraw (`requestRender(true)`) resets `#previousWidth`/`#previousHeight`
+	 * to -1, which makes `#doRender` treat the frame as a width change and fall into the
+	 * `fullRender` path. In terminal multiplexers that path skips the scrollback-clearing
+	 * `3J` escape (users navigate scrollback history), so replaying every transcript line
+	 * piles it back on top of scrollback — the "top of screen scrolls down to the prompt at
+	 * high speed" resize storm. Here we keep force off in multiplexers so `#doRender`'s
+	 * height-change branch takes the viewport-only `multiplexerViewportRepaint` path instead.
+	 * Set `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy forced redraw.
+	 */
+	requestResizeRender(): void {
+		this.requestRender(!(isMultiplexerSession() && !useLegacyMultiplexerFullRender()), "resize");
+	}
+
 	requestRender(force = false, source = "unknown"): void {
 		if (!this.terminalAvailable) {
 			this.#markTerminalUnavailable();
@@ -1071,7 +1164,7 @@ export class TUI extends Container {
 			const { width, maxHeight } = this.#resolveOverlayLayout(options, 0, termWidth, termHeight);
 
 			// Render component at calculated width
-			let overlayLines = component.render(width);
+			let overlayLines = safeRenderComponent(component, width, "overlay");
 
 			// Apply maxHeight if specified
 			if (maxHeight !== undefined && overlayLines.length > maxHeight) {
@@ -1302,7 +1395,7 @@ export class TUI extends Container {
 
 		let pinnedLineCount = 0;
 		for (let i = pinnedStart; i < this.children.length; i++) {
-			pinnedLineCount += this.children[i].render(this.terminal.columns).length;
+			pinnedLineCount += safeRenderComponent(this.children[i], this.terminal.columns, "pinned").length;
 		}
 
 		const blankRows = height - lines.length;
@@ -1311,6 +1404,64 @@ export class TUI extends Container {
 		padded.splice(insertAt, 0, ...Array.from({ length: blankRows }, () => ""));
 		return padded;
 	}
+	#repaintViewportFromLines(
+		lines: string[],
+		width: number,
+		height: number,
+		viewportTop: number,
+		cursorPos: { row: number; col: number } | null,
+		reason: string,
+	): boolean {
+		if (height <= 0 || width <= 0) return false;
+		const maxViewportTop = Math.max(0, lines.length - height);
+		const nextViewportTop = Math.max(0, Math.min(maxViewportTop, viewportTop));
+		const currentScreenRow = Math.max(0, Math.min(height - 1, this.#hardwareCursorRow - this.#viewportTopRow));
+		let buffer = "\x1b[?2026h";
+		if (currentScreenRow > 0) {
+			buffer += `\x1b[${currentScreenRow}A`;
+		}
+		buffer += "\r";
+
+		for (let screenRow = 0; screenRow < height; screenRow++) {
+			if (screenRow > 0) buffer += "\r\n";
+			buffer += "\x1b[2K";
+			const lineIndex = nextViewportTop + screenRow;
+			if (lineIndex >= lines.length) continue;
+			const line = lines[lineIndex];
+			const isImage = TERMINAL.isImageLine(line);
+			if (!isImage && visibleWidth(line) > width) {
+				let truncatedLine = truncateToWidth(line, width, Ellipsis.Omit);
+				truncatedLine += truncatedLine.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET;
+				buffer += truncatedLine;
+			} else {
+				buffer += line;
+			}
+		}
+
+		const finalPhysicalRow = nextViewportTop + Math.max(0, height - 1);
+		let cursorSeq = "\x1b[?25l";
+		let cursorToRow = finalPhysicalRow;
+		if (cursorPos && cursorPos.row >= nextViewportTop && cursorPos.row < nextViewportTop + height) {
+			const cursor = this.#cursorControlSequence(cursorPos, lines.length, finalPhysicalRow);
+			cursorSeq = cursor.seq;
+			cursorToRow = cursor.toRow;
+		}
+		this.#hardwareCursorRow = cursorToRow;
+		buffer += cursorSeq;
+		buffer += "\x1b[?2026l";
+		if (!this.#writeTerminal(buffer)) return false;
+
+		if ($flag("PI_DEBUG_REDRAW")) {
+			const logPath = getDebugLogPath();
+			const msg = `[${new Date().toISOString()}] viewportRepaint: ${reason} (lines=${lines.length}, height=${height}, viewportTop=${nextViewportTop})\n`;
+			fs.appendFileSync(logPath, msg);
+		}
+
+		this.#cursorRow = Math.max(0, lines.length - 1);
+		this.#maxLinesRendered = lines.length;
+		this.#viewportTopRow = nextViewportTop;
+		return true;
+	}
 
 	#doRender(): void {
 		if (this.#stopped || !this.terminalAvailable) return;
@@ -1341,6 +1492,7 @@ export class TUI extends Container {
 
 		// Extract cursor position (marker must be found before diff comparison)
 		const cursorPos = this.#extractCursorPosition(newLines, height);
+		this.#lastCursorPosition = cursorPos;
 
 		// Terminate every non-image line so #previousLines mirrors emitted bytes
 		// (closes SGR + OSC 8 hyperlink state). Must run after cursor extraction
@@ -1401,6 +1553,28 @@ export class TUI extends Container {
 			if (usedWindowNormalize) renderMetrics.recordLineCount("offscreenScan", diffStart);
 		}
 
+		if (this.#manualViewportTop !== undefined) {
+			const maxViewportTop = Math.max(0, newLines.length - height);
+			const nextViewportTop = Math.max(0, Math.min(maxViewportTop, this.#manualViewportTop));
+			const followingLive = nextViewportTop >= maxViewportTop;
+			this.#manualViewportTop = followingLive ? undefined : nextViewportTop;
+			const repaintCursorPos = followingLive ? cursorPos : null;
+			if (
+				this.#repaintViewportFromLines(
+					newLines,
+					width,
+					height,
+					nextViewportTop,
+					repaintCursorPos,
+					"manual viewport render",
+				)
+			) {
+				this.#previousLines = newLines;
+				this.#previousWidth = width;
+				this.#previousHeight = height;
+			}
+			return;
+		}
 		// Helper to clear scrollback and viewport and render all new lines
 		const fullRender = (clear: boolean, reason = "full render"): void => {
 			this.#fullRedrawCount += 1;
@@ -1506,7 +1680,16 @@ export class TUI extends Container {
 		// Width changes always need a full re-render because wrapping changes.
 		if (widthChanged) {
 			logRedraw(`terminal width changed (${this.#previousWidth} -> ${width})`);
-			fullRender(true, "terminal width changed");
+			if (isMultiplexerSession() && !useLegacyMultiplexerFullRender()) {
+				// In multiplexers a full replay piles the whole transcript back onto
+				// scrollback (3J is intentionally skipped). Repaint the viewport only,
+				// mirroring the height-change branch. This also neutralizes the fake
+				// width change that requestRender(true) injects via #previousWidth = -1,
+				// so every force-render call site is safe in multiplexers too.
+				multiplexerViewportRepaint(`terminal width changed (${this.#previousWidth} -> ${width})`);
+			} else {
+				fullRender(true, "terminal width changed");
+			}
 			return;
 		}