@oh-my-pi/pi-tui 15.9.5 → 15.9.67

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [15.9.67] - 2026-06-06
+### Added
+
+- Added `setPaddingX` to `Box` so horizontal padding can be updated programmatically after creation
+- Added `ScrollView`, a fixed-height viewport component for pre-rendered lines with optional right-edge scrollbars and imperative scroll/page controls.
+- Added optional `Terminal.hasEagerEraseScrollbackRisk()` so custom/test terminal implementations can override the global ED3-risk profile without mutating the shared `TERMINAL` object.
+
+### Changed
+
+- Changed `SelectList` to render its visible window through `ScrollView`, replacing the `(N/M)` text scroll indicator with a uniform right-edge scrollbar (the type-to-search hint line is preserved).
+
+### Fixed
+
+- Fixed unknown-viewport deferred renders freezing bottom-anchored live chrome; deferred history mutations can now repaint only the active-grid bottom row with relative cursor movement, so spinner/status tails keep advancing without rewriting rows a scrolled reader can still see.
+- Fixed autocomplete popups freezing live repaint on ED3-risk macOS/POSIX terminals with unknown native viewport position; direct autocomplete shrink frames now repaint the live viewport without zero-byte deferral and preserve the old bottom anchor when padding can clear stale popup rows without duplicating committed scrollback.
+- Fixed focused Up/Down navigation on ED3-risk macOS/POSIX terminals replaying the whole transcript after dirty foreground-stream renders; selector/editor frames now repaint non-destructively instead of emitting `CSI 3 J` on every arrow-key move ([#1962](https://github.com/can1357/oh-my-pi/issues/1962)).
+- Fixed tmux (and screen/zellij) pane scrollback losing the head of a long streamed assistant reply once it grew past the visible pane, and stranding the chrome/footer in pane history after a later collapse — producing the "repeating chunks and missing sections" reporters saw when scrolling back through tmux pane history ([#1974](https://github.com/can1357/oh-my-pi/issues/1974)). The renderer's foreground-streaming cap-to-viewport branch (introduced in 15.9.2 for ED3-risk hosts that can checkpoint-rebuild later) also activated inside multiplexers, where checkpoint reconcile is a no-op (`refreshNativeScrollbackIfDirty` short-circuits because `\x1b[3J` cannot erase pane history). Every streaming frame clipped `lines` to the visible tail and reset `#scrollbackHighWater` to 0, so any row that scrolled above the viewport top was committed nowhere — pane history stayed empty until streaming ended. Meanwhile `#planLiveRegionPinnedRender` was explicitly disabled for multiplexers, but its `#emitLiveRegionPinnedRepaint` is built from the exact primitives tmux accepts (relative cursor moves, per-line `\x1b[2K`, `\r\n` to scroll the sealed prefix past the viewport bottom) and never emits `\x1b[2J`/`\x1b[3J`. The pinned planner now runs in multiplexers too, the cap branch skips them, and the diff/append path commits incrementally into pane history; the actively-mutating live tail stays in the visible viewport only.
+
 ## [15.9.5] - 2026-06-05
 
 ### Changed
@@ -13,6 +31,7 @@
 - Fixed ED3-risk foreground streaming dropping the scrolled-off head of an append-only live block that alone overflows the viewport (a long streamed assistant reply). The live-region pin again committed native scrollback only up to the live-region start, so once the live block grew past the viewport its earlier rows scrolled above the viewport top but were committed nowhere and repainted nowhere — they vanished, leaving the reply looking like a ~viewport-tall circular buffer. The `NativeScrollbackLiveRegion` seam now also reports an optional append-only `getNativeScrollbackCommitSafeEnd`, and the pinned commit boundary is the deeper of the sealed start and that append-only end: rows in `[liveRegionStart, commitSafeEnd)` above the viewport top commit to scrollback, while volatile live blocks (tool previews that collapse) omit the boundary and keep their mutable rows deferred — preserving the pending-box-above-running-box fix.
 
 ## [15.9.4] - 2026-06-05
+
 ### Added
 
 - Added `PI_TUI_SYNC_OUTPUT=0` and `PI_TUI_SYNC_OUTPUT=1` to explicitly disable or force-enable DEC 2026 synchronized-output mode, alongside `PI_FORCE_SYNC_OUTPUT=1` as a force-on alias

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

@@ -9,6 +9,7 @@ export declare class Box implements Component {
     addChild(component: Component): void;
     removeChild(component: Component): void;
     clear(): void;
+    setPaddingX(paddingX: number): void;
     setBgFn(bgFn?: (text: string) => string): void;
     invalidate(): void;
     render(width: number): string[];

package/dist/types/components/scroll-view.d.ts

@@ -0,0 +1,40 @@
+import type { Component } from "../tui";
+type ScrollbarMode = "auto" | "always" | "never";
+export interface ScrollViewTheme {
+    track?: (text: string) => string;
+    thumb?: (text: string) => string;
+}
+export interface ScrollViewOptions {
+    height: number;
+    /** Defaults to "auto". "auto" reserves a scrollbar column only when content overflows. */
+    scrollbar?: ScrollbarMode | boolean;
+    /** Logical row count for pre-windowed line slices. Defaults to lines.length. */
+    totalRows?: number;
+    theme?: ScrollViewTheme;
+    trackChar?: string;
+    thumbChar?: string;
+}
+/**
+ * Fixed-height viewport over pre-rendered lines, with optional right-edge scrollbar.
+ *
+ * ScrollView owns only the row offset. Callers remain responsible for producing
+ * already-wrapped logical lines appropriate for the current render width.
+ */
+export declare class ScrollView implements Component {
+    #private;
+    constructor(lines: readonly string[], options: ScrollViewOptions);
+    setLines(lines: readonly string[]): void;
+    setTotalRows(totalRows: number | undefined): void;
+    setHeight(height: number): void;
+    setScrollbar(scrollbar: ScrollViewOptions["scrollbar"]): void;
+    getScrollOffset(): number;
+    getMaxScrollOffset(): number;
+    setScrollOffset(offset: number): void;
+    scroll(delta: number): void;
+    page(delta: number): void;
+    scrollToTop(): void;
+    scrollToBottom(): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+export {};

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from "./components/image";
 export * from "./components/input";
 export * from "./components/loader";
 export * from "./components/markdown";
+export * from "./components/scroll-view";
 export * from "./components/select-list";
 export * from "./components/settings-list";
 export * from "./components/spacer";

package/dist/types/terminal.d.ts

@@ -58,6 +58,11 @@ export interface Terminal {
      * (xterm.js-backed) implement this with a real answer.
      */
     isNativeViewportAtBottom?(): boolean | undefined;
+    /**
+     * Override the global terminal-profile ED3 risk decision for custom/test
+     * terminals. `undefined` falls back to the resolved `TERMINAL` profile.
+     */
+    hasEagerEraseScrollbackRisk?(): boolean | undefined;
     /**
      * Register a callback for terminal appearance (dark/light) changes.
      * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.

package/dist/types/tui.d.ts

@@ -231,8 +231,8 @@ export declare class TUI extends Container {
      * (the viewport is never observable there and ConPTY hosts erase host
      * scrollback on ED3 — #1635/#1746); only the unknown POSIX case is forced to
      * rebuild. POSIX hosts known to disturb scrolled readers on xterm ED3
-     * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint and
-     * direct user-input rebuilds are unaffected.
+     * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint
+     * rebuilds are unaffected.
      *
      * Disabling stays active through one already-requested frame: the event batch
      * that ends a foreground stream both removes its UI rows (loader/status

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.9.5",
+	"version": "15.9.67",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.9.5",
-		"@oh-my-pi/pi-utils": "15.9.5",
+		"@oh-my-pi/pi-natives": "15.9.67",
+		"@oh-my-pi/pi-utils": "15.9.67",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/box.ts

@@ -42,6 +42,12 @@ export class Box implements Component {
 		this.#invalidateCache();
 	}
 
+	setPaddingX(paddingX: number): void {
+		if (this.#paddingX === paddingX) return;
+		this.#paddingX = paddingX;
+		this.#invalidateCache();
+	}
+
 	setBgFn(bgFn?: (text: string) => string): void {
 		this.#bgFn = bgFn;
 		// Don't invalidate here - we'll detect bgFn changes by sampling output

package/src/components/scroll-view.ts

@@ -0,0 +1,166 @@
+import type { Component } from "../tui";
+import { Ellipsis, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
+
+const DEFAULT_TRACK = "│";
+const DEFAULT_THUMB = "█";
+
+type ScrollbarMode = "auto" | "always" | "never";
+
+export interface ScrollViewTheme {
+	track?: (text: string) => string;
+	thumb?: (text: string) => string;
+}
+
+export interface ScrollViewOptions {
+	height: number;
+	/** Defaults to "auto". "auto" reserves a scrollbar column only when content overflows. */
+	scrollbar?: ScrollbarMode | boolean;
+	/** Logical row count for pre-windowed line slices. Defaults to lines.length. */
+	totalRows?: number;
+	theme?: ScrollViewTheme;
+	trackChar?: string;
+	thumbChar?: string;
+}
+
+function normalizeScrollbarMode(scrollbar: ScrollViewOptions["scrollbar"]): ScrollbarMode {
+	if (scrollbar === true) return "auto";
+	if (scrollbar === false) return "never";
+	return scrollbar ?? "auto";
+}
+
+function firstCellGlyph(value: string, fallback: string): string {
+	const glyph = Array.from(value)[0] ?? fallback;
+	return visibleWidth(glyph) === 1 ? glyph : fallback;
+}
+
+/**
+ * Fixed-height viewport over pre-rendered lines, with optional right-edge scrollbar.
+ *
+ * ScrollView owns only the row offset. Callers remain responsible for producing
+ * already-wrapped logical lines appropriate for the current render width.
+ */
+export class ScrollView implements Component {
+	#lines: string[];
+	#height: number;
+	#scrollOffset = 0;
+	#totalRows: number | undefined;
+	#scrollbar: ScrollbarMode;
+	#theme: Required<ScrollViewTheme>;
+	#trackChar: string;
+	#thumbChar: string;
+
+	constructor(lines: readonly string[], options: ScrollViewOptions) {
+		this.#lines = [...lines];
+		this.#height = Number.isFinite(options.height) ? Math.max(0, Math.trunc(options.height)) : 0;
+		this.#totalRows = options.totalRows === undefined ? undefined : Math.max(0, Math.trunc(options.totalRows));
+		this.#scrollbar = normalizeScrollbarMode(options.scrollbar);
+		this.#theme = {
+			track: options.theme?.track ?? (text => text),
+			thumb: options.theme?.thumb ?? (text => text),
+		};
+		this.#trackChar = firstCellGlyph(options.trackChar ?? DEFAULT_TRACK, DEFAULT_TRACK);
+		this.#thumbChar = firstCellGlyph(options.thumbChar ?? DEFAULT_THUMB, DEFAULT_THUMB);
+		this.#clampScrollOffset();
+	}
+
+	setLines(lines: readonly string[]): void {
+		this.#lines = [...lines];
+		this.#clampScrollOffset();
+	}
+
+	setTotalRows(totalRows: number | undefined): void {
+		this.#totalRows = totalRows === undefined ? undefined : Math.max(0, Math.trunc(totalRows));
+		this.#clampScrollOffset();
+	}
+
+	setHeight(height: number): void {
+		this.#height = Number.isFinite(height) ? Math.max(0, Math.trunc(height)) : 0;
+		this.#clampScrollOffset();
+	}
+
+	setScrollbar(scrollbar: ScrollViewOptions["scrollbar"]): void {
+		this.#scrollbar = normalizeScrollbarMode(scrollbar);
+	}
+
+	getScrollOffset(): number {
+		return this.#scrollOffset;
+	}
+
+	getMaxScrollOffset(): number {
+		const rowCount = this.#totalRows ?? this.#lines.length;
+		return Math.max(0, rowCount - this.#height);
+	}
+
+	setScrollOffset(offset: number): void {
+		this.#scrollOffset = Number.isFinite(offset) ? Math.trunc(offset) : 0;
+		this.#clampScrollOffset();
+	}
+
+	scroll(delta: number): void {
+		this.setScrollOffset(this.#scrollOffset + (Number.isFinite(delta) ? Math.trunc(delta) : 0));
+	}
+
+	page(delta: number): void {
+		const step = Math.max(1, this.#height - 1);
+		this.scroll(step * (Number.isFinite(delta) ? Math.trunc(delta) : 0));
+	}
+
+	scrollToTop(): void {
+		this.#scrollOffset = 0;
+	}
+
+	scrollToBottom(): void {
+		this.#scrollOffset = this.getMaxScrollOffset();
+	}
+
+	invalidate(): void {
+		// No cached layout to invalidate.
+	}
+
+	render(width: number): string[] {
+		this.#clampScrollOffset();
+		const safeWidth = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
+		if (this.#height === 0) return [];
+		const showScrollbar = safeWidth > 0 && this.#shouldRenderScrollbar();
+		const contentWidth = Math.max(0, safeWidth - (showScrollbar ? 1 : 0));
+		const thumb = showScrollbar ? this.#thumbRange() : undefined;
+		const lines: string[] = [];
+		for (let row = 0; row < this.#height; row++) {
+			const sourceIndex = this.#totalRows === undefined ? this.#scrollOffset + row : row;
+			const source = this.#lines[sourceIndex] ?? "";
+			const truncated = truncateToWidth(replaceTabs(source), contentWidth, Ellipsis.Unicode);
+			if (!showScrollbar) {
+				lines.push(truncated);
+				continue;
+			}
+			const content = `${truncated}${" ".repeat(Math.max(0, contentWidth - visibleWidth(truncated)))}`;
+			const barGlyph = thumb && row >= thumb.start && row < thumb.end ? this.#thumbChar : this.#trackChar;
+			const styledBar =
+				thumb && row >= thumb.start && row < thumb.end ? this.#theme.thumb(barGlyph) : this.#theme.track(barGlyph);
+			lines.push(`${content}${styledBar}`);
+		}
+		return lines;
+	}
+
+	#clampScrollOffset(): void {
+		this.#scrollOffset = Math.max(0, Math.min(this.#scrollOffset, this.getMaxScrollOffset()));
+	}
+
+	#shouldRenderScrollbar(): boolean {
+		if (this.#height <= 0) return false;
+		if (this.#scrollbar === "never") return false;
+		if (this.#scrollbar === "always") return true;
+		return (this.#totalRows ?? this.#lines.length) > this.#height;
+	}
+
+	#thumbRange(): { start: number; end: number } {
+		if (this.#height <= 0) return { start: 0, end: 0 };
+		const rowCount = this.#totalRows ?? this.#lines.length;
+		if (rowCount <= this.#height) return { start: 0, end: this.#height };
+		const thumbSize = Math.max(1, Math.min(Math.floor((this.#height * this.#height) / rowCount), this.#height));
+		const travel = this.#height - thumbSize;
+		const maxOffset = this.getMaxScrollOffset();
+		const start = maxOffset === 0 ? 0 : Math.round((this.#scrollOffset / maxOffset) * travel);
+		return { start, end: start + thumbSize };
+	}
+}

package/src/components/select-list.ts

@@ -4,6 +4,7 @@ import { extractPrintableText } from "../keys";
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
 import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
+import { ScrollView } from "./scroll-view";
 
 const DEFAULT_PRIMARY_COLUMN_WIDTH = 32;
 const PRIMARY_COLUMN_GAP = 2;
@@ -104,17 +105,29 @@ export class SelectList implements Component {
 		const endIndex = Math.min(startIndex + this.maxVisible, this.#filteredItems.length);
 
 		// Render visible items
+		const overflow = this.#filteredItems.length > this.maxVisible;
+		const rowWidth = Math.max(0, width - (overflow ? 1 : 0));
+		const rows: string[] = [];
 		for (let i = startIndex; i < endIndex; i++) {
 			const item = this.#filteredItems[i];
 			if (!item) continue;
 
 			const isSelected = i === this.#selectedIndex;
 			const descriptionText = item.description ? sanitizeSingleLine(item.description) : undefined;
-			lines.push(this.#renderItem(item, isSelected, width, descriptionText, primaryColumnWidth));
+			rows.push(this.#renderItem(item, isSelected, rowWidth, descriptionText, primaryColumnWidth));
 		}
 
-		// Add scroll/search status when needed
-		if (startIndex > 0 || endIndex < this.#filteredItems.length || showSearchStatus) {
+		const sv = new ScrollView(rows, {
+			height: rows.length,
+			scrollbar: "auto",
+			totalRows: this.#filteredItems.length,
+			theme: { track: t => this.theme.scrollInfo(t), thumb: t => this.theme.selectedPrefix(t) },
+		});
+		sv.setScrollOffset(startIndex);
+		lines.push(...sv.render(width));
+
+		// Add search status when relevant (scrollbar now indicates overflow)
+		if (showSearchStatus) {
 			lines.push(this.#renderStatusLine(width));
 		}
 
@@ -247,15 +260,8 @@ export class SelectList implements Component {
 	}
 
 	#renderStatusLine(width: number): string {
-		const selectedCount = this.#filteredItems.length === 0 ? 0 : this.#selectedIndex + 1;
-		const filteredCount = this.#filteredItems.length;
-		const count =
-			this.#filterQuery.trim() && filteredCount !== this.items.length
-				? `${selectedCount}/${filteredCount} of ${this.items.length}`
-				: `${selectedCount}/${filteredCount}`;
 		const query = sanitizeSingleLine(this.#filterQuery);
-		const searchSuffix = this.#shouldRenderSearchStatus() ? (query ? `  Search: ${query}` : "  Type to search") : "";
-		const statusText = `  (${count})${searchSuffix}`;
+		const statusText = query ? `  Search: ${query}` : "  Type to search";
 		return this.theme.scrollInfo(truncateToWidth(statusText, Math.max(1, width - 2), Ellipsis.Omit));
 	}
 

package/src/components/settings-list.ts

@@ -1,6 +1,7 @@
 import { getKeybindings } from "../keybindings";
 import type { Component } from "../tui";
 import { Ellipsis, padding, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
+import { ScrollView } from "./scroll-view";
 
 export interface SettingItem {
 	/** Unique identifier for this setting */
@@ -90,6 +91,22 @@ export class SettingsList implements Component {
 		return this.#renderMainList(width);
 	}
 
+	#renderItemRow(item: SettingItem, index: number, maxLabelWidth: number, rowWidth: number): string {
+		const isSelected = index === this.#selectedIndex;
+		const prefix = isSelected ? this.#theme.cursor : "  ";
+		const prefixWidth = visibleWidth(prefix);
+		const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
+		const labelText = this.#theme.label(labelPadded, isSelected, item.changed === true);
+		const separator = "  ";
+		const valueMaxWidth = rowWidth - prefixWidth - maxLabelWidth - visibleWidth(separator) - 2;
+		const valueText = this.#theme.value(
+			truncateToWidth(item.currentValue, valueMaxWidth, Ellipsis.Omit),
+			isSelected,
+			item.changed === true,
+		);
+		return truncateToWidth(prefix + labelText + separator + valueText, Math.max(0, rowWidth));
+	}
+
 	#renderMainList(width: number): string[] {
 		const lines: string[] = [];
 
@@ -98,48 +115,29 @@ export class SettingsList implements Component {
 			return lines;
 		}
 
-		// Calculate visible range with scrolling
+		const viewportHeight = Math.min(this.#maxVisible, this.#items.length);
 		const startIndex = Math.max(
 			0,
-			Math.min(this.#selectedIndex - Math.floor(this.#maxVisible / 2), this.#items.length - this.#maxVisible),
+			Math.min(this.#selectedIndex - Math.floor(viewportHeight / 2), this.#items.length - viewportHeight),
 		);
-		const endIndex = Math.min(startIndex + this.#maxVisible, this.#items.length);
-
-		// Calculate max label width for alignment
 		const maxLabelWidth = Math.min(30, Math.max(...this.#items.map(item => visibleWidth(item.label))));
-
-		// Render visible items
-		for (let i = startIndex; i < endIndex; i++) {
-			const item = this.#items[i];
-			if (!item) continue;
-
-			const isSelected = i === this.#selectedIndex;
-			const prefix = isSelected ? this.#theme.cursor : "  ";
-			const prefixWidth = visibleWidth(prefix);
-
-			// Pad label to align values
-			const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
-			const labelText = this.#theme.label(labelPadded, isSelected, item.changed === true);
-
-			// Calculate space for value
-			const separator = "  ";
-			const usedWidth = prefixWidth + maxLabelWidth + visibleWidth(separator);
-			const valueMaxWidth = width - usedWidth - 2;
-
-			const valueText = this.#theme.value(
-				truncateToWidth(item.currentValue, valueMaxWidth, Ellipsis.Omit),
-				isSelected,
-				item.changed === true,
-			);
-
-			lines.push(truncateToWidth(prefix + labelText + separator + valueText, width));
-		}
-
-		// Add scroll indicator if needed
-		if (startIndex > 0 || endIndex < this.#items.length) {
-			const scrollText = `  (${this.#selectedIndex + 1}/${this.#items.length})`;
-			lines.push(this.#theme.hint(truncateToWidth(scrollText, width - 2, Ellipsis.Omit)));
-		}
+		const itemRowsOverflow = this.#items.length > viewportHeight;
+		const itemRowWidth = Math.max(0, width - (itemRowsOverflow ? 1 : 0));
+		const visibleItems = this.#items.slice(startIndex, startIndex + viewportHeight);
+		const itemRows = visibleItems.map((item, index) =>
+			this.#renderItemRow(item, startIndex + index, maxLabelWidth, itemRowWidth),
+		);
+		const scrollView = new ScrollView(itemRows, {
+			height: viewportHeight,
+			scrollbar: "auto",
+			totalRows: this.#items.length,
+			theme: {
+				track: text => this.#theme.hint(text),
+				thumb: text => this.#theme.label(text, true, false),
+			},
+		});
+		scrollView.setScrollOffset(startIndex);
+		lines.push(...scrollView.render(width));
 
 		// Add description for selected item
 		const selectedItem = this.#items[this.#selectedIndex];

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./components/image";
 export * from "./components/input";
 export * from "./components/loader";
 export * from "./components/markdown";
+export * from "./components/scroll-view";
 export * from "./components/select-list";
 export * from "./components/settings-list";
 export * from "./components/spacer";

package/src/terminal.ts

@@ -129,6 +129,12 @@ export interface Terminal {
 	 */
 	isNativeViewportAtBottom?(): boolean | undefined;
 
+	/**
+	 * Override the global terminal-profile ED3 risk decision for custom/test
+	 * terminals. `undefined` falls back to the resolved `TERMINAL` profile.
+	 */
+	hasEagerEraseScrollbackRisk?(): boolean | undefined;
+
 	/**
 	 * Register a callback for terminal appearance (dark/light) changes.
 	 * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.

package/src/tui.ts

@@ -1,5 +1,14 @@
 /**
- * Minimal TUI implementation with differential rendering
+ * Minimal TUI implementation with differential rendering.
+ *
+ * Before changing the render planner, native-scrollback bookkeeping, capability
+ * detection, or width math, read `docs/tui-core-renderer.md`: it documents the
+ * failure modes (yank / corruption / flash / width crashes) and the invariants
+ * this engine must not violate. The short version: the renderer cannot observe
+ * the terminal's scroll position on most hosts, so ED3 (`CSI 3 J`) is confined
+ * to the destructive `clearScrollback` path, an unobservable viewport probe is
+ * never trusted for passive streaming, and the hot path clamps over-wide lines
+ * instead of throwing.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -357,6 +366,10 @@ export class Container implements Component {
  * - `deferredShrink`: pure content shrink would re-expose rows already in
  *   native history. Keep row indices stable with blank tail padding, repaint
  *   only the viewport, and defer the real shorter replay to a checkpoint.
+ * - `deferredTailRepaint`: a deferred history mutation also changed the active
+ *   grid's bottom row; repaint only that row relative to the tracked hardware
+ *   cursor so a bottom-anchored spinner can advance without rewriting rows that
+ *   a slightly-scrolled reader can still see.
  * - `deferredMutation`: a row-inserting edit would reindex native scrollback
  *   while the user is scrolled. Defer all bytes until a safe rebuild checkpoint.
  * - `shrink`: trailing rows were dropped — clear extras inline.
@@ -371,6 +384,7 @@ type RenderIntent =
 	| { kind: "liveRegionPinned"; appendFrom: number; appendTo: number; renderViewportTop: number }
 	| { kind: "viewportRepaint"; appendFrom?: number }
 	| { kind: "deferredShrink"; paddedLength: number }
+	| { kind: "deferredTailRepaint"; row: number; line: string }
 	| { kind: "deferredMutation" }
 	| { kind: "shrink" }
 	| { kind: "diff"; firstChanged: number; lastChanged: number; appendedLines: boolean };
@@ -421,6 +435,7 @@ export class TUI extends Container {
 	#nativeScrollbackLiveRegionStart: number | undefined;
 	#nativeScrollbackCommitSafeEnd: number | undefined;
 	#nativeScrollbackDirty = false;
+	#deferredTailLine: string | undefined;
 	// Highest `#maxLinesRendered` reached during a foreground tool turn while
 	// intermediate frames were prevented from committing to terminal scrollback.
 	// Used after the tool finishes to push the settled content into scrollback
@@ -569,8 +584,8 @@ export class TUI extends Container {
 	 * (the viewport is never observable there and ConPTY hosts erase host
 	 * scrollback on ED3 — #1635/#1746); only the unknown POSIX case is forced to
 	 * rebuild. POSIX hosts known to disturb scrolled readers on xterm ED3
-	 * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint and
-	 * direct user-input rebuilds are unaffected.
+	 * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint
+	 * rebuilds are unaffected.
 	 *
 	 * Disabling stays active through one already-requested frame: the event batch
 	 * that ends a foreground stream both removes its UI rows (loader/status
@@ -591,7 +606,7 @@ export class TUI extends Container {
 			this.#eagerNativeScrollbackRebuildDisablePending = true;
 			return;
 		}
-		if (process.platform !== "win32" && TERMINAL.eagerEraseScrollbackRisk) {
+		if (this.#hasEagerEraseScrollbackRisk()) {
 			this.#streamingHighWater = 0;
 			this.#markNativeScrollbackDirty();
 		}
@@ -1463,7 +1478,7 @@ export class TUI extends Container {
 		const heightChanged =
 			(this.#previousHeight > 0 && this.#previousHeight !== height) ||
 			(resizeEventOccurred && this.#previousHeight > 0);
-		const eagerEraseScrollbackRisk = process.platform !== "win32" && TERMINAL.eagerEraseScrollbackRisk;
+		const eagerEraseScrollbackRisk = this.#hasEagerEraseScrollbackRisk();
 		const eagerRebuildAllowed = this.#eagerNativeScrollbackRebuild && !eagerEraseScrollbackRisk;
 		const explicitViewportMutation = this.#allowUnknownViewportMutationOnNextRender;
 		const allowUnknownViewportMutation = explicitViewportMutation || eagerRebuildAllowed;
@@ -1528,6 +1543,7 @@ export class TUI extends Container {
 			} else if (
 				!explicitReconcile &&
 				nativeViewportAtBottom !== true &&
+				!isMultiplexerSession() &&
 				(intent.kind === "sessionReplace" ||
 					intent.kind === "historyRebuild" ||
 					intent.kind === "overlayRebuild" ||
@@ -1535,6 +1551,13 @@ export class TUI extends Container {
 			) {
 				// Cap the frame to the viewport and keep scrollback dirty: transient
 				// rows never enter history, and the checkpoint reconciles later.
+				// Multiplexers (tmux/screen/zellij) are excluded: their checkpoint
+				// reconcile is a no-op (pane history cannot be erased), so any rows
+				// dropped here are dropped forever. Pane history is append-only
+				// anyway, so a normal diff/append `\r\n` commit is exactly what the
+				// multiplexer needs — and the `liveRegionPinned` planner above
+				// keeps the actively-mutating live tail out of pane history while
+				// committing only the sealed prefix (issue #1974).
 				this.#markNativeScrollbackDirty();
 				this.#streamingHighWater = Math.max(this.#streamingHighWater, lines.length);
 				this.#scrollbackHighWater = 0;
@@ -1602,6 +1625,7 @@ export class TUI extends Container {
 					clearViewport: true,
 					clearScrollback: !isMultiplexerSession(),
 				});
+				this.#hasEverRendered = true;
 				return;
 			case "historyRebuild":
 				this.#clearNativeScrollbackDirty();
@@ -1637,6 +1661,16 @@ export class TUI extends Container {
 				}
 				this.#emitViewportRepaint(lines, width, height, cursorPos);
 				return;
+			case "deferredTailRepaint":
+				this.#emitDeferredTailRepaint(
+					intent.line,
+					width,
+					height,
+					intent.row,
+					prevViewportTop,
+					prevHardwareCursorRow,
+				);
+				return;
 			case "deferredMutation":
 				return;
 			case "deferredShrink":
@@ -1686,16 +1720,20 @@ export class TUI extends Container {
 		liveRegionStart: number | undefined,
 		commitSafeEnd: number | undefined,
 	): RenderIntent {
+		// A forced scrollback wipe can be queued before start()'s initial paint runs
+		// (cold `omp --resume` does this while replacing the welcome frame with the
+		// restored transcript). Honor it before the normal initial-preserve path so
+		// the first committed frame is the clean session replay, not a deferred wipe
+		// that waits for the user's first keystroke.
+		if (this.#clearScrollbackOnNextRender) return { kind: "sessionReplace" };
+
 		// Initial paint after start(): scrollback must keep its prior shell
 		// content, but the viewport must be cleared so stale rows do not bleed
 		// into the new UI.
 		if (!this.#hasEverRendered) return { kind: "initial" };
 
-		// Caller opted into a scrollback wipe via requestRender(true, { clearScrollback: true }).
-		if (this.#clearScrollbackOnNextRender) return { kind: "sessionReplace" };
-
 		const forceViewportRepaint = this.#forceViewportRepaintOnNextRender;
-		const eagerEraseScrollbackRisk = process.platform !== "win32" && TERMINAL.eagerEraseScrollbackRisk;
+		const eagerEraseScrollbackRisk = this.#hasEagerEraseScrollbackRisk();
 		if (overlayVisibilityReduced && !isMultiplexerSession()) {
 			return hasVisibleOverlay ? { kind: "overlayRebuild" } : { kind: "historyRebuild" };
 		}
@@ -1718,6 +1756,11 @@ export class TUI extends Container {
 			return hasVisibleOverlay ? { kind: "overlayRebuild" } : { kind: "historyRebuild" };
 		}
 
+		// Same dirty-scrollback opt-in policy as the non-overlay branch below: an
+		// ED3-risk macOS/POSIX terminal with an unobservable viewport ignores
+		// focused-input unknown opt-ins, so overlay selector Up/Down moves do not
+		// become ED3 clears plus full transcript replays. Non-ED3-risk POSIX still
+		// honors direct-input/IME/autocomplete opt-ins.
 		if (hasVisibleOverlay) {
 			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
 			// Multiplexer panes never get a destructive scrollback clear
@@ -1725,10 +1768,11 @@ export class TUI extends Container {
 			// "rebuild" would only append a full duplicate copy of the transcript
 			// to pane history on every dirty frame. Keep repainting the viewport
 			// and leave reconciliation to explicit checkpoints.
+			const allowDirtyUnknownViewportMutation = allowUnknownViewportMutation && !eagerEraseScrollbackRisk;
 			if (
 				this.#nativeScrollbackDirty &&
 				!isMultiplexerSession() &&
-				this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, allowUnknownViewportMutation)
+				this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, allowDirtyUnknownViewportMutation)
 			) {
 				return { kind: "overlayRebuild" };
 			}
@@ -1759,12 +1803,19 @@ export class TUI extends Container {
 			this.#streamingHighWater = 0;
 		}
 
-		if (
-			this.#nativeScrollbackDirty &&
-			!isMultiplexerSession() &&
-			this.#canRebuildNativeScrollbackLive(this.#readNativeViewportAtBottom(), allowUnknownViewportMutation)
-		) {
-			return { kind: "historyRebuild" };
+		if (this.#nativeScrollbackDirty && !isMultiplexerSession()) {
+			// A dirty flag means older native history is stale; it is not required to
+			// make the current focused-input frame correct. On ED3-risk macOS/POSIX
+			// terminals with an unobservable viewport, ignore focused-input unknown
+			// opt-ins so Up/Down selector moves do not become ED3 clears plus full
+			// transcript replays. Non-ED3-risk POSIX terminals keep their safe
+			// direct-input/IME/autocomplete opt-in.
+			const allowDirtyUnknownViewportMutation = allowUnknownViewportMutation && !eagerEraseScrollbackRisk;
+			if (
+				this.#canRebuildNativeScrollbackLive(this.#readNativeViewportAtBottom(), allowDirtyUnknownViewportMutation)
+			) {
+				return { kind: "historyRebuild" };
+			}
 		}
 
 		const diff = this.#diffLines(newLines);
@@ -1802,18 +1853,28 @@ export class TUI extends Container {
 			//
 			const paddedViewportTop = Math.max(0, this.#previousLines.length - height);
 			// ED3-risk terminals with an unobservable viewport cannot safely clear
-			// saved lines. During an active eager streaming turn the user follows the
-			// live tail, so paint the shrink's bottom-anchored viewport in place
-			// whether it still overflows OR now fits — otherwise the UI freezes on
-			// stale rows until the next input even though the frame has a fresh bottom
-			// viewport to show (issues #1682, foreground-stream fidelity on collapse).
-			// Native history stays dirty and reconciles at the next checkpoint. With no
-			// active eager turn the reader may be scrolled; even a padded shrink repaint
-			// can move ED3-risk unknown host scrollback (WSL/Ghostty-style), so defer
+			// saved lines. Direct user-input frames (autocomplete/IME) may still
+			// repaint the live viewport: the user action pins the host to the tail, and
+			// emitting zero bytes leaves stale autocomplete rows on screen until a later
+			// checkpoint. When the changed rows are at or below the previous viewport
+			// top, keep the old bottom anchor by padding the frame to its previous
+			// length; that clears stale popup rows without re-exposing rows already
+			// committed to native history. If an offscreen edit shifted rows above the
+			// viewport, padding would repaint the wrong seam, so use a viewport repaint
+			// for liveness and keep history dirty. Active eager streaming also uses a
+			// viewport repaint so the live tail keeps moving. With neither direct input
+			// nor active eager streaming, the reader may be scrolled, so defer
 			// completely rather than repainting over their history.
 			if (nativeViewportAtBottom === undefined && eagerEraseScrollbackRisk) {
 				this.#markNativeScrollbackDirty();
-				return this.#eagerNativeScrollbackRebuild ? { kind: "viewportRepaint" } : { kind: "deferredMutation" };
+				if (allowUnknownViewportMutation) {
+					return diff.firstChanged < prevViewportTop
+						? { kind: "viewportRepaint" }
+						: { kind: "deferredShrink", paddedLength: this.#previousLines.length };
+				}
+				return this.#eagerNativeScrollbackRebuild
+					? { kind: "viewportRepaint" }
+					: this.#planDeferredTailRepaint(newLines, prevViewportTop, height);
 			}
 
 			// Non-ED3-risk POSIX with an unobservable viewport. `deferredShrink` is
@@ -1825,7 +1886,7 @@ export class TUI extends Container {
 			}
 			this.#markNativeScrollbackDirty();
 			if (diff.firstChanged < prevViewportTop) {
-				return { kind: "deferredMutation" };
+				return this.#planDeferredTailRepaint(newLines, prevViewportTop, height);
 			}
 			return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
 		}
@@ -1924,21 +1985,30 @@ export class TUI extends Container {
 		const contentGrew = newLines.length > this.#previousLines.length;
 		const pureAppend = diff.appendedLines && diff.firstChanged === this.#previousLines.length;
 		const structuralMutation = newLines.length !== this.#previousLines.length || diff.firstChanged < prevViewportTop;
-		if (pureAppend && contentGrew && this.#previousLines.length > height && !isMultiplexerSession()) {
+		if (pureAppend && contentGrew && this.#previousLines.length >= height && !isMultiplexerSession()) {
 			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+			if (this.#nativeViewportIsKnownScrolled(nativeViewportAtBottom)) {
+				this.#markNativeScrollbackDirty();
+				return { kind: "deferredMutation" };
+			}
+			if (nativeViewportAtBottom === undefined && allowUnknownViewportMutation) {
+				// Direct input can grow transient live UI (autocomplete/IME/editor
+				// wraps) while the previous frame already touched the viewport bottom.
+				// A diff append would `\r\n`-scroll those transient rows into native
+				// history, and a later popup shrink would duplicate the stable prefix at
+				// the scrollback seam. Repaint the live viewport in place instead; the
+				// dirty checkpoint owns native-history reconciliation.
+				this.#markNativeScrollbackDirty();
+				return { kind: "viewportRepaint" };
+			}
 			if (this.#nativeViewportIsScrolled(nativeViewportAtBottom, allowUnknownViewportMutation)) {
 				this.#markNativeScrollbackDirty();
-				// Confirmed scrolled (probe returned `false`): the reader is parked in
-				// scrollback and writing the live frame is wasted bytes — defer until
-				// the next checkpoint reconciles. Unknown viewport (e.g. native Windows
-				// Terminal where the probe cannot see WT host scrollback) is a
-				// different case: a no-op there freezes the editor on the keystroke
-				// that grows `lines.length` past the viewport (the wrap keystroke).
-				// Fall through to a non-destructive viewport repaint instead so the
-				// live UI keeps updating without yanking a possibly-scrolled reader.
-				if (this.#nativeViewportIsKnownScrolled(nativeViewportAtBottom)) {
-					return { kind: "deferredMutation" };
-				}
+				// Unknown viewport (e.g. native Windows Terminal where the probe cannot
+				// see WT host scrollback) is a different case: a no-op there freezes the
+				// editor on the keystroke that grows `lines.length` past the viewport
+				// (the wrap keystroke). Fall through to a non-destructive viewport
+				// repaint instead so the live UI keeps updating without yanking a
+				// possibly-scrolled reader.
 				return { kind: "viewportRepaint" };
 			}
 		}
@@ -2022,7 +2092,7 @@ export class TUI extends Container {
 				!cleanTailAppend &&
 				!this.#eagerNativeScrollbackRebuild
 			) {
-				return { kind: "deferredMutation" };
+				return this.#planDeferredTailRepaint(newLines, prevViewportTop, height);
 			}
 			return { kind: "viewportRepaint", appendFrom: cleanTailAppend ? this.#previousLines.length : undefined };
 		}
@@ -2108,6 +2178,11 @@ export class TUI extends Container {
 		this.#nativeScrollbackDirty = false;
 	}
 
+	#hasEagerEraseScrollbackRisk(): boolean {
+		if (process.platform === "win32") return false;
+		return this.terminal.hasEagerEraseScrollbackRisk?.() ?? TERMINAL.eagerEraseScrollbackRisk;
+	}
+
 	#readNativeViewportAtBottom(): boolean | undefined {
 		// A stale positive is destructive: live history rebuilds clear native
 		// scrollback. Require two consecutive at-bottom probes before trusting it.
@@ -2174,11 +2249,18 @@ export class TUI extends Container {
 			liveRegionStart >= newLines.length ||
 			!this.#eagerNativeScrollbackRebuild ||
 			!eagerEraseScrollbackRisk ||
-			allowUnknownViewportMutation ||
-			isMultiplexerSession()
+			allowUnknownViewportMutation
 		) {
 			return undefined;
 		}
+		// Multiplexers (tmux/screen/zellij) cannot erase pane history with `\x1b[3J`
+		// and cannot answer a viewport-position probe, so the destructive checkpoint
+		// rebuild path is forever unavailable. The pinned emitter is built from the
+		// opposite primitives — relative cursor moves, per-line `\x1b[2K`, and
+		// `\r\n` to scroll sealed rows past the viewport bottom — which are exactly
+		// what tmux pane history accepts. Without this commit-as-you-go path, the
+		// streaming cap below clipped every frame to the visible tail and the
+		// scrolled-off head was committed nowhere (issue #1974).
 		if (newLines.length <= height && this.#scrollbackHighWater === 0) return undefined;
 		if (this.#readNativeViewportAtBottom() !== undefined) return undefined;
 
@@ -2209,6 +2291,19 @@ export class TUI extends Container {
 		return { kind: "liveRegionPinned", appendFrom, appendTo, renderViewportTop };
 	}
 
+	#planDeferredTailRepaint(newLines: string[], prevViewportTop: number, height: number): RenderIntent {
+		const row = prevViewportTop + height - 1;
+		if (row < 0 || row >= this.#previousLines.length || newLines.length !== this.#previousLines.length) {
+			return { kind: "deferredMutation" };
+		}
+		const line = newLines[row] ?? "";
+		const previousLine = this.#deferredTailLine ?? this.#previousLines[row] ?? "";
+		if (line === previousLine) {
+			return { kind: "deferredMutation" };
+		}
+		return { kind: "deferredTailRepaint", row, line };
+	}
+
 	#padDeferredShrinkLines(lines: string[], paddedLength: number): string[] {
 		if (lines.length >= paddedLength) return lines;
 		return [...lines, ...new Array<string>(paddedLength - lines.length).fill("")];
@@ -2240,6 +2335,7 @@ export class TUI extends Container {
 	 */
 
 	#commit(lines: string[], width: number, height: number, viewportTop: number, hardwareCursorRow: number): void {
+		this.#deferredTailLine = undefined;
 		this.#previousLines = lines;
 		this.#previousVisibleOverlayComponents = this.#visibleOverlayComponentsThisRender;
 		this.#forceViewportRepaintOnNextRender = false;
@@ -2536,6 +2632,41 @@ export class TUI extends Container {
 		}
 	}
 
+	/**
+	 * Paint only the active-grid bottom row while a scrollback mutation remains
+	 * deferred. If the native viewport is unknown and the user is scrolled up by a
+	 * single line, every active-grid row except the bottom can still be visible in
+	 * their scrollback window; touching only this row keeps that reader's viewport
+	 * unchanged while allowing bottom-anchored live chrome (spinner/status tail) to
+	 * advance for users at the tail.
+	 */
+	#emitDeferredTailRepaint(
+		line: string,
+		width: number,
+		height: number,
+		row: number,
+		prevViewportTop: number,
+		prevHardwareCursorRow: number,
+	): void {
+		const viewportBottom = prevViewportTop + height - 1;
+		if (row !== viewportBottom) return;
+
+		let buffer = this.#paintBeginSequence;
+		const clampedCursor = Math.min(prevHardwareCursorRow, viewportBottom);
+		const currentScreenRow = Math.max(0, Math.min(height - 1, clampedCursor - prevViewportTop));
+		const moveDown = height - 1 - currentScreenRow;
+		if (moveDown > 0) buffer += `\x1b[${moveDown}B`;
+		buffer += `\r\x1b[2K${this.#fitLineToWidth(line, width)}\x1b[?25l`;
+		buffer += this.#paintEndSequence;
+		this.terminal.write(buffer);
+
+		this.#deferredTailLine = line;
+		this.#previousWidth = width;
+		this.#previousHeight = height;
+		this.#viewportTopRow = prevViewportTop;
+		this.#hardwareCursorRow = row;
+	}
+
 	/**
 	 * Trailing-shrink: prior content shared a prefix with the new content; the
 	 * extra rows below the new tail need to be cleared without scrolling. Falls
@@ -2740,7 +2871,9 @@ export class TUI extends Container {
 					? `${intent.kind}(append=${intent.appendFrom}..${intent.appendTo}, viewportTop=${intent.renderViewportTop})`
 					: intent.kind === "viewportRepaint" && intent.appendFrom !== undefined
 						? `${intent.kind}(appendFrom=${intent.appendFrom})`
-						: intent.kind;
+						: intent.kind === "deferredTailRepaint"
+							? `${intent.kind}(row=${intent.row})`
+							: intent.kind;
 		const msg = `[${new Date().toISOString()}] render: ${detail} (prev=${this.#previousLines.length}, new=${newLength}, height=${height})\n`;
 		fs.appendFileSync(getDebugLogPath(), msg);
 	}