feat(ImageShowTool): use timg for full-res Kitty image, dedup placement

- Replace Jimp-based image loading with timg binary for complete image
processing (decode, scale, encode Kitty protocol) in one subprocess
- Write Kitty sequence directly to terminal fd via fs.writeSync, bypassing
Ink's stdout buffering
- Fix duplicate image placement with three mechanisms:
1. Position dedup: skip write if component hasn't moved
2. Delete-before-write: remove old image with \x1b_Ga=d,d=I,i=ID
3. Remove 500ms polling interval that caused repeated writes
- ImageDisplay now takes pre-generated kittySequence instead of loading
image in the UI component

Co-Authored-By: Claude Big Pickle <noreply@anthropic.com>

src/tools/ImageShowTool/DirectImageDisplay.tsx

@@ -1,176 +0,0 @@
-import fs from "node:fs";
-import React, { useCallback, useEffect, useRef, useState } from "react";
-import { Box } from "../../ink.js";
-import type { DOMElement } from "../../ink.js";
-import { useOnRender } from "../../ink-picture/InkPictureProvider.js";
-import { cursorForward } from "../../ink-picture/utils/ansiEscapes.js";
-import { fetchImage, getPngBuffer } from "../../ink-picture/utils/image.js";
-import generateKittyId from "../../ink-picture/utils/generateKittyId.js";
-import {
-  makeKittyDeletion,
-  makeKittyPlacement,
-  makeKittyTransmitChunks,
-} from "../../ink-picture/renderers/kitty.js";
-import usePosition from "../../ink-picture/hooks/usePosition.js";
-
-/**
- * Direct terminal image display that bypasses Ink's rendering loop.
- *
- * Follows the approach from commit f6a6fdc (old timg):
- * - Writes Kitty protocol directly to process.stdout.fd (not through Ink's stdout)
- * - useEffect fires AFTER Ink's frame write (post-commit), so first placement
- *   runs after Ink's initial output
- * - useOnRender + setTimeout(0) handles re-placement on subsequent renders
- *   (useOnRender fires DURING commit, before Ink writes; setTimeout defers
- *    placement until after)
- * - Periodic re-placement via setInterval combats Ink overwrites from other
- *   re-renders (where our subtree may not re-render)
- * - Renders empty Box placeholder in Ink for correct TUI layout
- */
-export function DirectImageDisplay({
-  src,
-  width,
-  height,
-  pixelWidth,
-  pixelHeight,
-}: {
-  src: string;
-  width: number;
-  height: number;
-  pixelWidth: number;
-  pixelHeight: number;
-}) {
-  const containerRef = useRef<DOMElement | null>(null);
-  const position = usePosition(containerRef);
-
-  const [imageData, setImageData] = useState<Buffer | undefined>(undefined);
-
-  // ── Load image via Jimp ──
-  useEffect(() => {
-    let cancelled = false;
-    (async () => {
-      try {
-        const image = await fetchImage(src);
-        if (!image || cancelled) return;
-        image.cover({ w: pixelWidth, h: pixelHeight });
-        const png = await getPngBuffer(image);
-        if (!cancelled) {
-          setImageData(png.data);
-        }
-      } catch {
-        // Image load failed — nothing to display
-      }
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [src, pixelWidth, pixelHeight]);
-
-  // ── Refs for values used in placement callback (stable identity) ──
-  const imageIdRef = useRef<number | undefined>(undefined);
-  const positionRef = useRef(position);
-  positionRef.current = position;
-  const dimsRef = useRef({ w: width, h: height });
-  dimsRef.current = { w: width, h: height };
-
-  // ── Transmit image data to terminal GPU memory ──
-  // Uses fs.writeSync to bypass Ink's stdout buffering.
-  useEffect(() => {
-    if (!imageData) return;
-
-    const id = generateKittyId();
-    const base64Data = imageData.toString("base64");
-    const chunks = makeKittyTransmitChunks(id, base64Data);
-    const fd = process.stdout.fd;
-    for (const chunk of chunks) {
-      fs.writeSync(fd, chunk);
-    }
-    imageIdRef.current = id;
-  }, [imageData]);
-
-  // ── Place image with position-aware cursor movement ──
-  const placeImage = useCallback(() => {
-    const id = imageIdRef.current;
-    if (!id) return;
-
-    const pos = positionRef.current;
-    if (!pos) return;
-
-    const { w, h } = dimsRef.current;
-    if (h <= 0) return;
-
-    // Calculate cursor-up distance (same logic as cursorUp() in ansiEscapes.ts)
-    // Note: terminalHeight is in character rows (process.stdout.rows),
-    // NOT terminalInfo.terminalHeight which is in pixels.
-    const terminalHeight = process.stdout.rows;
-    const cursorUpCount = pos.appHeight - pos.row;
-    const movementCount =
-      pos.appHeight >= terminalHeight ? cursorUpCount - 1 : cursorUpCount;
-
-    const fd = process.stdout.fd;
-    const parts: Buffer[] = [
-      Buffer.from(`\x1b7`), // save cursor (DECSC)
-    ];
-    if (movementCount > 0) {
-      parts.push(Buffer.from(`\x1b[${movementCount}A`)); // cursor up to image row
-    }
-    parts.push(
-      Buffer.from(`\r`), // carriage return to col 0
-      Buffer.from(cursorForward(pos.col)), // forward to image column
-      Buffer.from(makeKittyPlacement(id, 1, w, h)),
-      Buffer.from(`\x1b8`), // restore cursor (DECRC)
-    );
-    fs.writeSync(fd, Buffer.concat(parts));
-  }, []);
-
-  // ── First placement: after Ink writes its initial frame ──
-  // useEffect fires AFTER React's commit phase (which includes Ink's terminal
-  // output). So calling placeImage() directly here runs after Ink's frame write.
-  useEffect(() => {
-    if (!imageIdRef.current) return;
-    if (!position) return;
-
-    placeImage();
-  }, [imageData, position, placeImage]);
-
-  // ── Re-place after each React render ──
-  // useOnRender fires DURING the commit phase (via Profiler), BEFORE Ink writes
-  // its frame to the terminal. So we use setTimeout(0) to defer the placement
-  // until after Ink's synchronous frame write completes.
-  useOnRender(() => {
-    const id = imageIdRef.current;
-    if (!id) return;
-
-    setTimeout(() => {
-      placeImage();
-    }, 0);
-  });
-
-  // ── Periodic re-placement to combat Ink overwrites from OTHER re-renders ──
-  // When other parts of Codev re-render (e.g. new message arrives), Ink rewrites
-  // the entire frame. Our subtree might not re-render, so useOnRender won't fire.
-  // This interval ensures the image stays visible.
-  useEffect(() => {
-    const interval = setInterval(() => {
-      placeImage();
-    }, 500);
-
-    return () => clearInterval(interval);
-  }, [placeImage]);
-
-  // ── Cleanup: delete image from terminal GPU memory ──
-  useEffect(() => {
-    return () => {
-      const id = imageIdRef.current;
-      if (id) {
-        const fd = process.stdout.fd;
-        fs.writeSync(fd, makeKittyDeletion(id));
-      }
-    };
-  }, []);
-
-  // ── Empty placeholder for correct TUI layout ──
-  // Renders invisible Box with correct height so Ink reserves the right
-  // number of character cells. The actual image is drawn via Kitty protocol.
-  return <Box ref={containerRef} height={height} flexDirection="column" />;
-}

src/tools/ImageShowTool/ImageShowTool.ts

@@ -1,8 +1,10 @@
+import { execFileSync } from 'child_process'
 import { z } from 'zod/v4'
 import { Jimp } from "jimp";
 import { buildTool, type ToolDef } from '../../Tool.js'
 import { loadImageFromUrl } from "../../ink-picture/utils/jimpURL.ts";
 import { lazySchema } from '../../utils/lazySchema.js'
+import { whichSync } from '../../utils/which.js'
 import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
 import { IMAGE_SHOW_TOOL_NAME, DESCRIPTION } from './prompt.js'
 import {
@@ -32,6 +34,7 @@ export interface ImageShowOutput {
   height?: number
   pixelWidth?: number
   pixelHeight?: number
+  kittySequence?: string
 }
 
 // ── Utilities ──
@@ -89,6 +92,7 @@ const outputSchema = lazySchema(() =>
     height: z.number().optional(),
     pixelWidth: z.number().optional(),
     pixelHeight: z.number().optional(),
+    kittySequence: z.string().optional(),
   }),
 )
 type OutputSchema = ReturnType<typeof outputSchema>
@@ -168,11 +172,34 @@ export const ImageShowTool = buildTool({
         cols,
       )
 
+      // Generate full-resolution Kitty protocol sequence via timg
+      let kittySequence: string | undefined
+      try {
+        const timgPath = whichSync('timg')
+        if (timgPath) {
+          // Pipe image to timg via stdin, capture Kitty protocol output
+          const pngBuffer = await image.getBuffer("image/png")
+          kittySequence = execFileSync(
+            timgPath,
+            ['-p', 'kitty', '-g', `${dims.width}x${dims.height}`, '-'],
+            {
+              input: pngBuffer,
+              encoding: 'utf8',
+              timeout: 30000,
+              maxBuffer: 50 * 1024 * 1024,
+            },
+          )
+        }
+      } catch {
+        // timg not available — fall back to text display
+      }
+
       return {
         data: {
           src,
           success: true,
           ...dims,
+          kittySequence,
         } satisfies ImageShowOutput,
       }
     } catch (error) {

src/tools/ImageShowTool/UI.tsx

@@ -1,49 +1,155 @@
-import React, { useMemo } from 'react'
-import { Box, Text } from '../../ink.js'
-import { MessageResponse } from '../../components/MessageResponse.js'
-import { InkPictureProvider } from '../../ink-picture/InkPictureProvider.js'
-import type { ImageShowOutput } from './ImageShowTool.js'
-import { detectTerminalCaps } from './detectTerminal.js'
-import { DirectImageDisplay } from './DirectImageDisplay.js'
+import fs from "node:fs";
+import React, { useCallback, useEffect, useMemo, useRef } from "react";
+import { Box, Text } from "../../ink.js";
+import type { DOMElement } from "../../ink.js";
+import { MessageResponse } from "../../components/MessageResponse.js";
+import { useOnRender, InkPictureProvider } from "../../ink-picture/InkPictureProvider.js";
+import { cursorForward } from "../../ink-picture/utils/ansiEscapes.js";
+import usePosition from "../../ink-picture/hooks/usePosition.js";
+import type { ImageShowOutput } from "./ImageShowTool.js";
+import { detectTerminalCaps } from "./detectTerminal.js";
 
-// ── Image display component ──
-// Follows the old timg approach (commit f6a6fdc):
-// - Writes Kitty protocol directly to the terminal fd (bypassing Ink)
-// - Renders empty placeholder in Ink for correct TUI layout
-// - The image is drawn on the terminal framebuffer without affecting layout
-
-export function ImageDisplay({ src, width, height, pixelWidth, pixelHeight }: {
-  src: string
-  width: number
-  height: number
-  pixelWidth: number
-  pixelHeight: number
+// ── Timg-based image display ──
+// Writes a pre-generated Kitty protocol sequence (from timg) directly to the
+// terminal fd via fs.writeSync, completely bypassing Ink's rendering loop.
+// An empty Box placeholder reserves character cells in Ink's virtual DOM so
+// the TUI layout stays intact — the actual image is drawn on the terminal
+// framebuffer without interference.
+//
+// To prevent duplicate placements (each Kitty protocol write creates a new
+// image at the cursor position):
+//   - Position dedup: skip if the component hasn't moved since last write
+//   - Delete before write: send \x1b_Ga=d,d=I,i=ID to remove old image first
+//   - No periodic polling: remove the 500ms interval that caused duplicates
+
+function TimgDisplay({
+  kittySequence,
+  width,
+  height,
+}: {
+  kittySequence: string;
+  width: number;
+  height: number;
 }) {
-  const terminalInfo = useMemo(() => detectTerminalCaps(), [])
+  const containerRef = useRef<DOMElement | null>(null);
+  const position = usePosition(containerRef);
+
+  // Extract image ID from timg's Kitty sequence: "a=T,i=645096449,..."
+  const imageIdRef = useRef(extractKittyImageId(kittySequence));
+  const positionRef = useRef(position);
+  positionRef.current = position;
+  const dimsRef = useRef({ w: width, h: height });
+  dimsRef.current = { w: width, h: height };
+
+  // ── Dedup: skip if position hasn't changed since last write ──
+  const hasPlacedRef = useRef(false);
+  const lastPosKeyRef = useRef<string | null>(null);
+
+  const displayImage = useCallback(() => {
+    const pos = positionRef.current;
+    if (!pos) return;
+
+    // Skip entirely if image already placed at this exact position
+    const posKey = `${pos.col},${pos.row},${pos.appHeight}`;
+    if (hasPlacedRef.current && posKey === lastPosKeyRef.current) return;
+    lastPosKeyRef.current = posKey;
+
+    const fd = process.stdout.fd;
+    const parts: Buffer[] = [Buffer.from(`\x1b7`)]; // save cursor (DECSC)
 
-  const supportsKittyGraphics = terminalInfo.supportsKittyGraphics === true
+    // Delete previous image before placing new one (prevents duplicates)
+    const imageId = imageIdRef.current;
+    if (hasPlacedRef.current && imageId > 0) {
+      parts.push(Buffer.from(`\x1b_Ga=d,d=I,i=${imageId}\x1b\\`));
+    }
 
-  if (!supportsKittyGraphics) {
+    // Position cursor at the component's row/col
+    const terminalHeight = process.stdout.rows;
+    const cursorUpCount = pos.appHeight - pos.row;
+    const movementCount =
+      pos.appHeight >= terminalHeight ? cursorUpCount - 1 : cursorUpCount;
+    if (movementCount > 0) {
+      parts.push(Buffer.from(`\x1b[${movementCount}A`));
+    }
+    parts.push(
+      Buffer.from(`\r`),
+      Buffer.from(cursorForward(pos.col)),
+    );
+
+    // Full timg sequence (transmit + auto-display at cursor)
+    parts.push(Buffer.from(kittySequence), Buffer.from(`\x1b8`)); // restore cursor
+
+    fs.writeSync(fd, Buffer.concat(parts));
+    hasPlacedRef.current = true;
+  }, [kittySequence]);
+
+  // First display: useEffect fires AFTER Ink's frame write (post-commit)
+  useEffect(() => {
+    if (!position) return;
+    displayImage();
+  }, [kittySequence, position, displayImage]);
+
+  // Re-display on Ink render: useOnRender fires DURING commit (before Ink
+  // writes), so setTimeout(0) defers until after Ink's frame. The dedup
+  // check in displayImage prevents writing if position hasn't changed.
+  useOnRender(() => {
+    setTimeout(() => {
+      displayImage();
+    }, 0);
+  });
+
+  // Empty placeholder for correct TUI layout
+  return <Box ref={containerRef} height={height} flexDirection="column" />;
+}
+
+/** Extract Kitty image ID from a timg-generated protocol sequence. */
+function extractKittyImageId(sequence: string): number {
+  const match = sequence.match(/i=(\d+)/);
+  return match ? parseInt(match[1], 10) : 0;
+}
+
+// ── Image display component ──
+// Uses timg-generated Kitty protocol sequence when available, otherwise
+// falls back to a text-only summary.
+
+export function ImageDisplay({
+  src,
+  width,
+  height,
+  pixelWidth,
+  pixelHeight,
+  kittySequence,
+}: {
+  src: string;
+  width: number;
+  height: number;
+  pixelWidth: number;
+  pixelHeight: number;
+  kittySequence?: string;
+}) {
+  const terminalInfo = useMemo(() => detectTerminalCaps(), []);
+  const supportsKittyGraphics = terminalInfo.supportsKittyGraphics === true;
+
+  if (kittySequence && supportsKittyGraphics) {
     return (
-      <MessageResponse height={1}>
-        <Text dimColor>Image: {src}</Text>
-      </MessageResponse>
-    )
+      <Box flexDirection="column">
+        <InkPictureProvider terminalInfo={terminalInfo}>
+          <TimgDisplay
+            kittySequence={kittySequence}
+            width={width}
+            height={height}
+          />
+        </InkPictureProvider>
+      </Box>
+    );
   }
 
+  // Fallback: text-only summary
   return (
-    <Box flexDirection="column">
-      <InkPictureProvider terminalInfo={terminalInfo}>
-        <DirectImageDisplay
-          src={src}
-          width={width}
-          height={height}
-          pixelWidth={pixelWidth}
-          pixelHeight={pixelHeight}
-        />
-      </InkPictureProvider>
-    </Box>
-  )
+    <MessageResponse height={1}>
+      <Text dimColor>Image: {src}</Text>
+    </MessageResponse>
+  );
 }
 
 // ── Tool rendering functions ──
@@ -52,9 +158,9 @@ export function renderToolUseMessage(
   { src }: { src?: string },
   { verbose }: { theme?: string; verbose: boolean },
 ): React.ReactNode {
-  if (!src) return null
-  if (verbose) return `src: "${src}"`
-  return src
+  if (!src) return null;
+  if (verbose) return `src: "${src}"`;
+  return src;
 }
 
 export function renderToolUseProgressMessage(): React.ReactNode {
@@ -62,7 +168,7 @@ export function renderToolUseProgressMessage(): React.ReactNode {
     <MessageResponse height={1}>
       <Text dimColor>Rendering image…</Text>
     </MessageResponse>
-  )
+  );
 }
 
 export function renderToolResultMessage(
@@ -70,17 +176,17 @@ export function renderToolResultMessage(
   _progressMessages: unknown[],
   { verbose }: { verbose: boolean },
 ): React.ReactNode {
-  const { src, success, width, height, pixelWidth, pixelHeight } = output
+  const { src, success, width, height, pixelWidth, pixelHeight, kittySequence } = output;
 
   if (!success) {
     return (
       <MessageResponse height={1}>
         <Text color="red">Failed to display: {src}</Text>
       </MessageResponse>
-    )
+    );
   }
 
-  // Render the image via ink-picture when we have dimension data
+  // Render the image when we have dimension data
   if (width && height && pixelWidth && pixelHeight) {
     return (
       <ImageDisplay
@@ -89,8 +195,9 @@ export function renderToolResultMessage(
         height={height}
         pixelWidth={pixelWidth}
         pixelHeight={pixelHeight}
+        kittySequence={kittySequence}
       />
-    )
+    );
   }
 
   // Fallback: text-only summary
@@ -100,10 +207,10 @@ export function renderToolResultMessage(
         Image displayed: <Text bold>{src}</Text>
       </Text>
     </MessageResponse>
-  )
+  );
 }
 
 export function getToolUseSummary(input: { src?: string } | undefined): string | null {
-  if (!input?.src) return null
-  return input.src.length > 80 ? input.src.slice(0, 77) + '...' : input.src
+  if (!input?.src) return null;
+  return input.src.length > 80 ? input.src.slice(0, 77) + "..." : input.src;
 }