hermes-agent/apps/desktop/src/lib/keybinds/actions.ts

// The single source of truth for rebindable desktop hotkeys.
//
// Each entry is pure metadata: an id, a category, and the default combo(s).
// Handlers are wired separately in `use-keybinds.ts` (they need React context
// like navigate / theme); labels come from i18n (`t.keybinds.actions[id]`). To
// add a hotkey, add a row here and a handler there — nothing else.

import { registry } from '@/contrib/registry'

import { IS_MAC } from './combo'

export type KeybindCategory = 'composer' | 'profiles' | 'session' | 'navigation' | 'view'

// The self-referential opener — bound + dispatched like any action, but shown in
// the panel subtitle (not as its own row).
export const KEYBIND_PANEL_ACTION = 'keybinds.openPanel'

// `composer` is read-only; the rest are rebindable. `view` is the catch-all for
// layout, appearance, and the panel-opener.
export const KEYBIND_CATEGORIES: readonly KeybindCategory[] = ['composer', 'profiles', 'session', 'navigation', 'view']

export interface KeybindActionMeta {
  id: string
  category: KeybindCategory
  /** Default combos. Empty = shipped unbound (user can assign one). */
  defaults: readonly string[]
  /** Display label for CONTRIBUTED actions (built-ins use i18n). */
  label?: string
}

// Positional switch slots for *named* profiles: ⌘1…⌘9 for profiles 1-9, then
// ⌘⌥1…⌘⌥9 for 10-18. The default profile gets the two-key mnemonic ⌘D (see
// `profile.default`) — ⌘` is macOS-reserved (window cycling) and ⌘0 is reset-zoom.
export const PROFILE_SLOT_COUNT = 18

function comboForSlot(slot: number): string {
  return slot <= 9 ? `mod+${slot}` : `mod+alt+${slot - 9}`
}

const PROFILE_SWITCH_ACTIONS: KeybindActionMeta[] = Array.from({ length: PROFILE_SLOT_COUNT }, (_, i) => ({
  id: `profile.switch.${i + 1}`,
  category: 'profiles' as const,
  defaults: [comboForSlot(i + 1)]
}))

// Positional jumps — ^1…^9, mirroring profiles' ⌘1…⌘9.
export const SESSION_SLOT_COUNT = 9

const SESSION_SLOT_ACTIONS: KeybindActionMeta[] = Array.from({ length: SESSION_SLOT_COUNT }, (_, i) => ({
  id: `session.slot.${i + 1}`,
  category: 'session' as const,
  defaults: [`ctrl+${i + 1}`]
}))

export const KEYBIND_ACTIONS: readonly KeybindActionMeta[] = [
  // ── Composer ─────────────────────────────────────────────────────────────
  // Soft `/` / Enter focus (gated); other printables type-to-focus unbound.
  { id: 'composer.focus', category: 'composer', defaults: ['/', 'enter'] },
  { id: 'composer.modelPicker', category: 'composer', defaults: [] },
  // Voice conversation toggle. Matches the documented `voice.record_key`
  // (Ctrl+B). On macOS that's literally ⌃B — distinct from the ⌘B sidebar
  // toggle. Off macOS `ctrl` folds to `mod`, which IS the ⌘B/Ctrl+B sidebar
  // chord, so ship it unbound there (rebindable in the panel) rather than
  // stealing the long-standing sidebar binding.
  { id: 'composer.voice', category: 'composer', defaults: IS_MAC ? ['ctrl+b'] : [] },

  // ── Profiles ─────────────────────────────────────────────────────────────
  { id: 'profile.default', category: 'profiles', defaults: ['mod+d'] },
  ...PROFILE_SWITCH_ACTIONS,
  { id: 'profile.next', category: 'profiles', defaults: ['mod+shift+]'] },
  { id: 'profile.prev', category: 'profiles', defaults: ['mod+shift+['] },
  { id: 'profile.toggleAll', category: 'profiles', defaults: ['mod+shift+0'] },
  { id: 'profile.create', category: 'profiles', defaults: [] },

  // ── Session ──────────────────────────────────────────────────────────────
  { id: 'session.new', category: 'session', defaults: ['mod+n', 'shift+n'] },
  { id: 'session.newTab', category: 'session', defaults: ['mod+t'] },
  { id: 'session.newWindow', category: 'session', defaults: ['mod+shift+n'] },
  // ⌃Tab / ⌃⇧Tab — the universal tab-cycle chord. Literally Control, not Cmd
  // (macOS reserves Cmd+Tab for app switching); see `ctrl` in combo.ts.
  { id: 'session.next', category: 'session', defaults: ['ctrl+tab'] },
  { id: 'session.prev', category: 'session', defaults: ['ctrl+shift+tab'] },
  ...SESSION_SLOT_ACTIONS,
  { id: 'session.focusSearch', category: 'session', defaults: ['mod+shift+f'] },
  { id: 'session.togglePin', category: 'session', defaults: [] },
  // ⌘⇧B — "b" for branch: spin up a new git worktree from the active repo.
  { id: 'workspace.newWorktree', category: 'session', defaults: ['mod+shift+b'] },

  // ── Navigation ───────────────────────────────────────────────────────────
  { id: 'nav.commandPalette', category: 'navigation', defaults: ['mod+k', 'mod+p'] },
  { id: 'nav.commandCenter', category: 'navigation', defaults: ['mod+.'] },
  { id: 'nav.settings', category: 'navigation', defaults: ['mod+,'] },
  { id: 'nav.profiles', category: 'navigation', defaults: [] },
  { id: 'nav.skills', category: 'navigation', defaults: [] },
  { id: 'nav.messaging', category: 'navigation', defaults: [] },
  { id: 'nav.artifacts', category: 'navigation', defaults: [] },
  { id: 'nav.cron', category: 'navigation', defaults: [] },
  { id: 'nav.agents', category: 'navigation', defaults: [] },

  // ── View (layout + appearance + the shortcuts panel itself) ───────────────
  { id: 'view.toggleSidebar', category: 'view', defaults: ['mod+b'] },
  { id: 'view.toggleRightSidebar', category: 'view', defaults: ['mod+j'] },
  // ⌘⇧S — "s" for status bar. VS Code ships
  // `workbench.action.toggleStatusbarVisibility` unbound (it's a chord-free
  // gap in their View family) and Hermes has no chord dispatcher, so this
  // takes the nearest free single combo instead of a ⌘K ⌘S two-stroke.
  { id: 'view.toggleStatusbar', category: 'view', defaults: ['mod+shift+s'] },
  // ⌘G — "g" for git; the review pane is the source-control view.
  { id: 'view.toggleReview', category: 'view', defaults: ['mod+g'] },
  { id: 'view.showFiles', category: 'view', defaults: [] },
  // Control+` everywhere (literal `ctrl`, NOT `mod`): ⌘` is macOS-reserved for
  // cycling app windows, so VS Code/Cursor/Zed bind the terminal to Ctrl+` on
  // every platform. Off macOS `ctrl` folds to `mod` (= Ctrl), so it's unchanged.
  // Toggle reveals the terminal (opening one if none exist); Shift spawns a new one.
  { id: 'view.showTerminal', category: 'view', defaults: ['ctrl+`'] },
  { id: 'view.newTerminal', category: 'view', defaults: ['ctrl+shift+`'] },
  // Same Ctrl(+Shift) terminal family: arrows walk the (vertical) tab rail, W
  // kills the active one. ⌘W is taken (close preview tab) and ⌘⇧[ ] are profiles,
  // so these stay on `ctrl` — distinct on macOS, folding to Ctrl elsewhere.
  { id: 'view.nextTerminal', category: 'view', defaults: ['ctrl+shift+down'] },
  { id: 'view.prevTerminal', category: 'view', defaults: ['ctrl+shift+up'] },
  { id: 'view.closeTerminal', category: 'view', defaults: ['ctrl+shift+w'] },
  // ⌘\ — the backslash reads like a mirror line flipping the layout.
  { id: 'view.flipPanes', category: 'view', defaults: ['mod+\\'] },
  // ⌘W closes the focused zone's active tab — its own tab strip (preview) or
  // the tree tab (session tiles, files, terminal). The uncloseable workspace
  // is a no-op. ⌘⇧T reopens the last closed tab where it was.
  { id: 'view.closeTab', category: 'view', defaults: ['mod+w'] },
  { id: 'view.reopenTab', category: 'view', defaults: ['mod+shift+t'] },
  // ⌘F — open the find-in-page bar. `comboAllowedInInput` lets the combo
  // fire from inside a textarea / contenteditable (matches browser behavior
  // so typing in the composer and pressing ⌘F focuses find, not 'f').
  { id: 'view.findInPage', category: 'view', defaults: ['mod+f'] },
  // ⌘G / ⌘⇧G step matches — the platform-standard find-next/find-previous
  // pair (Chrome, Safari, VS Code, and Claude Desktop all ship it). No
  // `defaults` here on purpose: ⌘G already belongs to `view.toggleReview`,
  // and shipping a duplicate default would flag a permanent conflict in the
  // keybinds panel. While the find bar is OPEN, its capture-phase listener
  // claims ⌘G/⌘⇧G and stops propagation (see components/find-bar.tsx), so
  // stepping works out of the box and the review toggle keeps the key the
  // rest of the time. These entries exist so the panel documents the pair
  // and a user who prefers a dedicated chord can bind one.
  { id: 'view.findNext', category: 'view', defaults: [] },
  { id: 'view.findPrevious', category: 'view', defaults: [] },
  { id: 'appearance.toggleMode', category: 'view', defaults: ['shift+x'] },
  { id: 'keybinds.openPanel', category: 'view', defaults: ['mod+/'] }
]

export const KEYBIND_ACTION_IDS: readonly string[] = KEYBIND_ACTIONS.map(action => action.id)

const ACTION_BY_ID = new Map(KEYBIND_ACTIONS.map(action => [action.id, action]))

// ── Contributed actions — the `keybinds` registry area ──────────────────────
// Same declarative schema as every other surface: a data contribution carries
// the action's metadata AND its handler. Contributed actions are first-class:
// they dispatch, appear in the panel, are rebindable, and their overrides
// persist exactly like built-ins. Built-in ids can't be shadowed.

export const KEYBINDS_AREA = 'keybinds'

/** Payload of a `keybinds` data contribution. */
export interface KeybindContribution {
  id: string
  /** Panel section. Defaults to `view`. */
  category?: KeybindCategory
  /** Default combos (canonical form, e.g. `mod+shift+\\`). Empty = unbound. */
  defaults?: readonly string[]
  label: string
  run: () => void
}

export function contributedKeybinds(): KeybindContribution[] {
  return registry
    .getArea(KEYBINDS_AREA)
    .map(c => c.data as KeybindContribution)
    .filter(k => Boolean(k?.id && k.label) && typeof k?.run === 'function' && !ACTION_BY_ID.has(k.id))
}

/** Built-ins + contributed, one metadata list (panel, bindings, conflicts). */
export function allKeybindActions(): KeybindActionMeta[] {
  return [
    ...KEYBIND_ACTIONS,
    ...contributedKeybinds().map(k => ({
      id: k.id,
      category: k.category ?? ('view' as const),
      defaults: k.defaults ?? [],
      label: k.label
    }))
  ]
}

export function keybindAction(id: string): KeybindActionMeta | undefined {
  return ACTION_BY_ID.get(id) ?? allKeybindActions().find(action => action.id === id)
}

/** The contributed handler for an action id (built-ins wire theirs in use-keybinds). */
export function contributedKeybindHandler(id: string): (() => void) | undefined {
  return contributedKeybinds().find(k => k.id === id)?.run
}

export type KeybindBindings = Record<string, string[]>

export function defaultBindings(): KeybindBindings {
  return Object.fromEntries(allKeybindActions().map(action => [action.id, [...action.defaults]]))
}

// Fixed, non-rebindable shortcuts surfaced read-only in the panel so the map is
// complete. `keys` are canonical tokens run through `formatCombo` for display
// (single symbols like "@" / "/" pass through unchanged). Categories listed here
// render after the rebindable ones.
export interface KeybindReadonly {
  id: string
  category: KeybindCategory
  keys: readonly string[]
}

export const KEYBIND_READONLY: readonly KeybindReadonly[] = [
  { id: 'composer.send', category: 'composer', keys: ['enter'] },
  { id: 'composer.newline', category: 'composer', keys: ['shift+enter'] },
  { id: 'composer.steer', category: 'composer', keys: ['enter'] },
  { id: 'composer.queue', category: 'composer', keys: ['mod+enter'] },
  { id: 'composer.sendQueued', category: 'composer', keys: ['mod+shift+k'] },
  { id: 'composer.mention', category: 'composer', keys: ['@'] },
  { id: 'composer.slash', category: 'composer', keys: ['/'] },
  { id: 'composer.help', category: 'composer', keys: ['?'] },
  { id: 'composer.history', category: 'composer', keys: ['up', 'down'] },
  { id: 'composer.cancel', category: 'composer', keys: ['escape'] },
  // Fixed, context-local shortcuts surfaced for discoverability.
  { id: 'view.terminalSelection', category: 'view', keys: ['mod+l'] }
]