refactor: replace custom image rendering with ink-picture across all components

- ImageShowTool: remove jimp/timg rendering, use ink-picture Image component
with auto-detected protocol (Kitty, Sixel, iTerm2, HalfBlock, Braille, ASCII)
- InlineImage: replace manual kitty escape sequences + writeRaw with ink-picture
- Ink runtime: remove dead rawWritesAtRow APC/DCS handling (no longer needed)
- Delete unused utils/terminalImage.ts and utils/kittyProtocol.ts
- tests: expand ImageShowTool test coverage to 29 tests

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

src/components/InlineImage.tsx

@@ -1,26 +1,14 @@
-import React, { useContext, useEffect, useRef, useState } from 'react'
+import React from 'react'
+import Image, { InkPictureProvider } from 'ink-picture'
 import Link from '../ink/components/Link.js'
 import { supportsHyperlinks } from '../ink/supports-hyperlinks.js'
 import { Box, Text } from '../ink.js'
-import { TerminalWriteContext } from '../ink/useTerminalNotification.js'
-import { downloadImage, type CachedImage } from '../utils/imageUrlCache.js'
-import {
-  detectImageProtocol,
-  encodeImageForTerminal,
-  isInsideTmux,
-  type ImageProtocol,
-} from '../utils/terminalImage.js'
 
 type Props = {
   url: string
   alt?: string
 }
 
-type Status = 'loading' | 'ready' | 'error'
-
-/**
- * Extract a display filename from a URL (for fallback text).
- */
 function filenameFromUrl(url: string): string {
   try {
     const pathname = new URL(url).pathname
@@ -33,110 +21,21 @@ function filenameFromUrl(url: string): string {
 }
 
 /**
- * Renders an inline image in the terminal using the Kitty graphics protocol
- * when available. Falls back to a clickable hyperlink for terminals without
- * image protocol support.
+ * Renders an inline image in the terminal using ink-picture, which
+ * auto-detects the best available protocol (Kitty, Sixel, iTerm2,
+ * HalfBlock, Braille, ASCII) and handles loading/error states.
  *
- * Behavior:
- * - loading: dimmed "[Loading image...]" text + tmux passthrough notice
- * - ready + kitty protocol: writes escape sequence via Ink's writeRaw,
- *   shows clickable [Image] link
- * - ready + no protocol: shows clickable link with the URL
- * - error: shows clickable link with plain text fallback
+ * A clickable [image_name] link is shown below the image as a stable
+ * fallback for screen readers and quick URL access.
  */
 export function InlineImage({ url, alt }: Props) {
-  const writeRaw = useContext(TerminalWriteContext)
-  const [status, setStatus] = useState<Status>('loading')
-  const [imageData, setImageData] = useState<CachedImage | null>(null)
-  const [protocol, setProtocol] = useState<ImageProtocol>(() =>
-    detectImageProtocol(),
-  )
-  const protocolRef = useRef(protocol)
-  protocolRef.current = protocol
-  const imageWrittenRef = useRef(false)
-
-  const insideTmux = isInsideTmux()
-
-  // Download image on mount
-  useEffect(() => {
-    let cancelled = false
-
-    setStatus('loading')
-    setImageData(null)
-    setProtocol(detectImageProtocol())
-    imageWrittenRef.current = false
-    console.error(`[InlineImage] Starting download: ${url}`)
-
-    downloadImage(url)
-      .then(result => {
-        if (cancelled) return
-        console.error(`[InlineImage] Download result for ${url}:`, result ? `OK (${result.buffer.length} bytes, ${result.format})` : 'FAILED')
-        if (result) {
-          setImageData(result)
-          setStatus('ready')
-        } else {
-          setStatus('error')
-        }
-      })
-      .catch(err => {
-        if (!cancelled) {
-          console.error(`[InlineImage] Download error for ${url}:`, err)
-          setStatus('error')
-        }
-      })
-
-    return () => {
-      cancelled = true
-    }
-  }, [url])
-
-  // Write terminal image escape sequence via Ink's writeRaw (not raw stdout)
-  // so it stays synchronous with Ink's output and avoids cursor-position races.
-  useEffect(() => {
-    if (status !== 'ready' || !imageData || !protocol || imageWrittenRef.current) return
-
-    const sequence = encodeImageForTerminal(imageData.buffer, imageData.format)
-    if (sequence && writeRaw) {
-      console.error(`[InlineImage] Writing ${imageData.buffer.length} byte ${imageData.format} image via writeRaw`)
-      writeRaw(sequence)
-      imageWrittenRef.current = true
-    } else if (!writeRaw) {
-      console.error(`[InlineImage] writeRaw not available!`)
-    } else {
-      console.error(`[InlineImage] No sequence generated`)
-    }
-  }, [status, imageData, protocol, writeRaw])
-
   const displayName = alt || filenameFromUrl(url)
 
-  // -- Render states --
-
-  // Loading: dimmed placeholder text
-  if (status === 'loading') {
-    if (insideTmux) {
-      return (
-        <Text dimColor>
-          {`[Loading ${displayName}...] (tmux may need allow-passthrough on)`}
-        </Text>
-      )
-    }
-    return <Text dimColor>{`[Loading ${displayName}...]`}</Text>
-  }
-
-  // Error: clickable link or plain text
-  if (status === 'error') {
-    if (supportsHyperlinks()) {
-      return (
-        <Link url={url}>
-          <Text dimColor>{`[${displayName}]`}</Text>
-        </Link>
-      )
-    }
-    return <Text dimColor>{`[${displayName}: ${url}]`}</Text>
-  }
+  const cols = process.stdout.columns ?? 80
+  const rows = process.stdout.rows ?? 40
+  const imgWidth = Math.floor(cols * 0.6)
+  const imgHeight = Math.floor(rows * 0.4)
 
-  // Ready: if we have a protocol and wrote the sequence, render a small label.
-  // The image was already written to the terminal via writeRaw above.
   const link = supportsHyperlinks() ? (
     <Link url={url}>
       <Text dimColor>{`[${displayName}]`}</Text>
@@ -147,10 +46,15 @@ export function InlineImage({ url, alt }: Props) {
 
   return (
     <Box flexDirection="column">
+      <InkPictureProvider>
+        <Image
+          src={url}
+          width={imgWidth}
+          height={imgHeight}
+          alt={alt}
+        />
+      </InkPictureProvider>
       {link}
-      {insideTmux && protocol && (
-        <Text dimColor>{`  ⚠ tmux: add \`set -g allow-passthrough on\` to ~/.tmux.conf`}</Text>
-      )}
     </Box>
   )
 }

src/ink/log-update.ts

@@ -302,9 +302,6 @@ export class LogUpdate {
     let currentStyleId = stylePool.none
     let currentHyperlink: Hyperlink = undefined
 
-    // Track which rows had raw writes emitted to avoid duplicates
-    const emittedRawRows = new Set<number>()
-
     // First pass: render changes to existing rows (rows < prev.screen.height)
     let needsFullReset = false
     let resetTriggerY = -1
@@ -381,24 +378,6 @@ export class LogUpdate {
           return [patches, { dx: 1, dy: 0 }]
         })
       }
-
-      // Emit cursor-hide + bare APC/DCS + cursor-show after cell content
-      // so the native image overlays cell characters with no cursor flicker.
-      // No CUP prefix — the cursor is already at the correct row/column
-      // from moveCursorTo above.
-      if (!emittedRawRows.has(y)) {
-        emittedRawRows.add(y)
-        const rw = next.screen.rawWritesAtRow.get(y)
-        if (rw) {
-          screen.diff.push({
-            type: 'stdout',
-            content: '\x1b[?25l' + rw + '\x1b[?25h',
-          })
-          screen.txn(prev => {
-            return [[], { dx: x - prev.x, dy: y - prev.y }]
-          })
-        }
-      }
     })
     if (needsFullReset) {
       return fullResetSequence_CAUSES_FLICKER(next, 'offscreen', stylePool, {
@@ -429,7 +408,6 @@ export class LogUpdate {
         prev.screen.height,
         next.screen.height,
         stylePool,
-        viewportY,
       )
     }
 
@@ -545,8 +523,6 @@ function renderFrame(
 /**
  * Render a slice of rows from the frame's screen.
  * Each row is rendered followed by a newline. Cursor ends at (0, endY).
- * @param viewportY Number of rows above the viewport (scrollback), for
- *   viewport-adjusted raw write (APC/DCS) CUP positioning.
  */
 function renderFrameSlice(
   screen: VirtualScreen,
@@ -554,7 +530,6 @@ function renderFrameSlice(
   startY: number,
   endY: number,
   stylePool: StylePool,
-  viewportY = 0,
 ): VirtualScreen {
   let currentStyleId = stylePool.none
   let currentHyperlink: Hyperlink = undefined
@@ -635,19 +610,6 @@ function renderFrameSlice(
       currentHyperlink,
       undefined,
     )
-    // Emit cursor-hide + bare APC/DCS + cursor-show after cell content.
-    // The cursor is already at the CR+LF row position — no CUP needed.
-    {
-      const rw = frame.screen.rawWritesAtRow.get(y)
-      if (rw) {
-        screen.diff.push({
-          type: 'stdout',
-          content: '\x1b[?25l' + rw + '\x1b[?25h',
-        })
-        screen.txn(prev => [[], { dx: -prev.x, dy: y - prev.y }])
-      }
-    }
-
     // CR+LF at end of row — \r resets to column 0, \n moves to next line.
     // Without \r, the terminal cursor stays at whatever column content ended
     // (since we skip trailing spaces, this can be mid-row).

src/ink/output.ts

@@ -704,56 +704,29 @@ function writeLineToScreen(
               break
             }
           }
-        } else if (nextChar === '_') {
-          // APC (Application Program Command): store in screen.rawWritesAtRow
-          // for emission by log-update.ts before the row's cell content.
-          // This avoids the screen buffer width limit — APC payloads (e.g.
-          // Kitty base64 images) can be hundreds of KB, but screen rows are
-          // only ~80 columns wide.
-          const apcStartIdx = charIdx
-          charIdx++ // skip past ESC
-          while (charIdx < characters.length - 1) {
-            charIdx++
-            const c = characters[charIdx]?.value
-            if (c === '\x07') break
-            if (c === '\x1b') {
-              const nextC = characters[charIdx + 1]?.value
-              if (nextC === '\\') {
-                charIdx++ // skip backslash
-                break
-              }
-            }
-          }
-          // Reconstruct the full APC sequence from char tokens
-          let apc = ''
-          for (let i = apcStartIdx; i <= charIdx; i++) {
-            const ci = characters[i]
-            if (ci) apc += ci.value
-          }
-          // Append or create raw write entry. Store the bare APC — the
-          // cursor is already at the correct screen-buffer position when
-          // this entry is emitted (via CR+LF in renderFrameSlice or
-          // moveCursorTo in diffEach).
-          const existing = screen.rawWritesAtRow.get(y)
-          if (existing) {
-            screen.rawWritesAtRow.set(y, existing + apc)
-          } else {
-            screen.rawWritesAtRow.set(y, apc)
-          }
         } else if (
           nextChar === ']' ||
           nextChar === 'P' ||
+          nextChar === '_' ||
           nextChar === '^' ||
           nextChar === 'X'
         ) {
-          // String-based sequences (OSC, DCS, PM, SOS) terminated by
-          // BEL (0x07) or ST (ESC \): skip as before.
-          const seqStartIdx = charIdx
+          // String-based sequences terminated by BEL (0x07) or ST (ESC \):
+          // - OSC: ESC ] ... (Operating System Command)
+          // - DCS: ESC P ... (Device Control String)
+          // - APC: ESC _ ... (Application Program Command)
+          // - PM:  ESC ^ ... (Privacy Message)
+          // - SOS: ESC X ... (Start of String)
           charIdx++ // skip the introducer char
           while (charIdx < characters.length - 1) {
             charIdx++
             const c = characters[charIdx]?.value
-            if (c === '\x07') break
+            // BEL (0x07) terminates the sequence
+            if (c === '\x07') {
+              break
+            }
+            // ST (String Terminator) is ESC \
+            // When we see ESC, check if next char is backslash
             if (c === '\x1b') {
               const nextC = characters[charIdx + 1]?.value
               if (nextC === '\\') {
@@ -762,31 +735,6 @@ function writeLineToScreen(
               }
             }
           }
-
-          // Tmux DCS passthrough (\x1bPtmux;...\x1b\\): store the entire
-          // DCS sequence in rawWritesAtRow so tmux forwards the inner APC
-          // to the terminal for native Kitty image rendering.
-          if (
-            nextChar === 'P' &&
-            charIdx + 2 < characters.length &&
-            characters[seqStartIdx + 2]?.value === 't' &&
-            characters[seqStartIdx + 3]?.value === 'm' &&
-            characters[seqStartIdx + 4]?.value === 'u' &&
-            characters[seqStartIdx + 5]?.value === 'x' &&
-            characters[seqStartIdx + 6]?.value === ';' &&
-            characters[charIdx + 1]?.value === '\x1b' &&
-            characters[charIdx + 2]?.value === '\\'
-          ) {
-            // Extend to include outer DCS terminator (\x1b\\)
-            const dcsEnd = charIdx + 2
-            let dcs = ''
-            for (let i = seqStartIdx; i <= dcsEnd; i++) {
-              const ci = characters[i]
-              if (ci) dcs += ci.value
-            }
-            screen.rawWritesAtRow.set(y, dcs)
-            charIdx = dcsEnd
-          }
         } else if (
           nextCode !== undefined &&
           nextCode >= 0x30 &&

src/ink/screen.ts

@@ -391,15 +391,6 @@ export type Screen = Size & {
    */
   noSelect: Uint8Array
 
-  /**
-   * Per-row raw escape sequences (e.g. Kitty protocol APC) that must be
-   * emitted before the row's cell content. Populated by writeLineToScreen
-   * in output.ts when a RawAnsi line starts with \x1b_ (APC). Each entry
-   * already includes CUP positioning: \x1b[row;colH + raw-sequence.
-   * log-update.ts emits these before diffing cells in a row.
-   */
-  rawWritesAtRow: Map<number, string>
-
   /**
    * Per-ROW soft-wrap continuation marker. softWrap[r]=N>0 means row r
    * is a word-wrap continuation of row r-1 (the `\n` before it was
@@ -496,7 +487,6 @@ export function createScreen(
     emptyStyleId: styles.none,
     damage: undefined,
     noSelect: new Uint8Array(size),
-    rawWritesAtRow: new Map(),
     softWrap: new Int32Array(height),
   }
 }
@@ -549,9 +539,8 @@ export function resetScreen(
 
   // Shared pools accumulate — no clearing needed. Unique char/hyperlink sets are bounded.
 
-  // Clear damage tracking and per-row raw writes
+  // Clear damage tracking
   screen.damage = undefined
-  screen.rawWritesAtRow.clear()
 }
 
 /**

src/tools/ImageShowTool/ImageShowTool.tsx

@@ -2,16 +2,10 @@ import { readFile } from 'fs/promises'
 import { homedir } from 'os'
 import React from 'react'
 import { z } from 'zod/v4'
-import Jimp from 'jimp'
-import { RawAnsi, Text } from '../../ink.js'
+import { Text } from '../../ink.js'
 import { buildTool, type ToolDef } from '../../Tool.js'
 import { logForDebugging } from '../../utils/debug.js'
-import {
-  getBestTextProtocol,
-  renderImage,
-  type PixelData,
-  type TextImageProtocol,
-} from '../../utils/imageRenderers.js'
+import Image, { InkPictureProvider } from 'ink-picture'
 
 const IMAGE_TOOL_NAME = 'ImageShow'
 
@@ -117,83 +111,6 @@ async function loadImage(url: string): Promise<{ buffer: Buffer; format: string
   return fetchImage(normalizedUrl)
 }
 
-/**
- * Render an image buffer to an ANSI-escaped string via jimp + text-based
- * protocol (halfBlock / braille / ascii).
- *
- * Pure-JS equivalent of the old renderImageWithTimgSync that used the
- * external `timg` binary.
- *
- * @returns ANSI-escaped string, or null on failure.
- */
-async function renderImageWithJimp(
-  buffer: Buffer,
-  _format: string,
-): Promise<string | null> {
-  try {
-    const cols = process.stdout.columns ?? 80
-    const termRows = process.stdout.rows ?? 40
-    // Use at most half the terminal height so the image doesn't dominate
-    const maxRows = Math.max(10, Math.floor(termRows * 0.5))
-    // Aim for roughly 2:1 cell ratio (cells are ~2x tall)
-    const maxCols = Math.min(cols, Math.round(maxRows * 2))
-
-    // Decode image via jimp
-    const image = await Jimp.read(buffer)
-    const origWidth = image.bitmap.width
-    const origHeight = image.bitmap.height
-
-    // Scale to fit terminal
-    const scale = Math.min(maxCols / origWidth, maxRows / origHeight, 1)
-    const targetWidth = Math.round(origWidth * scale)
-    const targetHeight = Math.round(origHeight * scale)
-
-    image.resize(targetWidth, targetHeight)
-
-    // Extract pixel data
-    const pixelData: PixelData = {
-      data: image.bitmap.data,
-      info: {
-        width: targetWidth,
-        height: targetHeight,
-        channels: 4,
-      },
-    }
-
-    // Detect terminal capabilities and pick the best text protocol
-    const supportsColor = process.env.NO_COLOR === undefined
-    const supportsUnicode = true // modern terminals all support Unicode
-
-    const protocol: TextImageProtocol = getBestTextProtocol({
-      supportsUnicode,
-      supportsColor,
-    })
-
-    logForDebugging(`ImageShow: rendering ${targetWidth}x${targetHeight} via ${protocol}`)
-
-    return renderImage(pixelData, protocol, supportsColor)
-  } catch (err) {
-    logForDebugging(`ImageShow: jimp render error ${err}`)
-    return null
-  }
-}
-
-/**
- * React component that renders ink-picture output within Ink's
- * virtual DOM so Ink knows the image dimensions and the cursor stays
- * in sync with the terminal.
- */
-function ImageDisplay({ output }: { output: string }): React.ReactNode {
-  const lines = output.split('\n').filter(l => l.length > 0)
-  if (lines.length === 0) {
-    return null
-  }
-  // Measure visible width (strip ANSI escape codes)
-  const ansiStrip = (s: string) => s.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
-  const width = Math.max(...lines.map(l => ansiStrip(l).length))
-  return <RawAnsi lines={lines} width={width} />
-}
-
 function getToolUseSummary(input: Partial<Input>): string | null {
   return input?.url ? `Show: ${input.url.split('/').pop() ?? input.url}` : null
 }
@@ -202,9 +119,8 @@ export const ImageShowTool = buildTool({
   name: IMAGE_TOOL_NAME,
   description:
     'Display an image (PNG/JPEG/GIF/WebP) directly in the terminal. ' +
-    'Renders with Unicode-block characters within Ink\'s virtual DOM ' +
-    'so the cursor stays in sync and the image scrolls with conversation content. ' +
-    'Supports both URLs (https://) and local file paths.',
+    'Renders with full-resolution via Kitty Graphics Protocol when supported, ' +
+    'with automatic fallback to text-based rendering (half-block, braille, ascii).',
 
   getToolUseSummary,
   getActivityDescription(input) {
@@ -282,7 +198,8 @@ export const ImageShowTool = buildTool({
     content: {
       success: boolean
       message: string
-      imageOutput?: string
+      src?: string
+      alt?: string
     },
     _progressMessages,
     _options,
@@ -291,8 +208,23 @@ export const ImageShowTool = buildTool({
       return null
     }
 
-    if (content.imageOutput) {
-      return <ImageDisplay output={content.imageOutput} />
+    if (content.src) {
+      const cols = process.stdout.columns ?? 80
+      const rows = process.stdout.rows ?? 40
+      // Reasonable image size: 60% of terminal width, 40% of terminal height
+      const imgWidth = Math.floor(cols * 0.6)
+      const imgHeight = Math.floor(rows * 0.4)
+
+      return (
+        <InkPictureProvider>
+          <Image
+            src={content.src}
+            width={imgWidth}
+            height={imgHeight}
+            alt={content.alt}
+          />
+        </InkPictureProvider>
+      )
     }
 
     return <Text dimColor>{content.message}</Text>
@@ -304,12 +236,22 @@ export const ImageShowTool = buildTool({
       message: string
       imageData?: { base64: string; mediaType: string }
       base64?: string
-      imageOutput?: string
+      src?: string
+      alt?: string
     }
   }> {
     const url = input.url
     const alt = input.alt ?? url.split('/').pop() ?? 'image'
 
+    // Normalize src for ink-picture rendering
+    let src = url
+    if (src.startsWith('~')) {
+      src = src.replace(/^~(?=$|\/)/, homedir())
+    }
+    if (src.startsWith('file://')) {
+      src = src.slice(7)
+    }
+
     logForDebugging(`ImageShow: loading ${url}`)
 
     const result = await loadImage(url)
@@ -336,14 +278,6 @@ export const ImageShowTool = buildTool({
 
     logForDebugging(`ImageShow: loaded ${buffer.length} byte ${format} image`)
 
-    // Render via jimp + text protocol within Ink's virtual DOM.
-    // ImageDisplay in renderToolResultMessage renders the output so Ink
-    // knows the image dimensions and the cursor stays in sync.
-    const imageOutput = await renderImageWithJimp(buffer, format)
-    if (imageOutput) {
-      logForDebugging('ImageShow: generated text-protocol output')
-    }
-
     return {
       data: {
         success: true,
@@ -353,7 +287,8 @@ export const ImageShowTool = buildTool({
           mediaType,
         },
         base64: buffer.toString('base64'),
-        imageOutput,
+        src,
+        alt,
       },
     }
   },

src/tools/ImageShowTool/__tests__/ImageShowTool.test.ts

@@ -0,0 +1,343 @@
+import { describe, it, expect, beforeAll, vi } from 'vitest'
+import { ImageShowTool } from '../ImageShowTool'
+import { readFile } from 'fs/promises'
+import { homedir } from 'os'
+import path from 'path'
+import React from 'react'
+import type { Text } from 'ink'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function getExampleImagePath(): string {
+  const rel = path.join('src', 'ink-picture', 'examples', 'images', 'house.png')
+  return path.resolve(__dirname, '..', '..', '..', '..', rel)
+}
+
+function writeTempPng(): string {
+  // Minimal valid 1x1 red PNG (baked base64)
+  const pngBase64 =
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=='
+  const tmpFile = path.join(
+    process.env.TMPDIR || process.env.TEMP || '/tmp',
+    `imgshow-test-${Date.now()}.png`,
+  )
+  require('fs').writeFileSync(tmpFile, Buffer.from(pngBase64, 'base64'))
+  return tmpFile
+}
+
+// ── Suite ────────────────────────────────────────────────────────────────────
+
+describe('ImageShowTool – comprehensive', () => {
+  let imagePath: string
+
+  beforeAll(async () => {
+    imagePath = getExampleImagePath()
+    const exists = await readFile(imagePath).catch(() => null)
+    expect(exists).not.toBeNull()
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  Metadata
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('metadata', () => {
+    it('has correct name', () => {
+      expect(ImageShowTool.name).toBe('ImageShow')
+    })
+
+    it('is enabled', () => {
+      expect(ImageShowTool.isEnabled()).toBe(true)
+    })
+
+    it('is read only', () => {
+      expect(ImageShowTool.isReadOnly()).toBe(true)
+    })
+
+    it('is concurrency safe', () => {
+      expect(ImageShowTool.isConcurrencySafe()).toBe(true)
+    })
+
+    it('returns a prompt string', async () => {
+      const prompt = await ImageShowTool.prompt({} as any)
+      expect(typeof prompt).toBe('string')
+      expect(prompt.length).toBeGreaterThan(0)
+      expect(prompt.toLowerCase()).toContain('image')
+    })
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  Input validation
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('validateInput', () => {
+    it('accepts a valid local path', async () => {
+      const r = await ImageShowTool.validateInput({ url: imagePath })
+      expect(r.result).toBe(true)
+    })
+
+    it('accepts a remote URL', async () => {
+      const r = await ImageShowTool.validateInput({
+        url: 'https://example.com/img.png',
+      })
+      expect(r.result).toBe(true)
+    })
+
+    it('rejects missing url key', async () => {
+      const r = await ImageShowTool.validateInput({} as any)
+      expect(r.result).toBe(false)
+      expect(r.message).toMatch(/missing/i)
+      expect(r.errorCode).toBe(1)
+    })
+
+    it('rejects undefined input', async () => {
+      const r = await ImageShowTool.validateInput(undefined as any)
+      expect(r.result).toBe(false)
+      expect(r.message).toMatch(/missing/i)
+    })
+
+    it('rejects empty string url', async () => {
+      const r = await ImageShowTool.validateInput({ url: '' })
+      expect(r.result).toBe(false)
+    })
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  call — local files
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('call – local files', () => {
+    it('loads a PNG and returns base64 + metadata', async () => {
+      const result = await ImageShowTool.call({ url: imagePath })
+
+      expect(result.data.success).toBe(true)
+      expect(result.data.message).toContain('house.png')
+
+      // imageData
+      expect(result.data.imageData).toBeDefined()
+      expect(result.data.imageData!.mediaType).toBe('image/png')
+      expect(typeof result.data.imageData!.base64).toBe('string')
+      expect(result.data.imageData!.base64.length).toBeGreaterThan(0)
+
+      // base64 top-level alias
+      expect(result.data.base64).toBe(result.data.imageData!.base64)
+
+      // src – should be the raw file-system path
+      expect(result.data.src).toBe(imagePath)
+
+      // alt – defaults to filename
+      expect(result.data.alt).toBe('house.png')
+    })
+
+    it('handles file:// protocol', async () => {
+      const result = await ImageShowTool.call({ url: `file://${imagePath}` })
+      expect(result.data.success).toBe(true)
+      expect(result.data.imageData!.mediaType).toBe('image/png')
+      // src is normalized (file:// stripped)
+      expect(result.data.src).toBe(imagePath)
+    })
+
+    it('expands ~ to homedir', async () => {
+      // Write a temp PNG in the home dir so the ~ path resolves
+      const home = homedir()
+      const tmpFile = writeTempPng()
+      const homeFile = path.join(home, path.basename(tmpFile))
+      try {
+        require('fs').renameSync(tmpFile, homeFile)
+      } catch {
+        // home dir not writable — skip
+        require('fs').unlinkSync(tmpFile)
+        return
+      }
+
+      const result = await ImageShowTool.call({
+        url: `~/${path.basename(homeFile)}`,
+      })
+      expect(result.data.success).toBe(true)
+
+      // Cleanup
+      try { require('fs').unlinkSync(homeFile) } catch {}
+    })
+
+    it('uses custom alt text', async () => {
+      const result = await ImageShowTool.call({
+        url: imagePath,
+        alt: 'My House',
+      })
+      expect(result.data.alt).toBe('My House')
+    })
+
+    it('fails gracefully for non-existent file', async () => {
+      const result = await ImageShowTool.call({
+        url: '/tmp/__nonexistent_img_test_file__xyz.png',
+      })
+      expect(result.data.success).toBe(false)
+      expect(result.data.message).toMatch(/fail/i)
+    })
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  call — remote URLs
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('call – remote URLs', () => {
+    it('fails gracefully for unreachable URL', async () => {
+      // Temporarily mock fetch to reject quickly
+      const origFetch = globalThis.fetch
+      globalThis.fetch = vi.fn().mockRejectedValue(new Error('fetch failed'))
+      try {
+        const result = await ImageShowTool.call({
+          url: 'https://example.com/img.png',
+        })
+        expect(result.data.success).toBe(false)
+        expect(result.data.message).toMatch(/fail/i)
+      } finally {
+        globalThis.fetch = origFetch
+      }
+    })
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  getToolUseSummary
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('getToolUseSummary', () => {
+    it('returns null for empty input', () => {
+      expect(ImageShowTool.getToolUseSummary({} as any)).toBeNull()
+    })
+
+    it('includes filename from path', () => {
+      const s = ImageShowTool.getToolUseSummary({ url: imagePath })
+      expect(s).toBe(`Show: house.png`)
+    })
+
+    it('includes filename from remote URL', () => {
+      const s = ImageShowTool.getToolUseSummary({
+        url: 'https://example.com/photo.jpg',
+      })
+      expect(s).toBe('Show: photo.jpg')
+    })
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  getActivityDescription
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('getActivityDescription', () => {
+    it('returns generic string without input', () => {
+      expect(ImageShowTool.getActivityDescription({} as any)).toBe(
+        'Showing image',
+      )
+    })
+
+    it('includes URL in description', () => {
+      const d = ImageShowTool.getActivityDescription({ url: imagePath })
+      expect(d).toContain(imagePath)
+    })
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  mapToolResultToToolResultBlockParam
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('mapToolResultToToolResultBlockParam', () => {
+    it('returns image block on success with imageData', () => {
+      const content = {
+        success: true,
+        message: 'ok',
+        imageData: { base64: 'abc123', mediaType: 'image/png' },
+      }
+      const mapped = ImageShowTool.mapToolResultToToolResultBlockParam(
+        content as any,
+        'tool-use-42',
+      )
+      expect(mapped.tool_use_id).toBe('tool-use-42')
+      expect(mapped.content).toHaveLength(1)
+      const block = mapped.content[0]!
+      expect(block.type).toBe('image')
+      if (block.type === 'image') {
+        expect(block.source.type).toBe('base64')
+        expect(block.source.data).toBe('abc123')
+        expect(block.source.media_type).toBe('image/png')
+      }
+    })
+
+    it('returns image block with JPEG type', () => {
+      const content = {
+        success: true,
+        message: 'ok',
+        imageData: { base64: 'xyz', mediaType: 'image/jpeg' },
+      }
+      const mapped = ImageShowTool.mapToolResultToToolResultBlockParam(
+        content as any,
+        'tid',
+      )
+      const block = mapped.content[0]!
+      expect(block.type).toBe('image')
+      if (block.type === 'image') {
+        expect(block.source.media_type).toBe('image/jpeg')
+      }
+    })
+
+    it('returns text block on failure (no imageData)', () => {
+      const content = { success: false, message: 'Failed to load image' }
+      const mapped = ImageShowTool.mapToolResultToToolResultBlockParam(
+        content as any,
+        'tid',
+      )
+      expect(mapped.content).toHaveLength(1)
+      const block = mapped.content[0]!
+      expect(block.type).toBe('text')
+      if (block.type === 'text') {
+        expect(block.text).toBe('Failed to load image')
+      }
+    })
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  renderToolResultMessage
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('renderToolResultMessage', () => {
+    it('returns null when success is false', () => {
+      const node = ImageShowTool.renderToolResultMessage(
+        { success: false, message: 'error' },
+        [],
+        {} as any,
+      )
+      expect(node).toBeNull()
+    })
+
+    it('returns InkPictureProvider/Image element when src is provided', () => {
+      const node = ImageShowTool.renderToolResultMessage(
+        { success: true, message: 'ok', src: imagePath, alt: 'house' },
+        [],
+        {} as any,
+      )
+      expect(node).not.toBeNull()
+      expect(React.isValidElement(node)).toBe(true)
+    })
+
+    it('returns Text element when success but no src', () => {
+      const node = ImageShowTool.renderToolResultMessage(
+        { success: true, message: 'Displayed: house.png' },
+        [],
+        {} as any,
+      )
+      expect(node).not.toBeNull()
+      expect(React.isValidElement(node)).toBe(true)
+    })
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  prompt helper
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('prompt', () => {
+    it('describes supported formats and protocols', async () => {
+      const p = await ImageShowTool.prompt({} as any)
+      expect(p).toMatch(/png|jpeg|gif|webp/i)
+      expect(p).toMatch(/unicode|kitty|terminal/i)
+    })
+  })
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  checkPermissions
+  // ═══════════════════════════════════════════════════════════════════════════
+  describe('checkPermissions', () => {
+    it('always allows', async () => {
+      const r = await ImageShowTool.checkPermissions()
+      expect(r.behavior).toBe('allow')
+    })
+  })
+})

src/utils/terminalImage.ts

@@ -1,273 +0,0 @@
-import { execFileSync } from 'child_process'
-import { mkdtempSync, rmSync, writeFileSync } from 'fs'
-import { tmpdir } from 'os'
-import { join } from 'path'
-import { Buffer } from 'buffer'
-import { env } from './env.js'
-import { execFileNoThrow } from './execFileNoThrow.js'
-import { wrapForMultiplexer } from '../ink/termio/osc.js'
-import { which, whichSync } from './which.js'
-
-export type ImageProtocol = 'kitty' | null
-
-/** Is the terminal inside tmux? */
-export function isInsideTmux(): boolean {
-  return !!process.env.TMUX
-}
-
-const KITTY_IMAGE_CHUNK_SIZE = 4096
-
-// Image format codes for Kitty protocol
-const KITTY_FORMAT_CODES: Record<string, number> = {
-  png: 100,
-  jpeg: 101,
-  jpg: 101,
-  gif: 102,
-  webp: 103,
-}
-
-/**
- * Detect whether the current terminal supports inline image display via
- * the Kitty graphics protocol. Kitty, WezTerm, Konsole, foot, and
- * Ghostty all support it.
- */
-export function supportsImageProtocol(): boolean {
-  return detectImageProtocol() !== null
-}
-
-/**
- * Detect the best available terminal image protocol.
- * Currently only supports the Kitty protocol.
- *
- * Returns `'kitty'` or `null` if no protocol is available.
- */
-export function detectImageProtocol(): ImageProtocol {
-  const term = env.terminal ?? ''
-
-  // Explicit TERM check for Kitty (TERM=xterm-kitty or TERM contains kitty)
-  if (process.env.TERM?.includes('kitty')) return 'kitty'
-  if (process.env.KITTY_WINDOW_ID) return 'kitty'
-
-  // TERM_PROGRAM-based detection
-  switch (term) {
-    case 'kitty':
-    case 'WezTerm':
-    case 'konsole':
-    case 'ghostty':
-    case 'foot':
-      return 'kitty'
-  }
-
-  return null
-}
-
-/**
- * Get the Kitty protocol format code for a given image format string.
- * Defaults to PNG (100) for unknown formats.
- */
-function getKittyFormatCode(format: string): number {
-  return KITTY_FORMAT_CODES[format.toLowerCase()] ?? 100
-}
-
-/**
- * Encode an image buffer into Kitty graphics protocol escape sequences.
- *
- * Large images are split into chunks of KITTY_IMAGE_CHUNK_SIZE bytes
- * to avoid overflowing terminal input buffers.
- *
- * @param buffer - Raw image data
- * @param format - Image format (png, jpeg, gif, webp)
- * @returns Kitty protocol escape sequence
- */
-export function encodeKittyImage(buffer: Buffer, format: string): string {
-  const f = getKittyFormatCode(format)
-  const b64 = buffer.toString('base64')
-  const parts: string[] = []
-
-  if (b64.length <= KITTY_IMAGE_CHUNK_SIZE) {
-    // Single chunk — no splitting needed
-    parts.push(`\x1b_Ga=d,f=${f},m=0;${b64}\x1b\\`)
-  } else {
-    // Split into multiple chunks
-    let offset = 0
-    while (offset < b64.length) {
-      const chunk = b64.slice(offset, offset + KITTY_IMAGE_CHUNK_SIZE)
-      const isLast = offset + KITTY_IMAGE_CHUNK_SIZE >= b64.length
-      parts.push(`\x1b_Ga=d,f=${f},m=${isLast ? 0 : 1};${chunk}\x1b\\`)
-      offset += KITTY_IMAGE_CHUNK_SIZE
-    }
-  }
-
-  const sequence = parts.join('')
-
-  // Wrap for tmux/screen multiplexer passthrough if needed
-  return wrapForMultiplexer(sequence)
-}
-
-/**
- * Generate a terminal image display sequence for an image buffer.
- * Picks the best protocol for the current terminal.
- *
- * @param buffer - Raw image data
- * @param format - Image format (png, jpeg, gif, webp)
- * @returns The escape sequence to write to stdout, or null if no protocol available
- */
-export function encodeImageForTerminal(
-  buffer: Buffer,
-  format: string,
-): string | null {
-  const protocol = detectImageProtocol()
-  if (protocol === 'kitty') {
-    return encodeKittyImage(buffer, format)
-  }
-  return null
-}
-
-/**
- * Image protocol capabilities summary (for debugging/logging).
- */
-export function getImageProtocolSummary(): string {
-  const protocol = detectImageProtocol()
-  if (protocol === 'kitty') return 'kitty'
-  return 'none'
-}
-
-/**
- * Render an image using the `timg` utility with Unicode block characters.
- * Works in any terminal that supports Unicode and 24-bit color (virtually all
- * modern terminals). Falls back gracefully if timg is not installed.
- *
- * The image is rendered using quarter-block characters ("pixelation q") for
- * the best quality-to-compatibility ratio. If timg fails, half-blocks are
- * tried as a fallback.
- *
- * @param buffer - The raw image buffer (decoded)
- * @param format - Image format (png, jpeg, gif, webp)
- * @param columns - Optional terminal width in character columns (auto-detected)
- * @param rows - Optional terminal height in character rows (auto-detected)
- * @returns ANSI escape sequence string for rendering, or null on failure
- */
-export async function renderImageWithTimg(
-  buffer: Buffer,
-  format: string,
-  columns?: number,
-  rows?: number,
-): Promise<string | null> {
-  try {
-    const timgPath = await which('timg')
-    if (!timgPath) return null
-
-    const cols = columns ?? process.stdout.columns ?? 80
-    const termRows = rows ?? process.stdout.rows ?? 40
-    const tmpDir = mkdtempSync(join(tmpdir(), 'codev-timg-'))
-    const ext = format === 'jpeg' ? 'jpg' : format
-    const tmpFile = join(tmpDir, `image.${ext}`)
-    let result: string | null = null
-
-    // Use at most half the terminal height so the image doesn't dominate
-    const maxRows = Math.max(10, Math.floor(termRows * 0.5))
-
-    try {
-      writeFileSync(tmpFile, buffer)
-
-      // Try quarter blocks first (4 pixels per cell, better quality)
-      const quarter = await execFileNoThrow(
-        timgPath,
-        ['-p', 'q', '-g', `${cols}x${maxRows}`, tmpFile],
-        { timeout: 15000, preserveOutputOnError: true },
-      )
-      if (quarter.code === 0 && quarter.stdout) {
-        result = quarter.stdout
-      }
-
-      // Fallback to half blocks (2 pixels per cell, max compatibility)
-      if (!result) {
-        const half = await execFileNoThrow(
-          timgPath,
-          ['-p', 'h', '-g', `${cols}x${maxRows}`, tmpFile],
-          { timeout: 15000, preserveOutputOnError: true },
-        )
-        if (half.code === 0 && half.stdout) {
-          result = half.stdout
-        }
-      }
-    } finally {
-      try {
-        rmSync(tmpDir, { recursive: true, force: true })
-      } catch {
-        // ignore cleanup errors
-      }
-    }
-
-    return result
-  } catch {
-    return null
-  }
-}
-
-/**
- * Synchronous version of renderImageWithTimg. Blocks the event loop while
- * spawning timg, which prevents Ink from rendering between the tool call
- * and the image output — eliminating cursor-position races.
- *
- * @see renderImageWithTimg
- */
-export function renderImageWithTimgSync(
-  buffer: Buffer,
-  format: string,
-  columns?: number,
-  rows?: number,
-): string | null {
-  try {
-    const timgPath = whichSync('timg')
-    if (!timgPath) return null
-
-    const cols = columns ?? process.stdout.columns ?? 80
-    const termRows = rows ?? process.stdout.rows ?? 40
-    const maxRows = Math.max(10, Math.floor(termRows * 0.5))
-    const tmpDir = mkdtempSync(join(tmpdir(), 'codev-timg-'))
-    const ext = format === 'jpeg' ? 'jpg' : format
-    const tmpFile = join(tmpDir, `image.${ext}`)
-    let result: string | null = null
-
-    try {
-      writeFileSync(tmpFile, buffer)
-
-      // Try quarter blocks first (4 pixels per cell, better quality)
-      try {
-        const stdout = execFileSync(
-          timgPath,
-          ['-p', 'q', '-g', `${cols}x${maxRows}`, tmpFile],
-          { encoding: 'utf8', timeout: 15000, maxBuffer: 10 * 1024 * 1024 },
-        )
-        if (stdout) result = stdout
-      } catch {
-        // fall through to half blocks
-      }
-
-      // Fallback to half blocks (2 pixels per cell, max compatibility)
-      if (!result) {
-        try {
-          const stdout = execFileSync(
-            timgPath,
-            ['-p', 'h', '-g', `${cols}x${maxRows}`, tmpFile],
-            { encoding: 'utf8', timeout: 15000, maxBuffer: 10 * 1024 * 1024 },
-          )
-          if (stdout) result = stdout
-        } catch {
-          // ignored
-        }
-      }
-    } finally {
-      try {
-        rmSync(tmpDir, { recursive: true, force: true })
-      } catch {
-        // ignore cleanup errors
-      }
-    }
-
-    return result
-  } catch {
-    return null
-  }
-}