@tanstack/hotkeys 0.8.0 → 0.9.0

package/dist/key.types.d.ts

@@ -0,0 +1,82 @@
+import { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from "./_named-keys.js";
+
+//#region src/key.types.d.ts
+/**
+ * All supported modifier key names, including aliases.
+ * - Control/Ctrl: The Control key
+ * - Shift: The Shift key
+ * - Alt/Option: The Alt key (Option on macOS)
+ * - Command/Cmd: The Command key (macOS only)
+ * - CommandOrControl/Mod: Command on macOS, Control on other platforms
+ */
+type Modifier = 'Control' | 'Ctrl' | 'Shift' | 'Alt' | 'Option' | 'Command' | 'Cmd' | 'CommandOrControl' | 'Mod';
+/**
+ * Canonical modifier names that map to KeyboardEvent properties.
+ */
+type CanonicalModifier = 'Control' | 'Shift' | 'Alt' | 'Meta';
+/**
+ * Letter keys A-Z (case-insensitive in matching).
+ */
+type LetterKey = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+/**
+ * Number keys 0-9.
+ */
+type NumberKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+/**
+ * Function keys F1-F24, supported as both logical keys and physical codes.
+ */
+type FunctionKey = 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | 'F13' | 'F14' | 'F15' | 'F16' | 'F17' | 'F18' | 'F19' | 'F20' | 'F21' | 'F22' | 'F23' | 'F24';
+/**
+ * Navigation keys for cursor movement.
+ */
+type NavigationKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
+/**
+ * Editing and special keys.
+ */
+type EditingKey = 'Enter' | 'Escape' | 'Space' | 'Tab' | 'Backspace' | 'Delete';
+/**
+ * Printable punctuation glyphs used in keyboard shortcuts. Matching uses the
+ * final KeyboardEvent.key glyph, independent of which layout produced it.
+ */
+type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | ';' | '`' | "'" | '+' | '?' | '!' | '@' | '#' | '$' | '%' | '^' | '&' | '*' | '(' | ')' | '_' | '{' | '}' | '|' | ':' | '"' | '<' | '>' | '~';
+/** Additional named logical keys, including media, browser, lock, and input-mode keys. */
+type NamedKey = (typeof SHARED_NAMED_KEYS)[number] | (typeof LOGICAL_ONLY_NAMED_KEYS)[number];
+/** Supported logical key names other than printable punctuation. */
+type NonPunctuationKey = LetterKey | NumberKey | EditingKey | NavigationKey | FunctionKey | NamedKey;
+/**
+ * Supported physical KeyboardEvent.code names, independent of keyboard layout.
+ * Letter, digit, numpad, and sided modifier names use finite template unions.
+ * `Unidentified` is excluded because it cannot identify a physical key.
+ *
+ * @see https://www.w3.org/TR/uievents-code/
+ */
+type PhysicalKeyCode = `Key${LetterKey}` | `Digit${NumberKey}` | `Numpad${NumberKey}` | `${'Alt' | 'Control' | 'Meta' | 'Shift'}${'Left' | 'Right'}` | EditingKey | NavigationKey | FunctionKey | (typeof SHARED_NAMED_KEYS)[number] | 'Backquote' | 'Backslash' | 'BracketLeft' | 'BracketRight' | 'Comma' | 'Equal' | 'IntlBackslash' | 'IntlRo' | 'IntlYen' | 'Minus' | 'Period' | 'Quote' | 'Semicolon' | 'Slash' | `Lang${1 | 2 | 3 | 4 | 5}` | `Numpad${'Add' | 'Backspace' | 'Clear' | 'ClearEntry' | 'Comma' | 'Decimal' | 'Divide' | 'Enter' | 'Equal' | 'Hash' | 'MemoryAdd' | 'MemoryClear' | 'MemoryRecall' | 'MemoryStore' | 'MemorySubtract' | 'Multiply' | 'ParenLeft' | 'ParenRight' | 'Star' | 'Subtract'}` | 'LaunchApp1' | 'LaunchApp2' | 'MediaSelect' | 'Sleep' | 'Turbo' | 'Abort' | 'Resume' | 'Suspend';
+/**
+ * An explicit physical key token. All codes use brackets, including names such
+ * as `[Enter]` that also exist as logical keys. Invalid code names are rejected
+ * by TypeScript, and supported names are available in autocomplete.
+ */
+type PhysicalKey = `[${PhysicalKeyCode}]`;
+/** Supported logical key names, excluding bracketed physical-code syntax. */
+type LogicalKey = NonPunctuationKey | PunctuationKey;
+/** All supported logical keys and bracketed physical key tokens. */
+type Key = LogicalKey | PhysicalKey;
+/**
+ * Includes both modifier keys and regular keys.
+ */
+type IndividualKey = CanonicalModifier | Key;
+/** Keyboard event properties normalized for internal matching and recording. */
+interface NormalizedKeyboardEvent {
+  key: string;
+  code: string;
+  ctrl: boolean;
+  shift: boolean;
+  alt: boolean;
+  meta: boolean;
+  altGraph: boolean;
+  location: number;
+  isComposing: boolean;
+}
+//#endregion
+export { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey };
+//# sourceMappingURL=key.types.d.ts.map

package/dist/match.cjs

@@ -1,11 +1,14 @@
-const require_constants = require('./constants.cjs');
+const require_platform = require('./platform.cjs');
+const require__keyboard_event = require('./_keyboard-event.cjs');
 const require_parse = require('./parse.cjs');
+const require__match = require('./_match.cjs');
 
 //#region src/match.ts
 /**
 * Checks if a KeyboardEvent matches a hotkey.
 *
-* Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+* Physical bindings such as `Mod+[KeyS]` match `event.code` exactly.
+* Logical bindings use `event.key`, with a fallback to `code`
 * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
 * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
 * Letter keys are matched case-insensitively.
@@ -30,31 +33,8 @@ const require_parse = require('./parse.cjs');
 * })
 * ```
 */
-function matchesKeyboardEvent(event, hotkey, platform = require_constants.detectPlatform()) {
-	const parsed = typeof hotkey === "string" ? require_parse.parseHotkey(hotkey, platform) : hotkey;
-	if (event.ctrlKey !== parsed.ctrl) return false;
-	if (event.shiftKey !== parsed.shift) return false;
-	if (event.altKey !== parsed.alt) return false;
-	if (event.metaKey !== parsed.meta) return false;
-	const eventKey = require_constants.normalizeKeyName(event.key);
-	const hotkeyKey = parsed.key;
-	if (eventKey !== "Dead" && eventKey.length === 1 && hotkeyKey.length === 1) {
-		if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) return true;
-		if (require_constants.isSingleLetterKey(eventKey) && (/^[A-Za-z]$/.test(eventKey) || !event.altKey)) return false;
-	}
-	if (event.code && (eventKey === "Dead" || eventKey.length === 1 && hotkeyKey.length === 1)) {
-		if (event.code.startsWith("Key")) {
-			const codeLetter = event.code.slice(3);
-			if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) return codeLetter.toUpperCase() === hotkeyKey.toUpperCase();
-		}
-		if (event.code.startsWith("Digit")) {
-			const codeDigit = event.code.slice(5);
-			if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) return codeDigit === hotkeyKey;
-		}
-		if (event.code in require_constants.PUNCTUATION_CODE_MAP) return require_constants.PUNCTUATION_CODE_MAP[event.code] === hotkeyKey;
-		return false;
-	}
-	return eventKey === hotkeyKey;
+function matchesKeyboardEvent(event, hotkey, platform = require_platform.detectPlatform()) {
+	return require__match.matchKeyboardEvent(event, hotkey, platform).matched;
 }
 /**
 * Creates a keyboard event handler that calls the callback when the hotkey matches.
@@ -76,7 +56,7 @@ function matchesKeyboardEvent(event, hotkey, platform = require_constants.detect
 */
 function createHotkeyHandler(hotkey, callback, options = {}) {
 	const { preventDefault = true, stopPropagation = true, platform } = options;
-	const resolvedPlatform = platform ?? require_constants.detectPlatform();
+	const resolvedPlatform = platform ?? require_platform.detectPlatform();
 	const hotkeyString = typeof hotkey === "string" ? hotkey : formatParsedHotkey(hotkey);
 	const parsed = typeof hotkey === "string" ? require_parse.parseHotkey(hotkey, resolvedPlatform) : hotkey;
 	const context = {
@@ -111,7 +91,7 @@ function createHotkeyHandler(hotkey, callback, options = {}) {
 */
 function createMultiHotkeyHandler(handlers, options = {}) {
 	const { preventDefault = true, stopPropagation = true, platform } = options;
-	const resolvedPlatform = platform ?? require_constants.detectPlatform();
+	const resolvedPlatform = platform ?? require_platform.detectPlatform();
 	const parsedHandlers = Object.entries(handlers).filter((entry) => Boolean(entry[1])).map(([hotkey, handler]) => {
 		const parsed = require_parse.parseHotkey(hotkey, resolvedPlatform);
 		return {
@@ -142,11 +122,22 @@ function formatParsedHotkey(parsed) {
 	if (parsed.alt) parts.push("Alt");
 	if (parsed.shift) parts.push("Shift");
 	if (parsed.meta) parts.push("Meta");
-	parts.push(parsed.key);
+	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : parsed.key);
 	return parts.join("+");
 }
+/**
+* Compares normalized binding identity, including all four modifiers.
+* Aliases resolve on the supplied platform. A physical code and a logical key
+* remain distinct even when one keyboard event could match both.
+*/
+function areHotkeysEqual(left, right, platform = require_platform.detectPlatform()) {
+	const a = require_parse.parseRegisterableHotkey(left, platform);
+	const b = require_parse.parseRegisterableHotkey(right, platform);
+	return a.ctrl === b.ctrl && a.alt === b.alt && a.shift === b.shift && a.meta === b.meta && (a.code !== void 0 || b.code !== void 0 ? a.code === b.code : require__keyboard_event.keysEqual(a.key, b.key));
+}
 
 //#endregion
+exports.areHotkeysEqual = areHotkeysEqual;
 exports.createHotkeyHandler = createHotkeyHandler;
 exports.createMultiHotkeyHandler = createMultiHotkeyHandler;
 exports.matchesKeyboardEvent = matchesKeyboardEvent;

package/dist/match.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"match.cjs","names":["detectPlatform","parseHotkey","normalizeKeyName","isSingleLetterKey","PUNCTUATION_CODE_MAP"],"sources":["../src/match.ts"],"sourcesContent":["import {\n  PUNCTUATION_CODE_MAP,\n  detectPlatform,\n  isSingleLetterKey,\n  normalizeKeyName,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n} from './hotkey'\n\n/**\n * Checks if a KeyboardEvent matches a hotkey.\n *\n * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special\n * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).\n * Letter keys are matched case-insensitively.\n *\n * Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n *\n * @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (matchesKeyboardEvent(event, 'Mod+S')) {\n *     event.preventDefault()\n *     handleSave()\n *   }\n * })\n * ```\n */\nexport function matchesKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check modifiers\n  if (event.ctrlKey !== parsed.ctrl) {\n    return false\n  }\n  if (event.shiftKey !== parsed.shift) {\n    return false\n  }\n  if (event.altKey !== parsed.alt) {\n    return false\n  }\n  if (event.metaKey !== parsed.meta) {\n    return false\n  }\n\n  // Check key (case-insensitive for letters)\n  const eventKey = normalizeKeyName(event.key)\n  const hotkeyKey = parsed.key\n\n  // For single-character keys (not dead keys), try direct event.key match first\n  if (eventKey !== 'Dead' && eventKey.length === 1 && hotkeyKey.length === 1) {\n    if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n      return true\n    }\n\n    // If event.key is a letter, we usually trust the keyboard layout.\n    // For ASCII letters: always trust layout (Dvorak, Colemak, AZERTY support).\n    // For non-ASCII letters without Alt: trust layout (e.g., Cyrillic keyboards).\n    //\n    // For non-ASCII letters WITH Alt held down: fall through to the event.code\n    // fallback. macOS Option+letter combinations produce non-ASCII letters as\n    // event.key (e.g., Option+A → 'å', Option+' → 'æ', Option+P → 'π'), but\n    // event.code still reflects the physical key. We want Alt+A to match even\n    // when Option+A fires event.key='å'.\n    if (\n      isSingleLetterKey(eventKey) &&\n      (/^[A-Za-z]$/.test(eventKey) || !event.altKey)\n    ) {\n      return false\n    }\n  }\n\n  // Fallback to event.code for dead keys or single-char mismatches where\n  // event.key is a non-letter special character.\n  // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'\n  // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'\n  if (\n    event.code &&\n    (eventKey === 'Dead' || (eventKey.length === 1 && hotkeyKey.length === 1))\n  ) {\n    // fallback for letter keys (common with mac option + letter)\n    if (event.code.startsWith('Key')) {\n      const codeLetter = event.code.slice(3)\n      if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n        return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n      }\n    }\n\n    // fallback for number keys (common with mac option + num)\n    if (event.code.startsWith('Digit')) {\n      const codeDigit = event.code.slice(5)\n      if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n        return codeDigit === hotkeyKey\n      }\n    }\n    // Fallback for punctuation keys (e.g., Minus, Slash, BracketLeft).\n    // On macOS, Option+punctuation produces composed characters (e.g., Option+- → '–'),\n    // but event.code still reports the physical key.\n    if (event.code in PUNCTUATION_CODE_MAP) {\n      return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey\n    }\n\n    return false\n  }\n\n  // For special keys, compare exactly (after normalization)\n  return eventKey === hotkeyKey\n}\n\n/**\n * Options for creating a hotkey handler.\n */\nexport interface CreateHotkeyHandlerOptions {\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n}\n\n/**\n * Creates a keyboard event handler that calls the callback when the hotkey matches.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n *   console.log(`${hotkey} was pressed`)\n *   handleSave()\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createHotkeyHandler(\n  hotkey: Hotkey | ParsedHotkey,\n  callback: HotkeyCallback,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n  const context: HotkeyCallbackContext = {\n    hotkey: hotkeyString,\n    parsedHotkey: parsed,\n  }\n\n  return (event: KeyboardEvent) => {\n    if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n      if (preventDefault) {\n        event.preventDefault()\n      }\n      if (stopPropagation) {\n        event.stopPropagation()\n      }\n      callback(event, context)\n    }\n  }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/**\n * Creates a handler that matches multiple hotkeys.\n *\n * @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n *   'Mod+S': (event, { hotkey }) => handleSave(),\n *   'Mod+Z': (event, { hotkey }) => handleUndo(),\n *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createMultiHotkeyHandler(\n  handlers: MultiHotkeyHandler,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  // Pre-parse all hotkeys for efficiency\n  const parsedHandlers = Object.entries(handlers)\n    .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n    .map(([hotkey, handler]) => {\n      const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n      const context: HotkeyCallbackContext = {\n        hotkey: hotkey as Hotkey,\n        parsedHotkey: parsed,\n      }\n      return { parsed, handler, context }\n    })\n\n  return (event: KeyboardEvent) => {\n    for (const { parsed, handler, context } of parsedHandlers) {\n      if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n        if (preventDefault) {\n          event.preventDefault()\n        }\n        if (stopPropagation) {\n          event.stopPropagation()\n        }\n        handler(event, context)\n        return // Only handle the first match\n      }\n    }\n  }\n}\n\n/**\n * Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n  const parts: Array<string> = []\n\n  if (parsed.ctrl) parts.push('Control')\n  if (parsed.alt) parts.push('Alt')\n  if (parsed.shift) parts.push('Shift')\n  if (parsed.meta) parts.push('Meta')\n  parts.push(parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n"],"mappings":"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"}
+{"version":3,"file":"match.cjs","names":["detectPlatform","matchKeyboardEvent","parseHotkey","parseRegisterableHotkey","keysEqual"],"sources":["../src/match.ts"],"sourcesContent":["import { matchKeyboardEvent } from './_match'\nimport { parseHotkey, parseRegisterableHotkey } from './parse'\nimport { detectPlatform } from './platform'\nimport { keysEqual } from './_keyboard-event'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n  RegisterableHotkey,\n} from './hotkey.types'\n\nexport interface KeyboardEventMatch {\n  matched: boolean\n  score: 0 | 1 | 2 | 3\n  source?: 'key' | 'code' | 'fallback'\n  identity?: { key: string; code: string }\n}\n\n/**\n * Checks if a KeyboardEvent matches a hotkey.\n *\n * Physical bindings such as `Mod+[KeyS]` match `event.code` exactly.\n * Logical bindings use `event.key`, with a fallback to `code`\n * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special\n * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).\n * Letter keys are matched case-insensitively.\n *\n * Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n *\n * @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (matchesKeyboardEvent(event, 'Mod+S')) {\n *     event.preventDefault()\n *     handleSave()\n *   }\n * })\n * ```\n */\nexport function matchesKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  return matchKeyboardEvent(event, hotkey, platform).matched\n}\n\n/**\n * Options for creating a hotkey handler.\n */\nexport interface CreateHotkeyHandlerOptions {\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n}\n\n/**\n * Creates a keyboard event handler that calls the callback when the hotkey matches.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n *   console.log(`${hotkey} was pressed`)\n *   handleSave()\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createHotkeyHandler(\n  hotkey: Hotkey | ParsedHotkey,\n  callback: HotkeyCallback,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n  const context: HotkeyCallbackContext = {\n    hotkey: hotkeyString,\n    parsedHotkey: parsed,\n  }\n\n  return (event: KeyboardEvent) => {\n    if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n      if (preventDefault) {\n        event.preventDefault()\n      }\n      if (stopPropagation) {\n        event.stopPropagation()\n      }\n      callback(event, context)\n    }\n  }\n}\n\nexport type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/**\n * Creates a handler that matches multiple hotkeys.\n *\n * @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n *   'Mod+S': (event, { hotkey }) => handleSave(),\n *   'Mod+Z': (event, { hotkey }) => handleUndo(),\n *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createMultiHotkeyHandler(\n  handlers: MultiHotkeyHandler,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  // Pre-parse all hotkeys for efficiency\n  const parsedHandlers = Object.entries(handlers)\n    .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n    .map(([hotkey, handler]) => {\n      const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n      const context: HotkeyCallbackContext = {\n        hotkey: hotkey as Hotkey,\n        parsedHotkey: parsed,\n      }\n      return { parsed, handler, context }\n    })\n\n  return (event: KeyboardEvent) => {\n    for (const { parsed, handler, context } of parsedHandlers) {\n      if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n        if (preventDefault) {\n          event.preventDefault()\n        }\n        if (stopPropagation) {\n          event.stopPropagation()\n        }\n        handler(event, context)\n        return // Only handle the first match\n      }\n    }\n  }\n}\n\n/**\n * Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n  const parts: Array<string> = []\n\n  if (parsed.ctrl) parts.push('Control')\n  if (parsed.alt) parts.push('Alt')\n  if (parsed.shift) parts.push('Shift')\n  if (parsed.meta) parts.push('Meta')\n  parts.push(parsed.code !== undefined ? `[${parsed.code}]` : parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n\n/**\n * Compares normalized binding identity, including all four modifiers.\n * Aliases resolve on the supplied platform. A physical code and a logical key\n * remain distinct even when one keyboard event could match both.\n */\nexport function areHotkeysEqual(\n  left: RegisterableHotkey,\n  right: RegisterableHotkey,\n  platform = detectPlatform(),\n): boolean {\n  const a = parseRegisterableHotkey(left, platform)\n  const b = parseRegisterableHotkey(right, platform)\n  return (\n    a.ctrl === b.ctrl &&\n    a.alt === b.alt &&\n    a.shift === b.shift &&\n    a.meta === b.meta &&\n    (a.code !== undefined || b.code !== undefined\n      ? a.code === b.code\n      : keysEqual(a.key, b.key))\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,qBACd,OACA,QACA,WAAwCA,iCAAgB,EAC/C;AACT,QAAOC,kCAAmB,OAAO,QAAQ,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;AAiCrD,SAAgB,oBACd,QACA,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAYD,iCAAgB;CAErD,MAAM,eACJ,OAAO,WAAW,WAAW,SAAS,mBAAmB,OAAO;CAClE,MAAM,SACJ,OAAO,WAAW,WAAWE,0BAAY,QAAQ,iBAAiB,GAAG;CAEvE,MAAM,UAAiC;EACrC,QAAQ;EACR,cAAc;EACf;AAED,SAAQ,UAAyB;AAC/B,MAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,YAAS,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;AAyB9B,SAAgB,yBACd,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAYF,iCAAgB;CAGrD,MAAM,iBAAiB,OAAO,QAAQ,SAAS,CAC5C,QAAQ,UAA6C,QAAQ,MAAM,GAAG,CAAC,CACvE,KAAK,CAAC,QAAQ,aAAa;EAC1B,MAAM,SAASE,0BAAY,QAAkB,iBAAiB;AAK9D,SAAO;GAAE;GAAQ;GAAS,SAJa;IAC7B;IACR,cAAc;IACf;GACkC;GACnC;AAEJ,SAAQ,UAAyB;AAC/B,OAAK,MAAM,EAAE,QAAQ,SAAS,aAAa,eACzC,KAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,WAAQ,OAAO,QAAQ;AACvB;;;;;;;;AAUR,SAAS,mBAAmB,QAA8B;CACxD,MAAM,QAAuB,EAAE;AAE/B,KAAI,OAAO,KAAM,OAAM,KAAK,UAAU;AACtC,KAAI,OAAO,IAAK,OAAM,KAAK,MAAM;AACjC,KAAI,OAAO,MAAO,OAAM,KAAK,QAAQ;AACrC,KAAI,OAAO,KAAM,OAAM,KAAK,OAAO;AACnC,OAAM,KAAK,OAAO,SAAS,SAAY,IAAI,OAAO,KAAK,KAAK,OAAO,IAAI;AAEvE,QAAO,MAAM,KAAK,IAAI;;;;;;;AAQxB,SAAgB,gBACd,MACA,OACA,WAAWF,iCAAgB,EAClB;CACT,MAAM,IAAIG,sCAAwB,MAAM,SAAS;CACjD,MAAM,IAAIA,sCAAwB,OAAO,SAAS;AAClD,QACE,EAAE,SAAS,EAAE,QACb,EAAE,QAAQ,EAAE,OACZ,EAAE,UAAU,EAAE,SACd,EAAE,SAAS,EAAE,SACZ,EAAE,SAAS,UAAa,EAAE,SAAS,SAChC,EAAE,SAAS,EAAE,OACbC,kCAAU,EAAE,KAAK,EAAE,IAAI"}

package/dist/match.d.cts

@@ -1,10 +1,20 @@
-import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.cjs";
+import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.cjs";
 
 //#region src/match.d.ts
+interface KeyboardEventMatch {
+  matched: boolean;
+  score: 0 | 1 | 2 | 3;
+  source?: 'key' | 'code' | 'fallback';
+  identity?: {
+    key: string;
+    code: string;
+  };
+}
 /**
  * Checks if a KeyboardEvent matches a hotkey.
  *
- * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+ * Physical bindings such as `Mod+[KeyS]` match `event.code` exactly.
+ * Logical bindings use `event.key`, with a fallback to `code`
  * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
  * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
  * Letter keys are matched case-insensitively.
@@ -80,6 +90,12 @@ type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback };
  * ```
  */
 declare function createMultiHotkeyHandler(handlers: MultiHotkeyHandler, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+/**
+ * Compares normalized binding identity, including all four modifiers.
+ * Aliases resolve on the supplied platform. A physical code and a logical key
+ * remain distinct even when one keyboard event could match both.
+ */
+declare function areHotkeysEqual(left: RegisterableHotkey, right: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): boolean;
 //#endregion
-export { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
+export { CreateHotkeyHandlerOptions, KeyboardEventMatch, MultiHotkeyHandler, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
 //# sourceMappingURL=match.d.cts.map

package/dist/match.d.ts

@@ -1,10 +1,20 @@
-import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.js";
+import { Hotkey, HotkeyCallback, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
 
 //#region src/match.d.ts
+interface KeyboardEventMatch {
+  matched: boolean;
+  score: 0 | 1 | 2 | 3;
+  source?: 'key' | 'code' | 'fallback';
+  identity?: {
+    key: string;
+    code: string;
+  };
+}
 /**
  * Checks if a KeyboardEvent matches a hotkey.
  *
- * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+ * Physical bindings such as `Mod+[KeyS]` match `event.code` exactly.
+ * Logical bindings use `event.key`, with a fallback to `code`
  * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
  * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
  * Letter keys are matched case-insensitively.
@@ -80,6 +90,12 @@ type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback };
  * ```
  */
 declare function createMultiHotkeyHandler(handlers: MultiHotkeyHandler, options?: CreateHotkeyHandlerOptions): (event: KeyboardEvent) => void;
+/**
+ * Compares normalized binding identity, including all four modifiers.
+ * Aliases resolve on the supplied platform. A physical code and a logical key
+ * remain distinct even when one keyboard event could match both.
+ */
+declare function areHotkeysEqual(left: RegisterableHotkey, right: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): boolean;
 //#endregion
-export { CreateHotkeyHandlerOptions, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
+export { CreateHotkeyHandlerOptions, KeyboardEventMatch, MultiHotkeyHandler, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
 //# sourceMappingURL=match.d.ts.map

package/dist/match.js

@@ -1,11 +1,14 @@
-import { PUNCTUATION_CODE_MAP, detectPlatform, isSingleLetterKey, normalizeKeyName } from "./constants.js";
-import { parseHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
+import { keysEqual } from "./_keyboard-event.js";
+import { parseHotkey, parseRegisterableHotkey } from "./parse.js";
+import { matchKeyboardEvent } from "./_match.js";
 
 //#region src/match.ts
 /**
 * Checks if a KeyboardEvent matches a hotkey.
 *
-* Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+* Physical bindings such as `Mod+[KeyS]` match `event.code` exactly.
+* Logical bindings use `event.key`, with a fallback to `code`
 * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
 * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
 * Letter keys are matched case-insensitively.
@@ -31,30 +34,7 @@ import { parseHotkey } from "./parse.js";
 * ```
 */
 function matchesKeyboardEvent(event, hotkey, platform = detectPlatform()) {
-	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
-	if (event.ctrlKey !== parsed.ctrl) return false;
-	if (event.shiftKey !== parsed.shift) return false;
-	if (event.altKey !== parsed.alt) return false;
-	if (event.metaKey !== parsed.meta) return false;
-	const eventKey = normalizeKeyName(event.key);
-	const hotkeyKey = parsed.key;
-	if (eventKey !== "Dead" && eventKey.length === 1 && hotkeyKey.length === 1) {
-		if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) return true;
-		if (isSingleLetterKey(eventKey) && (/^[A-Za-z]$/.test(eventKey) || !event.altKey)) return false;
-	}
-	if (event.code && (eventKey === "Dead" || eventKey.length === 1 && hotkeyKey.length === 1)) {
-		if (event.code.startsWith("Key")) {
-			const codeLetter = event.code.slice(3);
-			if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) return codeLetter.toUpperCase() === hotkeyKey.toUpperCase();
-		}
-		if (event.code.startsWith("Digit")) {
-			const codeDigit = event.code.slice(5);
-			if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) return codeDigit === hotkeyKey;
-		}
-		if (event.code in PUNCTUATION_CODE_MAP) return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey;
-		return false;
-	}
-	return eventKey === hotkeyKey;
+	return matchKeyboardEvent(event, hotkey, platform).matched;
 }
 /**
 * Creates a keyboard event handler that calls the callback when the hotkey matches.
@@ -142,10 +122,20 @@ function formatParsedHotkey(parsed) {
 	if (parsed.alt) parts.push("Alt");
 	if (parsed.shift) parts.push("Shift");
 	if (parsed.meta) parts.push("Meta");
-	parts.push(parsed.key);
+	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : parsed.key);
 	return parts.join("+");
 }
+/**
+* Compares normalized binding identity, including all four modifiers.
+* Aliases resolve on the supplied platform. A physical code and a logical key
+* remain distinct even when one keyboard event could match both.
+*/
+function areHotkeysEqual(left, right, platform = detectPlatform()) {
+	const a = parseRegisterableHotkey(left, platform);
+	const b = parseRegisterableHotkey(right, platform);
+	return a.ctrl === b.ctrl && a.alt === b.alt && a.shift === b.shift && a.meta === b.meta && (a.code !== void 0 || b.code !== void 0 ? a.code === b.code : keysEqual(a.key, b.key));
+}
 
 //#endregion
-export { createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
+export { areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
 //# sourceMappingURL=match.js.map

package/dist/match.js.map

@@ -1 +1 @@
-{"version":3,"file":"match.js","names":[],"sources":["../src/match.ts"],"sourcesContent":["import {\n  PUNCTUATION_CODE_MAP,\n  detectPlatform,\n  isSingleLetterKey,\n  normalizeKeyName,\n} from './constants'\nimport { parseHotkey } from './parse'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n} from './hotkey'\n\n/**\n * Checks if a KeyboardEvent matches a hotkey.\n *\n * Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`\n * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special\n * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).\n * Letter keys are matched case-insensitively.\n *\n * Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n *\n * @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (matchesKeyboardEvent(event, 'Mod+S')) {\n *     event.preventDefault()\n *     handleSave()\n *   }\n * })\n * ```\n */\nexport function matchesKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check modifiers\n  if (event.ctrlKey !== parsed.ctrl) {\n    return false\n  }\n  if (event.shiftKey !== parsed.shift) {\n    return false\n  }\n  if (event.altKey !== parsed.alt) {\n    return false\n  }\n  if (event.metaKey !== parsed.meta) {\n    return false\n  }\n\n  // Check key (case-insensitive for letters)\n  const eventKey = normalizeKeyName(event.key)\n  const hotkeyKey = parsed.key\n\n  // For single-character keys (not dead keys), try direct event.key match first\n  if (eventKey !== 'Dead' && eventKey.length === 1 && hotkeyKey.length === 1) {\n    if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) {\n      return true\n    }\n\n    // If event.key is a letter, we usually trust the keyboard layout.\n    // For ASCII letters: always trust layout (Dvorak, Colemak, AZERTY support).\n    // For non-ASCII letters without Alt: trust layout (e.g., Cyrillic keyboards).\n    //\n    // For non-ASCII letters WITH Alt held down: fall through to the event.code\n    // fallback. macOS Option+letter combinations produce non-ASCII letters as\n    // event.key (e.g., Option+A → 'å', Option+' → 'æ', Option+P → 'π'), but\n    // event.code still reflects the physical key. We want Alt+A to match even\n    // when Option+A fires event.key='å'.\n    if (\n      isSingleLetterKey(eventKey) &&\n      (/^[A-Za-z]$/.test(eventKey) || !event.altKey)\n    ) {\n      return false\n    }\n  }\n\n  // Fallback to event.code for dead keys or single-char mismatches where\n  // event.key is a non-letter special character.\n  // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'\n  // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'\n  if (\n    event.code &&\n    (eventKey === 'Dead' || (eventKey.length === 1 && hotkeyKey.length === 1))\n  ) {\n    // fallback for letter keys (common with mac option + letter)\n    if (event.code.startsWith('Key')) {\n      const codeLetter = event.code.slice(3)\n      if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) {\n        return codeLetter.toUpperCase() === hotkeyKey.toUpperCase()\n      }\n    }\n\n    // fallback for number keys (common with mac option + num)\n    if (event.code.startsWith('Digit')) {\n      const codeDigit = event.code.slice(5)\n      if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) {\n        return codeDigit === hotkeyKey\n      }\n    }\n    // Fallback for punctuation keys (e.g., Minus, Slash, BracketLeft).\n    // On macOS, Option+punctuation produces composed characters (e.g., Option+- → '–'),\n    // but event.code still reports the physical key.\n    if (event.code in PUNCTUATION_CODE_MAP) {\n      return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey\n    }\n\n    return false\n  }\n\n  // For special keys, compare exactly (after normalization)\n  return eventKey === hotkeyKey\n}\n\n/**\n * Options for creating a hotkey handler.\n */\nexport interface CreateHotkeyHandlerOptions {\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n}\n\n/**\n * Creates a keyboard event handler that calls the callback when the hotkey matches.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n *   console.log(`${hotkey} was pressed`)\n *   handleSave()\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createHotkeyHandler(\n  hotkey: Hotkey | ParsedHotkey,\n  callback: HotkeyCallback,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n  const context: HotkeyCallbackContext = {\n    hotkey: hotkeyString,\n    parsedHotkey: parsed,\n  }\n\n  return (event: KeyboardEvent) => {\n    if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n      if (preventDefault) {\n        event.preventDefault()\n      }\n      if (stopPropagation) {\n        event.stopPropagation()\n      }\n      callback(event, context)\n    }\n  }\n}\n\ntype MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/**\n * Creates a handler that matches multiple hotkeys.\n *\n * @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n *   'Mod+S': (event, { hotkey }) => handleSave(),\n *   'Mod+Z': (event, { hotkey }) => handleUndo(),\n *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createMultiHotkeyHandler(\n  handlers: MultiHotkeyHandler,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  // Pre-parse all hotkeys for efficiency\n  const parsedHandlers = Object.entries(handlers)\n    .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n    .map(([hotkey, handler]) => {\n      const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n      const context: HotkeyCallbackContext = {\n        hotkey: hotkey as Hotkey,\n        parsedHotkey: parsed,\n      }\n      return { parsed, handler, context }\n    })\n\n  return (event: KeyboardEvent) => {\n    for (const { parsed, handler, context } of parsedHandlers) {\n      if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n        if (preventDefault) {\n          event.preventDefault()\n        }\n        if (stopPropagation) {\n          event.stopPropagation()\n        }\n        handler(event, context)\n        return // Only handle the first match\n      }\n    }\n  }\n}\n\n/**\n * Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n  const parts: Array<string> = []\n\n  if (parsed.ctrl) parts.push('Control')\n  if (parsed.alt) parts.push('Alt')\n  if (parsed.shift) parts.push('Shift')\n  if (parsed.meta) parts.push('Meta')\n  parts.push(parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n"],"mappings":"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"}
+{"version":3,"file":"match.js","names":[],"sources":["../src/match.ts"],"sourcesContent":["import { matchKeyboardEvent } from './_match'\nimport { parseHotkey, parseRegisterableHotkey } from './parse'\nimport { detectPlatform } from './platform'\nimport { keysEqual } from './_keyboard-event'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  ParsedHotkey,\n  RegisterableHotkey,\n} from './hotkey.types'\n\nexport interface KeyboardEventMatch {\n  matched: boolean\n  score: 0 | 1 | 2 | 3\n  source?: 'key' | 'code' | 'fallback'\n  identity?: { key: string; code: string }\n}\n\n/**\n * Checks if a KeyboardEvent matches a hotkey.\n *\n * Physical bindings such as `Mod+[KeyS]` match `event.code` exactly.\n * Logical bindings use `event.key`, with a fallback to `code`\n * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special\n * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).\n * Letter keys are matched case-insensitively.\n *\n * Also handles \"dead key\" events where `event.key` is `'Dead'` instead of the expected\n * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,\n * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.\n * In these cases, `event.code` is used to determine the physical key.\n *\n * @param event - The KeyboardEvent to check\n * @param hotkey - The hotkey string or ParsedHotkey to match against\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns True if the event matches the hotkey\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (matchesKeyboardEvent(event, 'Mod+S')) {\n *     event.preventDefault()\n *     handleSave()\n *   }\n * })\n * ```\n */\nexport function matchesKeyboardEvent(\n  event: KeyboardEvent,\n  hotkey: Hotkey | ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  return matchKeyboardEvent(event, hotkey, platform).matched\n}\n\n/**\n * Options for creating a hotkey handler.\n */\nexport interface CreateHotkeyHandlerOptions {\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n}\n\n/**\n * Creates a keyboard event handler that calls the callback when the hotkey matches.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to match\n * @param callback - The function to call when the hotkey matches\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createHotkeyHandler('Mod+S', (event, { hotkey, parsedHotkey }) => {\n *   console.log(`${hotkey} was pressed`)\n *   handleSave()\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createHotkeyHandler(\n  hotkey: Hotkey | ParsedHotkey,\n  callback: HotkeyCallback,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string' ? hotkey : formatParsedHotkey(hotkey)\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, resolvedPlatform) : hotkey\n\n  const context: HotkeyCallbackContext = {\n    hotkey: hotkeyString,\n    parsedHotkey: parsed,\n  }\n\n  return (event: KeyboardEvent) => {\n    if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n      if (preventDefault) {\n        event.preventDefault()\n      }\n      if (stopPropagation) {\n        event.stopPropagation()\n      }\n      callback(event, context)\n    }\n  }\n}\n\nexport type MultiHotkeyHandler = { [K in Hotkey]?: HotkeyCallback }\n\n/**\n * Creates a handler that matches multiple hotkeys.\n *\n * @param handlers - A map of hotkey strings to their handlers\n * @param options - Options for matching and handling\n * @returns A function that can be used as an event handler\n *\n * @example\n * ```ts\n * const handler = createMultiHotkeyHandler({\n *   'Mod+S': (event, { hotkey }) => handleSave(),\n *   'Mod+Z': (event, { hotkey }) => handleUndo(),\n *   'Mod+Shift+Z': (event, { hotkey }) => handleRedo(),\n * })\n *\n * document.addEventListener('keydown', handler)\n * ```\n */\nexport function createMultiHotkeyHandler(\n  handlers: MultiHotkeyHandler,\n  options: CreateHotkeyHandlerOptions = {},\n): (event: KeyboardEvent) => void {\n  const { preventDefault = true, stopPropagation = true, platform } = options\n  const resolvedPlatform = platform ?? detectPlatform()\n\n  // Pre-parse all hotkeys for efficiency\n  const parsedHandlers = Object.entries(handlers)\n    .filter((entry): entry is [string, HotkeyCallback] => Boolean(entry[1]))\n    .map(([hotkey, handler]) => {\n      const parsed = parseHotkey(hotkey as Hotkey, resolvedPlatform)\n      const context: HotkeyCallbackContext = {\n        hotkey: hotkey as Hotkey,\n        parsedHotkey: parsed,\n      }\n      return { parsed, handler, context }\n    })\n\n  return (event: KeyboardEvent) => {\n    for (const { parsed, handler, context } of parsedHandlers) {\n      if (matchesKeyboardEvent(event, parsed, resolvedPlatform)) {\n        if (preventDefault) {\n          event.preventDefault()\n        }\n        if (stopPropagation) {\n          event.stopPropagation()\n        }\n        handler(event, context)\n        return // Only handle the first match\n      }\n    }\n  }\n}\n\n/**\n * Formats a ParsedHotkey back to a hotkey string.\n * Used internally to provide the hotkey string in callback context.\n */\nfunction formatParsedHotkey(parsed: ParsedHotkey): Hotkey {\n  const parts: Array<string> = []\n\n  if (parsed.ctrl) parts.push('Control')\n  if (parsed.alt) parts.push('Alt')\n  if (parsed.shift) parts.push('Shift')\n  if (parsed.meta) parts.push('Meta')\n  parts.push(parsed.code !== undefined ? `[${parsed.code}]` : parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n\n/**\n * Compares normalized binding identity, including all four modifiers.\n * Aliases resolve on the supplied platform. A physical code and a logical key\n * remain distinct even when one keyboard event could match both.\n */\nexport function areHotkeysEqual(\n  left: RegisterableHotkey,\n  right: RegisterableHotkey,\n  platform = detectPlatform(),\n): boolean {\n  const a = parseRegisterableHotkey(left, platform)\n  const b = parseRegisterableHotkey(right, platform)\n  return (\n    a.ctrl === b.ctrl &&\n    a.alt === b.alt &&\n    a.shift === b.shift &&\n    a.meta === b.meta &&\n    (a.code !== undefined || b.code !== undefined\n      ? a.code === b.code\n      : keysEqual(a.key, b.key))\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,qBACd,OACA,QACA,WAAwC,gBAAgB,EAC/C;AACT,QAAO,mBAAmB,OAAO,QAAQ,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;AAiCrD,SAAgB,oBACd,QACA,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAY,gBAAgB;CAErD,MAAM,eACJ,OAAO,WAAW,WAAW,SAAS,mBAAmB,OAAO;CAClE,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,iBAAiB,GAAG;CAEvE,MAAM,UAAiC;EACrC,QAAQ;EACR,cAAc;EACf;AAED,SAAQ,UAAyB;AAC/B,MAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,YAAS,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;AAyB9B,SAAgB,yBACd,UACA,UAAsC,EAAE,EACR;CAChC,MAAM,EAAE,iBAAiB,MAAM,kBAAkB,MAAM,aAAa;CACpE,MAAM,mBAAmB,YAAY,gBAAgB;CAGrD,MAAM,iBAAiB,OAAO,QAAQ,SAAS,CAC5C,QAAQ,UAA6C,QAAQ,MAAM,GAAG,CAAC,CACvE,KAAK,CAAC,QAAQ,aAAa;EAC1B,MAAM,SAAS,YAAY,QAAkB,iBAAiB;AAK9D,SAAO;GAAE;GAAQ;GAAS,SAJa;IAC7B;IACR,cAAc;IACf;GACkC;GACnC;AAEJ,SAAQ,UAAyB;AAC/B,OAAK,MAAM,EAAE,QAAQ,SAAS,aAAa,eACzC,KAAI,qBAAqB,OAAO,QAAQ,iBAAiB,EAAE;AACzD,OAAI,eACF,OAAM,gBAAgB;AAExB,OAAI,gBACF,OAAM,iBAAiB;AAEzB,WAAQ,OAAO,QAAQ;AACvB;;;;;;;;AAUR,SAAS,mBAAmB,QAA8B;CACxD,MAAM,QAAuB,EAAE;AAE/B,KAAI,OAAO,KAAM,OAAM,KAAK,UAAU;AACtC,KAAI,OAAO,IAAK,OAAM,KAAK,MAAM;AACjC,KAAI,OAAO,MAAO,OAAM,KAAK,QAAQ;AACrC,KAAI,OAAO,KAAM,OAAM,KAAK,OAAO;AACnC,OAAM,KAAK,OAAO,SAAS,SAAY,IAAI,OAAO,KAAK,KAAK,OAAO,IAAI;AAEvE,QAAO,MAAM,KAAK,IAAI;;;;;;;AAQxB,SAAgB,gBACd,MACA,OACA,WAAW,gBAAgB,EAClB;CACT,MAAM,IAAI,wBAAwB,MAAM,SAAS;CACjD,MAAM,IAAI,wBAAwB,OAAO,SAAS;AAClD,QACE,EAAE,SAAS,EAAE,QACb,EAAE,QAAQ,EAAE,OACZ,EAAE,UAAU,EAAE,SACd,EAAE,SAAS,EAAE,SACZ,EAAE,SAAS,UAAa,EAAE,SAAS,SAChC,EAAE,SAAS,EAAE,OACb,UAAU,EAAE,KAAK,EAAE,IAAI"}

package/dist/parse.cjs

@@ -1,4 +1,6 @@
 const require_constants = require('./constants.cjs');
+const require_platform = require('./platform.cjs');
+const require__keyboard_event = require('./_keyboard-event.cjs');
 
 //#region src/parse.ts
 /**
@@ -6,7 +8,7 @@ const require_constants = require('./constants.cjs');
 *
 * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
 * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
-* @returns A ParsedHotkey object with the key and modifier flags
+* @returns A ParsedHotkey with either logical key or physical code and modifier flags
 *
 * @example
 * ```ts
@@ -15,8 +17,8 @@ const require_constants = require('./constants.cjs');
 * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
 * ```
 */
-function parseHotkey(hotkey, platform = require_constants.detectPlatform()) {
-	const parts = hotkey.split("+");
+function parseHotkey(hotkey, platform = require_platform.detectPlatform()) {
+	const parts = require__keyboard_event.splitHotkeyParts(hotkey);
 	const modifiers = /* @__PURE__ */ new Set();
 	let key = "";
 	for (let i = 0; i < parts.length; i++) {
@@ -25,14 +27,15 @@ function parseHotkey(hotkey, platform = require_constants.detectPlatform()) {
 		else {
 			const alias = require_constants.MODIFIER_ALIASES[part] ?? require_constants.MODIFIER_ALIASES[part.toLowerCase()];
 			if (alias) {
-				const resolved = require_constants.resolveModifier(alias, platform);
+				const resolved = require_platform.resolveModifier(alias, platform);
 				modifiers.add(resolved);
 			} else if (parts.length === 1) key = require_constants.normalizeKeyName(part);
 		}
 	}
 	if (!key && parts.length > 0) key = require_constants.normalizeKeyName(parts[parts.length - 1].trim());
+	const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(key)?.[1];
 	return {
-		key,
+		...code !== void 0 ? { code } : { key },
 		ctrl: modifiers.has("Control"),
 		shift: modifiers.has("Shift"),
 		alt: modifiers.has("Alt"),
@@ -61,12 +64,13 @@ function parseHotkey(hotkey, platform = require_constants.detectPlatform()) {
 * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
 * ```
 */
-function rawHotkeyToParsedHotkey(raw, platform = require_constants.detectPlatform()) {
+function rawHotkeyToParsedHotkey(raw, platform = require_platform.detectPlatform()) {
+	if (raw.code === void 0) require__keyboard_event.assertLogicalKey(raw.key);
 	let ctrl = raw.ctrl ?? false;
 	const shift = raw.shift ?? false;
 	const alt = raw.alt ?? false;
 	let meta = raw.meta ?? false;
-	if (raw.mod) if (require_constants.resolveModifier("Mod", platform) === "Control") ctrl = true;
+	if (raw.mod) if (require_platform.resolveModifier("Mod", platform) === "Control") ctrl = true;
 	else meta = true;
 	const modifiers = require_constants.MODIFIER_ORDER.filter((m) => {
 		switch (m) {
@@ -78,7 +82,7 @@ function rawHotkeyToParsedHotkey(raw, platform = require_constants.detectPlatfor
 		}
 	});
 	return {
-		key: raw.key,
+		...raw.code !== void 0 ? { code: raw.code } : { key: require_constants.normalizeKeyName(raw.key) },
 		ctrl,
 		shift,
 		alt,
@@ -92,6 +96,7 @@ function rawHotkeyToParsedHotkey(raw, platform = require_constants.detectPlatfor
 * otherwise full `Control+Alt+Shift+Meta` order.
 */
 function normalizedHotkeyStringFromParsed(parsed, platform) {
+	if (parsed.code === void 0) require__keyboard_event.assertLogicalKey(parsed.key);
 	const canUseMod = platform === "mac" ? parsed.meta && !parsed.ctrl : parsed.ctrl && !parsed.meta;
 	const parts = [];
 	if (canUseMod) {
@@ -99,7 +104,7 @@ function normalizedHotkeyStringFromParsed(parsed, platform) {
 		if (parsed.alt) parts.push("Alt");
 		if (parsed.shift) parts.push("Shift");
 	} else for (const modifier of require_constants.MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
-	parts.push(require_constants.normalizeKeyName(parsed.key));
+	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : require_constants.normalizeKeyName(parsed.key));
 	return parts.join("+");
 }
 /**
@@ -122,20 +127,20 @@ function normalizedHotkeyStringFromParsed(parsed, platform) {
 * normalizeHotkey('esc') // 'Escape'
 * ```
 */
-function normalizeHotkey(hotkey, platform = require_constants.detectPlatform()) {
+function normalizeHotkey(hotkey, platform = require_platform.detectPlatform()) {
 	return normalizedHotkeyStringFromParsed(parseHotkey(hotkey, platform), platform);
 }
 /**
 * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
 */
-function normalizeHotkeyFromParsed(parsed, platform = require_constants.detectPlatform()) {
+function normalizeHotkeyFromParsed(parsed, platform = require_platform.detectPlatform()) {
 	return normalizedHotkeyStringFromParsed(parsed, platform);
 }
 /**
 * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
 * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
 */
-function normalizeRegisterableHotkey(hotkey, platform = require_constants.detectPlatform()) {
+function normalizeRegisterableHotkey(hotkey, platform = require_platform.detectPlatform()) {
 	return typeof hotkey === "string" ? normalizeHotkey(hotkey, platform) : normalizeHotkeyFromParsed(rawHotkeyToParsedHotkey(hotkey, platform), platform);
 }
 /**
@@ -168,19 +173,22 @@ function isModifierKey(key) {
 * })
 * ```
 */
-function parseKeyboardEvent(event) {
-	const normalizedKey = require_constants.normalizeKeyName(event.key);
+function parseKeyboardEvent(event, platform) {
+	const normalized = require__keyboard_event.normalizeKeyboardEvent(event, platform);
+	const ctrl = normalized.altGraph ? false : normalized.ctrl;
+	const alt = normalized.altGraph ? false : normalized.alt;
+	const shift = normalized.shift;
 	const modifiers = [];
-	if (event.ctrlKey) modifiers.push("Control");
-	if (event.altKey) modifiers.push("Alt");
-	if (event.shiftKey) modifiers.push("Shift");
-	if (event.metaKey) modifiers.push("Meta");
+	if (ctrl) modifiers.push("Control");
+	if (alt) modifiers.push("Alt");
+	if (shift) modifiers.push("Shift");
+	if (normalized.meta) modifiers.push("Meta");
 	return {
-		key: normalizedKey,
-		ctrl: event.ctrlKey,
-		shift: event.shiftKey,
-		alt: event.altKey,
-		meta: event.metaKey,
+		key: normalized.key,
+		ctrl,
+		shift,
+		alt,
+		meta: normalized.meta,
 		modifiers
 	};
 }
@@ -190,8 +198,8 @@ function parseKeyboardEvent(event) {
 * @param event - The keyboard event (typically `keydown`)
 * @param platform - Target platform for `Mod` eligibility
 */
-function normalizeHotkeyFromEvent(event, platform = require_constants.detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform);
+function normalizeHotkeyFromEvent(event, platform = require_platform.detectPlatform()) {
+	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event, platform), platform);
 }
 /**
 * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
@@ -210,10 +218,18 @@ function normalizeHotkeyFromEvent(event, platform = require_constants.detectPlat
 * hasNonModifierKey(parseHotkey('Mod+A')) // true
 * ```
 */
-function hasNonModifierKey(hotkey, platform = require_constants.detectPlatform()) {
+function hasNonModifierKey(hotkey, platform = require_platform.detectPlatform()) {
 	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
+	if (parsed.code !== void 0) return parsed.code.length > 0 && !/^(Control|Shift|Alt|Meta)(Left|Right)$/.test(parsed.code);
 	return !isModifierKey(parsed.key) && parsed.key.length > 0;
 }
+/**
+* Parses a string or raw binding, resolving Mod for the supplied platform.
+* Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
+*/
+function parseRegisterableHotkey(hotkey, platform = require_platform.detectPlatform()) {
+	return typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
+}
 
 //#endregion
 exports.hasNonModifierKey = hasNonModifierKey;
@@ -224,5 +240,6 @@ exports.normalizeHotkeyFromParsed = normalizeHotkeyFromParsed;
 exports.normalizeRegisterableHotkey = normalizeRegisterableHotkey;
 exports.parseHotkey = parseHotkey;
 exports.parseKeyboardEvent = parseKeyboardEvent;
+exports.parseRegisterableHotkey = parseRegisterableHotkey;
 exports.rawHotkeyToParsedHotkey = rawHotkeyToParsedHotkey;
 //# sourceMappingURL=parse.cjs.map