@tanstack/hotkeys 0.8.0 → 0.10.0

package/dist/display-labels.js

@@ -0,0 +1,112 @@
+//#region src/display-labels.ts
+/**
+* Modifier key symbols for macOS display.
+*
+* Used by formatting functions to display hotkeys with macOS-style symbols
+* (e.g., ⌘ for Command, ⌃ for Control) instead of text labels. This provides
+* a native macOS look and feel in hotkey displays.
+*
+* @example
+* ```ts
+* MAC_MODIFIER_SYMBOLS['Meta'] // '⌘'
+* MAC_MODIFIER_SYMBOLS['Control'] // '⌃'
+* MAC_MODIFIER_SYMBOLS['Alt'] // '⌥'
+* MAC_MODIFIER_SYMBOLS['Shift'] // '⇧'
+* ```
+*/
+const MAC_MODIFIER_SYMBOLS = {
+	Control: "⌃",
+	Alt: "⌥",
+	Shift: "⇧",
+	Meta: "⌘",
+	Mod: "⌘"
+};
+/**
+* Modifier key labels for macOS display.
+*
+* Used by formatting functions to display hotkeys with macOS-style text labels
+* (e.g., 'Control' for Control, 'Option' for Alt, 'Cmd' for Meta) instead of symbols.
+* This provides a familiar macOS look and feel in hotkey displays.
+*
+* @example
+* ```ts
+* MAC_MODIFIER_LABELS['Control'] // 'control'
+* MAC_MODIFIER_LABELS['Alt'] // 'option'
+* MAC_MODIFIER_LABELS['Shift'] // 'shift'
+* MAC_MODIFIER_LABELS['Meta'] // 'cmd'
+* ```
+*/
+const MAC_MODIFIER_LABELS = {
+	Control: "Control",
+	Alt: "Option",
+	Shift: "Shift",
+	Meta: "Cmd",
+	Mod: "Cmd"
+};
+/**
+* Modifier key labels for Windows/Linux display.
+*
+* Used by formatting functions to display hotkeys with standard text labels
+* (e.g., 'Ctrl' for Control, 'Win' for Meta/Windows key) instead of symbols.
+* This provides a familiar Windows/Linux look and feel in hotkey displays.
+*
+* @example
+* ```ts
+* STANDARD_MODIFIER_LABELS['Control'] // 'Ctrl'
+* STANDARD_MODIFIER_LABELS['Meta'] // 'Win'
+* STANDARD_MODIFIER_LABELS['Alt'] // 'Alt'
+* STANDARD_MODIFIER_LABELS['Shift'] // 'Shift'
+* ```
+*/
+const WINDOWS_MODIFIER_LABELS = {
+	Control: "Ctrl",
+	Alt: "Alt",
+	Shift: "Shift",
+	Meta: "Win",
+	Mod: "Ctrl"
+};
+const LINUX_MODIFIER_LABELS = {
+	...WINDOWS_MODIFIER_LABELS,
+	Meta: "Super"
+};
+const PUNCTUATION_KEY_DISPLAY_LABELS = {
+	"`": "Backquote",
+	"\\": "Backslash",
+	"[": "Left Bracket",
+	"]": "Right Bracket",
+	",": "Comma",
+	"=": "Equal",
+	"-": "Minus",
+	".": "Period",
+	";": "Semicolon"
+};
+/**
+* Special key symbols for display formatting.
+*
+* Maps certain keys to their visual symbols for better readability in hotkey displays.
+* Used by formatting functions to show symbols like ↑ for ArrowUp or ↵ for Enter
+* instead of text labels.
+*
+* @example
+* ```ts
+* KEY_DISPLAY_SYMBOLS['ArrowUp'] // '↑'
+* KEY_DISPLAY_SYMBOLS['Enter'] // '↵'
+* KEY_DISPLAY_SYMBOLS['Escape'] // 'Esc'
+* KEY_DISPLAY_SYMBOLS['Space'] // '␣'
+* ```
+*/
+const KEY_DISPLAY_SYMBOLS = {
+	ArrowUp: "↑",
+	ArrowDown: "↓",
+	ArrowLeft: "←",
+	ArrowRight: "→",
+	Enter: "↵",
+	Escape: "Esc",
+	Backspace: "⌫",
+	Delete: "⌦",
+	Tab: "⇥",
+	Space: "␣"
+};
+
+//#endregion
+export { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS };

package/dist/format.d.ts

@@ -1,8 +1,8 @@
-import { FormatDisplayOptions, Hotkey, ParsedHotkey, RegisterableHotkey } from "./hotkey.js";
-
+import { Hotkey, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
 //#region src/format.d.ts
 /**
- * Converts a hotkey sequence array to a display string.
+ * Joins stored sequence steps with spaces, preserving physical code tokens.
+ * For user-facing labels, call formatForDisplay on each step instead.
  *
  * @param sequence - Array of hotkey strings that form the sequence
  * @returns A space-separated string (e.g. ['G','G'] → 'G G')
@@ -13,7 +13,7 @@ import { FormatDisplayOptions, Hotkey, ParsedHotkey, RegisterableHotkey } from "
  * formatHotkeySequence(['D', 'I', 'W']) // 'D I W'
  * ```
  */
-declare function formatHotkeySequence(sequence: Array<Hotkey>): string;
+export declare function formatHotkeySequence(sequence: Array<Hotkey>): string;
 /**
  * Converts a ParsedHotkey back to a hotkey string.
  *
@@ -26,17 +26,22 @@ declare function formatHotkeySequence(sequence: Array<Hotkey>): string;
  * // Returns: 'Control+Shift+S'
  * ```
  */
-declare function formatHotkey(parsed: ParsedHotkey): string;
+export declare function formatHotkey(parsed: ParsedHotkey): string;
+export type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {});
 /**
  * Formats a hotkey for display in a user interface.
  *
  * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
  * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
  * The separator can be customized with `separatorToken`.
+ * Physical codes use conventional display labels: `[KeyS]` becomes `S` and
+ * `[Digit2]` becomes `2`. These labels do not infer the active keyboard layout
+ * or change matching. Supply a resolved `layoutMap` for layout-aware labels;
+ * `keyLabels` overrides both layout entries and fallback labels.
  *
- * @param hotkey - The hotkey string or ParsedHotkey to format
+ * @param hotkey - A logical or physical string, raw binding, or ParsedHotkey
  * @param options - Formatting options
- * @returns A formatted string suitable for display
+ * @returns Display text, or individual key labels when parts is true
  *
  * @example
  * ```ts
@@ -50,11 +55,42 @@ declare function formatHotkey(parsed: ParsedHotkey): string;
  * // Returns: 'Esc' (on all platforms)
  * ```
  */
-declare function formatForDisplay(hotkey: RegisterableHotkey | (string & {}), options?: FormatDisplayOptions): string;
+export declare function formatForDisplay(hotkey: DisplayHotkey, options: FormatDisplayOptions & {
+  parts: true;
+}): Array<string>;
+export declare function formatForDisplay(hotkey: DisplayHotkey, options?: FormatDisplayOptions & {
+  parts?: false;
+}): string;
+export declare function formatForDisplay(hotkey: DisplayHotkey, options: FormatDisplayOptions): string | Array<string>;
 /**
  * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
  */
-declare function formatWithLabels(hotkey: RegisterableHotkey, options?: Omit<FormatDisplayOptions, 'useSymbols'>): string;
-//#endregion
-export { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels };
-//# sourceMappingURL=format.d.ts.map
+export declare function formatWithLabels(hotkey: RegisterableHotkey, options?: Omit<FormatDisplayOptions, 'useSymbols' | 'parts'>): string;
+/**
+ * Options for formatting hotkeys for display.
+ */
+export interface FormatDisplayOptions {
+  /** The target platform. Defaults to auto-detection. */
+  platform?: 'mac' | 'windows' | 'linux';
+  /** Whether to use symbols for the display. Defaults to true. */
+  useSymbols?: boolean | {
+    modifiers?: boolean;
+    keys?: boolean;
+  };
+  /** Return individual key labels instead of a joined string. Default: false. */
+  parts?: boolean;
+  /**
+   * An already-resolved code-to-key map, such as KeyboardLayoutMap or Map.
+   * Used only for physical bindings. Mapped keys receive normal display formatting;
+   * missing or empty entries use conventional fallback labels. The caller owns
+   * loading and refreshing the map; this formatter never calls browser APIs.
+   */
+  layoutMap?: {
+    get: (code: string) => string | undefined;
+  };
+  /** Final display overrides for logical keys or physical codes; take precedence over layoutMap. Never changes matching. */
+  keyLabels?: Readonly<Record<string, string>>;
+  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
+  separatorToken?: string | null;
+}
+//#endregion

package/dist/format.js

@@ -1,9 +1,13 @@
-import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_ORDER, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, detectPlatform } from "./constants.js";
-import { isModifierKey, normalizeRegisterableHotkey } from "./parse.js";
+import { MODIFIER_ALIASES, MODIFIER_ORDER, PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
+import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
+import { detectPlatform } from "./platform.js";
+import { assertLogicalKey, splitHotkeyParts } from "./_keyboard-event.js";
+import { isModifierKey, normalizeHotkeyFromParsed, normalizeRegisterableHotkey } from "./parse.js";
 
 //#region src/format.ts
 /**
-* Converts a hotkey sequence array to a display string.
+* Joins stored sequence steps with spaces, preserving physical code tokens.
+* For user-facing labels, call formatForDisplay on each step instead.
 *
 * @param sequence - Array of hotkey strings that form the sequence
 * @returns A space-separated string (e.g. ['G','G'] → 'G G')
@@ -30,48 +34,41 @@ function formatHotkeySequence(sequence) {
 * ```
 */
 function formatHotkey(parsed) {
+	if (parsed.code === void 0) assertLogicalKey(parsed.key);
 	const parts = [];
 	for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
-	parts.push(parsed.key);
+	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : parsed.key);
 	return parts.join("+");
 }
-/**
-* Formats a hotkey for display in a user interface.
-*
-* On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
-* On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
-* The separator can be customized with `separatorToken`.
-*
-* @param hotkey - The hotkey string or ParsedHotkey to format
-* @param options - Formatting options
-* @returns A formatted string suitable for display
-*
-* @example
-* ```ts
-* formatForDisplay('Mod+Shift+S', { platform: 'mac' })
-* // Returns: '⌘ ⇧ S' (symbols separated by spaces on macOS)
-*
-* formatForDisplay('Mod+Shift+S', { platform: 'windows' })
-* // Returns: 'Ctrl+Shift+S'
-*
-* formatForDisplay('Escape')
-* // Returns: 'Esc' (on all platforms)
-* ```
-*/
 function formatForDisplay(hotkey, options = {}) {
 	const platform = options.platform ?? detectPlatform();
-	const useSymbols = options.useSymbols ?? true;
-	const separatorToken = options.separatorToken ?? (platform === "mac" && useSymbols ? " " : "+");
-	return normalizeRegisterableHotkey(hotkey, platform).split("+").map((segment) => {
+	const symbols = options.useSymbols ?? true;
+	const modifierSymbols = typeof symbols === "boolean" ? symbols : symbols.modifiers ?? true;
+	const keySymbols = typeof symbols === "boolean" ? symbols : symbols.keys ?? true;
+	const separator = options.separatorToken ?? (platform === "mac" && modifierSymbols ? " " : "+");
+	const normalized = typeof hotkey === "object" && "modifiers" in hotkey ? normalizeHotkeyFromParsed(hotkey, platform) : normalizeRegisterableHotkey(hotkey, platform);
+	const parts = splitHotkeyParts(normalized).map((segment) => {
 		if (isModifierKey(segment)) {
-			const modifierToken = MODIFIER_ALIASES[segment] ?? MODIFIER_ALIASES[segment.toLowerCase()];
-			return platform === "mac" ? useSymbols ? MAC_MODIFIER_SYMBOLS[modifierToken] : MAC_MODIFIER_LABELS[modifierToken] : platform === "windows" ? WINDOWS_MODIFIER_LABELS[modifierToken] : LINUX_MODIFIER_LABELS[modifierToken];
-		} else {
-			const keyDisplaySymbol = useSymbols && KEY_DISPLAY_SYMBOLS[segment];
-			if (keyDisplaySymbol) return keyDisplaySymbol;
-			return !useSymbols && PUNCTUATION_KEY_DISPLAY_LABELS[segment] || segment;
+			const modifier = MODIFIER_ALIASES[segment] ?? MODIFIER_ALIASES[segment.toLowerCase()];
+			return platform === "mac" ? modifierSymbols ? MAC_MODIFIER_SYMBOLS[modifier] : MAC_MODIFIER_LABELS[modifier] : platform === "windows" ? WINDOWS_MODIFIER_LABELS[modifier] : LINUX_MODIFIER_LABELS[modifier];
+		}
+		const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(segment)?.[1];
+		const label = options.keyLabels?.[code ?? segment];
+		if (label !== void 0) return label;
+		const numpad = code?.startsWith("Numpad") ?? false;
+		let displayKey = code ?? segment;
+		const mappedKey = code ? options.layoutMap?.get(code) : void 0;
+		if (mappedKey) displayKey = normalizeKeyName(mappedKey);
+		else if (code) {
+			if (/^Key[A-Z]$/.test(code)) displayKey = code.slice(3);
+			else if (/^Digit[0-9]$/.test(code)) displayKey = code.slice(5);
+			else if (numpad) displayKey = code.slice(6);
+			else displayKey = PUNCTUATION_CODE_MAP[code] ?? code;
 		}
-	}).join(separatorToken);
+		const display = (keySymbols ? KEY_DISPLAY_SYMBOLS : PUNCTUATION_KEY_DISPLAY_LABELS)[displayKey] ?? displayKey;
+		return numpad ? `Numpad ${display.replace(/([a-z])([A-Z])/g, "$1 $2")}` : display;
+	});
+	return options.parts ? parts : parts.join(separator);
 }
 /**
 * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
@@ -84,5 +81,4 @@ function formatWithLabels(hotkey, options = {}) {
 }
 
 //#endregion
-export { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels };
-//# sourceMappingURL=format.js.map
+export { formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels };

package/dist/hint.d.ts

@@ -0,0 +1,20 @@
+import { RegisterableHotkey } from "./hotkey.types.js";
+//#region src/hint.d.ts
+export interface HeldModifierOptions {
+  /** Resolve Mod for this platform. Defaults to platform detection. */
+  platform?: 'mac' | 'windows' | 'linux';
+  /** Require every binding modifier to be held. Default: false (nonempty subset). */
+  exact?: boolean;
+}
+/**
+ * Returns whether held modifiers should reveal a shortcut hint.
+ * By default, any nonempty subset of the binding's modifiers qualifies; an
+ * unrelated modifier hides the hint. `exact` requires every binding modifier.
+ * Nonmodifier keys are ignored. This does not check registration or focus.
+ *
+ * @example
+ * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true
+ * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt', 'Control']) // false
+ */
+export declare function matchesHeldModifiers(hotkey: RegisterableHotkey, heldKeys: ReadonlyArray<string>, options?: HeldModifierOptions): boolean;
+//#endregion

package/dist/hint.js

@@ -0,0 +1,23 @@
+import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
+import { parseRegisterableHotkey } from "./parse.js";
+
+//#region src/hint.ts
+/**
+* Returns whether held modifiers should reveal a shortcut hint.
+* By default, any nonempty subset of the binding's modifiers qualifies; an
+* unrelated modifier hides the hint. `exact` requires every binding modifier.
+* Nonmodifier keys are ignored. This does not check registration or focus.
+*
+* @example
+* matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true
+* matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt', 'Control']) // false
+*/
+function matchesHeldModifiers(hotkey, heldKeys, options = {}) {
+	if (heldKeys.includes("AltGraph")) return false;
+	const held = [...new Set(heldKeys.map(normalizeKeyName).filter((key) => MODIFIER_KEYS.has(key)))];
+	const { modifiers } = parseRegisterableHotkey(hotkey, options.platform);
+	return held.length > 0 && held.every((key) => modifiers.includes(key)) && (!options.exact || held.length === modifiers.length);
+}
+
+//#endregion
+export { matchesHeldModifiers };

package/dist/hotkey-manager.d.ts

@@ -1,12 +1,10 @@
-import { Hotkey, HotkeyCallback, HotkeyMeta, ParsedHotkey, RegisterableHotkey } from "./hotkey.js";
-import { ConflictBehavior } from "./manager.utils.js";
+import { ConflictBehavior, Hotkey, HotkeyCallback, HotkeyMeta, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
 import { Store } from "@tanstack/store";
-
 //#region src/hotkey-manager.d.ts
 /**
  * Options for registering a hotkey.
  */
-interface HotkeyOptions {
+export interface HotkeyOptions {
   /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */
   conflictBehavior?: ConflictBehavior;
   /**
@@ -35,11 +33,16 @@ interface HotkeyOptions {
 /**
  * A registered hotkey handler in the HotkeyManager.
  */
-interface HotkeyRegistration {
+export interface HotkeyRegistration {
   /** The callback to invoke */
   callback: HotkeyCallback;
   /** Whether this registration has fired and needs reset (for requireReset) */
   hasFired: boolean;
+  /** The concrete key/code that activated a requireReset registration. */
+  activeMatch?: {
+    key: string;
+    code: string;
+  };
   /** The original hotkey string */
   hotkey: Hotkey;
   /** Unique identifier for this registration */
@@ -57,7 +60,7 @@ interface HotkeyRegistration {
  * Public view of a hotkey registration for display and introspection.
  * Omits the callback function which is an internal implementation detail.
  */
-interface HotkeyRegistrationView {
+export interface HotkeyRegistrationView {
   /** The original hotkey string */
   hotkey: Hotkey;
   /** Unique identifier for this registration */
@@ -77,7 +80,7 @@ interface HotkeyRegistrationView {
  * Creates a public view from an internal registration,
  * stripping the callback function.
  */
-declare function toHotkeyRegistrationView(reg: HotkeyRegistration): HotkeyRegistrationView;
+export declare function toHotkeyRegistrationView(reg: HotkeyRegistration): HotkeyRegistrationView;
 /**
  * A handle returned from HotkeyManager.register() that allows updating
  * the callback and options without re-registering the hotkey.
@@ -101,7 +104,7 @@ declare function toHotkeyRegistrationView(reg: HotkeyRegistration): HotkeyRegist
  * handle.unregister()
  * ```
  */
-interface HotkeyRegistrationHandle {
+export interface HotkeyRegistrationHandle {
   /**
    * The callback function. Can be set directly to update without re-registering.
    * This avoids stale closures when the callback references React state.
@@ -138,7 +141,7 @@ interface HotkeyRegistrationHandle {
  * unregister()
  * ```
  */
-declare class HotkeyManager {
+export declare class HotkeyManager {
   #private;
   /**
    * The TanStack Store containing all hotkey registrations.
@@ -224,7 +227,6 @@ declare class HotkeyManager {
  * Gets the singleton HotkeyManager instance.
  * Convenience function for accessing the manager.
  */
-declare function getHotkeyManager(): HotkeyManager;
+export declare function getHotkeyManager(): HotkeyManager;
 //#endregion
-export { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, getHotkeyManager, toHotkeyRegistrationView };
-//# sourceMappingURL=hotkey-manager.d.ts.map
+export type { ConflictBehavior };

package/dist/hotkey-manager.js

@@ -1,8 +1,12 @@
-import { detectPlatform, normalizeKeyName } from "./constants.js";
+import { normalizeKeyName } from "./constants.js";
+import { detectPlatform } from "./platform.js";
 import { parseHotkey, rawHotkeyToParsedHotkey } from "./parse.js";
 import { formatHotkey } from "./format.js";
-import { matchesKeyboardEvent } from "./match.js";
-import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, isEventForTarget, shouldIgnoreInputEvent } from "./manager.utils.js";
+import { matchKeyboardEvent } from "./_match.js";
+import { areHotkeysEqual } from "./match.js";
+import { isRecordingEvent } from "./_recording-guard.js";
+import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
+import { isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
@@ -49,11 +53,30 @@ function generateId() {
 */
 var HotkeyManager = class HotkeyManager {
 	static #instance = null;
+	/**
+	* The TanStack Store containing all hotkey registrations.
+	* Use this to subscribe to registration changes or access current registrations.
+	*
+	* @example
+	* ```ts
+	* const manager = HotkeyManager.getInstance()
+	*
+	* // Subscribe to registration changes
+	* const unsubscribe = manager.registrations.subscribe(() => {
+	*   console.log('Registrations changed:', manager.registrations.state.size)
+	* })
+	*
+	* // Access current registrations
+	* for (const [id, reg] of manager.registrations.state) {
+	*   console.log(reg.hotkey, reg.options.enabled)
+	* }
+	* ```
+	*/
+	registrations = new Store(/* @__PURE__ */ new Map());
 	#platform;
 	#targetListeners = /* @__PURE__ */ new Map();
 	#targetRegistrations = /* @__PURE__ */ new Map();
 	constructor() {
-		this.registrations = new Store(/* @__PURE__ */ new Map());
 		this.#platform = detectPlatform();
 	}
 	/**
@@ -162,7 +185,10 @@ var HotkeyManager = class HotkeyManager {
 			setOptions: (newOptions) => {
 				manager.registrations.setState((prev) => {
 					const reg = prev.get(id);
-					if (reg) {
+					if (reg && !optionsEqual(reg.options, {
+						...reg.options,
+						...newOptions
+					})) {
 						const next = new Map(prev);
 						next.set(id, {
 							...reg,
@@ -230,8 +256,27 @@ var HotkeyManager = class HotkeyManager {
 	* Processes keyboard events for a specific target and event type.
 	*/
 	#processTargetEvent(event, target, eventType) {
+		if (eventType === "keyup") for (const id of this.#targetRegistrations.get(target) ?? []) {
+			const registration = this.registrations.state.get(id);
+			if (registration?.hasFired && this.#shouldResetRegistration(registration, event)) {
+				registration.hasFired = false;
+				registration.activeMatch = void 0;
+			}
+		}
+		if (isRecordingEvent(event)) return;
 		const targetRegs = this.#targetRegistrations.get(target);
 		if (!targetRegs) return;
+		const matches = /* @__PURE__ */ new Map();
+		let bestScore = 0;
+		for (const id of targetRegs) {
+			const registration = this.registrations.state.get(id);
+			if (!registration || !registration.options.enabled || registration.options.eventType !== eventType || !isEventForTarget(event, target) || registration.options.ignoreInputs !== false && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			const result = matchKeyboardEvent(event, registration.parsedHotkey, registration.options.platform);
+			if (result.matched) {
+				matches.set(id, result);
+				bestScore = Math.max(bestScore, result.score);
+			}
+		}
 		for (const id of targetRegs) {
 			const registration = this.registrations.state.get(id);
 			if (!registration) continue;
@@ -242,21 +287,21 @@ var HotkeyManager = class HotkeyManager {
 			}
 			if (eventType === "keydown") {
 				if (registration.options.eventType !== "keydown") continue;
-				if (matchesKeyboardEvent(event, registration.parsedHotkey, registration.options.platform)) {
+				const match = matches.get(id);
+				if (match?.matched && match.score === bestScore) {
 					if (registration.options.preventDefault) event.preventDefault();
 					if (registration.options.stopPropagation) event.stopPropagation();
 					if (!registration.options.requireReset || !registration.hasFired) {
 						this.#executeHotkeyCallback(registration, event);
-						if (registration.options.requireReset) registration.hasFired = true;
+						if (registration.options.requireReset) {
+							registration.hasFired = true;
+							registration.activeMatch = match.identity;
+						}
 					}
 				}
-			} else {
-				if (registration.options.eventType === "keyup") {
-					if (matchesKeyboardEvent(event, registration.parsedHotkey, registration.options.platform)) this.#executeHotkeyCallback(registration, event);
-				}
-				if (registration.options.requireReset && registration.hasFired) {
-					if (this.#shouldResetRegistration(registration, event)) registration.hasFired = false;
-				}
+			} else if (registration.options.eventType === "keyup") {
+				const match = matches.get(id);
+				if (match?.matched && match.score === bestScore) this.#executeHotkeyCallback(registration, event);
 			}
 		}
 	}
@@ -294,7 +339,7 @@ var HotkeyManager = class HotkeyManager {
 	* Finds an existing registration with the same hotkey and target.
 	*/
 	#findConflictingRegistration(hotkey, target) {
-		for (const registration of this.registrations.state.values()) if (registration.hotkey === hotkey && registration.target === target) return registration;
+		for (const registration of this.registrations.state.values()) if (areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform) && registration.target === target) return registration;
 		return null;
 	}
 	/**
@@ -303,8 +348,13 @@ var HotkeyManager = class HotkeyManager {
 	#shouldResetRegistration(registration, event) {
 		const parsed = registration.parsedHotkey;
 		const releasedKey = normalizeKeyName(event.key);
-		const parsedKeyNormalized = parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key;
-		if ((releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey) === parsedKeyNormalized) return true;
+		if (registration.activeMatch?.code && event.code === registration.activeMatch.code) return true;
+		if (parsed.code !== void 0) {
+			if (event.code === parsed.code) return true;
+		} else {
+			const parsedKeyNormalized = parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key;
+			if ((releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey) === parsedKeyNormalized) return true;
+		}
 		if (parsed.ctrl && releasedKey === "Control") return true;
 		if (parsed.shift && releasedKey === "Shift") return true;
 		if (parsed.alt && releasedKey === "Alt") return true;
@@ -323,7 +373,7 @@ var HotkeyManager = class HotkeyManager {
 		if (!registration) return false;
 		const parsed = registration.parsedHotkey;
 		const syntheticEvent = new KeyboardEvent(registration.options.eventType ?? "keydown", {
-			key: parsed.key,
+			...parsed.code !== void 0 ? { code: parsed.code } : { key: parsed.key },
 			ctrlKey: parsed.ctrl,
 			shiftKey: parsed.shift,
 			altKey: parsed.alt,
@@ -353,7 +403,7 @@ var HotkeyManager = class HotkeyManager {
 	* @returns True if a matching registration exists
 	*/
 	isRegistered(hotkey, target) {
-		for (const registration of this.registrations.state.values()) if (registration.hotkey === hotkey) {
+		for (const registration of this.registrations.state.values()) if (areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform)) {
 			if (target === void 0 || registration.target === target) return true;
 		}
 		return false;
@@ -377,5 +427,4 @@ function getHotkeyManager() {
 }
 
 //#endregion
-export { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView };
-//# sourceMappingURL=hotkey-manager.js.map
+export { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView };

package/dist/hotkey-recorder.d.ts

@@ -1,11 +1,11 @@
-import { Hotkey } from "./hotkey.js";
+import { Hotkey } from "./hotkey.types.js";
+import { HotkeyRecorderValidationContext, RecorderOptions } from "./recorder-options.js";
 import { Store } from "@tanstack/store";
-
 //#region src/hotkey-recorder.d.ts
 /**
  * State interface for the HotkeyRecorder.
  */
-interface HotkeyRecorderState {
+export interface HotkeyRecorderState {
   /** Whether recording is currently active */
   isRecording: boolean;
   /** The currently recorded hotkey (for live preview) */
@@ -14,7 +14,9 @@ interface HotkeyRecorderState {
 /**
  * Options for configuring a HotkeyRecorder instance.
  */
-interface HotkeyRecorderOptions {
+export interface HotkeyRecorderOptions extends RecorderOptions {
+  /** Return true to accept, or false/a message to reject while staying in recording mode. */
+  validate?: (hotkey: Hotkey, context: HotkeyRecorderValidationContext) => boolean | string;
   /** Callback when a hotkey is successfully recorded */
   onRecord: (hotkey: Hotkey) => void;
   /** Optional callback when recording is cancelled (Escape pressed) */
@@ -69,7 +71,7 @@ interface HotkeyRecorderOptions {
  * unsubscribe()
  * ```
  */
-declare class HotkeyRecorder {
+export declare class HotkeyRecorder {
   #private;
   /**
    * The TanStack Store instance containing the recorder state.
@@ -111,6 +113,4 @@ declare class HotkeyRecorder {
    */
   destroy(): void;
 }
-//#endregion
-export { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState };
-//# sourceMappingURL=hotkey-recorder.d.ts.map
+//#endregion