Skip to content

The agent that grows with you

22.9 KB
Raw Blame
// 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 type { Contribution } from '@/contrib/types'
import { hostHas } from '@/lib/host-capabilities'
import { isMacPlatform } from '@/lib/platform'

import { inChromiumAppWindow } from './app-window'

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

// A browser tab acts on some chords before the page sees the keydown: new
// window / tab / private window, close tab / window, reopen tab, and tab
// cycling (Chrome, Edge and Firefox: Ctrl/⌘+N, T, W, their Shift forms,
// Ctrl+Tab, Ctrl+PageUp/PageDown). Actions bound there get a browser default
// instead: Alt + the same key on Windows and Linux (plain left Alt types no
// character there; AltGr arrives as Ctrl+Alt or AltGraph), ⌃⌘ + the same key
// on macOS (Option types a character). Alt+Tab is the OS window switcher, so
// tab cycling takes ] and [. Native Desktop keeps the native chords.
//
// A Chromium app window (Install / "Open as window", `--app=`) reserves none
// of them (see app-window.ts). Off macOS it keeps the native Ctrl chords, the
// same ones Desktop ships; macOS keeps ⌃⌘ either way. The window kind can
// change without a reload ("Open in Chrome"), so these rows resolve their
// defaults on every read and the bindings store follows the change.

interface BrowserChords {
  /** Omitted: the native default already reaches the page on macOS. */
  mac?: string
  other: string
}

// The host and platform are fixed for the page's life; only the window kind
// moves, so a Windows/Linux browser row reads it on every access.
function hostAction(
  id: string,
  category: KeybindCategory,
  native: readonly string[],
  browser: BrowserChords
): KeybindActionMeta {
  if (!hostHas('browserShortcutDefaults')) {
    return { id, category, defaults: native }
  }

  if (isMacPlatform()) {
    return { id, category, defaults: browser.mac ? [browser.mac] : native }
  }

  const tab = [browser.other]

  return {
    id,
    category,
    get defaults() {
      return inChromiumAppWindow() ? native : tab
    },
    // Alt+letter has no Cmd/Ctrl, so it needs the editable-target opt-in to
    // fire from the composer the way the native ⌘/Ctrl chord does. Fixed, not
    // keyed on the window kind: a user's Alt rebind outlives a move into an
    // app window, and the Ctrl defaults there pass the input gate anyway.
    editableTargetPolicy: 'modified'
  }
}

// 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
  /**
   * The handler may decline (return `false`) when its context does not
   * apply, handing the chord to the next action bound to it. Sharing a combo
   * with a later action is then layering, not a conflict.
   */
  passthrough?: true
  /** `modified`: a combo carrying a non-Shift modifier may fire while an
   *  editable target (the composer) has focus, beyond the global combo-safety
   *  policy in `actionAllowedInInput`. Bare/shift-only rebinds never qualify,
   *  so a text key stays typing-safe (#71627). */
  editableTargetPolicy?: 'modified'
}

// 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 tab-slot jumps — activate the Nth visible tab of the zone under
// the pointer (else the focused zone, else the workspace's). They share
// ⌘1…⌘9 with the profile switchers and pass through when no eligible tab
// strip exists, so the same chord is "tab N" over a strip and "profile N"
// anywhere else (#92569: the two are separate actions, so rebinding either
// changes only that one).
export const TAB_SLOT_COUNT = 9

const TAB_SLOT_ACTIONS: KeybindActionMeta[] = Array.from({ length: TAB_SLOT_COUNT }, (_, i) => ({
  id: `view.tabSlot.${i + 1}`,
  category: 'view' as const,
  defaults: [comboForSlot(i + 1)],
  passthrough: true
}))

// 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'] },
  // ⌘⇧M — "m" for model; the convention chat apps converged on (LibreChat,
  // Open WebUI, and Cherry Studio all ship the same chord). Opens the pill's
  // live dropdown on the pane under the pointer, else the active composer.
  { id: 'composer.modelPicker', category: 'composer', defaults: ['mod+shift+m'] },
  // Voice conversation toggle. On macOS that's literally ⌃B — distinct from
  // the ⌘B sidebar toggle. Off macOS `ctrl` folds to `mod`, so ⌃B IS the
  // sidebar chord. Ship ⌃⌥V there ("v" for voice) instead of stealing mod+b
  // or leaving the action unbound.
  { id: 'composer.voice', category: 'composer', defaults: isMacPlatform() ? ['ctrl+b'] : ['mod+alt+v'] },
  // Dictation is intentionally unbound: it is available for users who prefer
  // a keyboard trigger without claiming a chord from text entry by default.
  { id: 'composer.dictate', category: 'composer', defaults: [] },
  // Reasoning level up/down — one notch through off → minimal → … → xhigh,
  // clamped at the ends (#71627). Unbound like dictate: the chords a user
  // picks (Alt+., Ctrl+Alt+↑, Numpad +/- …) are too personal to claim by
  // default. `editableTargetPolicy` lets a MODIFIED combo fire while the
  // composer has focus; bare/shift-only rebinds stay typing-safe.
  { id: 'composer.reasoningUp', category: 'composer', defaults: [], editableTargetPolicy: 'modified' },
  { id: 'composer.reasoningDown', category: 'composer', defaults: [], editableTargetPolicy: 'modified' },

  // ── Profiles ─────────────────────────────────────────────────────────────
  // Tab-slot actions BEFORE profile switchers: they claim ⌘1…⌘9 first and
  // pass through to the profile switch when no tab strip is eligible.
  ...TAB_SLOT_ACTIONS,
  { 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 ──────────────────────────────────────────────────────────────
  // `shift+n` was dropped from the defaults (#76185): a bare shifted letter
  // hijacked normal typing — pressing uppercase N outside an input (or via an
  // IME) created a new session unexpectedly.
  hostAction('session.new', 'session', ['mod+n'], { mac: 'mod+ctrl+n', other: 'alt+n' }),
  hostAction('session.newTab', 'session', ['mod+t'], { mac: 'mod+ctrl+t', other: 'alt+t' }),
  hostAction('session.newWindow', 'session', ['mod+shift+n'], { mac: 'mod+ctrl+shift+n', other: 'alt+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.
  hostAction('session.next', 'session', ['ctrl+tab', 'ctrl+pagedown'], { mac: 'mod+ctrl+]', other: 'alt+]' }),
  hostAction('session.prev', 'session', ['ctrl+shift+tab', 'ctrl+pageup'], { mac: 'mod+ctrl+[', other: 'alt+[' }),
  ...SESSION_SLOT_ACTIONS,
  { id: 'session.focusSearch', category: 'session', defaults: ['mod+shift+f'] },
  { id: 'session.togglePin', category: 'session', defaults: [] },
  { id: 'conversation.scrollPageUp', category: 'session', defaults: ['pageup'] },
  { id: 'conversation.scrollPageDown', category: 'session', defaults: ['pagedown'] },
  // Archive the active session. Ships unbound (like `session.togglePin`) so an
  // irreversible-feeling, mouse-only action doesn't silently claim a chord for
  // every user — surfaced in the panel for opt-in binding (the issue suggests
  // ⌘⇧⌫ / Ctrl+Shift+⌫).
  { id: 'session.archive', 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'] },
  // ⌘O — the editor-standard "open folder" chord (VS Code ⌘O, Zed's
  // workspace::Open). Picks a folder and opens it as a project (upsert:
  // enters the owning project when one exists, else creates one), landing on
  // a fresh session anchored there.
  { id: 'workspace.openFolder', category: 'session', defaults: ['mod+o'] },

  // ── 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.capabilities', 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'] },
  // Expose the sidebar's mouse-only grouping control to keyboard-first users.
  // Ships unbound so it is opt-in and cannot claim another global chord.
  { id: 'view.cycleSidebarGrouping', category: 'view', defaults: [] },
  { 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'] },
  // ⌥⌘T — "t" for tabs, reaching past ⇧ because ⌘⇧T is reopen-closed-tab
  // everywhere. Ships BOUND, unlike VS Code's settings-only tab-bar switch:
  // here the hide can take away every other affordance the zone had, so the
  // way back has to already exist. (⌥+letter emits a symbol on macOS; the
  // binding resolves through KeyT via comboFromEvent's `event.code` fallback.)
  { id: 'view.toggleTabStrip', category: 'view', defaults: ['mod+alt+t'] },
  // Unbound: the rail is a one-time preference, not something to flip mid-chat.
  { id: 'view.toggleProfileRail', category: 'view', defaults: [] },
  // Unbound for the same reason: Simple ↔ Advanced is a stance, not a view
  // toggle; ⌘K, the layout editor and Settings → Appearance are its doors.
  { id: 'view.toggleSimpleMode', category: 'view', defaults: [] },
  // ⌘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: [] },
  // ⌘⇧L — "L" for location, the address-bar chord every browser shares. Plain
  // ⌘L is the terminal's selection shortcut, hence the shift.
  { id: 'view.showBrowser', category: 'view', defaults: ['mod+shift+l'] },
  // ⌘⇧H — "h" for HUD. Enters/leaves the chrome-free floating chat: the app
  // window steps aside and a composer + live reply float over whatever the
  // user is working in. Ships bound because the whole point is leaving the app
  // without reaching for it — but the titlebar button is the discoverable door.
  { id: 'view.toggleHud', category: 'view', defaults: ['mod+shift+h'] },
  // 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'] },
  hostAction('view.closeTerminal', 'view', ['ctrl+shift+w'], { other: 'alt+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.
  hostAction('view.closeTab', 'view', ['mod+w'], { mac: 'mod+ctrl+w', other: 'alt+w' }),
  hostAction('view.reopenTab', 'view', ['mod+shift+t'], { mac: 'mod+ctrl+shift+t', other: 'alt+shift+t' }),
  // ⌘F — open the find-in-page bar. `actionAllowedInInput` lets this action
  // 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)

// The built-in actions a plugin may run by id (`ctx.runAction`, see
// plugin-actions.ts): view / navigation only. Nothing destructive, nothing
// that switches profile / model, spawns a shell, or opens native dialogs.
export const PLUGIN_APP_ACTIONS = [
  // Panels and layout
  'view.showBrowser',
  'view.showFiles',
  'view.toggleSidebar',
  'view.toggleRightSidebar',
  'view.toggleReview',
  'view.toggleStatusbar',
  'view.findInPage',
  // Composer and chat
  'composer.focus',
  'session.new',
  'session.focusSearch',
  'conversation.scrollPageUp',
  'conversation.scrollPageDown',
  // Navigation
  'nav.commandPalette',
  'nav.settings',
  'nav.profiles',
  'nav.capabilities',
  'nav.messaging',
  'nav.artifacts',
  'nav.cron',
  'nav.agents',
  'keybinds.openPanel'
] as const

/** An app action id a plugin may run with `ctx.runAction`. */
export type PluginAppActionId = (typeof PLUGIN_APP_ACTIONS)[number]

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
}

// React consumers pass their `useContributions(KEYBINDS_AREA)` snapshot in:
// with React Compiler enabled, an independently-called `contributedKeybinds()`
// can stay memoized across a late registration the subscription DID deliver.
export function contributedKeybinds(
  contributions: readonly Contribution[] = registry.getArea(KEYBINDS_AREA)
): KeybindContribution[] {
  return contributions
    .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(contributions?: readonly Contribution[]): KeybindActionMeta[] {
  return [
    ...KEYBIND_ACTIONS,
    ...contributedKeybinds(contributions).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)
}

/** True when `combo` carries a modifier beyond Shift (mod, ctrl, or alt). */
function comboHasNonShiftModifier(combo: string): boolean {
  const parts = combo.split('+')

  return parts.slice(0, -1).some(part => part !== 'shift')
}

/** An action's own allowance for firing inside an editable target: the
 *  `editableTargetPolicy` gate that `actionAllowedInInput` consults. Only a
 *  combo with a real modifier qualifies — a bare or shift-only rebind stays
 *  with the input so it can never hijack typing. */
export function keybindActionAllowedInEditableTarget(id: string, combo: string): boolean {
  return keybindAction(id)?.editableTargetPolicy === 'modified' && comboHasNonShiftModifier(combo)
}

/** 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'] },
  // ⌘/Ctrl+L moves focus to the composer from anywhere, like the address-bar
  // chord in a browser. The row reuses the id of the rebindable soft-focus
  // action above. As a result, the panel shows one "Focus composer" label
  // for both. The row is fixed because the selection shortcut below uses the
  // same chord. Who claims a contested press: see the priority ladder in
  // app/chat/composer/focus-chord.ts.
  { id: 'composer.focus', category: 'composer', keys: ['mod+l'] },
  // Fixed, context-local shortcuts, listed so users can find them. This row
  // uses the same ⌘/Ctrl+L chord as `composer.focus` above. It is the
  // selection half of the chord: the selected text (terminal text, preview
  // lines) goes into the composer as context.
  { id: 'view.selectionToComposer', category: 'view', keys: ['mod+l'] },
  // Terminal clipboard. ⌘C/⌘V on macOS, Ctrl+Shift+C/V elsewhere — matching VS
  // Code. Plain Ctrl+C also copies when text is selected (Windows Terminal /
  // Tabby behavior); with no selection it stays SIGINT, so it isn't listed.
  { id: 'view.terminalCopy', category: 'view', keys: isMacPlatform() ? ['mod+c'] : ['mod+shift+c'] },
  { id: 'view.terminalPaste', category: 'view', keys: isMacPlatform() ? ['mod+v'] : ['mod+shift+v'] },
  // Global OS chord registered in main while HUD mode is up.
  { id: 'hud.snapToPointer', category: 'view', keys: ['mod+shift+g'] }
]