@alumbwe/anvil 1.0.0

package/src/components/grid-layout.tsx

@@ -0,0 +1,80 @@
+import React, { memo, type ReactNode } from 'react'
+
+import { useGridLayout } from '../hooks/use-grid-layout'
+import { MIN_COLUMN_WIDTH } from '../utils/layout-helpers'
+
+export interface GridLayoutProps<T> {
+  items: T[]
+  availableWidth: number
+  getItemKey: (item: T) => string
+  renderItem: (item: T, index: number, columnWidth: number) => ReactNode
+  footer?: ReactNode
+  marginTop?: number
+}
+
+function GridLayoutInner<T>({
+  items,
+  availableWidth,
+  getItemKey,
+  renderItem,
+  footer,
+  marginTop = 0,
+}: GridLayoutProps<T>): ReactNode {
+  const { columns, columnWidth, columnGroups } = useGridLayout(items, availableWidth)
+
+  if (items.length === 0) return null
+
+  // Unified structure for both single and multi-column layouts
+  // Using a consistent DOM structure prevents reconciliation issues during resize transitions
+  const isMultiColumn = columns > 1
+
+  return (
+    <box
+      style={{
+        flexDirection: 'column',
+        gap: isMultiColumn ? 1 : 0,
+        width: '100%',
+        marginTop,
+      }}
+    >
+      <box
+        style={{
+          flexDirection: 'row',
+          gap: isMultiColumn ? 1 : 0,
+          width: '100%',
+          alignItems: 'flex-start',
+        }}
+      >
+        {columnGroups.map((columnItems, colIdx) => {
+          const columnKey = columnItems[0]
+            ? getItemKey(columnItems[0])
+            : `col-${colIdx}`
+          return (
+            <box
+              key={columnKey}
+              style={{
+                flexDirection: 'column',
+                gap: 0,
+                flexGrow: 1,
+                flexShrink: 1,
+                flexBasis: 0,
+                // Use MIN_COLUMN_WIDTH instead of 0 to prevent columns from collapsing
+                // to zero during resize transitions (prevents 2→1 column transition bug)
+                minWidth: MIN_COLUMN_WIDTH,
+              }}
+            >
+              {columnItems.map((item, idx) => (
+                <box key={getItemKey(item)} style={{ width: '100%' }}>
+                  {renderItem(item, idx, columnWidth)}
+                </box>
+              ))}
+            </box>
+          )
+        })}
+      </box>
+      {footer}
+    </box>
+  )
+}
+
+export const GridLayout = memo(GridLayoutInner) as typeof GridLayoutInner

package/src/components/help-banner.tsx

@@ -0,0 +1,127 @@
+import React from 'react'
+
+import { BottomBanner } from './bottom-banner'
+import { useSubscriptionQuery } from '../hooks/use-subscription-query'
+import { useTheme } from '../hooks/use-theme'
+import { IS_FREEBUFF } from '../utils/constants'
+import { useChatStore } from '../state/chat-store'
+
+const HELP_TIMEOUT = 60 * 1000 // 60 seconds
+
+/** Section header component for consistent styling */
+const SectionHeader = ({ children }: { children: React.ReactNode }) => {
+  const theme = useTheme()
+  return <text style={{ fg: theme.muted }}>{children}</text>
+}
+
+/** Keyboard shortcut item */
+const Shortcut = ({
+  keys,
+  action,
+}: {
+  keys: string
+  action: string
+}) => {
+  const theme = useTheme()
+  return (
+    <box style={{ flexDirection: 'row', gap: 1 }}>
+      <text style={{ fg: theme.foreground }}>{keys}</text>
+      <text style={{ fg: theme.muted }}>{action}</text>
+    </box>
+  )
+}
+
+/** Help banner showing keyboard shortcuts and tips in an organized layout. */
+export const HelpBanner = () => {
+  const setInputMode = useChatStore((state) => state.setInputMode)
+  const theme = useTheme()
+  const { data: subscriptionData } = useSubscriptionQuery()
+  const hasSubscription = subscriptionData?.hasSubscription ?? false
+
+  // Auto-hide after timeout
+  React.useEffect(() => {
+    const timer = setTimeout(() => {
+      setInputMode('default')
+    }, HELP_TIMEOUT)
+    return () => clearTimeout(timer)
+  }, [setInputMode])
+
+  return (
+    <BottomBanner
+      borderColorKey="info"
+      onClose={() => setInputMode('default')}
+    >
+      <box style={{ flexDirection: 'column', gap: 1, flexGrow: 1 }}>
+        {/* Shortcuts Section */}
+        <box style={{ flexDirection: 'column', gap: 0 }}>
+          <SectionHeader>Shortcuts</SectionHeader>
+          <box style={{ flexDirection: 'row', flexWrap: 'wrap', columnGap: 2, paddingLeft: 2 }}>
+            <Shortcut keys="Ctrl+C / Esc" action="stop" />
+            <Shortcut keys="Ctrl+J / Opt+Enter" action="newline" />
+            <Shortcut keys="↑↓" action="history" />
+            <Shortcut keys="Ctrl+T" action="collapse/expand agents" />
+            <Shortcut keys="Ctrl+Q" action="edit queued messages" />
+          </box>
+        </box>
+
+        {/* Features Section */}
+        <box style={{ flexDirection: 'column', gap: 0 }}>
+          <SectionHeader>Features</SectionHeader>
+          <box style={{ flexDirection: 'row', flexWrap: 'wrap', columnGap: 2, paddingLeft: 2 }}>
+            <Shortcut keys="/" action="commands" />
+            <Shortcut keys="@files" action="mention" />
+            <Shortcut keys="@agents" action="use agent" />
+            <Shortcut keys="!bash" action="run command" />
+          </box>
+        </box>
+
+        {/* Tips Section */}
+        <box style={{ flexDirection: 'column', gap: 0 }}>
+          <SectionHeader>Tips</SectionHeader>
+          <box style={{ flexDirection: 'column', paddingLeft: 2 }}>
+            {IS_FREEBUFF && (
+              <text style={{ fg: theme.muted }}>
+                Try workflow: /interview → /plan → implement → /review
+              </text>
+            )}
+            <text style={{ fg: theme.muted }}>
+              Use @ to reference agents to spawn or files to read
+            </text>
+            <text style={{ fg: theme.muted }}>
+              Drag to select text — it copies automatically (or click ⎘ on a
+              message)
+            </text>
+            <text style={{ fg: theme.muted }}>
+              Esc to cancel the current response
+            </text>
+          </box>
+        </box>
+
+        {/* Credits Section — hidden in Freebuff */}
+        {!IS_FREEBUFF && (
+          <box style={{ flexDirection: 'column', gap: 0 }}>
+            <SectionHeader>Credits</SectionHeader>
+            <box style={{ flexDirection: 'column', paddingLeft: 2 }}>
+              <box style={{ flexDirection: 'row', flexWrap: 'wrap', columnGap: 1 }}>
+                <text style={{ fg: theme.foreground }}>1 credit = 1 cent</text>
+                <text style={{ fg: theme.muted }}>·</text>
+                <text style={{ fg: theme.foreground }}>/subscribe</text>
+                <text style={{ fg: theme.muted }}>·</text>
+                <text style={{ fg: theme.foreground }}>/usage</text>
+                {!hasSubscription && (
+                  <>
+                    <text style={{ fg: theme.muted }}>·</text>
+                    <text style={{ fg: theme.foreground }}>/ads:enable</text>
+                  </>
+                )}
+              </box>
+              <text style={{ fg: theme.muted }}>
+                Subscribe for the best credit rates — /subscribe
+              </text>
+            </box>
+          </box>
+        )}
+      </box>
+    </BottomBanner>
+  )
+}

package/src/components/highlighted-text.tsx

@@ -0,0 +1,52 @@
+import React from 'react'
+
+interface HighlightedSubsequenceTextProps {
+  text: string
+  indices?: number[] | null
+  color: string
+  highlightColor: string
+}
+
+export const HighlightedSubsequenceText = ({
+  text,
+  indices,
+  color,
+  highlightColor,
+}: HighlightedSubsequenceTextProps) => {
+  if (!indices || indices.length === 0) {
+    return <span fg={color}>{text}</span>
+  }
+
+  const parts: React.ReactNode[] = []
+  const highlightSet = new Set(indices)
+  let currentSegment = ''
+  let isHighlighted = false
+
+  for (let i = 0; i < text.length; i++) {
+    const shouldHighlight = highlightSet.has(i)
+
+    if (shouldHighlight !== isHighlighted) {
+      if (currentSegment) {
+        parts.push(
+          <span key={parts.length} fg={isHighlighted ? highlightColor : color}>
+            {currentSegment}
+          </span>,
+        )
+      }
+      currentSegment = text[i]
+      isHighlighted = shouldHighlight
+    } else {
+      currentSegment += text[i]
+    }
+  }
+
+  if (currentSegment) {
+    parts.push(
+      <span key={parts.length} fg={isHighlighted ? highlightColor : color}>
+        {currentSegment}
+      </span>,
+    )
+  }
+
+  return <>{parts}</>
+}

package/src/components/image-card.tsx

@@ -0,0 +1,167 @@
+import fs from 'fs'
+
+import { useEffect, useState } from 'react'
+
+import { AttachmentCard } from './attachment-card'
+import { ImageThumbnail } from './image-thumbnail'
+import { useTheme } from '../hooks/use-theme'
+import {
+  supportsInlineImages,
+  renderInlineImage,
+} from '../utils/terminal-images'
+
+// Image card display constants
+const MAX_FILENAME_LENGTH = 16
+const IMAGE_CARD_WIDTH = 18
+const THUMBNAIL_WIDTH = 14
+const THUMBNAIL_HEIGHT = 3
+const INLINE_IMAGE_WIDTH = 4
+const INLINE_IMAGE_HEIGHT = 3
+
+const truncateFilename = (filename: string): string => {
+  if (filename.length <= MAX_FILENAME_LENGTH) {
+    return filename
+  }
+  const lastDot = filename.lastIndexOf('.')
+  const ext = lastDot !== -1 ? filename.slice(lastDot) : ''
+  const baseName = lastDot !== -1 ? filename.slice(0, lastDot) : filename
+  const maxBaseLength = MAX_FILENAME_LENGTH - ext.length - 1 // -1 for ellipsis
+  return baseName.slice(0, maxBaseLength) + '…' + ext
+}
+
+export interface ImageCardImage {
+  path: string
+  filename: string
+  status?: 'processing' | 'ready' | 'error' // Defaults to 'ready' if not provided
+  note?: string // Display note: 'compressed' | error message
+  processedImage?: {
+    base64: string
+    mediaType: string
+  }
+}
+
+interface ImageCardProps {
+  image: ImageCardImage
+  onRemove?: () => void
+  showRemoveButton?: boolean
+}
+
+export const ImageCard = ({
+  image,
+  onRemove,
+  showRemoveButton = true,
+}: ImageCardProps) => {
+  const theme = useTheme()
+  const [thumbnailSequence, setThumbnailSequence] = useState<string | null>(
+    null,
+  )
+  const canShowInlineImages = supportsInlineImages()
+
+  // Load thumbnail if terminal supports inline images (iTerm2/Kitty)
+  useEffect(() => {
+    if (!canShowInlineImages) return
+    // Skip loading while image is processing or has error to avoid race condition and unnecessary failed reads
+    if ((image.status ?? 'ready') !== 'ready') return
+
+    let cancelled = false
+
+    const loadThumbnail = async () => {
+      try {
+        let base64Data: string | undefined
+
+        if (image.processedImage) {
+          base64Data = image.processedImage.base64
+        } else if (!image.path.startsWith('clipboard:')) {
+          const imageData = fs.readFileSync(image.path)
+          base64Data = imageData.toString('base64')
+        }
+
+        if (base64Data) {
+          const sequence = renderInlineImage(base64Data, {
+            width: INLINE_IMAGE_WIDTH,
+            height: INLINE_IMAGE_HEIGHT,
+            filename: image.filename,
+          })
+          if (!cancelled) {
+            setThumbnailSequence(sequence)
+          }
+        } else {
+          if (!cancelled) {
+            setThumbnailSequence(null)
+          }
+        }
+      } catch {
+        // Failed to load image, will show icon fallback
+        if (!cancelled) {
+          setThumbnailSequence(null)
+        }
+      }
+    }
+
+    loadThumbnail()
+
+    return () => {
+      cancelled = true
+    }
+  }, [image, image.filename, canShowInlineImages])
+
+  const truncatedName = truncateFilename(image.filename)
+
+  return (
+    <AttachmentCard
+      width={IMAGE_CARD_WIDTH}
+      onRemove={onRemove}
+      showRemoveButton={showRemoveButton}
+    >
+      {/* Thumbnail or icon area */}
+      <box
+        style={{
+          height: THUMBNAIL_HEIGHT,
+          justifyContent: 'center',
+          alignItems: 'center',
+        }}
+      >
+        {thumbnailSequence ? (
+          <text>{thumbnailSequence}</text>
+        ) : (
+          <ImageThumbnail
+            image={image}
+            width={THUMBNAIL_WIDTH}
+            height={THUMBNAIL_HEIGHT}
+            fallback={<text style={{ fg: theme.info }}>🖼️</text>}
+          />
+        )}
+      </box>
+
+      {/* Filename - full width */}
+      <box
+        style={{
+          paddingLeft: 1,
+          paddingRight: 1,
+          flexDirection: 'column',
+        }}
+      >
+        <text
+          style={{
+            fg: theme.foreground,
+            wrapMode: 'none',
+          }}
+        >
+          {truncatedName}
+        </text>
+        {((image.status ?? 'ready') === 'processing' || image.note) && (
+          <text
+            style={{
+              fg: theme.muted,
+              wrapMode: 'none',
+            }}
+          >
+            {(image.status ?? 'ready') === 'processing'
+              ? 'processing…'
+              : image.note}
+          </text>
+        )}
+      </box>
+    </AttachmentCard>
+  )
+}

package/src/components/image-thumbnail.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 { type ImageCardImage } from './image-card'
+import {
+  extractThumbnailColors,
+  rgbToHex,
+  type ThumbnailData,
+} from '../utils/image-thumbnail'
+
+interface ImageThumbnailProps {
+  image: ImageCardImage
+  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(({
+  image,
+  width,
+  height,
+  fallback,
+}: ImageThumbnailProps) => {
+  const [thumbnailData, setThumbnailData] = useState<ThumbnailData | null>(null)
+
+  useEffect(() => {
+    // Skip loading while image is processing or has error to avoid race condition and unnecessary failed reads
+    if ((image.status ?? 'ready') !== 'ready') return
+
+    let cancelled = false
+
+    const loadThumbnail = async () => {
+      let data: ThumbnailData | null = null
+      try {
+        if (image.processedImage) {
+          const imageBuffer = Buffer.from(image.processedImage.base64, 'base64')
+          data = await extractThumbnailColors(imageBuffer, width, height)
+        } else if (!image.path.startsWith('clipboard:')) {
+          data = await extractThumbnailColors(image.path, width, height)
+        }
+      } catch {
+        // Ignore errors, will show fallback
+      }
+
+      if (!cancelled) {
+        setThumbnailData(data)
+      }
+    }
+
+    loadThumbnail()
+
+    return () => {
+      cancelled = true
+    }
+  }, [image, width, height])
+
+  if (!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>
+  )
+})

package/src/components/input-cursor.tsx

@@ -0,0 +1,77 @@
+import { TextAttributes } from '@opentui/core'
+import React, { useEffect, useRef, useState } from 'react'
+
+interface InputCursorProps {
+  visible: boolean
+  focused: boolean
+  shouldBlink?: boolean
+  char?: string
+  color?: string
+  blinkDelay?: number
+  blinkInterval?: number
+  bold?: boolean
+}
+
+export const InputCursor: React.FC<InputCursorProps> = ({
+  visible,
+  focused,
+  shouldBlink = true,
+  char = '▍',
+  color,
+  blinkDelay = 500,
+  blinkInterval = 500,  // Faster blinking
+  bold = true,
+}) => {
+  // false = normal/visible, true = invisible
+  const [isInvisible, setIsInvisible] = useState(false)
+  const blinkIntervalRef = useRef<NodeJS.Timeout | null>(null)
+
+  // Handle blinking (toggle visible/invisible) when idle
+  useEffect(() => {
+    // Clear any existing interval
+    if (blinkIntervalRef.current) {
+      clearInterval(blinkIntervalRef.current)
+      blinkIntervalRef.current = null
+    }
+
+    // Reset cursor to visible
+    setIsInvisible(false)
+
+    // Only blink if shouldBlink is enabled, focused, and visible
+    if (!shouldBlink || !focused || !visible) return
+
+    // Set up idle detection
+    const idleTimer = setTimeout(() => {
+      // Start blinking interval (toggle between visible and invisible)
+      blinkIntervalRef.current = setInterval(() => {
+        setIsInvisible((prev) => !prev)
+      }, blinkInterval)
+    }, blinkDelay)
+
+    return () => {
+      clearTimeout(idleTimer)
+      if (blinkIntervalRef.current) {
+        clearInterval(blinkIntervalRef.current)
+        blinkIntervalRef.current = null
+      }
+    }
+  }, [visible, focused, shouldBlink, blinkDelay, blinkInterval])
+
+  if (!visible || !focused) {
+    return null
+  }
+
+  // When invisible, return a space to maintain layout
+  if (isInvisible) {
+    return <span> </span>
+  }
+
+  return (
+    <span
+      {...(color ? { fg: color } : undefined)}
+      {...(bold ? { attributes: TextAttributes.BOLD } : undefined)}
+    >
+      {char}
+    </span>
+  )
+}

package/src/components/input-mode-banner.tsx

@@ -0,0 +1,57 @@
+import React from 'react'
+import { IS_FREEBUFF } from '../utils/constants'
+
+import { HelpBanner } from './help-banner'
+import { PendingAttachmentsBanner } from './pending-attachments-banner'
+import { SubscriptionLimitBanner } from './subscription-limit-banner'
+import { UsageBanner } from './usage-banner'
+import { useChatStore } from '../state/chat-store'
+
+/**
+ * Registry mapping input modes to their banner components.
+ *
+ * To add a new banner:
+ * 1. Create the banner component using BottomBanner
+ * 2. Add an entry here mapping the input mode to a render function
+ *
+ * Render functions receive context (like showTime) and return the component.
+ */
+const BANNER_REGISTRY: Record<
+  string,
+  (ctx: { showTime: number }) => React.ReactNode
+> = {
+  default: () => <PendingAttachmentsBanner />,
+  image: () => <PendingAttachmentsBanner />,
+  ...(IS_FREEBUFF ? {} : { usage: ({ showTime }: { showTime: number }) => <UsageBanner showTime={showTime} /> }),
+  help: () => <HelpBanner />,
+  ...(IS_FREEBUFF ? {} : { subscriptionLimit: () => <SubscriptionLimitBanner /> }),
+}
+
+/**
+ * Banner component that shows contextual information below the input box.
+ * Shows mode-specific banners based on the current input mode.
+ *
+ * Uses a registry pattern for easy extensibility - add new banners by
+ * updating BANNER_REGISTRY above.
+ */
+export const InputModeBanner = () => {
+  const inputMode = useChatStore((state) => state.inputMode)
+
+  const [usageBannerShowTime, setUsageBannerShowTime] = React.useState(() =>
+    Date.now(),
+  )
+
+  React.useEffect(() => {
+    if (inputMode === 'usage') {
+      setUsageBannerShowTime(Date.now())
+    }
+  }, [inputMode])
+
+  const renderBanner = BANNER_REGISTRY[inputMode]
+
+  if (!renderBanner) {
+    return null
+  }
+
+  return <>{renderBanner({ showTime: usageBannerShowTime })}</>
+}