fix: render timg images within Ink's virtual DOM to prevent cursor desync

timg Unicode-block output was written to stdout via process.stdout.write(),
bypassing Ink's rendering pipeline. Ink's virtual cursor didn't know about
the image rows, causing subsequent UI (prompt, input bar) to render at wrong
positions — overlapping the image and duplicating input bars.

Now the timg ANSI output is passed through the tool data and rendered via
the RawAnsi component within Ink's virtual DOM. Ink's Yoga layout accounts
for the image's width × height, keeping cursor position in sync.

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

src/tools/ImageShowTool/ImageShowTool.tsx

@@ -2,7 +2,7 @@ import { readFile } from 'fs/promises'
 import { homedir } from 'os'
 import React, { useContext, useEffect, useRef } from 'react'
 import { z } from 'zod/v4'
-import { Text } from '../../ink.js'
+import { RawAnsi, Text } from '../../ink.js'
 import { TerminalWriteContext } from '../../ink/useTerminalNotification.js'
 import { buildTool, type ToolDef } from '../../Tool.js'
 import { logForDebugging } from '../../utils/debug.js'
@@ -10,7 +10,7 @@ import {
   detectImageProtocol,
   encodeKittyImage,
   isInsideTmux,
-  renderImageWithTimg,
+  renderImageWithTimgSync,
 } from '../../utils/terminalImage.js'
 
 const IMAGE_TOOL_NAME = 'ImageShow'
@@ -122,16 +122,11 @@ function getToolUseSummary(input: Partial<Input>): string | null {
 }
 
 /**
- * React component that displays an image in the terminal using the best
- * available method:
- *  1. Kitty graphics protocol – when the terminal supports it AND we're
- *     NOT inside tmux (where Kitty passthrough may be blocked).
- *  2. `timg` Unicode blocks – reliable fallback that works in virtually
- *     every modern terminal (Unicode + 24-bit color required).
- *  3. Plain text message – when neither method is available.
- *
- * The image is rendered via Ink's writeRaw so the escape sequences stay
- * synchronized with Ink's render cycle and avoid cursor-position races.
+ * React component that renders the image via the Kitty graphics protocol
+ * when the terminal naturally supports it (Kitty/Ghostty/WezTerm outside
+ * tmux). timg fallback is rendered in-band via RawAnsi (in
+ * renderToolResultMessage), so Ink knows the image dimensions and its
+ * virtual cursor stays in sync with the terminal.
  */
 function TerminalImageDisplay({
   base64,
@@ -146,37 +141,22 @@ function TerminalImageDisplay({
   const renderedRef = useRef(false)
 
   useEffect(() => {
-    if (renderedRef.current || !base64 || !format || !writeRaw) return
+    if (renderedRef.current || !writeRaw) return
     renderedRef.current = true
 
+    // Kitty protocol: timg fallback is rendered in renderToolResultMessage
+    // via RawAnsi (in-band with Ink's virtual DOM), so Ink knows the image
+    // dimensions and cursor position stays correct.
+    // Only use Kitty when it can reach the terminal natively.
     const protocol = detectImageProtocol()
-    const buf = Buffer.from(base64, 'base64')
-
-    // Path A: Kitty protocol – best quality, works natively in Kitty,
-    // Ghostty, WezTerm, Konsole, foot outside tmux.
-    if (protocol === 'kitty' && !isInsideTmux()) {
+    if (protocol === 'kitty' && !isInsideTmux() && base64 && format) {
+      const buf = Buffer.from(base64, 'base64')
       const sequence = encodeKittyImage(buf, format)
       if (sequence) {
-        writeRaw(sequence)
+        writeRaw(sequence + '\n')
         logForDebugging('ImageShow: displayed via Kitty protocol')
       }
-      return
     }
-
-    // Path B: timg Unicode-block rendering – reliable in all modern
-    // terminals including inside tmux where Kitty passthrough may be blocked.
-    renderImageWithTimg(buf, format)
-      .then(output => {
-        if (output) {
-          writeRaw(output)
-          logForDebugging('ImageShow: displayed via timg Unicode blocks')
-        } else {
-          logForDebugging('ImageShow: timg not available, showing text only')
-        }
-      })
-      .catch(() => {
-        logForDebugging('ImageShow: timg render error, showing text only')
-      })
   }, [base64, format, writeRaw])
 
   return <Text dimColor>{message}</Text>
@@ -268,6 +248,7 @@ export const ImageShowTool = buildTool({
       message: string
       base64?: string
       format?: string
+      timgOutput?: string
     },
     _progressMessages,
     _options,
@@ -275,6 +256,22 @@ export const ImageShowTool = buildTool({
     if (!content.success) {
       return null
     }
+
+    // timg output rendered in-band via RawAnsi so Ink knows the image
+    // dimensions and its virtual cursor stays in sync with the terminal.
+    if (content.timgOutput) {
+      // Strip cursor hide/show sequences that timg adds
+      const cleaned = content.timgOutput.replace(/\x1b\[\?25[hl]/g, '')
+      const lines = cleaned.split('\n').filter(l => l.length > 0)
+      if (lines.length === 0) {
+        return <Text dimColor>{content.message}</Text>
+      }
+      // 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} />
+    }
+
     return (
       <TerminalImageDisplay
         base64={content.base64}
@@ -291,6 +288,7 @@ export const ImageShowTool = buildTool({
       imageData?: { base64: string; mediaType: string }
       base64?: string
       format?: string
+      timgOutput?: string
     }
   }> {
     const url = input.url
@@ -322,8 +320,20 @@ export const ImageShowTool = buildTool({
 
     logForDebugging(`ImageShow: loaded ${buffer.length} byte ${format} image`)
 
-    // Return data with base64 and format so renderToolResultMessage can
-    // pass them to KittyImageDisplay for writeRaw-based terminal output.
+    // Generate timg Unicode-block rendering. The output is passed through
+    // to the Ink virtual DOM via RawAnsi in renderToolResultMessage, so
+    // Ink knows the image dimensions and its cursor stays in sync.
+    // Kitty protocol is separately handled in TerminalImageDisplay via
+    // writeRaw (only when the terminal natively supports it outside tmux).
+    const protocol = detectImageProtocol()
+    let timgOutput: string | undefined
+    if (isInsideTmux() || protocol !== 'kitty') {
+      timgOutput = renderImageWithTimgSync(buffer, format) ?? undefined
+      if (timgOutput) {
+        logForDebugging('ImageShow: displayed via timg Unicode blocks (in-band with Ink)')
+      }
+    }
+
     return {
       data: {
         success: true,
@@ -334,6 +344,7 @@ export const ImageShowTool = buildTool({
         },
         base64: buffer.toString('base64'),
         format,
+        timgOutput,
       },
     }
   },

src/utils/terminalImage.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from 'child_process'
 import { mkdtempSync, rmSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
@@ -5,7 +6,7 @@ import { Buffer } from 'buffer'
 import { env } from './env.js'
 import { execFileNoThrow } from './execFileNoThrow.js'
 import { wrapForMultiplexer } from '../ink/termio/osc.js'
-import { which } from './which.js'
+import { which, whichSync } from './which.js'
 
 export type ImageProtocol = 'kitty' | null
 
@@ -203,3 +204,70 @@ export async function renderImageWithTimg(
     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(), 'versperclaw-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
+  }
+}