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

package/CHANGELOG.md

@@ -2,7 +2,57 @@
 
 ## [Unreleased]
 
+## [15.9.5] - 2026-06-05
+
+### Changed
+
+- Changed terminal resize handling so any width or height change always performs a clean reset + redraw: the renderer now unconditionally clears the viewport and native scrollback (`CSI 2 J` / `CSI 3 J`) and replays the full transcript at the new geometry, replacing the previous matrix of conditional viewport-repaint / history-rebuild / deferred-mutation branches. Multiplexer panes still repaint the visible window in place (pane scrollback cannot be erased), but a resize during active ED3-risk foreground streaming now performs the same clean rebuild rather than downgrading to a non-destructive viewport repaint: the terminal already re-wrapped its saved lines at the old width, so the rebuild must erase them (ED 3) instead of leaving the mis-wrapped history on screen. As a deliberate tradeoff this drops the prior no-overflow and confirmed-scrolled guards on resize: a reader scrolled into history snaps back to the bottom and preexisting shell scrollback above the UI is cleared.
+
+### Fixed
+
+- 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
+- Added `PI_TUI_ED3_SAFE=1` environment override to treat a terminal as non-ED3-risk for eager native scrollback rebuilds on unknown POSIX hosts
+
+### Changed
+
+- Changed native-scrollback safety defaults to treat unknown POSIX, SSH, and multiplexer-shaped terminals as ED3-risk for passive rendering; checkpoint replay now requires a positive at-tail viewport proof instead of assuming prompt submit makes host scrollback safe.
+- Changed synchronized-output defaults to a conservative opt-in profile: DEC 2026 paint wrappers stay disabled for remote/multiplexer/VTE/unknown terminals unless explicitly forced, while the autowrap guards remain active.
+
+### Fixed
+
+- Fixed ED3-risk unknown-viewport renders repainting offscreen structural edits over stale native scrollback, which could duplicate or shift rows when async blocks collapsed or middle rows were deleted.
+- Fixed ED3-risk foreground streams committing mutable live-region rows into native scrollback, which could leave a stale `pending` tool box above the `running` box after the preview re-rendered.
+- Fixed TUI shutdown leaving paint-time terminal state and Kitty image data behind by restoring synchronized-output/autowrap modes and purging all transmitted Kitty image ids on stop.
+- Fixed stdin buffering splitting surrogate-pair text into UTF-16 halves and reduced timing sensitivity for incomplete escape sequences.
+- Fixed terminal content not reflowing after a resize on terminals using DEC 2048 in-band resize (kitty/Ghostty/iTerm2/WezTerm). `ProcessTerminal.columns`/`rows` returned the last cached in-band report even after the OS already knew the new size, so a SIGWINCH whose in-band report was dropped or malformed (split past the stdin flush window, `:`-subparameter fields) re-rendered the whole transcript at the stale width. OS resize events now reconcile cached in-band geometry against the live `process.stdout` dimensions, dropping a stale cached value so the next render uses the true size; a valid in-band report still re-seeds pixel sizing.
+
+## [15.9.3] - 2026-06-05
+
+### Fixed
+
+- Fixed ED3-risk foreground streaming erasing the head of any block that alone overflows the viewport (a tall tool result drawn in one frame, or a multi-line assistant reply growing past the viewport as it streams). The live-region pin committed native scrollback only up to the sealed-prefix boundary (`liveRegionStart`), so rows of the live block that had physically scrolled above the viewport top were neither pushed into scrollback nor kept in the repainted viewport — they vanished. The commit boundary is now the viewport top: every row above the viewport enters scrollback (only the tail still visible in the viewport stays transient and deferred to the checkpoint).
+- Fixed the same ED3-risk live-region pin duplicating already-committed scrollback rows when a foreground stream's live region collapsed mid-turn (a tool preview shrinking to its compact result, an assistant block re-wrapping shorter, a late tool completion). Because growth commits every row above the viewport top to native scrollback, a subsequent shrink moved the bottom-anchored viewport back across those committed rows and the repaint re-drew them into the viewport — so they appeared twice on scroll-up, and with no prompt-submit checkpoint to reconcile (autonomous multi-turn runs, or the session ending into the welcome screen) the duplicate was baked permanently into terminal history. The pinned repaint now separates commit geometry from repaint geometry: a collapse clamps the repaint to the committed sealed boundary (`min(#scrollbackHighWater, liveRegionStart)`) instead of re-exposing those rows, leaving native scrollback un-duplicated without emitting ED3 under a possibly-scrolled reader; stale mutable live-region saved lines still reconcile at the next checkpoint.
+- Fixed hiding overlays during ED3-risk foreground streaming on unknown-viewport terminals leaving the overlay's transient rows in native scrollback. Overlay visibility reductions now bypass the streaming deferral path and rebuild once, so hidden dialog/notification sentinels are scrubbed immediately.
+- Fixed ED3-risk / unknown-viewport terminals (including WSL fronted by Windows Terminal) keeping the foreground-stream eager-rebuild mode active after the stream had already settled. A later scrolled content shrink or resize-with-append could then bypass the anti-yank deferral and repaint from stale geometry, jumping the viewport or replaying the wrong rows. The eager opt-in now drops immediately when no teardown render is pending, and the one-frame post-checkpoint suffix-suppression path no longer overrides geometry reflow handling.
+
+## [15.9.2] - 2026-06-05
+
+### Changed
+
+- Changed foreground-stream rendering on ED3-risk terminals (Ghostty/kitty/Alacritty/VTE/iTerm2 on POSIX) to defer native-scrollback commits for unpinned transient frames: while a turn streams, generic frames repaint only the viewport and suppress `\r\n` scroll growth, so transient output (spinner ticks, partial lines, status rows) never pollutes terminal history. Components that report a `NativeScrollbackLiveRegion` still commit newly sealed prefix rows while keeping the active suffix dirty for checkpoint replay. Native scrollback is reconciled in a single ED3 (`CSI 3 J`) + re-emit at the next checkpoint (prompt submit) or on an explicit user-input/IME opt-in; an erase is never emitted mid-stream under a possibly-scrolled reader. Non-ED3-risk terminals keep their eager live rebuild. ([#1895](https://github.com/can1357/oh-my-pi/pull/1895))
+
+### Fixed
+
+- Fixed ED3-risk foreground streaming dropping sealed transcript rows above the live block until the next prompt-submit checkpoint, which made scrollback beyond the viewport appear duplicated or out of order. The renderer restores native-scrollback live-region pinning so newly sealed rows are appended once while active live rows remain deferred.
+- Fixed inline images (added in 15.9) rendering as a wall of empty PUA box glyphs and producing laggy scrolling on Kitty-protocol terminals that do not implement Unicode placeholders — most notably WezTerm (per upstream wezterm/wezterm#986, placeholder support is still unchecked) and the tmux/screen `getFallbackImageProtocol` path that forces Kitty mode even on non-supporting outer terminals (Terminal.app, etc.). `unicodePlaceholders` now defaults on only for `kitty` and `ghostty`; everything else falls back to direct `a=p,i=…,p=…` placement, which those paths already render correctly. `PI_NO_KITTY_PLACEHOLDERS=1` is still honored as a hard opt-out, and a new `PI_KITTY_PLACEHOLDERS=1` opts in on otherwise-unsupported terminals (e.g. a wezterm nightly that has merged placeholder support) ([#1877](https://github.com/can1357/oh-my-pi/issues/1877)).
+
 ## [15.9.1] - 2026-06-04
+
 ### Fixed
 
 - Fixed the OSC 11 appearance poll re-querying every 2s forever on terminals that support Mode 2031 but never change theme, whose repeated OSC 11/DA1 writes cleared the user's active text selection (breaking copy every 2 seconds). The poll now stops as soon as DECRQM confirms Mode 2031 support, since push notifications make polling redundant.
@@ -1022,4 +1072,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/components/image.d.ts

@@ -64,6 +64,8 @@ export declare class ImageBudget {
     endPass(): boolean;
     /** Image ids to delete from the terminal this frame; clears the pending set. */
     takePurgeIds(): readonly number[];
+    /** All image ids believed to be loaded in the terminal store; clears tracking. */
+    takeAllTransmittedIds(): readonly number[];
     /** Whether `imageId`'s data still needs to be transmitted to the terminal. */
     shouldTransmit(imageId: number): boolean;
     /**

package/dist/types/kitty-graphics.d.ts

@@ -9,6 +9,24 @@ export interface KittyGraphicsFeatures {
     /** How image data reaches the terminal: in-band base64 or a temp file. */
     transmissionMedium: KittyTransmissionMedium;
 }
+/**
+ * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
+ * U+10EEEE with row/column diacritics).
+ *
+ * Only `kitty` (the protocol's origin) and `ghostty` ship a working
+ * implementation; WezTerm advertises Kitty graphics but treats placeholder
+ * cells as literal PUA glyphs (see wezterm/wezterm#986, "placeholder support"
+ * still unchecked), and the tmux/screen fallback can land on any outer
+ * terminal. Enabling placeholders on those paths emits a `columns × rows`
+ * grid of U+10EEEE per image per frame; the cells render as boxed fallback
+ * glyphs and re-emit on every repaint, which is exactly the
+ * "stuck/laggy scrolling + ASCII artifact" symptom reported in #1877.
+ *
+ * `PI_NO_KITTY_PLACEHOLDERS=1` forces off (e.g. for tmux passthrough to a
+ * non-supporting outer terminal); `PI_KITTY_PLACEHOLDERS=1` forces on (e.g.
+ * for a wezterm nightly that has merged placeholder support).
+ */
+export declare function detectKittyUnicodePlaceholdersSupport(terminalId: string, env?: NodeJS.ProcessEnv): boolean;
 export declare function getKittyGraphics(): Readonly<KittyGraphicsFeatures>;
 export declare function setKittyGraphics(partial: Partial<KittyGraphicsFeatures>): void;
 /**

package/dist/types/stdin-buffer.d.ts

@@ -19,8 +19,8 @@
 import { EventEmitter } from "events";
 export type StdinBufferOptions = {
     /**
-     * Maximum time to wait for sequence completion (default: 10ms)
-     * After this time, the buffer is flushed even if incomplete
+     * Maximum time to wait for sequence completion (default: 75ms).
+     * After this time, a genuinely incomplete escape is flushed.
      */
     timeout?: number;
 };

package/dist/types/terminal-capabilities.d.ts

@@ -36,28 +36,23 @@ export declare function isNotificationSuppressed(): boolean;
  */
 export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
- * Whether eager live-frame native scrollback rebuilds are unsafe when the
- * terminal viewport position is unobservable.
+ * Whether live-frame native scrollback rebuilds are unsafe when the terminal
+ * 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/VTE clamp the scroll offset back to the
- * active tail when saved lines are erased. WezTerm, macOS Terminal.app, and
- * iTerm2 expose scrollback-only clears via ED3/terminfo E3; that still
- * invalidates a reader's scrollback position during live streaming.
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). Many
+ * terminals either clamp a scrolled reader back to the active tail or erase host
+ * scrollback when ED3 lands. The important property is not the brand name — it
+ * is that an unknown viewport position cannot be proven safe. Environment
+ * markers are therefore only used to prove *risk* or a strongly-known profile;
+ * unknown POSIX/remote/multiplexer shapes default to risky for passive renders.
  *
- * Windows Terminal erases its host scrollback on ED3 and repositions the
- * viewport against the shortened buffer, so a scrolled-up reader is yanked.
- * Native win32 is excluded here because the renderer guards it with dedicated
- * platform checks (the viewport position is never observable on Windows — see
- * `Terminal.isNativeViewportAtBottom`); a `WT_SESSION` sighting on any other
- * platform means the outer host is Windows Terminal fronting a WSL distro (WT
- * propagates the variable into the Linux environment), where the same ED3
- * yank applies. See #1610.
- *
- * Pure helper for tests and `TERMINAL` trait construction. See #1682 and #1719.
+ * Native win32 is excluded here because the renderer has dedicated ConPTY
+ * deferral paths; a `WT_SESSION` sighting on POSIX means Windows Terminal is the
+ * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
  */
 export declare function detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** Whether DEC 2026 synchronized-output wrappers should be enabled by default. */
+export declare function shouldEnableSynchronizedOutputByDefault(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, terminalId?: TerminalId): boolean;
 /**
  * Whether the terminal applies Kitty-style DECCARA rectangular SGR changes
  * (`CSI Pt ; Pl ; Pb ; Pr ; <sgr> $ r`) extended to background color, so large

package/dist/types/tui.d.ts

@@ -42,6 +42,28 @@ export interface Component {
      */
     invalidate(): void;
 }
+/**
+ * Optional component seam for native-scrollback pinning. A component that
+ * renders a stable prefix followed by a live/transient suffix reports the local
+ * line index where that suffix begins after each render. TUI treats that suffix
+ * — and every root child rendered below it — as not yet safe to commit to native
+ * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ *
+ * `getNativeScrollbackCommitSafeEnd` optionally reports a *deeper* boundary
+ * inside that live suffix: the line index up to which the live region is
+ * append-only (its earlier rows never re-layout, only new rows append at the
+ * bottom — a streaming assistant message). Rows in `[liveRegionStart,
+ * commitSafeEnd)` that scroll above the viewport are safe to commit to native
+ * scrollback even though they are technically live, because they will never
+ * change. Without this, a single live block that alone overflows the viewport
+ * loses its scrolled-off head (committed nowhere, repainted nowhere). Volatile
+ * live blocks (tool previews that collapse) omit it, so their mutable rows stay
+ * deferred. Defaults to `liveRegionStart` when absent.
+ */
+export interface NativeScrollbackLiveRegion {
+    getNativeScrollbackLiveRegionStart(): number | undefined;
+    getNativeScrollbackCommitSafeEnd?(): number | undefined;
+}
 /**
  * Interface for components that can receive focus and display a cursor.
  * When focused, the component should emit CURSOR_MARKER at the cursor position
@@ -76,9 +98,8 @@ export interface RenderRequestOptions {
      */
     allowUnknownViewportMutation?: boolean;
 }
-/** Options for deferred native scrollback rebuild checkpoints. */
+/** Options for deferred native scrollback rebuild checkpoints. Reserved for API stability. */
 export interface NativeScrollbackRefreshOptions {
-    /** Allow replay when the terminal cannot report viewport state. Use only for explicit user submit checkpoints. */
     allowUnknownViewport?: boolean;
 }
 /** Type guard to check if a component implements Focusable */
@@ -173,6 +194,7 @@ export declare class TUI extends Container {
         hidden: boolean;
     }[];
     constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: TUIOptions);
+    render(width: number): string[];
     get fullRedraws(): number;
     /** Shared budget that caps how many inline images render as live graphics. */
     get imageBudget(): ImageBudget;
@@ -193,8 +215,8 @@ export declare class TUI extends Container {
     setClearOnShrink(enabled: boolean): void;
     /**
      * Whether DEC 2026 synchronized-output wrappers are currently emitted around
-     * paints. Starts from `PI_NO_SYNC_OUTPUT` and is force-disabled at runtime if
-     * the terminal reports mode 2026 unsupported via DECRQM.
+     * paints. Starts from conservative terminal/env detection and is force-disabled
+     * at runtime if the terminal reports mode 2026 unsupported via DECRQM.
      */
     get synchronizedOutput(): boolean;
     /**
@@ -212,12 +234,13 @@ export declare class TUI extends Container {
      * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint and
      * direct user-input rebuilds are unaffected.
      *
-     * Disabling does not take effect until the next frame has been classified:
-     * the event batch that ends a foreground stream both removes its UI rows
-     * (loader/status teardown — a shrink) and clears this flag before the
-     * throttled render timer fires. If the flag dropped immediately, that
-     * teardown frame would hit the ED3-risk idle deferral and freeze on screen
-     * (stale spinner) until the next keystroke.
+     * Disabling stays active through one already-requested frame: the event batch
+     * that ends a foreground stream both removes its UI rows (loader/status
+     * teardown — a shrink) and clears this flag before the throttled render timer
+     * fires. If the flag dropped immediately, that teardown frame would hit the
+     * ED3-risk idle deferral and freeze on screen (stale spinner) until the next
+     * keystroke. When no render is pending, disable immediately so a later
+     * unrelated content mutation does not inherit foreground-stream privileges.
      */
     setEagerNativeScrollbackRebuild(enabled: boolean): void;
     setFocus(component: Component | null): void;
@@ -240,6 +263,6 @@ export declare class TUI extends Container {
      * Callers should only invoke this at checkpoints where the user is expected to be
      * at the terminal bottom, such as after submitting a new prompt.
      */
-    refreshNativeScrollbackIfDirty(options?: NativeScrollbackRefreshOptions): boolean;
+    refreshNativeScrollbackIfDirty(_options?: NativeScrollbackRefreshOptions): boolean;
     requestRender(force?: boolean, options?: RenderRequestOptions): void;
 }

package/package.json

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

package/src/components/image.ts

@@ -163,6 +163,16 @@ export class ImageBudget {
 		return ids;
 	}
 
+	/** All image ids believed to be loaded in the terminal store; clears tracking. */
+	takeAllTransmittedIds(): readonly number[] {
+		if (this.#transmitted.size === 0) return EMPTY_IDS;
+		const ids = [...this.#transmitted];
+		this.#transmitted.clear();
+		this.#purgeIds = [];
+		this.#pendingTransmits = [];
+		return ids;
+	}
+
 	/** Whether `imageId`'s data still needs to be transmitted to the terminal. */
 	shouldTransmit(imageId: number): boolean {
 		return !this.#transmitted.has(imageId);

package/src/kitty-graphics.ts

@@ -17,7 +17,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { $env, $flag, logger } from "@oh-my-pi/pi-utils";
+import { $env, logger } from "@oh-my-pi/pi-utils";
 
 /** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
 export const KITTY_PLACEHOLDER = "\u{10eeee}";
@@ -76,8 +76,36 @@ function transmissionOverride(): KittyTransmissionMedium | "auto" {
 	return "auto";
 }
 
+/**
+ * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
+ * U+10EEEE with row/column diacritics).
+ *
+ * Only `kitty` (the protocol's origin) and `ghostty` ship a working
+ * implementation; WezTerm advertises Kitty graphics but treats placeholder
+ * cells as literal PUA glyphs (see wezterm/wezterm#986, "placeholder support"
+ * still unchecked), and the tmux/screen fallback can land on any outer
+ * terminal. Enabling placeholders on those paths emits a `columns × rows`
+ * grid of U+10EEEE per image per frame; the cells render as boxed fallback
+ * glyphs and re-emit on every repaint, which is exactly the
+ * "stuck/laggy scrolling + ASCII artifact" symptom reported in #1877.
+ *
+ * `PI_NO_KITTY_PLACEHOLDERS=1` forces off (e.g. for tmux passthrough to a
+ * non-supporting outer terminal); `PI_KITTY_PLACEHOLDERS=1` forces on (e.g.
+ * for a wezterm nightly that has merged placeholder support).
+ */
+export function detectKittyUnicodePlaceholdersSupport(terminalId: string, env: NodeJS.ProcessEnv = Bun.env): boolean {
+	const offRaw = env.PI_NO_KITTY_PLACEHOLDERS?.trim().toLowerCase();
+	if (offRaw === "1" || offRaw === "true" || offRaw === "on" || offRaw === "yes" || offRaw === "y") return false;
+	const force = env.PI_KITTY_PLACEHOLDERS?.trim().toLowerCase();
+	if (force === "1" || force === "true" || force === "on" || force === "yes" || force === "y") return true;
+	if (force === "0" || force === "false" || force === "off" || force === "no" || force === "n") return false;
+	return terminalId === "kitty" || terminalId === "ghostty";
+}
+
 let features: KittyGraphicsFeatures = {
-	unicodePlaceholders: !$flag("PI_NO_KITTY_PLACEHOLDERS"),
+	// Off until `terminal-capabilities` seeds it from the detected terminal id —
+	// the default-on path corrupts wezterm and tmux-passthrough sessions.
+	unicodePlaceholders: false,
 	// Start direct; a successful probe (or explicit `temp-file` override) promotes.
 	transmissionMedium: transmissionOverride() === "temp-file" ? "temp-file" : "direct",
 };

package/src/stdin-buffer.ts

@@ -233,9 +233,10 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 				return { sequences, remainder: remaining };
 			}
 		} else {
-			// Not an escape sequence - take a single character
-			sequences.push(remaining[0]!);
-			pos++;
+			// Not an escape sequence - take one Unicode scalar, not a UTF-16 code unit.
+			const char = Array.from(remaining)[0] ?? "";
+			sequences.push(char);
+			pos += char.length;
 		}
 	}
 
@@ -244,8 +245,8 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 
 export type StdinBufferOptions = {
 	/**
-	 * Maximum time to wait for sequence completion (default: 10ms)
-	 * After this time, the buffer is flushed even if incomplete
+	 * Maximum time to wait for sequence completion (default: 75ms).
+	 * After this time, a genuinely incomplete escape is flushed.
 	 */
 	timeout?: number;
 };
@@ -269,7 +270,7 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 
 	constructor(options: StdinBufferOptions = {}) {
 		super();
-		this.#timeoutMs = options.timeout ?? 10;
+		this.#timeoutMs = options.timeout ?? 75;
 	}
 
 	process(data: string | Buffer): void {

package/src/terminal-capabilities.ts

@@ -1,12 +1,14 @@
 import { encodeSixel } from "@oh-my-pi/pi-natives";
 import { $env, isBunTestRuntime } from "@oh-my-pi/pi-utils";
 import {
+	detectKittyUnicodePlaceholdersSupport,
 	encodeKittyTempFileTransmit,
 	getKittyGraphics,
 	isPngBase64,
 	KITTY_PLACEHOLDER,
 	kittyPlaceholdersFit,
 	renderKittyPlaceholderLines,
+	setKittyGraphics,
 } from "./kitty-graphics";
 
 export enum ImageProtocol {
@@ -116,33 +118,44 @@ export function isWindowsTerminalPreviewSixelSupported(
 }
 
 /**
- * Whether eager live-frame native scrollback rebuilds are unsafe when the
- * terminal viewport position is unobservable.
+ * Whether live-frame native scrollback rebuilds are unsafe when the terminal
+ * 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/VTE clamp the scroll offset back to the
- * active tail when saved lines are erased. WezTerm, macOS Terminal.app, and
- * iTerm2 expose scrollback-only clears via ED3/terminfo E3; that still
- * invalidates a reader's scrollback position during live streaming.
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). Many
+ * terminals either clamp a scrolled reader back to the active tail or erase host
+ * scrollback when ED3 lands. The important property is not the brand name — it
+ * is that an unknown viewport position cannot be proven safe. Environment
+ * markers are therefore only used to prove *risk* or a strongly-known profile;
+ * unknown POSIX/remote/multiplexer shapes default to risky for passive renders.
  *
- * Windows Terminal erases its host scrollback on ED3 and repositions the
- * viewport against the shortened buffer, so a scrolled-up reader is yanked.
- * Native win32 is excluded here because the renderer guards it with dedicated
- * platform checks (the viewport position is never observable on Windows — see
- * `Terminal.isNativeViewportAtBottom`); a `WT_SESSION` sighting on any other
- * platform means the outer host is Windows Terminal fronting a WSL distro (WT
- * propagates the variable into the Linux environment), where the same ED3
- * yank applies. See #1610.
- *
- * Pure helper for tests and `TERMINAL` trait construction. See #1682 and #1719.
+ * Native win32 is excluded here because the renderer has dedicated ConPTY
+ * deferral paths; a `WT_SESSION` sighting on POSIX means Windows Terminal is the
+ * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
  */
 export function detectTerminalEagerEraseScrollbackRisk(
 	env: NodeJS.ProcessEnv = Bun.env,
 	platform: NodeJS.Platform = process.platform,
 ): boolean {
 	if (platform === "win32") return false;
+
+	const term = env.TERM?.toLowerCase() ?? "";
+	const termProgram = env.TERM_PROGRAM?.toLowerCase() ?? "";
+	const colorTerm = env.COLORTERM?.toLowerCase() ?? "";
+
+	if (env.PI_TUI_ED3_SAFE === "1") return false;
 	if (env.WT_SESSION) return true;
+	if (
+		env.SSH_CONNECTION ||
+		env.SSH_CLIENT ||
+		env.SSH_TTY ||
+		env.TMUX ||
+		env.STY ||
+		env.ZELLIJ ||
+		term.startsWith("tmux") ||
+		term.startsWith("screen")
+	) {
+		return true;
+	}
 	if (
 		env.WEZTERM_PANE ||
 		env.KITTY_WINDOW_ID ||
@@ -153,17 +166,62 @@ export function detectTerminalEagerEraseScrollbackRisk(
 	) {
 		return true;
 	}
-	switch (env.TERM_PROGRAM?.toLowerCase()) {
+	switch (termProgram) {
 		case "alacritty":
 		case "apple_terminal":
 		case "ghostty":
+		case "gnome-terminal":
 		case "iterm.app":
+		case "kgx":
 		case "kitty":
+		case "ptyxis":
 		case "wezterm":
+		case "xfce4-terminal":
 			return true;
 		default:
+			break;
+	}
+	if (platform === "linux" && (colorTerm === "truecolor" || colorTerm === "24bit")) return true;
+	// Unknown POSIX terminals have no scroll-position oracle. Treat them as risky
+	// for passive ED3 until a positive terminal-specific integration proves safe.
+	return true;
+}
+
+/** Whether DEC 2026 synchronized-output wrappers should be enabled by default. */
+export function shouldEnableSynchronizedOutputByDefault(
+	env: NodeJS.ProcessEnv = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+	terminalId: TerminalId = TERMINAL_ID,
+): boolean {
+	if (env.PI_NO_SYNC_OUTPUT || env.PI_TUI_SYNC_OUTPUT === "0") return false;
+	if (env.PI_FORCE_SYNC_OUTPUT === "1" || env.PI_TUI_SYNC_OUTPUT === "1") return true;
+	if (platform === "win32") return false;
+
+	const term = env.TERM?.toLowerCase() ?? "";
+	const termProgram = env.TERM_PROGRAM?.toLowerCase() ?? "";
+	if (
+		env.SSH_CONNECTION ||
+		env.SSH_CLIENT ||
+		env.SSH_TTY ||
+		env.TMUX ||
+		env.STY ||
+		env.ZELLIJ ||
+		term.startsWith("tmux") ||
+		term.startsWith("screen")
+	) {
+		return false;
+	}
+	if (env.VTE_VERSION) return false;
+	switch (termProgram) {
+		case "gnome-terminal":
+		case "kgx":
+		case "ptyxis":
+		case "xfce4-terminal":
 			return false;
+		default:
+			break;
 	}
+	return terminalId === "kitty" || terminalId === "ghostty" || terminalId === "wezterm" || terminalId === "iterm2";
 }
 
 /**
@@ -321,6 +379,12 @@ export const TERMINAL = (() => {
 	return resolved;
 })();
 
+// Seed Kitty Unicode placeholder support from the resolved terminal id. Only
+// kitty/ghostty are known to honor `U=1` placement; other Kitty-protocol paths
+// (wezterm, tmux/screen fallback) treat the placeholder cells as literal PUA
+// glyphs, which is the "ASCII artifact + laggy scrolling" reported in #1877.
+setKittyGraphics({ unicodePlaceholders: detectKittyUnicodePlaceholdersSupport(TERMINAL.id, Bun.env) });
+
 type MutableTerminalInfo = {
 	imageProtocol: ImageProtocol | null;
 	deccara: boolean;

package/src/terminal.ts

@@ -35,7 +35,9 @@ export function emergencyTerminalRestore(): void {
 			// Blind restore only if we know a terminal was started but lost track of it
 			// This avoids writing escape sequences for non-TUI commands (grep, commit, etc.)
 			process.stdout.write(
-				"\x1b[?2004l" + // Disable bracketed paste
+				"\x1b[?2026l" + // End synchronized output
+					"\x1b[?7h" + // Restore autowrap
+					"\x1b[?2004l" + // Disable bracketed paste
 					"\x1b[?2031l" + // Disable Mode 2031 appearance notifications
 					"\x1b[?2048l" + // Disable in-band resize notifications
 					"\x1b[<u" + // Pop kitty keyboard protocol
@@ -173,6 +175,7 @@ export class ProcessTerminal implements Terminal {
 	#wasRaw = false;
 	#inputHandler?: (data: string) => void;
 	#resizeHandler?: () => void;
+	#stdoutResizeListener?: () => void;
 	#kittyProtocolActive = false;
 	#modifyOtherKeysActive = false;
 	#modifyOtherKeysTimeout?: Timer;
@@ -239,8 +242,14 @@ export class ProcessTerminal implements Terminal {
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
 		this.#safeWrite("\x1b[?2004h");
 
-		// Set up resize handler immediately
-		process.stdout.on("resize", this.#resizeHandler);
+		// Set up resize handler immediately. The OS refreshes process.stdout
+		// dimensions before firing `resize`, so it is authoritative for geometry:
+		// reconcile any stale cached DEC 2048 report before notifying the renderer.
+		this.#stdoutResizeListener = () => {
+			this.#reconcileInBandGeometryOnResize();
+			this.#resizeHandler?.();
+		};
+		process.stdout.on("resize", this.#stdoutResizeListener);
 
 		// Refresh terminal dimensions - they may be stale after suspend/resume
 		// (SIGWINCH is lost while process is stopped). Unix only.
@@ -845,6 +854,31 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
+	/**
+	 * Reconcile cached in-band geometry with the OS on an OS-level resize.
+	 *
+	 * SIGWINCH (POSIX) and ConPTY (Windows) refresh `process.stdout.columns`/
+	 * `rows` before the `resize` event fires, so they are authoritative for the
+	 * new cell geometry. A cached DEC 2048 report can be stale: the matching
+	 * post-resize report may be dropped (split across stdin reads past the flush
+	 * window) or carry `:`-subparameters the parser skips, leaving the getters
+	 * pinned to the old size — which freezes the rendered width because the
+	 * renderer reflows against {@link columns}/{@link rows}, not the live OS
+	 * value. Drop a cached dimension that disagrees with the live OS value; the
+	 * terminal's next valid in-band report re-seeds pixel sizing.
+	 */
+	#reconcileInBandGeometryOnResize(): void {
+		if (!this.#inBandResizeActive) return;
+		const osColumns = process.stdout.columns;
+		const osRows = process.stdout.rows;
+		if (this.#reportedColumns !== undefined && osColumns > 0 && this.#reportedColumns !== osColumns) {
+			this.#reportedColumns = undefined;
+		}
+		if (this.#reportedRows !== undefined && osRows > 0 && this.#reportedRows !== osRows) {
+			this.#reportedRows = undefined;
+		}
+	}
+
 	async drainInput(maxMs = 1000, idleMs = 50): Promise<void> {
 		if (this.#kittyProtocolActive) {
 			// Disable Kitty keyboard protocol first so any late key releases
@@ -897,6 +931,10 @@ export class ProcessTerminal implements Terminal {
 			this.#safeWrite(TERMINAL_PROGRESS_CLEAR_SEQUENCE);
 		}
 
+		// Leave paint-time terminal modes even if the process exits between the
+		// begin/end halves of a frame. Safe no-ops on terminals that ignored them.
+		this.#safeWrite("\x1b[?2026l\x1b[?7h");
+
 		// Disable bracketed paste mode
 		this.#safeWrite("\x1b[?2004l");
 
@@ -958,10 +996,11 @@ export class ProcessTerminal implements Terminal {
 		}
 		this.#inputHandler = undefined;
 		this.#appearance = undefined;
-		if (this.#resizeHandler) {
-			process.stdout.removeListener("resize", this.#resizeHandler);
-			this.#resizeHandler = undefined;
+		if (this.#stdoutResizeListener) {
+			process.stdout.removeListener("resize", this.#stdoutResizeListener);
+			this.#stdoutResizeListener = undefined;
 		}
+		this.#resizeHandler = undefined;
 
 		// Pause stdin to prevent any buffered input (e.g., Ctrl+D) from being
 		// re-interpreted after raw mode is disabled. This fixes a race condition