@alumbwe/anvil 1.0.0

package/src/utils/image-display.ts

@@ -0,0 +1,67 @@
+/**
+ * Image display utilities for calculating terminal display dimensions.
+ * Uses actual image dimensions to preserve aspect ratio when rendering.
+ */
+
+// Terminal cells are approximately 2:1 aspect ratio (height:width in pixels)
+const CELL_ASPECT_RATIO = 2
+
+// Approximate pixels per terminal cell for scaling
+const PIXELS_PER_CELL = 15
+
+// Maximum display width in cells to prevent images from being too large
+const MAX_DISPLAY_WIDTH = 60
+
+export interface DisplaySizeInput {
+  /** Original image width in pixels */
+  width?: number
+  /** Original image height in pixels */
+  height?: number
+  /** Available terminal width in cells */
+  availableWidth: number
+}
+
+export interface DisplaySize {
+  /** Display width in terminal cells */
+  width: number
+  /** Display height in terminal cells */
+  height: number
+}
+
+/**
+ * Calculate display dimensions for an image in terminal cells.
+ * 
+ * Uses actual image dimensions to preserve aspect ratio. Falls back to
+ * percentage-based sizing when dimensions are not available.
+ * 
+ * @param input - Image dimensions and available space
+ * @returns Display dimensions in terminal cells
+ */
+export function calculateDisplaySize(input: DisplaySizeInput): DisplaySize {
+  const { width, height, availableWidth } = input
+  
+  // Calculate max width with padding
+  const maxWidth = Math.max(1, Math.min(availableWidth - 4, MAX_DISPLAY_WIDTH))
+  
+  // Fallback when dimensions are unknown or invalid
+  if (!width || !height || width <= 0 || height <= 0) {
+    const fallbackWidth = Math.max(1, Math.floor(maxWidth * 0.5))
+    const fallbackHeight = Math.max(1, Math.floor(fallbackWidth / CELL_ASPECT_RATIO))
+    return { width: fallbackWidth, height: fallbackHeight }
+  }
+  
+  const aspectRatio = width / height
+  
+  // Calculate natural cell width based on image pixel dimensions
+  // This prevents tiny images from being blown up too large
+  const naturalCellWidth = Math.ceil(width / PIXELS_PER_CELL)
+  
+  // Use the smaller of natural width and max available width
+  const displayWidth = Math.max(1, Math.min(naturalCellWidth, maxWidth))
+  
+  // Calculate height preserving aspect ratio, accounting for cell aspect ratio
+  // Since cells are 2:1, we divide by CELL_ASPECT_RATIO to get proper visual proportions
+  const displayHeight = Math.max(1, Math.floor(displayWidth / aspectRatio / CELL_ASPECT_RATIO))
+  
+  return { width: displayWidth, height: displayHeight }
+}

package/src/utils/image-handler.ts

@@ -0,0 +1,325 @@
+import { readFileSync, statSync } from 'fs'
+import { homedir } from 'os'
+import path from 'path'
+
+import {
+  SUPPORTED_IMAGE_EXTENSIONS,
+  MAX_IMAGE_FILE_SIZE,
+  MAX_IMAGE_BASE64_SIZE,
+  MAX_TOTAL_IMAGE_SIZE,
+  IMAGE_EXTENSIONS_PATTERN,
+  getImageMimeType,
+} from '@anvil/common/constants/images'
+import { Jimp } from 'jimp'
+
+import { logger } from './logger'
+
+// Re-export all image constants for backwards compatibility
+export * from '@anvil/common/constants/images'
+
+export interface ImageUploadResult {
+  success: boolean
+  imagePart?: {
+    type: 'image'
+    image: string // base64
+    mediaType: string
+    filename?: string
+    size?: number
+    width?: number
+    height?: number
+  }
+  error?: string
+  wasCompressed?: boolean
+}
+
+interface CompressionResult {
+  success: boolean
+  buffer?: Buffer
+  base64?: string
+  mediaType?: string
+  width?: number
+  height?: number
+  error?: string
+}
+
+// Compression settings for iterative compression
+const COMPRESSION_QUALITIES = [85, 70, 50, 30]
+const DIMENSION_LIMITS = [1500, 1200, 800, 600]
+
+/**
+ * Validates total size of multiple images
+ */
+export function validateTotalImageSize(imageParts: Array<{ size?: number }>): {
+  valid: boolean
+  error?: string
+} {
+  const totalSize = imageParts.reduce((sum, part) => sum + (part.size || 0), 0)
+
+  if (totalSize > MAX_TOTAL_IMAGE_SIZE) {
+    const totalMB = (totalSize / (1024 * 1024)).toFixed(1)
+    const maxMB = (MAX_TOTAL_IMAGE_SIZE / (1024 * 1024)).toFixed(1)
+    return {
+      valid: false,
+      error: `Total image size too large: ${totalMB}MB (max ${maxMB}MB)`,
+    }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Normalizes a user-provided file path by handling escape sequences.
+ */
+function normalizeUserProvidedPath(filePath: string): string {
+  let normalized = filePath
+
+  // Handle unicode escape sequences (e.g., from terminal copy/paste)
+  normalized = normalized.replace(/\\u\{([0-9a-fA-F]+)\}|\\u([0-9a-fA-F]{4})/g, (_, bracedCode, shortCode) => {
+    const code = bracedCode || shortCode
+    const value = Number.parseInt(code, 16)
+    return Number.isNaN(value) ? _ : String.fromCodePoint(value)
+  })
+
+  // Handle shell-escaped special characters (e.g., spaces in paths)
+  normalized = normalized.replace(/\\([ \t"'(){}\[\]])/g, '$1')
+
+  return normalized
+}
+
+/**
+ * Validates if a file path is a supported image
+ */
+export function isImageFile(filePath: string): boolean {
+  const ext = path.extname(filePath).toLowerCase()
+  return SUPPORTED_IMAGE_EXTENSIONS.has(ext)
+}
+
+/**
+ * Resolves a file path, handling ~, relative paths, etc.
+ */
+export function resolveFilePath(filePath: string, cwd: string): string {
+  const normalized = normalizeUserProvidedPath(filePath)
+  if (normalized.startsWith('~')) {
+    return path.join(homedir(), normalized.slice(1))
+  }
+  if (path.isAbsolute(normalized)) {
+    return normalized
+  }
+  return path.resolve(cwd, normalized)
+}
+
+/**
+ * Attempts to compress an image to fit within the max base64 size.
+ * Tries different dimension/quality combinations until one fits.
+ */
+async function compressImageToFitSize(fileBuffer: Buffer): Promise<CompressionResult> {
+  const image = await Jimp.read(fileBuffer)
+  const originalWidth = image.bitmap.width
+  const originalHeight = image.bitmap.height
+
+  let bestBase64Size = Infinity
+  let attemptCount = 0
+
+  for (const maxDimension of DIMENSION_LIMITS) {
+    for (const quality of COMPRESSION_QUALITIES) {
+      attemptCount++
+      
+      const testImage = await Jimp.read(fileBuffer)
+
+      // Resize if needed (preserve aspect ratio)
+      if (originalWidth > maxDimension || originalHeight > maxDimension) {
+        if (originalWidth > originalHeight) {
+          testImage.resize({ w: maxDimension })
+        } else {
+          testImage.resize({ h: maxDimension })
+        }
+      }
+
+      const testBuffer = await testImage.getBuffer('image/jpeg', { quality })
+      const testBase64 = testBuffer.toString('base64')
+      const testBase64Size = testBase64.length
+
+      // Track best attempt
+      if (testBase64Size < bestBase64Size) {
+        bestBase64Size = testBase64Size
+      }
+
+      // If this attempt fits, use it
+      if (testBase64Size <= MAX_IMAGE_BASE64_SIZE) {
+        logger.debug(
+          {
+            originalSize: fileBuffer.length,
+            finalSize: testBuffer.length,
+            finalDimensions: `${testImage.bitmap.width}x${testImage.bitmap.height}`,
+            quality,
+            attempts: attemptCount,
+          },
+          'Image handler: Successful compression found',
+        )
+
+        return {
+          success: true,
+          buffer: testBuffer,
+          base64: testBase64,
+          mediaType: 'image/jpeg',
+          width: testImage.bitmap.width,
+          height: testImage.bitmap.height,
+        }
+      }
+    }
+  }
+
+  // No compression attempt succeeded
+  const bestSizeKB = (bestBase64Size / 1024).toFixed(1)
+  const maxKB = (MAX_IMAGE_BASE64_SIZE / 1024).toFixed(1)
+  const originalKB = (fileBuffer.toString('base64').length / 1024).toFixed(1)
+
+  return {
+    success: false,
+    error: `Image too large even after ${attemptCount} compression attempts. Original: ${originalKB}KB, best compressed: ${bestSizeKB}KB (max ${maxKB}KB). Try using a smaller image.`,
+  }
+}
+
+/**
+ * Processes an image file and converts it to base64 for upload.
+ * Includes automatic downsampling for large images.
+ */
+export async function processImageFile(
+  filePath: string,
+  cwd: string,
+): Promise<ImageUploadResult> {
+  const resolvedPath = resolveFilePath(filePath, cwd)
+
+  // Validate file exists
+  let stats
+  try {
+    stats = statSync(resolvedPath)
+  } catch (error) {
+    logger.debug({ resolvedPath, error }, 'Image handler: File not found')
+    return { success: false, error: `File not found: ${filePath}` }
+  }
+
+  if (!stats.isFile()) {
+    return { success: false, error: `Path is not a file: ${filePath}` }
+  }
+
+  // Validate file size
+  if (stats.size > MAX_IMAGE_FILE_SIZE) {
+    const sizeMB = (stats.size / (1024 * 1024)).toFixed(1)
+    const maxMB = (MAX_IMAGE_FILE_SIZE / (1024 * 1024)).toFixed(1)
+    return { success: false, error: `File too large: ${sizeMB}MB (max ${maxMB}MB): ${filePath}` }
+  }
+
+  // Validate image format
+  if (!isImageFile(resolvedPath)) {
+    return {
+      success: false,
+      error: `Unsupported image format: ${filePath}. Supported: ${Array.from(SUPPORTED_IMAGE_EXTENSIONS).join(', ')}`,
+    }
+  }
+
+  // Get MIME type
+  const mediaType = getImageMimeType(path.extname(resolvedPath))
+  if (!mediaType) {
+    return { success: false, error: `Could not determine image type for: ${filePath}` }
+  }
+
+  // Read file
+  let fileBuffer: Buffer
+  try {
+    fileBuffer = readFileSync(resolvedPath)
+  } catch (error) {
+    logger.debug({ resolvedPath, error }, 'Image handler: Failed to read file')
+    return { success: false, error: `Could not read file: ${filePath}` }
+  }
+
+  // Get initial dimensions
+  let width: number | undefined
+  let height: number | undefined
+  try {
+    const image = await Jimp.read(fileBuffer)
+    width = image.bitmap.width
+    height = image.bitmap.height
+  } catch {
+    // Continue without dimensions if we can't read them
+  }
+
+  // Check if compression is needed
+  let base64Data = fileBuffer.toString('base64')
+  let processedBuffer = fileBuffer
+  let finalMediaType = mediaType
+  let wasCompressed = false
+
+  if (base64Data.length > MAX_IMAGE_BASE64_SIZE) {
+    const compressionResult = await compressImageToFitSize(fileBuffer)
+    
+    if (!compressionResult.success) {
+      return { success: false, error: compressionResult.error }
+    }
+
+    base64Data = compressionResult.base64!
+    processedBuffer = compressionResult.buffer!
+    finalMediaType = compressionResult.mediaType!
+    width = compressionResult.width
+    height = compressionResult.height
+    wasCompressed = true
+  }
+
+  logger.debug(
+    { resolvedPath, finalSize: processedBuffer.length, wasCompressed },
+    'Image handler: Processing complete',
+  )
+
+  return {
+    success: true,
+    imagePart: {
+      type: 'image',
+      image: base64Data,
+      mediaType: finalMediaType,
+      filename: path.basename(resolvedPath),
+      size: processedBuffer.length,
+      width,
+      height,
+    },
+    wasCompressed,
+  }
+}
+
+/**
+ * Extracts image file paths from user input using @path syntax and auto-detection
+ */
+export function extractImagePaths(input: string): string[] {
+  const paths: string[] = []
+
+  // Skip paths inside code blocks
+  const cleanInput = input.replace(/```[\s\S]*?```|`[^`]*`/g, ' ')
+
+  const addPath = (p: string) => {
+    const cleaned = p.replace(/[.,!?;)\]}>">]+$/, '') // Remove trailing punctuation
+    if (isImageFile(cleaned) && !paths.includes(cleaned)) {
+      paths.push(cleaned)
+    }
+  }
+
+  // @path syntax
+  for (const match of cleanInput.matchAll(/@([^\s]+)/g)) {
+    addPath(match[1])
+  }
+
+  // Path patterns to detect
+  const patterns = [
+    `(?:^|\\s)((?:[~/]|[A-Za-z]:\\\\)[^\\s"']*\\.(?:${IMAGE_EXTENSIONS_PATTERN}))(?=\\s|$|[.,!?;)\\]}>])`, // Absolute paths
+    `(?:^|\\s)(\\.\\.?[\\/\\\\][^\\s"']*\\.(?:${IMAGE_EXTENSIONS_PATTERN}))(?=\\s|$|[.,!?;)\\]}>])`, // ./path, ../path
+    `(?:^|\\s)((?![^\\s]*:\\/\\/|@)[^\\s"':]*[\\/\\\\][^\\s"']*\\.(?:${IMAGE_EXTENSIONS_PATTERN}))(?=\\s|$|[.,!?;)\\]}>])`, // relative/path
+    `["']([^"']*[\\/\\\\][^"']*\\.(?:${IMAGE_EXTENSIONS_PATTERN}))["']`, // Quoted paths
+  ]
+
+  for (const pattern of patterns) {
+    const regex = new RegExp(pattern, 'gi')
+    for (const match of cleanInput.matchAll(regex)) {
+      addPath(match[1])
+    }
+  }
+
+  return paths
+}

package/src/utils/image-processor.ts

@@ -0,0 +1,133 @@
+import { extractImagePaths, processImageFile } from './image-handler'
+import { logger } from './logger'
+
+import type { PendingImageAttachment } from '../types/store'
+import type { MessageContent } from '@anvil/sdk'
+
+// Converts pending images + inline references into SDK-ready message content.
+export type ProcessedImagePart = {
+  type: 'image'
+  image: string
+  mediaType: string
+  filename?: string
+  size?: number
+  width?: number
+  height?: number
+  path: string
+}
+
+export const processImagesForMessage = async (params: {
+  content: string
+  pendingImages: PendingImageAttachment[]
+  projectRoot: string
+  processor?: typeof processImageFile
+  log?: typeof logger
+}): Promise<{
+  attachments: { path: string; filename: string; size?: number }[]
+  messageContent: MessageContent[] | undefined
+}> => {
+  const {
+    content,
+    pendingImages,
+    projectRoot,
+    processor = processImageFile,
+    log = logger,
+  } = params
+
+  const attachments = pendingImages.map((img) => ({
+    path: img.path,
+    filename: img.filename,
+    size: img.size,
+  }))
+
+  const validImageParts: ProcessedImagePart[] = []
+
+  // First, use pre-processed data from pendingImages (already processed when attached)
+  // This avoids re-reading from disk, which can fail if the path is relative to a different cwd
+  const pendingImagePaths = new Set<string>()
+  for (const img of pendingImages) {
+    pendingImagePaths.add(img.path)
+
+    if (img.processedImage) {
+      // Use the already-processed image data
+      validImageParts.push({
+        type: 'image',
+        image: img.processedImage.base64,
+        mediaType: img.processedImage.mediaType,
+        filename: img.filename,
+        size: img.size,
+        width: img.width,
+        height: img.height,
+        path: img.path,
+      })
+    } else if (img.status === 'ready') {
+      // Backwards compatibility: if processedImage is missing but status is ready,
+      // try to process from disk (shouldn't happen in normal flow)
+      log.warn(
+        { imagePath: img.path },
+        'Pending image marked ready but missing processedImage data, re-processing from disk',
+      )
+      const result = await processor(img.path, projectRoot)
+      if (result.success && result.imagePart) {
+        validImageParts.push({
+          type: 'image',
+          image: result.imagePart.image,
+          mediaType: result.imagePart.mediaType,
+          filename: result.imagePart.filename,
+          size: result.imagePart.size,
+          width: result.imagePart.width,
+          height: result.imagePart.height,
+          path: img.path,
+        })
+      } else if (!result.success) {
+        log.warn(
+          { imagePath: img.path, error: result.error },
+          'Failed to process pending image from disk',
+        )
+      }
+    }
+    // Skip images with status 'processing' or 'error' - they shouldn't be sent
+  }
+
+  // Then, process any inline image paths from the message content that aren't already in pendingImages
+  const detectedImagePaths = extractImagePaths(content)
+  for (const imagePath of detectedImagePaths) {
+    // Skip if this path is already handled by pendingImages
+    if (pendingImagePaths.has(imagePath)) {
+      continue
+    }
+
+    const result = await processor(imagePath, projectRoot)
+    if (result.success && result.imagePart) {
+      validImageParts.push({
+        type: 'image',
+        image: result.imagePart.image,
+        mediaType: result.imagePart.mediaType,
+        filename: result.imagePart.filename,
+        size: result.imagePart.size,
+        width: result.imagePart.width,
+        height: result.imagePart.height,
+        path: imagePath,
+      })
+    } else if (!result.success) {
+      log.warn(
+        { imagePath, error: result.error },
+        'Failed to process inline image path for SDK',
+      )
+    }
+  }
+
+  let messageContent: MessageContent[] | undefined
+  if (validImageParts.length > 0) {
+    messageContent = validImageParts.map((img) => ({
+      type: 'image',
+      image: img.image,
+      mediaType: img.mediaType,
+    }))
+  }
+
+  return {
+    attachments,
+    messageContent,
+  }
+}

package/src/utils/image-thumbnail.ts

@@ -0,0 +1,78 @@
+/**
+ * Image thumbnail utilities for extracting pixel colors
+ * Uses Jimp to decode images and sample colors for display
+ */
+
+import { Jimp, ResizeStrategy } from 'jimp'
+
+import { logger } from './logger'
+
+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(
+  source: string | Buffer,
+  targetWidth: number,
+  targetHeight: number,
+): Promise<ThumbnailData | null> {
+  try {
+    const image = await Jimp.read(source)
+
+    // Resize to target dimensions (height * 2 because we use half-blocks)
+    // Use bilinear interpolation for smoother downscaling (sharper than nearest-neighbor)
+    const resizedHeight = targetHeight * 2
+    image.resize({ w: targetWidth, h: resizedHeight, mode: ResizeStrategy.BILINEAR })
+
+    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 (error) {
+    logger.warn(
+      {
+        source: typeof source === 'string' ? source : `Buffer(len=${source.length})`,
+        error: error instanceof Error ? error.message : String(error),
+      },
+      'Failed to extract thumbnail colors from image',
+    )
+    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')}`
+}