@tanstack/hotkeys 0.7.0 → 0.8.0

package/dist/constants.cjs

@@ -391,6 +391,7 @@ function isSingleLetterKey(key) {
 * ```
 */
 function normalizeKeyName(key) {
+	if (!key) return "";
 	if (key in KEY_ALIASES) return KEY_ALIASES[key];
 	if (isSingleLetterKey(key)) {
 		const upper = key.toUpperCase();

package/dist/constants.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"constants.cjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["import type {\n  CanonicalModifier,\n  EditingKey,\n  FunctionKey,\n  LetterKey,\n  NavigationKey,\n  NumberKey,\n  PunctuationKey,\n} from './hotkey'\n\n/**\n * Detects the current platform based on browser navigator properties.\n *\n * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n *\n * @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n *\n * @example\n * ```ts\n * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n */\nexport function detectPlatform(): 'mac' | 'windows' | 'linux' {\n  if (typeof navigator === 'undefined') {\n    return 'linux' // Default for SSR\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const platform = navigator.platform?.toLowerCase() ?? ''\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n  if (platform.includes('mac') || userAgent.includes('mac')) {\n    return 'mac'\n  }\n  if (platform.includes('win') || userAgent.includes('win')) {\n    return 'windows'\n  }\n  return 'linux'\n}\n\n/**\n * Canonical order for modifiers in normalized hotkey strings.\n *\n * Defines the standard order in which modifiers should appear when formatting\n * hotkeys. This ensures consistent, predictable output across the library.\n *\n * Order: Control → Alt → Shift → Meta\n *\n * @example\n * ```ts\n * // Input: 'Shift+Control+Meta+S'\n * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)\n * ```\n */\nexport const MODIFIER_ORDER: Array<CanonicalModifier> = [\n  'Control',\n  'Alt',\n  'Shift',\n  'Meta',\n]\n\n/**\n * Set of canonical modifier key names for fast lookup.\n *\n * Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when\n * a modifier is released so we can clear non-modifier keys whose keyup events\n * may have been swallowed by the OS (e.g. macOS Cmd+key combos).\n */\nexport const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)\n\n/**\n * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.\n *\n * This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')\n * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the\n * platform-adaptive 'Mod' token.\n *\n * The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`\n * based on the detected platform (Command on Mac, Control elsewhere).\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * MODIFIER_ALIASES['Ctrl'] // 'Control'\n * MODIFIER_ALIASES['Cmd'] // 'Meta'\n * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)\n * ```\n */\nexport const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'> = {\n  // Control variants\n  Control: 'Control',\n  Ctrl: 'Control',\n  control: 'Control',\n  ctrl: 'Control',\n\n  // Shift variants\n  Shift: 'Shift',\n  shift: 'Shift',\n\n  // Alt variants\n  Alt: 'Alt',\n  Option: 'Alt',\n  alt: 'Alt',\n  option: 'Alt',\n\n  // Meta/Command variants\n  Command: 'Meta',\n  Cmd: 'Meta',\n  Meta: 'Meta',\n  command: 'Meta',\n  cmd: 'Meta',\n  meta: 'Meta',\n\n  // DOM `KeyboardEvent.key` spellings for the meta / Windows key\n  OS: 'Meta',\n  os: 'Meta',\n  Win: 'Meta',\n  win: 'Meta',\n\n  // Platform-adaptive (resolved at runtime)\n  CommandOrControl: 'Mod',\n  Mod: 'Mod',\n  commandorcontrol: 'Mod',\n  mod: 'Mod',\n}\n\n/**\n * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n *\n * The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n *\n * This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n *\n * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n *\n * @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n */\nexport function resolveModifier(\n  modifier: CanonicalModifier | 'Mod',\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): CanonicalModifier {\n  if (modifier === 'Mod') {\n    return platform === 'mac' ? 'Meta' : 'Control'\n  }\n  return modifier\n}\n\n/**\n * Set of all valid letter keys (A-Z).\n *\n * Used for validation and type checking. Letter keys are matched case-insensitively\n * in hotkey matching, but normalized to uppercase in canonical form.\n */\nexport const LETTER_KEYS = new Set<LetterKey>([\n  'A',\n  'B',\n  'C',\n  'D',\n  'E',\n  'F',\n  'G',\n  'H',\n  'I',\n  'J',\n  'K',\n  'L',\n  'M',\n  'N',\n  'O',\n  'P',\n  'Q',\n  'R',\n  'S',\n  'T',\n  'U',\n  'V',\n  'W',\n  'X',\n  'Y',\n  'Z',\n])\n\n/**\n * Set of all valid number keys (0-9).\n *\n * Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid\n * layout-dependent behavior.\n */\nexport const NUMBER_KEYS = new Set<NumberKey>([\n  '0',\n  '1',\n  '2',\n  '3',\n  '4',\n  '5',\n  '6',\n  '7',\n  '8',\n  '9',\n])\n\n/**\n * Set of all valid function keys (F1-F12).\n *\n * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,\n * Alt+F4 to close windows) and application-specific commands.\n */\nexport const FUNCTION_KEYS = new Set<FunctionKey>([\n  'F1',\n  'F2',\n  'F3',\n  'F4',\n  'F5',\n  'F6',\n  'F7',\n  'F8',\n  'F9',\n  'F10',\n  'F11',\n  'F12',\n])\n\n/**\n * Set of all valid navigation keys for cursor movement and document navigation.\n *\n * Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).\n * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or\n * navigation shortcuts (Alt+ArrowLeft for back).\n */\nexport const NAVIGATION_KEYS = new Set<NavigationKey>([\n  'ArrowUp',\n  'ArrowDown',\n  'ArrowLeft',\n  'ArrowRight',\n  'Home',\n  'End',\n  'PageUp',\n  'PageDown',\n])\n\n/**\n * Set of all valid editing and special keys.\n *\n * Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and\n * special actions (Escape, Space). These keys are frequently combined with modifiers\n * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).\n */\nexport const EDITING_KEYS = new Set<EditingKey>([\n  'Enter',\n  'Escape',\n  'Space',\n  'Tab',\n  'Backspace',\n  'Delete',\n])\n\n/**\n * Set of all valid punctuation keys commonly used in keyboard shortcuts.\n *\n * These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,\n * typically US keyboard layout). Common shortcuts include:\n * - `Mod+/` - Toggle comment\n * - `Mod+[` / `Mod+]` - Indent/outdent\n * - `Mod+=` / `Mod+-` - Zoom in/out\n *\n * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.\n */\nexport const PUNCTUATION_KEYS = new Set<PunctuationKey>([\n  '/',\n  '[',\n  ']',\n  '\\\\',\n  '=',\n  '-',\n  ',',\n  '.',\n  ';',\n  '`',\n])\n\n/**\n * Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.\n *\n * On macOS, holding the Option (Alt) key transforms punctuation keys into special characters\n * (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.\n * However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables\n * falling back to `event.code` for punctuation keys, similar to the existing `Key*`/`Digit*`\n * fallbacks for letters and digits.\n */\nexport const PUNCTUATION_CODE_MAP: Record<string, string> = {\n  Backquote: '`',\n  Backslash: '\\\\',\n  BracketLeft: '[',\n  BracketRight: ']',\n  Comma: ',',\n  Equal: '=',\n  Minus: '-',\n  Period: '.',\n  Semicolon: ';',\n  Slash: '/',\n}\n\n/**\n * Set of all valid non-modifier keys.\n *\n * This is the union of all key type sets (letters, numbers, function keys, navigation,\n * editing, and punctuation). Used primarily for validation to check if a key string\n * is recognized and will have type-safe autocomplete support.\n *\n * @see {@link LETTER_KEYS}\n * @see {@link NUMBER_KEYS}\n * @see {@link FUNCTION_KEYS}\n * @see {@link NAVIGATION_KEYS}\n * @see {@link EDITING_KEYS}\n * @see {@link PUNCTUATION_KEYS}\n */\nexport const ALL_KEYS = new Set([\n  ...LETTER_KEYS,\n  ...NUMBER_KEYS,\n  ...FUNCTION_KEYS,\n  ...NAVIGATION_KEYS,\n  ...EDITING_KEYS,\n  ...PUNCTUATION_KEYS,\n])\n\n/**\n * Maps key name aliases to their canonical form.\n *\n * Handles common variations and alternative names for keys to provide a more\n * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and\n * they'll all normalize to 'Escape'.\n *\n * This map is used internally by `normalizeKeyName()` to convert user input\n * into the canonical key names used throughout the library.\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * KEY_ALIASES['Esc'] // 'Escape'\n * KEY_ALIASES['Del'] // 'Delete'\n * KEY_ALIASES['Up'] // 'ArrowUp'\n * ```\n */\nconst KEY_ALIASES: Record<string, string> = {\n  // Escape variants\n  Esc: 'Escape',\n  esc: 'Escape',\n  escape: 'Escape',\n\n  // Enter variants\n  Return: 'Enter',\n  return: 'Enter',\n  enter: 'Enter',\n\n  // Space variants\n  ' ': 'Space',\n  space: 'Space',\n  Spacebar: 'Space',\n  spacebar: 'Space',\n\n  // Tab variants\n  tab: 'Tab',\n\n  // Backspace variants\n  backspace: 'Backspace',\n\n  // Delete variants\n  Del: 'Delete',\n  del: 'Delete',\n  delete: 'Delete',\n\n  // Arrow key variants\n  Up: 'ArrowUp',\n  up: 'ArrowUp',\n  arrowup: 'ArrowUp',\n  Down: 'ArrowDown',\n  down: 'ArrowDown',\n  arrowdown: 'ArrowDown',\n  Left: 'ArrowLeft',\n  left: 'ArrowLeft',\n  arrowleft: 'ArrowLeft',\n  Right: 'ArrowRight',\n  right: 'ArrowRight',\n  arrowright: 'ArrowRight',\n\n  // Navigation variants\n  home: 'Home',\n  end: 'End',\n  pageup: 'PageUp',\n  pagedown: 'PageDown',\n  PgUp: 'PageUp',\n  PgDn: 'PageDown',\n  pgup: 'PageUp',\n  pgdn: 'PageDown',\n}\n\n/**\n * Normalizes a key name to its canonical form.\n *\n * Converts various key name formats (aliases, case variations) into the standard\n * canonical names used throughout the library. This enables a more forgiving API\n * where users can write keys in different ways and still get correct behavior.\n *\n * Normalization rules:\n * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')\n * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')\n * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')\n * 4. Other keys → returned as-is (already canonical or unknown)\n *\n * @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n *\n * @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n */\nexport function isSingleLetterKey(key: string): boolean {\n  return /^\\p{Letter}$/u.test(key)\n}\n\n/**\n * Normalizes a key name to its canonical form.\n *\n * @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n *\n * @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n */\nexport function normalizeKeyName(key: string): string {\n  // Check aliases first\n  if (key in KEY_ALIASES) {\n    return KEY_ALIASES[key]!\n  }\n\n  if (isSingleLetterKey(key)) {\n    const upper = key.toUpperCase()\n    // Some Unicode letters (e.g., 'ß') uppercase to multi-character sequences\n    // ('SS'). Avoid changing the string length so the rest of the matching\n    // logic can rely on a stable single-character key value.\n    return upper.length === 1 ? upper : key\n  }\n\n  // Check if it's a function key (normalize case)\n  const upperKey = key.toUpperCase()\n  if (/^F([1-9]|1[0-2])$/.test(upperKey)) {\n    return upperKey\n  }\n\n  return key\n}\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/**\n * Modifier key symbols for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n */\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: '⌃',\n  Alt: '⌥',\n  Shift: '⇧',\n  Meta: '⌘',\n  Mod: '⌘',\n}\n\n/**\n * Modifier key labels for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style text labels\n * (e.g., 'Control' for Control, 'Option' for Alt, 'Cmd' for Meta) instead of symbols.\n * This provides a familiar macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_LABELS['Control'] // 'control'\n * MAC_MODIFIER_LABELS['Alt'] // 'option'\n * MAC_MODIFIER_LABELS['Shift'] // 'shift'\n * MAC_MODIFIER_LABELS['Meta'] // 'cmd'\n * ```\n */\nexport const MAC_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: 'Control',\n  Alt: 'Option',\n  Shift: 'Shift',\n  Meta: 'Cmd',\n  Mod: 'Cmd',\n}\n\n/**\n * Modifier key labels for Windows/Linux display.\n *\n * Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n */\nexport const WINDOWS_MODIFIER_LABELS: Record<\n  CanonicalModifier | 'Mod',\n  string\n> = {\n  Control: 'Ctrl',\n  Alt: 'Alt',\n  Shift: 'Shift',\n  Meta: 'Win',\n  Mod: 'Ctrl',\n}\n\nexport const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> =\n  {\n    ...WINDOWS_MODIFIER_LABELS,\n    Meta: 'Super',\n  }\n\nexport const PUNCTUATION_KEY_DISPLAY_LABELS = {\n  '`': 'Backquote',\n  '\\\\': 'Backslash',\n  '[': 'Left Bracket',\n  ']': 'Right Bracket',\n  ',': 'Comma',\n  '=': 'Equal',\n  '-': 'Minus',\n  '.': 'Period',\n  ';': 'Semicolon',\n} as const satisfies Record<string, string>\n\n/**\n * Special key symbols for display formatting.\n *\n * Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n *\n * @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS = {\n  ArrowUp: '↑',\n  ArrowDown: '↓',\n  ArrowLeft: '←',\n  ArrowRight: '→',\n  Enter: '↵',\n  Escape: 'Esc',\n  Backspace: '⌫',\n  Delete: '⌦',\n  Tab: '⇥',\n  Space: '␣',\n} as const satisfies Record<string, string>\n"],"mappings":"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"}
+{"version":3,"file":"constants.cjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["import type {\n  CanonicalModifier,\n  EditingKey,\n  FunctionKey,\n  LetterKey,\n  NavigationKey,\n  NumberKey,\n  PunctuationKey,\n} from './hotkey'\n\n/**\n * Detects the current platform based on browser navigator properties.\n *\n * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n *\n * @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n *\n * @example\n * ```ts\n * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n */\nexport function detectPlatform(): 'mac' | 'windows' | 'linux' {\n  if (typeof navigator === 'undefined') {\n    return 'linux' // Default for SSR\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const platform = navigator.platform?.toLowerCase() ?? ''\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n  if (platform.includes('mac') || userAgent.includes('mac')) {\n    return 'mac'\n  }\n  if (platform.includes('win') || userAgent.includes('win')) {\n    return 'windows'\n  }\n  return 'linux'\n}\n\n/**\n * Canonical order for modifiers in normalized hotkey strings.\n *\n * Defines the standard order in which modifiers should appear when formatting\n * hotkeys. This ensures consistent, predictable output across the library.\n *\n * Order: Control → Alt → Shift → Meta\n *\n * @example\n * ```ts\n * // Input: 'Shift+Control+Meta+S'\n * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)\n * ```\n */\nexport const MODIFIER_ORDER: Array<CanonicalModifier> = [\n  'Control',\n  'Alt',\n  'Shift',\n  'Meta',\n]\n\n/**\n * Set of canonical modifier key names for fast lookup.\n *\n * Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when\n * a modifier is released so we can clear non-modifier keys whose keyup events\n * may have been swallowed by the OS (e.g. macOS Cmd+key combos).\n */\nexport const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)\n\n/**\n * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.\n *\n * This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')\n * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the\n * platform-adaptive 'Mod' token.\n *\n * The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`\n * based on the detected platform (Command on Mac, Control elsewhere).\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * MODIFIER_ALIASES['Ctrl'] // 'Control'\n * MODIFIER_ALIASES['Cmd'] // 'Meta'\n * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)\n * ```\n */\nexport const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'> = {\n  // Control variants\n  Control: 'Control',\n  Ctrl: 'Control',\n  control: 'Control',\n  ctrl: 'Control',\n\n  // Shift variants\n  Shift: 'Shift',\n  shift: 'Shift',\n\n  // Alt variants\n  Alt: 'Alt',\n  Option: 'Alt',\n  alt: 'Alt',\n  option: 'Alt',\n\n  // Meta/Command variants\n  Command: 'Meta',\n  Cmd: 'Meta',\n  Meta: 'Meta',\n  command: 'Meta',\n  cmd: 'Meta',\n  meta: 'Meta',\n\n  // DOM `KeyboardEvent.key` spellings for the meta / Windows key\n  OS: 'Meta',\n  os: 'Meta',\n  Win: 'Meta',\n  win: 'Meta',\n\n  // Platform-adaptive (resolved at runtime)\n  CommandOrControl: 'Mod',\n  Mod: 'Mod',\n  commandorcontrol: 'Mod',\n  mod: 'Mod',\n}\n\n/**\n * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n *\n * The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n *\n * This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n *\n * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n *\n * @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n */\nexport function resolveModifier(\n  modifier: CanonicalModifier | 'Mod',\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): CanonicalModifier {\n  if (modifier === 'Mod') {\n    return platform === 'mac' ? 'Meta' : 'Control'\n  }\n  return modifier\n}\n\n/**\n * Set of all valid letter keys (A-Z).\n *\n * Used for validation and type checking. Letter keys are matched case-insensitively\n * in hotkey matching, but normalized to uppercase in canonical form.\n */\nexport const LETTER_KEYS = new Set<LetterKey>([\n  'A',\n  'B',\n  'C',\n  'D',\n  'E',\n  'F',\n  'G',\n  'H',\n  'I',\n  'J',\n  'K',\n  'L',\n  'M',\n  'N',\n  'O',\n  'P',\n  'Q',\n  'R',\n  'S',\n  'T',\n  'U',\n  'V',\n  'W',\n  'X',\n  'Y',\n  'Z',\n])\n\n/**\n * Set of all valid number keys (0-9).\n *\n * Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid\n * layout-dependent behavior.\n */\nexport const NUMBER_KEYS = new Set<NumberKey>([\n  '0',\n  '1',\n  '2',\n  '3',\n  '4',\n  '5',\n  '6',\n  '7',\n  '8',\n  '9',\n])\n\n/**\n * Set of all valid function keys (F1-F12).\n *\n * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,\n * Alt+F4 to close windows) and application-specific commands.\n */\nexport const FUNCTION_KEYS = new Set<FunctionKey>([\n  'F1',\n  'F2',\n  'F3',\n  'F4',\n  'F5',\n  'F6',\n  'F7',\n  'F8',\n  'F9',\n  'F10',\n  'F11',\n  'F12',\n])\n\n/**\n * Set of all valid navigation keys for cursor movement and document navigation.\n *\n * Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).\n * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or\n * navigation shortcuts (Alt+ArrowLeft for back).\n */\nexport const NAVIGATION_KEYS = new Set<NavigationKey>([\n  'ArrowUp',\n  'ArrowDown',\n  'ArrowLeft',\n  'ArrowRight',\n  'Home',\n  'End',\n  'PageUp',\n  'PageDown',\n])\n\n/**\n * Set of all valid editing and special keys.\n *\n * Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and\n * special actions (Escape, Space). These keys are frequently combined with modifiers\n * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).\n */\nexport const EDITING_KEYS = new Set<EditingKey>([\n  'Enter',\n  'Escape',\n  'Space',\n  'Tab',\n  'Backspace',\n  'Delete',\n])\n\n/**\n * Set of all valid punctuation keys commonly used in keyboard shortcuts.\n *\n * These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,\n * typically US keyboard layout). Common shortcuts include:\n * - `Mod+/` - Toggle comment\n * - `Mod+[` / `Mod+]` - Indent/outdent\n * - `Mod+=` / `Mod+-` - Zoom in/out\n *\n * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.\n */\nexport const PUNCTUATION_KEYS = new Set<PunctuationKey>([\n  '/',\n  '[',\n  ']',\n  '\\\\',\n  '=',\n  '-',\n  ',',\n  '.',\n  ';',\n  '`',\n])\n\n/**\n * Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.\n *\n * On macOS, holding the Option (Alt) key transforms punctuation keys into special characters\n * (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.\n * However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables\n * falling back to `event.code` for punctuation keys, similar to the existing `Key*`/`Digit*`\n * fallbacks for letters and digits.\n */\nexport const PUNCTUATION_CODE_MAP: Record<string, string> = {\n  Backquote: '`',\n  Backslash: '\\\\',\n  BracketLeft: '[',\n  BracketRight: ']',\n  Comma: ',',\n  Equal: '=',\n  Minus: '-',\n  Period: '.',\n  Semicolon: ';',\n  Slash: '/',\n}\n\n/**\n * Set of all valid non-modifier keys.\n *\n * This is the union of all key type sets (letters, numbers, function keys, navigation,\n * editing, and punctuation). Used primarily for validation to check if a key string\n * is recognized and will have type-safe autocomplete support.\n *\n * @see {@link LETTER_KEYS}\n * @see {@link NUMBER_KEYS}\n * @see {@link FUNCTION_KEYS}\n * @see {@link NAVIGATION_KEYS}\n * @see {@link EDITING_KEYS}\n * @see {@link PUNCTUATION_KEYS}\n */\nexport const ALL_KEYS = new Set([\n  ...LETTER_KEYS,\n  ...NUMBER_KEYS,\n  ...FUNCTION_KEYS,\n  ...NAVIGATION_KEYS,\n  ...EDITING_KEYS,\n  ...PUNCTUATION_KEYS,\n])\n\n/**\n * Maps key name aliases to their canonical form.\n *\n * Handles common variations and alternative names for keys to provide a more\n * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and\n * they'll all normalize to 'Escape'.\n *\n * This map is used internally by `normalizeKeyName()` to convert user input\n * into the canonical key names used throughout the library.\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * KEY_ALIASES['Esc'] // 'Escape'\n * KEY_ALIASES['Del'] // 'Delete'\n * KEY_ALIASES['Up'] // 'ArrowUp'\n * ```\n */\nconst KEY_ALIASES: Record<string, string> = {\n  // Escape variants\n  Esc: 'Escape',\n  esc: 'Escape',\n  escape: 'Escape',\n\n  // Enter variants\n  Return: 'Enter',\n  return: 'Enter',\n  enter: 'Enter',\n\n  // Space variants\n  ' ': 'Space',\n  space: 'Space',\n  Spacebar: 'Space',\n  spacebar: 'Space',\n\n  // Tab variants\n  tab: 'Tab',\n\n  // Backspace variants\n  backspace: 'Backspace',\n\n  // Delete variants\n  Del: 'Delete',\n  del: 'Delete',\n  delete: 'Delete',\n\n  // Arrow key variants\n  Up: 'ArrowUp',\n  up: 'ArrowUp',\n  arrowup: 'ArrowUp',\n  Down: 'ArrowDown',\n  down: 'ArrowDown',\n  arrowdown: 'ArrowDown',\n  Left: 'ArrowLeft',\n  left: 'ArrowLeft',\n  arrowleft: 'ArrowLeft',\n  Right: 'ArrowRight',\n  right: 'ArrowRight',\n  arrowright: 'ArrowRight',\n\n  // Navigation variants\n  home: 'Home',\n  end: 'End',\n  pageup: 'PageUp',\n  pagedown: 'PageDown',\n  PgUp: 'PageUp',\n  PgDn: 'PageDown',\n  pgup: 'PageUp',\n  pgdn: 'PageDown',\n}\n\n/**\n * Normalizes a key name to its canonical form.\n *\n * Converts various key name formats (aliases, case variations) into the standard\n * canonical names used throughout the library. This enables a more forgiving API\n * where users can write keys in different ways and still get correct behavior.\n *\n * Normalization rules:\n * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')\n * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')\n * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')\n * 4. Other keys → returned as-is (already canonical or unknown)\n *\n * @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n *\n * @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n */\nexport function isSingleLetterKey(key: string): boolean {\n  return /^\\p{Letter}$/u.test(key)\n}\n\n/**\n * Normalizes a key name to its canonical form.\n *\n * @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n *\n * @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n */\nexport function normalizeKeyName(key: string): string {\n  // key can be undefined in rare cases\n  // (browser extensions synthesizing key events, accessibility tools, certain OS/browser combinations).\n  if (!key) return ''\n  // Check aliases first\n  if (key in KEY_ALIASES) {\n    return KEY_ALIASES[key]!\n  }\n\n  if (isSingleLetterKey(key)) {\n    const upper = key.toUpperCase()\n    // Some Unicode letters (e.g., 'ß') uppercase to multi-character sequences\n    // ('SS'). Avoid changing the string length so the rest of the matching\n    // logic can rely on a stable single-character key value.\n    return upper.length === 1 ? upper : key\n  }\n\n  // Check if it's a function key (normalize case)\n  const upperKey = key.toUpperCase()\n  if (/^F([1-9]|1[0-2])$/.test(upperKey)) {\n    return upperKey\n  }\n\n  return key\n}\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/**\n * Modifier key symbols for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n */\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: '⌃',\n  Alt: '⌥',\n  Shift: '⇧',\n  Meta: '⌘',\n  Mod: '⌘',\n}\n\n/**\n * Modifier key labels for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style text labels\n * (e.g., 'Control' for Control, 'Option' for Alt, 'Cmd' for Meta) instead of symbols.\n * This provides a familiar macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_LABELS['Control'] // 'control'\n * MAC_MODIFIER_LABELS['Alt'] // 'option'\n * MAC_MODIFIER_LABELS['Shift'] // 'shift'\n * MAC_MODIFIER_LABELS['Meta'] // 'cmd'\n * ```\n */\nexport const MAC_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: 'Control',\n  Alt: 'Option',\n  Shift: 'Shift',\n  Meta: 'Cmd',\n  Mod: 'Cmd',\n}\n\n/**\n * Modifier key labels for Windows/Linux display.\n *\n * Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n */\nexport const WINDOWS_MODIFIER_LABELS: Record<\n  CanonicalModifier | 'Mod',\n  string\n> = {\n  Control: 'Ctrl',\n  Alt: 'Alt',\n  Shift: 'Shift',\n  Meta: 'Win',\n  Mod: 'Ctrl',\n}\n\nexport const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> =\n  {\n    ...WINDOWS_MODIFIER_LABELS,\n    Meta: 'Super',\n  }\n\nexport const PUNCTUATION_KEY_DISPLAY_LABELS = {\n  '`': 'Backquote',\n  '\\\\': 'Backslash',\n  '[': 'Left Bracket',\n  ']': 'Right Bracket',\n  ',': 'Comma',\n  '=': 'Equal',\n  '-': 'Minus',\n  '.': 'Period',\n  ';': 'Semicolon',\n} as const satisfies Record<string, string>\n\n/**\n * Special key symbols for display formatting.\n *\n * Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n *\n * @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS = {\n  ArrowUp: '↑',\n  ArrowDown: '↓',\n  ArrowLeft: '←',\n  ArrowRight: '→',\n  Enter: '↵',\n  Escape: 'Esc',\n  Backspace: '⌫',\n  Delete: '⌦',\n  Tab: '⇥',\n  Space: '␣',\n} as const satisfies Record<string, string>\n"],"mappings":"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"}

package/dist/constants.js

@@ -390,6 +390,7 @@ function isSingleLetterKey(key) {
 * ```
 */
 function normalizeKeyName(key) {
+	if (!key) return "";
 	if (key in KEY_ALIASES) return KEY_ALIASES[key];
 	if (isSingleLetterKey(key)) {
 		const upper = key.toUpperCase();

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","names":[],"sources":["../src/constants.ts"],"sourcesContent":["import type {\n  CanonicalModifier,\n  EditingKey,\n  FunctionKey,\n  LetterKey,\n  NavigationKey,\n  NumberKey,\n  PunctuationKey,\n} from './hotkey'\n\n/**\n * Detects the current platform based on browser navigator properties.\n *\n * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n *\n * @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n *\n * @example\n * ```ts\n * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n */\nexport function detectPlatform(): 'mac' | 'windows' | 'linux' {\n  if (typeof navigator === 'undefined') {\n    return 'linux' // Default for SSR\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const platform = navigator.platform?.toLowerCase() ?? ''\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n  if (platform.includes('mac') || userAgent.includes('mac')) {\n    return 'mac'\n  }\n  if (platform.includes('win') || userAgent.includes('win')) {\n    return 'windows'\n  }\n  return 'linux'\n}\n\n/**\n * Canonical order for modifiers in normalized hotkey strings.\n *\n * Defines the standard order in which modifiers should appear when formatting\n * hotkeys. This ensures consistent, predictable output across the library.\n *\n * Order: Control → Alt → Shift → Meta\n *\n * @example\n * ```ts\n * // Input: 'Shift+Control+Meta+S'\n * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)\n * ```\n */\nexport const MODIFIER_ORDER: Array<CanonicalModifier> = [\n  'Control',\n  'Alt',\n  'Shift',\n  'Meta',\n]\n\n/**\n * Set of canonical modifier key names for fast lookup.\n *\n * Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when\n * a modifier is released so we can clear non-modifier keys whose keyup events\n * may have been swallowed by the OS (e.g. macOS Cmd+key combos).\n */\nexport const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)\n\n/**\n * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.\n *\n * This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')\n * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the\n * platform-adaptive 'Mod' token.\n *\n * The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`\n * based on the detected platform (Command on Mac, Control elsewhere).\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * MODIFIER_ALIASES['Ctrl'] // 'Control'\n * MODIFIER_ALIASES['Cmd'] // 'Meta'\n * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)\n * ```\n */\nexport const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'> = {\n  // Control variants\n  Control: 'Control',\n  Ctrl: 'Control',\n  control: 'Control',\n  ctrl: 'Control',\n\n  // Shift variants\n  Shift: 'Shift',\n  shift: 'Shift',\n\n  // Alt variants\n  Alt: 'Alt',\n  Option: 'Alt',\n  alt: 'Alt',\n  option: 'Alt',\n\n  // Meta/Command variants\n  Command: 'Meta',\n  Cmd: 'Meta',\n  Meta: 'Meta',\n  command: 'Meta',\n  cmd: 'Meta',\n  meta: 'Meta',\n\n  // DOM `KeyboardEvent.key` spellings for the meta / Windows key\n  OS: 'Meta',\n  os: 'Meta',\n  Win: 'Meta',\n  win: 'Meta',\n\n  // Platform-adaptive (resolved at runtime)\n  CommandOrControl: 'Mod',\n  Mod: 'Mod',\n  commandorcontrol: 'Mod',\n  mod: 'Mod',\n}\n\n/**\n * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n *\n * The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n *\n * This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n *\n * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n *\n * @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n */\nexport function resolveModifier(\n  modifier: CanonicalModifier | 'Mod',\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): CanonicalModifier {\n  if (modifier === 'Mod') {\n    return platform === 'mac' ? 'Meta' : 'Control'\n  }\n  return modifier\n}\n\n/**\n * Set of all valid letter keys (A-Z).\n *\n * Used for validation and type checking. Letter keys are matched case-insensitively\n * in hotkey matching, but normalized to uppercase in canonical form.\n */\nexport const LETTER_KEYS = new Set<LetterKey>([\n  'A',\n  'B',\n  'C',\n  'D',\n  'E',\n  'F',\n  'G',\n  'H',\n  'I',\n  'J',\n  'K',\n  'L',\n  'M',\n  'N',\n  'O',\n  'P',\n  'Q',\n  'R',\n  'S',\n  'T',\n  'U',\n  'V',\n  'W',\n  'X',\n  'Y',\n  'Z',\n])\n\n/**\n * Set of all valid number keys (0-9).\n *\n * Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid\n * layout-dependent behavior.\n */\nexport const NUMBER_KEYS = new Set<NumberKey>([\n  '0',\n  '1',\n  '2',\n  '3',\n  '4',\n  '5',\n  '6',\n  '7',\n  '8',\n  '9',\n])\n\n/**\n * Set of all valid function keys (F1-F12).\n *\n * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,\n * Alt+F4 to close windows) and application-specific commands.\n */\nexport const FUNCTION_KEYS = new Set<FunctionKey>([\n  'F1',\n  'F2',\n  'F3',\n  'F4',\n  'F5',\n  'F6',\n  'F7',\n  'F8',\n  'F9',\n  'F10',\n  'F11',\n  'F12',\n])\n\n/**\n * Set of all valid navigation keys for cursor movement and document navigation.\n *\n * Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).\n * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or\n * navigation shortcuts (Alt+ArrowLeft for back).\n */\nexport const NAVIGATION_KEYS = new Set<NavigationKey>([\n  'ArrowUp',\n  'ArrowDown',\n  'ArrowLeft',\n  'ArrowRight',\n  'Home',\n  'End',\n  'PageUp',\n  'PageDown',\n])\n\n/**\n * Set of all valid editing and special keys.\n *\n * Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and\n * special actions (Escape, Space). These keys are frequently combined with modifiers\n * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).\n */\nexport const EDITING_KEYS = new Set<EditingKey>([\n  'Enter',\n  'Escape',\n  'Space',\n  'Tab',\n  'Backspace',\n  'Delete',\n])\n\n/**\n * Set of all valid punctuation keys commonly used in keyboard shortcuts.\n *\n * These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,\n * typically US keyboard layout). Common shortcuts include:\n * - `Mod+/` - Toggle comment\n * - `Mod+[` / `Mod+]` - Indent/outdent\n * - `Mod+=` / `Mod+-` - Zoom in/out\n *\n * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.\n */\nexport const PUNCTUATION_KEYS = new Set<PunctuationKey>([\n  '/',\n  '[',\n  ']',\n  '\\\\',\n  '=',\n  '-',\n  ',',\n  '.',\n  ';',\n  '`',\n])\n\n/**\n * Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.\n *\n * On macOS, holding the Option (Alt) key transforms punctuation keys into special characters\n * (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.\n * However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables\n * falling back to `event.code` for punctuation keys, similar to the existing `Key*`/`Digit*`\n * fallbacks for letters and digits.\n */\nexport const PUNCTUATION_CODE_MAP: Record<string, string> = {\n  Backquote: '`',\n  Backslash: '\\\\',\n  BracketLeft: '[',\n  BracketRight: ']',\n  Comma: ',',\n  Equal: '=',\n  Minus: '-',\n  Period: '.',\n  Semicolon: ';',\n  Slash: '/',\n}\n\n/**\n * Set of all valid non-modifier keys.\n *\n * This is the union of all key type sets (letters, numbers, function keys, navigation,\n * editing, and punctuation). Used primarily for validation to check if a key string\n * is recognized and will have type-safe autocomplete support.\n *\n * @see {@link LETTER_KEYS}\n * @see {@link NUMBER_KEYS}\n * @see {@link FUNCTION_KEYS}\n * @see {@link NAVIGATION_KEYS}\n * @see {@link EDITING_KEYS}\n * @see {@link PUNCTUATION_KEYS}\n */\nexport const ALL_KEYS = new Set([\n  ...LETTER_KEYS,\n  ...NUMBER_KEYS,\n  ...FUNCTION_KEYS,\n  ...NAVIGATION_KEYS,\n  ...EDITING_KEYS,\n  ...PUNCTUATION_KEYS,\n])\n\n/**\n * Maps key name aliases to their canonical form.\n *\n * Handles common variations and alternative names for keys to provide a more\n * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and\n * they'll all normalize to 'Escape'.\n *\n * This map is used internally by `normalizeKeyName()` to convert user input\n * into the canonical key names used throughout the library.\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * KEY_ALIASES['Esc'] // 'Escape'\n * KEY_ALIASES['Del'] // 'Delete'\n * KEY_ALIASES['Up'] // 'ArrowUp'\n * ```\n */\nconst KEY_ALIASES: Record<string, string> = {\n  // Escape variants\n  Esc: 'Escape',\n  esc: 'Escape',\n  escape: 'Escape',\n\n  // Enter variants\n  Return: 'Enter',\n  return: 'Enter',\n  enter: 'Enter',\n\n  // Space variants\n  ' ': 'Space',\n  space: 'Space',\n  Spacebar: 'Space',\n  spacebar: 'Space',\n\n  // Tab variants\n  tab: 'Tab',\n\n  // Backspace variants\n  backspace: 'Backspace',\n\n  // Delete variants\n  Del: 'Delete',\n  del: 'Delete',\n  delete: 'Delete',\n\n  // Arrow key variants\n  Up: 'ArrowUp',\n  up: 'ArrowUp',\n  arrowup: 'ArrowUp',\n  Down: 'ArrowDown',\n  down: 'ArrowDown',\n  arrowdown: 'ArrowDown',\n  Left: 'ArrowLeft',\n  left: 'ArrowLeft',\n  arrowleft: 'ArrowLeft',\n  Right: 'ArrowRight',\n  right: 'ArrowRight',\n  arrowright: 'ArrowRight',\n\n  // Navigation variants\n  home: 'Home',\n  end: 'End',\n  pageup: 'PageUp',\n  pagedown: 'PageDown',\n  PgUp: 'PageUp',\n  PgDn: 'PageDown',\n  pgup: 'PageUp',\n  pgdn: 'PageDown',\n}\n\n/**\n * Normalizes a key name to its canonical form.\n *\n * Converts various key name formats (aliases, case variations) into the standard\n * canonical names used throughout the library. This enables a more forgiving API\n * where users can write keys in different ways and still get correct behavior.\n *\n * Normalization rules:\n * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')\n * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')\n * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')\n * 4. Other keys → returned as-is (already canonical or unknown)\n *\n * @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n *\n * @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n */\nexport function isSingleLetterKey(key: string): boolean {\n  return /^\\p{Letter}$/u.test(key)\n}\n\n/**\n * Normalizes a key name to its canonical form.\n *\n * @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n *\n * @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n */\nexport function normalizeKeyName(key: string): string {\n  // Check aliases first\n  if (key in KEY_ALIASES) {\n    return KEY_ALIASES[key]!\n  }\n\n  if (isSingleLetterKey(key)) {\n    const upper = key.toUpperCase()\n    // Some Unicode letters (e.g., 'ß') uppercase to multi-character sequences\n    // ('SS'). Avoid changing the string length so the rest of the matching\n    // logic can rely on a stable single-character key value.\n    return upper.length === 1 ? upper : key\n  }\n\n  // Check if it's a function key (normalize case)\n  const upperKey = key.toUpperCase()\n  if (/^F([1-9]|1[0-2])$/.test(upperKey)) {\n    return upperKey\n  }\n\n  return key\n}\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/**\n * Modifier key symbols for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n */\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: '⌃',\n  Alt: '⌥',\n  Shift: '⇧',\n  Meta: '⌘',\n  Mod: '⌘',\n}\n\n/**\n * Modifier key labels for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style text labels\n * (e.g., 'Control' for Control, 'Option' for Alt, 'Cmd' for Meta) instead of symbols.\n * This provides a familiar macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_LABELS['Control'] // 'control'\n * MAC_MODIFIER_LABELS['Alt'] // 'option'\n * MAC_MODIFIER_LABELS['Shift'] // 'shift'\n * MAC_MODIFIER_LABELS['Meta'] // 'cmd'\n * ```\n */\nexport const MAC_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: 'Control',\n  Alt: 'Option',\n  Shift: 'Shift',\n  Meta: 'Cmd',\n  Mod: 'Cmd',\n}\n\n/**\n * Modifier key labels for Windows/Linux display.\n *\n * Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n */\nexport const WINDOWS_MODIFIER_LABELS: Record<\n  CanonicalModifier | 'Mod',\n  string\n> = {\n  Control: 'Ctrl',\n  Alt: 'Alt',\n  Shift: 'Shift',\n  Meta: 'Win',\n  Mod: 'Ctrl',\n}\n\nexport const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> =\n  {\n    ...WINDOWS_MODIFIER_LABELS,\n    Meta: 'Super',\n  }\n\nexport const PUNCTUATION_KEY_DISPLAY_LABELS = {\n  '`': 'Backquote',\n  '\\\\': 'Backslash',\n  '[': 'Left Bracket',\n  ']': 'Right Bracket',\n  ',': 'Comma',\n  '=': 'Equal',\n  '-': 'Minus',\n  '.': 'Period',\n  ';': 'Semicolon',\n} as const satisfies Record<string, string>\n\n/**\n * Special key symbols for display formatting.\n *\n * Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n *\n * @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS = {\n  ArrowUp: '↑',\n  ArrowDown: '↓',\n  ArrowLeft: '←',\n  ArrowRight: '→',\n  Enter: '↵',\n  Escape: 'Esc',\n  Backspace: '⌫',\n  Delete: '⌦',\n  Tab: '⇥',\n  Space: '␣',\n} as const satisfies Record<string, string>\n"],"mappings":"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"}
+{"version":3,"file":"constants.js","names":[],"sources":["../src/constants.ts"],"sourcesContent":["import type {\n  CanonicalModifier,\n  EditingKey,\n  FunctionKey,\n  LetterKey,\n  NavigationKey,\n  NumberKey,\n  PunctuationKey,\n} from './hotkey'\n\n/**\n * Detects the current platform based on browser navigator properties.\n *\n * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n *\n * @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n *\n * @example\n * ```ts\n * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n */\nexport function detectPlatform(): 'mac' | 'windows' | 'linux' {\n  if (typeof navigator === 'undefined') {\n    return 'linux' // Default for SSR\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const platform = navigator.platform?.toLowerCase() ?? ''\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n  if (platform.includes('mac') || userAgent.includes('mac')) {\n    return 'mac'\n  }\n  if (platform.includes('win') || userAgent.includes('win')) {\n    return 'windows'\n  }\n  return 'linux'\n}\n\n/**\n * Canonical order for modifiers in normalized hotkey strings.\n *\n * Defines the standard order in which modifiers should appear when formatting\n * hotkeys. This ensures consistent, predictable output across the library.\n *\n * Order: Control → Alt → Shift → Meta\n *\n * @example\n * ```ts\n * // Input: 'Shift+Control+Meta+S'\n * // Normalized: 'Control+Alt+Shift+Meta+S' (following MODIFIER_ORDER)\n * ```\n */\nexport const MODIFIER_ORDER: Array<CanonicalModifier> = [\n  'Control',\n  'Alt',\n  'Shift',\n  'Meta',\n]\n\n/**\n * Set of canonical modifier key names for fast lookup.\n *\n * Derived from `MODIFIER_ORDER` to ensure consistency. Used to detect when\n * a modifier is released so we can clear non-modifier keys whose keyup events\n * may have been swallowed by the OS (e.g. macOS Cmd+key combos).\n */\nexport const MODIFIER_KEYS = new Set<string>(MODIFIER_ORDER)\n\n/**\n * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.\n *\n * This map allows users to write hotkeys using various aliases (e.g., 'Ctrl', 'Cmd', 'Option')\n * which are then normalized to canonical names ('Control', 'Meta', 'Alt') or the\n * platform-adaptive 'Mod' token.\n *\n * The 'Mod' and 'CommandOrControl' aliases are resolved at runtime via `resolveModifier()`\n * based on the detected platform (Command on Mac, Control elsewhere).\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * MODIFIER_ALIASES['Ctrl'] // 'Control'\n * MODIFIER_ALIASES['Cmd'] // 'Meta'\n * MODIFIER_ALIASES['Mod'] // 'Mod' (resolved at runtime)\n * ```\n */\nexport const MODIFIER_ALIASES: Record<string, CanonicalModifier | 'Mod'> = {\n  // Control variants\n  Control: 'Control',\n  Ctrl: 'Control',\n  control: 'Control',\n  ctrl: 'Control',\n\n  // Shift variants\n  Shift: 'Shift',\n  shift: 'Shift',\n\n  // Alt variants\n  Alt: 'Alt',\n  Option: 'Alt',\n  alt: 'Alt',\n  option: 'Alt',\n\n  // Meta/Command variants\n  Command: 'Meta',\n  Cmd: 'Meta',\n  Meta: 'Meta',\n  command: 'Meta',\n  cmd: 'Meta',\n  meta: 'Meta',\n\n  // DOM `KeyboardEvent.key` spellings for the meta / Windows key\n  OS: 'Meta',\n  os: 'Meta',\n  Win: 'Meta',\n  win: 'Meta',\n\n  // Platform-adaptive (resolved at runtime)\n  CommandOrControl: 'Mod',\n  Mod: 'Mod',\n  commandorcontrol: 'Mod',\n  mod: 'Mod',\n}\n\n/**\n * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n *\n * The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n *\n * This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n *\n * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n *\n * @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n */\nexport function resolveModifier(\n  modifier: CanonicalModifier | 'Mod',\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): CanonicalModifier {\n  if (modifier === 'Mod') {\n    return platform === 'mac' ? 'Meta' : 'Control'\n  }\n  return modifier\n}\n\n/**\n * Set of all valid letter keys (A-Z).\n *\n * Used for validation and type checking. Letter keys are matched case-insensitively\n * in hotkey matching, but normalized to uppercase in canonical form.\n */\nexport const LETTER_KEYS = new Set<LetterKey>([\n  'A',\n  'B',\n  'C',\n  'D',\n  'E',\n  'F',\n  'G',\n  'H',\n  'I',\n  'J',\n  'K',\n  'L',\n  'M',\n  'N',\n  'O',\n  'P',\n  'Q',\n  'R',\n  'S',\n  'T',\n  'U',\n  'V',\n  'W',\n  'X',\n  'Y',\n  'Z',\n])\n\n/**\n * Set of all valid number keys (0-9).\n *\n * Note: Number keys are affected by Shift (Shift+1 → '!' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid\n * layout-dependent behavior.\n */\nexport const NUMBER_KEYS = new Set<NumberKey>([\n  '0',\n  '1',\n  '2',\n  '3',\n  '4',\n  '5',\n  '6',\n  '7',\n  '8',\n  '9',\n])\n\n/**\n * Set of all valid function keys (F1-F12).\n *\n * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,\n * Alt+F4 to close windows) and application-specific commands.\n */\nexport const FUNCTION_KEYS = new Set<FunctionKey>([\n  'F1',\n  'F2',\n  'F3',\n  'F4',\n  'F5',\n  'F6',\n  'F7',\n  'F8',\n  'F9',\n  'F10',\n  'F11',\n  'F12',\n])\n\n/**\n * Set of all valid navigation keys for cursor movement and document navigation.\n *\n * Includes arrow keys, Home/End (line navigation), and PageUp/PageDown (page navigation).\n * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or\n * navigation shortcuts (Alt+ArrowLeft for back).\n */\nexport const NAVIGATION_KEYS = new Set<NavigationKey>([\n  'ArrowUp',\n  'ArrowDown',\n  'ArrowLeft',\n  'ArrowRight',\n  'Home',\n  'End',\n  'PageUp',\n  'PageDown',\n])\n\n/**\n * Set of all valid editing and special keys.\n *\n * Includes keys commonly used for text editing (Enter, Backspace, Delete, Tab) and\n * special actions (Escape, Space). These keys are frequently combined with modifiers\n * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).\n */\nexport const EDITING_KEYS = new Set<EditingKey>([\n  'Enter',\n  'Escape',\n  'Space',\n  'Tab',\n  'Backspace',\n  'Delete',\n])\n\n/**\n * Set of all valid punctuation keys commonly used in keyboard shortcuts.\n *\n * These are the literal characters as they appear in `KeyboardEvent.key` (layout-dependent,\n * typically US keyboard layout). Common shortcuts include:\n * - `Mod+/` - Toggle comment\n * - `Mod+[` / `Mod+]` - Indent/outdent\n * - `Mod+=` / `Mod+-` - Zoom in/out\n *\n * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),\n * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.\n */\nexport const PUNCTUATION_KEYS = new Set<PunctuationKey>([\n  '/',\n  '[',\n  ']',\n  '\\\\',\n  '=',\n  '-',\n  ',',\n  '.',\n  ';',\n  '`',\n])\n\n/**\n * Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.\n *\n * On macOS, holding the Option (Alt) key transforms punctuation keys into special characters\n * (e.g., Option+Minus → en-dash '–'), causing `event.key` to differ from the expected character.\n * However, `event.code` still reports the physical key (e.g., 'Minus'). This map enables\n * falling back to `event.code` for punctuation keys, similar to the existing `Key*`/`Digit*`\n * fallbacks for letters and digits.\n */\nexport const PUNCTUATION_CODE_MAP: Record<string, string> = {\n  Backquote: '`',\n  Backslash: '\\\\',\n  BracketLeft: '[',\n  BracketRight: ']',\n  Comma: ',',\n  Equal: '=',\n  Minus: '-',\n  Period: '.',\n  Semicolon: ';',\n  Slash: '/',\n}\n\n/**\n * Set of all valid non-modifier keys.\n *\n * This is the union of all key type sets (letters, numbers, function keys, navigation,\n * editing, and punctuation). Used primarily for validation to check if a key string\n * is recognized and will have type-safe autocomplete support.\n *\n * @see {@link LETTER_KEYS}\n * @see {@link NUMBER_KEYS}\n * @see {@link FUNCTION_KEYS}\n * @see {@link NAVIGATION_KEYS}\n * @see {@link EDITING_KEYS}\n * @see {@link PUNCTUATION_KEYS}\n */\nexport const ALL_KEYS = new Set([\n  ...LETTER_KEYS,\n  ...NUMBER_KEYS,\n  ...FUNCTION_KEYS,\n  ...NAVIGATION_KEYS,\n  ...EDITING_KEYS,\n  ...PUNCTUATION_KEYS,\n])\n\n/**\n * Maps key name aliases to their canonical form.\n *\n * Handles common variations and alternative names for keys to provide a more\n * forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and\n * they'll all normalize to 'Escape'.\n *\n * This map is used internally by `normalizeKeyName()` to convert user input\n * into the canonical key names used throughout the library.\n *\n * @remarks Case-insensitive lookups are supported via lowercase variants\n *\n * @example\n * ```ts\n * KEY_ALIASES['Esc'] // 'Escape'\n * KEY_ALIASES['Del'] // 'Delete'\n * KEY_ALIASES['Up'] // 'ArrowUp'\n * ```\n */\nconst KEY_ALIASES: Record<string, string> = {\n  // Escape variants\n  Esc: 'Escape',\n  esc: 'Escape',\n  escape: 'Escape',\n\n  // Enter variants\n  Return: 'Enter',\n  return: 'Enter',\n  enter: 'Enter',\n\n  // Space variants\n  ' ': 'Space',\n  space: 'Space',\n  Spacebar: 'Space',\n  spacebar: 'Space',\n\n  // Tab variants\n  tab: 'Tab',\n\n  // Backspace variants\n  backspace: 'Backspace',\n\n  // Delete variants\n  Del: 'Delete',\n  del: 'Delete',\n  delete: 'Delete',\n\n  // Arrow key variants\n  Up: 'ArrowUp',\n  up: 'ArrowUp',\n  arrowup: 'ArrowUp',\n  Down: 'ArrowDown',\n  down: 'ArrowDown',\n  arrowdown: 'ArrowDown',\n  Left: 'ArrowLeft',\n  left: 'ArrowLeft',\n  arrowleft: 'ArrowLeft',\n  Right: 'ArrowRight',\n  right: 'ArrowRight',\n  arrowright: 'ArrowRight',\n\n  // Navigation variants\n  home: 'Home',\n  end: 'End',\n  pageup: 'PageUp',\n  pagedown: 'PageDown',\n  PgUp: 'PageUp',\n  PgDn: 'PageDown',\n  pgup: 'PageUp',\n  pgdn: 'PageDown',\n}\n\n/**\n * Normalizes a key name to its canonical form.\n *\n * Converts various key name formats (aliases, case variations) into the standard\n * canonical names used throughout the library. This enables a more forgiving API\n * where users can write keys in different ways and still get correct behavior.\n *\n * Normalization rules:\n * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')\n * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')\n * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')\n * 4. Other keys → returned as-is (already canonical or unknown)\n *\n * @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n *\n * @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n */\nexport function isSingleLetterKey(key: string): boolean {\n  return /^\\p{Letter}$/u.test(key)\n}\n\n/**\n * Normalizes a key name to its canonical form.\n *\n * @param key - The key name to normalize (can be an alias, lowercase, etc.)\n * @returns The canonical key name\n *\n * @example\n * ```ts\n * normalizeKeyName('esc') // 'Escape'\n * normalizeKeyName('a') // 'A'\n * normalizeKeyName('f1') // 'F1'\n * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)\n * ```\n */\nexport function normalizeKeyName(key: string): string {\n  // key can be undefined in rare cases\n  // (browser extensions synthesizing key events, accessibility tools, certain OS/browser combinations).\n  if (!key) return ''\n  // Check aliases first\n  if (key in KEY_ALIASES) {\n    return KEY_ALIASES[key]!\n  }\n\n  if (isSingleLetterKey(key)) {\n    const upper = key.toUpperCase()\n    // Some Unicode letters (e.g., 'ß') uppercase to multi-character sequences\n    // ('SS'). Avoid changing the string length so the rest of the matching\n    // logic can rely on a stable single-character key value.\n    return upper.length === 1 ? upper : key\n  }\n\n  // Check if it's a function key (normalize case)\n  const upperKey = key.toUpperCase()\n  if (/^F([1-9]|1[0-2])$/.test(upperKey)) {\n    return upperKey\n  }\n\n  return key\n}\n\n// =============================================================================\n// Display Symbols\n// =============================================================================\n\n/**\n * Modifier key symbols for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style symbols\n * (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides\n * a native macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'\n * MAC_MODIFIER_SYMBOLS['Control'] // '⌃'\n * MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'\n * MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'\n * ```\n */\nexport const MAC_MODIFIER_SYMBOLS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: '⌃',\n  Alt: '⌥',\n  Shift: '⇧',\n  Meta: '⌘',\n  Mod: '⌘',\n}\n\n/**\n * Modifier key labels for macOS display.\n *\n * Used by formatting functions to display hotkeys with macOS-style text labels\n * (e.g., 'Control' for Control, 'Option' for Alt, 'Cmd' for Meta) instead of symbols.\n * This provides a familiar macOS look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * MAC_MODIFIER_LABELS['Control'] // 'control'\n * MAC_MODIFIER_LABELS['Alt'] // 'option'\n * MAC_MODIFIER_LABELS['Shift'] // 'shift'\n * MAC_MODIFIER_LABELS['Meta'] // 'cmd'\n * ```\n */\nexport const MAC_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> = {\n  Control: 'Control',\n  Alt: 'Option',\n  Shift: 'Shift',\n  Meta: 'Cmd',\n  Mod: 'Cmd',\n}\n\n/**\n * Modifier key labels for Windows/Linux display.\n *\n * Used by formatting functions to display hotkeys with standard text labels\n * (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.\n * This provides a familiar Windows/Linux look and feel in hotkey displays.\n *\n * @example\n * ```ts\n * STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'\n * STANDARD_MODIFIER_LABELS['Meta'] // 'Win'\n * STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'\n * STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'\n * ```\n */\nexport const WINDOWS_MODIFIER_LABELS: Record<\n  CanonicalModifier | 'Mod',\n  string\n> = {\n  Control: 'Ctrl',\n  Alt: 'Alt',\n  Shift: 'Shift',\n  Meta: 'Win',\n  Mod: 'Ctrl',\n}\n\nexport const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> =\n  {\n    ...WINDOWS_MODIFIER_LABELS,\n    Meta: 'Super',\n  }\n\nexport const PUNCTUATION_KEY_DISPLAY_LABELS = {\n  '`': 'Backquote',\n  '\\\\': 'Backslash',\n  '[': 'Left Bracket',\n  ']': 'Right Bracket',\n  ',': 'Comma',\n  '=': 'Equal',\n  '-': 'Minus',\n  '.': 'Period',\n  ';': 'Semicolon',\n} as const satisfies Record<string, string>\n\n/**\n * Special key symbols for display formatting.\n *\n * Maps certain keys to their visual symbols for better readability in hotkey displays.\n * Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter\n * instead of text labels.\n *\n * @example\n * ```ts\n * KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'\n * KEY_DISPLAY_SYMBOLS['Enter'] // '↵'\n * KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'\n * KEY_DISPLAY_SYMBOLS['Space'] // '␣'\n * ```\n */\nexport const KEY_DISPLAY_SYMBOLS = {\n  ArrowUp: '↑',\n  ArrowDown: '↓',\n  ArrowLeft: '←',\n  ArrowRight: '→',\n  Enter: '↵',\n  Escape: 'Esc',\n  Backspace: '⌫',\n  Delete: '⌦',\n  Tab: '⇥',\n  Space: '␣',\n} as const satisfies Record<string, string>\n"],"mappings":"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"}

package/dist/hotkey-recorder.cjs

@@ -14,7 +14,7 @@ let _tanstack_store = require("@tanstack/store");
 * State Management:
 * - Uses TanStack Store for reactive state management
 * - State can be accessed via `recorder.store.state` when using the class directly
-* - When using framework adapters (React), use `useStore` hooks for reactive state
+* - When using framework adapters (React), use `useSelector` hooks for reactive state
 *
 * @example
 * ```ts

package/dist/hotkey-recorder.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"hotkey-recorder.cjs","names":["Store","#options","#platform","detectPlatform","#keydownHandler","isInputElement","hotkeyChordFromKeydown","#removeListener","#addListener"],"sources":["../src/hotkey-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport { isInputElement } from './manager.utils'\nimport { hotkeyChordFromKeydown } from './recorder-chord'\nimport type { Hotkey } from './hotkey'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions {\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\n  /**\n   * Whether to ignore keyboard events from input-like elements (text inputs,\n   * textarea, select, contenteditable). When true, typing in inputs passes\n   * through normally instead of being captured as a hotkey recording.\n   * Escape always works regardless of this setting.\n   * @default true\n   */\n  ignoreInputs?: boolean\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useStore` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      // If ignoreInputs is enabled (default) and focus is in an input element,\n      // let the event pass through so the user can type normally.\n      // Escape is the exception — it should always cancel recording.\n      if (this.#options.ignoreInputs !== false) {\n        const activeEl =\n          typeof document !== 'undefined' ? document.activeElement : null\n        if (isInputElement(activeEl) && event.key !== 'Escape') {\n          return\n        }\n      }\n\n      event.preventDefault()\n      event.stopPropagation()\n\n      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.#options.onClear?.()\n          this.#options.onRecord('' as Hotkey)\n          this.stop()\n          return\n        }\n      }\n\n      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)\n      if (finalHotkey === null) {\n        return\n      }\n\n      // Remove listener FIRST to prevent any additional events\n      const handlerToRemove = this.#keydownHandler as\n        | ((event: KeyboardEvent) => void)\n        | null\n      if (handlerToRemove) {\n        this.#removeListener(handlerToRemove)\n        this.#keydownHandler = null\n      }\n\n      // Update store state immediately\n      this.store.setState(() => ({\n        isRecording: false,\n        recordedHotkey: finalHotkey,\n      }))\n\n      // Call callback AFTER listener is removed and state is set\n      this.#options.onRecord(finalHotkey)\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2EA,IAAa,iBAAb,MAA4B;CAU1B,kBAA2D;CAC3D;CACA;CAEA,YAAY,SAAgC;eATC,IAAIA,sBAA2B;GAC1E,aAAa;GACb,gBAAgB;GACjB,CAAC;AAOA,QAAKC,UAAW;AAChB,QAAKC,WAAYC,kCAAgB;;;;;;CAOnC,WAAW,SAA+C;AACxD,QAAKF,UAAW;GACd,GAAG,MAAKA;GACR,GAAG;GACJ;;;;;;;;;CAUH,QAAc;AAEZ,MAAI,MAAKG,eACP;AAIF,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;EAGH,MAAM,WAAW,UAAyB;AAExC,OAAI,CAAC,MAAKA,eACR;AAMF,OAAI,MAAKH,QAAS,iBAAiB,OAGjC;QAAII,qCADF,OAAO,aAAa,cAAc,SAAS,gBAAgB,KACjC,IAAI,MAAM,QAAQ,SAC5C;;AAIJ,SAAM,gBAAgB;AACtB,SAAM,iBAAiB;AAGvB,OAAI,MAAM,QAAQ,UAAU;AAC1B,SAAK,QAAQ;AACb;;AAIF,OAAI,MAAM,QAAQ,eAAe,MAAM,QAAQ,UAC7C;QACE,CAAC,MAAM,WACP,CAAC,MAAM,YACP,CAAC,MAAM,UACP,CAAC,MAAM,SACP;AACA,WAAKJ,QAAS,WAAW;AACzB,WAAKA,QAAS,SAAS,GAAa;AACpC,UAAK,MAAM;AACX;;;GAIJ,MAAM,cAAcK,8CAAuB,OAAO,MAAKJ,SAAU;AACjE,OAAI,gBAAgB,KAClB;GAIF,MAAM,kBAAkB,MAAKE;AAG7B,OAAI,iBAAiB;AACnB,UAAKG,eAAgB,gBAAgB;AACrC,UAAKH,iBAAkB;;AAIzB,QAAK,MAAM,gBAAgB;IACzB,aAAa;IACb,gBAAgB;IACjB,EAAE;AAGH,SAAKH,QAAS,SAAS,YAAY;;AAGrC,QAAKG,iBAAkB;AACvB,QAAKI,YAAa,QAAQ;;;;;;;CAQ5B,OAAa;AAEX,MAAI,MAAKJ,gBAAiB;AACxB,SAAKG,eAAgB,MAAKH,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;;;;;;;;CASL,SAAe;AAEb,MAAI,MAAKA,gBAAiB;AACxB,SAAKG,eAAgB,MAAKH,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;AAGH,QAAKH,QAAS,YAAY;;;;;CAM5B,aAAa,SAA+C;AAC1D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,iBAAiB,WAAW,SAAS,KAAK;;;;;CAMrD,gBAAgB,SAA+C;AAC7D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,oBAAoB,WAAW,SAAS,KAAK;;;;;;;;CASxD,UAAgB;AACd,OAAK,MAAM;AACX,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE"}
+{"version":3,"file":"hotkey-recorder.cjs","names":["Store","#options","#platform","detectPlatform","#keydownHandler","isInputElement","hotkeyChordFromKeydown","#removeListener","#addListener"],"sources":["../src/hotkey-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport { isInputElement } from './manager.utils'\nimport { hotkeyChordFromKeydown } from './recorder-chord'\nimport type { Hotkey } from './hotkey'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions {\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\n  /**\n   * Whether to ignore keyboard events from input-like elements (text inputs,\n   * textarea, select, contenteditable). When true, typing in inputs passes\n   * through normally instead of being captured as a hotkey recording.\n   * Escape always works regardless of this setting.\n   * @default true\n   */\n  ignoreInputs?: boolean\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useSelector` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      // If ignoreInputs is enabled (default) and focus is in an input element,\n      // let the event pass through so the user can type normally.\n      // Escape is the exception — it should always cancel recording.\n      if (this.#options.ignoreInputs !== false) {\n        const activeEl =\n          typeof document !== 'undefined' ? document.activeElement : null\n        if (isInputElement(activeEl) && event.key !== 'Escape') {\n          return\n        }\n      }\n\n      event.preventDefault()\n      event.stopPropagation()\n\n      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.#options.onClear?.()\n          this.#options.onRecord('' as Hotkey)\n          this.stop()\n          return\n        }\n      }\n\n      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)\n      if (finalHotkey === null) {\n        return\n      }\n\n      // Remove listener FIRST to prevent any additional events\n      const handlerToRemove = this.#keydownHandler as\n        | ((event: KeyboardEvent) => void)\n        | null\n      if (handlerToRemove) {\n        this.#removeListener(handlerToRemove)\n        this.#keydownHandler = null\n      }\n\n      // Update store state immediately\n      this.store.setState(() => ({\n        isRecording: false,\n        recordedHotkey: finalHotkey,\n      }))\n\n      // Call callback AFTER listener is removed and state is set\n      this.#options.onRecord(finalHotkey)\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2EA,IAAa,iBAAb,MAA4B;CAU1B,kBAA2D;CAC3D;CACA;CAEA,YAAY,SAAgC;eATC,IAAIA,sBAA2B;GAC1E,aAAa;GACb,gBAAgB;GACjB,CAAC;AAOA,QAAKC,UAAW;AAChB,QAAKC,WAAYC,kCAAgB;;;;;;CAOnC,WAAW,SAA+C;AACxD,QAAKF,UAAW;GACd,GAAG,MAAKA;GACR,GAAG;GACJ;;;;;;;;;CAUH,QAAc;AAEZ,MAAI,MAAKG,eACP;AAIF,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;EAGH,MAAM,WAAW,UAAyB;AAExC,OAAI,CAAC,MAAKA,eACR;AAMF,OAAI,MAAKH,QAAS,iBAAiB,OAGjC;QAAII,qCADF,OAAO,aAAa,cAAc,SAAS,gBAAgB,KACjC,IAAI,MAAM,QAAQ,SAC5C;;AAIJ,SAAM,gBAAgB;AACtB,SAAM,iBAAiB;AAGvB,OAAI,MAAM,QAAQ,UAAU;AAC1B,SAAK,QAAQ;AACb;;AAIF,OAAI,MAAM,QAAQ,eAAe,MAAM,QAAQ,UAC7C;QACE,CAAC,MAAM,WACP,CAAC,MAAM,YACP,CAAC,MAAM,UACP,CAAC,MAAM,SACP;AACA,WAAKJ,QAAS,WAAW;AACzB,WAAKA,QAAS,SAAS,GAAa;AACpC,UAAK,MAAM;AACX;;;GAIJ,MAAM,cAAcK,8CAAuB,OAAO,MAAKJ,SAAU;AACjE,OAAI,gBAAgB,KAClB;GAIF,MAAM,kBAAkB,MAAKE;AAG7B,OAAI,iBAAiB;AACnB,UAAKG,eAAgB,gBAAgB;AACrC,UAAKH,iBAAkB;;AAIzB,QAAK,MAAM,gBAAgB;IACzB,aAAa;IACb,gBAAgB;IACjB,EAAE;AAGH,SAAKH,QAAS,SAAS,YAAY;;AAGrC,QAAKG,iBAAkB;AACvB,QAAKI,YAAa,QAAQ;;;;;;;CAQ5B,OAAa;AAEX,MAAI,MAAKJ,gBAAiB;AACxB,SAAKG,eAAgB,MAAKH,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;;;;;;;;CASL,SAAe;AAEb,MAAI,MAAKA,gBAAiB;AACxB,SAAKG,eAAgB,MAAKH,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;AAGH,QAAKH,QAAS,YAAY;;;;;CAM5B,aAAa,SAA+C;AAC1D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,iBAAiB,WAAW,SAAS,KAAK;;;;;CAMrD,gBAAgB,SAA+C;AAC7D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,oBAAoB,WAAW,SAAS,KAAK;;;;;;;;CASxD,UAAgB;AACd,OAAK,MAAM;AACX,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE"}

package/dist/hotkey-recorder.d.cts

@@ -40,7 +40,7 @@ interface HotkeyRecorderOptions {
  * State Management:
  * - Uses TanStack Store for reactive state management
  * - State can be accessed via `recorder.store.state` when using the class directly
- * - When using framework adapters (React), use `useStore` hooks for reactive state
+ * - When using framework adapters (React), use `useSelector` hooks for reactive state
  *
  * @example
  * ```ts

package/dist/hotkey-recorder.d.ts

@@ -40,7 +40,7 @@ interface HotkeyRecorderOptions {
  * State Management:
  * - Uses TanStack Store for reactive state management
  * - State can be accessed via `recorder.store.state` when using the class directly
- * - When using framework adapters (React), use `useStore` hooks for reactive state
+ * - When using framework adapters (React), use `useSelector` hooks for reactive state
  *
  * @example
  * ```ts

package/dist/hotkey-recorder.js

@@ -14,7 +14,7 @@ import { Store } from "@tanstack/store";
 * State Management:
 * - Uses TanStack Store for reactive state management
 * - State can be accessed via `recorder.store.state` when using the class directly
-* - When using framework adapters (React), use `useStore` hooks for reactive state
+* - When using framework adapters (React), use `useSelector` hooks for reactive state
 *
 * @example
 * ```ts

package/dist/hotkey-recorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"hotkey-recorder.js","names":["#options","#platform","#keydownHandler","#removeListener","#addListener"],"sources":["../src/hotkey-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport { isInputElement } from './manager.utils'\nimport { hotkeyChordFromKeydown } from './recorder-chord'\nimport type { Hotkey } from './hotkey'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions {\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\n  /**\n   * Whether to ignore keyboard events from input-like elements (text inputs,\n   * textarea, select, contenteditable). When true, typing in inputs passes\n   * through normally instead of being captured as a hotkey recording.\n   * Escape always works regardless of this setting.\n   * @default true\n   */\n  ignoreInputs?: boolean\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useStore` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      // If ignoreInputs is enabled (default) and focus is in an input element,\n      // let the event pass through so the user can type normally.\n      // Escape is the exception — it should always cancel recording.\n      if (this.#options.ignoreInputs !== false) {\n        const activeEl =\n          typeof document !== 'undefined' ? document.activeElement : null\n        if (isInputElement(activeEl) && event.key !== 'Escape') {\n          return\n        }\n      }\n\n      event.preventDefault()\n      event.stopPropagation()\n\n      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.#options.onClear?.()\n          this.#options.onRecord('' as Hotkey)\n          this.stop()\n          return\n        }\n      }\n\n      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)\n      if (finalHotkey === null) {\n        return\n      }\n\n      // Remove listener FIRST to prevent any additional events\n      const handlerToRemove = this.#keydownHandler as\n        | ((event: KeyboardEvent) => void)\n        | null\n      if (handlerToRemove) {\n        this.#removeListener(handlerToRemove)\n        this.#keydownHandler = null\n      }\n\n      // Update store state immediately\n      this.store.setState(() => ({\n        isRecording: false,\n        recordedHotkey: finalHotkey,\n      }))\n\n      // Call callback AFTER listener is removed and state is set\n      this.#options.onRecord(finalHotkey)\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2EA,IAAa,iBAAb,MAA4B;CAU1B,kBAA2D;CAC3D;CACA;CAEA,YAAY,SAAgC;eATC,IAAI,MAA2B;GAC1E,aAAa;GACb,gBAAgB;GACjB,CAAC;AAOA,QAAKA,UAAW;AAChB,QAAKC,WAAY,gBAAgB;;;;;;CAOnC,WAAW,SAA+C;AACxD,QAAKD,UAAW;GACd,GAAG,MAAKA;GACR,GAAG;GACJ;;;;;;;;;CAUH,QAAc;AAEZ,MAAI,MAAKE,eACP;AAIF,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;EAGH,MAAM,WAAW,UAAyB;AAExC,OAAI,CAAC,MAAKA,eACR;AAMF,OAAI,MAAKF,QAAS,iBAAiB,OAGjC;QAAI,eADF,OAAO,aAAa,cAAc,SAAS,gBAAgB,KACjC,IAAI,MAAM,QAAQ,SAC5C;;AAIJ,SAAM,gBAAgB;AACtB,SAAM,iBAAiB;AAGvB,OAAI,MAAM,QAAQ,UAAU;AAC1B,SAAK,QAAQ;AACb;;AAIF,OAAI,MAAM,QAAQ,eAAe,MAAM,QAAQ,UAC7C;QACE,CAAC,MAAM,WACP,CAAC,MAAM,YACP,CAAC,MAAM,UACP,CAAC,MAAM,SACP;AACA,WAAKA,QAAS,WAAW;AACzB,WAAKA,QAAS,SAAS,GAAa;AACpC,UAAK,MAAM;AACX;;;GAIJ,MAAM,cAAc,uBAAuB,OAAO,MAAKC,SAAU;AACjE,OAAI,gBAAgB,KAClB;GAIF,MAAM,kBAAkB,MAAKC;AAG7B,OAAI,iBAAiB;AACnB,UAAKC,eAAgB,gBAAgB;AACrC,UAAKD,iBAAkB;;AAIzB,QAAK,MAAM,gBAAgB;IACzB,aAAa;IACb,gBAAgB;IACjB,EAAE;AAGH,SAAKF,QAAS,SAAS,YAAY;;AAGrC,QAAKE,iBAAkB;AACvB,QAAKE,YAAa,QAAQ;;;;;;;CAQ5B,OAAa;AAEX,MAAI,MAAKF,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;;;;;;;;CASL,SAAe;AAEb,MAAI,MAAKA,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;AAGH,QAAKF,QAAS,YAAY;;;;;CAM5B,aAAa,SAA+C;AAC1D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,iBAAiB,WAAW,SAAS,KAAK;;;;;CAMrD,gBAAgB,SAA+C;AAC7D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,oBAAoB,WAAW,SAAS,KAAK;;;;;;;;CASxD,UAAgB;AACd,OAAK,MAAM;AACX,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE"}
+{"version":3,"file":"hotkey-recorder.js","names":["#options","#platform","#keydownHandler","#removeListener","#addListener"],"sources":["../src/hotkey-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport { isInputElement } from './manager.utils'\nimport { hotkeyChordFromKeydown } from './recorder-chord'\nimport type { Hotkey } from './hotkey'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions {\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\n  /**\n   * Whether to ignore keyboard events from input-like elements (text inputs,\n   * textarea, select, contenteditable). When true, typing in inputs passes\n   * through normally instead of being captured as a hotkey recording.\n   * Escape always works regardless of this setting.\n   * @default true\n   */\n  ignoreInputs?: boolean\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useSelector` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      // If ignoreInputs is enabled (default) and focus is in an input element,\n      // let the event pass through so the user can type normally.\n      // Escape is the exception — it should always cancel recording.\n      if (this.#options.ignoreInputs !== false) {\n        const activeEl =\n          typeof document !== 'undefined' ? document.activeElement : null\n        if (isInputElement(activeEl) && event.key !== 'Escape') {\n          return\n        }\n      }\n\n      event.preventDefault()\n      event.stopPropagation()\n\n      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.#options.onClear?.()\n          this.#options.onRecord('' as Hotkey)\n          this.stop()\n          return\n        }\n      }\n\n      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)\n      if (finalHotkey === null) {\n        return\n      }\n\n      // Remove listener FIRST to prevent any additional events\n      const handlerToRemove = this.#keydownHandler as\n        | ((event: KeyboardEvent) => void)\n        | null\n      if (handlerToRemove) {\n        this.#removeListener(handlerToRemove)\n        this.#keydownHandler = null\n      }\n\n      // Update store state immediately\n      this.store.setState(() => ({\n        isRecording: false,\n        recordedHotkey: finalHotkey,\n      }))\n\n      // Call callback AFTER listener is removed and state is set\n      this.#options.onRecord(finalHotkey)\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2EA,IAAa,iBAAb,MAA4B;CAU1B,kBAA2D;CAC3D;CACA;CAEA,YAAY,SAAgC;eATC,IAAI,MAA2B;GAC1E,aAAa;GACb,gBAAgB;GACjB,CAAC;AAOA,QAAKA,UAAW;AAChB,QAAKC,WAAY,gBAAgB;;;;;;CAOnC,WAAW,SAA+C;AACxD,QAAKD,UAAW;GACd,GAAG,MAAKA;GACR,GAAG;GACJ;;;;;;;;;CAUH,QAAc;AAEZ,MAAI,MAAKE,eACP;AAIF,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;EAGH,MAAM,WAAW,UAAyB;AAExC,OAAI,CAAC,MAAKA,eACR;AAMF,OAAI,MAAKF,QAAS,iBAAiB,OAGjC;QAAI,eADF,OAAO,aAAa,cAAc,SAAS,gBAAgB,KACjC,IAAI,MAAM,QAAQ,SAC5C;;AAIJ,SAAM,gBAAgB;AACtB,SAAM,iBAAiB;AAGvB,OAAI,MAAM,QAAQ,UAAU;AAC1B,SAAK,QAAQ;AACb;;AAIF,OAAI,MAAM,QAAQ,eAAe,MAAM,QAAQ,UAC7C;QACE,CAAC,MAAM,WACP,CAAC,MAAM,YACP,CAAC,MAAM,UACP,CAAC,MAAM,SACP;AACA,WAAKA,QAAS,WAAW;AACzB,WAAKA,QAAS,SAAS,GAAa;AACpC,UAAK,MAAM;AACX;;;GAIJ,MAAM,cAAc,uBAAuB,OAAO,MAAKC,SAAU;AACjE,OAAI,gBAAgB,KAClB;GAIF,MAAM,kBAAkB,MAAKC;AAG7B,OAAI,iBAAiB;AACnB,UAAKC,eAAgB,gBAAgB;AACrC,UAAKD,iBAAkB;;AAIzB,QAAK,MAAM,gBAAgB;IACzB,aAAa;IACb,gBAAgB;IACjB,EAAE;AAGH,SAAKF,QAAS,SAAS,YAAY;;AAGrC,QAAKE,iBAAkB;AACvB,QAAKE,YAAa,QAAQ;;;;;;;CAQ5B,OAAa;AAEX,MAAI,MAAKF,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;;;;;;;;CASL,SAAe;AAEb,MAAI,MAAKA,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;AAGH,QAAKF,QAAS,YAAY;;;;;CAM5B,aAAa,SAA+C;AAC1D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,iBAAiB,WAAW,SAAS,KAAK;;;;;CAMrD,gBAAgB,SAA+C;AAC7D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,oBAAoB,WAAW,SAAS,KAAK;;;;;;;;CASxD,UAAgB;AACd,OAAK,MAAM;AACX,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/store": "^0.9.3"
+    "@tanstack/store": "^0.11.0"
   },
   "scripts": {
     "clean": "premove ./build ./dist",

package/src/constants.ts

@@ -455,6 +455,9 @@ export function isSingleLetterKey(key: string): boolean {
  * ```
  */
 export function normalizeKeyName(key: string): string {
+  // key can be undefined in rare cases
+  // (browser extensions synthesizing key events, accessibility tools, certain OS/browser combinations).
+  if (!key) return ''
   // Check aliases first
   if (key in KEY_ALIASES) {
     return KEY_ALIASES[key]!

package/src/hotkey-recorder.ts

@@ -44,7 +44,7 @@ export interface HotkeyRecorderOptions {
  * State Management:
  * - Uses TanStack Store for reactive state management
  * - State can be accessed via `recorder.store.state` when using the class directly
- * - When using framework adapters (React), use `useStore` hooks for reactive state
+ * - When using framework adapters (React), use `useSelector` hooks for reactive state
  *
  * @example
  * ```ts