@oh-my-pi/pi-tui 15.10.3 → 15.10.5

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [15.10.5] - 2026-06-08
+
+### Added
+
+- Added `atomicTokenPattern` to `Editor`: when set to a global regex matching placeholder tokens such as `[Image #1, 800x600]` or `[Paste #2, +30 lines]`, a single backspace or forward-delete landing anywhere on a token removes the whole token instead of corrupting it into stray text.
+
+### Changed
+
+- Changed the large-paste placeholder label from `[paste #N +X lines]`/`[paste #N Y chars]` to `[Paste #N, +X lines]`/`[Paste #N, Y chars]`.
+
+### Fixed
+
+- Fixed pasting large text lagging the prompt for hundreds of milliseconds before the `[paste #N …]` placeholder appeared. `StdinBuffer` assembled bracketed pastes by re-concatenating and re-scanning the entire accumulated buffer on every incoming stdin chunk (`#pasteBuffer += chunk; indexOf(END)`), which is O(n²) in the paste size and dominates when the terminal/PTY delivers the paste in many small reads (SSH, tmux, slow hosts) — a 1 MB paste at 1 KB chunks cost ~33 ms and 5 MB ~740 ms. Chunks are now collected in an array and joined once when the end marker arrives, with a short overlap tail carried across chunk boundaries so a marker split between two reads is still detected without rescanning, making assembly O(n) (~1 ms for 5 MB). The `Editor` paste cleaner also dropped its `split("").filter().join("")` per-code-unit array allocation in favor of a single control-character regex pass (~20× faster on large pastes).
+
+## [15.10.4] - 2026-06-08
+
+### Fixed
+
+- Fixed Windows ConPTY session-resume painting the transcript with the last several rows truncated below the viewport until Alt+Tab forced a host repaint. After `sessionReplace`/`historyRebuild`/`overlayRebuild` paints that scroll-push content into native scrollback, the renderer now arms a 150 ms ConPTY settle window that coalesces spinner/blink-driven `requestRender(false)` calls into a single trailing render — Windows Terminal's viewport-follow logic no longer falls further behind the cursor on every tick of the post-paint storm. The arm also reclaims any render request queued *during* the in-flight composition (notably `ImageBudget.endPass()` calling `requestRender()` synchronously when a frame trips the live-graphics cap): without that, the queued request sat on the standard 30 Hz throttle and fired at ~33 ms — well inside the 150 ms quiet window — defeating the coalescing. Bumped the ConPTY per-`WriteFile` chunk cap from 8 KiB to 16 KiB so a multi-megabyte resume paint emits half as many writes (still well under the ~32 KiB threshold from #2034 that the original cap defends against), and made the cap measure encoded UTF-8 bytes instead of JS code units so a CJK-heavy transcript can't silently inflate a 16-KiB-of-code-units chunk into ~48 KiB of `WriteFile` traffic and reintroduce the #2034 viewport bug ([#2095](https://github.com/can1357/oh-my-pi/issues/2095)).
+
 ## [15.10.3] - 2026-06-08
 
 ### Fixed

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

@@ -37,6 +37,12 @@ export declare class Editor implements Component, Focusable {
     decorateText: ((text: string) => string) | undefined;
     borderColor: (str: string) => string;
     onAutocompleteUpdate?: () => void;
+    /** Optional pattern matching atomic placeholder tokens (e.g. `[Image #1, 800x600]` or
+     *  `[Paste #2, +30 lines]`) that the editor treats as indivisible: a backspace or forward-delete
+     *  landing on any character of a token removes the whole token instead of corrupting it into
+     *  stray text. MUST be a global regex; the editor recompiles a private copy so its `lastIndex`
+     *  is never shared with the caller. */
+    atomicTokenPattern: RegExp | undefined;
     onSubmit?: (text: string) => void;
     onAltEnter?: (text: string) => void;
     onChange?: (text: string) => void;

package/dist/types/terminal.d.ts

@@ -1,17 +1,24 @@
 /**
- * Split `data` into chunks no larger than `maxChunkSize`, preferring a line
- * boundary (`\n`) as the cut point so escape sequences (which never contain
- * `\n`) stay intact. The TUI's full-paint buffers are line-structured
- * (`buffer += "\r\n"` between rows), so a newline almost always exists within
- * the window. The fallback for a buffer with no newline in range is a hard
- * cut at `maxChunkSize`: the ConPTY viewport bug from a single oversized
- * write is strictly worse than a one-frame escape-sequence glitch on a buffer
- * the renderer effectively never produces.
+ * Split `data` into chunks whose encoded UTF-8 byte length is no greater than
+ * `maxChunkBytes`, preferring a line boundary (`\n`) as the cut point so
+ * escape sequences (which never contain `\n`) stay intact. The TUI's
+ * full-paint buffers are line-structured (`buffer += "\r\n"` between rows),
+ * so a newline almost always exists within the window. The fallback for a
+ * buffer with no newline in range is a hard cut at the last UTF-8 code-point
+ * boundary that still fits — the ConPTY viewport bug from a single oversized
+ * write is strictly worse than a one-frame escape-sequence glitch on a
+ * buffer the renderer effectively never produces.
+ *
+ * UTF-16 code units are walked manually rather than measuring with
+ * `Buffer.byteLength` per slice candidate: each code unit's UTF-8 width is
+ * known from its value (BMP `<0x80` → 1, `<0x800` → 2, surrogate pair → 4
+ * bytes across two units, other BMP → 3), and surrogate pairs are kept
+ * together so the chunker never splits a non-BMP character.
  *
  * Exported for unit testing of the chunking contract; `#safeWrite` is the
  * sole production caller.
  */
-export declare function chunkForConPTY(data: string, maxChunkSize?: number): string[];
+export declare function chunkForConPTY(data: string, maxChunkBytes?: number): string[];
 /**
  * Emergency terminal restore - call this from signal/crash handlers
  * Resets terminal state without requiring access to the ProcessTerminal instance
@@ -91,6 +98,15 @@ export interface Terminal {
      */
     onPrivateModeReport?(callback: (mode: number, supported: boolean) => void): void;
 }
+/**
+ * True when stdout flows through a ConPTY pseudo-console (native win32, or
+ * Linux running under WSL where stdout still crosses into ConPTY at the
+ * `wslhost` boundary). ConPTY hosts share the per-WriteFile viewport-tracking
+ * quirks documented above and on {@link MAX_CONPTY_WRITE_CHUNK_BYTES}, so both
+ * `#safeWrite` and the renderer's post-big-paint settle gate hang off this
+ * single predicate.
+ */
+export declare function isConPTYHosted(): boolean;
 /**
  * Real terminal using process.stdin/stdout
  */

package/dist/types/tui.d.ts

@@ -1,5 +1,5 @@
 import { ImageBudget } from "./components/image";
-import type { Terminal } from "./terminal";
+import { type Terminal } from "./terminal";
 import { visibleWidth } from "./utils";
 type InputListenerResult = {
     consume?: boolean;

package/package.json

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

package/src/components/editor.ts

@@ -368,6 +368,15 @@ export class Editor implements Component, Focusable {
 	#pastes: Map<number, string> = new Map();
 	#pasteCounter: number = 0;
 
+	/** Optional pattern matching atomic placeholder tokens (e.g. `[Image #1, 800x600]` or
+	 *  `[Paste #2, +30 lines]`) that the editor treats as indivisible: a backspace or forward-delete
+	 *  landing on any character of a token removes the whole token instead of corrupting it into
+	 *  stray text. MUST be a global regex; the editor recompiles a private copy so its `lastIndex`
+	 *  is never shared with the caller. */
+	atomicTokenPattern: RegExp | undefined;
+	#atomicTokenSource: string | undefined;
+	#atomicTokenRe: RegExp | undefined;
+
 	// Bracketed paste mode buffering
 	#pasteHandler = new BracketedPasteHandler();
 
@@ -1389,7 +1398,7 @@ export class Editor implements Component, Focusable {
 	#expandPasteMarkers(text: string): string {
 		let result = text;
 		for (const [pasteId, pasteContent] of this.#pastes) {
-			const markerRegex = new RegExp(`\\[paste #${pasteId}( (\\+\\d+ lines|\\d+ chars))?\\]`, "g");
+			const markerRegex = new RegExp(`\\[Paste #${pasteId}(?:, (?:\\+\\d+ lines|\\d+ chars))?\\]`, "g");
 			result = result.replace(markerRegex, () => pasteContent);
 		}
 		return result;
@@ -1627,11 +1636,10 @@ export class Editor implements Component, Focusable {
 			// Convert tabs to spaces (4 spaces per tab)
 			const tabExpandedText = cleanText.replace(/\t/g, "    ");
 
-			// Filter out non-printable characters except newlines
-			let filteredText = tabExpandedText
-				.split("")
-				.filter(char => char === "\n" || char.charCodeAt(0) >= 32)
-				.join("");
+			// Strip control characters except newline (tabs already expanded above,
+			// CRs already normalized). Single regex pass instead of split/filter/join
+			// to avoid allocating a per-code-unit array for large pastes.
+			let filteredText = tabExpandedText.replace(/[\x00-\x09\x0B-\x1F]/g, "");
 
 			// If pasting a file path (starts with /, ~, or .) and the character before
 			// the cursor is a word character, prepend a space for better readability
@@ -1654,11 +1662,11 @@ export class Editor implements Component, Focusable {
 				const pasteId = this.#pasteCounter;
 				this.#pastes.set(pasteId, filteredText);
 
-				// Insert marker like "[paste #1 +123 lines]" or "[paste #1 1234 chars]"
+				// Insert marker like "[Paste #1, +123 lines]" or "[Paste #1, 1234 chars]"
 				const marker =
 					pastedLines.length > 10
-						? `[paste #${pasteId} +${pastedLines.length} lines]`
-						: `[paste #${pasteId} ${totalChars} chars]`;
+						? `[Paste #${pasteId}, +${pastedLines.length} lines]`
+						: `[Paste #${pasteId}, ${totalChars} chars]`;
 				this.#insertTextAtCursor(marker);
 
 				return;
@@ -1727,26 +1735,72 @@ export class Editor implements Component, Focusable {
 		if (this.onSubmit) this.onSubmit(result);
 	}
 
+	/** Resolve the compiled, global copy of `atomicTokenPattern`, rebuilt only when the source changes. */
+	#getAtomicTokenRe(): RegExp | undefined {
+		const pattern = this.atomicTokenPattern;
+		if (pattern === undefined) {
+			this.#atomicTokenSource = undefined;
+			this.#atomicTokenRe = undefined;
+			return undefined;
+		}
+		if (pattern.source !== this.#atomicTokenSource) {
+			this.#atomicTokenSource = pattern.source;
+			this.#atomicTokenRe = new RegExp(
+				pattern.source,
+				pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`,
+			);
+		}
+		return this.#atomicTokenRe;
+	}
+
+	/** Find an atomic token on `line` whose span contains column `col` (`start <= col < end`). */
+	#atomicTokenAt(line: string, col: number): { start: number; end: number } | undefined {
+		const re = this.#getAtomicTokenRe();
+		if (re === undefined) return undefined;
+		re.lastIndex = 0;
+		for (;;) {
+			const match = re.exec(line);
+			if (match === null) break;
+			if (match[0].length === 0) {
+				re.lastIndex = match.index + 1;
+				continue;
+			}
+			const start = match.index;
+			const end = start + match[0].length;
+			if (col < start) break;
+			if (col < end) return { start, end };
+		}
+		return undefined;
+	}
+
 	#handleBackspace(): void {
 		this.#historyIndex = -1; // Exit history browsing mode
 		this.#resetKillSequence();
 		this.#recordUndoState();
 
 		if (this.#state.cursorCol > 0) {
-			// Delete grapheme before cursor (handles emojis, combining characters, etc.)
 			const line = this.#state.lines[this.#state.cursorLine] || "";
-			const beforeCursor = line.slice(0, this.#state.cursorCol);
+			// An atomic placeholder token (image/paste marker) deletes as a unit, so a single
+			// backspace never leaves a half-eaten `[Paste #1, +30 lines` behind as stray text.
+			const token = this.#atomicTokenAt(line, this.#state.cursorCol - 1);
+			if (token !== undefined) {
+				this.#state.lines[this.#state.cursorLine] = line.slice(0, token.start) + line.slice(token.end);
+				this.#setCursorCol(token.start);
+			} else {
+				// Delete grapheme before cursor (handles emojis, combining characters, etc.)
+				const beforeCursor = line.slice(0, this.#state.cursorCol);
 
-			// Find the last grapheme in the text before cursor
-			const graphemes = [...segmenter.segment(beforeCursor)];
-			const lastGrapheme = graphemes[graphemes.length - 1];
-			const graphemeLength = lastGrapheme ? lastGrapheme.segment.length : 1;
+				// Find the last grapheme in the text before cursor
+				const graphemes = [...segmenter.segment(beforeCursor)];
+				const lastGrapheme = graphemes[graphemes.length - 1];
+				const graphemeLength = lastGrapheme ? lastGrapheme.segment.length : 1;
 
-			const before = line.slice(0, this.#state.cursorCol - graphemeLength);
-			const after = line.slice(this.#state.cursorCol);
+				const before = line.slice(0, this.#state.cursorCol - graphemeLength);
+				const after = line.slice(this.#state.cursorCol);
 
-			this.#state.lines[this.#state.cursorLine] = before + after;
-			this.#setCursorCol(this.#state.cursorCol - graphemeLength);
+				this.#state.lines[this.#state.cursorLine] = before + after;
+				this.#setCursorCol(this.#state.cursorCol - graphemeLength);
+			}
 		} else if (this.#state.cursorLine > 0) {
 			// Merge with previous line
 			const currentLine = this.#state.lines[this.#state.cursorLine] || "";
@@ -2218,17 +2272,25 @@ export class Editor implements Component, Focusable {
 		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 
 		if (this.#state.cursorCol < currentLine.length) {
-			// Delete grapheme at cursor position (handles emojis, combining characters, etc.)
-			const afterCursor = currentLine.slice(this.#state.cursorCol);
+			// An atomic placeholder token (image/paste marker) deletes as a unit.
+			const token = this.#atomicTokenAt(currentLine, this.#state.cursorCol);
+			if (token !== undefined) {
+				this.#state.lines[this.#state.cursorLine] =
+					currentLine.slice(0, token.start) + currentLine.slice(token.end);
+				this.#setCursorCol(token.start);
+			} else {
+				// Delete grapheme at cursor position (handles emojis, combining characters, etc.)
+				const afterCursor = currentLine.slice(this.#state.cursorCol);
 
-			// Find the first grapheme at cursor
-			const graphemes = [...segmenter.segment(afterCursor)];
-			const firstGrapheme = graphemes[0];
-			const graphemeLength = firstGrapheme ? firstGrapheme.segment.length : 1;
+				// Find the first grapheme at cursor
+				const graphemes = [...segmenter.segment(afterCursor)];
+				const firstGrapheme = graphemes[0];
+				const graphemeLength = firstGrapheme ? firstGrapheme.segment.length : 1;
 
-			const before = currentLine.slice(0, this.#state.cursorCol);
-			const after = currentLine.slice(this.#state.cursorCol + graphemeLength);
-			this.#state.lines[this.#state.cursorLine] = before + after;
+				const before = currentLine.slice(0, this.#state.cursorCol);
+				const after = currentLine.slice(this.#state.cursorCol + graphemeLength);
+				this.#state.lines[this.#state.cursorLine] = before + after;
+			}
 		} else if (this.#state.cursorLine < this.#state.lines.length - 1) {
 			// At end of line - merge with next line
 			const nextLine = this.#state.lines[this.#state.cursorLine + 1] || "";

package/src/stdin-buffer.ts

@@ -265,7 +265,8 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 	#timeout?: NodeJS.Timeout;
 	readonly #timeoutMs: number;
 	#pasteMode: boolean = false;
-	#pasteBuffer: string = "";
+	#pasteChunks: string[] = [];
+	#pasteOverlap: string = "";
 	#pendingKittyPrintableCodepoint: number | undefined;
 
 	constructor(options: StdinBufferOptions = {}) {
@@ -302,24 +303,9 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		this.#buffer += str;
 
 		if (this.#pasteMode) {
-			this.#pasteBuffer += this.#buffer;
+			const chunk = this.#buffer;
 			this.#buffer = "";
-
-			const endIndex = this.#pasteBuffer.indexOf(BRACKETED_PASTE_END);
-			if (endIndex !== -1) {
-				const pastedContent = this.#pasteBuffer.slice(0, endIndex);
-				const remaining = this.#pasteBuffer.slice(endIndex + BRACKETED_PASTE_END.length);
-
-				this.#pasteMode = false;
-				this.#pasteBuffer = "";
-				this.#pendingKittyPrintableCodepoint = undefined;
-
-				this.emit("paste", pastedContent);
-
-				if (remaining.length > 0) {
-					this.process(remaining);
-				}
-			}
+			this.#consumePasteChunk(chunk);
 			return;
 		}
 
@@ -335,25 +321,12 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 
 			this.#pendingKittyPrintableCodepoint = undefined;
 			this.#buffer = this.#buffer.slice(startIndex + BRACKETED_PASTE_START.length);
-			this.#pasteMode = true;
-			this.#pasteBuffer = this.#buffer;
+			const firstChunk = this.#buffer;
 			this.#buffer = "";
-
-			const endIndex = this.#pasteBuffer.indexOf(BRACKETED_PASTE_END);
-			if (endIndex !== -1) {
-				const pastedContent = this.#pasteBuffer.slice(0, endIndex);
-				const remaining = this.#pasteBuffer.slice(endIndex + BRACKETED_PASTE_END.length);
-
-				this.#pasteMode = false;
-				this.#pasteBuffer = "";
-				this.#pendingKittyPrintableCodepoint = undefined;
-
-				this.emit("paste", pastedContent);
-
-				if (remaining.length > 0) {
-					this.process(remaining);
-				}
-			}
+			this.#pasteMode = true;
+			this.#pasteChunks = [];
+			this.#pasteOverlap = "";
+			this.#consumePasteChunk(firstChunk);
 			return;
 		}
 
@@ -375,6 +348,42 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		}
 	}
 
+	/**
+	 * Consume one chunk of paste-mode input. Chunks are accumulated in an array
+	 * and only joined once the end marker arrives, so a large paste delivered in
+	 * many small terminal reads stays O(total) instead of the O(total^2) cost of
+	 * re-concatenating and rescanning the whole buffer on every chunk. A short
+	 * overlap tail (end-marker length - 1) is carried across chunk boundaries so
+	 * a marker split between two reads is still detected without rescanning.
+	 */
+	#consumePasteChunk(chunk: string): void {
+		const probe = this.#pasteOverlap + chunk;
+		if (probe.indexOf(BRACKETED_PASTE_END) === -1) {
+			this.#pasteChunks.push(chunk);
+			const keep = BRACKETED_PASTE_END.length - 1;
+			this.#pasteOverlap = probe.length > keep ? probe.slice(probe.length - keep) : probe;
+			return;
+		}
+
+		// End marker arrived: join once and split at its first occurrence,
+		// matching the prior indexOf-from-start semantics exactly.
+		const flat = this.#pasteChunks.length > 0 ? `${this.#pasteChunks.join("")}${chunk}` : chunk;
+		const endIndex = flat.indexOf(BRACKETED_PASTE_END);
+		const pastedContent = flat.slice(0, endIndex);
+		const remaining = flat.slice(endIndex + BRACKETED_PASTE_END.length);
+
+		this.#pasteMode = false;
+		this.#pasteChunks = [];
+		this.#pasteOverlap = "";
+		this.#pendingKittyPrintableCodepoint = undefined;
+
+		this.emit("paste", pastedContent);
+
+		if (remaining.length > 0) {
+			this.process(remaining);
+		}
+	}
+
 	#emitDataSequence(sequence: string): void {
 		const rawCodepoint = sequence.length === 1 ? sequence.codePointAt(0) : undefined;
 		if (rawCodepoint !== undefined && rawCodepoint === this.#pendingKittyPrintableCodepoint) {
@@ -409,7 +418,8 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		}
 		this.#buffer = "";
 		this.#pasteMode = false;
-		this.#pasteBuffer = "";
+		this.#pasteChunks = [];
+		this.#pasteOverlap = "";
 		this.#pendingKittyPrintableCodepoint = undefined;
 	}
 

package/src/terminal.ts

@@ -10,7 +10,7 @@ const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
 const TERMINAL_PROGRESS_CLEAR_SEQUENCE = "\x1b]9;4;0;\x07";
 
 /**
- * Maximum bytes per `process.stdout.write` call on Windows.
+ * Maximum encoded UTF-8 bytes per `process.stdout.write` call on Windows.
  *
  * Windows ConPTY ties viewport tracking to per-`WriteFile` boundaries: when a
  * single write exceeds ~32-64 KB, the pseudo-console stops following the
@@ -20,43 +20,96 @@ const TERMINAL_PROGRESS_CLEAR_SEQUENCE = "\x1b]9;4;0;\x07";
  * first ~30 lines until any focus event forces the host to re-query the
  * cursor. The data is delivered correctly — it's purely a viewport-sync bug.
  *
- * 8 KiB is well below the 32 KiB threshold reported on Windows Terminal and
- * leaves headroom for the other ConPTY hosts (Tabby, Hyper, VS Code) where
- * the exact limit is undocumented. The cost is a handful of extra syscalls
- * per full paint — invisible compared to the cost of the paint itself.
+ * The cap is on **encoded UTF-8 bytes**, not JS code units, because
+ * `process.stdout.write(string)` UTF-8-encodes before handing off to
+ * `WriteFile`. A pure-CJK transcript row encodes to ~3 bytes per BMP code
+ * unit, so a code-unit-based cap of 16 KiB could land at ~48 KiB of actual
+ * `WriteFile` traffic and reintroduce the #2034 parked-viewport bug for
+ * non-ASCII content.
+ *
+ * 16 KiB is half the smallest observed Windows Terminal threshold (32 KiB),
+ * which keeps the per-write parked-viewport bug fixed by #2034 while halving
+ * the WriteFile count on multi-megabyte paints (a 3 MB session resume splits
+ * into ~192 chunks instead of ~384). Fewer WriteFiles means fewer chances for
+ * WT's viewport-following logic to lose track of the cursor during the burst,
+ * which mitigates the residual mid-paint drift the original 8 KiB cap left
+ * behind (#2095). Still well clear of the threshold so the other ConPTY hosts
+ * (Tabby, Hyper, VS Code) — where the exact limit is undocumented — keep
+ * their safety margin.
  */
-const MAX_CONPTY_WRITE_CHUNK = 8 * 1024;
+const MAX_CONPTY_WRITE_CHUNK_BYTES = 16 * 1024;
 
 /**
- * Split `data` into chunks no larger than `maxChunkSize`, preferring a line
- * boundary (`\n`) as the cut point so escape sequences (which never contain
- * `\n`) stay intact. The TUI's full-paint buffers are line-structured
- * (`buffer += "\r\n"` between rows), so a newline almost always exists within
- * the window. The fallback for a buffer with no newline in range is a hard
- * cut at `maxChunkSize`: the ConPTY viewport bug from a single oversized
- * write is strictly worse than a one-frame escape-sequence glitch on a buffer
- * the renderer effectively never produces.
+ * Split `data` into chunks whose encoded UTF-8 byte length is no greater than
+ * `maxChunkBytes`, preferring a line boundary (`\n`) as the cut point so
+ * escape sequences (which never contain `\n`) stay intact. The TUI's
+ * full-paint buffers are line-structured (`buffer += "\r\n"` between rows),
+ * so a newline almost always exists within the window. The fallback for a
+ * buffer with no newline in range is a hard cut at the last UTF-8 code-point
+ * boundary that still fits — the ConPTY viewport bug from a single oversized
+ * write is strictly worse than a one-frame escape-sequence glitch on a
+ * buffer the renderer effectively never produces.
+ *
+ * UTF-16 code units are walked manually rather than measuring with
+ * `Buffer.byteLength` per slice candidate: each code unit's UTF-8 width is
+ * known from its value (BMP `<0x80` → 1, `<0x800` → 2, surrogate pair → 4
+ * bytes across two units, other BMP → 3), and surrogate pairs are kept
+ * together so the chunker never splits a non-BMP character.
  *
  * Exported for unit testing of the chunking contract; `#safeWrite` is the
  * sole production caller.
  */
-export function chunkForConPTY(data: string, maxChunkSize: number = MAX_CONPTY_WRITE_CHUNK): string[] {
-	if (data.length <= maxChunkSize) return [data];
+export function chunkForConPTY(data: string, maxChunkBytes: number = MAX_CONPTY_WRITE_CHUNK_BYTES): string[] {
+	// Fast path: whole buffer fits in one write.
+	if (Buffer.byteLength(data, "utf8") <= maxChunkBytes) return [data];
 	const chunks: string[] = [];
+	const len = data.length;
 	let pos = 0;
-	while (pos < data.length) {
-		const remaining = data.length - pos;
-		if (remaining <= maxChunkSize) {
+	while (pos < len) {
+		let bytes = 0;
+		// Index just past the most recent `\n` we've consumed inside [pos, i):
+		// the natural cut point that leaves escape sequences intact.
+		let lastNewlineEnd = -1;
+		let i = pos;
+		while (i < len) {
+			const cu = data.charCodeAt(i);
+			let cuLen = 1;
+			let cuBytes: number;
+			if (cu < 0x80) {
+				cuBytes = 1;
+			} else if (cu < 0x800) {
+				cuBytes = 2;
+			} else if (cu >= 0xd800 && cu < 0xdc00) {
+				// High surrogate: pair with the following low surrogate (4 bytes
+				// across two code units); an unpaired surrogate UTF-8-encodes as
+				// the 3-byte U+FFFD replacement character.
+				const next = i + 1 < len ? data.charCodeAt(i + 1) : 0;
+				if (next >= 0xdc00 && next < 0xe000) {
+					cuBytes = 4;
+					cuLen = 2;
+				} else {
+					cuBytes = 3;
+				}
+			} else {
+				// BMP non-surrogate or unpaired low surrogate → 3 bytes.
+				cuBytes = 3;
+			}
+			if (bytes + cuBytes > maxChunkBytes && i > pos) {
+				// Would overflow the cap. Cut at the last newline if we found one,
+				// otherwise hard-cut at the current code-point boundary.
+				const cut = lastNewlineEnd > pos ? lastNewlineEnd : i;
+				chunks.push(data.slice(pos, cut));
+				pos = cut;
+				break;
+			}
+			bytes += cuBytes;
+			i += cuLen;
+			if (cu === 0x0a) lastNewlineEnd = i;
+		}
+		if (i >= len) {
 			chunks.push(data.slice(pos));
-			break;
+			pos = len;
 		}
-		const windowEnd = pos + maxChunkSize;
-		// Prefer the last newline inside the window so escape sequences stay
-		// intact within their chunk; hard-cut at `windowEnd` otherwise.
-		const nl = data.lastIndexOf("\n", windowEnd - 1);
-		const cut = nl >= pos ? nl + 1 : windowEnd;
-		chunks.push(data.slice(pos, cut));
-		pos = cut;
 	}
 	return chunks;
 }
@@ -202,7 +255,17 @@ export interface Terminal {
 	onPrivateModeReport?(callback: (mode: number, supported: boolean) => void): void;
 }
 
-function isWindowsSubsystemForLinux(): boolean {
+/**
+ * True when stdout flows through a ConPTY pseudo-console (native win32, or
+ * Linux running under WSL where stdout still crosses into ConPTY at the
+ * `wslhost` boundary). ConPTY hosts share the per-WriteFile viewport-tracking
+ * quirks documented above and on {@link MAX_CONPTY_WRITE_CHUNK_BYTES}, so both
+ * `#safeWrite` and the renderer's post-big-paint settle gate hang off this
+ * single predicate.
+ */
+export function isConPTYHosted(): boolean {
+	if (process.platform === "win32") return true;
+	// WSL: stdout still crosses into ConPTY at the `wslhost` boundary.
 	return process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
 }
 
@@ -349,7 +412,8 @@ export class ProcessTerminal implements Terminal {
 		// Windows Terminal under WSL has been observed to close the hosting tab
 		// after repeated OSC 11/DA1 probes. Keep the initial/event-driven probes,
 		// but avoid background polling there.
-		if (!isWindowsSubsystemForLinux()) {
+		const isWSL = process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
+		if (!isWSL) {
 			this.#startOsc11Poll();
 		}
 
@@ -1090,10 +1154,12 @@ export class ProcessTerminal implements Terminal {
 			// WSL — `process.platform === "linux"` there, but stdout still
 			// crosses into ConPTY at the `wslhost` boundary, so the same per-
 			// WriteFile cap applies. Non-ConPTY PTYs keep the single-write fast
-			// path. See #2034.
-			const conptyHosted = process.platform === "win32" || isWindowsSubsystemForLinux();
-			if (conptyHosted && data.length > MAX_CONPTY_WRITE_CHUNK) {
-				for (const chunk of chunkForConPTY(data, MAX_CONPTY_WRITE_CHUNK)) {
+			// path. The cap is on encoded UTF-8 bytes, not JS code units, because
+			// `process.stdout.write(string)` UTF-8-encodes before `WriteFile`,
+			// and a code-unit cap would let CJK transcript rows expand past the
+			// threshold. See #2034 and #2095.
+			if (isConPTYHosted() && Buffer.byteLength(data, "utf8") > MAX_CONPTY_WRITE_CHUNK_BYTES) {
+				for (const chunk of chunkForConPTY(data, MAX_CONPTY_WRITE_CHUNK_BYTES)) {
 					process.stdout.write(chunk);
 				}
 			} else {

package/src/tui.ts

@@ -17,7 +17,7 @@ import { $flag, getDebugLogPath } from "@oh-my-pi/pi-utils";
 import { DEFAULT_MAX_INLINE_IMAGES, ImageBudget } from "./components/image";
 import { planDeccaraFills } from "./deccara";
 import { isKeyRelease, matchesKey } from "./keys";
-import type { Terminal } from "./terminal";
+import { isConPTYHosted, type Terminal } from "./terminal";
 import {
 	encodeKittyDeleteImage,
 	ImageProtocol,
@@ -494,6 +494,26 @@ export class TUI extends Container {
 	// arrives (issue #2088). Coalescing every SIGWINCH inside this window into
 	// a single forced render lets the multiplexer settle first.
 	static readonly #MULTIPLEXER_RESIZE_DEBOUNCE_MS = 50;
+	// Post-paint settle window for ConPTY hosts. The `sessionReplace` /
+	// `historyRebuild` / `overlayRebuild` intents drive `#emitFullPaint` over
+	// a transcript that overflows the viewport, scroll-pushing everything past
+	// the last `height` rows into native scrollback. Windows Terminal's
+	// viewport-follow logic gets lossy during that burst: spinner/blink-driven
+	// `requestRender(false)` calls firing inside the window each produce another
+	// diff write, and the WT host processes them faster than its viewport
+	// tracker can keep up — the visible tail ends up parked a few rows above
+	// the actual last row until any focus event (Alt+Tab) forces a host repaint.
+	// Coalescing every non-forced render inside this window into a single
+	// trailing render lets the host fully settle the big paint before any
+	// follow-up writes touch the buffer. The first-ever `initial` paint is
+	// deliberately exempt: nothing has been on screen yet, so no drift can
+	// have accumulated, and tests that start the TUI over an over-tall
+	// component depend on the next paint firing without delay. Only armed on
+	// ConPTY hosts (`isConPTYHosted()`); other terminals do not exhibit the
+	// drift and would just see an unnecessary post-paint latency. See #2095.
+	static readonly #CONPTY_POST_FULL_PAINT_SETTLE_MS = 150;
+	#postFullPaintSettleUntilMs = 0;
+	#postFullPaintSettleTimer: RenderTimer | undefined;
 	#cursorRow = 0; // Logical cursor row (end of rendered content)
 	#hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
 	#hardwareCursorState: HardwareCursorState | null = null;
@@ -1106,6 +1126,7 @@ export class TUI extends Container {
 			this.#multiplexerResizeTimer.cancel();
 			this.#multiplexerResizeTimer = undefined;
 		}
+		this.#clearPostFullPaintSettle();
 		this.#deferredForcedClearScrollback = false;
 		// Place the parent shell on the first line after the rendered content. When
 		// that line is still inside the viewport, moving there and writing `\r` is
@@ -1214,6 +1235,10 @@ export class TUI extends Container {
 				this.#armMultiplexerResizeTimer(options?.clearScrollback === true);
 				return;
 			}
+			// A forced render preempts the post-full-paint ConPTY settle: it owns
+			// the next paint and is going to redraw the buffer anyway, so the
+			// trailing coalesced render queued by the settle would only race it.
+			this.#clearPostFullPaintSettle();
 			this.#prepareForcedRender(options?.clearScrollback === true);
 			this.#renderRequested = true;
 			this.#renderScheduler.scheduleImmediate(() => {
@@ -1226,6 +1251,27 @@ export class TUI extends Container {
 			});
 			return;
 		}
+		// Coalesce non-forced renders inside the post-full-paint ConPTY settle
+		// window into one trailing render. Spinner/blink/streaming components
+		// otherwise fire `requestRender(false)` at 30 Hz while the host is still
+		// catching up with the previous big paint, and each follow-up viewport
+		// repaint nudges Windows Terminal's viewport tracker further off the
+		// last row (see #2095).
+		if (this.#postFullPaintSettleUntilMs > 0) {
+			const now = this.#renderScheduler.now();
+			if (now < this.#postFullPaintSettleUntilMs) {
+				if (this.#postFullPaintSettleTimer === undefined) {
+					this.#postFullPaintSettleTimer = this.#renderScheduler.scheduleRender(() => {
+						this.#postFullPaintSettleTimer = undefined;
+						this.#postFullPaintSettleUntilMs = 0;
+						if (this.#stopped) return;
+						this.requestRender(false);
+					}, this.#postFullPaintSettleUntilMs - now);
+				}
+				return;
+			}
+			this.#postFullPaintSettleUntilMs = 0;
+		}
 		if (this.#renderRequested) return;
 		this.#renderRequested = true;
 		this.#renderScheduler.scheduleImmediate(() => this.#scheduleRender());
@@ -1262,6 +1308,64 @@ export class TUI extends Container {
 			this.requestRender(true, { clearScrollback: deferredClearScrollback });
 		}, TUI.#MULTIPLEXER_RESIZE_DEBOUNCE_MS);
 	}
+
+	/**
+	 * Arm the post-full-paint settle window after an `#emitFullPaint` that
+	 * pushed content into native scrollback on a ConPTY host. Idempotent inside
+	 * the window: a later overflowing paint extends `until` to the later
+	 * deadline so back-to-back big paints do not double-fire the trailing
+	 * coalesced render, and the existing deferred timer is rescheduled to the
+	 * later deadline.
+	 *
+	 * Mid-composition callers (most notably `ImageBudget.endPass()`, which can
+	 * call `requestRender()` from inside the in-flight paint when a new image
+	 * trips the budget) queue their render *before* the settle exists, so they
+	 * fall through the gate and set `#renderRequested` / `#renderTimer` on the
+	 * 30 Hz throttle. Without absorbing those, the throttled follow-up fires
+	 * inside the 150 ms quiet window and reintroduces the cascade the settle
+	 * was meant to stop. Cancel both, then eagerly arm the trailing settle
+	 * timer so the in-flight request still rides one coalesced render at the
+	 * end of the window. See #2095.
+	 */
+	#armPostFullPaintSettle(): void {
+		if (!isConPTYHosted()) return;
+		const until = this.#renderScheduler.now() + TUI.#CONPTY_POST_FULL_PAINT_SETTLE_MS;
+		if (until <= this.#postFullPaintSettleUntilMs) return;
+		this.#postFullPaintSettleUntilMs = until;
+		const hadPendingRender = this.#renderRequested || this.#renderTimer !== undefined;
+		// Reclaim any render that was queued during the in-flight composition:
+		// `#renderRequested` was set before the settle existed and would
+		// otherwise fire on the standard throttle inside the window.
+		this.#renderRequested = false;
+		if (this.#renderTimer) {
+			this.#renderTimer.cancel();
+			this.#renderTimer = undefined;
+		}
+		if (this.#postFullPaintSettleTimer) {
+			this.#postFullPaintSettleTimer.cancel();
+			this.#postFullPaintSettleTimer = undefined;
+		}
+		if (hadPendingRender) {
+			// Replay the absorbed request via the trailing settle timer so the
+			// caller's render still happens — just deferred to the end of the
+			// window. Subsequent `requestRender(false)` calls during the
+			// settle see this timer and fold into it (existing gate at L1263).
+			this.#postFullPaintSettleTimer = this.#renderScheduler.scheduleRender(() => {
+				this.#postFullPaintSettleTimer = undefined;
+				this.#postFullPaintSettleUntilMs = 0;
+				if (this.#stopped) return;
+				this.requestRender(false);
+			}, TUI.#CONPTY_POST_FULL_PAINT_SETTLE_MS);
+		}
+	}
+
+	#clearPostFullPaintSettle(): void {
+		if (this.#postFullPaintSettleTimer) {
+			this.#postFullPaintSettleTimer.cancel();
+			this.#postFullPaintSettleTimer = undefined;
+		}
+		this.#postFullPaintSettleUntilMs = 0;
+	}
 	#prepareForcedRender(clearScrollback: boolean): void {
 		const geometryChanged =
 			(this.#previousWidth > 0 && this.#previousWidth !== this.terminal.columns) ||
@@ -1927,6 +2031,7 @@ export class TUI extends Container {
 					clearViewport: true,
 					clearScrollback: !isMultiplexerSession(),
 				});
+				if (lines.length > height) this.#armPostFullPaintSettle();
 				this.#hasEverRendered = true;
 				return;
 			case "historyRebuild":
@@ -1935,6 +2040,7 @@ export class TUI extends Container {
 					clearViewport: true,
 					clearScrollback: !isMultiplexerSession(),
 				});
+				if (lines.length > height) this.#armPostFullPaintSettle();
 				return;
 			case "overlayRebuild":
 				this.#clearNativeScrollbackDirty();
@@ -1945,6 +2051,7 @@ export class TUI extends Container {
 					clearScrollback: !isMultiplexerSession(),
 				});
 				this.#emitViewportRepaint(lines, width, height, cursorPos);
+				if (baseLines.length > height) this.#armPostFullPaintSettle();
 				return;
 			case "liveRegionPinned":
 				this.#emitLiveRegionPinnedRepaint(