@oh-my-pi/pi-tui 18.0.6 → 18.0.8

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [18.0.8] - 2026-08-27
+
+### Added
+
+- `ProcessTerminal` accepts a `conpty` option to force ConPTY-hosted behavior on or off, keeping terminal tests hermetic on WSL where live env detection would otherwise flip kitty-keyboard flags and write chunking ([#9887](https://github.com/can1357/oh-my-pi/issues/9887)).
+
+### Fixed
+
+- Fixed pending-work animations repeatedly composing expensive frames without applying their full render cost to CPU backpressure.
+- Fixed unfinished live viewport rows entering tmux pane history and duplicating streamed output ([#9780](https://github.com/can1357/oh-my-pi/issues/9780)).
+
+## [18.0.7] - 2026-08-26
+
+### Breaking Changes
+
+- Removed the `inlineMathSpanEnd` and `mathStartIndex` exports; the math delimiter grammar now lives in `@oh-my-pi/pi-utils/math-delimiters`.
+
+### Fixed
+
+- Math spans now end at the first unescaped delimiter, so a TeX row break no longer closes a span early: `\(a \\) b\)` renders as one equation, and an escaped `\$` no longer ends `$$…$$`.
+- Fixed image previews displaying as garbled characters in Paseo terminals.
+- Fixed terminal resizing from duplicating committed history in native scrollback.
+- Fixed autocomplete suggestions for bare-name skills such as `/batch` when no command matches the prefix more strongly.
+
 ## [18.0.6] - 2026-08-26
 
 ### Added

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

@@ -1,8 +1,6 @@
 import type { SymbolTheme } from "../symbols.js";
 import type { Component } from "../tui.js";
 /** @internal exported for tests — must stay index-identical to the old regex scan. */
-export declare function mathStartIndex(src: string): number | undefined;
-/** @internal exported for tests — must stay index-identical to the old regex scan. */
 export declare function autolinkSchemeScanIndex(src: string): number | undefined;
 /** @internal exported for tests — must never return false for a src the built-in url regex matches. */
 export declare function urlTokenPossible(src: string): boolean;

package/dist/types/latex-to-unicode.d.ts

@@ -39,12 +39,3 @@ export declare function isBareMathEnvironment(env: string): boolean;
  * $10" is left untouched.
  */
 export declare function renderMathInText(text: string): string;
-/**
- * Index of the `$` that closes an inline math span opened at `open` (the index
- * of the opening `$`), or -1 when the run is not inline math. Applies pandoc's
- * anti-currency heuristics: the opener must not be followed by whitespace, the
- * closer must not be preceded by whitespace nor followed by a digit, `\$` is a
- * literal dollar, and the span may not span a newline. Shared by
- * `renderMathInText` and the markdown math tokenizer so the rule has one home.
- */
-export declare function inlineMathSpanEnd(text: string, open: number): number;

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

@@ -153,6 +153,23 @@ export declare function shouldEnableHyperlinksByDefault(env?: NodeJS.ProcessEnv,
  * without mutating `process.platform`.
  */
 export declare function resolveWarpImageProtocol(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): ImageProtocol | null;
+/**
+ * Paseo (getpaseo/paseo) hardcodes `TERM_PROGRAM=kitty` into every PTY
+ * (`buildTerminalEnvironment`) while its xterm.js renderer implements neither
+ * Kitty graphics nor Unicode placeholders — trusting the advertisement turns
+ * image previews into literal PUA garbage (getpaseo/paseo#3850). Paseo
+ * injects `PASEO_TERMINAL_ID` into every terminal it hosts, which makes a
+ * reliable embedder signal.
+ */
+export declare function isPaseoEmbedder(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve the image protocol for a non-forced runtime: static per-terminal
+ * support (with Warp's platform carve-out), then the multiplexer fallback,
+ * then the Paseo embedder carve-out. `isTTY` is injectable because the
+ * fallback only fires on a real TTY — a piped subprocess cannot exercise
+ * that path, so regression tests call this directly.
+ */
+export declare function resolveImageProtocol(terminalId: TerminalId, env?: NodeJS.ProcessEnv, isTTY?: boolean): ImageProtocol | null;
 /** Resolve terminal identity from environment markers used by common emulators. */
 export declare function detectTerminalId(env?: NodeJS.ProcessEnv): TerminalId;
 export declare const TERMINAL_ID: TerminalId;

package/dist/types/terminal.d.ts

@@ -172,11 +172,22 @@ export interface Terminal {
  * single predicate.
  */
 export declare function isConPTYHosted(): boolean;
+/** Construction-time overrides for {@link ProcessTerminal}. */
+export interface ProcessTerminalOptions {
+    /**
+     * Force ConPTY-hosted behavior on or off. Defaults to live detection via
+     * {@link isConPTYHosted}. Tests set this so the kitty-flag and write-chunking
+     * paths stay hermetic regardless of the ambient WSL env (`WSL_DISTRO_NAME` /
+     * `WSL_INTEROP`) — the suite must behave identically on WSL and on CI.
+     */
+    conpty?: boolean;
+}
 /**
  * Real terminal using process.stdin/stdout
  */
 export declare class ProcessTerminal implements Terminal {
     #private;
+    constructor(options?: ProcessTerminalOptions);
     get kittyProtocolActive(): boolean;
     get kittyEnableSequence(): string | null;
     get keyboardEnhancementEnterSequence(): string | null;

package/dist/types/tui.d.ts

@@ -292,6 +292,13 @@ export declare class TUI extends Container {
      * positive report, disabled on a negative one.
      */
     get synchronizedOutput(): boolean;
+    /**
+     * Cost in milliseconds of the most recently completed frame.
+     *
+     * Animation components use this to apply proportional backpressure after
+     * their render request is asynchronously composed and written.
+     */
+    get lastFrameCostMs(): number;
     setFocus(component: Component | null): void;
     /** Component currently receiving keyboard input, if any. */
     getFocused(): Component | null;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.0.6",
+	"version": "18.0.8",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.0.6",
-		"@oh-my-pi/pi-utils": "18.0.6"
+		"@oh-my-pi/pi-natives": "18.0.8",
+		"@oh-my-pi/pi-utils": "18.0.8"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/autocomplete.ts

@@ -331,10 +331,19 @@ function buildSlashCommandCompletions(
 				let best: (AutocompleteItem & { score: number; usage: number }) | undefined;
 
 				const isSkillCommand = name.startsWith(SKILL_NAMESPACE);
+				// Skills are matched by their bare name as well as the full
+				// `skill:` name so a broken-out or mid-prompt skill ranks at
+				// prefix strength (`/batch` → `skill:batch`) instead of a weak
+				// full-name fuzzy hit.
 				const nameScore =
 					lowerPrefix.length === 0 && isSkillCommand
 						? 950
-						: scoreCommandTextMatch(lowerPrefix, name.toLowerCase());
+						: isSkillCommand
+							? Math.max(
+									scoreCommandTextMatch(lowerPrefix, name.toLowerCase()),
+									scoreCommandTextMatch(lowerPrefix, name.slice(SKILL_NAMESPACE.length).toLowerCase()),
+								)
+							: scoreCommandTextMatch(lowerPrefix, name.toLowerCase());
 				const lowerDesc = staticDesc.toLowerCase();
 				const descScore =
 					lowerDesc && fuzzyMatch(lowerPrefix, lowerDesc) ? fuzzyScore(lowerPrefix, lowerDesc) * 0.5 : 0;
@@ -391,23 +400,56 @@ function hasPromptTextBeforeSlash(
 
 export const SKILL_NAMESPACE = "skill:";
 
+/**
+ * Match tier used to compare a skill's bare name against non-skill command
+ * names when deciding whether the skill may break out of the collapsed
+ * `skill:` group: exact (1000) > prefix (900) > anything weaker (0). Fuzzy
+ * hits deliberately map to 0 — a fuzzy skill match is never strong enough to
+ * mix skills into the command popup.
+ */
+function skillBreakoutTier(lowerPrefix: string, lowerTarget: string): number {
+	if (lowerPrefix === lowerTarget) return 1000;
+	if (lowerTarget.startsWith(lowerPrefix)) return 900;
+	return 0;
+}
+
 /**
  * Collapse `skill:*` commands into a single `/skill:` namespace row while the
- * typed prefix has not committed to the namespace. Until the prefix starts
- * with `skill:`, individual skills never list — a lone group entry (shown only
- * while the prefix is still a prefix of `skill:`) keeps the `/` popup
- * readable. Accepting the group inserts `/skill:` without a trailing space so
- * the reopened popup expands to the individual skills.
+ * typed prefix has not committed to the namespace. A lone group entry (shown
+ * only while the prefix is still a prefix of `skill:`) keeps the `/` popup
+ * readable. A skill breaks out of the group only when its bare name matches
+ * the prefix at a strictly stronger tier than every non-skill command name
+ * and alias (`/batch` → `skill:batch` while no command prefix-matches
+ * `batch`); a tie keeps the popup command-only, and fuzzy-only skill hits
+ * never surface. Accepting the group inserts `/skill:` without a trailing
+ * space so the reopened popup expands to the individual skills.
  */
 function collapseSkillNamespace(commands: CommandEntry[], lowerPrefix: string): CommandEntry[] {
 	if (lowerPrefix.startsWith(SKILL_NAMESPACE)) return commands;
+	const approachesNamespace = SKILL_NAMESPACE.startsWith(lowerPrefix);
+	let commandTier = 0;
+	if (!approachesNamespace) {
+		for (const cmd of commands) {
+			const name = getCommandName(cmd);
+			if (!name || name.startsWith(SKILL_NAMESPACE)) continue;
+			commandTier = Math.max(commandTier, skillBreakoutTier(lowerPrefix, name.toLowerCase()));
+			for (const alias of getCommandAliases(cmd)) {
+				commandTier = Math.max(commandTier, skillBreakoutTier(lowerPrefix, alias.toLowerCase()));
+			}
+			if (commandTier === 1000) break;
+		}
+	}
 	let skillCount = 0;
 	let skillIcon: string | undefined;
 	const rest = commands.filter(cmd => {
-		if (!getCommandName(cmd)?.startsWith(SKILL_NAMESPACE)) return true;
+		const name = getCommandName(cmd);
+		if (!name?.startsWith(SKILL_NAMESPACE)) return true;
 		skillCount += 1;
 		skillIcon ??= cmd.icon;
-		return false;
+		return (
+			!approachesNamespace &&
+			skillBreakoutTier(lowerPrefix, name.slice(SKILL_NAMESPACE.length).toLowerCase()) > commandTier
+		);
 	});
 	if (skillCount === 0) return commands;
 	if (!SKILL_NAMESPACE.startsWith(lowerPrefix)) return rest;

package/src/components/loader.ts

@@ -5,6 +5,7 @@ import { Text } from "./text";
 const RENDER_INTERVAL_MS = 1000 / 30;
 const SPINNER_ADVANCE_MS = 80;
 const RENDER_BACKPRESSURE_MULTIPLIER = 9;
+const MAX_BACKPRESSURE_FRAME_COST_MS = 200;
 
 type ColorFn = (str: string) => string;
 
@@ -139,12 +140,17 @@ export class Loader extends Text {
 				this.#requestPaint();
 			}
 
-			const frameCostMs = performance.now() - startedAt;
+			const completedFrameCostMs = this.#ui?.lastFrameCostMs ?? 0;
+			const requestCostMs = performance.now() - startedAt;
 			if (this.#intervalId !== timer) return;
-			const cadenceDelayMs = Math.max(0, intervalMs - frameCostMs);
-			// Idle for nine times the paint cost to keep animation at or below
-			// 10% CPU, even when a slow ConPTY write exceeds the normal cadence.
-			const backpressureDelayMs = frameCostMs * RENDER_BACKPRESSURE_MULTIPLIER;
+			const cadenceDelayMs = Math.max(0, intervalMs - requestCostMs);
+			// Idle for nine times the full frame cost to keep animation at or
+			// below 10% CPU even though requestComponentRender() only enqueues.
+			const boundedFrameCostMs = Math.min(
+				MAX_BACKPRESSURE_FRAME_COST_MS,
+				Math.max(completedFrameCostMs, requestCostMs),
+			);
+			const backpressureDelayMs = boundedFrameCostMs * RENDER_BACKPRESSURE_MULTIPLIER;
 			this.#scheduleTick(intervalMs, Math.max(cadenceDelayMs, backpressureDelayMs));
 		}, delayMs);
 		this.#intervalId = timer;

package/src/components/markdown.ts

@@ -7,8 +7,9 @@ import {
 	type TokenizerAndRendererExtension,
 	type Tokens,
 } from "@oh-my-pi/pi-utils/marked";
+import { mathBlockAt, mathSpanAt, mathStartIndex } from "@oh-my-pi/pi-utils/math-delimiters";
 import { latexToBlock } from "../latex-block";
-import { inlineMathSpanEnd, isBareMathEnvironment, latexToUnicode } from "../latex-to-unicode";
+import { isBareMathEnvironment, latexToUnicode } from "../latex-to-unicode";
 import type { SymbolTheme } from "../symbols";
 import { TERMINAL } from "../terminal-capabilities";
 import type { Component } from "../tui";
@@ -528,7 +529,7 @@ markdownParser.setOptions({
 // `math` inline token before markdown's escape/emphasis/link rules run, so
 // backslash commands (`\frac`, `\alpha`) and intraword underscores (`x_i`)
 // survive intact instead of being mangled or split. The `$…$` form uses
-// pandoc's anti-currency heuristic (`inlineMathSpanEnd`) so "$5 and $10" is
+// pandoc's anti-currency heuristic (`mathSpanAt`) so "$5 and $10" is
 // never math. Inline extensions run before marked's escape tokenizer, so
 // `\(…\)` becomes math while a genuinely escaped `\$` is left to `escape` and
 // renders as a literal dollar.
@@ -582,78 +583,33 @@ const customHrExtension: TokenizerAndRendererExtension = {
 	},
 };
 
-// Leftmost-match scan replacing /\$|\\\(|\\\[/ in mathExtension.start —
-// marked calls start() on the remaining source at every inline position, so
-// the regex alternation showed up in CPU profiles (part of a ~4.3% start()
-// tail). Three indexOf scans yield the identical leftmost index.
-/** @internal exported for tests — must stay index-identical to the old regex scan. */
-export function mathStartIndex(src: string): number | undefined {
-	let best = src.indexOf("$");
-	const paren = src.indexOf("\\(");
-	if (paren !== -1 && (best === -1 || paren < best)) best = paren;
-	const bracket = src.indexOf("\\[");
-	if (bracket !== -1 && (best === -1 || bracket < best)) best = bracket;
-	return best === -1 ? undefined : best;
-}
-
+// Delimiters come from `@oh-my-pi/pi-utils/math-delimiters`; rendering policy stays here.
 const mathExtension: TokenizerAndRendererExtension = {
 	name: "math",
 	level: "inline",
-	start(src) {
-		return mathStartIndex(src);
-	},
+	start: mathStartIndex,
 	tokenizer(src) {
-		if (src.startsWith("$$")) {
-			const end = src.indexOf("$$", 2);
-			if (end !== -1 && src.slice(2, end).trim().length > 0) {
-				return { type: "math", raw: src.slice(0, end + 2), text: src.slice(2, end), display: true };
-			}
-			return undefined;
-		}
-		if (src.startsWith("\\[")) {
-			const end = src.indexOf("\\]", 2);
-			if (end !== -1) return { type: "math", raw: src.slice(0, end + 2), text: src.slice(2, end), display: true };
-			return undefined;
-		}
-		if (src.startsWith("\\(")) {
-			const end = src.indexOf("\\)", 2);
-			if (end !== -1) return { type: "math", raw: src.slice(0, end + 2), text: src.slice(2, end), display: false };
-			return undefined;
-		}
-		if (src.charCodeAt(0) === 0x24 /* $ */) {
-			const end = inlineMathSpanEnd(src, 0);
-			if (end !== -1) return { type: "math", raw: src.slice(0, end + 1), text: src.slice(1, end), display: false };
-		}
-		return undefined;
+		const span = mathSpanAt(src, 0);
+		if (!span) return undefined;
+		return { type: "math", raw: src.slice(0, span.end), text: span.body, display: span.display };
 	},
 	renderer(token) {
-		return (token as { text?: string }).text ?? "";
+		return typeof token.text === "string" ? token.text : "";
 	},
 };
 
-// Display math blocks: opening `$$` / `\[` and closing `$$` / `\]` each alone on
-// their own line (≤3 leading spaces). Matched at the block level — before
-// paragraph/list parsing — so a multi-line equation (e.g. a matrix with `\\`
-// row breaks) renders across several lines instead of being collapsed onto one,
-// and blank lines inside the block don't split it. The own-line requirement
-// keeps inline `$$…$$` inside prose for the inline tokenizer above.
-const MATH_BLOCK_DOLLAR = /^ {0,3}\$\$[ \t]*\n([\s\S]+?)\n {0,3}\$\$[ \t]*(?:\n|$)/;
-const MATH_BLOCK_BRACKET = /^ {0,3}\\\[[ \t]*\n([\s\S]+?)\n {0,3}\\\][ \t]*(?:\n|$)/;
-const MATH_BLOCK_START = /(?:^|\n) {0,3}(?:\$\$|\\\[)[ \t]*\n/;
 const mathBlockExtension: TokenizerAndRendererExtension = {
 	name: "mathBlock",
 	level: "block",
-	start(src) {
-		const m = MATH_BLOCK_START.exec(src);
-		return m ? m.index : undefined;
-	},
+	// No `start` hint: marked only probes block extensions at a block boundary
+	// here and never consults their hints.
 	tokenizer(src) {
-		const m = MATH_BLOCK_DOLLAR.exec(src) ?? MATH_BLOCK_BRACKET.exec(src);
-		if (!m || m[1].trim().length === 0) return undefined;
-		return { type: "math", raw: m[0], text: m[1], display: true };
+		const block = mathBlockAt(src);
+		if (!block) return undefined;
+		return { type: "math", raw: block.raw, text: block.body, display: true };
 	},
 	renderer(token) {
-		return (token as { text?: string }).text ?? "";
+		return typeof token.text === "string" ? token.text : "";
 	},
 };
 
@@ -718,7 +674,7 @@ const mathEnvBlockExtension: TokenizerAndRendererExtension = {
 // (return undefined) to marked's own autolink handling unchanged.
 const AUTOLINK_SCHEME_REGEX = /^(?:www\.|https?:\/\/|ftp:\/\/)/i;
 // Case-insensitive scheme scan replacing /www\.|https?:\/\/|ftp:\/\//i in
-// boundedAutolinkExtension.start — like mathStartIndex above, this runs on the
+// boundedAutolinkExtension.start — like `mathStartIndex`, this runs on the
 // remaining source at every inline position (part of a ~4.3% CPU start() scan
 // tail in profiles). charCode-only: no allocation, no toLowerCase copies.
 // `| 32` lower-cases ASCII letters; `.`/`:`/`/` are compared exactly, matching

package/src/latex-to-unicode.ts

@@ -1,3 +1,4 @@
+import { mathSpanAt } from "@oh-my-pi/pi-utils/math-delimiters";
 import { TERMINAL } from "./terminal-capabilities";
 
 // LaTeX → Unicode/ANSI converter.
@@ -1934,47 +1935,34 @@ export function renderMathInText(text: string): string {
 				i += 2;
 				continue;
 			}
-			if (d === "(") {
-				const close = text.indexOf("\\)", i + 2);
-				if (close !== -1) {
-					out += conv(text.slice(i + 2, close));
-					i = close + 2;
-					continue;
-				}
-			} else if (d === "[") {
-				const close = text.indexOf("\\]", i + 2);
-				if (close !== -1) {
-					out += conv(text.slice(i + 2, close));
-					i = close + 2;
-					continue;
-				}
-			} else if (d === "$") {
+			if (d === "$") {
 				out += "$";
 				i += 2;
 				continue;
 			}
+			// `i` as the escape bound: the walk above already consumed `\\` and `\$`.
+			const span = mathSpanAt(text, i, i);
+			if (span) {
+				out += conv(span.body);
+				i = span.end;
+				continue;
+			}
 			out += c;
 			i++;
 			continue;
 		}
 		if (c === "$") {
+			const span = mathSpanAt(text, i, i);
+			if (span) {
+				out += conv(span.body);
+				i = span.end;
+				continue;
+			}
 			if (text[i + 1] === "$") {
-				const close = text.indexOf("$$", i + 2);
-				if (close !== -1 && text.slice(i + 2, close).trim().length > 0) {
-					out += conv(text.slice(i + 2, close));
-					i = close + 2;
-					continue;
-				}
 				out += "$$";
 				i += 2;
 				continue;
 			}
-			const close = inlineMathSpanEnd(text, i);
-			if (close !== -1) {
-				out += conv(text.slice(i + 1, close));
-				i = close + 1;
-				continue;
-			}
 			out += "$";
 			i++;
 			continue;
@@ -1984,34 +1972,3 @@ export function renderMathInText(text: string): string {
 	}
 	return renderBareMathInText(out);
 }
-
-/**
- * Index of the `$` that closes an inline math span opened at `open` (the index
- * of the opening `$`), or -1 when the run is not inline math. Applies pandoc's
- * anti-currency heuristics: the opener must not be followed by whitespace, the
- * closer must not be preceded by whitespace nor followed by a digit, `\$` is a
- * literal dollar, and the span may not span a newline. Shared by
- * `renderMathInText` and the markdown math tokenizer so the rule has one home.
- */
-export function inlineMathSpanEnd(text: string, open: number): number {
-	const after = text[open + 1];
-	if (after === undefined || after === " " || after === "\t" || after === "\n" || after === "$") {
-		return -1;
-	}
-	for (let j = open + 1; j < text.length; j++) {
-		const ch = text[j];
-		if (ch === "\\") {
-			j++;
-			continue;
-		}
-		if (ch === "\n") return -1;
-		if (ch === "$") {
-			const prev = text[j - 1];
-			if (prev === " " || prev === "\t") return -1;
-			const next = text[j + 1];
-			if (next !== undefined && next >= "0" && next <= "9") continue; // currency: keep scanning
-			return text.slice(open + 1, j).trim().length > 0 ? j : -1;
-		}
-	}
-	return -1;
-}

package/src/terminal-capabilities.ts

@@ -446,10 +446,14 @@ export function shouldEnableHyperlinksByDefault(
 	return true;
 }
 
-function getFallbackImageProtocol(terminalId: TerminalId): ImageProtocol | null {
-	if (!process.stdout.isTTY) return null;
+function getFallbackImageProtocol(
+	terminalId: TerminalId,
+	env: NodeJS.ProcessEnv = Bun.env,
+	isTTY: boolean = process.stdout.isTTY === true,
+): ImageProtocol | null {
+	if (!isTTY) return null;
 	if (terminalId === "vscode" || terminalId === "alacritty") return null;
-	const term = Bun.env.TERM?.toLowerCase() ?? "";
+	const term = env.TERM?.toLowerCase() ?? "";
 	if (term.includes("screen") || term.includes("tmux") || term.includes("ghostty")) {
 		return ImageProtocol.Kitty;
 	}
@@ -470,6 +474,51 @@ export function resolveWarpImageProtocol(
 	return windowsHost ? null : ImageProtocol.Kitty;
 }
 
+/**
+ * Paseo (getpaseo/paseo) hardcodes `TERM_PROGRAM=kitty` into every PTY
+ * (`buildTerminalEnvironment`) while its xterm.js renderer implements neither
+ * Kitty graphics nor Unicode placeholders — trusting the advertisement turns
+ * image previews into literal PUA garbage (getpaseo/paseo#3850). Paseo
+ * injects `PASEO_TERMINAL_ID` into every terminal it hosts, which makes a
+ * reliable embedder signal.
+ */
+export function isPaseoEmbedder(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	return Boolean(env.PASEO_TERMINAL_ID);
+}
+
+/**
+ * Resolve the image protocol for a non-forced runtime: static per-terminal
+ * support (with Warp's platform carve-out), then the multiplexer fallback,
+ * then the Paseo embedder carve-out. `isTTY` is injectable because the
+ * fallback only fires on a real TTY — a piped subprocess cannot exercise
+ * that path, so regression tests call this directly.
+ */
+export function resolveImageProtocol(
+	terminalId: TerminalId,
+	env: NodeJS.ProcessEnv = Bun.env,
+	isTTY: boolean = process.stdout.isTTY === true,
+): ImageProtocol | null {
+	let imageProtocol: ImageProtocol | null;
+	if (terminalId === "warp") {
+		// Warp advertises Kitty graphics on macOS/Linux only; drop it on win32.
+		imageProtocol = resolveWarpImageProtocol(process.platform, env);
+	} else {
+		imageProtocol = getTerminalInfo(terminalId).imageProtocol;
+		if (!imageProtocol) {
+			const fallbackImageProtocol = getFallbackImageProtocol(terminalId, env, isTTY);
+			if (fallbackImageProtocol) imageProtocol = fallbackImageProtocol;
+		}
+	}
+	// Paseo's xterm.js renderer draws neither Kitty APC nor placeholders —
+	// applied after the multiplexer fallback so tmux/screen inside a Paseo
+	// pane cannot restore Kitty via getFallbackImageProtocol
+	// (getpaseo/paseo#3850).
+	if (imageProtocol !== null && isPaseoEmbedder(env)) {
+		return null;
+	}
+	return imageProtocol;
+}
+
 function getWarpTerminalInfo(platform: NodeJS.Platform, env: NodeJS.ProcessEnv = Bun.env): TerminalInfo {
 	return new TerminalInfo(
 		"warp",
@@ -572,12 +621,8 @@ export const TERMINAL: RuntimeTerminal = (() => {
 	const forcedImageProtocol = getForcedImageProtocol();
 	if (forcedImageProtocol !== undefined) {
 		resolved.imageProtocol = forcedImageProtocol;
-	} else if (resolved.id === "warp") {
-		// Warp advertises Kitty graphics on macOS/Linux only; drop it on win32.
-		resolved.imageProtocol = resolveWarpImageProtocol();
-	} else if (!resolved.imageProtocol) {
-		const fallbackImageProtocol = getFallbackImageProtocol(resolved.id);
-		if (fallbackImageProtocol) resolved.imageProtocol = fallbackImageProtocol;
+	} else {
+		resolved.imageProtocol = resolveImageProtocol(resolved.id, Bun.env, process.stdout.isTTY === true);
 	}
 	// Hyperlink (OSC 8) capability. The static per-terminal flag lives on
 	// KNOWN_TERMINALS; shouldEnableHyperlinksByDefault folds in runtime context —

package/src/terminal.ts

@@ -581,6 +581,17 @@ function isPrivateModeSupported(status: string): boolean {
 	return status !== "0" && status !== "4";
 }
 
+/** Construction-time overrides for {@link ProcessTerminal}. */
+export interface ProcessTerminalOptions {
+	/**
+	 * Force ConPTY-hosted behavior on or off. Defaults to live detection via
+	 * {@link isConPTYHosted}. Tests set this so the kitty-flag and write-chunking
+	 * paths stay hermetic regardless of the ambient WSL env (`WSL_DISTRO_NAME` /
+	 * `WSL_INTEROP`) — the suite must behave identically on WSL and on CI.
+	 */
+	conpty?: boolean;
+}
+
 /**
  * Real terminal using process.stdin/stdout
  */
@@ -619,6 +630,11 @@ export class ProcessTerminal implements Terminal {
 	// terminal side effect (writes, probes, raw mode, SIGWINCH, timers) is
 	// suppressed. Defaults on under `bun test` — see isTerminalHeadless().
 	#headless = isTerminalHeadless();
+	// Captured once at construction: whether stdout flows through a ConPTY
+	// pseudo-console. Gates the kitty-flag choice (#1216) and large-write
+	// chunking (#safeWrite). Live-detected by default; tests inject a fixed
+	// value so WSL env does not change behavior. See {@link ProcessTerminalOptions}.
+	readonly #conpty: boolean;
 	#writeLogPath = $env.PI_TUI_WRITE_LOG || "";
 	#stdoutErrorCleanup?: () => void;
 	#stdoutErrorHandler = (err: Error) => {
@@ -674,6 +690,10 @@ export class ProcessTerminal implements Terminal {
 	#windowsTerminalAppearancePollTimer?: Timer;
 	#progressTimer?: Timer;
 
+	constructor(options?: ProcessTerminalOptions) {
+		this.#conpty = options?.conpty ?? isConPTYHosted();
+	}
+
 	get kittyProtocolActive(): boolean {
 		return this.#kittyProtocolActive;
 	}
@@ -1213,7 +1233,7 @@ export class ProcessTerminal implements Terminal {
 				const reportedFlags = parseInt(match[1]!, 10);
 				this.#kittyProtocolActive = true;
 				setKittyProtocolActive(true);
-				if (isConPTYHosted()) {
+				if (this.#conpty) {
 					// ConPTY (native Windows and WSL) drops Shift+letter keypresses
 					// entirely when flag 4 (report alternate keys) is set. Use flag 1
 					// (disambiguate only), preserving flag 2 if already active.
@@ -1863,7 +1883,7 @@ export class ProcessTerminal implements Terminal {
 			// threshold. See #2034 and #2095.
 			const bytes = Buffer.byteLength(data, "utf8");
 			let accepted: boolean;
-			if (isConPTYHosted() && bytes > MAX_CONPTY_WRITE_CHUNK_BYTES) {
+			if (this.#conpty && bytes > MAX_CONPTY_WRITE_CHUNK_BYTES) {
 				accepted = true;
 				for (const chunk of chunkForConPTY(data, MAX_CONPTY_WRITE_CHUNK_BYTES)) {
 					if (this.#dead) break;

package/src/tui.ts

@@ -901,6 +901,16 @@ export class TUI extends Container {
 		return this.#synchronizedOutputEnabled;
 	}
 
+	/**
+	 * Cost in milliseconds of the most recently completed frame.
+	 *
+	 * Animation components use this to apply proportional backpressure after
+	 * their render request is asynchronously composed and written.
+	 */
+	get lastFrameCostMs(): number {
+		return this.#lastFrameCostMs;
+	}
+
 	setFocus(component: Component | null): void {
 		const topVisibleOverlay = this.#getTopmostVisibleOverlay();
 		if (topVisibleOverlay && !isOverlayFocusTarget(topVisibleOverlay.component, component)) {
@@ -2218,6 +2228,14 @@ export class TUI extends Container {
 	 * Append mode leaves the terminal's prior copy in place and writes a
 	 * current-width copy below it. Rebuild mode routes through the destructive
 	 * reset latch so ED3 removes stale history before the same replay.
+	 *
+	 * The append replay only exists to refresh width-shredded scrollback: a
+	 * width change leaves the terminal's committed history wrapped at the old
+	 * width, so the copy below it is the intended fresh current-width render. A
+	 * height-only change reflows nothing (the terminal merely pulls rows back
+	 * out of scrollback), so replaying would write an identical duplicate — the
+	 * editor/status chrome included — below the retained copy. Skip it, matching
+	 * the `widthChanged`-gated commit-ledger logic in {@link #doRender}.
 	 */
 	#prepareResizeReplay(width: number, height: number): void {
 		const size = `${width}x${height}`;
@@ -2240,6 +2258,7 @@ export class TUI extends Container {
 			this.#prepareForcedRender(true);
 			return;
 		}
+		if (width === this.#previousWidth) return;
 		provider.beginHistoryReplay();
 		this.#forceViewportRepaintOnNextRender = true;
 	}
@@ -2352,7 +2371,16 @@ export class TUI extends Container {
 			// committed rows and blanks, never an unfinished frame.
 			const pushed = Math.max(0, startTop + preparedHistory.length + rows - height);
 			if (pushed > this.#providerViewportTop && this.#providerWindow.length > 0) {
-				buffer += `\x1b[${this.#providerViewportTop + 1};1H\x1b[J`;
+				const eraseTop = this.#providerViewportTop;
+				if (eraseTop > 0) {
+					// Below existing history: ED0 here never spans the whole screen.
+					buffer += `\x1b[${eraseTop + 1};1H\x1b[J`;
+				} else {
+					// Full-screen erase makes tmux preserve the live rows (#9780);
+					// EL2 the first row + ED0 the rest clears the same cells, no full clear.
+					buffer += "\x1b[1;1H\x1b[2K";
+					if (height > 1) buffer += "\x1b[2;1H\x1b[J";
+				}
 			}
 			buffer += `\x1b[${startTop + 1};1H`;
 			let screenRow = startTop;
@@ -2471,10 +2499,16 @@ export class TUI extends Container {
 			this.#altActive = false;
 			this.#altMouseTrackingActive = false;
 			this.#altPreviousLines = [];
-			// The alt buffer restore put the pre-overlay normal screen back; a
-			// geometry change while covered invalidates the diff baseline and the
-			// writer's dimension check forces the full anchored rewrite.
+			// The alt-buffer restore put the pre-overlay normal screen back. If
+			// that buffer resized while covered, its cursor moved with width
+			// rewrap or a height-grow scrollback pull, while our viewport anchor
+			// stayed frozen. Recover the restored cursor position before any
+			// provider repaint can overwrite history at the stale row.
 			if (width !== this.#altEnterWidth || height !== this.#altEnterHeight) {
+				if (this.#frameProvider !== undefined) {
+					this.#beginResizeAnchorProbe();
+					return;
+				}
 				this.#forceViewportRepaintOnNextRender = true;
 			}
 		} else if (wantMouseTracking !== this.#altMouseTrackingActive) {