feat(cli): add colored image thumbnail preview for all terminals

- Add image-thumbnail.ts utility to extract pixel colors using Jimp
- Add ImageThumbnail component rendering with Unicode half-blocks (▀)
- Use OpenTUI native fg/backgroundColor styling instead of ANSI escapes
- Works in terminals without iTerm2/Kitty inline image support
- Falls back to emoji if image processing fails

Author: brandonkachen

bun.lock

@@ -38,12 +38,13 @@
     "open": "^10.1.0",
     "pino": "9.4.0",
     "posthog-node": "4.17.2",
-    "string-width": "^7.2.0",
     "react": "^19.0.0",
     "react-reconciler": "^0.32.0",
     "remark-breaks": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
+    "string-width": "^7.2.0",
+    "terminal-image": "^4.1.0",
     "unified": "^11.0.0",
     "yoga-layout": "^3.2.1",
     "zod": "^3.24.1",

cli/package.json

@@ -2,6 +2,7 @@ import React, { useEffect, useState } from 'react'
 import fs from 'fs'
 
 import { Button } from './button'
+import { ImageThumbnail } from './image-thumbnail'
 
 import { useTheme } from '../hooks/use-theme'
 import {
@@ -61,26 +62,40 @@ export const ImageCard = ({
   const theme = useTheme()
   const [isCloseHovered, setIsCloseHovered] = useState(false)
   const [thumbnailSequence, setThumbnailSequence] = useState<string | null>(null)
-  const canShowThumbnail = supportsInlineImages()
+  const canShowInlineImages = supportsInlineImages()
 
-  // Load thumbnail if terminal supports inline images
+  // Load thumbnail if terminal supports inline images (iTerm2/Kitty)
   useEffect(() => {
-    if (!canShowThumbnail) return
-
-    try {
-      const imageData = fs.readFileSync(image.path)
-      const base64Data = imageData.toString('base64')
-      const sequence = renderInlineImage(base64Data, {
-        width: 4, // Small thumbnail width in cells
-        height: 3, // Small thumbnail height in cells
-        filename: image.filename,
-      })
-      setThumbnailSequence(sequence)
-    } catch {
-      // Failed to load image, will show icon fallback
-      setThumbnailSequence(null)
+    if (!canShowInlineImages) return
+
+    let cancelled = false
+
+    const loadThumbnail = async () => {
+      try {
+        const imageData = fs.readFileSync(image.path)
+        const base64Data = imageData.toString('base64')
+        const sequence = renderInlineImage(base64Data, {
+          width: 4,
+          height: 3,
+          filename: image.filename,
+        })
+        if (!cancelled) {
+          setThumbnailSequence(sequence)
+        }
+      } catch {
+        // Failed to load image, will show icon fallback
+        if (!cancelled) {
+          setThumbnailSequence(null)
+        }
+      }
+    }
+
+    loadThumbnail()
+
+    return () => {
+      cancelled = true
     }
-  }, [image.path, image.filename, canShowThumbnail])
+  }, [image.path, image.filename, canShowInlineImages])
 
   const truncatedName = truncateFilename(image.filename)
 
@@ -114,7 +129,12 @@ export const ImageCard = ({
           {thumbnailSequence ? (
             <text>{thumbnailSequence}</text>
           ) : (
-            <text style={{ fg: theme.info }}>🖼️</text>
+            <ImageThumbnail
+              imagePath={image.path}
+              width={18}
+              height={3}
+              fallback={<text style={{ fg: theme.info }}>🖼️</text>}
+            />
           )}
         </box>
         {/* Close button in top-right corner */}

cli/src/components/image-card.tsx

@@ -0,0 +1,114 @@
+/**
+ * Image Thumbnail Component
+ * Renders a small image preview using colored Unicode half-blocks
+ * Uses OpenTUI's native fg/backgroundColor styling instead of ANSI escape sequences
+ */
+
+import React, { useEffect, useState, memo } from 'react'
+
+import {
+  extractThumbnailColors,
+  rgbToHex,
+  type ThumbnailData,
+} from '../utils/image-thumbnail'
+
+interface ImageThumbnailProps {
+  imagePath: string
+  width: number // Width in cells
+  height: number // Height in rows (each row uses half-blocks for 2 pixel rows)
+  fallback?: React.ReactNode
+}
+
+/**
+ * Renders an image as colored blocks using Unicode half-blocks (▀)
+ * Each character cell displays 2 vertical pixels by using:
+ * - Foreground color for top pixel
+ * - Background color for bottom pixel
+ * - ▀ (upper half block) character
+ */
+export const ImageThumbnail = memo(({
+  imagePath,
+  width,
+  height,
+  fallback,
+}: ImageThumbnailProps) => {
+  const [thumbnailData, setThumbnailData] = useState<ThumbnailData | null>(null)
+  const [isLoading, setIsLoading] = useState(true)
+  const [error, setError] = useState(false)
+
+  useEffect(() => {
+    let cancelled = false
+
+    const loadThumbnail = async () => {
+      setIsLoading(true)
+      setError(false)
+      
+      const data = await extractThumbnailColors(imagePath, width, height)
+      
+      if (!cancelled) {
+        if (data) {
+          setThumbnailData(data)
+        } else {
+          setError(true)
+        }
+        setIsLoading(false)
+      }
+    }
+
+    loadThumbnail()
+
+    return () => {
+      cancelled = true
+    }
+  }, [imagePath, width, height])
+
+  if (isLoading) {
+    return <>{fallback}</>
+  }
+
+  if (error || !thumbnailData) {
+    return <>{fallback}</>
+  }
+
+  // Render the thumbnail using half-blocks
+  // Each row of our output combines 2 pixel rows from the image
+  const rows: React.ReactNode[] = []
+  
+  for (let rowIndex = 0; rowIndex < thumbnailData.height; rowIndex += 2) {
+    const topRow = thumbnailData.pixels[rowIndex]
+    const bottomRow = thumbnailData.pixels[rowIndex + 1] || topRow // Use top row if no bottom
+    
+    const cells: React.ReactNode[] = []
+    
+    for (let col = 0; col < thumbnailData.width; col++) {
+      const topPixel = topRow[col]
+      const bottomPixel = bottomRow[col]
+      
+      const fgColor = rgbToHex(topPixel.r, topPixel.g, topPixel.b)
+      const bgColor = rgbToHex(bottomPixel.r, bottomPixel.g, bottomPixel.b)
+      
+      cells.push(
+        <box
+          key={col}
+          style={{
+            backgroundColor: bgColor,
+          }}
+        >
+          <text style={{ fg: fgColor }}>▀</text>
+        </box>
+      )
+    }
+    
+    rows.push(
+      <box key={rowIndex} style={{ flexDirection: 'row' }}>
+        {cells}
+      </box>
+    )
+  }
+
+  return (
+    <box style={{ flexDirection: 'column' }}>
+      {rows}
+    </box>
+  )
+})

cli/src/components/image-thumbnail.tsx

@@ -0,0 +1,68 @@
+/**
+ * Image thumbnail utilities for extracting pixel colors
+ * Uses Jimp to decode images and sample colors for display
+ */
+
+import { Jimp } from 'jimp'
+
+export interface ThumbnailPixel {
+  r: number
+  g: number
+  b: number
+}
+
+export interface ThumbnailData {
+  width: number
+  height: number
+  pixels: ThumbnailPixel[][] // [row][col]
+}
+
+/**
+ * Extract a thumbnail grid of colors from an image file
+ * @param imagePath - Path to the image file
+ * @param targetWidth - Target width in cells
+ * @param targetHeight - Target height in cells (will be doubled with half-blocks)
+ * @returns Promise resolving to thumbnail data with pixel colors
+ */
+export async function extractThumbnailColors(
+  imagePath: string,
+  targetWidth: number,
+  targetHeight: number,
+): Promise<ThumbnailData | null> {
+  try {
+    const image = await Jimp.read(imagePath)
+    
+    // Resize to target dimensions (height * 2 because we use half-blocks)
+    const resizedHeight = targetHeight * 2
+    image.resize({ w: targetWidth, h: resizedHeight })
+    
+    const width = image.width
+    const height = image.height
+    
+    const pixels: ThumbnailPixel[][] = []
+    
+    for (let y = 0; y < height; y++) {
+      const row: ThumbnailPixel[] = []
+      for (let x = 0; x < width; x++) {
+        const color = image.getPixelColor(x, y)
+        // Jimp stores colors as 32-bit integers: RRGGBBAA
+        const r = (color >> 24) & 0xff
+        const g = (color >> 16) & 0xff
+        const b = (color >> 8) & 0xff
+        row.push({ r, g, b })
+      }
+      pixels.push(row)
+    }
+    
+    return { width, height, pixels }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Convert RGB to hex color string
+ */
+export function rgbToHex(r: number, g: number, b: number): string {
+  return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`
+}

cli/src/utils/image-thumbnail.ts

@@ -1,8 +1,11 @@
 /**
  * Terminal image rendering utilities
  * Supports iTerm2 inline images protocol and Kitty graphics protocol
+ * Falls back to ANSI block characters for unsupported terminals
  */
 
+import terminalImage from 'terminal-image'
+
 export type TerminalImageProtocol = 'iterm2' | 'kitty' | 'sixel' | 'none'
 
 let cachedProtocol: TerminalImageProtocol | null = null
@@ -221,3 +224,58 @@ export function getImageSupportDescription(): string {
       return 'No inline image support'
   }
 }
+
+/**
+ * Render an image using ANSI block characters (Unicode half-blocks)
+ * This works in any terminal that supports 24-bit color
+ * @param imageBuffer - Buffer containing image data
+ * @param options - Display options
+ * @returns Promise resolving to the ANSI escape sequence string
+ */
+export async function renderAnsiBlockImage(
+  imageBuffer: Buffer,
+  options: {
+    width?: number
+    height?: number
+  } = {},
+): Promise<string> {
+  const { width = 20, height = 10 } = options
+
+  try {
+    const result = await terminalImage.buffer(imageBuffer, {
+      width,
+      height,
+      preserveAspectRatio: true,
+    })
+    return result
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Render an image from a file path using ANSI block characters
+ * @param filePath - Path to the image file
+ * @param options - Display options
+ * @returns Promise resolving to the ANSI escape sequence string
+ */
+export async function renderAnsiBlockImageFromFile(
+  filePath: string,
+  options: {
+    width?: number
+    height?: number
+  } = {},
+): Promise<string> {
+  const { width = 20, height = 10 } = options
+
+  try {
+    const result = await terminalImage.file(filePath, {
+      width,
+      height,
+      preserveAspectRatio: true,
+    })
+    return result
+  } catch {
+    return ''
+  }
+}