@gajae-code/tui 0.12.11 → 0.12.12

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.12.12] - 2026-08-05
+### Fixed
+
+- Restored 60 fps time-dependent loader gradients on direct local terminals while retaining the 80 ms cadence and congestion dropping on SSH and multiplexed terminals.
+- Bounded loader animation scheduling to 80 ms, stopped OSC 11 polling after DA1 proves the query unsupported while preserving Mode 2031 recovery, and added the default-on `GJC_TUI_SYNCHRONIZED_OUTPUT=0` compatibility opt-out for terminal parsers that mishandle synchronized-output framing. Real iOS-client validation remains pending for #3798.
+- Decorative animation ticks now pause while stdout has more than 64 KiB buffered, preventing slow SSH terminals and multiplexers from accumulating stale spinner frames.
+
 ## [0.12.11] - 2026-08-03
 
 ## [0.12.10] - 2026-08-03
@@ -22,6 +29,7 @@
 - Restored the `isProcessTerminal`/`shouldUseViewportRepaintForHost` gate on the width-change viewport-repaint intercept so plain terminals (non-multiplexer, non-process-terminal) use `fullRender` for width changes instead of an unconditional viewport repaint. The #3684 chain removed this gate, causing lossless Korean/CJK prose wrapping to break at narrow widths because the viewport repaint only painted the visible rows without committing the full transcript to scrollback (#1979).
 - Restored the `fullRender` fallback for the `firstChanged < viewportTop` branch on non-viewport-repaint hosts, so above-viewport mutations replay the full frame instead of silently viewport-repainting.
 - Propagated IME cursor write failure from `#writeRenderBufferAndReanchorImeCursor` so callers detect terminal detach when the deferred cursor write fails after the shared frame commits.
+- The win32 viewport-repaint fallback no longer outranks a terminal that reports `isProcessTerminal: false`. Platform identity exists to recognize Windows console hosts that cannot report the capability, so a terminal that has answered now decides; previously every non-process terminal on Windows (embedders, pipes, the render regression suite) inherited viewport-repaint semantics, suppressed durable history replay, and left contracted rows behind as duplicates.
 
 ## [0.12.7] - 2026-07-31
 

package/dist/types/animation-scheduler.d.ts

@@ -8,6 +8,9 @@ export declare const __animationSchedulerTestHooks: {
     getActiveTimerCount(cadence?: AnimationCadence): number;
     getRegistrantCount(cadence?: AnimationCadence): number;
     getStartedTimerCount(cadence?: AnimationCadence): number;
+    getSkippedTickCount(): number;
+    getCongestionThresholdBytes(): number;
+    setBufferedOutputBytesProbe(probe: (() => number | undefined) | undefined): void;
     reset(): void;
 };
 export {};

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

@@ -1,5 +1,14 @@
 import type { TUI } from "../tui";
 import { Text } from "./text";
+/**
+ * Compatibility options for existing loader call sites.
+ *
+ * @deprecated `timeDependentColor` preserves the historical smooth-animation
+ * contract: direct local terminals reevaluate colorizers at 60 fps, while
+ * remote or multiplexed terminals stay on the shared 80 ms cadence to avoid
+ * output churn. The field remains accepted for downstream callers while they
+ * migrate to an explicit animation policy.
+ */
 export interface LoaderOptions {
     timeDependentColor?: boolean;
 }
@@ -7,6 +16,8 @@ export interface LoaderOptions {
 export declare const __loaderPerfCounters: {
     liveIntervals: number;
     startedIntervals: number;
+    callbackInvocations: number;
+    renderRequests: number;
     reset(): void;
 };
 export declare class Loader extends Text {
@@ -14,6 +25,7 @@ export declare class Loader extends Text {
     private spinnerColorFn;
     private messageColorFn;
     private message;
+    private options;
     constructor(ui: TUI, spinnerColorFn: (str: string) => string, messageColorFn: (str: string) => string, message?: string, spinnerFrames?: string[], options?: LoaderOptions);
     render(width: number): string[];
     start(): void;

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

@@ -22,6 +22,8 @@ export declare class TerminalInfo {
     sendNotification(message: string): void;
 }
 export declare function isNotificationSuppressed(): boolean;
+/** Returns whether stdout crosses an SSH transport, where animation bytes can outpace the link. */
+export declare function isRemoteTerminalSession(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Returns whether the process runs under a terminal multiplexer (tmux, GNU
  * screen, or zellij). Recognizes the same host markers as the renderer's

package/dist/types/tui.d.ts

@@ -179,6 +179,18 @@ export declare function shouldUseViewportRepaintForHost(env?: Record<string, str
     includeNativeWindows?: boolean;
     includeProcessTerminal?: boolean;
 }): boolean;
+/**
+ * Viewport-repaint host gate resolved against a terminal's reported capability.
+ *
+ * `includeNativeWindows` exists so a Windows console host that cannot report
+ * `isProcessTerminal` is still recognized from platform identity. It is a
+ * fallback, so it must not outrank a terminal that has answered: a terminal
+ * reporting `false` is not a native console host, and letting win32 override it
+ * gives every non-process terminal on Windows — embedders, pipes, and the
+ * render regression suite — viewport-repaint semantics. Those hosts then never
+ * replay durable history, so contracted rows survive as duplicates.
+ */
+export declare function shouldUseViewportRepaintForTerminal(isProcessTerminal: boolean | undefined, env?: Record<string, string | undefined>, platform?: NodeJS.Platform): boolean;
 /**
  * Options for overlay positioning and sizing.
  * Values can be absolute numbers or percentage strings (e.g., "50%").

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.12.11",
+	"version": "0.12.12",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.12.11",
-		"@gajae-code/utils": "0.12.11",
+		"@gajae-code/natives": "0.12.12",
+		"@gajae-code/utils": "0.12.12",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/animation-scheduler.ts

@@ -9,6 +9,28 @@ interface CadenceBucket {
 	startedTimers: number;
 }
 
+// Animation ticks are decorative. When the output sink cannot keep up — a
+// remote terminal over SSH, a multiplexer, a slow pipe — those frames are not
+// merely wasted, they queue. Bun buffers whatever `write()` could not hand to
+// the OS, so the renderer runs ahead of the wire and the user watches a backlog
+// drain instead of the current frame.
+//
+// Dropping a decorative tick loses nothing: the next one redraws from live state.
+// Skipping is therefore always safe here, and must never be extended to renders
+// that carry content, which the diff renderer must still emit in order.
+const DEFAULT_CONGESTION_THRESHOLD_BYTES = 64 * 1024;
+
+let bufferedOutputBytesProbe: (() => number | undefined) | undefined;
+let skippedTicks = 0;
+
+function outputIsCongested(): boolean {
+	const stdout = globalThis.process?.stdout as { writableLength?: number } | undefined;
+	const buffered = bufferedOutputBytesProbe ? bufferedOutputBytesProbe() : stdout?.writableLength;
+	// A healthy TTY drains synchronously and reports 0 here, so this is a no-op
+	// locally and only engages once bytes are genuinely stuck.
+	return typeof buffered === "number" && buffered > DEFAULT_CONGESTION_THRESHOLD_BYTES;
+}
+
 const buckets = new Map<AnimationCadence, CadenceBucket>();
 
 function getBucket(cadence: AnimationCadence): CadenceBucket {
@@ -23,6 +45,12 @@ function getBucket(cadence: AnimationCadence): CadenceBucket {
 function startBucket(cadence: AnimationCadence, bucket: CadenceBucket): void {
 	if (bucket.timer) return;
 	bucket.timer = setInterval(() => {
+		// Skip the whole tick, not each callback: the decision is about the shared
+		// output sink, so sampling it once keeps every registrant on the same frame.
+		if (outputIsCongested()) {
+			skippedTicks += 1;
+			return;
+		}
 		const now = performance.now();
 		// Snapshot so re-entrant register/unregister during a tick is safe, and
 		// isolate each callback so one throwing registrant cannot starve siblings
@@ -89,11 +117,22 @@ export const __animationSchedulerTestHooks = {
 		for (const bucket of buckets.values()) count += bucket.startedTimers;
 		return count;
 	},
+	getSkippedTickCount(): number {
+		return skippedTicks;
+	},
+	getCongestionThresholdBytes(): number {
+		return DEFAULT_CONGESTION_THRESHOLD_BYTES;
+	},
+	setBufferedOutputBytesProbe(probe: (() => number | undefined) | undefined): void {
+		bufferedOutputBytesProbe = probe;
+	},
 	reset(): void {
 		for (const bucket of buckets.values()) {
 			stopBucket(bucket);
 			bucket.callbacks.clear();
 			bucket.startedTimers = 0;
 		}
+		skippedTicks = 0;
+		bufferedOutputBytesProbe = undefined;
 	},
 };

package/src/components/loader.ts

@@ -1,21 +1,42 @@
 import { type AnimationRegistration, registerAnimationCallback } from "../animation-scheduler";
+import { isRemoteTerminalSession, isUnderTerminalMultiplexer } from "../terminal-capabilities";
 import type { TUI } from "../tui";
 import { sliceByColumn, visibleWidth } from "../utils";
 import { Text } from "./text";
 
 const SPINNER_ADVANCE_MS = 80;
 
+/**
+ * Compatibility options for existing loader call sites.
+ *
+ * @deprecated `timeDependentColor` preserves the historical smooth-animation
+ * contract: direct local terminals reevaluate colorizers at 60 fps, while
+ * remote or multiplexed terminals stay on the shared 80 ms cadence to avoid
+ * output churn. The field remains accepted for downstream callers while they
+ * migrate to an explicit animation policy.
+ */
 export interface LoaderOptions {
 	timeDependentColor?: boolean;
 }
 
+const SMOOTH_ANIMATION_MS = 16;
+
+function resolveAnimationCadence(options: LoaderOptions): 16 | 80 {
+	if (options.timeDependentColor !== true) return SPINNER_ADVANCE_MS;
+	return isRemoteTerminalSession() || isUnderTerminalMultiplexer() ? SPINNER_ADVANCE_MS : SMOOTH_ANIMATION_MS;
+}
+
 /** Test-only performance counters for advisory baseline tests. */
 export const __loaderPerfCounters = {
 	liveIntervals: 0,
 	startedIntervals: 0,
+	callbackInvocations: 0,
+	renderRequests: 0,
 	reset(): void {
 		this.liveIntervals = 0;
 		this.startedIntervals = 0;
+		this.callbackInvocations = 0;
+		this.renderRequests = 0;
 	},
 };
 
@@ -26,7 +47,6 @@ export class Loader extends Text {
 	#ui: TUI | null = null;
 	#lastSpinnerTick = 0;
 	#lastDisplayed?: string;
-	#timeDependentColor: boolean;
 
 	constructor(
 		ui: TUI,
@@ -34,11 +54,10 @@ export class Loader extends Text {
 		private messageColorFn: (str: string) => string,
 		private message: string = "Loading...",
 		spinnerFrames?: string[],
-		options: LoaderOptions = {},
+		private options: LoaderOptions = {},
 	) {
 		super("", 1, 0);
 		this.#ui = ui;
-		this.#timeDependentColor = options.timeDependentColor ?? false;
 		if (spinnerFrames && spinnerFrames.length > 0) {
 			this.#frames = spinnerFrames;
 		}
@@ -62,16 +81,14 @@ export class Loader extends Text {
 		this.#updateDisplay();
 		__loaderPerfCounters.liveIntervals += 1;
 		__loaderPerfCounters.startedIntervals += 1;
-		this.#animation = registerAnimationCallback(
-			now => {
-				if (now - this.#lastSpinnerTick >= SPINNER_ADVANCE_MS) {
-					this.#currentFrame = (this.#currentFrame + 1) % this.#frames.length;
-					this.#lastSpinnerTick = now;
-				}
-				this.#updateDisplay();
-			},
-			this.#timeDependentColor ? 16 : 80,
-		);
+		this.#animation = registerAnimationCallback(now => {
+			__loaderPerfCounters.callbackInvocations += 1;
+			if (now - this.#lastSpinnerTick >= SPINNER_ADVANCE_MS) {
+				this.#currentFrame = (this.#currentFrame + 1) % this.#frames.length;
+				this.#lastSpinnerTick = now;
+			}
+			this.#updateDisplay();
+		}, resolveAnimationCadence(this.options));
 	}
 
 	stop() {
@@ -97,6 +114,7 @@ export class Loader extends Text {
 		if (next === this.#lastDisplayed) return;
 		this.#lastDisplayed = next;
 		this.setText(next);
+		__loaderPerfCounters.renderRequests += 1;
 		this.#ui?.requestRender(false, "loader");
 	}
 }

package/src/components/settings-list.ts

@@ -1,6 +1,7 @@
 import { getKeybindings } from "../keybindings";
+import { extractPrintableText, matchesKey } from "../keys";
 import type { Component } from "../tui";
-import { Ellipsis, padding, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
+import { Ellipsis, getSegmenter, padding, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
 
 export interface SettingItem {
 	/** Unique identifier for this setting */
@@ -26,7 +27,9 @@ export interface SettingsListTheme {
 }
 
 export class SettingsList implements Component {
+	#allItems: SettingItem[];
 	#items: SettingItem[];
+	#searchQuery = "";
 	#theme: SettingsListTheme;
 	#selectedIndex = 0;
 	#maxVisible: number;
@@ -48,6 +51,7 @@ export class SettingsList implements Component {
 		onSelectionChange?: (item: SettingItem | undefined) => void,
 		descriptionRows = 0,
 	) {
+		this.#allItems = items;
 		this.#items = items;
 		this.#maxVisible = maxVisible;
 		this.#theme = theme;
@@ -68,7 +72,7 @@ export class SettingsList implements Component {
 
 	/** Update an item's currentValue */
 	updateValue(id: string, newValue: string): void {
-		const item = this.#items.find(i => i.id === id);
+		const item = this.#allItems.find(i => i.id === id);
 		if (item) {
 			item.currentValue = newValue;
 		}
@@ -82,11 +86,24 @@ export class SettingsList implements Component {
 	 * restored index against the new list on the way out.
 	 */
 	setItems(items: SettingItem[]): void {
-		this.#items = items;
+		this.#allItems = items;
+		this.#items = this.#filterItems();
 		this.#clampSelectedIndex();
 		this.#notifySelectionChange();
 	}
 
+	#filterItems(): SettingItem[] {
+		const query = this.#searchQuery.toLocaleLowerCase();
+		return query ? this.#allItems.filter(item => item.label.toLocaleLowerCase().includes(query)) : this.#allItems;
+	}
+
+	#setSearchQuery(query: string): void {
+		this.#searchQuery = query.normalize("NFC");
+		this.#items = this.#filterItems();
+		this.#selectedIndex = 0;
+		this.#notifySelectionChange();
+	}
+
 	invalidate(): void {
 		this.#submenuComponent?.invalidate?.();
 	}
@@ -106,9 +123,17 @@ export class SettingsList implements Component {
 
 	#renderMainList(width: number): string[] {
 		const lines: string[] = [];
+		if (this.#searchQuery) {
+			lines.push(this.#theme.hint(truncateToWidth(`  Search: ${this.#searchQuery}`, width)));
+			lines.push("");
+		}
 
 		if (this.#items.length === 0) {
-			lines.push(this.#theme.hint("  No settings available"));
+			lines.push(this.#theme.hint(this.#searchQuery ? "  No matching settings" : "  No settings available"));
+			if (this.#searchQuery) {
+				lines.push("");
+				lines.push(this.#theme.hint(truncateToWidth("  Type to search · Backspace to edit · Esc to clear", width)));
+			}
 			return lines;
 		}
 
@@ -181,7 +206,10 @@ export class SettingsList implements Component {
 
 		// Add hint
 		lines.push("");
-		lines.push(truncateToWidth(this.#theme.hint("  Enter/Space to change · Esc to cancel"), width));
+		const hint = this.#searchQuery
+			? "  Type to search · Enter to change · Backspace to edit · Esc to clear"
+			: "  Type to search · Enter/Space to change · Esc to cancel";
+		lines.push(truncateToWidth(this.#theme.hint(hint), width));
 
 		return lines;
 	}
@@ -196,24 +224,44 @@ export class SettingsList implements Component {
 
 		// Main list input handling
 		const kb = getKeybindings();
-		if (this.#items.length === 0) {
-			if (kb.matches(data, "tui.select.cancel")) {
-				this.#onCancel();
-			}
-			return;
-		}
-
-		if (kb.matches(data, "tui.select.up")) {
+		if (this.#items.length > 0 && kb.matches(data, "tui.select.up")) {
 			this.#selectedIndex = this.#selectedIndex === 0 ? this.#items.length - 1 : this.#selectedIndex - 1;
 			this.#notifySelectionChange();
-		} else if (kb.matches(data, "tui.select.down")) {
+			return;
+		}
+		if (this.#items.length > 0 && kb.matches(data, "tui.select.down")) {
 			this.#selectedIndex = this.#selectedIndex === this.#items.length - 1 ? 0 : this.#selectedIndex + 1;
 			this.#notifySelectionChange();
-		} else if (kb.matches(data, "tui.select.confirm") || data === " " || data === "\n") {
+			return;
+		}
+		if (
+			this.#items.length > 0 &&
+			(kb.matches(data, "tui.select.confirm") || data === "\n" || (data === " " && !this.#searchQuery))
+		) {
 			this.#activateItem();
-		} else if (kb.matches(data, "tui.select.cancel")) {
-			this.#onCancel();
+			return;
+		}
+		if (kb.matches(data, "tui.select.cancel")) {
+			if (this.#searchQuery) {
+				this.#setSearchQuery("");
+			} else {
+				this.#onCancel();
+			}
+			return;
 		}
+		if (this.#searchQuery && matchesKey(data, "backspace")) {
+			const graphemes = [...getSegmenter().segment(this.#searchQuery)];
+			this.#setSearchQuery(
+				graphemes
+					.slice(0, -1)
+					.map(part => part.segment)
+					.join(""),
+			);
+			return;
+		}
+
+		const printableText = extractPrintableText(data);
+		if (printableText) this.#setSearchQuery(this.#searchQuery + printableText);
 	}
 
 	#activateItem(): void {

package/src/terminal-capabilities.ts

@@ -60,6 +60,11 @@ function multiplexerEnvEnabled(value: string | undefined): boolean {
 	return normalized !== undefined && normalized.length > 0 && !MULTIPLEXER_DISABLED_ENV_VALUES.has(normalized);
 }
 
+/** Returns whether stdout crosses an SSH transport, where animation bytes can outpace the link. */
+export function isRemoteTerminalSession(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	return Boolean(env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY);
+}
+
 /**
  * Returns whether the process runs under a terminal multiplexer (tmux, GNU
  * screen, or zellij). Recognizes the same host markers as the renderer's

package/src/terminal.ts

@@ -263,6 +263,8 @@ function unsubscribeFromStdinErrors(subscriber: (err: Error) => void): void {
 	stdinErrorSubscribers.delete(subscriber);
 	if (stdinErrorSubscribers.size === 0) process.stdin.removeListener("error", dispatchStdinError);
 }
+type Osc11QuerySource = "startup" | "poll" | "mode2031";
+type Osc11QueuedSource = Exclude<Osc11QuerySource, "startup">;
 
 /**
  * Real terminal using process.stdin/stdout
@@ -287,7 +289,7 @@ export class ProcessTerminal implements Terminal {
 	#appearanceCallbacks: Array<(appearance: TerminalAppearance) => void> = [];
 	#appearance: TerminalAppearance | undefined;
 	#osc11Pending = false;
-	#osc11QueryQueued = false;
+	#osc11QueuedSource?: Osc11QueuedSource;
 	#osc11ResponseBuffer = "";
 	#privateCsiResponseBuffer = "";
 	#pendingDa1Sentinels = 0;
@@ -409,7 +411,7 @@ export class ProcessTerminal implements Terminal {
 		// sequences in order, so if DA1 arrives before OSC 11 response,
 		// the terminal does not support OSC 11. This avoids indefinite hangs.
 		// Technique used by Neovim, bat, fish, and terminal-colorsaurus.
-		this.#queryBackgroundColor();
+		this.#queryBackgroundColor("startup");
 
 		// Subscribe to Mode 2031 appearance change notifications.
 		// When the terminal reports a change, we re-query OSC 11 to get the
@@ -571,16 +573,22 @@ export class ProcessTerminal implements Terminal {
 			// already succeeded. Other terminal probes should never see these replies.
 			if (da1ResponsePattern.test(sequence) && this.#pendingDa1Sentinels > 0) {
 				this.#pendingDa1Sentinels--;
-				if (this.#osc11Pending) {
-					// DA1 arrived before OSC 11 response: terminal does not support
-					// OSC 11. Clear the pending state without starting a queued query
-					// (queued query is started below, after sentinel is consumed).
+				const negativeEvidence = this.#osc11Pending;
+				const queuedSource = this.#osc11QueuedSource;
+				this.#osc11QueuedSource = undefined;
+				if (negativeEvidence) {
+					// DA1 arrived before OSC 11: this cycle proved OSC 11 unsupported.
+					// Stop futile polling, but retain one stronger Mode 2031 push request.
 					this.#osc11Pending = false;
 					this.#osc11ResponseBuffer = "";
-				}
-				// Now that this DA1 cycle is complete, start any queued query.
-				if (this.#osc11QueryQueued && !this.#dead) {
-					this.#osc11QueryQueued = false;
+					this.#clearOsc11QueryWatchdog();
+					this.#stopOsc11Poll();
+					if (queuedSource === "mode2031" && !this.#dead) {
+						this.#startOsc11Query();
+					}
+				} else if (queuedSource && !this.#dead) {
+					// A positive OSC reply arrived first. The delayed sentinel only
+					// closes that successful cycle, so preserve its single follow-up.
 					this.#startOsc11Query();
 				}
 				return;
@@ -600,8 +608,9 @@ export class ProcessTerminal implements Terminal {
 					const osc11Match = this.#osc11ResponseBuffer.match(osc11ResponsePattern);
 					if (osc11Match) {
 						const [, rHex, gHex, bHex] = osc11Match;
-						this.#osc11Pending = false;
 						this.#osc11ResponseBuffer = "";
+						if (!this.#osc11Pending) return;
+						this.#osc11Pending = false;
 						this.#clearOsc11QueryWatchdog();
 						this.#handleOsc11Response(rHex!, gHex!, bHex!);
 						return;
@@ -628,7 +637,7 @@ export class ProcessTerminal implements Terminal {
 				if (this.#mode2031DebounceTimer) clearTimeout(this.#mode2031DebounceTimer);
 				this.#mode2031DebounceTimer = setTimeout(() => {
 					this.#mode2031DebounceTimer = undefined;
-					this.#queryBackgroundColor();
+					this.#queryBackgroundColor("mode2031");
 				}, 100);
 				return;
 			}
@@ -662,14 +671,14 @@ export class ProcessTerminal implements Terminal {
 	 * DA1 avoids indefinite hangs: if DA1 response arrives before OSC 11,
 	 * the terminal does not support OSC 11.
 	 */
-	#queryBackgroundColor(): void {
+	#queryBackgroundColor(source: Osc11QuerySource): void {
 		if (this.#dead) return;
-		// Queue if an OSC 11 query is in flight or its DA1 sentinel hasn't been
-		// consumed yet. Starting a new query while a DA1 is outstanding would
-		// increment the sentinel counter, and the old DA1 arrival would then
-		// prematurely clear the new query's pending state.
+		// Queue if an OSC 11 query is in flight or its DA1 sentinel has not yet
+		// been consumed. Mode 2031 push evidence outranks a periodic poll.
 		if (this.#osc11Pending || this.#pendingDa1Sentinels > 0) {
-			this.#osc11QueryQueued = true;
+			if (source === "mode2031" || (source === "poll" && this.#osc11QueuedSource === undefined)) {
+				this.#osc11QueuedSource = source;
+			}
 			return;
 		}
 		this.#startOsc11Query();
@@ -698,11 +707,12 @@ export class ProcessTerminal implements Terminal {
 			this.#osc11QueryWatchdog = undefined;
 			if (this.#dead) return;
 			if (!this.#osc11Pending && this.#pendingDa1Sentinels === 0) return;
+			const queuedSource = this.#osc11QueuedSource;
+			this.#osc11QueuedSource = undefined;
 			this.#osc11Pending = false;
 			this.#osc11ResponseBuffer = "";
 			this.#pendingDa1Sentinels = 0;
-			if (this.#osc11QueryQueued && !this.#dead) {
-				this.#osc11QueryQueued = false;
+			if (queuedSource && !this.#dead) {
 				this.#startOsc11Query();
 			}
 		}, 1000);
@@ -750,7 +760,7 @@ export class ProcessTerminal implements Terminal {
 				this.#stopOsc11Poll();
 				return;
 			}
-			this.#queryBackgroundColor();
+			this.#queryBackgroundColor("poll");
 		}, 2_000);
 		this.#osc11PollTimer.unref();
 	}
@@ -878,7 +888,7 @@ export class ProcessTerminal implements Terminal {
 		}
 		this.#appearanceCallbacks = [];
 		this.#osc11Pending = false;
-		this.#osc11QueryQueued = false;
+		this.#osc11QueuedSource = undefined;
 		this.#osc11ResponseBuffer = "";
 		this.#privateCsiResponseBuffer = "";
 		this.#pendingDa1Sentinels = 0;

package/src/tui.ts

@@ -430,6 +430,28 @@ export function shouldUseViewportRepaintForHost(
 	return isViewportSensitiveHost(env, platform, includeNativeWindows, includeProcessTerminal);
 }
 
+/**
+ * Viewport-repaint host gate resolved against a terminal's reported capability.
+ *
+ * `includeNativeWindows` exists so a Windows console host that cannot report
+ * `isProcessTerminal` is still recognized from platform identity. It is a
+ * fallback, so it must not outrank a terminal that has answered: a terminal
+ * reporting `false` is not a native console host, and letting win32 override it
+ * gives every non-process terminal on Windows — embedders, pipes, and the
+ * render regression suite — viewport-repaint semantics. Those hosts then never
+ * replay durable history, so contracted rows survive as duplicates.
+ */
+export function shouldUseViewportRepaintForTerminal(
+	isProcessTerminal: boolean | undefined,
+	env: Record<string, string | undefined> = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	return shouldUseViewportRepaintForHost(env, platform, {
+		includeNativeWindows: isProcessTerminal !== false,
+		includeProcessTerminal: isProcessTerminal === true,
+	});
+}
+
 /**
  * Options for overlay positioning and sizing.
  * Values can be absolute numbers or percentage strings (e.g., "50%").
@@ -903,6 +925,8 @@ export class TUI extends Container {
 	// showHardwareCursor=false but cursor is shown for IME anchoring (macOS).
 	#imeCursorActive = false;
 	#clearOnShrink = $pickflag("GJC_CLEAR_ON_SHRINK", "PI_CLEAR_ON_SHRINK");
+	#synchronizedOutputBegin = "";
+	#synchronizedOutputEnd = "";
 
 	// Default-on: reuse the previous normalized off-screen prefix and only normalize/diff the
 	// visible window, bounding per-frame work on huge transcripts. Output stays byte-identical;
@@ -997,6 +1021,9 @@ export class TUI extends Container {
 		this.terminal = terminal;
 		this.#legacyMultiplexerFullRender =
 			isMultiplexerSession(Bun.env) && envIsEnabled(Bun.env.PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER);
+		const synchronizedOutputEnabled = $flag("GJC_TUI_SYNCHRONIZED_OUTPUT", true);
+		this.#synchronizedOutputBegin = synchronizedOutputEnabled ? "\x1b[?2026h" : "";
+		this.#synchronizedOutputEnd = synchronizedOutputEnabled ? "\x1b[?2026l" : "";
 		if (showHardwareCursor !== undefined) {
 			this.#showHardwareCursor = showHardwareCursor;
 		}
@@ -1671,6 +1698,10 @@ export class TUI extends Container {
 		return this.#guardTerminalOperation(() => this.terminal.write(data), !deferRenderFailure);
 	}
 
+	#frameSynchronizedOutput(payload: string): string {
+		return `${this.#synchronizedOutputBegin}${payload}${this.#synchronizedOutputEnd}`;
+	}
+
 	#hideCursor(): boolean {
 		return this.#guardTerminalOperation(() => this.terminal.hideCursor());
 	}
@@ -1939,6 +1970,11 @@ export class TUI extends Container {
 		this.#forcedRenderQueued = false;
 	}
 
+	/** Host gate for viewport-repaint decisions, resolved against this terminal. */
+	#viewportRepaintHost(): boolean {
+		return shouldUseViewportRepaintForTerminal(this.terminal.isProcessTerminal);
+	}
+
 	/**
 	 * Viewport-repaint-aware resize render request.
 	 *
@@ -1962,13 +1998,7 @@ export class TUI extends Container {
 		this.#lastObservedWidth = observedWidth;
 		const heightChanged = this.#previousHeight !== this.terminal.rows;
 		if (widthChanged) this.#scheduleWidthSettleRedraw();
-		this.requestRender(
-			heightChanged &&
-				!shouldUseViewportRepaintForHost(Bun.env, process.platform, {
-					includeProcessTerminal: this.terminal.isProcessTerminal === true,
-				}),
-			"resize",
-		);
+		this.requestRender(heightChanged && !this.#viewportRepaintHost(), "resize");
 	}
 
 	/**
@@ -3135,7 +3165,7 @@ export class TUI extends Container {
 					{ top: transcriptLineCount, bottom: transcriptLineCount + suffixLineCount },
 				]
 			: [{ top: nextViewportTop, bottom: nextViewportTop + height }];
-		let buffer = `\x1b[?2026h${deletePlan.output}`;
+		let buffer = deletePlan.output;
 		buffer += "\x1b[H";
 		const committedTranscriptRows: Array<number | null> = [];
 		for (let screenRow = 0; screenRow < height; screenRow++) {
@@ -3175,7 +3205,7 @@ export class TUI extends Container {
 			cursorToRow = cursor.toRow;
 		}
 		buffer += cursorSeq;
-		buffer += "\x1b[?2026l";
+		buffer = this.#frameSynchronizedOutput(buffer);
 		let contentWritten = false;
 		const writeSucceeded = this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, lines.length, () => {
 			contentWritten = true;
@@ -3564,10 +3594,7 @@ export class TUI extends Container {
 			return;
 		}
 		// Helper to clear scrollback and viewport and render all new lines
-		const shouldPreserveScrollbackOnFullClear =
-			shouldUseViewportRepaintForHost(Bun.env, process.platform, {
-				includeProcessTerminal: this.terminal.isProcessTerminal === true,
-			}) || this.#legacyMultiplexerFullRender;
+		const shouldPreserveScrollbackOnFullClear = this.#viewportRepaintHost() || this.#legacyMultiplexerFullRender;
 		let viewportRepaint: (
 			reason: string,
 			targetViewportTopOrAllowPastLiveBottom?: number | boolean,
@@ -3591,7 +3618,7 @@ export class TUI extends Container {
 				[],
 				clear,
 			);
-			let buffer = `\x1b[?2026h${deletePlan.output}`; // Begin synchronized output
+			let buffer = deletePlan.output;
 			// Skip clearing scrollback (3J) in hosts where clear/replay can snap the
 			// native viewport away from the live prompt (tmux/screen, Windows ConPTY) —
 			// unless the caller explicitly needs history erased (the settled width
@@ -3609,7 +3636,7 @@ export class TUI extends Container {
 			const cursorRow = Math.max(0, newLines.length - 1);
 			const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, cursorRow);
 			buffer += seq;
-			buffer += "\x1b[?2026l"; // End synchronized output
+			buffer = this.#frameSynchronizedOutput(buffer);
 			if (
 				!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length, () => {
 					this.#cursorRow = cursorRow;
@@ -3763,9 +3790,7 @@ export class TUI extends Container {
 			fullRender(true, "width settled", true);
 			return;
 		}
-		const useViewportRepaintPath = shouldUseViewportRepaintForHost(Bun.env, process.platform, {
-			includeProcessTerminal: this.terminal.isProcessTerminal === true,
-		});
+		const useViewportRepaintPath = this.#viewportRepaintHost();
 		const widthReflowRequired =
 			this.#previousWidth > 0 &&
 			rawLines.some(
@@ -3811,7 +3836,9 @@ export class TUI extends Container {
 					.slice(0, this.#restartDurableLineCount)
 					.every((line, index) => line === this.#restartDurableRawLines[index]);
 			if (restartAppendProven && rawLines.length > this.#restartDurableLineCount) {
-				const appendBuffer = `\x1b[?2026h${newLines.slice(this.#restartDurableLineCount).join("\r\n")}\x1b[?2026l`;
+				const appendBuffer = this.#frameSynchronizedOutput(
+					newLines.slice(this.#restartDurableLineCount).join("\r\n"),
+				);
 				if (!this.#writeTerminal(appendBuffer)) return;
 				// The append already reached native scrollback. Advance both the live
 				// frontier and the retained restart baseline before the viewport write:
@@ -4057,7 +4084,7 @@ export class TUI extends Container {
 				const deletePlan = this.#kittyPlacementDeletePlan(previousKittyPlacementSpans, nextKittyPlacementSpans, [
 					{ top: firstChanged, bottom: lastChanged + 1 },
 				]);
-				let buffer = `\x1b[?2026h${deletePlan.output}`;
+				let buffer = deletePlan.output;
 				// Move to end of new content (clamp to 0 for empty content)
 				const targetRow = Math.max(0, newLines.length - 1);
 				const lineDiff = computeLineDiff(targetRow);
@@ -4085,7 +4112,7 @@ export class TUI extends Container {
 				}
 				const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, targetRow);
 				buffer += seq;
-				buffer += "\x1b[?2026l";
+				buffer = this.#frameSynchronizedOutput(buffer);
 				if (
 					!this.#writeRenderBufferAndReanchorImeCursor(buffer, cursorPos, newLines.length, () => {
 						this.#cursorRow = targetRow;
@@ -4226,7 +4253,7 @@ export class TUI extends Container {
 		const deletePlan = this.#kittyPlacementDeletePlan(previousKittyPlacementSpans, nextKittyPlacementSpans, [
 			{ top: firstChanged, bottom: lastChanged + 1 },
 		]);
-		let buffer = `\x1b[?2026h${deletePlan.output}`; // Begin synchronized output
+		let buffer = deletePlan.output;
 		const prevViewportBottom = prevViewportTop + height - 1;
 		const nativeScrollbackAdmission =
 			appendedLines &&
@@ -4341,7 +4368,7 @@ export class TUI extends Container {
 
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, finalCursorRow);
 		buffer += seq;
-		buffer += "\x1b[?2026l"; // End synchronized output
+		buffer = this.#frameSynchronizedOutput(buffer);
 
 		if ($pickflag("GJC_TUI_DEBUG", "PI_TUI_DEBUG")) {
 			const debugDir = "/tmp/tui";
@@ -4490,7 +4517,7 @@ export class TUI extends Container {
 			// DECSC/DECRC keep the hardware cursor stable; the dedicated
 			// synchronized block prevents visible tearing while the overlay
 			// area is cleared and redrawn.
-			const overlayBuffer = `\x1b[?2026h\x1b7${overlay}\x1b8\x1b[?2026l`;
+			const overlayBuffer = this.#frameSynchronizedOutput(`\x1b7${overlay}\x1b8`);
 			// Overlay delivery is outside shared transcript ownership. The
 			// shared write has already committed even when this exempt write
 			// fails, so do not make callers retry the shared bytes.