@oh-my-pi/pi-tui 15.7.2 → 15.7.5

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## [Unreleased]
 
+## [15.7.5] - 2026-06-01
+
+### Fixed
+
+- Fixed native Windows + Windows Terminal scrollback being yanked to the top when a streaming response triggered a TUI full redraw. Under ConPTY the `kernel32` `GetConsoleScreenBufferInfo` probe answers about the pseudo-console (always at the buffer tail) and not about WT's host scrollback, so `isNativeViewportAtBottom()` falsely returned `true` while the user was scrolled up and the shrink-across-viewport branch issued a destructive `historyRebuild` (`\x1b[2J\x1b[H\x1b[3J`). The probe now short-circuits to `undefined` whenever `WT_SESSION` is set, letting the existing deferred-rebuild path keep streaming-time mutations non-destructive and reconcile native history at the next prompt-submit checkpoint. ([#1635](https://github.com/can1357/oh-my-pi/issues/1635))
+
+## [15.7.3] - 2026-05-31
+
+### Added
+
+- Added `overflowSearch` to `SelectListLayoutOptions` to let consumers enable or disable type-to-filter search and search-status rendering per SelectList instance
+- Added fuzzy type-to-filter search to overflowing `SelectList` pickers, with search status and result counts.
+- Added `TUI.setEagerNativeScrollbackRebuild(enabled)` — while enabled, live render frames rebuild native scrollback on offscreen/structural changes even when the viewport position is unobservable (POSIX), instead of deferring to a non-destructive repaint. Trades the anti-yank guarantee for clean, duplicate-free history; intended for windows where output above the fold is actively re-laying out (e.g. a tool whose result is still streaming). A terminal that reports a known-scrolled viewport still defers.
+
+### Changed
+
+- Disabled interactive search filtering for editor autocomplete and slash-command `SelectList`s by passing `overflowSearch: false` in their layout options
+
+### Fixed
+
+- Preserved hidden tmux overlays in the live viewport by removing overlay content from view when an overlay was hidden while keeping pane history intact
+- Preserved native scrollback when forced TUI renders coalesce with content growth, and deferred pure tail appends while readers are scrolled into history.
+- Preserved existing terminal scrollback during forced and structural TUI renders so preexisting shell lines remained visible after component mutations
+- Rebuilt native scrollback for safe bottom-anchored offscreen edits and high-water preview collapses instead of repainting only the viewport, preventing stale or duplicated rows above the live viewport.
+- Stripped internal cursor marker sentinels from all rendered lines so offscreen focus markers no longer leak into terminal output
+- Truncated all painted lines to terminal width during viewport repaints and append-tail updates so long content no longer overflows or wraps unexpectedly
+- Fixed `tui.select.cancel` handling in `SelectList` so pressing Escape or Ctrl+C closes the list even when no matches are currently shown
+- Fixed native scrollback corruption when an offscreen row edit and repeated-tail append land in one render frame; ambiguous appended tails now rebuild history instead of splicing stale rows into the buffer.
+- Fixed scrolled-up readers being yanked back to the tail whenever streaming content arrived on POSIX terminals (macOS/Linux). Native viewport position is unobservable there (`isNativeViewportAtBottom()` returns `undefined`), and the planner optimistically treated "unknown" as "at bottom", so every offscreen streaming edit ran a destructive `historyRebuild` that cleared scrollback and snapped the view to the bottom. Live render frames now treat an unknown viewport as unsafe for a destructive rebuild — they defer to a non-destructive viewport repaint and reconcile native scrollback at the next explicit checkpoint (prompt submit). Resize and checkpoint replays keep the prior behavior.
+- Fixed native scrollback not rewrapping when the terminal widens on POSIX. A width increase reflows the transcript to fewer lines, which the shrink-across-boundary branch intercepted and (after the unknown-viewport deferral) repainted only the viewport — leaving committed history wrapped at the old width and duplicated above the live viewport. Width changes now rebuild native scrollback at the new geometry even when the viewport position is unknown (a yank is acceptable on an explicit resize); a terminal that can report a scrolled viewport still defers.
+
 ## [15.7.0] - 2026-05-31
 
 ### Fixed

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

@@ -26,6 +26,8 @@ export interface SelectListLayoutOptions {
     minPrimaryColumnWidth?: number;
     maxPrimaryColumnWidth?: number;
     truncatePrimary?: (context: SelectListTruncatePrimaryContext) => string;
+    /** Enable type-to-filter search when the item count exceeds maxVisible. Defaults to true. */
+    overflowSearch?: boolean;
 }
 export declare class SelectList implements Component {
     #private;

package/dist/types/terminal.d.ts

@@ -41,6 +41,21 @@ export interface Terminal {
     /** The last detected terminal appearance, or undefined if not yet known. */
     get appearance(): TerminalAppearance | undefined;
 }
+/**
+ * Whether the native console viewport-position probe should be consulted.
+ *
+ * Returns `true` only on native Windows that is *not* fronted by Windows
+ * Terminal. The kernel32 `GetConsoleScreenBufferInfo` API answers about the
+ * ConPTY pseudo-console — which is always pinned to its tail — and not about
+ * the user-visible scrollback in modern hosts. Treat any such host as
+ * unreportable so the renderer falls back to the deferred-rebuild path.
+ *
+ * Pure helper for unit testing; the runtime call site reads `$env` /
+ * `process.platform`. See #1635.
+ */
+export declare function shouldTrustNativeViewportProbe(env?: {
+    WT_SESSION?: string | undefined;
+}, platform?: NodeJS.Platform): boolean;
 /**
  * Real terminal using process.stdin/stdout
  */
@@ -53,6 +68,15 @@ export declare class ProcessTerminal implements Terminal {
     /**
      * Returns true when Windows' active console viewport is at the scrollback tail.
      * POSIX terminals do not expose native scrollback position through a standard API.
+     *
+     * On native Windows running under Windows Terminal (the default modern
+     * host), the `kernel32` probe answers about the ConPTY pseudo-console — not
+     * the user-visible WT viewport — so it would always read "at bottom" while
+     * the user is scrolled up. Return `undefined` there so the renderer falls
+     * back to the POSIX-style deferred-rebuild path: streaming mutations stay
+     * non-destructive (no `\x1b[3J`), and the rebuild fires at the next prompt
+     * checkpoint via {@link TUI.refreshNativeScrollbackIfDirty} where the user
+     * is already pinned to the bottom by the editor keystroke. See #1635.
      */
     isNativeViewportAtBottom(): boolean | undefined;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;

package/dist/types/tui.d.ts

@@ -164,6 +164,18 @@ export declare class TUI extends Container {
      * When false, empty rows remain (reduces redraws on slower terminals).
      */
     setClearOnShrink(enabled: boolean): void;
+    /**
+     * When enabled, live render frames rebuild native scrollback on offscreen and
+     * structural changes even when the viewport position is unobservable (POSIX,
+     * where `isNativeViewportAtBottom()` is `undefined`), instead of deferring to a
+     * non-destructive repaint. This trades the anti-yank guarantee for a clean,
+     * duplicate-free history and is meant for windows where output above the fold
+     * is actively re-rendering — e.g. a tool whose result is still streaming and
+     * re-laying-out rows that have already scrolled into history. A snap to the tail
+     * is acceptable there. A terminal that can report a *known*-scrolled viewport
+     * (Windows) still defers; only the unknown case is forced to rebuild.
+     */
+    setEagerNativeScrollbackRebuild(enabled: boolean): void;
     setFocus(component: Component | null): void;
     /**
      * Show an overlay component with configurable positioning and sizing.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.7.2",
+	"version": "15.7.5",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -32,13 +32,13 @@
 		"check": "biome check . && bun run check:types",
 		"check:types": "tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
-		"test": "bun test test/*.test.ts",
+		"test": "bun test --parallel test/*.test.ts",
 		"fix": "biome check --write --unsafe .",
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.7.2",
-		"@oh-my-pi/pi-utils": "15.7.2",
+		"@oh-my-pi/pi-natives": "15.7.5",
+		"@oh-my-pi/pi-utils": "15.7.5",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/editor.ts

@@ -19,9 +19,14 @@ import {
 } from "../utils";
 import { SelectList, type SelectListLayoutOptions, type SelectListTheme } from "./select-list";
 
+const AUTOCOMPLETE_SELECT_LIST_LAYOUT: SelectListLayoutOptions = {
+	overflowSearch: false,
+};
+
 const SLASH_COMMAND_SELECT_LIST_LAYOUT: SelectListLayoutOptions = {
 	minPrimaryColumnWidth: 12,
 	maxPrimaryColumnWidth: 32,
+	overflowSearch: false,
 };
 
 function sanitizeLoadedText(text: string): string {
@@ -2524,11 +2529,8 @@ export class Editor implements Component, Focusable {
 		prefix: string,
 		items: Array<{ value: string; label: string; description?: string }>,
 	): SelectList {
-		// Layout options prepared for future SelectList enhancements (e.g., for slash commands)
-		const layout = prefix.startsWith("/") ? SLASH_COMMAND_SELECT_LIST_LAYOUT : undefined;
-		// TODO: Pass layout to SelectList when constructor is updated to support it
-		void layout; // Use layout variable to avoid lint warnings
-		return new SelectList(items, this.#autocompleteMaxVisible, this.#theme.selectList);
+		const layout = prefix.startsWith("/") ? SLASH_COMMAND_SELECT_LIST_LAYOUT : AUTOCOMPLETE_SELECT_LIST_LAYOUT;
+		return new SelectList(items, this.#autocompleteMaxVisible, this.#theme.selectList, layout);
 	}
 
 	#handleTabCompletion(): void {

package/src/components/select-list.ts

@@ -1,4 +1,6 @@
+import { fuzzyFilter } from "../fuzzy";
 import { getKeybindings } from "../keybindings";
+import { extractPrintableText } from "../keys";
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
 import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
@@ -45,10 +47,13 @@ export interface SelectListLayoutOptions {
 	minPrimaryColumnWidth?: number;
 	maxPrimaryColumnWidth?: number;
 	truncatePrimary?: (context: SelectListTruncatePrimaryContext) => string;
+	/** Enable type-to-filter search when the item count exceeds maxVisible. Defaults to true. */
+	overflowSearch?: boolean;
 }
 
 export class SelectList implements Component {
 	#filteredItems: ReadonlyArray<SelectItem>;
+	#filterQuery = "";
 	#selectedIndex: number = 0;
 
 	onSelect?: (item: SelectItem) => void;
@@ -65,9 +70,7 @@ export class SelectList implements Component {
 	}
 
 	setFilter(filter: string): void {
-		this.#filteredItems = this.items.filter(item => item.value.toLowerCase().startsWith(filter.toLowerCase()));
-		// Reset selection when filter changes
-		this.#selectedIndex = 0;
+		this.#setFilter(filter, true);
 	}
 
 	setSelectedIndex(index: number): void {
@@ -80,10 +83,14 @@ export class SelectList implements Component {
 
 	render(width: number): string[] {
 		const lines: string[] = [];
+		const showSearchStatus = this.#shouldRenderSearchStatus();
 
 		// If no items match filter, show message
 		if (this.#filteredItems.length === 0) {
-			lines.push(this.theme.noMatch("  No matching commands"));
+			if (showSearchStatus) {
+				lines.push(this.#renderStatusLine(width));
+			}
+			lines.push(this.theme.noMatch("  No matching items"));
 			return lines;
 		}
 
@@ -106,19 +113,29 @@ export class SelectList implements Component {
 			lines.push(this.#renderItem(item, isSelected, width, descriptionText, primaryColumnWidth));
 		}
 
-		// Add scroll indicators if needed
-		if (startIndex > 0 || endIndex < this.#filteredItems.length) {
-			const scrollText = `  (${this.#selectedIndex + 1}/${this.#filteredItems.length})`;
-			// Truncate if too long for terminal
-			lines.push(this.theme.scrollInfo(truncateToWidth(scrollText, width - 2, Ellipsis.Omit)));
+		// Add scroll/search status when needed
+		if (startIndex > 0 || endIndex < this.#filteredItems.length || showSearchStatus) {
+			lines.push(this.#renderStatusLine(width));
 		}
 
 		return lines;
 	}
 
 	handleInput(keyData: string): void {
-		if (this.#filteredItems.length === 0) return;
 		const kb = getKeybindings();
+		// Escape or Ctrl+C
+		if (kb.matches(keyData, "tui.select.cancel")) {
+			if (this.onCancel) {
+				this.onCancel();
+			}
+			return;
+		}
+
+		if (this.#handleSearchInput(keyData)) {
+			return;
+		}
+
+		if (this.#filteredItems.length === 0) 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;
@@ -146,12 +163,6 @@ export class SelectList implements Component {
 				this.onSelect(selectedItem);
 			}
 		}
-		// Escape or Ctrl+C
-		else if (kb.matches(keyData, "tui.select.cancel")) {
-			if (this.onCancel) {
-				this.onCancel();
-			}
-		}
 	}
 
 	#renderItem(
@@ -235,6 +246,71 @@ export class SelectList implements Component {
 		return sanitizeSingleLine(item.label || item.value);
 	}
 
+	#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}`;
+		return this.theme.scrollInfo(truncateToWidth(statusText, Math.max(1, width - 2), Ellipsis.Omit));
+	}
+
+	#shouldRenderSearchStatus(): boolean {
+		return (
+			this.layout.overflowSearch !== false && (this.items.length > this.maxVisible || this.#filterQuery.length > 0)
+		);
+	}
+
+	#canEditSearch(): boolean {
+		return this.layout.overflowSearch !== false && this.items.length > this.maxVisible;
+	}
+
+	#handleSearchInput(keyData: string): boolean {
+		if (!this.#canEditSearch()) return false;
+
+		const kb = getKeybindings();
+		if (kb.matches(keyData, "tui.editor.deleteCharBackward")) {
+			if (this.#filterQuery.length === 0) return false;
+			const chars = [...this.#filterQuery];
+			chars.pop();
+			this.#setFilter(chars.join(""), true);
+			return true;
+		}
+
+		const printableText = extractPrintableText(keyData);
+		if (printableText === undefined) return false;
+		if (this.#filterQuery.length === 0 && printableText.trim().length === 0) return false;
+
+		this.#setFilter(this.#filterQuery + printableText, true);
+		return true;
+	}
+
+	#setFilter(filter: string, notify: boolean): void {
+		this.#filterQuery = filter;
+		this.#filteredItems = filter.trim()
+			? fuzzyFilter([...this.items], filter, item => this.#getFilterText(item))
+			: this.items;
+		this.#selectedIndex = 0;
+		if (notify) {
+			this.#notifySelectionChange();
+		}
+	}
+
+	#getFilterText(item: SelectItem): string {
+		let text = `${item.label} ${item.value}`;
+		if (item.description) {
+			text += ` ${item.description}`;
+		}
+		if (item.hint) {
+			text += ` ${item.hint}`;
+		}
+		return sanitizeSingleLine(text);
+	}
+
 	#notifySelectionChange(): void {
 		const selectedItem = this.#filteredItems[this.#selectedIndex];
 		if (selectedItem && this.onSelectionChange) {

package/src/terminal.ts

@@ -113,6 +113,27 @@ function isWindowsSubsystemForLinux(): boolean {
 	return process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
 }
 
+/**
+ * Whether the native console viewport-position probe should be consulted.
+ *
+ * Returns `true` only on native Windows that is *not* fronted by Windows
+ * Terminal. The kernel32 `GetConsoleScreenBufferInfo` API answers about the
+ * ConPTY pseudo-console — which is always pinned to its tail — and not about
+ * the user-visible scrollback in modern hosts. Treat any such host as
+ * unreportable so the renderer falls back to the deferred-rebuild path.
+ *
+ * Pure helper for unit testing; the runtime call site reads `$env` /
+ * `process.platform`. See #1635.
+ */
+export function shouldTrustNativeViewportProbe(
+	env: { WT_SESSION?: string | undefined } = $env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (platform !== "win32") return false;
+	if (env.WT_SESSION) return false;
+	return true;
+}
+
 /**
  * Real terminal using process.stdin/stdout
  */
@@ -214,9 +235,18 @@ export class ProcessTerminal implements Terminal {
 	/**
 	 * Returns true when Windows' active console viewport is at the scrollback tail.
 	 * POSIX terminals do not expose native scrollback position through a standard API.
+	 *
+	 * On native Windows running under Windows Terminal (the default modern
+	 * host), the `kernel32` probe answers about the ConPTY pseudo-console — not
+	 * the user-visible WT viewport — so it would always read "at bottom" while
+	 * the user is scrolled up. Return `undefined` there so the renderer falls
+	 * back to the POSIX-style deferred-rebuild path: streaming mutations stay
+	 * non-destructive (no `\x1b[3J`), and the rebuild fires at the next prompt
+	 * checkpoint via {@link TUI.refreshNativeScrollbackIfDirty} where the user
+	 * is already pinned to the bottom by the editor keystroke. See #1635.
 	 */
 	isNativeViewportAtBottom(): boolean | undefined {
-		if (process.platform !== "win32") return undefined;
+		if (!shouldTrustNativeViewportProbe()) return undefined;
 		try {
 			const kernel32 = dlopen("kernel32.dll", {
 				GetStdHandle: { args: [FFIType.i32], returns: FFIType.ptr },

package/src/tui.ts

@@ -282,6 +282,7 @@ type RenderIntent =
 	| { kind: "initial" }
 	| { kind: "sessionReplace" }
 	| { kind: "historyRebuild" }
+	| { kind: "overlayRebuild" }
 	| { kind: "viewportRepaint"; appendFrom?: number }
 	| { kind: "deferredShrink"; paddedLength: number }
 	| { kind: "deferredMutation" }
@@ -328,7 +329,9 @@ export class TUI extends Container {
 	#nativeScrollbackDirty = false;
 	#fullRedrawCount = 0;
 	#clearScrollbackOnNextRender = false;
+	#forceViewportRepaintOnNextRender = false;
 	#allowUnknownViewportMutationOnNextRender = false;
+	#eagerNativeScrollbackRebuild = false;
 	#hasEverRendered = false;
 	#stopped = false;
 
@@ -376,6 +379,21 @@ export class TUI extends Container {
 		this.#clearOnShrink = enabled;
 	}
 
+	/**
+	 * When enabled, live render frames rebuild native scrollback on offscreen and
+	 * structural changes even when the viewport position is unobservable (POSIX,
+	 * where `isNativeViewportAtBottom()` is `undefined`), instead of deferring to a
+	 * non-destructive repaint. This trades the anti-yank guarantee for a clean,
+	 * duplicate-free history and is meant for windows where output above the fold
+	 * is actively re-rendering — e.g. a tool whose result is still streaming and
+	 * re-laying-out rows that have already scrolled into history. A snap to the tail
+	 * is acceptable there. A terminal that can report a *known*-scrolled viewport
+	 * (Windows) still defers; only the unknown case is forced to rebuild.
+	 */
+	setEagerNativeScrollbackRebuild(enabled: boolean): void {
+		this.#eagerNativeScrollbackRebuild = enabled;
+	}
+
 	setFocus(component: Component | null): void {
 		// Clear focused flag on old component
 		if (isFocusable(this.#focusedComponent)) {
@@ -675,7 +693,7 @@ export class TUI extends Container {
 		) {
 			return false;
 		}
-		this.#prepareForcedRender(true);
+		this.#prepareForcedRender(true, options?.allowUnknownViewport === true);
 		this.#renderRequested = false;
 		this.#lastRenderAt = performance.now();
 		this.#doRender();
@@ -683,9 +701,10 @@ export class TUI extends Container {
 	}
 
 	requestRender(force = false, options?: RenderRequestOptions): void {
-		this.#allowUnknownViewportMutationOnNextRender ||= options?.allowUnknownViewportMutation === true;
+		const allowUnknownViewportMutation = options?.allowUnknownViewportMutation === true;
+		this.#allowUnknownViewportMutationOnNextRender ||= allowUnknownViewportMutation;
 		if (force) {
-			this.#prepareForcedRender(options?.clearScrollback === true);
+			this.#prepareForcedRender(options?.clearScrollback === true, allowUnknownViewportMutation);
 			this.#renderRequested = true;
 			process.nextTick(() => {
 				if (this.#stopped || !this.#renderRequested) {
@@ -702,15 +721,15 @@ export class TUI extends Container {
 		process.nextTick(() => this.#scheduleRender());
 	}
 
-	#prepareForcedRender(clearScrollback: boolean): void {
-		this.#clearScrollbackOnNextRender ||= clearScrollback;
-		this.#previousLines = [];
-		this.#previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
-		this.#previousHeight = -1; // -1 triggers heightChanged, forcing a full clear
-		this.#cursorRow = 0;
-		this.#hardwareCursorRow = 0;
-		this.#viewportTopRow = 0;
-		this.#maxLinesRendered = 0;
+	#prepareForcedRender(clearScrollback: boolean, allowUnknownViewportMutation: boolean): void {
+		const geometryChanged =
+			(this.#previousWidth > 0 && this.#previousWidth !== this.terminal.columns) ||
+			(this.#previousHeight > 0 && this.#previousHeight !== this.terminal.rows);
+		const replayGeometry =
+			geometryChanged &&
+			this.#canReplayNativeScrollbackAtCheckpoint(this.#readNativeViewportAtBottom(), allowUnknownViewportMutation);
+		this.#clearScrollbackOnNextRender ||= clearScrollback || replayGeometry;
+		this.#forceViewportRepaintOnNextRender = true;
 		if (this.#renderTimer) {
 			clearTimeout(this.#renderTimer);
 			this.#renderTimer = undefined;
@@ -1090,23 +1109,27 @@ export class TUI extends Container {
 	 * @returns Cursor position { row, col } or null if no marker found
 	 */
 	#extractCursorPosition(lines: string[], height: number): { row: number; col: number } | null {
-		// Only scan the bottom `height` lines (visible viewport)
+		// Cursor markers are internal sentinels and must never reach the terminal,
+		// even when the focused component is above the visible viewport. Only a
+		// visible marker becomes a hardware cursor target.
 		const viewportTop = Math.max(0, lines.length - height);
-		for (let row = lines.length - 1; row >= viewportTop; row--) {
+		let cursor: { row: number; col: number } | null = null;
+		for (let row = lines.length - 1; row >= 0; row--) {
 			const line = lines[row];
-			const markerIndex = line.indexOf(CURSOR_MARKER);
-			if (markerIndex !== -1) {
-				// Calculate visual column (width of text before marker)
+			let markerIndex = line.indexOf(CURSOR_MARKER);
+			if (markerIndex === -1) continue;
+			if (cursor === null && row >= viewportTop) {
 				const beforeMarker = line.slice(0, markerIndex);
-				const col = visibleWidth(beforeMarker);
-
-				// Strip marker from the line
-				lines[row] = line.slice(0, markerIndex) + line.slice(markerIndex + CURSOR_MARKER.length);
-
-				return { row, col };
+				cursor = { row, col: visibleWidth(beforeMarker) };
 			}
+			let stripped = line;
+			while (markerIndex !== -1) {
+				stripped = stripped.slice(0, markerIndex) + stripped.slice(markerIndex + CURSOR_MARKER.length);
+				markerIndex = stripped.indexOf(CURSOR_MARKER, markerIndex);
+			}
+			lines[row] = stripped;
 		}
-		return null;
+		return cursor;
 	}
 
 	/**
@@ -1140,19 +1163,25 @@ export class TUI extends Container {
 		const height = this.terminal.rows;
 
 		// 1. Compose the frame.
-		let lines = this.render(width);
+		let baseLines = this.render(width);
+		let lines = baseLines;
 		if (this.overlayStack.length > 0) {
-			lines = this.#compositeOverlays(lines, width, height);
+			lines = this.#compositeOverlays(baseLines, width, height);
 		}
 		const cursorPos = this.#extractCursorPosition(lines, height);
-		lines = this.#applyLineResets(lines);
+		lines = this.#fitLinesToWidth(this.#applyLineResets(lines), width);
+		if (lines !== baseLines) {
+			this.#extractCursorPosition(baseLines, height);
+			baseLines = this.#fitLinesToWidth(this.#applyLineResets(baseLines), width);
+		}
 
 		// 2. Capture transition + pre-render state before any emitter runs.
 		const prevViewportTop = this.#viewportTopRow;
 		const prevHardwareCursorRow = this.#hardwareCursorRow;
 		const widthChanged = this.#previousWidth > 0 && this.#previousWidth !== width;
 		const heightChanged = this.#previousHeight > 0 && this.#previousHeight !== height;
-		const allowUnknownViewportMutation = this.#allowUnknownViewportMutationOnNextRender;
+		const allowUnknownViewportMutation =
+			this.#allowUnknownViewportMutationOnNextRender || this.#eagerNativeScrollbackRebuild;
 		this.#allowUnknownViewportMutationOnNextRender = false;
 
 		// 3. Classify intent.
@@ -1192,9 +1221,17 @@ export class TUI extends Container {
 					clearScrollback: !isMultiplexerSession(),
 				});
 				return;
+			case "overlayRebuild":
+				this.#clearNativeScrollbackDirty();
+				this.#emitFullPaint(baseLines, width, height, null, {
+					clearViewport: true,
+					clearScrollback: !isMultiplexerSession(),
+				});
+				this.#emitViewportRepaint(lines, width, height, cursorPos);
+				return;
 			case "viewportRepaint":
 				if (intent.appendFrom !== undefined) {
-					this.#emitAppendTail(lines, intent.appendFrom, height, prevViewportTop, prevHardwareCursorRow);
+					this.#emitAppendTail(lines, intent.appendFrom, height, width, prevViewportTop, prevHardwareCursorRow);
 				}
 				this.#emitViewportRepaint(lines, width, height, cursorPos);
 				return;
@@ -1251,23 +1288,31 @@ export class TUI extends Container {
 		// Caller opted into a scrollback wipe via requestRender(true, { clearScrollback: true }).
 		if (this.#clearScrollbackOnNextRender) return { kind: "sessionReplace" };
 
-		// Forced reset (requestRender(true)) without scrollback wipe: previous
-		// lines were dropped, so no diff is possible. Repaint visible rows only
-		// — emitting the transcript here would duplicate it into scrollback.
-		if (this.#previousLines.length === 0) return { kind: "viewportRepaint" };
+		const forceViewportRepaint = this.#forceViewportRepaintOnNextRender;
+		if (this.hasOverlay()) {
+			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+			if (
+				this.#nativeScrollbackDirty &&
+				this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, allowUnknownViewportMutation)
+			) {
+				return { kind: "overlayRebuild" };
+			}
+			this.#markNativeScrollbackDirty();
+			return { kind: "viewportRepaint" };
+		}
+
 		if (this.#nativeScrollbackDirty && this.#nativeViewportIsAtBottom(this.#readNativeViewportAtBottom())) {
 			return { kind: "historyRebuild" };
 		}
 
 		const diff = this.#diffLines(newLines);
 		// Shrink across the viewport boundary: the new transcript would re-expose
-		// rows already committed to native scrollback. A real resize already
-		// reflowed history, so rebuild it now; a pure content shrink (e.g. a
-		// streaming tail cell collapsing) defers the clear+replay. When the terminal
-		// can report that the user is scrolled into history, the live repaint keeps
-		// the previous row count with blank tail padding; otherwise cursor-home
-		// repainting rewrites old buffer rows with newly bottom-anchored content,
-		// which looks like a jump upward.
+		// rows already committed to native scrollback. Rebuild immediately when the
+		// viewport is known/allowed to be at the tail; otherwise defer the rewrite
+		// and repaint against the previous row count so users scrolled into history
+		// are not yanked. A viewport-only repaint for a bottom-anchored shrink leaves
+		// stale high-water rows in native scrollback and duplicates the new tail above
+		// the viewport.
 		const naturalViewportTop = Math.max(0, newLines.length - height);
 		if (
 			diff.firstChanged !== -1 &&
@@ -1275,18 +1320,57 @@ export class TUI extends Container {
 			naturalViewportTop < this.#scrollbackHighWater &&
 			!isMultiplexerSession()
 		) {
-			if (widthChanged || heightChanged) {
-				if (this.#nativeViewportIsScrolled(this.#readNativeViewportAtBottom(), allowUnknownViewportMutation)) {
-					this.#markNativeScrollbackDirty();
-					return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
-				}
+			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+			if (this.#nativeViewportIsScrolled(nativeViewportAtBottom, allowUnknownViewportMutation)) {
+				this.#markNativeScrollbackDirty();
+				return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
+			}
+			// A width change rewraps the whole transcript, so committed scrollback is
+			// mis-wrapped at the old width. Yank is acceptable on an explicit resize, so
+			// rebuild even when the viewport position is unknown (POSIX); the
+			// known-scrolled case already deferred above.
+			if (
+				widthChanged ||
+				this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, allowUnknownViewportMutation)
+			) {
 				return { kind: "historyRebuild" };
 			}
-			this.#markNativeScrollbackDirty();
-			if (this.#nativeViewportIsScrolled(this.#readNativeViewportAtBottom(), allowUnknownViewportMutation)) {
-				return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
+			// POSIX terminals — and Windows Terminal/ConPTY — that cannot report the
+			// viewport position fall through here (`canRebuildNativeScrollbackLive` is
+			// false). A destructive rebuild emits `\x1b[3J`, which on modern terminals
+			// resets the viewport to the top of scrollback and yanks a scrolled-up
+			// reader (issue #1635), so it is unsafe while the probe is unavailable.
+			//
+			// When the shrunk transcript now fits entirely in the viewport there is no
+			// new native history to preserve during the live frame: repaint the screen
+			// in place (no `\x1b[3J`) and defer stale-scrollback cleanup to the next
+			// checkpoint rebuild (e.g. prompt submit -> `refreshNativeScrollbackIfDirty`).
+			if (nativeViewportAtBottom === undefined && newLines.length <= height) {
+				this.#markNativeScrollbackDirty();
+				return { kind: "viewportRepaint" };
 			}
-			return { kind: "viewportRepaint" };
+			// The shrunk transcript still overflows the viewport. A plain viewport
+			// repaint would re-emit the rows between the new and old viewport tops on top
+			// of the copies the terminal already kept in native scrollback; `deferredShrink`
+			// pads to the previous row count so no committed row is re-emitted, and the
+			// next checkpoint rebuild cleans up.
+			//
+			// That deferral only carries real content when `newLines.length` reaches the
+			// padded viewport top (`previousLines.length - height`) — otherwise every row
+			// the padded repaint draws is past the end of `newLines` and renders blank,
+			// hiding the prompt until the next checkpoint. This can happen even when
+			// `scrollbackHighWater` is far below `previousLines.length - height`, because
+			// prior unknown-POSIX viewport repaints commit longer logical frames without
+			// moving the native scrollback boundary. For a shrink that large a blank,
+			// uninteractable viewport is the greater evil, so yank with `historyRebuild`.
+			// Real win32 unknown probes defer as scrolled above and never reach this; the
+			// yank only lands on non-win32 hosts whose probe is genuinely unavailable.
+			const paddedViewportTop = Math.max(0, this.#previousLines.length - height);
+			if (newLines.length <= paddedViewportTop) {
+				return { kind: "historyRebuild" };
+			}
+			this.#markNativeScrollbackDirty();
+			return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
 		}
 
 		const suppressSuffixScroll = this.#suppressNextSuffixScroll;
@@ -1297,13 +1381,36 @@ export class TUI extends Container {
 			diff.firstChanged < this.#previousLines.length &&
 			!isMultiplexerSession()
 		) {
+			// A checkpoint replay is followed by one frame where transient live chrome
+			// (status/footer rows) may be inserted inside the visible suffix and then
+			// disappear; repaint it in place so it never enters scrollback. If the
+			// insertion grows the overflow boundary, native history would lose rows
+			// while the viewport looks correct, so rebuild instead.
+			const appendedTailStart = this.#findAppendedTailStart(newLines);
+			const overflowBefore = Math.max(0, this.#previousLines.length - height);
+			const overflowAfter = Math.max(0, newLines.length - height);
+			if (
+				appendedTailStart === newLines.length &&
+				diff.firstChanged >= prevViewportTop &&
+				overflowAfter <= overflowBefore
+			) {
+				return { kind: "viewportRepaint" };
+			}
+			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+			if (this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, allowUnknownViewportMutation)) {
+				return { kind: "historyRebuild" };
+			}
+			this.#markNativeScrollbackDirty();
 			return { kind: "viewportRepaint" };
 		}
 
 		if (diff.firstChanged === -1) {
-			// Content unchanged. Width change still alters wrapping geometry;
-			// height change shifts the visible window. Either needs a repaint
-			// (outside hostile environments).
+			// Content unchanged. A forced render still needs to refresh the visible
+			// viewport, but it must keep the existing diff basis so later coalesced
+			// content mutations can still update native scrollback correctly.
+			if (forceViewportRepaint) return { kind: "viewportRepaint" };
+			// Width change still alters wrapping geometry; height change shifts the
+			// visible window. Either needs a repaint (outside hostile environments).
 			if (widthChanged) return { kind: "viewportRepaint" };
 			if (heightChanged && !isTermuxSession() && !isMultiplexerSession()) return { kind: "viewportRepaint" };
 			return { kind: "noop" };
@@ -1328,29 +1435,47 @@ 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()) {
+			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+			if (this.#nativeViewportIsScrolled(nativeViewportAtBottom, allowUnknownViewportMutation)) {
+				this.#markNativeScrollbackDirty();
+				return { kind: "deferredMutation" };
+			}
+		}
 		if (!pureAppend && structuralMutation && !isMultiplexerSession()) {
 			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
 			if (this.#nativeViewportIsScrolled(nativeViewportAtBottom, allowUnknownViewportMutation)) {
 				this.#markNativeScrollbackDirty();
 				return { kind: "deferredMutation" };
 			}
-			// Expanding a collapsed offscreen cell inserts rows before an unchanged
-			// suffix. A viewport-only repaint makes the live bottom look correct but
-			// leaves native scrollback holding the old collapsed rows; scrolling up then
-			// shows a splice of stale history and the new tail. Pure tail appends with an
-			// offscreen status/header tick are still handled by the append-tail path.
+			// The append-tail path can only scroll a clean pure-tail append over an
+			// offscreen edit into history: the rows it pushes must equal the net
+			// growth, i.e. `#findAppendedTailStart` must land on `previousLines.length`
+			// (`tailAppendCount === addedCount`). Any mismatch is structurally
+			// ambiguous — more added than the matched tail means offscreen rows were
+			// inserted (a collapsed cell expanding); fewer means the previous last
+			// line repeats earlier so the tail is mis-located. Under-counting splices
+			// stale history; over-counting scrolls an extra row and duplicates the
+			// line at the viewport top. Rebuild whenever the replay checkpoint allows.
 			if (
 				contentGrew &&
 				diff.firstChanged < prevViewportTop &&
-				this.#canReplayNativeScrollbackAtCheckpoint(nativeViewportAtBottom, false)
+				this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, false)
 			) {
 				const appendedTailStart = diff.appendedLines ? this.#findAppendedTailStart(newLines) : newLines.length;
 				const tailAppendCount = newLines.length - appendedTailStart;
 				const addedCount = newLines.length - this.#previousLines.length;
-				if (addedCount > tailAppendCount) {
+				if (addedCount !== tailAppendCount) {
 					return { kind: "historyRebuild" };
 				}
 			}
+			if (
+				newLines.length !== this.#previousLines.length &&
+				this.#scrollbackHighWater > 0 &&
+				this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, allowUnknownViewportMutation)
+			) {
+				return { kind: "historyRebuild" };
+			}
 		}
 
 		// Height changes shift the visible window. Repaint when content didn't
@@ -1360,6 +1485,17 @@ export class TUI extends Container {
 			return { kind: "viewportRepaint" };
 		}
 
+		// A height change that also grew the content into a frame that now fits
+		// entirely on screen cannot use the diff or append-tail emitters below:
+		// both position scrolled rows against the previous viewport top and
+		// hardware cursor row, which the reflow just invalidated, so the appended
+		// tail lands `height`-delta rows too low. With no overflow there is no
+		// native scrollback to preserve, so repaint the viewport at the new
+		// geometry. (Height changes with overflow keep the existing deferral.)
+		if (heightChanged && newLines.length <= height && !isTermuxSession() && !isMultiplexerSession()) {
+			return { kind: "viewportRepaint" };
+		}
+
 		// Configurable shrink-clear: opt-in path that repaints to wipe rows the
 		// diff path would leave behind.
 		if (this.#clearOnShrink && newLines.length < this.#previousLines.length && this.overlayStack.length === 0) {
@@ -1371,11 +1507,33 @@ export class TUI extends Container {
 			return { kind: "shrink" };
 		}
 
-		// Offscreen edit: viewport repaint corrects shifted rows when the native
-		// viewport is at the tail. Scrolled native-history cases are deferred above.
+		// Offscreen edit: repainting only the viewport leaves native history stale
+		// while the user is bottom-anchored. Rebuild whenever replay is safe. If
+		// replay is not safe, keep the viewport stable, mark history dirty, and only
+		// scroll a clean appended tail so newly streamed rows remain reachable until
+		// the next checkpoint rebuild.
 		if (diff.firstChanged < prevViewportTop) {
-			const appendFrom = diff.appendedLines ? this.#findAppendedTailStart(newLines) : undefined;
-			return { kind: "viewportRepaint", appendFrom };
+			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+			const cleanTailAppend =
+				diff.appendedLines && this.#findAppendedTailStart(newLines) === this.#previousLines.length;
+			if (
+				!isMultiplexerSession() &&
+				this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, allowUnknownViewportMutation)
+			) {
+				return { kind: "historyRebuild" };
+			}
+			this.#markNativeScrollbackDirty();
+			return { kind: "viewportRepaint", appendFrom: cleanTailAppend ? this.#previousLines.length : undefined };
+		}
+
+		if (forceViewportRepaint) {
+			if (isMultiplexerSession()) return { kind: "viewportRepaint" };
+			if (pureAppend && contentGrew && this.#previousLines.length >= height) {
+				return { kind: "viewportRepaint", appendFrom: this.#previousLines.length };
+			}
+			if (newLines.length === this.#previousLines.length && diff.firstChanged >= prevViewportTop) {
+				return { kind: "viewportRepaint" };
+			}
 		}
 
 		return {
@@ -1477,6 +1635,30 @@ export class TUI extends Container {
 		);
 	}
 
+	/**
+	 * Live-frame counterpart to {@link #canReplayNativeScrollbackAtCheckpoint}.
+	 * Decides whether a destructive native scrollback rebuild
+	 * (`historyRebuild`/`overlayRebuild`, which clear scrollback and snap the
+	 * viewport to the tail) is safe to emit *during ordinary rendering*. POSIX
+	 * terminals cannot report whether the user has scrolled up
+	 * (`isNativeViewportAtBottom()` is `undefined`), so an unknown position is
+	 * treated as unsafe: defer to a non-destructive viewport repaint, mark
+	 * scrollback dirty, and reconcile history at the next explicit checkpoint
+	 * ({@link refreshNativeScrollbackIfDirty} on prompt submit) where the
+	 * editor keystroke has already pinned the terminal to the bottom. Without
+	 * this, every offscreen transcript edit while streaming wiped scrollback and
+	 * yanked a scrolled-up reader back down. `allowUnknownViewportMutation`
+	 * (autocomplete/IME) opts directly user-driven frames back into the rebuild.
+	 * Unlike the checkpoint predicate this carries no `process.platform`
+	 * optimism — resize and checkpoint replays keep using that one.
+	 */
+	#canRebuildNativeScrollbackLive(
+		nativeViewportAtBottom: boolean | undefined,
+		allowUnknownViewportMutation: boolean,
+	): boolean {
+		return nativeViewportAtBottom === true || (nativeViewportAtBottom === undefined && allowUnknownViewportMutation);
+	}
+
 	#padDeferredShrinkLines(lines: string[], paddedLength: number): string[] {
 		if (lines.length >= paddedLength) return lines;
 		return [...lines, ...new Array<string>(paddedLength - lines.length).fill("")];
@@ -1488,6 +1670,13 @@ export class TUI extends Container {
 	 * `truncateToWidth` drops the trailing bytes appended by
 	 * {@link #applyLineResets}.
 	 */
+	#fitLinesToWidth(lines: string[], width: number): string[] {
+		for (let i = 0; i < lines.length; i++) {
+			lines[i] = this.#fitLineToWidth(lines[i], width);
+		}
+		return lines;
+	}
+
 	#fitLineToWidth(line: string, width: number): string {
 		if (TERMINAL.isImageLine(line)) return line;
 		if (visibleWidth(line) <= width) return line;
@@ -1501,6 +1690,7 @@ export class TUI extends Container {
 	 */
 	#commit(lines: string[], width: number, height: number, viewportTop: number, hardwareCursorRow: number): void {
 		this.#previousLines = lines;
+		this.#forceViewportRepaintOnNextRender = false;
 		this.#previousWidth = width;
 		this.#previousHeight = height;
 		this.#cursorRow = Math.max(0, lines.length - 1);
@@ -1526,7 +1716,7 @@ export class TUI extends Container {
 		}
 		for (let i = 0; i < lines.length; i++) {
 			if (i > 0) buffer += "\r\n";
-			buffer += lines[i];
+			buffer += this.#fitLineToWidth(lines[i], width);
 		}
 		const finalRow = Math.max(0, lines.length - 1);
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, finalRow);
@@ -1592,6 +1782,7 @@ export class TUI extends Container {
 		lines: string[],
 		start: number,
 		height: number,
+		width: number,
 		prevViewportTop: number,
 		prevHardwareCursorRow: number,
 	): void {
@@ -1606,7 +1797,7 @@ export class TUI extends Container {
 		if (moveToBottom > 0) buffer += `\x1b[${moveToBottom}B`;
 		for (let i = start; i < lines.length; i++) {
 			buffer += "\r\n";
-			buffer += lines[i];
+			buffer += this.#fitLineToWidth(lines[i], width);
 		}
 		buffer += PAINT_END;
 		this.terminal.write(buffer);