@alumbwe/anvil 1.0.0

package/src/utils/input-modes.ts

@@ -0,0 +1,174 @@
+import { IS_FREEBUFF } from './constants'
+
+// Input mode types and configurations
+// To add a new mode:
+// 1. Add it to the InputMode type
+// 2. Add its configuration to INPUT_MODE_CONFIGS
+
+export type InputMode =
+  | 'default'
+  | 'bash'
+  | 'homeDir'
+  | 'plan'
+  | 'review'
+  | 'interview'
+  | 'usage'
+  | 'image'
+  | 'help'
+  | 'outOfCredits'
+  | 'subscriptionLimit'
+
+// Theme color keys that are valid color values (must match ChatTheme keys)
+export type ThemeColorKey =
+  | 'foreground'
+  | 'background'
+  | 'error'
+  | 'warning'
+  | 'success'
+  | 'info'
+  | 'muted'
+  | 'imageCardBorder'
+  | 'link'
+
+export type InputModeConfig = {
+  /** Prefix icon shown before input (e.g., "!" for bash) */
+  icon: string | null
+  /** Colored label shown before input (e.g., "Plan") */
+  label: string | null
+  /** Theme color key for icon and border */
+  color: ThemeColorKey
+  /** Input placeholder text */
+  placeholder: string
+  /** Width adjustment for the prefix (icon width + padding) */
+  widthAdjustment: number
+  /** Whether to show the agent mode toggle */
+  showAgentModeToggle: boolean
+  /** Whether to disable slash command suggestions */
+  disableSlashSuggestions: boolean
+  /** Whether keyboard shortcuts (Escape, Backspace) can exit this mode */
+  blockKeyboardExit: boolean
+}
+
+export const INPUT_MODE_CONFIGS: Record<InputMode, InputModeConfig> = {
+  default: {
+    icon: null,
+    label: null,
+    color: 'foreground',
+    placeholder: 'enter a coding task or / for commands',
+    widthAdjustment: 0,
+    showAgentModeToggle: true,
+    disableSlashSuggestions: false,
+    blockKeyboardExit: false,
+  },
+  bash: {
+    icon: null,
+    label: '!',
+    color: 'info',
+    placeholder: 'enter bash command...',
+    widthAdjustment: 4, // ` ! ` (3 chars) + 1 padding
+    showAgentModeToggle: false,
+    disableSlashSuggestions: true,
+    blockKeyboardExit: false,
+  },
+  homeDir: {
+    icon: null,
+    label: null,
+    color: 'warning',
+    placeholder: 'enter a coding task or / for commands',
+    widthAdjustment: 0,
+    showAgentModeToggle: true,
+    disableSlashSuggestions: false,
+    blockKeyboardExit: false,
+  },
+  interview: {
+    icon: null,
+    label: 'Interview',
+    color: 'info',
+    placeholder: 'describe a feature/bug or other request to be fleshed out...',
+    widthAdjustment: 12,
+    showAgentModeToggle: false,
+    disableSlashSuggestions: true,
+    blockKeyboardExit: false,
+  },
+  plan: {
+    icon: null,
+    label: 'Plan',
+    color: 'info',
+    placeholder: 'describe what you want to plan...',
+    widthAdjustment: 7,
+    showAgentModeToggle: false,
+    disableSlashSuggestions: true,
+    blockKeyboardExit: false,
+  },
+  review: {
+    icon: null,
+    label: 'Review',
+    color: 'info',
+    placeholder: 'describe what to review...',
+    widthAdjustment: 9,
+    showAgentModeToggle: false,
+    disableSlashSuggestions: true,
+    blockKeyboardExit: false,
+  },
+  usage: {
+    icon: null,
+    label: null,
+    color: 'foreground',
+    placeholder: 'enter a coding task or / for commands',
+    widthAdjustment: 0,
+    showAgentModeToggle: true,
+    disableSlashSuggestions: false,
+    blockKeyboardExit: false,
+  },
+  image: {
+    icon: '📎',
+    label: null,
+    color: 'imageCardBorder',
+    placeholder: 'enter image path or Ctrl+V to paste',
+    widthAdjustment: 3, // emoji width + padding
+    showAgentModeToggle: false,
+    disableSlashSuggestions: true,
+    blockKeyboardExit: false,
+  },
+  help: {
+    icon: null,
+    label: null,
+    color: 'info',
+    placeholder: 'enter a coding task or / for commands',
+    widthAdjustment: 0,
+    showAgentModeToggle: true,
+    disableSlashSuggestions: false,
+    blockKeyboardExit: false,
+  },
+  outOfCredits: {
+    icon: null,
+    label: null,
+    color: 'warning',
+    placeholder: '',
+    widthAdjustment: 0,
+    showAgentModeToggle: false,
+    disableSlashSuggestions: true,
+    blockKeyboardExit: false,
+  },
+  subscriptionLimit: {
+    icon: null,
+    label: null,
+    color: 'warning',
+    placeholder: '',
+    widthAdjustment: 0,
+    showAgentModeToggle: false,
+    disableSlashSuggestions: true,
+    blockKeyboardExit: true, // User must click "Continue with credits" or wait for reset
+  },
+}
+
+// In Freebuff, never show the agent mode toggle
+if (IS_FREEBUFF) {
+  for (const key of Object.keys(INPUT_MODE_CONFIGS) as InputMode[]) {
+    INPUT_MODE_CONFIGS[key].showAgentModeToggle = false
+  }
+}
+
+export function getInputModeConfig(mode: InputMode): InputModeConfig {
+  return INPUT_MODE_CONFIGS[mode]
+}

package/src/utils/keyboard-actions.ts

@@ -0,0 +1,392 @@
+import { getInputModeConfig, type InputMode } from './input-modes'
+import { isPlainEnterKey } from './terminal-enter-detection'
+import type { KeyEvent } from '@opentui/core'
+
+
+/**
+ * State needed to determine keyboard actions in chat input contexts.
+ * This is a focused subset of app state relevant to keyboard handling.
+ */
+export type ChatKeyboardState = {
+  // Input state
+  inputMode: InputMode
+  inputValue: string
+  cursorPosition: number
+
+  // Stream state
+  isStreaming: boolean
+  isWaitingForResponse: boolean
+
+  // Feedback mode
+  feedbackMode: boolean
+
+  // Focus state
+  focusedAgentId: string | null
+
+  // Menu state
+  slashMenuActive: boolean
+  mentionMenuActive: boolean
+  slashSelectedIndex: number
+  agentSelectedIndex: number
+  slashMatchesLength: number
+  totalMentionMatches: number
+  disableSlashSuggestions: boolean
+
+  // Queue state
+  queuePaused: boolean
+  queuedCount: number
+
+  // History navigation state
+  historyNavUpEnabled: boolean
+  historyNavDownEnabled: boolean
+
+  // Exit handler state
+  nextCtrlCWillExit: boolean
+}
+
+/**
+ * All possible keyboard actions for chat input.
+ * Each action represents a distinct behavior to be handled.
+ */
+export type ChatKeyboardAction =
+  // Mode actions
+  | { type: 'exit-input-mode' }
+  | { type: 'exit-feedback-mode' }
+  | { type: 'clear-feedback-input' }
+
+  // Input actions
+  | { type: 'clear-input' }
+  | { type: 'backspace-exit-mode' }
+
+  // Stream actions
+  | { type: 'interrupt-stream' }
+
+  // Menu navigation
+  | { type: 'slash-menu-down' }
+  | { type: 'slash-menu-up' }
+  | { type: 'slash-menu-select' }
+  | { type: 'slash-menu-complete' }
+  | { type: 'mention-menu-down' }
+  | { type: 'mention-menu-up' }
+  | { type: 'mention-menu-tab' }
+  | { type: 'mention-menu-shift-tab' }
+  | { type: 'mention-menu-select' }
+  | { type: 'mention-menu-complete' }
+  | { type: 'open-file-menu-with-tab' }
+
+  // History navigation
+  | { type: 'history-up' }
+  | { type: 'history-down' }
+
+  // Agent mode
+  | { type: 'toggle-agent-mode' }
+  | { type: 'unfocus-agent' }
+
+  // Toggle all collapsed/expanded
+  | { type: 'toggle-all' }
+
+  // Queue actions
+  | { type: 'clear-queue' }
+  | { type: 'open-queue-panel' }
+
+  // Exit actions
+  | { type: 'exit-app-warning' }
+  | { type: 'exit-app' }
+
+  // Bash history navigation
+  | { type: 'bash-history-up' }
+  | { type: 'bash-history-down' }
+
+  // Scroll actions
+  | { type: 'scroll-up' }
+  | { type: 'scroll-down' }
+
+  // Paste action (dispatcher checks clipboard content to route to image or text handler)
+  | { type: 'paste' }
+
+  // Out of credits action
+  | { type: 'open-buy-credits' }
+
+  // No action needed
+  | { type: 'none' }
+
+const hasModifier = (key: KeyEvent) =>
+  Boolean(key.ctrl || key.meta || key.option)
+
+/**
+ * Pure function that resolves a keyboard action based on key event and state.
+ * This implements the priority-based keyboard handling logic.
+ */
+export function resolveChatKeyboardAction(
+  key: KeyEvent,
+  state: ChatKeyboardState,
+): ChatKeyboardAction {
+  const isEscape = key.name === 'escape'
+  const isCtrlC = key.ctrl && key.name === 'c'
+  const isCtrlV = key.ctrl && key.name === 'v'
+  const isBackspace = key.name === 'backspace'
+  const isUp = key.name === 'up' && !hasModifier(key)
+  const isDown = key.name === 'down' && !hasModifier(key)
+  const isTab = key.name === 'tab' && !hasModifier(key)
+  const isShiftTab =
+    key.name === 'tab' && key.shift && !key.ctrl && !key.meta && !key.option
+  const isEnter = isPlainEnterKey(key)
+  const isPageUp = key.name === 'pageup' && !hasModifier(key)
+  const isPageDown = key.name === 'pagedown' && !hasModifier(key)
+
+  // Priority 0: Out of credits mode - Enter opens buy credits page
+  if (state.inputMode === 'outOfCredits') {
+    if (isEnter) {
+      return { type: 'open-buy-credits' }
+    }
+    // Allow Escape or Ctrl+C to exit out-of-credits mode (return to normal input)
+    if (isEscape || isCtrlC) {
+      return { type: 'exit-input-mode' }
+    }
+    // Block most other inputs in this mode
+    return { type: 'none' }
+  }
+
+  // Priority 1: Feedback mode - block global keys except Escape/Ctrl-C/Ctrl-V
+  if (state.feedbackMode) {
+    if (isEscape) {
+      return { type: 'exit-feedback-mode' }
+    }
+    if (isCtrlC) {
+      return state.inputValue.length === 0
+        ? { type: 'exit-feedback-mode' }
+        : { type: 'clear-feedback-input' }
+    }
+    if (isCtrlV) {
+      return { type: 'paste' }
+    }
+    return { type: 'none' }
+  }
+
+  // Priority 2: Non-default input mode escape
+  // Escape should exit the current mode BEFORE interrupting streams
+  // Exception: modes with blockKeyboardExit cannot be escaped
+  const modeConfig = getInputModeConfig(state.inputMode)
+  if (isEscape && state.inputMode !== 'default' && !modeConfig.blockKeyboardExit) {
+    return { type: 'exit-input-mode' }
+  }
+
+  // Priority 2.5: Open the queue editor (Ctrl+Q). Ahead of the ctrl-c rules
+  // below so it works with a half-typed message still in the composer; raw
+  // mode disables XON/XOFF, so ctrl-q is ours to use.
+  if (key.ctrl && key.name === 'q' && !key.meta && !key.option) {
+    return state.queuedCount > 0
+      ? { type: 'open-queue-panel' }
+      : { type: 'none' }
+  }
+
+  // Priority 3: Clear input with ctrl-c when there's text
+  if (isCtrlC && state.inputValue.trim().length > 0) {
+    return { type: 'clear-input' }
+  }
+
+  // Priority 4: Interrupt streaming
+  if (
+    (isEscape || isCtrlC) &&
+    (state.isStreaming || state.isWaitingForResponse)
+  ) {
+    return { type: 'interrupt-stream' }
+  }
+
+  // Priority 5: Backspace at position 0 exits non-default mode
+  // Exception: modes with blockKeyboardExit cannot be exited via keyboard
+  if (
+    isBackspace &&
+    state.cursorPosition === 0 &&
+    state.inputMode !== 'default' &&
+    !modeConfig.blockKeyboardExit &&
+    state.inputValue.length === 0
+  ) {
+    return { type: 'backspace-exit-mode' }
+  }
+
+  // Priority 6: Slash menu navigation (when active and not disabled)
+  // Skip menu navigation for Up/Down if history navigation is enabled (user is paging through history)
+  if (
+    state.slashMenuActive &&
+    state.slashMatchesLength > 0 &&
+    !state.disableSlashSuggestions
+  ) {
+    if (isDown) {
+      // If user is navigating history (historyNavDownEnabled), skip menu navigation entirely
+      if (state.historyNavDownEnabled) {
+        // Fall through to history navigation
+      } else if (state.slashSelectedIndex < state.slashMatchesLength - 1) {
+        return { type: 'slash-menu-down' }
+      } else {
+        return { type: 'none' } // At bottom, don't navigate
+      }
+    }
+    if (isUp) {
+      // If user is navigating history (historyNavUpEnabled), skip menu navigation entirely
+      if (state.historyNavUpEnabled) {
+        // Fall through to history navigation
+      } else if (state.slashSelectedIndex > 0) {
+        return { type: 'slash-menu-up' }
+      } else {
+        return { type: 'none' } // At top, don't navigate
+      }
+    }
+    if (isTab || isShiftTab) {
+      // Tab accepts the highlighted command into the input without executing
+      // it, leaving the cursor after it so the user can keep typing (e.g. extra
+      // params for a skill). Tab no longer navigates between items — use the
+      // arrow keys for that. Enter (below) selects the highlighted item; the
+      // command decides whether selection inserts text or executes immediately.
+      return { type: 'slash-menu-complete' }
+    }
+    if (isEnter) {
+      return { type: 'slash-menu-select' }
+    }
+  }
+
+  // Priority 7: Mention menu navigation (when active)
+  // Skip menu navigation for Up/Down if history navigation is enabled (user is paging through history)
+  if (state.mentionMenuActive && state.totalMentionMatches > 0) {
+    if (isDown) {
+      // If user is navigating history (historyNavDownEnabled), skip menu navigation entirely
+      if (state.historyNavDownEnabled) {
+        // Fall through to history navigation
+      } else if (state.agentSelectedIndex < state.totalMentionMatches - 1) {
+        return { type: 'mention-menu-down' }
+      } else {
+        return { type: 'none' } // At bottom, don't navigate
+      }
+    }
+    if (isUp) {
+      // If user is navigating history (historyNavUpEnabled), skip menu navigation entirely
+      if (state.historyNavUpEnabled) {
+        // Fall through to history navigation
+      } else if (state.agentSelectedIndex > 0) {
+        return { type: 'mention-menu-up' }
+      } else {
+        return { type: 'none' } // At top, don't navigate
+      }
+    }
+    if (isShiftTab) {
+      return { type: 'mention-menu-shift-tab' }
+    }
+    if (isTab) {
+      // Multiple matches: cycle through options
+      // Single match: complete the word without executing
+      if (state.totalMentionMatches > 1) {
+        return { type: 'mention-menu-tab' }
+      }
+      return { type: 'mention-menu-complete' }
+    }
+    if (isEnter) {
+      return { type: 'mention-menu-select' }
+    }
+  }
+
+  // Priority 8: Tab to open file menu (when not in a menu, not shift-tab, and suggestions enabled)
+  // This is handled by the hook since it needs to check word at cursor
+  if (
+    isTab &&
+    !key.shift &&
+    !state.mentionMenuActive &&
+    !state.slashMenuActive &&
+    !state.disableSlashSuggestions
+  ) {
+    return { type: 'open-file-menu-with-tab' }
+  }
+
+  // Priority 9: Queue management
+  if (isCtrlC && state.queuePaused && state.queuedCount > 0) {
+    return { type: 'clear-queue' }
+  }
+
+  // Priority 10: Bash history navigation (when in bash mode)
+  if (state.inputMode === 'bash') {
+    if (isUp && state.historyNavUpEnabled) {
+      return { type: 'bash-history-up' }
+    }
+    if (isDown && state.historyNavDownEnabled) {
+      return { type: 'bash-history-down' }
+    }
+  }
+
+  // Priority 10.5: Regular history navigation (when at edges and enabled)
+  if (isUp && state.historyNavUpEnabled) {
+    return { type: 'history-up' }
+  }
+  if (isDown && state.historyNavDownEnabled) {
+    return { type: 'history-down' }
+  }
+
+  // Priority 11: Toggle all collapsed/expanded (Ctrl+T)
+  const isCtrlT = key.ctrl && key.name === 't' && !key.meta && !key.option
+
+  if (isCtrlT) {
+    return { type: 'toggle-all' }
+  }
+
+  // Priority 12: Agent mode toggle (tab or shift-tab when not in menus)
+  if (
+    (isShiftTab || isTab) &&
+    !state.slashMenuActive &&
+    !state.mentionMenuActive
+  ) {
+    return { type: 'toggle-agent-mode' }
+  }
+
+  // Priority 13: Unfocus agent
+  if (isEscape && state.focusedAgentId !== null) {
+    return { type: 'unfocus-agent' }
+  }
+
+  // Priority 14: Scroll with PageUp/PageDown
+  if (isPageUp) {
+    return { type: 'scroll-up' }
+  }
+  if (isPageDown) {
+    return { type: 'scroll-down' }
+  }
+
+  // Priority 15: Paste (ctrl-v)
+  if (isCtrlV) {
+    return { type: 'paste' }
+  }
+
+  // Priority 16: Exit app (ctrl-c double-tap)
+  if (isCtrlC) {
+    if (state.nextCtrlCWillExit) {
+      return { type: 'exit-app' }
+    }
+    return { type: 'exit-app-warning' }
+  }
+
+  return { type: 'none' }
+}
+
+/**
+ * Creates default chat keyboard state for initialization.
+ */
+export function createDefaultChatKeyboardState(): ChatKeyboardState {
+  return {
+    inputMode: 'default',
+    inputValue: '',
+    cursorPosition: 0,
+    isStreaming: false,
+    isWaitingForResponse: false,
+    feedbackMode: false,
+    focusedAgentId: null,
+    slashMenuActive: false,
+    mentionMenuActive: false,
+    slashSelectedIndex: 0,
+    agentSelectedIndex: 0,
+    slashMatchesLength: 0,
+    totalMentionMatches: 0,
+    disableSlashSuggestions: false,
+    queuePaused: false,
+    queuedCount: 0,
+    historyNavUpEnabled: false,
+    historyNavDownEnabled: false,
+    nextCtrlCWillExit: false,
+  }
+}

package/src/utils/keypad-keys.ts

@@ -0,0 +1,47 @@
+type KeypadKey = {
+  name?: string
+  sequence?: string
+}
+
+const APPLICATION_KEYPAD_DIGITS = 'pqrstuvwxy'
+const KEYPAD_OPERATOR_NAMES: Record<string, string> = {
+  kpdecimal: '.',
+  kpdivide: '/',
+  kpmultiply: '*',
+  kpminus: '-',
+  kpplus: '+',
+  kpequal: '=',
+  kpseparator: ',',
+}
+
+const APPLICATION_KEYPAD_OPERATORS: Record<string, string> = {
+  n: '.',
+  o: '/',
+  j: '*',
+  m: '-',
+  k: '+',
+  X: '=',
+  l: ',',
+}
+
+export function isKeypadEnter(key: KeypadKey): boolean {
+  return key.name === 'kpenter' || key.sequence === '\x1bOM'
+}
+
+export function getKeypadPrintableSequence(key: KeypadKey): string | null {
+  const kittyDigit = /^kp([0-9])$/.exec(key.name ?? '')?.[1]
+  if (kittyDigit !== undefined) return kittyDigit
+
+  const kittyOperator = key.name ? KEYPAD_OPERATOR_NAMES[key.name] : undefined
+  if (kittyOperator !== undefined) return kittyOperator
+
+  if (!key.sequence?.startsWith('\x1bO') || key.sequence.length !== 3) {
+    return null
+  }
+
+  const applicationKey = key.sequence[2] ?? ''
+  const applicationDigit = APPLICATION_KEYPAD_DIGITS.indexOf(applicationKey)
+  if (applicationDigit >= 0) return String(applicationDigit)
+
+  return APPLICATION_KEYPAD_OPERATORS[applicationKey] ?? null
+}

package/src/utils/layout-helpers.ts

@@ -0,0 +1,33 @@
+/** Minimum width (in characters) for a grid column */
+export const MIN_COLUMN_WIDTH = 10
+
+/** Maximum nesting depth for agent blocks */
+export const MAX_AGENT_DEPTH = 10
+
+/** Horizontal padding (in characters) inside agent content boxes */
+export const AGENT_CONTENT_HORIZONTAL_PADDING = 12
+
+/**
+ * Compute the ideal number of columns for a grid layout.
+ * Tries to create a balanced grid (e.g. 2x2 instead of 3x1 + 1) while respecting max columns.
+ */
+export function computeSmartColumns(itemCount: number, maxColumns: number): number {
+  if (itemCount === 0) return 1
+  if (itemCount <= maxColumns) return itemCount
+
+  // If we can make a perfect grid with maxColumns, do it
+  if (itemCount % maxColumns === 0) return maxColumns
+
+  // Special case for 4 items on a 3-column screen: prefer 2x2 over 3+1
+  if (itemCount === 4 && maxColumns === 3) return 2
+
+  // Iterate down from maxColumns to find a divisor or better balance
+  // We prioritize using more columns (larger width) over perfect balance, unless it's very egregious
+  for (let c = maxColumns; c >= 2; c--) {
+    // If perfect match (divisor)
+    if (itemCount % c === 0) return c
+  }
+
+  // Default to max columns if no nice divisor found
+  return maxColumns
+}

package/src/utils/lazy-response-ads.ts

@@ -0,0 +1 @@
+export * from '@anvil/common/util/lazy-response-ads'