@xortex/xcode 3.0.1 → 3.0.3

package/keybindings/schema.ts

@@ -0,0 +1,236 @@
+/**
+ * Zod schema for keybindings.json configuration.
+ * Used for validation and JSON schema generation.
+ */
+
+import { z } from 'zod/v4'
+import { lazySchema } from '../utils/lazySchema.js'
+
+/**
+ * Valid context names where keybindings can be applied.
+ */
+export const KEYBINDING_CONTEXTS = [
+  'Global',
+  'Chat',
+  'Autocomplete',
+  'Confirmation',
+  'Help',
+  'Transcript',
+  'HistorySearch',
+  'Task',
+  'ThemePicker',
+  'Settings',
+  'Tabs',
+  // New contexts for keybindings migration
+  'Attachments',
+  'Footer',
+  'MessageSelector',
+  'DiffDialog',
+  'ModelPicker',
+  'Select',
+  'Plugin',
+] as const
+
+/**
+ * Human-readable descriptions for each keybinding context.
+ */
+export const KEYBINDING_CONTEXT_DESCRIPTIONS: Record<
+  (typeof KEYBINDING_CONTEXTS)[number],
+  string
+> = {
+  Global: 'Active everywhere, regardless of focus',
+  Chat: 'When the chat input is focused',
+  Autocomplete: 'When autocomplete menu is visible',
+  Confirmation: 'When a confirmation/permission dialog is shown',
+  Help: 'When the help overlay is open',
+  Transcript: 'When viewing the transcript',
+  HistorySearch: 'When searching command history (ctrl+r)',
+  Task: 'When a task/agent is running in the foreground',
+  ThemePicker: 'When the theme picker is open',
+  Settings: 'When the settings menu is open',
+  Tabs: 'When tab navigation is active',
+  Attachments: 'When navigating image attachments in a select dialog',
+  Footer: 'When footer indicators are focused',
+  MessageSelector: 'When the message selector (rewind) is open',
+  DiffDialog: 'When the diff dialog is open',
+  ModelPicker: 'When the model picker is open',
+  Select: 'When a select/list component is focused',
+  Plugin: 'When the plugin dialog is open',
+}
+
+/**
+ * All valid keybinding action identifiers.
+ */
+export const KEYBINDING_ACTIONS = [
+  // App-level actions (Global context)
+  'app:interrupt',
+  'app:exit',
+  'app:toggleTodos',
+  'app:toggleTranscript',
+  'app:toggleBrief',
+  'app:toggleTeammatePreview',
+  'app:toggleTerminal',
+  'app:redraw',
+  'app:globalSearch',
+  'app:quickOpen',
+  // History navigation
+  'history:search',
+  'history:previous',
+  'history:next',
+  // Chat input actions
+  'chat:cancel',
+  'chat:killAgents',
+  'chat:cycleMode',
+  'chat:modelPicker',
+  'chat:fastMode',
+  'chat:thinkingToggle',
+  'chat:submit',
+  'chat:newline',
+  'chat:undo',
+  'chat:externalEditor',
+  'chat:stash',
+  'chat:imagePaste',
+  'chat:messageActions',
+  // Autocomplete menu actions
+  'autocomplete:accept',
+  'autocomplete:dismiss',
+  'autocomplete:previous',
+  'autocomplete:next',
+  // Confirmation dialog actions
+  'confirm:yes',
+  'confirm:no',
+  'confirm:previous',
+  'confirm:next',
+  'confirm:nextField',
+  'confirm:previousField',
+  'confirm:cycleMode',
+  'confirm:toggle',
+  'confirm:toggleExplanation',
+  // Tabs navigation actions
+  'tabs:next',
+  'tabs:previous',
+  // Transcript viewer actions
+  'transcript:toggleShowAll',
+  'transcript:exit',
+  // History search actions
+  'historySearch:next',
+  'historySearch:accept',
+  'historySearch:cancel',
+  'historySearch:execute',
+  // Task/agent actions
+  'task:background',
+  // Theme picker actions
+  'theme:toggleSyntaxHighlighting',
+  // Help menu actions
+  'help:dismiss',
+  // Attachment navigation (select dialog image attachments)
+  'attachments:next',
+  'attachments:previous',
+  'attachments:remove',
+  'attachments:exit',
+  // Footer indicator actions
+  'footer:up',
+  'footer:down',
+  'footer:next',
+  'footer:previous',
+  'footer:openSelected',
+  'footer:clearSelection',
+  'footer:close',
+  // Message selector (rewind) actions
+  'messageSelector:up',
+  'messageSelector:down',
+  'messageSelector:top',
+  'messageSelector:bottom',
+  'messageSelector:select',
+  // Diff dialog actions
+  'diff:dismiss',
+  'diff:previousSource',
+  'diff:nextSource',
+  'diff:back',
+  'diff:viewDetails',
+  'diff:previousFile',
+  'diff:nextFile',
+  // Model picker actions (ant-only)
+  'modelPicker:decreaseEffort',
+  'modelPicker:increaseEffort',
+  // Select component actions (distinct from confirm: to avoid collisions)
+  'select:next',
+  'select:previous',
+  'select:accept',
+  'select:cancel',
+  // Plugin dialog actions
+  'plugin:toggle',
+  'plugin:install',
+  // Permission dialog actions
+  'permission:toggleDebug',
+  // Settings config panel actions
+  'settings:search',
+  'settings:retry',
+  'settings:close',
+  // Voice actions
+  'voice:pushToTalk',
+] as const
+
+/**
+ * Schema for a single keybinding block.
+ */
+export const KeybindingBlockSchema = lazySchema(() =>
+  z
+    .object({
+      context: z
+        .enum(KEYBINDING_CONTEXTS)
+        .describe(
+          'UI context where these bindings apply. Global bindings work everywhere.',
+        ),
+      bindings: z
+        .record(
+          z
+            .string()
+            .describe('Keystroke pattern (e.g., "ctrl+k", "shift+tab")'),
+          z
+            .union([
+              z.enum(KEYBINDING_ACTIONS),
+              z
+                .string()
+                .regex(/^command:[a-zA-Z0-9:\-_]+$/)
+                .describe(
+                  'Command binding (e.g., "command:help", "command:compact"). Executes the slash command as if typed.',
+                ),
+              z.null().describe('Set to null to unbind a default shortcut'),
+            ])
+            .describe(
+              'Action to trigger, command to invoke, or null to unbind',
+            ),
+        )
+        .describe('Map of keystroke patterns to actions'),
+    })
+    .describe('A block of keybindings for a specific context'),
+)
+
+/**
+ * Schema for the entire keybindings.json file.
+ * Uses object wrapper format with optional $schema and $docs metadata.
+ */
+export const KeybindingsSchema = lazySchema(() =>
+  z
+    .object({
+      $schema: z
+        .string()
+        .optional()
+        .describe('JSON Schema URL for editor validation'),
+      $docs: z.string().optional().describe('Documentation URL'),
+      bindings: z
+        .array(KeybindingBlockSchema())
+        .describe('Array of keybinding blocks by context'),
+    })
+    .describe(
+      'Claude Code keybindings configuration. Customize keyboard shortcuts by context.',
+    ),
+)
+
+/**
+ * TypeScript types derived from the schema.
+ */
+export type KeybindingsSchemaType = z.infer<
+  ReturnType<typeof KeybindingsSchema>
+>

package/keybindings/shortcutFormat.ts

@@ -0,0 +1,63 @@
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../services/analytics/index.js'
+import { loadKeybindingsSync } from './loadUserBindings.js'
+import { getBindingDisplayText } from './resolver.js'
+import type { KeybindingContextName } from './types.js'
+
+// TODO(keybindings-migration): Remove fallback parameter after migration is
+// complete and we've confirmed no 'keybinding_fallback_used' events are being
+// logged. The fallback exists as a safety net during migration - if bindings
+// fail to load or an action isn't found, we fall back to hardcoded values.
+// Once stable, callers should be able to trust that getBindingDisplayText
+// always returns a value for known actions, and we can remove this defensive
+// pattern.
+
+// Track which action+context pairs have already logged a fallback event
+// to avoid duplicate events from repeated calls in non-React contexts.
+const LOGGED_FALLBACKS = new Set<string>()
+
+/**
+ * Get the display text for a configured shortcut without React hooks.
+ * Use this in non-React contexts (commands, services, etc.).
+ *
+ * This lives in its own module (not useShortcutDisplay.ts) so that
+ * non-React callers like query/stopHooks.ts don't pull React into their
+ * module graph via the sibling hook.
+ *
+ * @param action - The action name (e.g., 'app:toggleTranscript')
+ * @param context - The keybinding context (e.g., 'Global')
+ * @param fallback - Fallback text if binding not found
+ * @returns The configured shortcut display text
+ *
+ * @example
+ * const expandShortcut = getShortcutDisplay('app:toggleTranscript', 'Global', 'ctrl+o')
+ * // Returns the user's configured binding, or 'ctrl+o' as default
+ */
+export function getShortcutDisplay(
+  action: string,
+  context: KeybindingContextName,
+  fallback: string,
+): string {
+  const bindings = loadKeybindingsSync()
+  const resolved = getBindingDisplayText(action, context, bindings)
+  if (resolved === undefined) {
+    const key = `${action}:${context}`
+    if (!LOGGED_FALLBACKS.has(key)) {
+      LOGGED_FALLBACKS.add(key)
+      logEvent('tengu_keybinding_fallback_used', {
+        action:
+          action as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        context:
+          context as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        fallback:
+          fallback as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        reason:
+          'action_not_found' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      })
+    }
+    return fallback
+  }
+  return resolved
+}

package/keybindings/template.ts

@@ -0,0 +1,52 @@
+/**
+ * Keybindings template generator.
+ * Generates a well-documented template file for ~/.claude/keybindings.json
+ */
+
+import { jsonStringify } from '../utils/slowOperations.js'
+import { DEFAULT_BINDINGS } from './defaultBindings.js'
+import {
+  NON_REBINDABLE,
+  normalizeKeyForComparison,
+} from './reservedShortcuts.js'
+import type { KeybindingBlock } from './types.js'
+
+/**
+ * Filter out reserved shortcuts that cannot be rebound.
+ * These would cause /doctor to warn, so we exclude them from the template.
+ */
+function filterReservedShortcuts(blocks: KeybindingBlock[]): KeybindingBlock[] {
+  const reservedKeys = new Set(
+    NON_REBINDABLE.map(r => normalizeKeyForComparison(r.key)),
+  )
+
+  return blocks
+    .map(block => {
+      const filteredBindings: Record<string, string | null> = {}
+      for (const [key, action] of Object.entries(block.bindings)) {
+        if (!reservedKeys.has(normalizeKeyForComparison(key))) {
+          filteredBindings[key] = action
+        }
+      }
+      return { context: block.context, bindings: filteredBindings }
+    })
+    .filter(block => Object.keys(block.bindings).length > 0)
+}
+
+/**
+ * Generate a template keybindings.json file content.
+ * Creates a fully valid JSON file with all default bindings that users can customize.
+ */
+export function generateKeybindingsTemplate(): string {
+  // Filter out reserved shortcuts that cannot be rebound
+  const bindings = filterReservedShortcuts(DEFAULT_BINDINGS)
+
+  // Format as object wrapper with bindings array
+  const config = {
+    $schema: 'https://www.schemastore.org/claude-code-keybindings.json',
+    $docs: 'https://code.claude.com/docs/en/keybindings',
+    bindings,
+  }
+
+  return jsonStringify(config, null, 2) + '\n'
+}

package/keybindings/useKeybinding.ts

@@ -0,0 +1,196 @@
+import { useCallback, useEffect } from 'react'
+import type { InputEvent } from '../ink/events/input-event.js'
+import { type Key, useInput } from '../ink.js'
+import { useOptionalKeybindingContext } from './KeybindingContext.js'
+import type { KeybindingContextName } from './types.js'
+
+type Options = {
+  /** Which context this binding belongs to (default: 'Global') */
+  context?: KeybindingContextName
+  /** Only handle when active (like useInput's isActive) */
+  isActive?: boolean
+}
+
+/**
+ * Ink-native hook for handling a keybinding.
+ *
+ * The handler stays in the component (React way).
+ * The binding (keystroke → action) comes from config.
+ *
+ * Supports chord sequences (e.g., "ctrl+k ctrl+s"). When a chord is started,
+ * the hook will manage the pending state automatically.
+ *
+ * Uses stopImmediatePropagation() to prevent other handlers from firing
+ * once this binding is handled.
+ *
+ * @example
+ * ```tsx
+ * useKeybinding('app:toggleTodos', () => {
+ *   setShowTodos(prev => !prev)
+ * }, { context: 'Global' })
+ * ```
+ */
+export function useKeybinding(
+  action: string,
+  handler: () => void | false | Promise<void>,
+  options: Options = {},
+): void {
+  const { context = 'Global', isActive = true } = options
+  const keybindingContext = useOptionalKeybindingContext()
+
+  // Register handler with the context for ChordInterceptor to invoke
+  useEffect(() => {
+    if (!keybindingContext || !isActive) return
+    return keybindingContext.registerHandler({ action, context, handler })
+  }, [action, context, handler, keybindingContext, isActive])
+
+  const handleInput = useCallback(
+    (input: string, key: Key, event: InputEvent) => {
+      // If no keybinding context available, skip resolution
+      if (!keybindingContext) return
+
+      // Build context list: registered active contexts + this context + Global
+      // More specific contexts (registered ones) take precedence over Global
+      const contextsToCheck: KeybindingContextName[] = [
+        ...keybindingContext.activeContexts,
+        context,
+        'Global',
+      ]
+      // Deduplicate while preserving order (first occurrence wins for priority)
+      const uniqueContexts = [...new Set(contextsToCheck)]
+
+      const result = keybindingContext.resolve(input, key, uniqueContexts)
+
+      switch (result.type) {
+        case 'match':
+          // Chord completed (if any) - clear pending state
+          keybindingContext.setPendingChord(null)
+          if (result.action === action) {
+            if (handler() !== false) {
+              event.stopImmediatePropagation()
+            }
+          }
+          break
+        case 'chord_started':
+          // User started a chord sequence - update pending state
+          keybindingContext.setPendingChord(result.pending)
+          event.stopImmediatePropagation()
+          break
+        case 'chord_cancelled':
+          // Chord was cancelled (escape or invalid key)
+          keybindingContext.setPendingChord(null)
+          break
+        case 'unbound':
+          // Explicitly unbound - clear any pending chord
+          keybindingContext.setPendingChord(null)
+          event.stopImmediatePropagation()
+          break
+        case 'none':
+          // No match - let other handlers try
+          break
+      }
+    },
+    [action, context, handler, keybindingContext],
+  )
+
+  useInput(handleInput, { isActive })
+}
+
+/**
+ * Handle multiple keybindings in one hook (reduces useInput calls).
+ *
+ * Supports chord sequences. When a chord is started, the hook will
+ * manage the pending state automatically.
+ *
+ * @example
+ * ```tsx
+ * useKeybindings({
+ *   'chat:submit': () => handleSubmit(),
+ *   'chat:cancel': () => handleCancel(),
+ * }, { context: 'Chat' })
+ * ```
+ */
+export function useKeybindings(
+  // Handler returning `false` means "not consumed" — the event propagates
+  // to later useInput/useKeybindings handlers. Useful for fall-through:
+  // e.g. ScrollKeybindingHandler's scroll:line* returns false when the
+  // ScrollBox content fits (scroll is a no-op), letting a child component's
+  // handler take the wheel event for list navigation instead. Promise<void>
+  // is allowed for fire-and-forget async handlers (the `!== false` check
+  // only skips propagation for a sync `false`, not a pending Promise).
+  handlers: Record<string, () => void | false | Promise<void>>,
+  options: Options = {},
+): void {
+  const { context = 'Global', isActive = true } = options
+  const keybindingContext = useOptionalKeybindingContext()
+
+  // Register all handlers with the context for ChordInterceptor to invoke
+  useEffect(() => {
+    if (!keybindingContext || !isActive) return
+
+    const unregisterFns: Array<() => void> = []
+    for (const [action, handler] of Object.entries(handlers)) {
+      unregisterFns.push(
+        keybindingContext.registerHandler({ action, context, handler }),
+      )
+    }
+
+    return () => {
+      for (const unregister of unregisterFns) {
+        unregister()
+      }
+    }
+  }, [context, handlers, keybindingContext, isActive])
+
+  const handleInput = useCallback(
+    (input: string, key: Key, event: InputEvent) => {
+      // If no keybinding context available, skip resolution
+      if (!keybindingContext) return
+
+      // Build context list: registered active contexts + this context + Global
+      // More specific contexts (registered ones) take precedence over Global
+      const contextsToCheck: KeybindingContextName[] = [
+        ...keybindingContext.activeContexts,
+        context,
+        'Global',
+      ]
+      // Deduplicate while preserving order (first occurrence wins for priority)
+      const uniqueContexts = [...new Set(contextsToCheck)]
+
+      const result = keybindingContext.resolve(input, key, uniqueContexts)
+
+      switch (result.type) {
+        case 'match':
+          // Chord completed (if any) - clear pending state
+          keybindingContext.setPendingChord(null)
+          if (result.action in handlers) {
+            const handler = handlers[result.action]
+            if (handler && handler() !== false) {
+              event.stopImmediatePropagation()
+            }
+          }
+          break
+        case 'chord_started':
+          // User started a chord sequence - update pending state
+          keybindingContext.setPendingChord(result.pending)
+          event.stopImmediatePropagation()
+          break
+        case 'chord_cancelled':
+          // Chord was cancelled (escape or invalid key)
+          keybindingContext.setPendingChord(null)
+          break
+        case 'unbound':
+          // Explicitly unbound - clear any pending chord
+          keybindingContext.setPendingChord(null)
+          event.stopImmediatePropagation()
+          break
+        case 'none':
+          // No match - let other handlers try
+          break
+      }
+    },
+    [context, handlers, keybindingContext],
+  )
+
+  useInput(handleInput, { isActive })
+}

package/keybindings/useShortcutDisplay.ts

@@ -0,0 +1,59 @@
+import { useEffect, useRef } from 'react'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../services/analytics/index.js'
+import { useOptionalKeybindingContext } from './KeybindingContext.js'
+import type { KeybindingContextName } from './types.js'
+
+// TODO(keybindings-migration): Remove fallback parameter after migration is complete
+// and we've confirmed no 'keybinding_fallback_used' events are being logged.
+// The fallback exists as a safety net during migration - if bindings fail to load
+// or an action isn't found, we fall back to hardcoded values. Once stable, callers
+// should be able to trust that getBindingDisplayText always returns a value for
+// known actions, and we can remove this defensive pattern.
+
+/**
+ * Hook to get the display text for a configured shortcut.
+ * Returns the configured binding or a fallback if unavailable.
+ *
+ * @param action - The action name (e.g., 'app:toggleTranscript')
+ * @param context - The keybinding context (e.g., 'Global')
+ * @param fallback - Fallback text if keybinding context unavailable
+ * @returns The configured shortcut display text
+ *
+ * @example
+ * const expandShortcut = useShortcutDisplay('app:toggleTranscript', 'Global', 'ctrl+o')
+ * // Returns the user's configured binding, or 'ctrl+o' as default
+ */
+export function useShortcutDisplay(
+  action: string,
+  context: KeybindingContextName,
+  fallback: string,
+): string {
+  const keybindingContext = useOptionalKeybindingContext()
+  const resolved = keybindingContext?.getDisplayText(action, context)
+  const isFallback = resolved === undefined
+  const reason = keybindingContext ? 'action_not_found' : 'no_context'
+
+  // Log fallback usage once per mount (not on every render) to avoid
+  // flooding analytics with events from frequent re-renders.
+  const hasLoggedRef = useRef(false)
+  useEffect(() => {
+    if (isFallback && !hasLoggedRef.current) {
+      hasLoggedRef.current = true
+      logEvent('tengu_keybinding_fallback_used', {
+        action:
+          action as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        context:
+          context as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        fallback:
+          fallback as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        reason:
+          reason as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      })
+    }
+  }, [isFallback, action, context, fallback, reason])
+
+  return isFallback ? fallback : resolved
+}