fix: simplify ImageShowTool to always render timg blocks within Ink's virtual DOM

Remove Kitty protocol/writeRaw bypass that caused TUI cursor corruption and
image display failures. Always render via timg Unicode blocks through RawAnsi
so Ink knows the image dimensions and the cursor stays in sync.

Clean up terminalImage.ts by removing TimgMode, mode parameter, getImageRowsCount,
and tmux TERM_PROGRAM detection that were added in subsequent broken commits.

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

src/tools/ImageShowTool/ImageShowTool.tsx

@@ -1,14 +1,11 @@
 import { readFile } from 'fs/promises'
 import { homedir } from 'os'
-import React, { useContext, useEffect } from 'react'
+import React from 'react'
 import { z } from 'zod/v4'
 import { RawAnsi, Text } from '../../ink.js'
-import { wrapForMultiplexer } from '../../ink/termio/osc.js'
-import { TerminalWriteContext } from '../../ink/useTerminalNotification.js'
 import { buildTool, type ToolDef } from '../../Tool.js'
 import { logForDebugging } from '../../utils/debug.js'
 import {
-  detectImageProtocol,
   renderImageWithTimgSync,
 } from '../../utils/terminalImage.js'
 
@@ -40,46 +37,111 @@ function detectFormat(url: string): string {
   return 'png'
 }
 
-function getToolUseSummary(input: Partial<Input>): string | null {
-  return input?.url ? `Show: ${input.url.split('/').pop() ?? input.url}` : null
+/** Read a local file and return its buffer + detected format */
+async function readLocalImage(url: string): Promise<{ buffer: Buffer; format: string } | null> {
+  try {
+    const format = detectFormat(url)
+    const buffer = await readFile(url)
+    return { buffer, format }
+  } catch {
+    return null
+  }
 }
 
-/**
- * Renders a Kitty-protocol image by writing the escape sequence directly
- * to the terminal via writeRaw, bypassing Ink's virtual DOM. Reserves
- * vertical space with empty RawAnsi lines so Ink doesn't overwrite the
- * image area.
- */
-function KittyImage({
-  kittyOutput,
-  imageRows,
-  offset = 4,
-}: {
-  kittyOutput: string
-  imageRows: number
-  offset?: number
-}) {
-  const writeRaw = useContext(TerminalWriteContext)
-
-  useEffect(() => {
-    if (writeRaw && kittyOutput) {
-      writeRaw(`\x1b[${imageRows + offset}A${kittyOutput}\x1b[${imageRows + offset}B`)
+/** Download an image from URL and return its buffer + detected format */
+async function fetchImage(url: string): Promise<{ buffer: Buffer; format: string } | null> {
+  try {
+    const response = await fetch(url, {
+      headers: {
+        'User-Agent': 'Mozilla/5.0 (compatible; Codev/1.0)',
+      },
+      redirect: 'follow',
+    })
+
+    if (!response.ok) {
+      logForDebugging(`ImageShow: HTTP ${response.status} for ${url}`)
+      return null
     }
-  }, [kittyOutput, imageRows, offset, writeRaw])
 
-  const width = process.stdout.columns ?? 80
-  const lines = new Array<string>(imageRows).fill('')
+    const contentType = response.headers.get('content-type') ?? ''
+    const format = detectFormat(url !== contentType ? url : contentType)
+
+    const reader = response.body?.getReader()
+    if (!reader) return null
+
+    const chunks: Uint8Array[] = []
+    let totalSize = 0
+    const MAX_SIZE = 10_000_000
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      totalSize += value.byteLength
+      if (totalSize > MAX_SIZE) {
+        logForDebugging(`ImageShow: image too large (${totalSize} bytes) for ${url}`)
+        reader.cancel()
+        return null
+      }
+      chunks.push(value)
+    }
+
+    const combinedLength = chunks.reduce((acc, c) => acc + c.byteLength, 0)
+    const combined = new Uint8Array(combinedLength)
+    let offset = 0
+    for (const chunk of chunks) {
+      combined.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+
+    return { buffer: Buffer.from(combined.buffer), format }
+  } catch (err) {
+    logForDebugging(`ImageShow: fetch error ${err} for ${url}`)
+    return null
+  }
+}
+
+/** Load image: local file or remote URL */
+async function loadImage(url: string): Promise<{ buffer: Buffer; format: string } | null> {
+  // Expand ~ to home directory
+  const normalizedUrl = url.startsWith('~')
+    ? url.replace(/^~(?=$|\/)/, homedir())
+    : url
+  if (normalizedUrl.startsWith('file://') || normalizedUrl.startsWith('/') || normalizedUrl.startsWith('.')) {
+    const path = normalizedUrl.startsWith('file://') ? normalizedUrl.slice(7) : normalizedUrl
+    return readLocalImage(path)
+  }
+  return fetchImage(normalizedUrl)
+}
+
+/**
+ * React component that renders timg Unicode-block output within Ink's
+ * virtual DOM so Ink knows the image dimensions and the cursor stays
+ * in sync with the terminal.
+ */
+function TimgDisplay({ output }: { output: string }): React.ReactNode {
+  // Strip cursor hide/show sequences that timg adds
+  const cleaned = output.replace(/\x1b\[\?25[hl]/g, '')
+  const lines = cleaned.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
+}
+
 export const ImageShowTool = buildTool({
   name: IMAGE_TOOL_NAME,
   description:
     'Display an image (PNG/JPEG/GIF/WebP) directly in the terminal. ' +
-    'Uses the Kitty graphics protocol via timg for native quality when the ' +
-    'terminal supports it, with a Unicode-block fallback for universal compatibility. ' +
-    'The block-mode output is rendered within Ink\'s virtual DOM so the cursor ' +
-    'stays in sync and the image scrolls with conversation content.',
+    'Renders with timg 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.',
 
   getToolUseSummary,
   getActivityDescription(input) {
@@ -102,7 +164,7 @@ export const ImageShowTool = buildTool({
   },
 
   async prompt(_options): Promise<string> {
-    return `ImageShow displays a PNG/JPEG/GIF/WebP image directly in the terminal. Uses the Kitty graphics protocol via timg when the terminal supports it (Kitty, Ghostty, WezTerm, foot), or falls back to timg Unicode-block rendering for universal terminal compatibility. Supports local file paths (e.g. /tmp/image.png) and HTTPS URLs (e.g. https://example.com/image.png). The image is shown inline above the tool result.`
+    return `ImageShow displays a PNG/JPEG/GIF/WebP image directly in the terminal using timg Unicode-block rendering. Supports local file paths (e.g. /tmp/image.png) and HTTPS URLs (e.g. https://example.com/image.png). The image is rendered within Ink's virtual DOM so the cursor stays in sync.`
   },
 
   async checkPermissions(): Promise<{ behavior: 'allow' }> {
@@ -157,9 +219,7 @@ export const ImageShowTool = buildTool({
     content: {
       success: boolean
       message: string
-      kittyOutput?: string
       timgOutput?: string
-      imageRows?: number
     },
     _progressMessages,
     _options,
@@ -168,26 +228,8 @@ export const ImageShowTool = buildTool({
       return null
     }
 
-    // Kitty protocol: bypass Ink's virtual DOM via writeRaw and reserve
-    // space with empty RawAnsi lines.
-    if (content.kittyOutput && content.imageRows && content.imageRows > 0) {
-      return (
-        <KittyImage
-          kittyOutput={content.kittyOutput}
-          imageRows={content.imageRows}
-        />
-      )
-    }
-
-    // Block-mode fallback when Kitty protocol is not supported.
     if (content.timgOutput) {
-      const cleaned = content.timgOutput.replace(/\x1b\[\?25[hl]/g, '')
-      const lines = cleaned.split('\n').filter(l => l.length > 0)
-      if (lines.length > 0) {
-        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} />
-      }
+      return <TimgDisplay output={content.timgOutput} />
     }
 
     return <Text dimColor>{content.message}</Text>
@@ -199,8 +241,6 @@ export const ImageShowTool = buildTool({
       message: string
       imageData?: { base64: string; mediaType: string }
       base64?: string
-      format?: string
-      kittyOutput?: string
       timgOutput?: string
     }
   }> {
@@ -209,60 +249,9 @@ export const ImageShowTool = buildTool({
 
     logForDebugging(`ImageShow: loading ${url}`)
 
-    // Expand ~ to home directory for local files
-    const normalizedUrl = url.startsWith('~')
-      ? url.replace(/^~(?=$|\/)/, homedir())
-      : url
-
-    let imgResult: { buffer: Buffer; format: string } | null = null
-
-    if (normalizedUrl.startsWith('file://') || normalizedUrl.startsWith('/') || normalizedUrl.startsWith('.')) {
-      const path = normalizedUrl.startsWith('file://') ? normalizedUrl.slice(7) : normalizedUrl
-      try {
-        const format = detectFormat(path)
-        const buffer = await readFile(path)
-        imgResult = { buffer, format }
-      } catch {
-        // fall through
-      }
-    } else {
-      try {
-        const response = await fetch(normalizedUrl, {
-          headers: { 'User-Agent': 'Mozilla/5.0 (compatible; Codev/1.0)' },
-          redirect: 'follow',
-        })
-        if (response.ok) {
-          const contentType = response.headers.get('content-type') ?? ''
-          const format = detectFormat(normalizedUrl !== contentType ? normalizedUrl : contentType)
-          const reader = response.body?.getReader()
-          if (reader) {
-            const chunks: Uint8Array[] = []
-            let totalSize = 0
-            while (true) {
-              const { done, value } = await reader.read()
-              if (done) break
-              totalSize += value.byteLength
-              if (totalSize > 10_000_000) {
-                reader.cancel()
-                break
-              }
-              chunks.push(value)
-            }
-            const combined = new Uint8Array(chunks.reduce((acc, c) => acc + c.byteLength, 0))
-            let offset = 0
-            for (const chunk of chunks) {
-              combined.set(chunk, offset)
-              offset += chunk.byteLength
-            }
-            imgResult = { buffer: Buffer.from(combined.buffer), format }
-          }
-        }
-      } catch (err) {
-        logForDebugging(`ImageShow: fetch error ${err} for ${normalizedUrl}`)
-      }
-    }
+    const result = await loadImage(url)
 
-    if (!imgResult) {
+    if (!result) {
       return {
         data: {
           success: false,
@@ -271,45 +260,25 @@ export const ImageShowTool = buildTool({
       }
     }
 
-    const { buffer, format } = imgResult
+    const { buffer, format } = result
+
     const mediaType =
-      format === 'jpeg' ? 'image/jpeg'
-        : format === 'gif' ? 'image/gif'
-          : format === 'webp' ? 'image/webp'
+      format === 'jpeg'
+        ? 'image/jpeg'
+        : format === 'gif'
+          ? 'image/gif'
+          : format === 'webp'
+            ? 'image/webp'
             : 'image/png'
 
     logForDebugging(`ImageShow: loaded ${buffer.length} byte ${format} image`)
 
-    // Rendering approach:
-    // 1. Kitty protocol via timg for native-quality display (when supported)
-    // 2. Block-mode via timg as fallback for terminals without Kitty support
-    const protocol = detectImageProtocol()
-    let kittyOutput: string | undefined
-    let timgOutput: string | undefined
-    let imageRows = 0
-
-    if (protocol === 'kitty') {
-      const rawKitty = renderImageWithTimgSync(buffer, format, undefined, undefined, 'kitty')
-      if (rawKitty) {
-        // Pass the raw timg output directly through writeRaw — no need to
-        // strip cursor sequences since writeRaw bypasses Ink's screen buffer.
-        kittyOutput = wrapForMultiplexer(rawKitty.trimEnd())
-        const termRows = process.stdout.rows ?? 40
-        imageRows = Math.max(10, Math.floor(termRows * 0.5))
-        logForDebugging(
-          `ImageShow: generated Kitty protocol output, image rows = ${imageRows}`,
-        )
-      }
-      if (imageRows === 0) {
-        kittyOutput = undefined
-      }
-    }
-
-    if (!kittyOutput) {
-      timgOutput = renderImageWithTimgSync(buffer, format, undefined, undefined, 'blocks') ?? undefined
-      if (timgOutput) {
-        logForDebugging('ImageShow: generated block-mode output via timg')
-      }
+    // Always render via timg Unicode blocks within Ink's virtual DOM.
+    // RawAnsi in renderToolResultMessage renders the output so Ink knows
+    // the image dimensions and the cursor stays in sync.
+    const timgOutput = renderImageWithTimgSync(buffer, format) ?? undefined
+    if (timgOutput) {
+      logForDebugging('ImageShow: generated timg Unicode-block output')
     }
 
     return {
@@ -321,10 +290,7 @@ export const ImageShowTool = buildTool({
           mediaType,
         },
         base64: buffer.toString('base64'),
-        format,
-        kittyOutput,
         timgOutput,
-        imageRows,
       },
     }
   },

src/utils/terminalImage.ts

@@ -58,14 +58,6 @@ export function detectImageProtocol(): ImageProtocol {
       return 'kitty'
   }
 
-  // Inside tmux, TERM_PROGRAM may reveal the host terminal if forwarded
-  if (process.env.TMUX) {
-    const hostTerm = process.env.TERM_PROGRAM ?? ''
-    if (['kitty', 'WezTerm', 'ghostty', 'foot'].includes(hostTerm)) {
-      return 'kitty'
-    }
-  }
-
   return null
 }
 
@@ -141,32 +133,25 @@ export function getImageProtocolSummary(): string {
 }
 
 /**
- * Supported rendering modes for timg-based image display.
- */
-export type TimgMode = 'kitty' | 'blocks'
-
-/**
- * Render an image using the `timg` utility.
- *
- * In `kitty` mode, uses the Kitty graphics protocol for native-quality
- * rendering in terminals that support it.
+ * 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.
  *
- * In `blocks` mode, renders with Unicode quarter-block characters for
- * universal compatibility, falling back to half-blocks if needed.
+ * 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
- * @param rows - Optional terminal height in character rows
- * @param mode - Rendering mode: `'kitty'` or `'blocks'` (default: `'blocks'`)
- * @returns Escape sequence string for rendering, or null on failure
+ * @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,
-  mode: TimgMode = 'blocks',
 ): Promise<string | null> {
   try {
     const timgPath = await which('timg')
@@ -185,37 +170,25 @@ export async function renderImageWithTimg(
     try {
       writeFileSync(tmpFile, buffer)
 
-      if (mode === 'kitty') {
-        // Native Kitty protocol rendering
-        const kitty = await execFileNoThrow(
-          timgPath,
-          ['-p', 'kitty', '-g', `${cols}x${maxRows}`, tmpFile],
-          { timeout: 30000, preserveOutputOnError: true },
-        )
-        if (kitty.code === 0 && kitty.stdout) {
-          result = kitty.stdout
-        }
-      } else {
-        // Try quarter blocks first (4 pixels per cell, better quality)
-        const quarter = await execFileNoThrow(
+      // 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', 'q', '-g', `${cols}x${maxRows}`, tmpFile],
+          ['-p', 'h', '-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
-          }
+        if (half.code === 0 && half.stdout) {
+          result = half.stdout
         }
       }
     } finally {
@@ -232,63 +205,6 @@ export async function renderImageWithTimg(
   }
 }
 
-/**
- * Determine the number of terminal rows an image occupies when rendered.
- * Runs `timg -p q` (block-mode) and counts the output lines.
- * Used to reserve layout space in Ink's virtual DOM when the Kitty
- * protocol is used for native-quality rendering.
- *
- * @param buffer - The raw image buffer
- * @param format - Image format (png, jpeg, gif, webp)
- * @param columns - Optional terminal width in character columns (default: stdout.columns)
- * @returns Number of terminal rows, or 0 on failure
- */
-export function getImageRowsCount(
-  buffer: Buffer,
-  format: string,
-  columns?: number,
-): number {
-  try {
-    const timgPath = whichSync('timg')
-    if (!timgPath) return 0
-
-    const cols = columns ?? process.stdout.columns ?? 80
-    const termRows = process.stdout.rows ?? 40
-    const maxRows = Math.max(10, Math.floor(termRows * 0.5))
-    const tmpDir = mkdtempSync(join(tmpdir(), 'codev-timg-rows-'))
-    const ext = format === 'jpeg' ? 'jpg' : format
-    const tmpFile = join(tmpDir, `image.${ext}`)
-
-    try {
-      writeFileSync(tmpFile, buffer)
-
-      const stdout = execFileSync(
-        timgPath,
-        ['-p', 'q', '-g', `${cols}x${maxRows}`, tmpFile],
-        { encoding: 'utf8', timeout: 15000, maxBuffer: 10 * 1024 * 1024 },
-      )
-
-      // Count non-empty lines; strip ANSI escape sequences first so we
-      // only count lines that actually contain block-mode content.
-      const lines = stdout
-        .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
-        .replace(/\x1b\[?25[hl]/g, '')
-        .split('\n')
-        .filter(l => l.trim().length > 0)
-
-      return lines.length
-    } finally {
-      try {
-        rmSync(tmpDir, { recursive: true, force: true })
-      } catch {
-        // ignore cleanup errors
-      }
-    }
-  } catch {
-    return 0
-  }
-}
-
 /**
  * Synchronous version of renderImageWithTimg. Blocks the event loop while
  * spawning timg, which prevents Ink from rendering between the tool call
@@ -301,7 +217,6 @@ export function renderImageWithTimgSync(
   format: string,
   columns?: number,
   rows?: number,
-  mode: TimgMode = 'blocks',
 ): string | null {
   try {
     const timgPath = whichSync('timg')
@@ -318,43 +233,29 @@ export function renderImageWithTimgSync(
     try {
       writeFileSync(tmpFile, buffer)
 
-      if (mode === 'kitty') {
-        // Native Kitty protocol rendering
-        try {
-          const stdout = execFileSync(
-            timgPath,
-            ['-p', 'kitty', '-g', `${cols}x${maxRows}`, tmpFile],
-            { encoding: 'utf8', timeout: 30000, maxBuffer: 50 * 1024 * 1024 },
-          )
-          if (stdout) result = stdout
-        } catch {
-          // failed
-        }
-      } else {
-        // Try quarter blocks first (4 pixels per cell, better quality)
+      // 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', 'q', '-g', `${cols}x${maxRows}`, tmpFile],
+            ['-p', 'h', '-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
-          }
+          // ignored
         }
       }
     } finally {