fix: Image note rendered between frames

Author: nexuls

src/components/image-preview.tsx

@@ -14,7 +14,8 @@ import { iconFor } from "../lib/icons";
 import {
 	type DecodedImage,
 	kittyDelete,
-	kittyImage,
+	kittyPut,
+	kittyTransmit,
 	loadImage,
 	pickProtocol,
 } from "../lib/image";
@@ -110,6 +111,19 @@ function cellPixels(renderer: ReturnType<typeof useRenderer>): {
 
 type Cells = { cols: number; rows: number };
 
+// OpenTUI writes every frame through its own serialized output path
+// (renderer.writeOut → native lib.writeOut). Writing kitty escapes via
+// process.stdout instead races that path at the byte level and the sequence
+// can arrive interleaved/corrupt — the image then intermittently fails to
+// show. Route our escapes through the same path so they can't interleave.
+// `writeOut` is internal (not in the public typings) but is the method the
+// renderer uses for all of its own output.
+type RawWriter = { writeOut(chunk: string): void };
+
+function writeRaw(renderer: ReturnType<typeof useRenderer>, seq: string): void {
+	(renderer as unknown as RawWriter).writeOut(seq);
+}
+
 export function ImagePreview({ node }: { node: FileNode }) {
 	const renderer = useRenderer();
 	const containerRef = useRef<BoxRenderable>(null);
@@ -164,34 +178,36 @@ export function ImagePreview({ node }: { node: FileNode }) {
 		};
 	}, [node.path, cells, protocol, renderer]);
 
-	// Kitty path: transmit + display the image over the pane, re-placing it only
-	// when its on-screen geometry changes. Cleanup deletes the image so it
-	// doesn't linger when switching files or unmounting.
+	// Kitty path: transmit the pixels once, display the placement immediately, and
+	// keep the placement in sync as the pane moves. Cleanup deletes the image so
+	// it doesn't linger when switching files or unmounting.
 	useEffect(() => {
 		if (protocol !== "kitty" || !image) return;
-		let currentId: number | null = null;
-		let lastKey = "";
+		const { id, sequence } = kittyTransmit(image);
+		writeRaw(renderer, sequence);
 
 		const place = () => {
 			const box = containerRef.current;
 			if (!box || box.width <= 0 || box.height <= 0) return;
-			const key = `${box.x},${box.y},${box.width},${box.height}`;
-			if (key === lastKey) return;
-			lastKey = key;
-
-			let out = "";
-			if (currentId !== null) out += kittyDelete(currentId);
-			const placed = kittyImage(image);
-			currentId = placed.id;
-			// Save cursor, jump to the pane's top-left (1-based), emit, restore.
-			out += `\x1b7\x1b[${box.y + 1};${box.x + 1}H${placed.sequence}\x1b8`;
-			process.stdout.write(out);
+			// Save cursor, jump to the pane's top-left (1-based), place, restore.
+			writeRaw(
+				renderer,
+				`\x1b7\x1b[${box.y + 1};${box.x + 1}H${kittyPut(id)}\x1b8`,
+			);
 		};
 
+		// Display it now — layout has already settled (the pane was measured before
+		// we got here), so the geometry is valid. We must NOT rely on a FRAME event
+		// to show it: OpenTUI renders on demand and stays idle once the pane
+		// settles, so a frame often never arrives and the image would never appear.
+		// Redrawn cells don't erase kitty images, so one placement keeps it visible;
+		// the FRAME listener only re-places when the pane moves (scroll/resize),
+		// which do trigger renders.
+		place();
 		renderer.on(CliRenderEvents.FRAME, place);
 		return () => {
 			renderer.off(CliRenderEvents.FRAME, place);
-			if (currentId !== null) process.stdout.write(kittyDelete(currentId));
+			writeRaw(renderer, kittyDelete(id));
 		};
 	}, [protocol, image, renderer]);
 

src/components/preview.tsx

@@ -153,8 +153,10 @@ export function Preview({ node }: { node: FileNode }) {
 	}
 
 	// Images read as "binary" (NUL bytes) — render them instead of a placeholder.
+	// Key on the path so switching image→image remounts (fresh decode + display)
+	// rather than reusing the instance, which leaves the previous image on screen.
 	if (preview.kind === "binary" && isImage(node.name)) {
-		return <ImagePreview node={node} />;
+		return <ImagePreview key={node.path} node={node} />;
 	}
 
 	const message =

src/lib/image.ts

@@ -74,11 +74,19 @@ export function pickProtocol(caps: TerminalCapabilities | null): ImageProtocol {
 // ---------------------------------------------------------------------------
 // Kitty graphics protocol
 //
-// We transmit the raw RGBA (f=32), zlib-compressed (o=z), chunked into 4 KiB
-// base64 payloads, and display it at the cursor (a=T) without moving the cursor
-// (C=1). The caller positions the cursor over the preview pane first. Kitty
-// draws the image above the cell background but below glyphs, so it shows
-// through the pane's empty space cells.
+// Transmit and display are split into two steps so the display can be re-asserted
+// cheaply every frame (see ImagePreview):
+//   - kittyTransmit: send the raw RGBA (f=32), zlib-compressed (o=z), chunked into
+//     4 KiB base64 payloads, stored under an image id (a=t) without displaying.
+//   - kittyPut: create/replace a placement of that image (a=p) at the cursor,
+//     without moving the cursor (C=1). Uses a fixed placement id (p=1) so
+//     re-emitting it every frame replaces the placement in place rather than
+//     stacking new ones. The caller positions the cursor over the pane first.
+//
+// Kitty draws the image above the cell background but below glyphs, so it shows
+// through the pane's empty-space cells. Re-asserting the placement each frame
+// makes it self-healing: any redraw/scroll that would otherwise clear it (e.g.
+// the larger repaint when switching between two images) is immediately undone.
 // ---------------------------------------------------------------------------
 
 let nextKittyId = 1;
@@ -88,7 +96,8 @@ export interface KittyImage {
 	sequence: string;
 }
 
-export function kittyImage(img: DecodedImage): KittyImage {
+// Transmit (but don't display) an image, returning its id and the escape bytes.
+export function kittyTransmit(img: DecodedImage): KittyImage {
 	const id = nextKittyId++;
 	const compressed = deflateSync(Buffer.from(img.rgba));
 	const b64 = compressed.toString("base64");
@@ -100,7 +109,7 @@ export function kittyImage(img: DecodedImage): KittyImage {
 		const first = i === 0;
 		const last = i + CHUNK >= b64.length;
 		const control = first
-			? `a=T,f=32,o=z,i=${id},s=${img.width},v=${img.height},C=1,q=2,m=${last ? 0 : 1}`
+			? `a=t,f=32,o=z,i=${id},s=${img.width},v=${img.height},q=2,m=${last ? 0 : 1}`
 			: `m=${last ? 0 : 1}`;
 		parts.push(`\x1b_G${control};${chunk}\x1b\\`);
 	}
@@ -109,6 +118,12 @@ export function kittyImage(img: DecodedImage): KittyImage {
 	return { id, sequence: parts.join("") };
 }
 
+// Create/replace the on-screen placement of a transmitted image at the cursor.
+// Cheap (no pixel data) so it can be re-emitted every frame.
+export function kittyPut(id: number): string {
+	return `\x1b_Ga=p,i=${id},p=1,C=1,q=2\x1b\\`;
+}
+
 // Delete a previously transmitted image (and free its data) by id.
 export function kittyDelete(id: number): string {
 	return `\x1b_Ga=d,d=I,i=${id},q=2\x1b\\`;