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

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [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

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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.7.3",
+	"version": "15.7.5",
 	"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.7.3",
-		"@oh-my-pi/pi-utils": "15.7.3",
+		"@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/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

@@ -1335,8 +1335,42 @@ export class TUI extends Container {
 			) {
 				return { kind: "historyRebuild" };
 			}
+			// 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" };
+			}
+			// 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: "viewportRepaint" };
+			return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
 		}
 
 		const suppressSuffixScroll = this.#suppressNextSuffixScroll;