feat(cli): improve image paste UX with instant feedback and status tracking

- Add typed status field to PendingImage (processing/ready/error) instead of string matching
- Show image banner immediately on Ctrl+V before clipboard check completes
- Display "X images attached, Y images processing" in banner header
- Move processing indicator to note area, show generic thumbnail fallback
- Add tests for image lifecycle status transitions
- Simplify pending images filtering with single-pass loop

Author: brandonkachen

cli/src/chat.tsx

@@ -11,7 +11,7 @@ import {
 import { useShallow } from 'zustand/react/shallow'
 
 import { routeUserPrompt, addBashMessageToHistory } from './commands/router'
-import { addPendingImageFromFile } from './utils/add-pending-image'
+import { addClipboardPlaceholder, addPendingImageFromFile } from './utils/add-pending-image'
 import { getProjectRoot } from './project-files'
 import { AnnouncementBanner } from './components/announcement-banner'
 import { hasClipboardImage, readClipboardImage } from './utils/clipboard-image'
@@ -1015,20 +1015,31 @@ export const Chat = ({
       onBashHistoryUp: navigateUp,
       onBashHistoryDown: navigateDown,
       onPasteImage: () => {
-        if (!hasClipboardImage()) {
-          return false
-        }
+        // Show placeholder immediately so user sees the banner right away
+        const placeholderPath = addClipboardPlaceholder()
+
+        // Check and process clipboard image in background
+        setTimeout(() => {
+          // Check if clipboard actually has an image
+          if (!hasClipboardImage()) {
+            // No image - quietly remove placeholder (brief flash is acceptable)
+            useChatStore.getState().removePendingImage(placeholderPath)
+            return
+          }
 
-        const result = readClipboardImage()
-        if (!result.success || !result.imagePath || !result.filename) {
-          showClipboardMessage(result.error || 'Failed to paste image', {
-            durationMs: 3000,
-          })
-          return true
-        }
+          const result = readClipboardImage()
+          if (!result.success || !result.imagePath) {
+            useChatStore.getState().removePendingImage(placeholderPath)
+            showClipboardMessage(result.error || 'Failed to paste image', {
+              durationMs: 3000,
+            })
+            return
+          }
+
+          const cwd = getProjectRoot() ?? process.cwd()
+          void addPendingImageFromFile(result.imagePath, cwd, placeholderPath)
+        }, 0)
 
-        const cwd = getProjectRoot() ?? process.cwd()
-        void addPendingImageFromFile(result.imagePath, cwd)
         return true
       },
     }),

cli/src/components/image-card.tsx

@@ -34,7 +34,8 @@ const truncateFilename = (filename: string): string => {
 export interface ImageCardImage {
   path: string
   filename: string
-  note?: string  // Status: "processing…" | "compressed" | error message
+  status?: 'processing' | 'ready' | 'error'  // Defaults to 'ready' if not provided
+  note?: string  // Display note: "compressed" | error message
 }
 
 interface ImageCardProps {
@@ -111,9 +112,7 @@ export const ImageCard = ({
             alignItems: 'center',
           }}
         >
-          {image.note === 'processing…' ? (
-            <text style={{ fg: theme.muted }}>⏳</text>
-          ) : thumbnailSequence ? (
+          {thumbnailSequence ? (
             <text>{thumbnailSequence}</text>
           ) : (
             <ImageThumbnail
@@ -141,14 +140,14 @@ export const ImageCard = ({
           >
             {truncatedName}
           </text>
-          {image.note && (
+          {((image.status ?? 'ready') === 'processing' || image.note) && (
             <text
               style={{
                 fg: theme.muted,
                 wrapMode: 'none',
               }}
             >
-              {image.note}
+              {(image.status ?? 'ready') === 'processing' ? 'processing…' : image.note}
             </text>
           )}
         </box>

cli/src/components/pending-images-banner.tsx

@@ -12,9 +12,21 @@ export const PendingImagesBanner = () => {
   const pendingImages = useChatStore((state) => state.pendingImages)
   const removePendingImage = useChatStore((state) => state.removePendingImage)
 
-  // Separate error messages from actual images
-  const errorImages = pendingImages.filter((img) => img.isError)
-  const validImages = pendingImages.filter((img) => !img.isError)
+  // Separate error messages from actual images, and count processing
+  const errorImages: typeof pendingImages = []
+  const validImages: typeof pendingImages = []
+  let processingCount = 0
+  for (const img of pendingImages) {
+    if (img.status === 'error') {
+      errorImages.push(img)
+    } else {
+      validImages.push(img)
+      if (img.status === 'processing') {
+        processingCount++
+      }
+    }
+  }
+  const readyCount = validImages.length - processingCount
 
   if (pendingImages.length === 0) {
     return null
@@ -72,7 +84,10 @@ export const PendingImagesBanner = () => {
 
       {/* Header */}
       <text style={{ fg: theme.info }}>
-        📎 {pluralize(validImages.length, 'image')} attached
+        📎{' '}
+        {readyCount > 0 && `${pluralize(readyCount, 'image')} attached`}
+        {readyCount > 0 && processingCount > 0 && ', '}
+        {processingCount > 0 && `${pluralize(processingCount, 'image')} processing`}
       </text>
 
       {/* Image cards in a horizontal row - only valid images */}

cli/src/state/chat-store.ts

@@ -43,14 +43,16 @@ export type AskUserState = {
   otherTexts: string[] // Custom text input for each question (empty string if not used)
 } | null
 
+export type PendingImageStatus = 'processing' | 'ready' | 'error'
+
 export type PendingImage = {
   path: string
   filename: string
+  status: PendingImageStatus
   size?: number
   width?: number
   height?: number
-  note?: string // Status: "processing…" | "compressed" | error message
-  isError?: boolean // True if this is an error entry (e.g., file not found)
+  note?: string // Display note: "compressed" | error message
   processedImage?: {
     base64: string
     mediaType: string