@sayknow-cli/tui 0.3.8 → 0.3.10

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

@@ -47,13 +47,73 @@ export interface ImageRenderOptions {
     maxWidthCells?: number;
     maxHeightCells?: number;
     preserveAspectRatio?: boolean;
+    /**
+     * Kitty-only: stable placement id (`p=`). Re-emitting the same image id +
+     * placement id *replaces* the existing placement instead of stacking a new
+     * copy, which makes diff-renderer repaints idempotent. Callers that render
+     * a persistent component should allocate one id per component instance.
+     */
+    placementId?: number;
+    /**
+     * Kitty-only: stable image id (`i=`). Defaults to a content hash of the
+     * base64 payload ({@link kittyImageId}). Pass a precomputed id to avoid
+     * re-hashing large payloads on every render.
+     */
+    imageId?: number;
+    /**
+     * Kitty-only: sink for the out-of-band data transmission (`a=t`) emitted
+     * the first time an image id is rendered. Defaults to the process-wide
+     * writer configured via {@link setKittyTransmitWriter} (stdout).
+     */
+    onTransmit?: (sequence: string) => void;
 }
+/**
+ * Derive a stable 32-bit non-zero kitty image id (`i=`) from image content
+ * (FNV-1a over the base64 payload). Identical content maps to the same id, so
+ * retransmission replaces the stored image instead of accumulating copies.
+ */
+export declare function kittyImageId(base64Data: string): number;
 export declare function getCellDimensions(): CellDimensions;
 export declare function setCellDimensions(dims: CellDimensions): void;
 export declare function encodeKitty(base64Data: string, options?: {
     columns?: number;
     rows?: number;
     imageId?: number;
+    placementId?: number;
+}): string;
+/** Test hook: forget which kitty image ids were transmitted. */
+export declare function resetKittyTransmissions(): void;
+/**
+ * Override where out-of-band kitty data transmissions (`a=t`) are written.
+ * The default writes directly to stdout: a transmit-only escape is
+ * cursor-neutral (it uploads pixel data without drawing anything), so the
+ * only ordering requirement is that it reaches the terminal before the
+ * placement escape that references it — which the synchronous write during
+ * render guarantees. Tests use this to capture transmissions.
+ */
+export declare function setKittyTransmitWriter(writer: (sequence: string) => void): void;
+/**
+ * Encode a kitty transmit-only (`a=t`) escape: uploads image data under a
+ * stable id without creating a placement. Chunked at 4096 bytes per spec.
+ *
+ * This is deliberately separate from placement: re-sending data (`a=t`/`a=T`)
+ * for an existing image id deletes the image and ALL of its placements, so
+ * data must be uploaded exactly once per id and repaints must go through
+ * {@link encodeKittyPlacement} only.
+ */
+export declare function encodeKittyTransmit(base64Data: string, imageId: number): string;
+/**
+ * Encode a kitty placement-only (`a=p`) escape referencing previously
+ * transmitted data. Re-emitting the same i=/p= pair replaces that one
+ * placement (never stacks, never touches sibling placements), and C=1
+ * keeps the cursor where it is so the escape can be emitted from the
+ * component's first row without cursor-up tricks.
+ */
+export declare function encodeKittyPlacement(options: {
+    imageId: number;
+    placementId: number;
+    columns: number;
+    rows: number;
 }): string;
 export declare function encodeITerm2(base64Data: string, options?: {
     width?: number | string;
@@ -68,8 +128,16 @@ export declare function getJpegDimensions(base64Data: string): ImageDimensions |
 export declare function getGifDimensions(base64Data: string): ImageDimensions | null;
 export declare function getWebpDimensions(base64Data: string): ImageDimensions | null;
 export declare function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null;
-export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): {
+export interface RenderedImage {
     sequence: string;
     rows: number;
-} | null;
+    /**
+     * True when the escape neither moves the cursor nor carries pixel data
+     * (kitty `a=p,C=1` placements). Cursor-neutral sequences can be emitted
+     * from the component's first row; cursor-advancing protocols
+     * (iTerm2/SIXEL) must draw from the last reserved row instead.
+     */
+    cursorNeutral?: boolean;
+}
+export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): RenderedImage | null;
 export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;

package/dist/types/terminal.d.ts

@@ -32,6 +32,7 @@ export interface Terminal {
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     write(data: string): void;
     get available(): boolean;
+    readonly isProcessTerminal?: boolean;
     get columns(): number;
     get rows(): number;
     get kittyProtocolActive(): boolean;
@@ -64,6 +65,7 @@ export declare function resolveTerminalRows(stream?: TerminalSizeStream, envRows
  */
 export declare class ProcessTerminal implements Terminal {
     #private;
+    get isProcessTerminal(): boolean;
     get kittyProtocolActive(): boolean;
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;

package/dist/types/tui.d.ts

@@ -72,6 +72,15 @@ export interface OverlayMargin {
 }
 /** Value that can be absolute (number) or percentage (string like "50%") */
 export type SizeValue = number | `${number}%`;
+/**
+ * True when repainting only the live viewport is safer than clearing/replaying
+ * the full transcript. Native Windows console hosts are included even when
+ * WT_SESSION is absent because PowerShell/ConPTY launch chains can drop terminal
+ * identity variables while keeping the same scroll-jump behavior.
+ */
+export declare function shouldUseViewportRepaintForHost(env?: Record<string, string | undefined>, platform?: NodeJS.Platform, options?: {
+    includeNativeWindows?: boolean;
+}): boolean;
 /**
  * Options for overlay positioning and sizing.
  * Values can be absolute numbers or percentage strings (e.g., "50%").
@@ -190,9 +199,9 @@ export declare class TUI extends Container {
      * `fullRender` path. In terminal multiplexers that path skips the scrollback-clearing
      * `3J` escape (users navigate scrollback history), so replaying every transcript line
      * piles it back on top of scrollback — the "top of screen scrolls down to the prompt at
-     * high speed" resize storm. Windows Terminal can also visibly jump to the
-     * transcript top during streaming redraws, so viewport-repaint sessions keep
-     * force off and let `#doRender` repaint only the live viewport. Set
+     * high speed" resize storm. Windows Terminal/ConPTY can also visibly jump to
+     * the transcript top during streaming redraws, so viewport-repaint sessions
+     * keep force off and let `#doRender` repaint only the live viewport. Set
      * `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy tmux redraw.
      */
     requestResizeRender(): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/tui",
-	"version": "0.3.8",
+	"version": "0.3.10",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.3.8",
-		"@sayknow-cli/utils": "0.3.8",
+		"@sayknow-cli/natives": "0.3.10",
+		"@sayknow-cli/utils": "0.3.10",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/editor.ts

@@ -1914,45 +1914,48 @@ export class Editor implements Component, Focusable {
 	#handlePaste(pastedText: string): void {
 		this.#historyIndex = -1; // Exit history browsing mode
 		this.#resetKillSequence();
-		this.#recordUndoState();
 		const hadAutocomplete = this.#autocompleteState !== null;
 		this.#cancelAutocomplete();
 		if (hadAutocomplete) {
 			this.onAutocompleteUpdate?.();
 		}
 
-		this.#withUndoSuspended(() => {
-			// Some terminals (e.g. tmux popups with extended-keys-format=csi-u) re-encode
-			// control bytes inside bracketed paste as CSI-u Ctrl+<letter> sequences
-			// (ESC [ <codepoint> ; 5 u). Decode those back to their literal byte so the
-			// per-char filter below preserves newlines instead of stripping ESC and
-			// leaking the printable tail (e.g. "[106;5u") into the editor.
-			const decodedText = pastedText.replace(/\x1b\[(\d+);5u/g, (match, code) => {
-				const cp = Number(code);
-				if (cp >= 97 && cp <= 122) return String.fromCharCode(cp - 96);
-				if (cp >= 65 && cp <= 90) return String.fromCharCode(cp - 64);
-				return match;
-			});
+		// Some terminals (e.g. tmux popups with extended-keys-format=csi-u) re-encode
+		// control bytes inside bracketed paste as CSI-u Ctrl+<letter> sequences
+		// (ESC [ <codepoint> ; 5 u). Decode those back to their literal byte so the
+		// per-char filter below preserves newlines instead of stripping ESC and
+		// leaking the printable tail (e.g. "[106;5u") into the editor.
+		const decodedText = pastedText.replace(/\x1b\[(\d+);5u/g, (match, code) => {
+			const cp = Number(code);
+			if (cp >= 97 && cp <= 122) return String.fromCharCode(cp - 96);
+			if (cp >= 65 && cp <= 90) return String.fromCharCode(cp - 64);
+			return match;
+		});
+
+		// Clean the pasted text. NFC-normalize so macOS Finder drag-drops of
+		// Korean filenames (which arrive as NFD: e.g. `ᄒ`+`ᅪ` instead of `화`)
+		// land in the buffer as the same precomposed syllables a terminal
+		// renders — without this, cursor column accounting drifts by
+		// `(NFD cells − NFC cells)` and the visible glyph desyncs from the
+		// hardware cursor. Matches the `Input` component's prior fix; this
+		// is the same fix on the real SKC prompt component (`Editor`).
+		const cleanText = decodedText.replace(/\r\n?/g, "\n").normalize("NFC");
 
-			// Clean the pasted text. NFC-normalize so macOS Finder drag-drops of
-			// Korean filenames (which arrive as NFD: e.g. `ᄒ`+`ᅪ` instead of `화`)
-			// land in the buffer as the same precomposed syllables a terminal
-			// renders — without this, cursor column accounting drifts by
-			// `(NFD cells − NFC cells)` and the visible glyph desyncs from the
-			// hardware cursor. Matches the `Input` component's prior fix; this
-			// is the same fix on the real SKC prompt component (`Editor`).
-			const cleanText = decodedText.replace(/\r\n?/g, "\n").normalize("NFC");
-
-			// Convert tabs to spaces (4 spaces per tab)
-			const tabExpandedText = cleanText.replace(/\t/g, "    ");
-
-			// Filter out non-printable characters except newlines
-			const filteredText = tabExpandedText
-				.split("")
-				.filter(char => char === "\n" || char.charCodeAt(0) >= 32)
-				.join("");
-
-			if (filteredText.length === 0) return;
+		// Convert tabs to spaces (4 spaces per tab)
+		const tabExpandedText = cleanText.replace(/\t/g, "    ");
+
+		// Filter out non-printable characters except newlines
+		const filteredText = tabExpandedText
+			.split("")
+			.filter(char => char === "\n" || char.charCodeAt(0) >= 32)
+			.join("");
+
+		// Nothing survived filtering: the buffer is untouched, so don't record
+		// an undo snapshot — a no-op entry would make the next undo appear dead.
+		if (filteredText.length === 0) return;
+
+		this.#recordUndoState();
+		this.#withUndoSuspended(() => {
 			// Split into lines
 			const pastedLines = filteredText.split("\n");
 

package/src/components/image.ts

@@ -1,12 +1,25 @@
 import {
 	getImageDimensions,
 	type ImageDimensions,
+	ImageProtocol,
 	imageFallback,
+	kittyImageId,
 	renderImage,
 	TERMINAL,
 } from "../terminal-capabilities";
 import type { Component } from "../tui";
 
+// Monotonic placement id allocator (kitty `p=`). Each Image instance keeps a
+// stable placement id so diff-renderer repaints replace its own placement
+// instead of stacking new copies, while two components showing identical
+// content (same image id) still coexist as distinct placements.
+let nextPlacementId = 1;
+function allocatePlacementId(): number {
+	const id = nextPlacementId;
+	nextPlacementId = nextPlacementId >= 0x7fffffff ? 1 : nextPlacementId + 1;
+	return id;
+}
+
 export interface ImageTheme {
 	fallbackColor: (str: string) => string;
 }
@@ -26,6 +39,10 @@ export class Image implements Component {
 
 	#cachedLines?: string[];
 	#cachedWidth?: number;
+	// Kitty graphics: content-derived image id + per-instance placement id.
+	// Computed lazily so non-kitty terminals never pay the hash cost.
+	#kittyImageId?: number;
+	readonly #kittyPlacementId = allocatePlacementId();
 
 	constructor(
 		base64Data: string,
@@ -57,22 +74,39 @@ export class Image implements Component {
 		let lines: string[];
 
 		if (TERMINAL.imageProtocol) {
+			if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
+				this.#kittyImageId ??= kittyImageId(this.#base64Data);
+			}
 			const result = renderImage(this.#base64Data, this.#dimensions, {
 				maxWidthCells: maxWidth,
 				maxHeightCells: this.#options.maxHeightCells,
+				imageId: this.#kittyImageId,
+				placementId: this.#kittyPlacementId,
 			});
 
 			if (result) {
-				// Return `rows` lines so TUI accounts for image height
-				// First (rows-1) lines are empty (TUI clears them)
-				// Last line: move cursor back up, then output image sequence
-				lines = [];
-				for (let i = 0; i < result.rows - 1; i++) {
-					lines.push("");
+				// Return `rows` lines so the TUI accounts for the image height.
+				if (result.cursorNeutral) {
+					// Kitty a=p,C=1 placements neither move the cursor nor carry
+					// pixel data, so the escape lives on the FIRST row — the image
+					// anchors to that cell and no cursor-up trick is needed (the
+					// old CUU approach clamped at the viewport top edge and placed
+					// the image over transcript text when partially scrolled out).
+					lines = [result.sequence];
+					for (let i = 0; i < result.rows - 1; i++) {
+						lines.push("");
+					}
+				} else {
+					// iTerm2/SIXEL draw at the cursor and advance it: reserve
+					// rows-1 blank lines (TUI clears them), then move the cursor
+					// up and draw from the last line.
+					lines = [];
+					for (let i = 0; i < result.rows - 1; i++) {
+						lines.push("");
+					}
+					const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
+					lines.push(moveUp + result.sequence);
 				}
-				// Move cursor up to first row, then output image
-				const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
-				lines.push(moveUp + result.sequence);
 			} else {
 				const fallback = imageFallback(this.#mimeType, this.#dimensions, this.#options.filename);
 				lines = [this.#theme.fallbackColor(fallback)];

package/src/terminal-capabilities.ts

@@ -222,6 +222,40 @@ export interface ImageRenderOptions {
 	maxWidthCells?: number;
 	maxHeightCells?: number;
 	preserveAspectRatio?: boolean;
+	/**
+	 * Kitty-only: stable placement id (`p=`). Re-emitting the same image id +
+	 * placement id *replaces* the existing placement instead of stacking a new
+	 * copy, which makes diff-renderer repaints idempotent. Callers that render
+	 * a persistent component should allocate one id per component instance.
+	 */
+	placementId?: number;
+	/**
+	 * Kitty-only: stable image id (`i=`). Defaults to a content hash of the
+	 * base64 payload ({@link kittyImageId}). Pass a precomputed id to avoid
+	 * re-hashing large payloads on every render.
+	 */
+	imageId?: number;
+	/**
+	 * Kitty-only: sink for the out-of-band data transmission (`a=t`) emitted
+	 * the first time an image id is rendered. Defaults to the process-wide
+	 * writer configured via {@link setKittyTransmitWriter} (stdout).
+	 */
+	onTransmit?: (sequence: string) => void;
+}
+
+/**
+ * Derive a stable 32-bit non-zero kitty image id (`i=`) from image content
+ * (FNV-1a over the base64 payload). Identical content maps to the same id, so
+ * retransmission replaces the stored image instead of accumulating copies.
+ */
+export function kittyImageId(base64Data: string): number {
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < base64Data.length; i++) {
+		hash ^= base64Data.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	hash >>>= 0;
+	return hash === 0 ? 1 : hash;
 }
 
 // Default cell dimensions - updated by TUI when terminal responds to query
@@ -241,6 +275,7 @@ export function encodeKitty(
 		columns?: number;
 		rows?: number;
 		imageId?: number;
+		placementId?: number;
 	} = {},
 ): string {
 	const CHUNK_SIZE = 4096;
@@ -249,7 +284,77 @@ export function encodeKitty(
 
 	if (options.columns) params.push(`c=${options.columns}`);
 	if (options.rows) params.push(`r=${options.rows}`);
-	if (options.imageId) params.push(`i=${options.imageId}`);
+	if (options.imageId) {
+		params.push(`i=${options.imageId}`);
+		// A placement id is only meaningful together with an image id. Same
+		// i= + p= replaces the previous placement (kitty graphics spec), so
+		// re-emitting this sequence never duplicates the image on screen.
+		if (options.placementId) params.push(`p=${options.placementId}`);
+	}
+
+	if (base64Data.length <= CHUNK_SIZE) {
+		return `\x1b_G${params.join(",")};${base64Data}\x1b\\`;
+	}
+
+	const chunks: string[] = [];
+	let offset = 0;
+	let isFirst = true;
+
+	while (offset < base64Data.length) {
+		const chunk = base64Data.slice(offset, offset + CHUNK_SIZE);
+		const isLast = offset + CHUNK_SIZE >= base64Data.length;
+
+		if (isFirst) {
+			chunks.push(`\x1b_G${params.join(",")},m=1;${chunk}\x1b\\`);
+			isFirst = false;
+		} else if (isLast) {
+			chunks.push(`\x1b_Gm=0;${chunk}\x1b\\`);
+		} else {
+			chunks.push(`\x1b_Gm=1;${chunk}\x1b\\`);
+		}
+
+		offset += CHUNK_SIZE;
+	}
+
+	return chunks.join("");
+}
+
+/** Kitty image ids already uploaded to the terminal in this process. */
+const transmittedKittyImageIds = new Set<number>();
+
+/** Test hook: forget which kitty image ids were transmitted. */
+export function resetKittyTransmissions(): void {
+	transmittedKittyImageIds.clear();
+}
+
+let kittyTransmitWriter: (sequence: string) => void = sequence => {
+	process.stdout.write(sequence);
+};
+
+/**
+ * Override where out-of-band kitty data transmissions (`a=t`) are written.
+ * The default writes directly to stdout: a transmit-only escape is
+ * cursor-neutral (it uploads pixel data without drawing anything), so the
+ * only ordering requirement is that it reaches the terminal before the
+ * placement escape that references it — which the synchronous write during
+ * render guarantees. Tests use this to capture transmissions.
+ */
+export function setKittyTransmitWriter(writer: (sequence: string) => void): void {
+	kittyTransmitWriter = writer;
+}
+
+/**
+ * Encode a kitty transmit-only (`a=t`) escape: uploads image data under a
+ * stable id without creating a placement. Chunked at 4096 bytes per spec.
+ *
+ * This is deliberately separate from placement: re-sending data (`a=t`/`a=T`)
+ * for an existing image id deletes the image and ALL of its placements, so
+ * data must be uploaded exactly once per id and repaints must go through
+ * {@link encodeKittyPlacement} only.
+ */
+export function encodeKittyTransmit(base64Data: string, imageId: number): string {
+	const CHUNK_SIZE = 4096;
+	const params = ["a=t", "f=100", "q=2", `i=${imageId}`];
 
 	if (base64Data.length <= CHUNK_SIZE) {
 		return `\x1b_G${params.join(",")};${base64Data}\x1b\\`;
@@ -278,6 +383,22 @@ export function encodeKitty(
 	return chunks.join("");
 }
 
+/**
+ * Encode a kitty placement-only (`a=p`) escape referencing previously
+ * transmitted data. Re-emitting the same i=/p= pair replaces that one
+ * placement (never stacks, never touches sibling placements), and C=1
+ * keeps the cursor where it is so the escape can be emitted from the
+ * component's first row without cursor-up tricks.
+ */
+export function encodeKittyPlacement(options: {
+	imageId: number;
+	placementId: number;
+	columns: number;
+	rows: number;
+}): string {
+	return `\x1b_Ga=p,i=${options.imageId},p=${options.placementId},c=${options.columns},r=${options.rows},C=1,q=2\x1b\\`;
+}
+
 export function encodeITerm2(
 	base64Data: string,
 	options: {
@@ -485,11 +606,23 @@ export function getImageDimensions(base64Data: string, mimeType: string): ImageD
 	return null;
 }
 
+export interface RenderedImage {
+	sequence: string;
+	rows: number;
+	/**
+	 * True when the escape neither moves the cursor nor carries pixel data
+	 * (kitty `a=p,C=1` placements). Cursor-neutral sequences can be emitted
+	 * from the component's first row; cursor-advancing protocols
+	 * (iTerm2/SIXEL) must draw from the last reserved row instead.
+	 */
+	cursorNeutral?: boolean;
+}
+
 export function renderImage(
 	base64Data: string,
 	imageDimensions: ImageDimensions,
 	options: ImageRenderOptions = {},
-): { sequence: string; rows: number } | null {
+): RenderedImage | null {
 	if (!TERMINAL.imageProtocol) {
 		return null;
 	}
@@ -498,11 +631,20 @@ export function renderImage(
 	const fit = calculateImageFit(imageDimensions, options, cellDims);
 
 	if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
-		const sequence = encodeKitty(base64Data, {
-			columns: fit.columns,
-			rows: fit.rows,
-		});
-		return { sequence, rows: fit.rows };
+		const imageId = options.imageId ?? kittyImageId(base64Data);
+		const placementId = options.placementId ?? 1;
+		// Upload data once per image id (out-of-band; the transmit escape is
+		// cursor-neutral), then return only a tiny placement escape. Repaints
+		// re-emit just the placement, which replaces/moves that placement —
+		// re-sending data (a=T/a=t) for an existing id would delete the image
+		// and ALL of its placements (breaking sibling components showing the
+		// same content) and would re-send multi-MB payloads on every repaint.
+		if (!transmittedKittyImageIds.has(imageId)) {
+			transmittedKittyImageIds.add(imageId);
+			(options.onTransmit ?? kittyTransmitWriter)(encodeKittyTransmit(base64Data, imageId));
+		}
+		const sequence = encodeKittyPlacement({ imageId, placementId, columns: fit.columns, rows: fit.rows });
+		return { sequence, rows: fit.rows, cursorNeutral: true };
 	}
 
 	if (TERMINAL.imageProtocol === ImageProtocol.Sixel) {

package/src/terminal.ts

@@ -128,6 +128,9 @@ export interface Terminal {
 	// Whether terminal output is still writable
 	get available(): boolean;
 
+	// True for the real process stdin/stdout terminal (not virtual test terminals).
+	readonly isProcessTerminal?: boolean;
+
 	// Get terminal dimensions
 	get columns(): number;
 	get rows(): number;
@@ -238,6 +241,10 @@ export class ProcessTerminal implements Terminal {
 	#mode2031DebounceTimer?: Timer;
 	#progressTimer?: ReturnType<typeof setInterval>;
 
+	get isProcessTerminal(): boolean {
+		return true;
+	}
+
 	get kittyProtocolActive(): boolean {
 		return this.#kittyProtocolActive;
 	}

package/src/tui.ts

@@ -137,49 +137,83 @@ function parseSizeValue(value: SizeValue | undefined, referenceSize: number): nu
 	return undefined;
 }
 
-function isTermuxSession(): boolean {
-	return Boolean(process.env.TERMUX_VERSION);
+function isTermuxSession(env: Record<string, string | undefined> = Bun.env): boolean {
+	return Boolean(env.TERMUX_VERSION);
 }
 
 const SKC_TMUX_LAUNCHED_ENV = "SKC_TMUX_LAUNCHED";
 const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "no"]);
+const TRUTHY_ENV_VALUES = new Set(["1", "true", "yes", "on", "y"]);
 
 function envIsEnabled(value: string | undefined): boolean {
 	const normalized = value?.trim().toLowerCase();
 	return normalized !== undefined && normalized.length > 0 && !DISABLED_ENV_VALUES.has(normalized);
 }
 
+function envFlagEnabled(value: string | undefined): boolean {
+	const normalized = value?.trim().toLowerCase();
+	return normalized !== undefined && TRUTHY_ENV_VALUES.has(normalized);
+}
+
 function termLooksMultiplexed(value: string | undefined): boolean {
 	const term = value?.trim().toLowerCase() ?? "";
 	return term.startsWith("tmux") || term.startsWith("screen");
 }
 
-function isWindowsTerminalSession(): boolean {
-	return envIsEnabled(Bun.env.WT_SESSION) || Bun.env.TERM_PROGRAM === "Windows_Terminal";
-}
-
-function isViewportRepaintSession(): boolean {
-	return isMultiplexerSession() || isWindowsTerminalSession();
+function isWindowsTerminalSession(env: Record<string, string | undefined> = Bun.env): boolean {
+	return envIsEnabled(env.WT_SESSION) || env.TERM_PROGRAM === "Windows_Terminal";
 }
 
 /** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
-function isMultiplexerSession(): boolean {
+function isMultiplexerSession(env: Record<string, string | undefined> = Bun.env): boolean {
 	return Boolean(
-		envIsEnabled(Bun.env.TMUX) ||
-			envIsEnabled(Bun.env.TMUX_PANE) ||
-			envIsEnabled(Bun.env.STY) ||
-			envIsEnabled(Bun.env.ZELLIJ) ||
-			envIsEnabled(Bun.env[SKC_TMUX_LAUNCHED_ENV]) ||
-			termLooksMultiplexed(Bun.env.TERM),
+		envIsEnabled(env.TMUX) ||
+			envIsEnabled(env.TMUX_PANE) ||
+			envIsEnabled(env.STY) ||
+			envIsEnabled(env.ZELLIJ) ||
+			envIsEnabled(env[SKC_TMUX_LAUNCHED_ENV]) ||
+			termLooksMultiplexed(env.TERM),
+	);
+}
+
+function useLegacyMultiplexerFullRender(env: Record<string, string | undefined> = Bun.env): boolean {
+	return envFlagEnabled(env.PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER);
+}
+
+function isViewportSensitiveHost(
+	env: Record<string, string | undefined>,
+	platform: NodeJS.Platform,
+	includeNativeWindows: boolean,
+): boolean {
+	return isMultiplexerSession(env) || isWindowsTerminalSession(env) || (includeNativeWindows && platform === "win32");
+}
+/**
+ * True when repainting only the live viewport is safer than clearing/replaying
+ * the full transcript. Native Windows console hosts are included even when
+ * WT_SESSION is absent because PowerShell/ConPTY launch chains can drop terminal
+ * identity variables while keeping the same scroll-jump behavior.
+ */
+export function shouldUseViewportRepaintForHost(
+	env: Record<string, string | undefined> = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+	options: { includeNativeWindows?: boolean } = {},
+): boolean {
+	const multiplexed = isMultiplexerSession(env);
+	const includeNativeWindows = options.includeNativeWindows ?? true;
+	return (
+		isViewportSensitiveHost(env, platform, includeNativeWindows) &&
+		!(multiplexed && useLegacyMultiplexerFullRender(env))
 	);
 }
 
-function useLegacyMultiplexerFullRender(): boolean {
-	return $flag("PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER");
+function useViewportRepaintPath(terminal: Terminal): boolean {
+	return shouldUseViewportRepaintForHost(Bun.env, process.platform, {
+		includeNativeWindows: terminal.isProcessTerminal === true,
+	});
 }
 
-function useViewportRepaintPath(): boolean {
-	return isViewportRepaintSession() && !(isMultiplexerSession() && useLegacyMultiplexerFullRender());
+function shouldPreserveScrollbackOnFullClear(terminal: Terminal): boolean {
+	return isViewportSensitiveHost(Bun.env, process.platform, terminal.isProcessTerminal === true);
 }
 
 /**
@@ -530,19 +564,13 @@ export class TUI extends Container {
 		const pageStep = Math.max(1, height - 1);
 		const targetViewportTop = Math.max(0, Math.min(maxViewportTop, currentViewportTop + direction * pageStep));
 
-		if (targetViewportTop >= maxViewportTop) {
-			this.#manualViewportTop = undefined;
-		} else {
-			this.#manualViewportTop = targetViewportTop;
-		}
-
-		const cursorPos = this.#manualViewportTop === undefined ? this.#lastCursorPosition : null;
+		this.#manualViewportTop = targetViewportTop;
 		return this.#repaintViewportFromLines(
 			this.#previousLines,
 			width,
 			height,
 			targetViewportTop,
-			cursorPos,
+			null,
 			"manual viewport scroll",
 		);
 	}
@@ -914,13 +942,13 @@ export class TUI extends Container {
 	 * `fullRender` path. In terminal multiplexers that path skips the scrollback-clearing
 	 * `3J` escape (users navigate scrollback history), so replaying every transcript line
 	 * piles it back on top of scrollback — the "top of screen scrolls down to the prompt at
-	 * high speed" resize storm. Windows Terminal can also visibly jump to the
-	 * transcript top during streaming redraws, so viewport-repaint sessions keep
-	 * force off and let `#doRender` repaint only the live viewport. Set
+	 * high speed" resize storm. Windows Terminal/ConPTY can also visibly jump to
+	 * the transcript top during streaming redraws, so viewport-repaint sessions
+	 * keep force off and let `#doRender` repaint only the live viewport. Set
 	 * `PI_TUI_LEGACY_MULTIPLEXER_FULL_RENDER=1` to restore the legacy tmux redraw.
 	 */
 	requestResizeRender(): void {
-		this.requestRender(!useViewportRepaintPath() && !isTermuxSession(), "resize");
+		this.requestRender(!useViewportRepaintPath(this.terminal) && !isTermuxSession(), "resize");
 	}
 
 	requestRender(force = false, source = "unknown"): void {
@@ -930,7 +958,7 @@ export class TUI extends Container {
 		}
 		if (renderMetrics.enabled) renderMetrics.recordRequest(source);
 		if (force) {
-			const preserveViewportCursor = useViewportRepaintPath();
+			const preserveViewportCursor = useViewportRepaintPath(this.terminal);
 			// A forced full redraw supersedes any queued input-priority render.
 			this.#inputRenderPending = false;
 			this.#previousLines = [];
@@ -1695,9 +1723,8 @@ export class TUI extends Container {
 		if (this.#manualViewportTop !== undefined) {
 			const maxViewportTop = Math.max(0, newLines.length - height);
 			const nextViewportTop = Math.max(0, Math.min(maxViewportTop, this.#manualViewportTop));
-			const followingLive = nextViewportTop >= maxViewportTop;
-			this.#manualViewportTop = followingLive ? undefined : nextViewportTop;
-			const repaintCursorPos = followingLive ? cursorPos : null;
+			this.#manualViewportTop = nextViewportTop;
+			const repaintCursorPos = null;
 			if (
 				this.#repaintViewportFromLines(
 					newLines,
@@ -1719,8 +1746,10 @@ export class TUI extends Container {
 			this.#fullRedrawCount += 1;
 			if (renderMetrics.enabled) renderMetrics.recordFullRedraw(reason);
 			let buffer = "\x1b[?2026h"; // Begin synchronized output
-			// Skip clearing scrollback (3J) in multiplexers — users actively navigate scrollback history
-			if (clear) buffer += isMultiplexerSession() ? "\x1b[2J\x1b[H" : "\x1b[2J\x1b[H\x1b[3J";
+			// Skip clearing scrollback (3J) in hosts where clear/replay can snap the
+			// native viewport away from the live prompt (tmux/screen, Windows ConPTY).
+			if (clear)
+				buffer += shouldPreserveScrollbackOnFullClear(this.terminal) ? "\x1b[2J\x1b[H" : "\x1b[2J\x1b[H\x1b[3J";
 			for (let i = 0; i < newLines.length; i++) {
 				if (i > 0) buffer += "\r\n";
 				// Lines were pre-terminated/normalized by #applyLineResets; image
@@ -1817,7 +1846,7 @@ export class TUI extends Container {
 		// Width changes always need a full re-render because wrapping changes.
 		if (widthChanged) {
 			logRedraw(`terminal width changed (${this.#previousWidth} -> ${width})`);
-			if (useViewportRepaintPath()) {
+			if (useViewportRepaintPath(this.terminal)) {
 				// In viewport-repaint sessions a full replay can either pile the transcript
 				// back onto scrollback (tmux/screen) or visibly jump to the transcript top
 				// (Windows Terminal). Repaint the viewport only, mirroring the height-change
@@ -1833,7 +1862,7 @@ export class TUI extends Container {
 		// but Termux changes height when the software keyboard shows or hides.
 		// In that environment, a full redraw causes the entire history to replay on every toggle.
 		if (heightChanged) {
-			if (useViewportRepaintPath()) {
+			if (useViewportRepaintPath(this.terminal)) {
 				viewportRepaint(`terminal height changed (${this.#previousHeight} -> ${height})`);
 				return;
 			}
@@ -1849,7 +1878,7 @@ export class TUI extends Container {
 		// Configurable via setClearOnShrink() or PI_CLEAR_ON_SHRINK=0 env var
 		if (this.#clearOnShrink && newLines.length < this.#previousLines.length && this.overlayStack.length === 0) {
 			logRedraw(`clearOnShrink (prev=${this.#previousLines.length}, new=${newLines.length})`);
-			if (useViewportRepaintPath()) {
+			if (useViewportRepaintPath(this.terminal)) {
 				viewportRepaint(`clearOnShrink (prev=${this.#previousLines.length}, new=${newLines.length})`);
 			} else {
 				fullRender(true, "clearOnShrink");
@@ -1910,7 +1939,7 @@ export class TUI extends Container {
 				const extraLines = this.#previousLines.length - newLines.length;
 				if (extraLines > height) {
 					logRedraw(`extraLines > height (${extraLines} > ${height})`);
-					if (useViewportRepaintPath()) {
+					if (useViewportRepaintPath(this.terminal)) {
 						viewportRepaint(`extraLines > height (${extraLines} > ${height})`);
 					} else {
 						fullRender(true, "extraLines > height");
@@ -1952,7 +1981,7 @@ export class TUI extends Container {
 		// back to live.
 		if (firstChanged < prevViewportTop) {
 			logRedraw(`firstChanged < viewportTop (${firstChanged} < ${prevViewportTop})`);
-			if (useViewportRepaintPath()) {
+			if (useViewportRepaintPath(this.terminal)) {
 				viewportRepaint(`firstChanged < viewportTop (${firstChanged} < ${prevViewportTop})`);
 				return;
 			}