@oh-my-pi/pi-tui 15.5.13 → 15.5.15

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [15.5.14] - 2026-05-29
+
+### Added
+
+- `Markdown` now renders a small color-chip swatch, painted with the referenced color, in front of CSS hex colors mentioned in prose, thinking traces, lists, tables, and blockquotes (e.g. `#C5FFD6` or `` `#C5FFD6` ``). The chip glyph comes from the theme's symbol set so it degrades across tiers (Nerd Font / Unicode `■` → ASCII `[]`) and is overridable via the `md.colorSwatch` symbol. Truecolor terminals get an exact 24-bit chip; others fall back to the nearest 256-color cell. Bare prose requires a hex letter for 3/4-digit forms so short issue/PR references (`#123`, `#1011`) don't sprout swatches; backticked codes are always treated as colors.
+
+### Fixed
+
+- Fixed the terminal hardware cursor disappearing in Ghostty. `resolveHardwareCursorPreference` force-hid the hardware cursor whenever it detected a Ghostty session (to fight bar-cursor afterimage "trails"), but the editor was simultaneously kept in terminal-cursor (marker-only) mode via `getUseTerminalCursorMarker()`, which renders no glyph and relies on the now-hidden hardware cursor — so Ghostty users had no visible caret at all, regardless of `PI_HARDWARE_CURSOR`. The Ghostty/`PI_FORCE_HARDWARE_CURSOR` override and the redundant `useTerminalCursorMarker` state are removed: `showHardwareCursor` is honored as-requested again (hardware cursor on by default), and disabling it cleanly falls back to the steady software-cursor glyph. The per-paint anti-trail mitigations (hide-cursor + autowrap-off inside the synchronized-output block) are retained, which is the actual trail fix.
+
 ## [15.5.12] - 2026-05-29
 
 ### Fixed

package/dist/types/symbols.d.ts

@@ -19,5 +19,7 @@ export interface SymbolTheme {
     table: BoxSymbols;
     quoteBorder: string;
     hrChar: string;
+    /** Chip glyph drawn (painted with the referenced color) before inline hex colors. */
+    colorSwatch?: string;
     spinnerFrames: string[];
 }

package/dist/types/terminal.d.ts

@@ -27,6 +27,11 @@ export interface Terminal {
     clearScreen(): void;
     setTitle(title: string): void;
     setProgress(active: boolean): void;
+    /**
+     * Returns whether the native terminal viewport is at the scrollback tail when
+     * the host exposes that state. `undefined` means the terminal cannot report it.
+     */
+    isNativeViewportAtBottom?(): boolean | undefined;
     /**
      * Register a callback for terminal appearance (dark/light) changes.
      * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.
@@ -45,6 +50,11 @@ export declare class ProcessTerminal implements Terminal {
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
     start(onInput: (data: string) => void, onResize: () => void): void;
+    /**
+     * Returns true when Windows' active console viewport is at the scrollback tail.
+     * POSIX terminals do not expose native scrollback position through a standard API.
+     */
+    isNativeViewportAtBottom(): boolean | undefined;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     stop(): void;
     write(data: string): void;

package/dist/types/tui.d.ts

@@ -45,6 +45,11 @@ export interface RenderRequestOptions {
     /** Clear terminal scrollback for intentional transcript replacement. */
     clearScrollback?: boolean;
 }
+/** Options for deferred native scrollback rebuild checkpoints. */
+export interface NativeScrollbackRefreshOptions {
+    /** Allow replay when the terminal cannot report viewport state. Use only for explicit user submit checkpoints. */
+    allowUnknownViewport?: boolean;
+}
 /** Type guard to check if a component implements Focusable */
 export declare function isFocusable(component: Component | null): component is Component & Focusable;
 /**
@@ -167,6 +172,6 @@ export declare class TUI extends Container {
      * Callers should only invoke this at checkpoints where the user is expected to be
      * at the terminal bottom, such as after submitting a new prompt.
      */
-    refreshNativeScrollbackIfDirty(): boolean;
+    refreshNativeScrollbackIfDirty(options?: NativeScrollbackRefreshOptions): boolean;
     requestRender(force?: boolean, options?: RenderRequestOptions): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.5.13",
+	"version": "15.5.15",
 	"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.5.13",
-		"@oh-my-pi/pi-utils": "15.5.13",
+		"@oh-my-pi/pi-natives": "15.5.15",
+		"@oh-my-pi/pi-utils": "15.5.15",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/editor.ts

@@ -596,7 +596,9 @@ export class Editor implements Component, Focusable {
 
 	#getStyledInputCursor(): { text: string; width: number } {
 		const cursorChar = this.#theme.symbols.inputCursor;
-		return { text: `\x1b[5m${cursorChar}\x1b[0m`, width: visibleWidth(cursorChar) };
+		// Keep the software cursor steady. Ghostty/cmux can leave visual
+		// afterimages for SGR blink cells during rapid input-row repaints.
+		return { text: cursorChar, width: visibleWidth(cursorChar) };
 	}
 
 	#renderEndOfLineCursorAtWidthLimit(
@@ -1485,19 +1487,7 @@ export class Editor implements Component, Focusable {
 	/** Insert text at the current cursor position */
 	insertText(text: string): void {
 		this.#exitHistoryForEditing();
-		this.#resetKillSequence();
-		this.#recordUndoState();
-
-		const line = this.#state.lines[this.#state.cursorLine] || "";
-		const before = line.slice(0, this.#state.cursorCol);
-		const after = line.slice(this.#state.cursorCol);
-
-		this.#state.lines[this.#state.cursorLine] = before + text + after;
-		this.#setCursorCol(this.#state.cursorCol + text.length);
-
-		if (this.onChange) {
-			this.onChange(this.getText());
-		}
+		this.#insertTextAtCursor(text);
 	}
 
 	// All the editor methods from before...

package/src/components/markdown.ts

@@ -130,6 +130,80 @@ function formatHyperlink(text: string, target: string): string {
 	return `\x1b]8;;${safeTarget}\x07${text}\x1b]8;;\x07`;
 }
 
+// ---------------------------------------------------------------------------
+// Inline hex-color swatches
+// ---------------------------------------------------------------------------
+// When prose/thinking mentions a CSS hex color (e.g. #C5FFD6 or `#C5FFD6`),
+// render a small chip painted with that color just before the code. The chip
+// glyph comes from the theme's symbol set (ASCII → Unicode → Nerd Font), so it
+// degrades gracefully; the color itself is exact 24-bit on truecolor terminals
+// and the nearest 256-color cell otherwise (Bun.color quantizes for us).
+
+/** Fallback chip when the theme supplies no `colorSwatch` symbol (Unicode default). */
+const DEFAULT_COLOR_SWATCH_GLYPH = "■";
+
+// `#` + 3-8 hex digits, not glued to a surrounding word/`#`/`&` (avoids HTML
+// entities like ☃ and paths like foo#fff) and not trailed by more hex
+// (so over-long runs never produce a misleading swatch). Length/letter rules
+// are enforced in classifyHexColor since the alternation can't express "exactly
+// 3, 4, 6, or 8".
+const HEX_COLOR_REGEX = /(?<![\w#&])#([0-9a-fA-F]{3,8})(?![0-9a-fA-F])/g;
+const HEX_COLOR_EXACT_REGEX = /^#([0-9a-fA-F]{3,8})$/;
+
+/**
+ * Decide whether a run of hex digits denotes a renderable CSS color.
+ *
+ * Only the canonical CSS lengths (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) qualify. In
+ * `strict` mode (bare prose) a 3/4-digit run must contain a hex letter, so the
+ * far more common short issue/PR references (#123, #1011) don't sprout swatches.
+ * Codespans opt out of strictness — the backticks already signal "this is a color".
+ */
+function classifyHexColor(hex: string, strict: boolean): boolean {
+	const n = hex.length;
+	if (n !== 3 && n !== 4 && n !== 6 && n !== 8) return false;
+	if (strict && n <= 4 && !/[a-fA-F]/.test(hex)) return false;
+	return true;
+}
+
+/** ANSI-painted `glyph` for `#${hex}`, or "" when the color can't be encoded. */
+function colorSwatch(hex: string, glyph: string): string {
+	const ansi = Bun.color(`#${hex}`, TERMINAL.trueColor ? "ansi-16m" : "ansi-256");
+	// Reset only the foreground (\x1b[39m) so an enclosing background/decoration
+	// applied later by the line renderer survives across the swatch.
+	return ansi ? `${ansi}${glyph}\x1b[39m ` : "";
+}
+
+/**
+ * Style a plain-text run, inserting a color swatch before each hex color it
+ * mentions. Non-color text (including the matched `#hex` itself) is routed
+ * through `applySegment` so the caller's base styling is preserved verbatim.
+ */
+function renderTextWithSwatches(text: string, applySegment: (t: string) => string, glyph: string): string {
+	HEX_COLOR_REGEX.lastIndex = 0;
+	let result = "";
+	let last = 0;
+	for (;;) {
+		const match = HEX_COLOR_REGEX.exec(text);
+		if (match === null) break;
+		if (!classifyHexColor(match[1], true)) continue;
+		const swatch = colorSwatch(match[1], glyph);
+		if (!swatch) continue;
+		if (match.index > last) result += applySegment(text.slice(last, match.index));
+		result += swatch + applySegment(match[0]);
+		last = match.index + match[0].length;
+	}
+	if (last === 0) return applySegment(text);
+	if (last < text.length) result += applySegment(text.slice(last));
+	return result;
+}
+
+/** Swatch for a codespan whose entire content is a single hex color, else "". */
+function codespanSwatch(code: string, glyph: string): string {
+	const match = HEX_COLOR_EXACT_REGEX.exec(code.trim());
+	if (!match || !classifyHexColor(match[1], false)) return "";
+	return colorSwatch(match[1], glyph);
+}
+
 export class Markdown implements Component {
 	#text: string;
 	#paddingX: number; // Left/right padding
@@ -543,6 +617,7 @@ export class Markdown implements Component {
 			const segments: string[] = text.split("\n");
 			return segments.map((segment: string) => applyText(segment)).join("\n");
 		};
+		const swatchGlyph = this.#theme.symbols.colorSwatch || DEFAULT_COLOR_SWATCH_GLYPH;
 
 		for (const token of tokens) {
 			switch (token.type) {
@@ -551,7 +626,7 @@ export class Markdown implements Component {
 					if (token.tokens && token.tokens.length > 0) {
 						result += this.#renderInlineTokens(token.tokens, resolvedStyleContext);
 					} else {
-						result += applyTextWithNewlines(token.text);
+						result += renderTextWithSwatches(token.text, applyTextWithNewlines, swatchGlyph);
 					}
 					break;
 
@@ -572,9 +647,10 @@ export class Markdown implements Component {
 					break;
 				}
 
-				case "codespan":
-					result += this.#theme.code(token.text) + stylePrefix;
+				case "codespan": {
+					result += codespanSwatch(token.text, swatchGlyph) + this.#theme.code(token.text) + stylePrefix;
 					break;
+				}
 
 				case "link": {
 					const linkText = this.#renderInlineTokens(token.tokens || [], resolvedStyleContext);

package/src/symbols.ts

@@ -20,5 +20,7 @@ export interface SymbolTheme {
 	table: BoxSymbols;
 	quoteBorder: string;
 	hrChar: string;
+	/** Chip glyph drawn (painted with the referenced color) before inline hex colors. */
+	colorSwatch?: string;
 	spinnerFrames: string[];
 }

package/src/terminal.ts

@@ -18,6 +18,7 @@ let activeTerminal: ProcessTerminal | null = null;
 let terminalEverStarted = false;
 
 const STD_INPUT_HANDLE = -10;
+const STD_OUTPUT_HANDLE = -11;
 const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
 /**
  * Emergency terminal restore - call this from signal/crash handlers
@@ -92,13 +93,18 @@ export interface Terminal {
 	// Progress indicator (OSC 9;4)
 	setProgress(active: boolean): void;
 
+	/**
+	 * Returns whether the native terminal viewport is at the scrollback tail when
+	 * the host exposes that state. `undefined` means the terminal cannot report it.
+	 */
+	isNativeViewportAtBottom?(): boolean | undefined;
+
 	/**
 	 * Register a callback for terminal appearance (dark/light) changes.
 	 * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.
 	 * Fires when the detected appearance changes, including the initial detection.
 	 */
 	onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
-
 	/** The last detected terminal appearance, or undefined if not yet known. */
 	get appearance(): TerminalAppearance | undefined;
 }
@@ -205,6 +211,33 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
+	/**
+	 * Returns true when Windows' active console viewport is at the scrollback tail.
+	 * POSIX terminals do not expose native scrollback position through a standard API.
+	 */
+	isNativeViewportAtBottom(): boolean | undefined {
+		if (process.platform !== "win32") return undefined;
+		try {
+			const kernel32 = dlopen("kernel32.dll", {
+				GetStdHandle: { args: [FFIType.i32], returns: FFIType.ptr },
+				GetConsoleScreenBufferInfo: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.bool },
+			});
+			try {
+				const handle = kernel32.symbols.GetStdHandle(STD_OUTPUT_HANDLE);
+				const info = new Uint8Array(22);
+				const infoPtr = ptr(info);
+				if (!infoPtr || !kernel32.symbols.GetConsoleScreenBufferInfo(handle, infoPtr)) return undefined;
+				const viewBottom = new DataView(info.buffer, info.byteOffset, info.byteLength).getInt16(16, true);
+				const bufferHeight = new DataView(info.buffer, info.byteOffset, info.byteLength).getInt16(2, true);
+				return viewBottom >= bufferHeight - 1;
+			} finally {
+				kernel32.close();
+			}
+		} catch {
+			return undefined;
+		}
+	}
+
 	/**
 	 * On Windows, add ENABLE_VIRTUAL_TERMINAL_INPUT to the stdin console mode
 	 * so modified keys (for example Shift+Tab) arrive as VT escape sequences.

package/src/tui.ts

@@ -26,6 +26,16 @@ const SEGMENT_RESET = "\x1b[0m";
  * diffing so `#previousLines` mirrors what was actually written.
  */
 const LINE_TERMINATOR = "\x1b[0m\x1b]8;;\x07";
+// Hide the hardware cursor before each paint/move write. Ghostty-style bar
+// cursors can otherwise leave visual afterimages while the TUI repaints the
+// row under a visible cursor. Paint writes also disable terminal autowrap:
+// several terminals keep a "pending wrap" flag after an exact-width row, so a
+// following cursor move can first wrap to the next row and produce staircase
+// trails. The TUI emits explicit CRLFs and restores autowrap before leaving
+// synchronized output mode.
+const HIDE_CURSOR = "\x1b[?25l";
+const PAINT_BEGIN = `${HIDE_CURSOR}\x1b[?2026h\x1b[?7l`;
+const PAINT_END = "\x1b[?7h\x1b[?2026l";
 
 type InputListenerResult = { consume?: boolean; data?: string } | undefined;
 type InputListener = (data: string) => InputListenerResult;
@@ -76,6 +86,11 @@ export interface RenderRequestOptions {
 	clearScrollback?: boolean;
 }
 
+/** Options for deferred native scrollback rebuild checkpoints. */
+export interface NativeScrollbackRefreshOptions {
+	/** Allow replay when the terminal cannot report viewport state. Use only for explicit user submit checkpoints. */
+	allowUnknownViewport?: boolean;
+}
 /** Type guard to check if a component implements Focusable */
 export function isFocusable(component: Component | null): component is Component & Focusable {
 	return component !== null && "focused" in component;
@@ -139,6 +154,15 @@ function isMultiplexerSession(): boolean {
 	return Boolean(Bun.env.TMUX || Bun.env.STY || Bun.env.ZELLIJ);
 }
 
+function requiresNativeViewportProofForReplay(): boolean {
+	return (
+		process.platform === "win32" ||
+		(process.platform === "linux" &&
+			Boolean(Bun.env.WT_SESSION) &&
+			Boolean(Bun.env.WSL_DISTRO_NAME || Bun.env.WSL_INTEROP))
+	);
+}
+
 /**
  * Options for overlay positioning and sizing.
  * Values can be absolute numbers or percentage strings (e.g., "50%").
@@ -242,6 +266,11 @@ export class Container implements Component {
  * - `viewportRepaint`: rewrite the visible viewport in place. If `appendFrom`
  *   is set, emit those tail rows as scrollback growth first so streaming
  *   output reaches terminal history before the corrected viewport is drawn.
+ * - `deferredShrink`: pure content shrink would re-expose rows already in
+ *   native history. Keep row indices stable with blank tail padding, repaint
+ *   only the viewport, and defer the real shorter replay to a checkpoint.
+ * - `deferredMutation`: a row-inserting edit would reindex native scrollback
+ *   while the user is scrolled. Defer all bytes until a safe rebuild checkpoint.
  * - `shrink`: trailing rows were dropped — clear extras inline.
  * - `diff`: differential repaint of visible rows / append new rows below.
  */
@@ -251,6 +280,8 @@ type RenderIntent =
 	| { kind: "sessionReplace" }
 	| { kind: "historyRebuild" }
 	| { kind: "viewportRepaint"; appendFrom?: number }
+	| { kind: "deferredShrink"; paddedLength: number }
+	| { kind: "deferredMutation" }
 	| { kind: "shrink" }
 	| { kind: "diff"; firstChanged: number; lastChanged: number; appendedLines: boolean };
 
@@ -308,9 +339,7 @@ export class TUI extends Container {
 	constructor(terminal: Terminal, showHardwareCursor?: boolean) {
 		super();
 		this.terminal = terminal;
-		if (showHardwareCursor !== undefined) {
-			this.#showHardwareCursor = showHardwareCursor;
-		}
+		this.#showHardwareCursor = showHardwareCursor === undefined ? this.#showHardwareCursor : showHardwareCursor;
 	}
 
 	get fullRedraws(): number {
@@ -634,8 +663,14 @@ export class TUI extends Container {
 	 * Callers should only invoke this at checkpoints where the user is expected to be
 	 * at the terminal bottom, such as after submitting a new prompt.
 	 */
-	refreshNativeScrollbackIfDirty(): boolean {
+	refreshNativeScrollbackIfDirty(options?: NativeScrollbackRefreshOptions): boolean {
 		if (!this.#nativeScrollbackDirty || this.#stopped) return false;
+		const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+		if (
+			!this.#canReplayNativeScrollbackAtCheckpoint(nativeViewportAtBottom, options?.allowUnknownViewport === true)
+		) {
+			return false;
+		}
 		this.#prepareForcedRender(true);
 		this.#renderRequested = false;
 		this.#lastRenderAt = performance.now();
@@ -1131,14 +1166,14 @@ export class TUI extends Container {
 				return;
 			case "sessionReplace":
 				this.#clearScrollbackOnNextRender = false;
-				this.#nativeScrollbackDirty = false;
+				this.#clearNativeScrollbackDirty();
 				this.#emitFullPaint(lines, width, height, cursorPos, {
 					clearViewport: true,
 					clearScrollback: !isMultiplexerSession(),
 				});
 				return;
 			case "historyRebuild":
-				this.#nativeScrollbackDirty = false;
+				this.#clearNativeScrollbackDirty();
 				this.#emitFullPaint(lines, width, height, cursorPos, {
 					clearViewport: true,
 					clearScrollback: !isMultiplexerSession(),
@@ -1150,6 +1185,16 @@ export class TUI extends Container {
 				}
 				this.#emitViewportRepaint(lines, width, height, cursorPos);
 				return;
+			case "deferredMutation":
+				return;
+			case "deferredShrink":
+				this.#emitViewportRepaint(
+					this.#padDeferredShrinkLines(lines, intent.paddedLength),
+					width,
+					height,
+					cursorPos,
+				);
+				return;
 			case "shrink":
 				this.#emitShrink(lines, width, height, cursorPos, prevHardwareCursorRow, prevViewportTop);
 				return;
@@ -1196,14 +1241,19 @@ export class TUI extends Container {
 		// lines were dropped, so no diff is possible. Repaint visible rows only
 		// — emitting the transcript here would duplicate it into scrollback.
 		if (this.#previousLines.length === 0) return { kind: "viewportRepaint" };
+		if (this.#nativeScrollbackDirty && this.#nativeViewportIsAtBottom(this.#readNativeViewportAtBottom())) {
+			return { kind: "historyRebuild" };
+		}
 
 		const diff = this.#diffLines(newLines);
-
 		// Shrink across the viewport boundary: the new transcript would re-expose
 		// rows already committed to native scrollback. A real resize already
 		// reflowed history, so rebuild it now; a pure content shrink (e.g. a
-		// streaming tail cell collapsing) defers the clear+replay so a user
-		// scrolled into history is not yanked to the bottom mid-stream.
+		// streaming tail cell collapsing) defers the clear+replay. When the terminal
+		// can report that the user is scrolled into history, the live repaint keeps
+		// the previous row count with blank tail padding; otherwise cursor-home
+		// repainting rewrites old buffer rows with newly bottom-anchored content,
+		// which looks like a jump upward.
 		const naturalViewportTop = Math.max(0, newLines.length - height);
 		if (
 			diff.firstChanged !== -1 &&
@@ -1211,8 +1261,17 @@ export class TUI extends Container {
 			naturalViewportTop < this.#scrollbackHighWater &&
 			!isMultiplexerSession()
 		) {
-			if (widthChanged || heightChanged) return { kind: "historyRebuild" };
-			this.#nativeScrollbackDirty = true;
+			if (widthChanged || heightChanged) {
+				if (this.#nativeViewportIsScrolled(this.#readNativeViewportAtBottom())) {
+					this.#markNativeScrollbackDirty();
+					return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
+				}
+				return { kind: "historyRebuild" };
+			}
+			this.#markNativeScrollbackDirty();
+			if (this.#nativeViewportIsScrolled(this.#readNativeViewportAtBottom())) {
+				return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
+			}
 			return { kind: "viewportRepaint" };
 		}
 
@@ -1241,12 +1300,26 @@ export class TUI extends Container {
 		// reflowed and the user is at the terminal to resize. Pure appends fall
 		// through to the diff path so the append handler scrolls them into history.
 		if (widthChanged) {
-			if (diff.firstChanged < prevViewportTop) return { kind: "historyRebuild" };
+			if (diff.firstChanged < prevViewportTop) {
+				if (this.#nativeViewportIsScrolled(this.#readNativeViewportAtBottom())) {
+					this.#markNativeScrollbackDirty();
+					return { kind: "viewportRepaint" };
+				}
+				return { kind: "historyRebuild" };
+			}
 			const pureAppend = diff.appendedLines && diff.firstChanged === this.#previousLines.length;
 			if (!pureAppend) return { kind: "viewportRepaint" };
 		}
 
 		const contentGrew = newLines.length > this.#previousLines.length;
+		const pureAppend = diff.appendedLines && diff.firstChanged === this.#previousLines.length;
+		const structuralMutation = newLines.length !== this.#previousLines.length || diff.firstChanged < prevViewportTop;
+		if (!pureAppend && structuralMutation && !isMultiplexerSession()) {
+			if (this.#nativeViewportIsScrolled(this.#readNativeViewportAtBottom())) {
+				this.#markNativeScrollbackDirty();
+				return { kind: "deferredMutation" };
+			}
+		}
 
 		// Height changes shift the visible window. Repaint when content didn't
 		// grow, but skip in Termux (software keyboard toggles height) and inside
@@ -1266,9 +1339,8 @@ export class TUI extends Container {
 			return { kind: "shrink" };
 		}
 
-		// Offscreen edit: viewport repaint corrects the shifted rows. If new
-		// rows also appended in the same frame, emit them as scrollback growth
-		// first so streaming output is not lost from terminal history.
+		// Offscreen edit: viewport repaint corrects shifted rows when the native
+		// viewport is at the tail. Scrolled native-history cases are deferred above.
 		if (diff.firstChanged < prevViewportTop) {
 			const appendFrom = diff.appendedLines ? this.#findAppendedTailStart(newLines) : undefined;
 			return { kind: "viewportRepaint", appendFrom };
@@ -1337,6 +1409,43 @@ export class TUI extends Container {
 		return bestEnd === -1 ? newLines.length : bestEnd + 1;
 	}
 
+	#markNativeScrollbackDirty(): void {
+		this.#nativeScrollbackDirty = true;
+	}
+
+	#clearNativeScrollbackDirty(): void {
+		this.#nativeScrollbackDirty = false;
+	}
+
+	#readNativeViewportAtBottom(): boolean | undefined {
+		return this.terminal.isNativeViewportAtBottom?.();
+	}
+
+	#nativeViewportIsScrolled(nativeViewportAtBottom: boolean | undefined): boolean {
+		return (
+			nativeViewportAtBottom === false ||
+			(nativeViewportAtBottom === undefined && requiresNativeViewportProofForReplay())
+		);
+	}
+
+	#nativeViewportIsAtBottom(nativeViewportAtBottom: boolean | undefined): boolean {
+		return nativeViewportAtBottom === true;
+	}
+
+	#canReplayNativeScrollbackAtCheckpoint(
+		nativeViewportAtBottom: boolean | undefined,
+		allowUnknownViewport: boolean,
+	): boolean {
+		return (
+			nativeViewportAtBottom === true ||
+			(nativeViewportAtBottom === undefined && (allowUnknownViewport || !requiresNativeViewportProofForReplay()))
+		);
+	}
+
+	#padDeferredShrinkLines(lines: string[], paddedLength: number): string[] {
+		if (lines.length >= paddedLength) return lines;
+		return [...lines, ...new Array<string>(paddedLength - lines.length).fill("")];
+	}
 	/**
 	 * Truncate a line to the visible viewport width. Image lines are left
 	 * alone, narrow lines pass through unchanged. Truncation re-appends the
@@ -1376,7 +1485,7 @@ export class TUI extends Container {
 		options: { clearViewport: boolean; clearScrollback: boolean },
 	): void {
 		this.#fullRedrawCount += 1;
-		let buffer = "\x1b[?2026h";
+		let buffer = PAINT_BEGIN;
 		if (options.clearViewport) {
 			buffer += options.clearScrollback ? "\x1b[2J\x1b[H\x1b[3J" : "\x1b[2J\x1b[H";
 		}
@@ -1387,7 +1496,7 @@ export class TUI extends Container {
 		const finalRow = Math.max(0, lines.length - 1);
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, finalRow);
 		buffer += seq;
-		buffer += "\x1b[?2026l";
+		buffer += PAINT_END;
 		this.terminal.write(buffer);
 
 		this.#maxLinesRendered = options.clearViewport ? lines.length : Math.max(this.#maxLinesRendered, lines.length);
@@ -1414,7 +1523,7 @@ export class TUI extends Container {
 	): void {
 		this.#fullRedrawCount += 1;
 		const viewportTop = Math.max(0, lines.length - height);
-		let buffer = "\x1b[?2026h\x1b[H";
+		let buffer = `${PAINT_BEGIN}\x1b[H`;
 		for (let screenRow = 0; screenRow < height; screenRow++) {
 			if (screenRow > 0) buffer += "\r\n";
 			buffer += "\x1b[2K";
@@ -1431,7 +1540,7 @@ export class TUI extends Container {
 		const finalRow = viewportTop + height - 1;
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, finalRow);
 		buffer += seq;
-		buffer += "\x1b[?2026l";
+		buffer += PAINT_END;
 		this.terminal.write(buffer);
 
 		this.#maxLinesRendered = lines.length;
@@ -1452,7 +1561,7 @@ export class TUI extends Container {
 		prevHardwareCursorRow: number,
 	): void {
 		if (start >= lines.length) return;
-		let buffer = "\x1b[?2026h";
+		let buffer = PAINT_BEGIN;
 		// Clamp tracked cursor to the visible viewport bottom — terminals clamp
 		// on resize, so a prior frame may have committed a row that no longer
 		// exists. Without this the scroll math points outside the viewport.
@@ -1464,7 +1573,7 @@ export class TUI extends Container {
 			buffer += "\r\n";
 			buffer += lines[i];
 		}
-		buffer += "\x1b[?2026l";
+		buffer += PAINT_END;
 		this.terminal.write(buffer);
 		const pushedNow = Math.max(0, lines.length - height);
 		if (pushedNow > this.#scrollbackHighWater) {
@@ -1500,7 +1609,7 @@ export class TUI extends Container {
 		const viewportTop = Math.max(0, this.#maxLinesRendered - height);
 		const targetRow = Math.max(0, lines.length - 1);
 
-		let buffer = "\x1b[?2026h";
+		let buffer = PAINT_BEGIN;
 
 		const clampedCursor = Math.min(prevHardwareCursorRow, prevViewportTop + height - 1);
 		const currentScreenRow = clampedCursor - prevViewportTop;
@@ -1525,7 +1634,7 @@ export class TUI extends Container {
 
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, targetRow);
 		buffer += seq;
-		buffer += "\x1b[?2026l";
+		buffer += PAINT_END;
 		this.terminal.write(buffer);
 
 		this.#maxLinesRendered = lines.length;
@@ -1559,7 +1668,7 @@ export class TUI extends Container {
 		const appendStart = appendedLines && firstChanged === this.#previousLines.length && firstChanged > 0;
 		const moveTargetRow = appendStart ? firstChanged - 1 : firstChanged;
 
-		let buffer = "\x1b[?2026h";
+		let buffer = PAINT_BEGIN;
 
 		// Scroll-down branch: target row is past the bottom of the previous
 		// viewport (a pure append). Emit `\r\n`s so the terminal pushes the
@@ -1610,7 +1719,7 @@ export class TUI extends Container {
 
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, finalCursorRow);
 		buffer += seq;
-		buffer += "\x1b[?2026l";
+		buffer += PAINT_END;
 
 		this.#writeDiffDebug(
 			lines,
@@ -1740,6 +1849,6 @@ export class TUI extends Container {
 		}
 		const { seq, toRow } = this.#cursorControlSequence(cursorPos, totalLines, this.#hardwareCursorRow);
 		this.#hardwareCursorRow = toRow;
-		this.terminal.write(`\x1b[?2026h${seq}\x1b[?2026l`);
+		this.terminal.write(`${HIDE_CURSOR}\x1b[?2026h${seq}\x1b[?2026l`);
 	}
 }

package/src/utils.ts

@@ -4,6 +4,7 @@ import {
 	extractSegments as nativeExtractSegments,
 	sliceWithWidth as nativeSliceWithWidth,
 	truncateToWidth as nativeTruncateToWidth,
+	visibleWidth as nativeVisibleWidth,
 	wrapTextWithAnsi as nativeWrapTextWithAnsi,
 	type SliceResult,
 } from "@oh-my-pi/pi-natives";
@@ -96,30 +97,17 @@ export function visibleWidthRaw(str: string): number {
 		return 0;
 	}
 
-	// Fast path: pure ASCII printable
-	let tabLength = 0;
-	const tabWidth = getDefaultTabWidth();
-	let isPureAscii = true;
-	let jamoOvercount = 0;
-	const isMacOS = process.platform === "darwin";
+	// Fast path: printable ASCII has one cell per code unit. Defer every
+	// control/non-ASCII case (tabs, ANSI/OSC, combining marks, CJK) to the
+	// native text engine so all width/slice/wrap helpers share one Unicode
+	// model instead of mixing Bun.stringWidth quirks with Rust truncation.
 	for (let i = 0; i < str.length; i++) {
 		const code = str.charCodeAt(i);
-		if (code === 9) {
-			tabLength += tabWidth;
-		} else if (code < 0x20 || code > 0x7e) {
-			isPureAscii = false;
-			// Hangul Compatibility Jamo (U+3131..U+318E) is EAW=W per UAX#11,
-			// but macOS terminals render them as 1 cell. WezTerm and others
-			// follow UAX#11 at 2 cells. Only correct on macOS.
-			if (isMacOS && code >= 0x3131 && code <= 0x318e) {
-				jamoOvercount++;
-			}
+		if (code < 0x20 || code > 0x7e) {
+			return nativeVisibleWidth(str, getDefaultTabWidth());
 		}
 	}
-	if (isPureAscii) {
-		return str.length + tabLength;
-	}
-	return Bun.stringWidth(str) - jamoOvercount + tabLength;
+	return str.length;
 }
 
 /**