@alumbwe/anvil 1.0.0

package/src/hooks/use-terminal-breakpoints.ts

@@ -0,0 +1,77 @@
+import { useRenderer } from '@opentui/react'
+import { useMemo } from 'react'
+
+export interface TerminalBreakpoints {
+  // Width-based
+  width: number
+  isNarrow: boolean // < 60 cols
+  isMediumWidth: boolean // >= 60 && < 100
+  isWide: boolean // >= 100 cols
+
+  // Height-based
+  height: number
+  isVerySmall: boolean // < 15 rows (minimal UI)
+  isSmall: boolean // >= 15 && < 20 rows (compact UI)
+  isMedium: boolean // >= 20 && < 30 rows (standard UI)
+  isLarge: boolean // >= 30 rows (spacious UI)
+  isTall: boolean // >= 20 rows (alias for backward compatibility)
+}
+
+const WIDTH_BREAKPOINTS = {
+  narrow: 60,
+  mediumWidth: 100,
+} as const
+
+const HEIGHT_BREAKPOINTS = {
+  verySmall: 15,
+  small: 20,
+  medium: 30,
+} as const
+
+/**
+ * Hook to get responsive breakpoints based on terminal dimensions.
+ * Similar to useMediaQuery in web apps, but for terminal-based UIs.
+ *
+ * @returns Object with terminal dimensions and boolean breakpoint flags
+ *
+ * @example
+ * const { isNarrow, isVerySmall, width, height } = useTerminalBreakpoints()
+ *
+ * // Use breakpoints for conditional rendering
+ * {isNarrow && <CompactView />}
+ * {!isNarrow && <FullView />}
+ *
+ * // Use dimensions for calculations
+ * const maxWidth = Math.min(width - 10, 100)
+ */
+export const useTerminalBreakpoints = (): TerminalBreakpoints => {
+  const renderer = useRenderer()
+
+  return useMemo(() => {
+    const width = renderer?.width || 80
+    const height = renderer?.height || 24
+
+    return {
+      width,
+      height,
+
+      // Width breakpoints
+      isNarrow: width < WIDTH_BREAKPOINTS.narrow,
+      isMediumWidth:
+        width >= WIDTH_BREAKPOINTS.narrow &&
+        width < WIDTH_BREAKPOINTS.mediumWidth,
+      isWide: width >= WIDTH_BREAKPOINTS.mediumWidth,
+
+      // Height breakpoints
+      isVerySmall: height < HEIGHT_BREAKPOINTS.verySmall,
+      isSmall:
+        height >= HEIGHT_BREAKPOINTS.verySmall &&
+        height < HEIGHT_BREAKPOINTS.small,
+      isMedium:
+        height >= HEIGHT_BREAKPOINTS.small &&
+        height < HEIGHT_BREAKPOINTS.medium,
+      isLarge: height >= HEIGHT_BREAKPOINTS.medium,
+      isTall: height >= HEIGHT_BREAKPOINTS.small, // Alias for backward compatibility
+    }
+  }, [renderer?.width, renderer?.height])
+}

package/src/hooks/use-terminal-dimensions.ts

@@ -0,0 +1,46 @@
+import { useRenderer, useTerminalDimensions as useOpenTuiDimensions } from '@opentui/react'
+import { useMemo } from 'react'
+
+export const useTerminalDimensions = () => {
+  const renderer = useRenderer()
+  const { width: measuredWidth } = useOpenTuiDimensions()
+
+  const sanitizeDimension = (
+    value: number | null | undefined,
+  ): number | null => {
+    if (typeof value !== 'number') return null
+    if (!Number.isFinite(value) || value <= 0) return null
+    return value
+  }
+
+  const resolvedTerminalWidth = useMemo(
+    () =>
+      sanitizeDimension(measuredWidth) ?? sanitizeDimension(renderer?.width) ?? 80,
+    [measuredWidth, renderer?.width],
+  )
+
+  const resolvedTerminalHeight = useMemo(
+    () => sanitizeDimension(renderer?.height) ?? 24,
+    [renderer?.height],
+  )
+
+  const terminalWidth = resolvedTerminalWidth
+  const terminalHeight = resolvedTerminalHeight
+
+  const separatorWidth = useMemo(
+    () => Math.max(1, Math.floor(terminalWidth) - 2),
+    [terminalWidth],
+  )
+
+  const contentMaxWidth = useMemo(
+    () => Math.max(10, Math.min(terminalWidth - 4, 80)),
+    [terminalWidth],
+  )
+
+  return {
+    terminalWidth,
+    terminalHeight,
+    separatorWidth,
+    contentMaxWidth,
+  }
+}

package/src/hooks/use-terminal-focus.ts

@@ -0,0 +1,29 @@
+import { useEffect } from 'react'
+
+import { logger } from '../utils/logger'
+import { getTerminalProtocolController } from '../utils/terminal-protocol-controller'
+
+export interface UseTerminalFocusOptions {
+  onFocusChange: (focused: boolean) => void
+  onSupportDetected?: () => void
+}
+
+/**
+ * Subscribe to the terminal protocol controller's parsed focus state. OpenTUI
+ * owns normal terminal input, while the controller enables focus reports for
+ * the lifetime of the active subscribers.
+ */
+export function useTerminalFocus({
+  onFocusChange,
+  onSupportDetected,
+}: UseTerminalFocusOptions): void {
+  useEffect(() => {
+    const controller = getTerminalProtocolController()
+    if (!controller) {
+      logger.debug({}, 'Terminal protocol controller is not installed')
+      return
+    }
+
+    return controller.subscribeToFocus({ onFocusChange, onSupportDetected })
+  }, [onFocusChange, onSupportDetected])
+}

package/src/hooks/use-terminal-layout.ts

@@ -0,0 +1,189 @@
+import { useMemo } from 'react'
+
+import { useTerminalDimensions } from './use-terminal-dimensions'
+
+/**
+ * Terminal width layout size breakpoints (Tailwind-style naming)
+ * - xs: Extra small/narrow terminals (< 80 cols) - minimize UI chrome
+ * - sm: Small/standard terminal widths (80-120 cols) - balanced layout
+ * - md: Medium/wide terminals (120-160 cols) - extra spacing/features
+ * - lg: Large/fullscreen terminals (> 160 cols) - maximum real estate
+ */
+export type TerminalWidthSize = 'xs' | 'sm' | 'md' | 'lg'
+
+/**
+ * Terminal height layout size breakpoints (Tailwind-style naming)
+ * - xs: Extra small/short terminals (< 20 rows) - minimize vertical chrome
+ * - sm: Small/standard terminal heights (20-40 rows) - balanced layout
+ * - md: Medium/tall terminals (> 40 rows) - extra vertical space available
+ */
+export type TerminalHeightSize = 'xs' | 'sm' | 'md'
+
+// Width breakpoints
+export const WIDTH_XS_BREAKPOINT = 50
+export const WIDTH_MD_BREAKPOINT = 100
+export const WIDTH_LG_BREAKPOINT = 150
+
+// Height breakpoints
+export const HEIGHT_XS_BREAKPOINT = 20
+export const HEIGHT_MD_BREAKPOINT = 40
+
+/** Ordered list of width sizes from smallest to largest */
+const WIDTH_SIZE_ORDER: TerminalWidthSize[] = ['xs', 'sm', 'md', 'lg']
+
+/** Ordered list of height sizes from smallest to largest */
+const HEIGHT_SIZE_ORDER: TerminalHeightSize[] = ['xs', 'sm', 'md']
+
+/**
+ * Helper object for checking width layout size.
+ * Provides type-safe methods that enforce mutual exclusivity.
+ */
+export interface WidthLayoutHelper {
+  /** Current layout size */
+  size: TerminalWidthSize
+  /** Check if current size exactly matches the given size */
+  is: (size: TerminalWidthSize) => boolean
+  /** Check if current size is at least the given size (inclusive) */
+  atLeast: (size: TerminalWidthSize) => boolean
+  /** Check if current size is at most the given size (inclusive) */
+  atMost: (size: TerminalWidthSize) => boolean
+}
+
+/**
+ * Helper object for checking height layout size.
+ * Provides type-safe methods that enforce mutual exclusivity.
+ */
+export interface HeightLayoutHelper {
+  /** Current layout size */
+  size: TerminalHeightSize
+  /** Check if current size exactly matches the given size */
+  is: (size: TerminalHeightSize) => boolean
+  /** Check if current size is at least the given size (inclusive) */
+  atLeast: (size: TerminalHeightSize) => boolean
+  /** Check if current size is at most the given size (inclusive) */
+  atMost: (size: TerminalHeightSize) => boolean
+}
+
+export interface TerminalLayout {
+  /** Width layout helper with is/atLeast/atMost methods */
+  width: WidthLayoutHelper
+  /** Height layout helper with is/atLeast/atMost methods */
+  height: HeightLayoutHelper
+  /** Raw terminal width in columns */
+  terminalWidth: number
+  /** Raw terminal height in rows */
+  terminalHeight: number
+}
+
+/**
+ * Create a width layout helper for a given size.
+ */
+const createWidthHelper = (size: TerminalWidthSize): WidthLayoutHelper => {
+  const sizeIndex = WIDTH_SIZE_ORDER.indexOf(size)
+
+  return {
+    size,
+    is: (targetSize: TerminalWidthSize) => size === targetSize,
+    atLeast: (targetSize: TerminalWidthSize) => {
+      const targetIndex = WIDTH_SIZE_ORDER.indexOf(targetSize)
+      return sizeIndex >= targetIndex
+    },
+    atMost: (targetSize: TerminalWidthSize) => {
+      const targetIndex = WIDTH_SIZE_ORDER.indexOf(targetSize)
+      return sizeIndex <= targetIndex
+    },
+  }
+}
+
+/**
+ * Create a height layout helper for a given size.
+ */
+const createHeightHelper = (size: TerminalHeightSize): HeightLayoutHelper => {
+  const sizeIndex = HEIGHT_SIZE_ORDER.indexOf(size)
+
+  return {
+    size,
+    is: (targetSize: TerminalHeightSize) => size === targetSize,
+    atLeast: (targetSize: TerminalHeightSize) => {
+      const targetIndex = HEIGHT_SIZE_ORDER.indexOf(targetSize)
+      return sizeIndex >= targetIndex
+    },
+    atMost: (targetSize: TerminalHeightSize) => {
+      const targetIndex = HEIGHT_SIZE_ORDER.indexOf(targetSize)
+      return sizeIndex <= targetIndex
+    },
+  }
+}
+
+/**
+ * Determine the width layout size from terminal width.
+ */
+const getWidthSize = (terminalWidth: number): TerminalWidthSize => {
+  if (terminalWidth < WIDTH_XS_BREAKPOINT) {
+    return 'xs'
+  } else if (terminalWidth > WIDTH_LG_BREAKPOINT) {
+    return 'lg'
+  } else if (terminalWidth > WIDTH_MD_BREAKPOINT) {
+    return 'md'
+  } else {
+    return 'sm'
+  }
+}
+
+/**
+ * Determine the height layout size from terminal height.
+ */
+const getHeightSize = (terminalHeight: number): TerminalHeightSize => {
+  if (terminalHeight < HEIGHT_XS_BREAKPOINT) {
+    return 'xs'
+  } else if (terminalHeight > HEIGHT_MD_BREAKPOINT) {
+    return 'md'
+  } else {
+    return 'sm'
+  }
+}
+
+/**
+ * Pure function to compute terminal layout from dimensions.
+ * Exported for testing purposes.
+ */
+export const computeTerminalLayout = (
+  terminalWidth: number,
+  terminalHeight: number,
+): TerminalLayout => {
+  const widthSize = getWidthSize(terminalWidth)
+  const heightSize = getHeightSize(terminalHeight)
+
+  return {
+    width: createWidthHelper(widthSize),
+    height: createHeightHelper(heightSize),
+    terminalWidth,
+    terminalHeight,
+  }
+}
+
+/**
+ * Hook providing semantic terminal layout information.
+ * Use this instead of raw dimension checks for responsive terminal UI.
+ *
+ * @example
+ * const { width, height } = useTerminalLayout()
+ *
+ * // Check exact size
+ * if (width.is('xs')) { ... }  // extra small (< 80 cols)
+ * if (height.is('xs')) { ... } // extra small (< 20 rows)
+ *
+ * // Check ranges
+ * if (width.atLeast('sm')) { ... }  // sm, md, or lg
+ * if (height.atMost('sm')) { ... }  // xs or sm
+ */
+export const useTerminalLayout = (): TerminalLayout => {
+  const { terminalWidth, terminalHeight } = useTerminalDimensions()
+
+  const layout = useMemo(
+    () => computeTerminalLayout(terminalWidth, terminalHeight),
+    [terminalWidth, terminalHeight],
+  )
+
+  return layout
+}

package/src/hooks/use-theme.tsx

@@ -0,0 +1,140 @@
+/**
+ * Theme Hooks
+ *
+ * Simple hooks for accessing theme from zustand store
+ */
+
+import { create } from 'zustand'
+
+import { getCliEnv } from '../utils/env'
+import { themeConfig, buildTheme } from '../utils/theme-config'
+import {
+  chatThemes,
+  cloneChatTheme,
+  detectIDETheme,
+  detectPlatformTheme,
+  detectTerminalOverrides,
+  getOscDetectedTheme,
+  initializeThemeWatcher,
+  setThemeResolver,
+  setLastDetectedTheme,
+  setupFileWatchers,
+} from '../utils/theme-system'
+
+import type { ChatTheme, ThemeName } from '../types/theme-system'
+import type { StoreApi, UseBoundStore } from 'zustand'
+
+type ThemeStore = {
+  theme: ChatTheme
+  setThemeName: (name: ThemeName) => void
+}
+
+export let useThemeStore: UseBoundStore<StoreApi<ThemeStore>> = (() => {
+  throw new Error('useThemeStore not initialized')
+}) as any
+let themeStoreInitialized = false
+
+type ThemeDetector = {
+  description: string
+  detect: () => ThemeName | null
+}
+
+const THEME_PRIORITY: ThemeDetector[] = [
+  {
+    description: 'Terminal override (e.g., OPENAI_THEME)',
+    detect: detectTerminalOverrides,
+  },
+  {
+    description: 'IDE configuration (VS Code, JetBrains, Zed)',
+    detect: detectIDETheme,
+  },
+  {
+    description: 'OSC terminal colors',
+    detect: () => getOscDetectedTheme(),
+  },
+  {
+    description: 'Operating system theme',
+    detect: detectPlatformTheme,
+  },
+]
+
+export const detectSystemTheme = (): ThemeName => {
+  const env = getCliEnv()
+  const envPreference = env.OPEN_TUI_THEME ?? env.OPENTUI_THEME
+  const normalizedEnv = envPreference?.toLowerCase()
+
+  if (normalizedEnv === 'dark' || normalizedEnv === 'light') {
+    return normalizedEnv
+  }
+
+  const preferredTheme = (): ThemeName => {
+    for (const detector of THEME_PRIORITY) {
+      const result = detector.detect()
+      if (result) {
+        return result
+      }
+    }
+    return 'dark'
+  }
+
+  const resolved = preferredTheme()
+
+  if (normalizedEnv === 'opposite') {
+    return resolved === 'dark' ? 'light' : 'dark'
+  }
+
+  return resolved
+}
+
+export function initializeThemeStore() {
+  if (themeStoreInitialized) {
+    return
+  }
+  themeStoreInitialized = true
+
+  setThemeResolver(detectSystemTheme)
+  setupFileWatchers()
+
+  const initialThemeName = detectSystemTheme()
+  setLastDetectedTheme(initialThemeName)
+  const initialTheme = buildTheme(
+    cloneChatTheme(chatThemes[initialThemeName]),
+    initialThemeName,
+    themeConfig.customColors,
+    themeConfig.plugins,
+  )
+
+  useThemeStore = create<ThemeStore>((set, get) => ({
+    theme: initialTheme,
+
+    setThemeName: (name: ThemeName) => {
+      const currentTheme = get().theme
+      
+      // Skip if theme name hasn't changed
+      if (currentTheme.name === name) {
+        return
+      }
+
+      const baseTheme = cloneChatTheme(chatThemes[name])
+      const theme = buildTheme(
+        baseTheme,
+        name,
+        themeConfig.customColors,
+        themeConfig.plugins,
+      )
+      set({ theme })
+    },
+  }))
+
+  // Set up the theme watcher for reactive updates when system theme changes
+  initializeThemeWatcher((name: ThemeName) => {
+    useThemeStore.getState().setThemeName(name)
+  })
+
+  // Note: OSC detection is done earlier in index.tsx before OpenTUI starts,
+  // so the result is already available via getOscDetectedTheme()
+}
+
+export const useTheme = (): ChatTheme => {
+  return useThemeStore((state) => state.theme)
+}

package/src/hooks/use-timeout.ts

@@ -0,0 +1,85 @@
+import { useCallback, useEffect, useRef } from 'react'
+
+/**
+ * Hook to safely manage multiple timeouts with automatic cleanup
+ *
+ * Provides setTimeout and clearTimeout methods that manage timeouts by key,
+ * similar to TanStack Query's key-based API. All timeouts are automatically
+ * cleaned up on component unmount.
+ *
+ * @returns Object with setTimeout and clearTimeout methods
+ *
+ * @example
+ * const { setTimeout, clearTimeout } = useTimeout()
+ *
+ * // Schedule multiple timeouts with different keys
+ * setTimeout('message', () => {
+ *   console.log('Message timeout')
+ * }, 1000)
+ *
+ * setTimeout('notification', () => {
+ *   console.log('Notification timeout')
+ * }, 2000)
+ *
+ * // Clear a specific timeout by key
+ * clearTimeout('message')
+ *
+ * // Clear all timeouts
+ * clearTimeout()
+ *
+ * // Replace existing timeout with same key
+ * setTimeout('message', () => console.log('First'), 1000)
+ * setTimeout('message', () => console.log('Second'), 2000) // Cancels first, schedules second
+ */
+export function useTimeout() {
+  const timeoutsRef = useRef<Map<string, NodeJS.Timeout>>(new Map())
+
+  const setTimeout = useCallback((key: string, callback: () => void, delay: number) => {
+    const timeouts = timeoutsRef.current
+
+    // Clear existing timeout for this key if it exists
+    const existingTimeout = timeouts.get(key)
+    if (existingTimeout) {
+      globalThis.clearTimeout(existingTimeout)
+    }
+
+    // Set new timeout with automatic cleanup after execution
+    const timeoutId = globalThis.setTimeout(() => {
+      callback()
+      timeouts.delete(key)
+    }, delay)
+    timeouts.set(key, timeoutId)
+  }, [])
+
+  const clearTimeout = useCallback((key?: string) => {
+    const timeouts = timeoutsRef.current
+
+    if (key) {
+      // Clear specific timeout
+      const timeoutId = timeouts.get(key)
+      if (timeoutId) {
+        globalThis.clearTimeout(timeoutId)
+        timeouts.delete(key)
+      }
+    } else {
+      // Clear all timeouts
+      timeouts.forEach((timeoutId) => {
+        globalThis.clearTimeout(timeoutId)
+      })
+      timeouts.clear()
+    }
+  }, [])
+
+  useEffect(() => {
+    return () => {
+      // Clean up all timeouts on unmount
+      const timeouts = timeoutsRef.current
+      timeouts.forEach((timeoutId) => {
+        globalThis.clearTimeout(timeoutId)
+      })
+      timeouts.clear()
+    }
+  }, [])
+
+  return { setTimeout, clearTimeout }
+}

package/src/hooks/use-update-preference.ts

@@ -0,0 +1,66 @@
+import { useCallback, useState } from 'react'
+
+import {
+  getActivityQueryData,
+  invalidateActivityQuery,
+  setActivityQueryData,
+} from './use-activity-query'
+import { subscriptionQueryKeys } from './use-subscription-query'
+import { showClipboardMessage } from '../utils/clipboard'
+import { getApiClient } from '../utils/anvil-api'
+import { logger } from '../utils/logger'
+
+import type { SubscriptionResponse } from '@anvil/common/types/subscription'
+
+interface UpdatePreferenceParams {
+  fallbackToALaCarte?: boolean
+}
+
+export function useUpdatePreference() {
+  const [isPending, setIsPending] = useState(false)
+
+  const mutate = useCallback(async (params: UpdatePreferenceParams) => {
+    const queryKey = subscriptionQueryKeys.current()
+
+    // Snapshot the previous value for rollback
+    const previousData = getActivityQueryData<SubscriptionResponse>(queryKey)
+
+    // Optimistically update to the new value
+    if (previousData && params.fallbackToALaCarte !== undefined) {
+      setActivityQueryData<SubscriptionResponse>(queryKey, {
+        ...previousData,
+        fallbackToALaCarte: params.fallbackToALaCarte,
+      })
+    }
+
+    setIsPending(true)
+
+    try {
+      const client = getApiClient()
+      const response = await client.patch<{ success: boolean; error?: string }>(
+        '/api/user/preferences',
+        params as Record<string, unknown>,
+        { includeCookie: true },
+      )
+
+      if (!response.ok) {
+        const errorMessage = response.error || 'Failed to update preference'
+        throw new Error(errorMessage)
+      }
+
+      // Invalidate to refetch fresh data from server
+      invalidateActivityQuery(queryKey)
+    } catch (err) {
+      // Rollback to previous value on error
+      if (previousData) {
+        setActivityQueryData(queryKey, previousData)
+      }
+      logger.error({ err }, 'Failed to update preference')
+      showClipboardMessage('Failed to update preference', { durationMs: 3000 })
+    } finally {
+      setIsPending(false)
+    }
+  }, [])
+
+  return { mutate, isPending }
+}

package/src/hooks/use-usage-monitor.ts

@@ -0,0 +1,55 @@
+import { useEffect, useRef } from 'react'
+
+import { useUsageQuery } from './use-usage-query'
+import { IS_FREEBUFF } from '../utils/constants'
+import { useChatStore } from '../state/chat-store'
+import { getAuthToken } from '../utils/auth'
+import { shouldAutoShowBanner } from '../utils/usage-banner-state'
+
+/**
+ * Hook that monitors usage data and auto-shows the usage banner
+ * when credit thresholds are crossed.
+ * 
+ * This should be placed in a component that's always mounted (like Chat)
+ * so monitoring happens continuously, not just when the banner is visible.
+ */
+export function useUsageMonitor() {
+  const isChainInProgress = useChatStore((state) => state.isChainInProgress)
+  const sessionCreditsUsed = useChatStore((state) => state.sessionCreditsUsed)
+  const setInputMode = useChatStore((state) => state.setInputMode)
+  const lastWarnedThresholdRef = useRef<number | null>(null)
+
+  // Query usage data - this will refetch when invalidated after message completion
+  const { data: usageData } = useUsageQuery({ enabled: !IS_FREEBUFF })
+
+  useEffect(() => {
+    if (IS_FREEBUFF) return
+
+    // Only show after user has sent at least one message (to avoid overwhelming on app start)
+    if (sessionCreditsUsed === 0) {
+      return
+    }
+
+    const authToken = getAuthToken()
+    const remainingBalance = usageData?.remainingBalance ?? null
+    const autoTopupEnabled = usageData?.autoTopupEnabled ?? false
+
+    const decision = shouldAutoShowBanner(
+      isChainInProgress,
+      !!authToken,
+      remainingBalance,
+      lastWarnedThresholdRef.current,
+      autoTopupEnabled,
+    )
+
+    // Update the last warned threshold
+    if (decision.newWarningThreshold !== lastWarnedThresholdRef.current) {
+      lastWarnedThresholdRef.current = decision.newWarningThreshold
+    }
+
+    // Show the usage banner if we should
+    if (decision.shouldShow) {
+      setInputMode('usage')
+    }
+  }, [isChainInProgress, usageData, sessionCreditsUsed, setInputMode])
+}