@tanstack/hotkeys 0.6.4 → 0.7.1

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-manager.cjs

@@ -6,6 +6,21 @@ const require_manager_utils = require('./manager.utils.cjs');
 let _tanstack_store = require("@tanstack/store");
 
 //#region src/hotkey-manager.ts
+/**
+* Creates a public view from an internal registration,
+* stripping the callback function.
+*/
+function toHotkeyRegistrationView(reg) {
+	return {
+		hotkey: reg.hotkey,
+		id: reg.id,
+		options: reg.options,
+		parsedHotkey: reg.parsedHotkey,
+		target: reg.target,
+		triggerCount: reg.triggerCount,
+		hasFired: reg.hasFired
+	};
+}
 let registrationIdCounter = 0;
 /**
 * Generates a unique ID for hotkey registrations.
@@ -364,4 +379,5 @@ function getHotkeyManager() {
 //#endregion
 exports.HotkeyManager = HotkeyManager;
 exports.getHotkeyManager = getHotkeyManager;
+exports.toHotkeyRegistrationView = toHotkeyRegistrationView;
 //# sourceMappingURL=hotkey-manager.cjs.map

package/dist/hotkey-manager.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"hotkey-manager.cjs","names":["#instance","Store","#platform","detectPlatform","parseHotkey","rawHotkeyToParsedHotkey","formatHotkey","#findConflictingRegistration","#unregister","getDefaultIgnoreInputs","defaultHotkeyOptions","#targetRegistrations","#ensureListenersForTarget","#removeListenersForTarget","#targetListeners","#createTargetKeyDownHandler","#createTargetKeyUpHandler","isEventForTarget","shouldIgnoreInputEvent","matchesKeyboardEvent","#executeHotkeyCallback","#shouldResetRegistration","#processTargetEvent","normalizeKeyName"],"sources":["../src/hotkey-manager.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform, normalizeKeyName } from './constants'\nimport { formatHotkey } from './format'\nimport { parseHotkey, rawHotkeyToParsedHotkey } from './parse'\nimport { matchesKeyboardEvent } from './match'\nimport {\n  defaultHotkeyOptions,\n  getDefaultIgnoreInputs,\n  handleConflict,\n  isEventForTarget,\n  shouldIgnoreInputEvent,\n} from './manager.utils'\nimport type { ConflictBehavior } from './manager.utils'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n  RegisterableHotkey,\n} from './hotkey'\n\nexport type { ConflictBehavior }\n\n/**\n * Options for registering a hotkey.\n */\nexport interface HotkeyOptions {\n  /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */\n  conflictBehavior?: ConflictBehavior\n  /**\n   * Soft-disable: when `false`, the callback does not run but the registration\n   * stays in `HotkeyManager` (and in devtools). Toggling this should update the\n   * existing handle via `setOptions` rather than unregistering. Defaults to `true`.\n   */\n  enabled?: boolean\n  /** The event type to listen for. Defaults to 'keydown' */\n  eventType?: 'keydown' | 'keyup'\n  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on hotkey: true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */\n  ignoreInputs?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** If true, only trigger once until all keys are released. Default: false */\n  requireReset?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The DOM element to attach the event listener to. Defaults to document. */\n  target?: HTMLElement | Document | Window | null\n}\n\n/**\n * A registered hotkey handler in the HotkeyManager.\n */\nexport interface HotkeyRegistration {\n  /** The callback to invoke */\n  callback: HotkeyCallback\n  /** Whether this registration has fired and needs reset (for requireReset) */\n  hasFired: boolean\n  /** The original hotkey string */\n  hotkey: Hotkey\n  /** Unique identifier for this registration */\n  id: string\n  /** Options for this registration */\n  options: HotkeyOptions\n  /** The parsed hotkey */\n  parsedHotkey: ParsedHotkey\n  /** The resolved target element for this registration */\n  target: HTMLElement | Document | Window\n  /** How many times this registration's callback has been triggered */\n  triggerCount: number\n}\n\n/**\n * A handle returned from HotkeyManager.register() that allows updating\n * the callback and options without re-registering the hotkey.\n *\n * @example\n * ```ts\n * const handle = manager.register('Mod+S', callback, options)\n *\n * // Update callback without re-registering (avoids stale closures)\n * handle.callback = newCallback\n *\n * // Update options without re-registering\n * handle.setOptions({ enabled: false })\n *\n * // Check if still active\n * if (handle.isActive) {\n *   // ...\n * }\n *\n * // Unregister when done\n * handle.unregister()\n * ```\n */\nexport interface HotkeyRegistrationHandle {\n  /**\n   * The callback function. Can be set directly to update without re-registering.\n   * This avoids stale closures when the callback references React state.\n   */\n  callback: HotkeyCallback\n  /** Unique identifier for this registration */\n  readonly id: string\n  /** Check if this registration is still active (not unregistered) */\n  readonly isActive: boolean\n  /**\n   * Update options (merged with existing options).\n   * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.\n   */\n  setOptions: (options: Partial<HotkeyOptions>) => void\n  /** Unregister this hotkey */\n  unregister: () => void\n}\n\nlet registrationIdCounter = 0\n\n/**\n * Generates a unique ID for hotkey registrations.\n */\nfunction generateId(): string {\n  return `hotkey_${++registrationIdCounter}`\n}\n\n/**\n * Singleton manager for hotkey registrations.\n *\n * This class provides a centralized way to register and manage keyboard hotkeys.\n * It uses a single event listener for efficiency, regardless of how many hotkeys\n * are registered.\n *\n * @example\n * ```ts\n * const manager = HotkeyManager.getInstance()\n *\n * const unregister = manager.register('Mod+S', (event, context) => {\n *   console.log('Save triggered!')\n * })\n *\n * // Later, to unregister:\n * unregister()\n * ```\n */\nexport class HotkeyManager {\n  static #instance: HotkeyManager | null = null\n\n  /**\n   * The TanStack Store containing all hotkey registrations.\n   * Use this to subscribe to registration changes or access current registrations.\n   *\n   * @example\n   * ```ts\n   * const manager = HotkeyManager.getInstance()\n   *\n   * // Subscribe to registration changes\n   * const unsubscribe = manager.registrations.subscribe(() => {\n   *   console.log('Registrations changed:', manager.registrations.state.size)\n   * })\n   *\n   * // Access current registrations\n   * for (const [id, reg] of manager.registrations.state) {\n   *   console.log(reg.hotkey, reg.options.enabled)\n   * }\n   * ```\n   */\n  readonly registrations: Store<Map<string, HotkeyRegistration>> = new Store(\n    new Map(),\n  )\n  #platform: 'mac' | 'windows' | 'linux'\n  #targetListeners: Map<\n    HTMLElement | Document | Window,\n    {\n      keydown: (event: KeyboardEvent) => void\n      keyup: (event: KeyboardEvent) => void\n    }\n  > = new Map()\n  #targetRegistrations: Map<HTMLElement | Document | Window, Set<string>> =\n    new Map()\n\n  private constructor() {\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Gets the singleton instance of HotkeyManager.\n   */\n  static getInstance(): HotkeyManager {\n    if (!HotkeyManager.#instance) {\n      HotkeyManager.#instance = new HotkeyManager()\n    }\n    return HotkeyManager.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (HotkeyManager.#instance) {\n      HotkeyManager.#instance.destroy()\n      HotkeyManager.#instance = null\n    }\n  }\n\n  /**\n   * Registers a hotkey handler and returns a handle for updating the registration.\n   *\n   * The returned handle allows updating the callback and options without\n   * re-registering, which is useful for avoiding stale closures in React.\n   *\n   * @param hotkey - The hotkey string (e.g., 'Mod+S') or RawHotkey object\n   * @param callback - The function to call when the hotkey is pressed\n   * @param options - Options for the hotkey behavior\n   * @returns A handle for managing the registration\n   *\n   * @example\n   * ```ts\n   * const handle = manager.register('Mod+S', callback)\n   *\n   * // Update callback without re-registering (avoids stale closures)\n   * handle.callback = newCallback\n   *\n   * // Update options\n   * handle.setOptions({ enabled: false })\n   *\n   * // Unregister when done\n   * handle.unregister()\n   * ```\n   */\n  register(\n    hotkey: RegisterableHotkey,\n    callback: HotkeyCallback,\n    options: HotkeyOptions = {},\n  ): HotkeyRegistrationHandle {\n    // In SSR environments, return a no-op handle since there's no DOM to attach listeners to\n    if (typeof document === 'undefined' && !options.target) {\n      let currentCallback = callback\n      return {\n        id: generateId(),\n        unregister: () => {},\n        get callback() {\n          return currentCallback\n        },\n        set callback(newCallback: HotkeyCallback) {\n          currentCallback = newCallback\n        },\n        setOptions: () => {},\n        get isActive() {\n          return false\n        },\n      }\n    }\n\n    const id = generateId()\n    const platform = options.platform ?? this.#platform\n    const parsedHotkey =\n      typeof hotkey === 'string'\n        ? parseHotkey(hotkey, platform)\n        : rawHotkeyToParsedHotkey(hotkey, platform)\n    const hotkeyStr = (\n      typeof hotkey === 'string' ? hotkey : formatHotkey(parsedHotkey)\n    ) as Hotkey\n\n    // Resolve target: default to document if not provided\n    // Note: SSR case without explicit target is handled above\n    const target = options.target ?? document\n\n    // Resolve conflict behavior\n    const conflictBehavior = options.conflictBehavior ?? 'warn'\n\n    // Check for existing registrations with the same hotkey and target\n    const conflictingRegistration = this.#findConflictingRegistration(\n      hotkeyStr,\n      target,\n    )\n\n    if (conflictingRegistration) {\n      handleConflict(\n        conflictingRegistration.id,\n        hotkeyStr,\n        conflictBehavior,\n        (id) => this.#unregister(id),\n      )\n    }\n\n    const resolvedIgnoreInputs =\n      options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey)\n\n    const baseOptions = {\n      ...defaultHotkeyOptions,\n      requireReset: false,\n      ...options,\n      platform,\n    }\n\n    const registration: HotkeyRegistration = {\n      id,\n      hotkey: hotkeyStr,\n      parsedHotkey,\n      callback,\n      options: { ...baseOptions, ignoreInputs: resolvedIgnoreInputs },\n      hasFired: false,\n      triggerCount: 0,\n      target,\n    }\n\n    this.registrations.setState((prev) => new Map(prev).set(id, registration))\n\n    // Track registration for this target\n    if (!this.#targetRegistrations.has(target)) {\n      this.#targetRegistrations.set(target, new Set())\n    }\n    this.#targetRegistrations.get(target)!.add(id)\n\n    // Ensure listeners are attached for this target\n    this.#ensureListenersForTarget(target)\n\n    // Create and return the handle\n    const manager = this\n    const handle: HotkeyRegistrationHandle = {\n      get id() {\n        return id\n      },\n      unregister: () => {\n        manager.#unregister(id)\n      },\n      get callback() {\n        const reg = manager.registrations.state.get(id)\n        return reg?.callback ?? callback\n      },\n      set callback(newCallback: HotkeyCallback) {\n        const reg = manager.registrations.state.get(id)\n        if (reg) {\n          reg.callback = newCallback\n        }\n      },\n      setOptions: (newOptions: Partial<HotkeyOptions>) => {\n        manager.registrations.setState((prev) => {\n          const reg = prev.get(id)\n          if (reg) {\n            const next = new Map(prev)\n            next.set(id, { ...reg, options: { ...reg.options, ...newOptions } })\n            return next\n          }\n          return prev\n        })\n      },\n      get isActive() {\n        return manager.registrations.state.has(id)\n      },\n    }\n\n    return handle\n  }\n\n  /**\n   * Unregisters a hotkey by its registration ID.\n   */\n  #unregister(id: string): void {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return\n    }\n\n    const target = registration.target\n\n    // Remove registration\n    this.registrations.setState((prev) => {\n      const next = new Map(prev)\n      next.delete(id)\n      return next\n    })\n\n    // Remove from target registrations tracking\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (targetRegs) {\n      targetRegs.delete(id)\n      // If no more registrations for this target, remove listeners\n      if (targetRegs.size === 0) {\n        this.#removeListenersForTarget(target)\n      }\n    }\n  }\n\n  /**\n   * Ensures event listeners are attached for a specific target.\n   */\n  #ensureListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    // Skip if listeners already exist for this target\n    if (this.#targetListeners.has(target)) {\n      return\n    }\n\n    const keydownHandler = this.#createTargetKeyDownHandler(target)\n    const keyupHandler = this.#createTargetKeyUpHandler(target)\n\n    target.addEventListener('keydown', keydownHandler as EventListener)\n    target.addEventListener('keyup', keyupHandler as EventListener)\n\n    this.#targetListeners.set(target, {\n      keydown: keydownHandler,\n      keyup: keyupHandler,\n    })\n  }\n\n  /**\n   * Removes event listeners for a specific target.\n   */\n  #removeListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    const listeners = this.#targetListeners.get(target)\n    if (!listeners) {\n      return\n    }\n\n    target.removeEventListener('keydown', listeners.keydown as EventListener)\n    target.removeEventListener('keyup', listeners.keyup as EventListener)\n\n    this.#targetListeners.delete(target)\n    this.#targetRegistrations.delete(target)\n  }\n\n  /**\n   * Processes keyboard events for a specific target and event type.\n   */\n  #processTargetEvent(\n    event: KeyboardEvent,\n    target: HTMLElement | Document | Window,\n    eventType: 'keydown' | 'keyup',\n  ): void {\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (!targetRegs) {\n      return\n    }\n\n    for (const id of targetRegs) {\n      const registration = this.registrations.state.get(id)\n      if (!registration) {\n        continue\n      }\n\n      // Check if event originated from or bubbled to this target\n      if (!isEventForTarget(event, target)) {\n        continue\n      }\n\n      if (!registration.options.enabled) {\n        continue\n      }\n\n      // Check if we should ignore input elements (defaults to true)\n      if (registration.options.ignoreInputs !== false) {\n        if (shouldIgnoreInputEvent(event, target, registration.target)) {\n          continue\n        }\n      }\n\n      // Handle keydown events\n      if (eventType === 'keydown') {\n        if (registration.options.eventType !== 'keydown') {\n          continue\n        }\n\n        // Check if the hotkey matches first\n        const matches = matchesKeyboardEvent(\n          event,\n          registration.parsedHotkey,\n          registration.options.platform,\n        )\n\n        if (matches) {\n          // Always apply preventDefault/stopPropagation if the hotkey matches,\n          // even when requireReset is active and has already fired\n          if (registration.options.preventDefault) {\n            event.preventDefault()\n          }\n          if (registration.options.stopPropagation) {\n            event.stopPropagation()\n          }\n\n          // Only execute callback if requireReset is not active or hasn't fired yet\n          if (!registration.options.requireReset || !registration.hasFired) {\n            this.#executeHotkeyCallback(registration, event)\n\n            // Mark as fired if requireReset is enabled\n            if (registration.options.requireReset) {\n              registration.hasFired = true\n            }\n          }\n        }\n      }\n      // Handle keyup events\n      else {\n        if (registration.options.eventType === 'keyup') {\n          if (\n            matchesKeyboardEvent(\n              event,\n              registration.parsedHotkey,\n              registration.options.platform,\n            )\n          ) {\n            this.#executeHotkeyCallback(registration, event)\n          }\n        }\n\n        // Reset hasFired when any key in the hotkey is released\n        if (registration.options.requireReset && registration.hasFired) {\n          if (this.#shouldResetRegistration(registration, event)) {\n            registration.hasFired = false\n          }\n        }\n      }\n    }\n  }\n\n  /**\n   * Executes a hotkey callback with proper event handling.\n   */\n  #executeHotkeyCallback(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): void {\n    if (registration.options.preventDefault) {\n      event.preventDefault()\n    }\n    if (registration.options.stopPropagation) {\n      event.stopPropagation()\n    }\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count.\n    // We create a new Map but keep the same registration reference to preserve\n    // identity for mutation-based fields like hasFired.\n    this.registrations.setState((prev) => new Map(prev))\n\n    const context: HotkeyCallbackContext = {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    }\n\n    registration.callback(event, context)\n  }\n\n  /**\n   * Creates a keydown handler for a specific target.\n   */\n  #createTargetKeyDownHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keydown')\n    }\n  }\n\n  /**\n   * Creates a keyup handler for a specific target.\n   */\n  #createTargetKeyUpHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keyup')\n    }\n  }\n\n  /**\n   * Finds an existing registration with the same hotkey and target.\n   */\n  #findConflictingRegistration(\n    hotkey: Hotkey,\n    target: HTMLElement | Document | Window,\n  ): HotkeyRegistration | null {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey && registration.target === target) {\n        return registration\n      }\n    }\n    return null\n  }\n\n  /**\n   * Determines if a registration should be reset based on the keyup event.\n   */\n  #shouldResetRegistration(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): boolean {\n    const parsed = registration.parsedHotkey\n    const releasedKey = normalizeKeyName(event.key)\n\n    // Reset if the main key is released\n    // Compare case-insensitively for single-letter keys\n    const parsedKeyNormalized =\n      parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key\n    const releasedKeyNormalized =\n      releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey\n\n    if (releasedKeyNormalized === parsedKeyNormalized) {\n      return true\n    }\n\n    // Reset if any required modifier is released\n    // Use normalized key names and check against canonical modifier names\n    if (parsed.ctrl && releasedKey === 'Control') {\n      return true\n    }\n    if (parsed.shift && releasedKey === 'Shift') {\n      return true\n    }\n    if (parsed.alt && releasedKey === 'Alt') {\n      return true\n    }\n    if (parsed.meta && releasedKey === 'Meta') {\n      return true\n    }\n\n    return false\n  }\n\n  /**\n   * Triggers a registration's callback programmatically from devtools.\n   * Creates a synthetic KeyboardEvent and invokes the callback.\n   *\n   * @param id - The registration ID to trigger\n   * @returns True if the registration was found and triggered\n   */\n  triggerRegistration(id: string): boolean {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return false\n    }\n\n    const parsed = registration.parsedHotkey\n    const syntheticEvent = new KeyboardEvent(\n      registration.options.eventType ?? 'keydown',\n      {\n        key: parsed.key,\n        ctrlKey: parsed.ctrl,\n        shiftKey: parsed.shift,\n        altKey: parsed.alt,\n        metaKey: parsed.meta,\n        bubbles: true,\n        cancelable: true,\n      },\n    )\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count\n    this.registrations.setState((prev) => new Map(prev))\n\n    registration.callback(syntheticEvent, {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    })\n\n    return true\n  }\n\n  /**\n   * Gets the number of registered hotkeys.\n   */\n  getRegistrationCount(): number {\n    return this.registrations.state.size\n  }\n\n  /**\n   * Checks if a specific hotkey is registered.\n   *\n   * @param hotkey - The hotkey string to check\n   * @param target - Optional target element to match (if provided, both hotkey and target must match)\n   * @returns True if a matching registration exists\n   */\n  isRegistered(\n    hotkey: Hotkey,\n    target?: HTMLElement | Document | Window,\n  ): boolean {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey) {\n        // If target is specified, both must match\n        if (target === undefined || registration.target === target) {\n          return true\n        }\n      }\n    }\n    return false\n  }\n\n  /**\n   * Destroys the manager and removes all listeners.\n   */\n  destroy(): void {\n    // Remove all target listeners\n    for (const target of this.#targetListeners.keys()) {\n      this.#removeListenersForTarget(target)\n    }\n\n    this.registrations.setState(() => new Map())\n    this.#targetListeners.clear()\n    this.#targetRegistrations.clear()\n  }\n}\n\n/**\n * Gets the singleton HotkeyManager instance.\n * Convenience function for accessing the manager.\n */\nexport function getHotkeyManager(): HotkeyManager {\n  return HotkeyManager.getInstance()\n}\n"],"mappings":"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"}
+{"version":3,"file":"hotkey-manager.cjs","names":["#instance","Store","#platform","detectPlatform","parseHotkey","rawHotkeyToParsedHotkey","formatHotkey","#findConflictingRegistration","#unregister","getDefaultIgnoreInputs","defaultHotkeyOptions","#targetRegistrations","#ensureListenersForTarget","#removeListenersForTarget","#targetListeners","#createTargetKeyDownHandler","#createTargetKeyUpHandler","isEventForTarget","shouldIgnoreInputEvent","matchesKeyboardEvent","#executeHotkeyCallback","#shouldResetRegistration","#processTargetEvent","normalizeKeyName"],"sources":["../src/hotkey-manager.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform, normalizeKeyName } from './constants'\nimport { formatHotkey } from './format'\nimport { parseHotkey, rawHotkeyToParsedHotkey } from './parse'\nimport { matchesKeyboardEvent } from './match'\nimport {\n  defaultHotkeyOptions,\n  getDefaultIgnoreInputs,\n  handleConflict,\n  isEventForTarget,\n  shouldIgnoreInputEvent,\n} from './manager.utils'\nimport type { ConflictBehavior } from './manager.utils'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeyMeta,\n  ParsedHotkey,\n  RegisterableHotkey,\n} from './hotkey'\n\nexport type { ConflictBehavior }\n\n/**\n * Options for registering a hotkey.\n */\nexport interface HotkeyOptions {\n  /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */\n  conflictBehavior?: ConflictBehavior\n  /**\n   * Soft-disable: when `false`, the callback does not run but the registration\n   * stays in `HotkeyManager` (and in devtools). Toggling this should update the\n   * existing handle via `setOptions` rather than unregistering. Defaults to `true`.\n   */\n  enabled?: boolean\n  /** The event type to listen for. Defaults to 'keydown' */\n  eventType?: 'keydown' | 'keyup'\n  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on hotkey: true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */\n  ignoreInputs?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** If true, only trigger once until all keys are released. Default: false */\n  requireReset?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The DOM element to attach the event listener to. Defaults to document. */\n  target?: HTMLElement | Document | Window | null\n  /** Optional metadata (name, description, custom fields via declaration merging) */\n  meta?: HotkeyMeta\n}\n\n/**\n * A registered hotkey handler in the HotkeyManager.\n */\nexport interface HotkeyRegistration {\n  /** The callback to invoke */\n  callback: HotkeyCallback\n  /** Whether this registration has fired and needs reset (for requireReset) */\n  hasFired: boolean\n  /** The original hotkey string */\n  hotkey: Hotkey\n  /** Unique identifier for this registration */\n  id: string\n  /** Options for this registration */\n  options: HotkeyOptions\n  /** The parsed hotkey */\n  parsedHotkey: ParsedHotkey\n  /** The resolved target element for this registration */\n  target: HTMLElement | Document | Window\n  /** How many times this registration's callback has been triggered */\n  triggerCount: number\n}\n\n/**\n * Public view of a hotkey registration for display and introspection.\n * Omits the callback function which is an internal implementation detail.\n */\nexport interface HotkeyRegistrationView {\n  /** The original hotkey string */\n  hotkey: Hotkey\n  /** Unique identifier for this registration */\n  id: string\n  /** Options for this registration */\n  options: HotkeyOptions\n  /** The parsed hotkey */\n  parsedHotkey: ParsedHotkey\n  /** The resolved target element for this registration */\n  target: HTMLElement | Document | Window\n  /** How many times this registration's callback has been triggered */\n  triggerCount: number\n  /** Whether this registration has fired and needs reset (for requireReset) */\n  hasFired: boolean\n}\n\n/**\n * Creates a public view from an internal registration,\n * stripping the callback function.\n */\nexport function toHotkeyRegistrationView(\n  reg: HotkeyRegistration,\n): HotkeyRegistrationView {\n  return {\n    hotkey: reg.hotkey,\n    id: reg.id,\n    options: reg.options,\n    parsedHotkey: reg.parsedHotkey,\n    target: reg.target,\n    triggerCount: reg.triggerCount,\n    hasFired: reg.hasFired,\n  }\n}\n\n/**\n * A handle returned from HotkeyManager.register() that allows updating\n * the callback and options without re-registering the hotkey.\n *\n * @example\n * ```ts\n * const handle = manager.register('Mod+S', callback, options)\n *\n * // Update callback without re-registering (avoids stale closures)\n * handle.callback = newCallback\n *\n * // Update options without re-registering\n * handle.setOptions({ enabled: false })\n *\n * // Check if still active\n * if (handle.isActive) {\n *   // ...\n * }\n *\n * // Unregister when done\n * handle.unregister()\n * ```\n */\nexport interface HotkeyRegistrationHandle {\n  /**\n   * The callback function. Can be set directly to update without re-registering.\n   * This avoids stale closures when the callback references React state.\n   */\n  callback: HotkeyCallback\n  /** Unique identifier for this registration */\n  readonly id: string\n  /** Check if this registration is still active (not unregistered) */\n  readonly isActive: boolean\n  /**\n   * Update options (merged with existing options).\n   * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.\n   */\n  setOptions: (options: Partial<HotkeyOptions>) => void\n  /** Unregister this hotkey */\n  unregister: () => void\n}\n\nlet registrationIdCounter = 0\n\n/**\n * Generates a unique ID for hotkey registrations.\n */\nfunction generateId(): string {\n  return `hotkey_${++registrationIdCounter}`\n}\n\n/**\n * Singleton manager for hotkey registrations.\n *\n * This class provides a centralized way to register and manage keyboard hotkeys.\n * It uses a single event listener for efficiency, regardless of how many hotkeys\n * are registered.\n *\n * @example\n * ```ts\n * const manager = HotkeyManager.getInstance()\n *\n * const unregister = manager.register('Mod+S', (event, context) => {\n *   console.log('Save triggered!')\n * })\n *\n * // Later, to unregister:\n * unregister()\n * ```\n */\nexport class HotkeyManager {\n  static #instance: HotkeyManager | null = null\n\n  /**\n   * The TanStack Store containing all hotkey registrations.\n   * Use this to subscribe to registration changes or access current registrations.\n   *\n   * @example\n   * ```ts\n   * const manager = HotkeyManager.getInstance()\n   *\n   * // Subscribe to registration changes\n   * const unsubscribe = manager.registrations.subscribe(() => {\n   *   console.log('Registrations changed:', manager.registrations.state.size)\n   * })\n   *\n   * // Access current registrations\n   * for (const [id, reg] of manager.registrations.state) {\n   *   console.log(reg.hotkey, reg.options.enabled)\n   * }\n   * ```\n   */\n  readonly registrations: Store<Map<string, HotkeyRegistration>> = new Store(\n    new Map(),\n  )\n  #platform: 'mac' | 'windows' | 'linux'\n  #targetListeners: Map<\n    HTMLElement | Document | Window,\n    {\n      keydown: (event: KeyboardEvent) => void\n      keyup: (event: KeyboardEvent) => void\n    }\n  > = new Map()\n  #targetRegistrations: Map<HTMLElement | Document | Window, Set<string>> =\n    new Map()\n\n  private constructor() {\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Gets the singleton instance of HotkeyManager.\n   */\n  static getInstance(): HotkeyManager {\n    if (!HotkeyManager.#instance) {\n      HotkeyManager.#instance = new HotkeyManager()\n    }\n    return HotkeyManager.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (HotkeyManager.#instance) {\n      HotkeyManager.#instance.destroy()\n      HotkeyManager.#instance = null\n    }\n  }\n\n  /**\n   * Registers a hotkey handler and returns a handle for updating the registration.\n   *\n   * The returned handle allows updating the callback and options without\n   * re-registering, which is useful for avoiding stale closures in React.\n   *\n   * @param hotkey - The hotkey string (e.g., 'Mod+S') or RawHotkey object\n   * @param callback - The function to call when the hotkey is pressed\n   * @param options - Options for the hotkey behavior\n   * @returns A handle for managing the registration\n   *\n   * @example\n   * ```ts\n   * const handle = manager.register('Mod+S', callback)\n   *\n   * // Update callback without re-registering (avoids stale closures)\n   * handle.callback = newCallback\n   *\n   * // Update options\n   * handle.setOptions({ enabled: false })\n   *\n   * // Unregister when done\n   * handle.unregister()\n   * ```\n   */\n  register(\n    hotkey: RegisterableHotkey,\n    callback: HotkeyCallback,\n    options: HotkeyOptions = {},\n  ): HotkeyRegistrationHandle {\n    // In SSR environments, return a no-op handle since there's no DOM to attach listeners to\n    if (typeof document === 'undefined' && !options.target) {\n      let currentCallback = callback\n      return {\n        id: generateId(),\n        unregister: () => {},\n        get callback() {\n          return currentCallback\n        },\n        set callback(newCallback: HotkeyCallback) {\n          currentCallback = newCallback\n        },\n        setOptions: () => {},\n        get isActive() {\n          return false\n        },\n      }\n    }\n\n    const id = generateId()\n    const platform = options.platform ?? this.#platform\n    const parsedHotkey =\n      typeof hotkey === 'string'\n        ? parseHotkey(hotkey, platform)\n        : rawHotkeyToParsedHotkey(hotkey, platform)\n    const hotkeyStr = (\n      typeof hotkey === 'string' ? hotkey : formatHotkey(parsedHotkey)\n    ) as Hotkey\n\n    // Resolve target: default to document if not provided\n    // Note: SSR case without explicit target is handled above\n    const target = options.target ?? document\n\n    // Resolve conflict behavior\n    const conflictBehavior = options.conflictBehavior ?? 'warn'\n\n    // Check for existing registrations with the same hotkey and target\n    const conflictingRegistration = this.#findConflictingRegistration(\n      hotkeyStr,\n      target,\n    )\n\n    if (conflictingRegistration) {\n      handleConflict(\n        conflictingRegistration.id,\n        hotkeyStr,\n        conflictBehavior,\n        (id) => this.#unregister(id),\n      )\n    }\n\n    const resolvedIgnoreInputs =\n      options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey)\n\n    const baseOptions = {\n      ...defaultHotkeyOptions,\n      requireReset: false,\n      ...options,\n      platform,\n    }\n\n    const registration: HotkeyRegistration = {\n      id,\n      hotkey: hotkeyStr,\n      parsedHotkey,\n      callback,\n      options: { ...baseOptions, ignoreInputs: resolvedIgnoreInputs },\n      hasFired: false,\n      triggerCount: 0,\n      target,\n    }\n\n    this.registrations.setState((prev) => new Map(prev).set(id, registration))\n\n    // Track registration for this target\n    if (!this.#targetRegistrations.has(target)) {\n      this.#targetRegistrations.set(target, new Set())\n    }\n    this.#targetRegistrations.get(target)!.add(id)\n\n    // Ensure listeners are attached for this target\n    this.#ensureListenersForTarget(target)\n\n    // Create and return the handle\n    const manager = this\n    const handle: HotkeyRegistrationHandle = {\n      get id() {\n        return id\n      },\n      unregister: () => {\n        manager.#unregister(id)\n      },\n      get callback() {\n        const reg = manager.registrations.state.get(id)\n        return reg?.callback ?? callback\n      },\n      set callback(newCallback: HotkeyCallback) {\n        const reg = manager.registrations.state.get(id)\n        if (reg) {\n          reg.callback = newCallback\n        }\n      },\n      setOptions: (newOptions: Partial<HotkeyOptions>) => {\n        manager.registrations.setState((prev) => {\n          const reg = prev.get(id)\n          if (reg) {\n            const next = new Map(prev)\n            next.set(id, { ...reg, options: { ...reg.options, ...newOptions } })\n            return next\n          }\n          return prev\n        })\n      },\n      get isActive() {\n        return manager.registrations.state.has(id)\n      },\n    }\n\n    return handle\n  }\n\n  /**\n   * Unregisters a hotkey by its registration ID.\n   */\n  #unregister(id: string): void {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return\n    }\n\n    const target = registration.target\n\n    // Remove registration\n    this.registrations.setState((prev) => {\n      const next = new Map(prev)\n      next.delete(id)\n      return next\n    })\n\n    // Remove from target registrations tracking\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (targetRegs) {\n      targetRegs.delete(id)\n      // If no more registrations for this target, remove listeners\n      if (targetRegs.size === 0) {\n        this.#removeListenersForTarget(target)\n      }\n    }\n  }\n\n  /**\n   * Ensures event listeners are attached for a specific target.\n   */\n  #ensureListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    // Skip if listeners already exist for this target\n    if (this.#targetListeners.has(target)) {\n      return\n    }\n\n    const keydownHandler = this.#createTargetKeyDownHandler(target)\n    const keyupHandler = this.#createTargetKeyUpHandler(target)\n\n    target.addEventListener('keydown', keydownHandler as EventListener)\n    target.addEventListener('keyup', keyupHandler as EventListener)\n\n    this.#targetListeners.set(target, {\n      keydown: keydownHandler,\n      keyup: keyupHandler,\n    })\n  }\n\n  /**\n   * Removes event listeners for a specific target.\n   */\n  #removeListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    const listeners = this.#targetListeners.get(target)\n    if (!listeners) {\n      return\n    }\n\n    target.removeEventListener('keydown', listeners.keydown as EventListener)\n    target.removeEventListener('keyup', listeners.keyup as EventListener)\n\n    this.#targetListeners.delete(target)\n    this.#targetRegistrations.delete(target)\n  }\n\n  /**\n   * Processes keyboard events for a specific target and event type.\n   */\n  #processTargetEvent(\n    event: KeyboardEvent,\n    target: HTMLElement | Document | Window,\n    eventType: 'keydown' | 'keyup',\n  ): void {\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (!targetRegs) {\n      return\n    }\n\n    for (const id of targetRegs) {\n      const registration = this.registrations.state.get(id)\n      if (!registration) {\n        continue\n      }\n\n      // Check if event originated from or bubbled to this target\n      if (!isEventForTarget(event, target)) {\n        continue\n      }\n\n      if (!registration.options.enabled) {\n        continue\n      }\n\n      // Check if we should ignore input elements (defaults to true)\n      if (registration.options.ignoreInputs !== false) {\n        if (shouldIgnoreInputEvent(event, target, registration.target)) {\n          continue\n        }\n      }\n\n      // Handle keydown events\n      if (eventType === 'keydown') {\n        if (registration.options.eventType !== 'keydown') {\n          continue\n        }\n\n        // Check if the hotkey matches first\n        const matches = matchesKeyboardEvent(\n          event,\n          registration.parsedHotkey,\n          registration.options.platform,\n        )\n\n        if (matches) {\n          // Always apply preventDefault/stopPropagation if the hotkey matches,\n          // even when requireReset is active and has already fired\n          if (registration.options.preventDefault) {\n            event.preventDefault()\n          }\n          if (registration.options.stopPropagation) {\n            event.stopPropagation()\n          }\n\n          // Only execute callback if requireReset is not active or hasn't fired yet\n          if (!registration.options.requireReset || !registration.hasFired) {\n            this.#executeHotkeyCallback(registration, event)\n\n            // Mark as fired if requireReset is enabled\n            if (registration.options.requireReset) {\n              registration.hasFired = true\n            }\n          }\n        }\n      }\n      // Handle keyup events\n      else {\n        if (registration.options.eventType === 'keyup') {\n          if (\n            matchesKeyboardEvent(\n              event,\n              registration.parsedHotkey,\n              registration.options.platform,\n            )\n          ) {\n            this.#executeHotkeyCallback(registration, event)\n          }\n        }\n\n        // Reset hasFired when any key in the hotkey is released\n        if (registration.options.requireReset && registration.hasFired) {\n          if (this.#shouldResetRegistration(registration, event)) {\n            registration.hasFired = false\n          }\n        }\n      }\n    }\n  }\n\n  /**\n   * Executes a hotkey callback with proper event handling.\n   */\n  #executeHotkeyCallback(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): void {\n    if (registration.options.preventDefault) {\n      event.preventDefault()\n    }\n    if (registration.options.stopPropagation) {\n      event.stopPropagation()\n    }\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count.\n    // We create a new Map but keep the same registration reference to preserve\n    // identity for mutation-based fields like hasFired.\n    this.registrations.setState((prev) => new Map(prev))\n\n    const context: HotkeyCallbackContext = {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    }\n\n    registration.callback(event, context)\n  }\n\n  /**\n   * Creates a keydown handler for a specific target.\n   */\n  #createTargetKeyDownHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keydown')\n    }\n  }\n\n  /**\n   * Creates a keyup handler for a specific target.\n   */\n  #createTargetKeyUpHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keyup')\n    }\n  }\n\n  /**\n   * Finds an existing registration with the same hotkey and target.\n   */\n  #findConflictingRegistration(\n    hotkey: Hotkey,\n    target: HTMLElement | Document | Window,\n  ): HotkeyRegistration | null {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey && registration.target === target) {\n        return registration\n      }\n    }\n    return null\n  }\n\n  /**\n   * Determines if a registration should be reset based on the keyup event.\n   */\n  #shouldResetRegistration(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): boolean {\n    const parsed = registration.parsedHotkey\n    const releasedKey = normalizeKeyName(event.key)\n\n    // Reset if the main key is released\n    // Compare case-insensitively for single-letter keys\n    const parsedKeyNormalized =\n      parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key\n    const releasedKeyNormalized =\n      releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey\n\n    if (releasedKeyNormalized === parsedKeyNormalized) {\n      return true\n    }\n\n    // Reset if any required modifier is released\n    // Use normalized key names and check against canonical modifier names\n    if (parsed.ctrl && releasedKey === 'Control') {\n      return true\n    }\n    if (parsed.shift && releasedKey === 'Shift') {\n      return true\n    }\n    if (parsed.alt && releasedKey === 'Alt') {\n      return true\n    }\n    if (parsed.meta && releasedKey === 'Meta') {\n      return true\n    }\n\n    return false\n  }\n\n  /**\n   * Triggers a registration's callback programmatically from devtools.\n   * Creates a synthetic KeyboardEvent and invokes the callback.\n   *\n   * @param id - The registration ID to trigger\n   * @returns True if the registration was found and triggered\n   */\n  triggerRegistration(id: string): boolean {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return false\n    }\n\n    const parsed = registration.parsedHotkey\n    const syntheticEvent = new KeyboardEvent(\n      registration.options.eventType ?? 'keydown',\n      {\n        key: parsed.key,\n        ctrlKey: parsed.ctrl,\n        shiftKey: parsed.shift,\n        altKey: parsed.alt,\n        metaKey: parsed.meta,\n        bubbles: true,\n        cancelable: true,\n      },\n    )\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count\n    this.registrations.setState((prev) => new Map(prev))\n\n    registration.callback(syntheticEvent, {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    })\n\n    return true\n  }\n\n  /**\n   * Gets the number of registered hotkeys.\n   */\n  getRegistrationCount(): number {\n    return this.registrations.state.size\n  }\n\n  /**\n   * Checks if a specific hotkey is registered.\n   *\n   * @param hotkey - The hotkey string to check\n   * @param target - Optional target element to match (if provided, both hotkey and target must match)\n   * @returns True if a matching registration exists\n   */\n  isRegistered(\n    hotkey: Hotkey,\n    target?: HTMLElement | Document | Window,\n  ): boolean {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey) {\n        // If target is specified, both must match\n        if (target === undefined || registration.target === target) {\n          return true\n        }\n      }\n    }\n    return false\n  }\n\n  /**\n   * Destroys the manager and removes all listeners.\n   */\n  destroy(): void {\n    // Remove all target listeners\n    for (const target of this.#targetListeners.keys()) {\n      this.#removeListenersForTarget(target)\n    }\n\n    this.registrations.setState(() => new Map())\n    this.#targetListeners.clear()\n    this.#targetRegistrations.clear()\n  }\n}\n\n/**\n * Gets the singleton HotkeyManager instance.\n * Convenience function for accessing the manager.\n */\nexport function getHotkeyManager(): HotkeyManager {\n  return HotkeyManager.getInstance()\n}\n"],"mappings":"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"}

package/dist/hotkey-manager.d.cts

@@ -1,4 +1,4 @@
-import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.cjs";
+import { Hotkey, HotkeyCallback, HotkeyMeta, ParsedHotkey, RegisterableHotkey } from "./hotkey.cjs";
 import { ConflictBehavior } from "./manager.utils.cjs";
 import { Store } from "@tanstack/store";
 
@@ -29,6 +29,8 @@ interface HotkeyOptions {
   stopPropagation?: boolean;
   /** The DOM element to attach the event listener to. Defaults to document. */
   target?: HTMLElement | Document | Window | null;
+  /** Optional metadata (name, description, custom fields via declaration merging) */
+  meta?: HotkeyMeta;
 }
 /**
  * A registered hotkey handler in the HotkeyManager.
@@ -51,6 +53,31 @@ interface HotkeyRegistration {
   /** How many times this registration's callback has been triggered */
   triggerCount: number;
 }
+/**
+ * Public view of a hotkey registration for display and introspection.
+ * Omits the callback function which is an internal implementation detail.
+ */
+interface HotkeyRegistrationView {
+  /** The original hotkey string */
+  hotkey: Hotkey;
+  /** Unique identifier for this registration */
+  id: string;
+  /** Options for this registration */
+  options: HotkeyOptions;
+  /** The parsed hotkey */
+  parsedHotkey: ParsedHotkey;
+  /** The resolved target element for this registration */
+  target: HTMLElement | Document | Window;
+  /** How many times this registration's callback has been triggered */
+  triggerCount: number;
+  /** Whether this registration has fired and needs reset (for requireReset) */
+  hasFired: boolean;
+}
+/**
+ * Creates a public view from an internal registration,
+ * stripping the callback function.
+ */
+declare function toHotkeyRegistrationView(reg: HotkeyRegistration): HotkeyRegistrationView;
 /**
  * A handle returned from HotkeyManager.register() that allows updating
  * the callback and options without re-registering the hotkey.
@@ -199,5 +226,5 @@ declare class HotkeyManager {
  */
 declare function getHotkeyManager(): HotkeyManager;
 //#endregion
-export { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager };
+export { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, getHotkeyManager, toHotkeyRegistrationView };
 //# sourceMappingURL=hotkey-manager.d.cts.map

package/dist/hotkey-manager.d.ts

@@ -1,4 +1,4 @@
-import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.js";
+import { Hotkey, HotkeyCallback, HotkeyMeta, ParsedHotkey, RegisterableHotkey } from "./hotkey.js";
 import { ConflictBehavior } from "./manager.utils.js";
 import { Store } from "@tanstack/store";
 
@@ -29,6 +29,8 @@ interface HotkeyOptions {
   stopPropagation?: boolean;
   /** The DOM element to attach the event listener to. Defaults to document. */
   target?: HTMLElement | Document | Window | null;
+  /** Optional metadata (name, description, custom fields via declaration merging) */
+  meta?: HotkeyMeta;
 }
 /**
  * A registered hotkey handler in the HotkeyManager.
@@ -51,6 +53,31 @@ interface HotkeyRegistration {
   /** How many times this registration's callback has been triggered */
   triggerCount: number;
 }
+/**
+ * Public view of a hotkey registration for display and introspection.
+ * Omits the callback function which is an internal implementation detail.
+ */
+interface HotkeyRegistrationView {
+  /** The original hotkey string */
+  hotkey: Hotkey;
+  /** Unique identifier for this registration */
+  id: string;
+  /** Options for this registration */
+  options: HotkeyOptions;
+  /** The parsed hotkey */
+  parsedHotkey: ParsedHotkey;
+  /** The resolved target element for this registration */
+  target: HTMLElement | Document | Window;
+  /** How many times this registration's callback has been triggered */
+  triggerCount: number;
+  /** Whether this registration has fired and needs reset (for requireReset) */
+  hasFired: boolean;
+}
+/**
+ * Creates a public view from an internal registration,
+ * stripping the callback function.
+ */
+declare function toHotkeyRegistrationView(reg: HotkeyRegistration): HotkeyRegistrationView;
 /**
  * A handle returned from HotkeyManager.register() that allows updating
  * the callback and options without re-registering the hotkey.
@@ -199,5 +226,5 @@ declare class HotkeyManager {
  */
 declare function getHotkeyManager(): HotkeyManager;
 //#endregion
-export { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, getHotkeyManager };
+export { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, getHotkeyManager, toHotkeyRegistrationView };
 //# sourceMappingURL=hotkey-manager.d.ts.map

package/dist/hotkey-manager.js

@@ -6,6 +6,21 @@ import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, isEventFo
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
+/**
+* Creates a public view from an internal registration,
+* stripping the callback function.
+*/
+function toHotkeyRegistrationView(reg) {
+	return {
+		hotkey: reg.hotkey,
+		id: reg.id,
+		options: reg.options,
+		parsedHotkey: reg.parsedHotkey,
+		target: reg.target,
+		triggerCount: reg.triggerCount,
+		hasFired: reg.hasFired
+	};
+}
 let registrationIdCounter = 0;
 /**
 * Generates a unique ID for hotkey registrations.
@@ -362,5 +377,5 @@ function getHotkeyManager() {
 }
 
 //#endregion
-export { HotkeyManager, getHotkeyManager };
+export { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView };
 //# sourceMappingURL=hotkey-manager.js.map