refactor: replace timg with jimp + ink-picture renderers for image display

Remove external `timg` binary dependency in ImageShowTool by using `jimp`
for image decoding and adapted ink-picture renderers (halfBlock/braille/ascii)
for ANSI text-protocol output. The renderers are pure functions that work
with codev's Ink fork via RawAnsi, avoiding context-incompatibility with
the ink-picture React components.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/tools/ImageShowTool/ImageShowTool.tsx

@@ -2,12 +2,16 @@ 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 { buildTool, type ToolDef } from '../../Tool.js'
 import { logForDebugging } from '../../utils/debug.js'
 import {
-  renderImageWithTimgSync,
-} from '../../utils/terminalImage.js'
+  getBestTextProtocol,
+  renderImage,
+  type PixelData,
+  type TextImageProtocol,
+} from '../../utils/imageRenderers.js'
 
 const IMAGE_TOOL_NAME = 'ImageShow'
 
@@ -114,14 +118,73 @@ async function loadImage(url: string): Promise<{ buffer: Buffer; format: string
 }
 
 /**
- * React component that renders timg Unicode-block output within Ink's
+ * 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 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)
+function ImageDisplay({ output }: { output: string }): React.ReactNode {
+  const lines = output.split('\n').filter(l => l.length > 0)
   if (lines.length === 0) {
     return null
   }
@@ -139,7 +202,7 @@ export const ImageShowTool = buildTool({
   name: IMAGE_TOOL_NAME,
   description:
     'Display an image (PNG/JPEG/GIF/WebP) directly in the terminal. ' +
-    'Renders with timg Unicode-block characters within Ink\'s virtual DOM ' +
+    '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.',
 
@@ -164,7 +227,7 @@ export const ImageShowTool = buildTool({
   },
 
   async prompt(_options): Promise<string> {
-    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.`
+    return `ImageShow displays a PNG/JPEG/GIF/WebP image directly in the terminal using 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' }> {
@@ -219,7 +282,7 @@ export const ImageShowTool = buildTool({
     content: {
       success: boolean
       message: string
-      timgOutput?: string
+      imageOutput?: string
     },
     _progressMessages,
     _options,
@@ -228,8 +291,8 @@ export const ImageShowTool = buildTool({
       return null
     }
 
-    if (content.timgOutput) {
-      return <TimgDisplay output={content.timgOutput} />
+    if (content.imageOutput) {
+      return <ImageDisplay output={content.imageOutput} />
     }
 
     return <Text dimColor>{content.message}</Text>
@@ -241,7 +304,7 @@ export const ImageShowTool = buildTool({
       message: string
       imageData?: { base64: string; mediaType: string }
       base64?: string
-      timgOutput?: string
+      imageOutput?: string
     }
   }> {
     const url = input.url
@@ -273,12 +336,12 @@ export const ImageShowTool = buildTool({
 
     logForDebugging(`ImageShow: loaded ${buffer.length} byte ${format} image`)
 
-    // 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')
+    // 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 {
@@ -290,7 +353,7 @@ export const ImageShowTool = buildTool({
           mediaType,
         },
         base64: buffer.toString('base64'),
-        timgOutput,
+        imageOutput,
       },
     }
   },

src/utils/imageRenderers.ts

@@ -0,0 +1,191 @@
+/**
+ * Terminal image renderers adapted from ink-picture.
+ *
+ * Pure functions that convert pixel data into ANSI-escaped strings
+ * for display in Ink's RawAnsi component. No Ink/React dependency.
+ *
+ * Source: https://github.com/endernoke/ink-picture
+ */
+
+import chalk from 'chalk'
+
+// --- Types ---
+
+export interface PixelData {
+  data: Buffer
+  info: {
+    width: number
+    height: number
+    channels: number
+  }
+}
+
+export type TextImageProtocol = 'halfBlock' | 'braille' | 'ascii'
+
+// --- Protocol detection ---
+
+export interface TerminalCaps {
+  supportsUnicode: boolean
+  supportsColor: boolean
+}
+
+/**
+ * Select the best text-based image protocol given terminal capabilities.
+ * Prioritises halfBlock (best quality), then braille, then ascii (lowest).
+ */
+export function getBestTextProtocol(caps: TerminalCaps): TextImageProtocol {
+  if (caps.supportsUnicode && caps.supportsColor) return 'halfBlock'
+  if (caps.supportsUnicode) return 'braille'
+  return 'ascii'
+}
+
+// --- ASCII renderer ---
+
+const ASCII_CHARS =
+  "$@B%8&WM#*oahkbdpqwmZO0QLCJUYXzcvunxrjft/\\|()1{}[]?-_+~<>i!lI;:,\"^`'. "
+
+export function renderAscii(
+  pixels: PixelData,
+  colored: boolean = true,
+): string {
+  const { data, info } = pixels
+  const { width, height, channels } = info
+
+  let result = ''
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const pixelIndex = (y * width + x) * channels
+
+      const r = data[pixelIndex]!
+      const g = data[pixelIndex + 1]!
+      const b = data[pixelIndex + 2]!
+      const a = channels === 4 ? (data[pixelIndex + 3] ?? 255) : 255
+
+      const sum = r + g + b + a
+      const intensity = sum === 0 ? 0 : sum / (255 * 4)
+      const char =
+        ASCII_CHARS[
+          ASCII_CHARS.length -
+            1 -
+            Math.floor(intensity * (ASCII_CHARS.length - 1))
+        ]!
+
+      result += colored ? chalk.rgb(r, g, b)(char) : char
+    }
+
+    result += '\n'
+  }
+
+  return result.slice(0, -1)
+}
+
+// --- Half-block renderer ---
+
+const HALF_BLOCK = '\u2584'
+
+export function renderHalfBlock(pixels: PixelData): string {
+  const { data, info } = pixels
+  const { width, height, channels } = info
+
+  let result = ''
+  for (let y = 0; y < height - 1; y += 2) {
+    for (let x = 0; x < width; x++) {
+      const topPixelIndex = (y * width + x) * channels
+      const bottomPixelIndex = ((y + 1) * width + x) * channels
+
+      const r = data[topPixelIndex]!
+      const g = data[topPixelIndex + 1]!
+      const b = data[topPixelIndex + 2]!
+      const a = channels === 4 ? (data[topPixelIndex + 3] ?? 255) : 255
+
+      const r2 = data[bottomPixelIndex]!
+      const g2 = data[bottomPixelIndex + 1]!
+      const b2 = data[bottomPixelIndex + 2]!
+
+      result +=
+        a === 0
+          ? chalk.reset(' ')
+          : chalk.bgRgb(r, g, b).rgb(r2, g2, b2)(HALF_BLOCK)
+    }
+
+    result += '\n'
+  }
+
+  return result.slice(0, -1)
+}
+
+// --- Braille renderer ---
+
+export function renderBraille(pixels: PixelData): string {
+  const { data, info } = pixels
+  const { width, height, channels } = info
+
+  let result = ''
+  for (let y = 0; y < height - 3; y += 4) {
+    for (let x = 0; x < width - 1; x += 2) {
+      const dot1Index = (y * width + x) * channels
+      const dot2Index = ((y + 1) * width + x) * channels
+      const dot3Index = ((y + 2) * width + x) * channels
+      const dot4Index = (y * width + x + 1) * channels
+      const dot5Index = ((y + 1) * width + x + 1) * channels
+      const dot6Index = ((y + 2) * width + x + 1) * channels
+      const dot7Index = ((y + 3) * width + x) * channels
+      const dot8Index = ((y + 3) * width + x + 1) * channels
+
+      const getLuminance = (index: number) => {
+        const r = data[index]!
+        const g = data[index + 1]!
+        const b = data[index + 2]!
+        const a = channels === 4 ? (data[index + 3] ?? 255) : 255
+        const alpha = a / 255
+        const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b
+        const alphaAdjustedLuminance =
+          luminance * alpha + 255 * (1 - alpha)
+        return alphaAdjustedLuminance > 128 ? 1 : 0
+      }
+
+      const dot1 = getLuminance(dot1Index)
+      const dot2 = getLuminance(dot2Index)
+      const dot3 = getLuminance(dot3Index)
+      const dot4 = getLuminance(dot4Index)
+      const dot5 = getLuminance(dot5Index)
+      const dot6 = getLuminance(dot6Index)
+      const dot7 = getLuminance(dot7Index)
+      const dot8 = getLuminance(dot8Index)
+
+      const brailleChar = String.fromCharCode(
+        0x2800 +
+          (dot8 << 7) +
+          (dot7 << 6) +
+          (dot6 << 5) +
+          (dot5 << 4) +
+          (dot4 << 3) +
+          (dot3 << 2) +
+          (dot2 << 1) +
+          dot1,
+      )
+      result += brailleChar
+    }
+    result += '\n'
+  }
+
+  return result.slice(0, -1)
+}
+
+/**
+ * Render pixel data as a string using the specified text protocol.
+ */
+export function renderImage(
+  pixels: PixelData,
+  protocol: TextImageProtocol,
+  colored: boolean = true,
+): string {
+  switch (protocol) {
+    case 'halfBlock':
+      return renderHalfBlock(pixels)
+    case 'braille':
+      return renderBraille(pixels)
+    case 'ascii':
+      return renderAscii(pixels, colored)
+  }
+}