@oh-my-pi/pi-tui 15.7.6 → 15.8.0

package/CHANGELOG.md

@@ -2,14 +2,19 @@
 
 ## [Unreleased]
 
-## [15.7.6] - 2026-06-01
+## [15.8.0] - 2026-06-02
 
 ### Fixed
 
-- Fixed native Windows + Windows Terminal freezing the editor on the wrap keystroke, on `/plan`/`/resume`/model-switch/status-line toggles, and on any other offscreen structural mutation until the next prompt submit. The `15.7.5` `#1635` fix routed every viewport-saturating pure-append and structural mutation through `deferredMutation` (a literal no-op) whenever `isNativeViewportAtBottom()` returned `undefined` — which it always does under `WT_SESSION` because the kernel32 probe can't see WT host scrollback. The deferral was only ever meant for the *confirmed-scrolled* case; an unknown viewport now falls back to a non-destructive `viewportRepaint` instead, so the live UI keeps updating without emitting `\x1b[3J` and without yanking a possibly-scrolled reader. Confirmed-scrolled frames (probe returns `false`) still defer.
+- Deferred eager live scrollback rebuilds on POSIX terminals where xterm ED3 (`CSI 3 J`, erase saved lines) can disturb scrolled-up readers during streaming, while keeping direct user-input and checkpoint rebuilds explicit ([#1682](https://github.com/can1357/oh-my-pi/issues/1682)).
+- Fixed TUI shutdown placing the parent shell prompt one row below short rendered content instead of directly on the next line ([#1620](https://github.com/can1357/oh-my-pi/issues/1620)).
+- Stopped painting inline color swatches for 4-digit hex runs in Markdown rendering. The `#RGBA` CSS form collides with hashline `#TAG` snapshot tags (4 hex digits, e.g. `#6C5E`), which were sprouting spurious RGB swatches in prose and codespans. Only `#RGB`, `#RRGGBB`, and `#RRGGBBAA` qualify now.
+
+## [15.7.6] - 2026-06-01
 
 ### Fixed
 
+- Fixed native Windows + Windows Terminal freezing the editor on the wrap keystroke, on `/plan`/`/resume`/model-switch/status-line toggles, and on any other offscreen structural mutation until the next prompt submit. The `15.7.5` `#1635` fix routed every viewport-saturating pure-append and structural mutation through `deferredMutation` (a literal no-op) whenever `isNativeViewportAtBottom()` returned `undefined` — which it always does under `WT_SESSION` because the kernel32 probe can't see WT host scrollback. The deferral was only ever meant for the *confirmed-scrolled* case; an unknown viewport now falls back to a non-destructive `viewportRepaint` instead, so the live UI keeps updating without emitting `\x1b[3J` and without yanking a possibly-scrolled reader. Confirmed-scrolled frames (probe returns `false`) still defer.
 - Removed the hard-coded 20-result cap on `@`-prefixed fuzzy file completion in `CombinedAutocompleteProvider.#getFuzzyFileSuggestions`. The dropdown now honors the existing `maxResults: 100` ceiling already configured for `fuzzyFind`, so projects with many files sharing a common stem (e.g. `@controller`, `@test`) surface all relevant matches instead of being silently truncated. ([#1652](https://github.com/can1357/oh-my-pi/issues/1652))
 
 ## [15.7.5] - 2026-06-01
@@ -50,6 +55,7 @@
 - Fixed slash-command autocomplete repainting when a Windows Terminal session cannot report native scrollback position; live input renders can now bypass the unknown-viewport deferral without weakening background scrollback protection. ([#1550](https://github.com/can1357/oh-my-pi/issues/1550))
 
 ## [15.6.0] - 2026-05-30
+
 ### Added
 
 - Added autocomplete triggering for internal URL scheme tokens such as `local://` and `skill://` while typing in the editor
@@ -96,6 +102,7 @@
 - Fixed full TUI redraws clearing terminal scrollback with `CSI 3 J`, preserving manual scrollback inspection while active sessions continue updating. ([#1295](https://github.com/can1357/oh-my-pi/issues/1295))
 
 ## [15.2.3] - 2026-05-22
+
 ### Added
 
 - Added `SettingsList#setItems` to replace the entire settings list with a new items array while automatically clamping selection to a valid index
@@ -123,6 +130,7 @@
 - Restored the `Key` runtime helper on `@oh-my-pi/pi-tui` to mirror upstream `@mariozechner/pi-tui`'s surface. `Key.enter`, `Key.escape`, `Key.tab`, … return the canonical key-name strings; modifier methods (`Key.ctrl(k)`, `Key.shift(k)`, `Key.ctrlShift(k)`, etc.) build precisely-typed `KeyId` literals like `"ctrl+c"`. Pure runtime convenience for typed key-id construction — plugins built against the upstream package surface that import `Key` (e.g. `@plannotator/pi-extension`, `@juicesharp/rpiv-ask-user-question`) load again now that the specifier shim remaps them onto this package.
 
 ## [15.0.1] - 2026-05-14
+
 ### Breaking Changes
 
 - Increased the minimum required Bun version for the TUI package from >=1.3.7 to >=1.3.14
@@ -156,6 +164,10 @@
 - `SlashCommand.getArgumentCompletions()` may return a `Promise`; results are now awaited and non-array returns are ignored (ports pi-mono `a1e10789`)
 - Fuzzy `@` autocomplete now follows symlinked directories via `ScanOptions.follow_links` plumbed through the native walker (ports pi-mono `780d5367`)
 - Plain `@<query>` (no slash) fuzzy matches by basename only, so `@plan` no longer surfaces every file whose ancestor directories contain `plan` (ports pi-mono `968430f6`)
+- Changed slash-command autocomplete list rendering to combine command hint and description in a single displayed suggestion text
+- Changed render scheduling to throttle `requestRender` calls to roughly 60fps by batching updates
+- Changed terminal input handling to process complete cell-size responses without buffering partial input
+- Changed `KeyId` to accept super-modifier combinations and improve typed key-id validation
 
 ### Fixed
 
@@ -171,20 +183,11 @@
 - Allowed `SlashCommand.getArgumentCompletions` to return asynchronous results by accepting Promise-based completions
 - Added `argumentHint` support to slash command definitions and displayed it in command suggestion descriptions
 - Added support for xterm `modifyOtherKeys` printable key sequences by decoding `CSI 27;mod;key~` into text input
-
-### Changed
-
-- Changed slash-command autocomplete list rendering to combine command hint and description in a single displayed suggestion text
-- Changed render scheduling to throttle `requestRender` calls to roughly 60fps by batching updates
-- Changed terminal input handling to process complete cell-size responses without buffering partial input
-- Changed `KeyId` to accept super-modifier combinations and improve typed key-id validation
-
-### Fixed
-
 - Normalized line output during rendering to correct Thai/Lao AM glyph composition for displayed text
 - Fixed duplicated Kitty key input emissions by dropping the matching unmodified follow-up sequence after a Kitty CSI-u printable-key event
 
 ## [14.9.5] - 2026-05-12
+
 ### Fixed
 
 - Fixed rapidly blinking cursor artifact during task execution by consolidating cursor control sequences into the synchronized output buffer ([#992](https://github.com/can1357/oh-my-pi/issues/992))
@@ -238,6 +241,7 @@
 - Autocomplete fuzzy discovery now accepts optional SearchDb instance for faster searches
 
 ## [13.16.0] - 2026-03-27
+
 ### Changed
 
 - Updated tab replacement in editor text sanitization to respect configured tab width setting
@@ -253,6 +257,7 @@
 - Fixed editor consuming user-rebound copy keys, preventing custom keybindings from working in the editor
 
 ## [13.14.1] - 2026-03-21
+
 ### Added
 
 - Added Ctrl+_ as an additional default shortcut for undo
@@ -273,17 +278,20 @@
 - Fixed paste marker expansion to handle special regex replacement tokens ($1, $2, $&, $$, $`, $') literally in pasted content
 
 ## [13.11.0] - 2026-03-12
+
 ### Fixed
 
 - Fixed OSC 11 background color detection to correctly handle partial escape sequences that arrive mid-buffer, preventing user input from being swallowed
 - Fixed race condition where overlapping OSC 11 queries would be incorrectly cancelled by DA1 sentinels from previous queries
 
 ## [13.7.5] - 2026-03-04
+
 ### Changed
 
 - Extracted word navigation logic into reusable `moveWordLeft` and `moveWordRight` utility functions for consistent cursor movement across components
 
 ## [13.6.2] - 2026-03-03
+
 ### Fixed
 
 - Fixed cursor positioning when content shrinks to empty without clearOnShrink enabled
@@ -293,6 +301,7 @@
 ### Fixed
 
 - Fixed viewport repaint scrollback accounting during resize oscillation to avoid double-scrolling on height shrink and added exact-row scrollback assertions in overlay regression coverage ([#228](https://github.com/can1357/oh-my-pi/issues/228), [#234](https://github.com/can1357/oh-my-pi/issues/234))
+
 ## [13.5.3] - 2026-03-01
 
 ### Fixed
@@ -302,6 +311,7 @@
 - Fixed cursor positioning instability when appending content under external cursor relocation by using absolute screen addressing instead of relative cursor movement
 
 ## [13.5.2] - 2026-03-01
+
 ### Breaking Changes
 
 - Removed `getMermaidImage` callback from MarkdownTheme; replaced with `getMermaidAscii` that accepts ASCII string instead of image data
@@ -312,6 +322,7 @@
 - Mermaid diagrams now render as ASCII text instead of terminal graphics protocol images
 
 ## [13.5.1] - 2026-03-01
+
 ### Fixed
 
 - Fixed viewport shift handling to prevent stale content when mixed updates remap screen rows
@@ -339,6 +350,7 @@
 
 - Fixed stale/duplicated terminal cursor dedup state by synchronizing `#lastCursorSequence` in all render write paths (hard reset, viewport repaint, deleted-lines clear path, append fast path, and differential path).
 - Fixed scroll overshoot on `stop()` when content fills the viewport by clamping target row movement to valid screen rows.
+
 ## [13.4.0] - 2026-03-01
 
 ### Added
@@ -360,6 +372,7 @@
 - Restored terminal image protocol override and fallback detection for image rendering, including `PI_FORCE_IMAGE_PROTOCOL` support and Kitty fallback for screen/tmux/ghostty-style TERM environments.
 
 ## [13.3.8] - 2026-02-28
+
 ### Breaking Changes
 
 - Changed mermaid hash type from string to bigint in `getMermaidImage` callback and `extractMermaidBlocks` return type
@@ -381,6 +394,7 @@
 - Fixed stale viewport rows appearing when terminal height increases by triggering full re-render on height changes
 
 ## [12.18.0] - 2026-02-21
+
 ### Fixed
 
 - Fixed viewport synchronization issue by clearing scrollback when terminal state becomes desynced during full re-renders
@@ -409,18 +423,21 @@
 - Fixed incremental stale-row clearing to use erase-below semantics in synchronized output, reducing leftover-line artifacts after shrink operations.
 
 ## [12.9.0] - 2026-02-17
+
 ### Added
 
 - Exported `getTerminalId()` function to get a stable identifier for the current terminal, with support for TTY device paths and terminal multiplexers
 - Exported `getTtyPath()` function to resolve the TTY device path for stdin via POSIX `ttyname(3)`
 
 ## [12.5.0] - 2026-02-15
+
 ### Added
 
 - Added `cursorOverride` and `cursorOverrideWidth` properties to customize the end-of-text cursor glyph with ANSI-styled strings
 - Added `getUseTerminalCursor()` method to query the terminal cursor mode setting
 
 ## [11.10.0] - 2026-02-10
+
 ### Added
 
 - Added `hint` property to autocomplete items to display dim ghost text after cursor when item is selected
@@ -433,6 +450,7 @@
 - Updated editor to render inline hint text as dim ghost text after cursor when autocomplete suggestions are active or provider supplies hints
 
 ## [11.8.0] - 2026-02-10
+
 ### Added
 
 - Added Alt+Y keybinding to cycle through kill ring entries (yank-pop)
@@ -449,6 +467,7 @@
 - Changed undo coalescing in Input component to group consecutive word typing into single undo units
 
 ## [11.4.1] - 2026-02-06
+
 ### Fixed
 
 - Fixed terminal scrolling when displaying overlays after rendering large content, preventing hundreds of blank lines from being output
@@ -541,6 +560,7 @@
 - Fixed handling of private use Unicode codepoints (U+E000 to U+F8FF) in Kitty key decoding to prevent invalid character interpretation
 
 ## [9.7.0] - 2026-02-01
+
 ### Breaking Changes
 
 - Removed `Key` helper object from public API; use string literals like `"ctrl+c"` instead of `Key.ctrl("c")`
@@ -552,6 +572,7 @@
 - Simplified `isKeyRelease()` and `isKeyRepeat()` to use regex pattern matching instead of string inclusion checks
 
 ## [9.6.2] - 2026-02-01
+
 ### Changed
 
 - Renamed `EllipsisKind` enum to `Ellipsis` for clearer API naming
@@ -565,6 +586,7 @@
 - Removed `extractAnsiCode` function from public API
 
 ## [9.6.1] - 2026-02-01
+
 ### Changed
 
 - Improved performance of key ID parsing with optimized cache lookup strategy
@@ -575,12 +597,14 @@
 - Removed `visibleWidth` benchmark file in favor of Kitty sequence benchmarking
 
 ## [9.5.0] - 2026-02-01
+
 ### Changed
 
 - Improved fuzzy file search performance by using native implementation instead of spawning external process
 - Replaced external `fd` binary with native fuzzy path search for `@`-prefixed autocomplete
 
 ## [9.4.0] - 2026-01-31
+
 ### Added
 
 - Exported `padding` utility function for creating space-padded strings efficiently
@@ -592,59 +616,74 @@
 ## [9.2.2] - 2026-01-31
 
 ### Added
+
 - Added setAutocompleteMaxVisible() configuration (3-20 items)
 - Added image detection to terminal capabilities (containsImage method)
 - Added stdin monitoring to detect stalled input events and log warnings
 
 ### Changed
+
 - Improved blockquote rendering with text wrapping in Markdown component
 - Restructured terminal capabilities from interface-based to class-based model
 - Improved table column width calculation with word-aware wrapping
 - Refactored text utilities to use native WASM implementations for strings >256 chars with JS fast path
 
 ### Fixed
+
 - Simplified terminal write error handling to mark terminal as dead on any write failure
 - Fixed multi-line strings in renderOutputBlock causing width overflow
 - Fixed slash command autocomplete applying stale completion when typing quickly
 
 ### Removed
+
 - Removed TUI layout engine exports from public API (BoxNode, ColumnNode, LayoutNode, etc.)
 
 ## [8.12.7] - 2026-01-29
 
 ### Fixed
+
 - Fixed slash command autocomplete applying stale completion when typing quickly
 
 ## [8.4.1] - 2026-01-25
 
 ### Added
+
 - Added fuzzy match function for autocomplete suggestions
+
 ## [8.4.0] - 2026-01-25
 
 ### Changed
+
 - Added Ctrl+Backspace as a delete-word-backward keybinding and improved modified backspace matching
 
 ### Fixed
+
 - Terminal gracefully handles write failures by marking dead instead of exiting the process
 - Reserved cursor space for zero padding and corrected end-of-line cursor rendering to prevent wrap glitches
 - Corrected editor end-of-line cursor rendering assertion to use includes() instead of endsWith()
+
 ## [8.2.0] - 2026-01-24
 
 ### Added
+
 - Added mermaid diagram rendering engine (renderMermaidToPng) with mmdc CLI integration
 - Added terminal graphics encoding (iTerm2/Kitty) for mermaid diagrams with automatic width scaling
 - Added mermaid block extraction and deduplication utilities (extractMermaidBlocks)
 
 ### Changed
+
 - Updated TypeScript configuration for better publish-time configuration handling with tsconfig.publish.json
 - Migrated file system operations from synchronous to asynchronous APIs in autocomplete provider for non-blocking I/O
 - Migrated node module imports from named to namespace imports across all packages for consistency with project guidelines
 
 ### Fixed
+
 - Fixed crash when terminal becomes unavailable (EIO errors) by exiting gracefully instead of throwing
 - Fixed potential errors during emergency terminal restore when terminal is already dead
 - Fixed autocomplete race condition by tracking request ID to prevent stale suggestion results
+
 ## [6.8.3] - 2026-01-21
+
 ### Added
 
 - Added undo support in the editor via `Ctrl+-`
@@ -700,6 +739,7 @@
 - Fixed Alt+letter key combinations for better recognition
 
 ## [5.3.1] - 2026-01-15
+
 ### Fixed
 
 - Fixed rendering issues on Windows by preventing re-entrant renders
@@ -729,27 +769,32 @@
 ## [4.7.0] - 2026-01-12
 
 ### Fixed
+
 - Remove trailing space padding from Text, Markdown, and TruncatedText components when no background color is set (fixes copied text including unwanted whitespace)
 
 ## [4.6.0] - 2026-01-12
 
 ### Added
+
 - Add fuzzy matching module (`fuzzyMatch`, `fuzzyFilter`) for command autocomplete
 - Add `getExpandedText()` to editor for expanding paste markers
 - Add backslash+enter newline fallback for terminals without Kitty protocol
 
 ### Fixed
+
 - Remove Kitty protocol query timeout that caused shift+enter delays
 - Add bracketed paste check to prevent false key release/repeat detection
 - Rendering optimizations: only re-render changed lines
 - Refactor input component to use keybindings manager
 
 ## [4.4.4] - 2026-01-11
+
 ### Fixed
 
 - Fixed Ctrl+Enter sequences to insert new lines in the editor
 
 ## [4.2.1] - 2026-01-11
+
 ### Changed
 
 - Improved file autocomplete to show directory listing when typing `@` with no query, and fall back to prefix matching when fuzzy search returns no results
@@ -760,11 +805,13 @@
 - Fixed `fd` tool detection to automatically find `fd` or `fdfind` in PATH when not explicitly configured
 
 ## [4.1.0] - 2026-01-10
+
 ### Added
 
 - Added persistent prompt history storage support via `setHistoryStorage()` method, allowing history to be saved and restored across sessions
 
 ## [4.0.0] - 2026-01-10
+
 ### Added
 
 - `EditorComponent` interface for custom editor implementations
@@ -795,6 +842,7 @@
 - Fixed text wrapping allowing long whitespace tokens to exceed line width
 
 ## [3.20.0] - 2026-01-06
+
 ### Added
 
 - Added `isCapsLock` helper function for detecting Caps Lock key press via Kitty protocol
@@ -826,6 +874,7 @@
 - Added support for custom spinner frames in the Loader component
 
 ## [3.9.1337] - 2026-01-04
+
 ### Added
 
 - Added `setTopBorder()` method to Editor component for displaying custom status content in the top border
@@ -838,6 +887,7 @@
 - Changed cursor style from block to thin blinking bar (▏) at end of line
 
 ## [1.500.0] - 2026-01-03
+
 ### Added
 
 - Added `getText()` method to Text component for retrieving current text content
@@ -902,4 +952,4 @@ Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mon
 
 ### Fixed
 
-- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))
+- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))

package/dist/types/terminal.d.ts

@@ -56,6 +56,28 @@ export interface Terminal {
 export declare function shouldTrustNativeViewportProbe(env?: {
     WT_SESSION?: string | undefined;
 }, platform?: NodeJS.Platform): boolean;
+/**
+ * Whether eager live-frame native scrollback rebuilds are unsafe for the
+ * current POSIX terminal when its viewport position is unobservable.
+ *
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). On the
+ * terminals below, ED3 can disturb a reader parked in native scrollback during
+ * streaming: kitty/ghostty/alacritty clamp the scroll offset back to the active
+ * tail when saved lines are erased, and WezTerm is the reported POSIX host for
+ * #1682. Defer only the eager streaming opt-in on these hosts; direct
+ * user-input renders and explicit checkpoint rebuilds still pass their own
+ * `allowUnknownViewportMutation` / `allowUnknownViewport` flags.
+ *
+ * Pure helper for unit testing; the runtime call site reads `$env` /
+ * `process.platform`. See #1682.
+ */
+export declare function terminalHasEagerEraseScrollbackRisk(env?: {
+    WEZTERM_PANE?: string | undefined;
+    KITTY_WINDOW_ID?: string | undefined;
+    GHOSTTY_RESOURCES_DIR?: string | undefined;
+    ALACRITTY_WINDOW_ID?: string | undefined;
+    TERM_PROGRAM?: string | undefined;
+}, platform?: NodeJS.Platform): boolean;
 /**
  * Real terminal using process.stdin/stdout
  */

package/dist/types/tui.d.ts

@@ -1,4 +1,4 @@
-import type { Terminal } from "./terminal";
+import { type Terminal } from "./terminal";
 import { visibleWidth } from "./utils";
 type InputListenerResult = {
     consume?: boolean;
@@ -171,9 +171,11 @@ export declare class TUI extends Container {
      * 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.
+     * re-laying-out rows that have already scrolled into history. A terminal that
+     * can report a *known*-scrolled viewport (Windows) still defers; only the
+     * unknown 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.
      */
     setEagerNativeScrollbackRebuild(enabled: boolean): void;
     setFocus(component: Component | null): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.7.6",
+	"version": "15.8.0",
 	"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.6",
-		"@oh-my-pi/pi-utils": "15.7.6",
+		"@oh-my-pi/pi-natives": "15.8.0",
+		"@oh-my-pi/pi-utils": "15.8.0",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/markdown.ts

@@ -146,22 +146,24 @@ const DEFAULT_COLOR_SWATCH_GLYPH = "■";
 // entities like ☃ and paths like foo#fff) and not trailed by more hex
 // (so over-long runs never produce a misleading swatch). Length/letter rules
 // are enforced in classifyHexColor since the alternation can't express "exactly
-// 3, 4, 6, or 8".
+// 3, 6, or 8".
 const HEX_COLOR_REGEX = /(?<![\w#&])#([0-9a-fA-F]{3,8})(?![0-9a-fA-F])/g;
 const HEX_COLOR_EXACT_REGEX = /^#([0-9a-fA-F]{3,8})$/;
 
 /**
  * Decide whether a run of hex digits denotes a renderable CSS color.
  *
- * Only the canonical CSS lengths (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) qualify. In
- * `strict` mode (bare prose) a 3/4-digit run must contain a hex letter, so the
+ * Only the canonical CSS lengths (#RGB, #RRGGBB, #RRGGBBAA) qualify. The 4-digit
+ * #RGBA form is deliberately excluded: it collides with hashline `#TAG` snapshot
+ * tags (4 hex digits, e.g. #6C5E), which would otherwise sprout spurious swatches.
+ * In `strict` mode (bare prose) a 3-digit run must contain a hex letter, so the
  * far more common short issue/PR references (#123, #1011) don't sprout swatches.
  * Codespans opt out of strictness — the backticks already signal "this is a color".
  */
 function classifyHexColor(hex: string, strict: boolean): boolean {
 	const n = hex.length;
-	if (n !== 3 && n !== 4 && n !== 6 && n !== 8) return false;
-	if (strict && n <= 4 && !/[a-fA-F]/.test(hex)) return false;
+	if (n !== 3 && n !== 6 && n !== 8) return false;
+	if (strict && n === 3 && !/[a-fA-F]/.test(hex)) return false;
 	return true;
 }
 

package/src/terminal.ts

@@ -134,6 +134,39 @@ export function shouldTrustNativeViewportProbe(
 	return true;
 }
 
+/**
+ * Whether eager live-frame native scrollback rebuilds are unsafe for the
+ * current POSIX terminal when its viewport position is unobservable.
+ *
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). On the
+ * terminals below, ED3 can disturb a reader parked in native scrollback during
+ * streaming: kitty/ghostty/alacritty clamp the scroll offset back to the active
+ * tail when saved lines are erased, and WezTerm is the reported POSIX host for
+ * #1682. Defer only the eager streaming opt-in on these hosts; direct
+ * user-input renders and explicit checkpoint rebuilds still pass their own
+ * `allowUnknownViewportMutation` / `allowUnknownViewport` flags.
+ *
+ * Pure helper for unit testing; the runtime call site reads `$env` /
+ * `process.platform`. See #1682.
+ */
+export function terminalHasEagerEraseScrollbackRisk(
+	env: {
+		WEZTERM_PANE?: string | undefined;
+		KITTY_WINDOW_ID?: string | undefined;
+		GHOSTTY_RESOURCES_DIR?: string | undefined;
+		ALACRITTY_WINDOW_ID?: string | undefined;
+		TERM_PROGRAM?: string | undefined;
+	} = $env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (platform === "win32") return false;
+	if (env.WEZTERM_PANE || env.KITTY_WINDOW_ID || env.GHOSTTY_RESOURCES_DIR || env.ALACRITTY_WINDOW_ID) {
+		return true;
+	}
+	const termProgram = env.TERM_PROGRAM?.toLowerCase();
+	return termProgram === "ghostty";
+}
+
 /**
  * Real terminal using process.stdin/stdout
  */

package/src/tui.ts

@@ -6,7 +6,7 @@ import * as path from "node:path";
 import { performance } from "node:perf_hooks";
 import { $flag, getDebugLogPath } from "@oh-my-pi/pi-utils";
 import { isKeyRelease, matchesKey } from "./keys";
-import type { Terminal } from "./terminal";
+import { type Terminal, terminalHasEagerEraseScrollbackRisk } from "./terminal";
 import { ImageProtocol, setCellDimensions, setTerminalImageProtocol, TERMINAL } from "./terminal-capabilities";
 import {
 	Ellipsis,
@@ -386,9 +386,11 @@ export class TUI extends Container {
 	 * 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.
+	 * re-laying-out rows that have already scrolled into history. A terminal that
+	 * can report a *known*-scrolled viewport (Windows) still defers; only the
+	 * unknown 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.
 	 */
 	setEagerNativeScrollbackRebuild(enabled: boolean): void {
 		this.#eagerNativeScrollbackRebuild = enabled;
@@ -664,16 +666,23 @@ export class TUI extends Container {
 			clearTimeout(this.#renderTimer);
 			this.#renderTimer = undefined;
 		}
-		// Move cursor to the end of the content to prevent overwriting/artifacts on exit
+		// Place the parent shell on the first line after the rendered content. When
+		// that line is still inside the viewport, moving there and writing `\r` is
+		// enough; emitting `\r\n` would create an extra blank row. If the content
+		// already reaches the viewport bottom, scroll exactly once so the prompt
+		// lands directly below the last visible TUI row.
 		if (this.#previousLines.length > 0) {
-			const targetRow = this.#previousLines.length; // Line after the last content
-			const lineDiff = targetRow - this.#hardwareCursorRow;
+			const targetRow = this.#previousLines.length;
+			const viewportBottom = this.#viewportTopRow + this.terminal.rows - 1;
+			const clampedCursorRow = Math.max(this.#viewportTopRow, Math.min(this.#hardwareCursorRow, viewportBottom));
+			const moveTargetRow = Math.min(targetRow, viewportBottom);
+			const lineDiff = moveTargetRow - clampedCursorRow;
 			if (lineDiff > 0) {
 				this.terminal.write(`\x1b[${lineDiff}B`);
 			} else if (lineDiff < 0) {
 				this.terminal.write(`\x1b[${-lineDiff}A`);
 			}
-			this.terminal.write("\r\n");
+			this.terminal.write(targetRow <= viewportBottom ? "\r" : "\r\n");
 		}
 
 		this.terminal.showCursor();
@@ -1180,8 +1189,8 @@ export class TUI extends Container {
 		const prevHardwareCursorRow = this.#hardwareCursorRow;
 		const widthChanged = this.#previousWidth > 0 && this.#previousWidth !== width;
 		const heightChanged = this.#previousHeight > 0 && this.#previousHeight !== height;
-		const allowUnknownViewportMutation =
-			this.#allowUnknownViewportMutationOnNextRender || this.#eagerNativeScrollbackRebuild;
+		const eagerRebuildAllowed = this.#eagerNativeScrollbackRebuild && !terminalHasEagerEraseScrollbackRisk();
+		const allowUnknownViewportMutation = this.#allowUnknownViewportMutationOnNextRender || eagerRebuildAllowed;
 		this.#allowUnknownViewportMutationOnNextRender = false;
 
 		// 3. Classify intent.
@@ -1337,8 +1346,8 @@ export class TUI extends Container {
 			}
 			// 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
+			// false). A destructive rebuild emits `\x1b[3J` (xterm erase saved lines),
+			// which can clear or reposition native scrollback and yank 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
@@ -1660,8 +1669,8 @@ 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
+	 * (`historyRebuild`/`overlayRebuild`, which clears saved lines and may move
+	 * the native viewport) 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
@@ -1669,10 +1678,11 @@ export class TUI extends Container {
 	 * ({@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.
+	 * yanked a scrolled-up reader out of their current context.
+	 * `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,