@tanstack/hotkeys 0.15.0 → 0.15.1

package/dist/_keyboard-event.js

@@ -1,4 +1,4 @@
-import { PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
+import { MODIFIER_ALIASES, PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
 
 //#region src/_keyboard-event.ts
 /** Normalizes Unicode key names and modifier flags while retaining physical code and IME state. */
@@ -45,6 +45,22 @@ function codeToLogicalKey(code) {
 function isPrintableKey(key) {
 	return key !== "" && Array.from(key).length === 1;
 }
+/**
+* Resolves a modifier token or alias case-insensitively: `ctrl` → `Control`,
+* `cmd` → `Meta`, `mod` → `Mod`. Returns undefined for anything else.
+*/
+function modifierAlias(token) {
+	const lower = token.toLowerCase();
+	return Object.hasOwn(MODIFIER_ALIASES, lower) ? MODIFIER_ALIASES[lower] : void 0;
+}
+/** Whether a string has the shape of a `KeyboardEvent.code`, such as `KeyS`. */
+function isCodeName(code) {
+	return /^[A-Za-z][A-Za-z0-9]*$/.test(code);
+}
+/** The code inside a physical token: `[KeyS]` → `KeyS`. Undefined for anything else. */
+function physicalCodeOf(token) {
+	return token.startsWith("[") && token.endsWith("]") && isCodeName(token.slice(1, -1)) ? token.slice(1, -1) : void 0;
+}
 /** Splits modifier tokens while retaining a trailing literal plus: `Control++` → `['Control', '+']`. */
 function splitHotkeyParts(hotkey) {
 	if (!hotkey.endsWith("+")) return hotkey.split("+");
@@ -72,4 +88,4 @@ function assertLogicalKey(key) {
 }
 
 //#endregion
-export { assertLogicalKey, codeToLogicalKey, isAsciiLetter, isLatinLetter, isPrintableKey, keysEqual, normalizeKeyboardEvent, splitHotkeyParts };
+export { assertLogicalKey, codeToLogicalKey, isAsciiLetter, isCodeName, isLatinLetter, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitHotkeyParts };

package/dist/_manager-ref.js

@@ -0,0 +1,10 @@
+//#region src/_manager-ref.ts
+/**
+* The HotkeyManager singleton, once created. Code that only reads the live
+* registry, such as conflict checks, reads this instead of importing the
+* manager, so a recorder bundle does not include hotkey dispatch.
+*/
+const managerRef = { current: null };
+
+//#endregion
+export { managerRef };

package/dist/_match.js

@@ -45,6 +45,14 @@ function modifiersMatch(event, parsed, allowImplicitShift) {
 	if (ctrl !== parsed.ctrl || alt !== parsed.alt || event.meta !== parsed.meta) return false;
 	return event.shift === parsed.shift || allowImplicitShift && event.shift;
 }
+/**
+* Whether two parsed chords have the same identity: equal modifiers, and the
+* same physical code or (case-insensitively) the same logical key. A code and
+* a key never match, even when one keyboard event could produce both.
+*/
+function parsedHotkeysEqual(a, b) {
+	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 { matchKeyboardEvent };
+export { matchKeyboardEvent, parsedHotkeysEqual };

package/dist/_recorder-chord.js

@@ -1,5 +1,5 @@
 import { normalizeKeyName } from "./constants.js";
-import { normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isCodeName, normalizeKeyboardEvent } from "./_keyboard-event.js";
 import { isModifierKey, normalizeHotkeyFromParsed, parseKeyboardEvent } from "./parse.js";
 
 //#region src/_recorder-chord.ts
@@ -11,7 +11,7 @@ import { isModifierKey, normalizeHotkeyFromParsed, parseKeyboardEvent } from "./
 function hotkeyChordFromKeydown(event, platform, recordBy = "code") {
 	const normalized = normalizeKeyboardEvent(event, platform);
 	if (normalized.isComposing || isModifierKey(normalizeKeyName(event.key)) || event.key === "AltGraph") return null;
-	if (recordBy === "code" && (!/^[A-Za-z][A-Za-z0-9]*$/.test(event.code) || event.code === "Unidentified" || normalized.altGraph)) return null;
+	if (recordBy === "code" && (!hasUsableCode(event) || normalized.altGraph)) return null;
 	const parsed = parseKeyboardEvent(event, platform);
 	if (recordBy === "code") {
 		const { key: _key, code: _code, ...modifiers } = parsed;
@@ -32,11 +32,15 @@ function chordRejection(event, options) {
 		reason: "alt-graph",
 		message: "AltGraph character entry cannot be recorded as a physical shortcut. Use key mode for characters."
 	};
-	if (!/^[A-Za-z][A-Za-z0-9]*$/.test(event.code) || event.code === "Unidentified") return {
+	if (!hasUsableCode(event)) return {
 		reason: "missing-code",
 		message: "This event has no usable physical key code."
 	};
 }
+/** Whether the event reports a real physical key code to record. */
+function hasUsableCode(event) {
+	return isCodeName(event.code) && event.code !== "Unidentified";
+}
 
 //#endregion
 export { chordRejection, hotkeyChordFromKeydown };

package/dist/conflicts.js

@@ -1,9 +1,10 @@
 import { detectPlatform } from "./platform.js";
-import { keysEqual } from "./_keyboard-event.js";
 import { isHotkeySequence, parseRegisterableHotkey } from "./parse.js";
+import { parsedHotkeysEqual } from "./_match.js";
 import { matchesKeyboardEvent } from "./match.js";
 import { getTargetDocument } from "./_event-target.js";
-import { getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { managerRef } from "./_manager-ref.js";
+import { toHotkeyRegistrationView } from "./hotkey-manager.js";
 
 //#region src/conflicts.ts
 /** Whether two targets share a document and one contains the other (or is its window). */
@@ -29,12 +30,12 @@ function findHotkeyConflicts(candidate, options = {}) {
 		if (!options.includeDisabled && registration.options.enabled === false || (registration.options.eventType ?? "keydown") !== (options.eventType ?? "keydown") || options.excludeIds?.includes(registration.id) || options.exclude?.(registration) || options.scope !== "all" && target && !targetsOverlap(target, registration.target)) return false;
 		return parsed.slice(0, Math.min(parsed.length, bindings.length)).every((a, index) => {
 			const b = parseRegisterableHotkey(bindings[index], registration.options.platform);
-			const same = 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));
 			const event = options.events?.[index];
-			return same || event !== void 0 && matchesKeyboardEvent(event, a, platform) && matchesKeyboardEvent(event, b, registration.options.platform);
+			return parsedHotkeysEqual(a, b) || event !== void 0 && matchesKeyboardEvent(event, a, platform) && matchesKeyboardEvent(event, b, registration.options.platform);
 		});
 	};
-	for (const registration of getHotkeyManager().registrations.state.values()) {
+	const registrations = managerRef.current?.registrations.state.values() ?? [];
+	for (const registration of registrations) {
 		const view = toHotkeyRegistrationView(registration);
 		if (matches(view, view.kind === "sequence" ? view.hotkey : [view.hotkey])) conflicts.push({ registration: view });
 	}

package/dist/constants.d.ts

@@ -119,30 +119,7 @@ export declare const PUNCTUATION_CODE_MAP: Record<string, string>;
  * @see {@link PUNCTUATION_KEYS}
  */
 export declare const ALL_KEYS: Set<"CapsLock" | "ContextMenu" | "Convert" | "KanaMode" | "NonConvert" | "Help" | "Insert" | "NumLock" | "Fn" | "FnLock" | "PrintScreen" | "ScrollLock" | "Pause" | "BrowserBack" | "BrowserFavorites" | "BrowserForward" | "BrowserHome" | "BrowserRefresh" | "BrowserSearch" | "BrowserStop" | "Eject" | "LaunchMail" | "MediaPlayPause" | "MediaStop" | "MediaTrackNext" | "MediaTrackPrevious" | "Power" | "AudioVolumeDown" | "AudioVolumeMute" | "AudioVolumeUp" | "WakeUp" | "Hyper" | "Super" | "Again" | "Copy" | "Cut" | "Find" | "Open" | "Paste" | "Props" | "Select" | "Undo" | "Hiragana" | "Katakana" | "Clear" | "Cancel" | "Standby" | "LaunchApplication1" | "LaunchApplication2" | "LaunchMediaPlayer" | "HangulMode" | "HanjaMode" | "Zenkaku" | "Hankaku" | "ZenkakuHankaku" | LetterKey | NumberKey | FunctionKey | NavigationKey | EditingKey | PunctuationKey>;
-/**
- * Normalizes a key name to its canonical form.
- *
- * Converts various key name formats (aliases, case variations) into the standard
- * canonical names used throughout the library. This enables a more forgiving API
- * where users can write keys in different ways and still get correct behavior.
- *
- * Normalization rules:
- * 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')
- * 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')
- * 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')
- * 4. Other keys → returned as-is (already canonical or unknown)
- *
- * @param key - The key name to normalize (can be an alias, lowercase, etc.)
- * @returns The canonical key name
- *
- * @example
- * ```ts
- * normalizeKeyName('esc') // 'Escape'
- * normalizeKeyName('a') // 'A'
- * normalizeKeyName('f1') // 'F1'
- * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
- * ```
- */
+/** Whether a key is a single Unicode letter, such as `'a'` or `'é'`. */
 export declare function isSingleLetterKey(key: string): boolean;
 /**
  * Normalizes a key name to its canonical form.

package/dist/constants.js

@@ -28,7 +28,7 @@ const MODIFIER_ORDER = [
 * a modifier is released so we can clear non-modifier keys whose keyup events
 * may have been swallowed by the OS (e.g. macOS Cmd+key combos).
 */
-const MODIFIER_KEYS = new Set(MODIFIER_ORDER);
+const MODIFIER_KEYS = /* @__PURE__ */ new Set(MODIFIER_ORDER);
 /**
 * Maps modifier key aliases to their canonical form or platform-adaptive 'Mod'.
 *
@@ -283,89 +283,28 @@ const ALL_KEYS = /* @__PURE__ */ new Set([
 	...SHARED_NAMED_KEYS,
 	...LOGICAL_ONLY_NAMED_KEYS
 ]);
-const CANONICAL_KEY_NAMES = new Map(Array.from(ALL_KEYS, (key) => [key.toLowerCase(), key]));
 /**
-* Maps key name aliases to their canonical form.
-*
-* Handles common variations and alternative names for keys to provide a more
-* forgiving API. For example, users can write 'Esc', 'esc', or 'escape' and
-* they'll all normalize to 'Escape'.
-*
-* This map is used internally by `normalizeKeyName()` to convert user input
-* into the canonical key names used throughout the library.
-*
-* @remarks Case-insensitive lookups are supported via lowercase variants
-*
-* @example
-* ```ts
-* KEY_ALIASES['Esc'] // 'Escape'
-* KEY_ALIASES['Del'] // 'Delete'
-* KEY_ALIASES['Up'] // 'ArrowUp'
-* ```
-*/
-const KEY_ALIASES = {
-	Plus: "+",
-	plus: "+",
-	Esc: "Escape",
-	esc: "Escape",
-	escape: "Escape",
-	Return: "Enter",
-	return: "Enter",
-	enter: "Enter",
-	" ": "Space",
-	space: "Space",
-	Spacebar: "Space",
-	spacebar: "Space",
-	tab: "Tab",
-	backspace: "Backspace",
-	Del: "Delete",
-	del: "Delete",
-	delete: "Delete",
-	Up: "ArrowUp",
-	up: "ArrowUp",
-	arrowup: "ArrowUp",
-	Down: "ArrowDown",
-	down: "ArrowDown",
-	arrowdown: "ArrowDown",
-	Left: "ArrowLeft",
-	left: "ArrowLeft",
-	arrowleft: "ArrowLeft",
-	Right: "ArrowRight",
-	right: "ArrowRight",
-	arrowright: "ArrowRight",
-	home: "Home",
-	end: "End",
-	pageup: "PageUp",
-	pagedown: "PageDown",
-	PgUp: "PageUp",
-	PgDn: "PageDown",
-	pgup: "PageUp",
-	pgdn: "PageDown"
-};
-/**
-* Normalizes a key name to its canonical form.
-*
-* Converts various key name formats (aliases, case variations) into the standard
-* canonical names used throughout the library. This enables a more forgiving API
-* where users can write keys in different ways and still get correct behavior.
-*
-* Normalization rules:
-* 1. Check aliases first (e.g., 'Esc' → 'Escape', 'Del' → 'Delete')
-* 2. Single letters → uppercase (e.g., 'a' → 'A', 's' → 'S')
-* 3. Function keys → uppercase (e.g., 'f1' → 'F1', 'F12' → 'F12')
-* 4. Other keys → returned as-is (already canonical or unknown)
-*
-* @param key - The key name to normalize (can be an alias, lowercase, etc.)
-* @returns The canonical key name
-*
-* @example
-* ```ts
-* normalizeKeyName('esc') // 'Escape'
-* normalizeKeyName('a') // 'A'
-* normalizeKeyName('f1') // 'F1'
-* normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
-* ```
+* Maps lowercase key names and aliases to their canonical form, so lookups
+* are case-insensitive: `'esc'`, `'Esc'`, and `'ESCAPE'` all become `'Escape'`.
+* Canonical names come from {@link ALL_KEYS}, so validation and normalization
+* share one spelling for every key.
 */
+const CANONICAL_KEY_NAMES = /* @__PURE__ */ new Map([
+	...Array.from(ALL_KEYS, (key) => [key.toLowerCase(), key]),
+	["plus", "+"],
+	["esc", "Escape"],
+	["return", "Enter"],
+	[" ", "Space"],
+	["spacebar", "Space"],
+	["del", "Delete"],
+	["up", "ArrowUp"],
+	["down", "ArrowDown"],
+	["left", "ArrowLeft"],
+	["right", "ArrowRight"],
+	["pgup", "PageUp"],
+	["pgdn", "PageDown"]
+]);
+/** Whether a key is a single Unicode letter, such as `'a'` or `'é'`. */
 function isSingleLetterKey(key) {
 	return /^\p{Letter}$/u.test(key);
 }
@@ -385,7 +324,6 @@ 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();
 		return upper.length === 1 ? upper : key;

package/dist/format.js

@@ -1,8 +1,8 @@
-import { MODIFIER_ALIASES, MODIFIER_ORDER, PUNCTUATION_CODE_MAP, normalizeKeyName } from "./constants.js";
+import { MODIFIER_ORDER, 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";
+import { assertLogicalKey, codeToLogicalKey, modifierAlias, physicalCodeOf, splitHotkeyParts } from "./_keyboard-event.js";
+import { normalizeHotkeyFromParsed, normalizeRegisterableHotkey } from "./parse.js";
 
 //#region src/format.ts
 /**
@@ -55,23 +55,16 @@ function formatChordParts(hotkey, options) {
 		segments.sort((a, b) => modifierIndex(a) - modifierIndex(b));
 	}
 	return segments.map((segment) => {
-		if (isModifierKey(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 modifier = modifierAlias(segment);
+		if (modifier) return platform === "mac" ? modifierSymbols ? MAC_MODIFIER_SYMBOLS[modifier] : MAC_MODIFIER_LABELS[modifier] : platform === "windows" ? WINDOWS_MODIFIER_LABELS[modifier] : LINUX_MODIFIER_LABELS[modifier];
+		const code = physicalCodeOf(segment);
 		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;
-		}
+		else if (code) displayKey = numpad ? code.slice(6) : codeToLogicalKey(code) ?? code;
 		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;
 	});

package/dist/hotkey-manager.js

@@ -1,12 +1,13 @@
 import { normalizeKeyName } from "./constants.js";
 import { detectPlatform } from "./platform.js";
-import { normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
 import { isHotkeySequence, isModifierKey, parseHotkey, rawHotkeyToParsedHotkey, simplifyHotkey } from "./parse.js";
 import { formatHotkey } from "./format.js";
-import { matchKeyboardEvent } from "./_match.js";
+import { matchKeyboardEvent, parsedHotkeysEqual } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
 import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
 import { TargetListeners } from "./_target-listeners.js";
+import { managerRef } from "./_manager-ref.js";
 import { isRecordingEvent } from "./_recording-guard.js";
 import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
 import { Store } from "@tanstack/store";
@@ -65,7 +66,7 @@ function ignoresInputs(registration) {
 	return ignoreInputs === "auto" ? getDefaultIgnoreInputs(resolvedSteps(registration)[0]) : ignoreInputs;
 }
 function sameResolvedSteps(left, right) {
-	return left.length === right.length && left.every((step, index) => areHotkeysEqual(step, right[index]));
+	return left.length === right.length && left.every((step, index) => parsedHotkeysEqual(step, right[index]));
 }
 function formatForMessage(hotkey) {
 	return isHotkeySequence(hotkey) ? hotkey.join(" ") : hotkey;
@@ -97,7 +98,6 @@ function formatForMessage(hotkey) {
 * ```
 */
 var HotkeyManager = class HotkeyManager {
-	static #instance = null;
 	/**
 	* The TanStack Store containing all hotkey registrations, chords and sequences.
 	* Use this to subscribe to registration changes or access current registrations.
@@ -136,17 +136,14 @@ var HotkeyManager = class HotkeyManager {
 	* Gets the singleton instance of HotkeyManager.
 	*/
 	static getInstance() {
-		if (!HotkeyManager.#instance) HotkeyManager.#instance = new HotkeyManager();
-		return HotkeyManager.#instance;
+		return managerRef.current ??= new HotkeyManager();
 	}
 	/**
 	* Resets the singleton instance. Useful for testing.
 	*/
 	static resetInstance() {
-		if (HotkeyManager.#instance) {
-			HotkeyManager.#instance.destroy();
-			HotkeyManager.#instance = null;
-		}
+		managerRef.current?.destroy();
+		managerRef.current = null;
 	}
 	/** Notifies subscribers after in-place updates such as counts and sequence progress. */
 	#notify() {
@@ -175,44 +172,37 @@ var HotkeyManager = class HotkeyManager {
 		const id = generateId();
 		const platform = options.platform ?? this.#platform;
 		const target = options.target ?? document;
-		let registration;
-		if (isHotkeySequence(hotkey)) registration = {
-			kind: "sequence",
+		const sequence = isHotkeySequence(hotkey);
+		const common = {
 			id,
-			hotkey,
-			parsedSequence: hotkey.map((step) => parseHotkey(step, platform)),
 			callback,
 			options: {
 				...defaultHotkeyOptions,
-				timeout: DEFAULT_SEQUENCE_TIMEOUT,
-				...optionsForKind("sequence", options),
+				...sequence ? { timeout: DEFAULT_SEQUENCE_TIMEOUT } : { requireReset: false },
+				...optionsForKind(sequence ? "sequence" : "chord", options),
 				platform,
 				ignoreInputs: options.ignoreInputs ?? "auto"
 			},
 			target,
-			currentIndex: 0,
-			lastKeyTime: 0,
 			triggerCount: 0,
 			hasFired: false
 		};
+		let registration;
+		if (sequence) registration = {
+			...common,
+			kind: "sequence",
+			hotkey,
+			parsedSequence: hotkey.map((step) => parseHotkey(step, platform)),
+			currentIndex: 0,
+			lastKeyTime: 0
+		};
 		else {
 			const parsedHotkey = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
 			registration = {
+				...common,
 				kind: "chord",
-				id,
 				hotkey: typeof hotkey === "string" ? hotkey : formatHotkey(parsedHotkey),
-				parsedHotkey,
-				callback,
-				options: {
-					...defaultHotkeyOptions,
-					requireReset: false,
-					...optionsForKind("chord", options),
-					platform,
-					ignoreInputs: options.ignoreInputs ?? "auto"
-				},
-				target,
-				hasFired: false,
-				triggerCount: 0
+				parsedHotkey
 			};
 		}
 		const conflicting = this.#findConflictingRegistration(registration);
@@ -320,18 +310,17 @@ var HotkeyManager = class HotkeyManager {
 			if (!match?.matched || match.score !== bestScore) continue;
 			const registration = this.#currentIn(snapshot, capture);
 			if (!registration) continue;
+			this.#consume(registration, event);
 			if (eventType === "keyup") {
-				this.#executeCallback(registration, event);
+				this.#fire(registration, event);
 				continue;
 			}
-			if (registration.options.preventDefault) event.preventDefault();
-			if (registration.options.stopPropagation) event.stopPropagation();
 			if (!registration.options.requireReset || !registration.hasFired) {
 				if (registration.options.requireReset) {
 					registration.hasFired = true;
 					registration.activeMatch = match.identity;
 				}
-				this.#executeCallback(registration, event);
+				this.#fire(registration, event);
 			}
 		}
 	}
@@ -410,8 +399,7 @@ var HotkeyManager = class HotkeyManager {
 				registration.currentIndex = candidate.nextIndex;
 				changed = true;
 				if (registration.currentIndex >= registration.parsedSequence.length) {
-					if (registration.options.preventDefault) event.preventDefault();
-					if (registration.options.stopPropagation) event.stopPropagation();
+					this.#consume(registration, event);
 					registration.currentIndex = 0;
 					completed.push(registration);
 				}
@@ -423,19 +411,20 @@ var HotkeyManager = class HotkeyManager {
 		if (changed && completed.length === 0) this.#notify();
 		for (const snapshot of completed) {
 			const registration = this.#currentIn(snapshot, capture);
-			if (registration) this.#executeCallback(registration, event);
+			if (registration) this.#fire(registration, event);
 		}
 	}
-	/**
-	* Executes a hotkey callback with proper event handling.
-	*/
-	#executeCallback(registration, event) {
+	/** Applies a matched registration's preventDefault and stopPropagation options. */
+	#consume(registration, event) {
 		if (registration.options.preventDefault) event.preventDefault();
 		if (registration.options.stopPropagation) event.stopPropagation();
+	}
+	/** Counts a trigger, notifies subscribers (such as devtools), and runs the callback. */
+	#fire(registration, event, context = this.#callbackContext(registration)) {
 		registration.triggerCount++;
 		if (registration.kind === "sequence") registration.hasFired = true;
 		this.#notify();
-		registration.callback(event, this.#callbackContext(registration));
+		registration.callback(event, context);
 	}
 	#callbackContext(registration) {
 		return {
@@ -460,17 +449,7 @@ var HotkeyManager = class HotkeyManager {
 		const parsed = registration.parsedHotkey;
 		const releasedKey = normalizeKeyName(event.key);
 		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;
-		if (parsed.meta && releasedKey === "Meta") return true;
-		return false;
+		return (parsed.code !== void 0 ? event.code === parsed.code : keysEqual(releasedKey, parsed.key)) || parsed.modifiers.includes(releasedKey);
 	}
 	/**
 	* Resets the progress of every in-progress sequence.
@@ -504,10 +483,7 @@ var HotkeyManager = class HotkeyManager {
 			bubbles: true,
 			cancelable: true
 		});
-		registration.triggerCount++;
-		if (registration.kind === "sequence") registration.hasFired = true;
-		this.#notify();
-		registration.callback(syntheticEvent, context);
+		this.#fire(registration, syntheticEvent, context);
 		return true;
 	}
 	/**

package/dist/hotkey-recorder.d.ts

@@ -1,7 +1,37 @@
-import { Hotkey, HotkeyChord, HotkeySequence } from "./hotkey.types.js";
-import { HotkeyRecorderValidationContext, RecorderOptions } from "./recorder-options.js";
+import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkey } from "./hotkey.types.js";
+import { HotkeyConflict, HotkeyConflictOptions } from "./conflicts.js";
 import { Store } from "@tanstack/store";
 //#region src/hotkey-recorder.d.ts
+/** Event property used to record a binding. Physical codes are the default. */
+export type RecorderKeyMode = 'code' | 'key';
+export interface RecorderRejection {
+  reason: 'missing-code' | 'alt-graph' | 'invalid' | 'conflict' | 'validation';
+  message: string;
+  /** The rejected chord or sequence, when one was recorded. */
+  hotkey?: Hotkey;
+  conflicts?: Array<HotkeyConflict>;
+}
+export interface RecorderOptions {
+  /** Physical code recording is the default. Choose key to record logical characters. */
+  recordBy?: RecorderKeyMode;
+  /** Platform used for Mod and AltGraph handling. Defaults to platform detection. */
+  platform?: 'mac' | 'windows' | 'linux';
+  /** Opt in to live-registry conflicts, including sequence prefixes. Default: false. */
+  detectConflicts?: boolean | HotkeyConflictOptions;
+  /** Rejected candidates leave recording active. */
+  onReject?: (rejection: RecorderRejection) => void;
+}
+/** Validation context for a recorded chord or sequence. */
+export interface HotkeyRecorderValidationContext {
+  /** The event that recorded the last chord. */
+  event: KeyboardEvent;
+  /** The last chord, parsed. */
+  parsedHotkey: ParsedHotkey;
+  /** The event that recorded each step. */
+  events: ReadonlyArray<KeyboardEvent>;
+  /** Every step, parsed. */
+  parsedSequence: ReadonlyArray<ParsedHotkey>;
+}
 /**
  * State interface for the HotkeyRecorder.
  */

package/dist/hotkey.types.d.ts

@@ -127,6 +127,19 @@ export type ParsedHotkey = ParsedModifiers & ({
   code: string;
   key?: never;
 });
+/** Modifier flags shared by logical-key and physical-code registrations. */
+export interface RawModifiers {
+  /** Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults to false. */
+  mod?: boolean;
+  /** Whether the Control key is required. Defaults to false. */
+  ctrl?: boolean;
+  /** Whether the Shift key is required. Defaults to false. */
+  shift?: boolean;
+  /** Whether the Alt key is required. Defaults to false. */
+  alt?: boolean;
+  /** Whether the Meta (Command) key is required. Defaults to false. */
+  meta?: boolean;
+}
 /**
  * A raw hotkey object for programmatic registration.
  *
@@ -149,20 +162,6 @@ export type ParsedHotkey = ParsedModifiers & ({
  * useHotkey({ code: 'NumpadAdd', mod: true }, handler)      // Physical numpad plus
  * ```
  */
-/** Modifier flags shared by logical-key and physical-code registrations. */
-export interface RawModifiers {
-  /** The non-modifier key (e.g., 'S', 'Escape', 'F1'). */
-  /** Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults to false. */
-  mod?: boolean;
-  /** Whether the Control key is required. Defaults to false. */
-  ctrl?: boolean;
-  /** Whether the Shift key is required. Defaults to false. */
-  shift?: boolean;
-  /** Whether the Alt key is required. Defaults to false. */
-  alt?: boolean;
-  /** Whether the Meta (Command) key is required. Defaults to false. */
-  meta?: boolean;
-}
 export type RawHotkey = ({
   key: LogicalKey | (string & {});
   code?: never;

package/dist/index.d.ts

@@ -12,6 +12,5 @@ import { CreateHotkeyHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, KeyboardEventMatc
 import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
 import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
-import { HotkeyRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./recorder-options.js";
-import { HotkeyChordRecorderOptions, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeySequenceRecorderOptions } from "./hotkey-recorder.js";
+import { HotkeyChordRecorderOptions, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeySequenceRecorderOptions, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./hotkey-recorder.js";
 export { ALL_KEYS, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkey, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyChord, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, HotkeySequence, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkey, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkey, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisteredAppHotkeys, SingleModifierHotkey, Target, ThreeModifierHotkey, TwoModifierHotkey, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyHandler, createMultiHotkeyHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeKeyName, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, provideAppHotkeys, publishAppHotkeysStore, rawHotkeyToParsedHotkey, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/dist/key-state-tracker.js

@@ -53,10 +53,8 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	store = new Store(getDefaultKeyStateTrackerState());
 	#heldEntries = /* @__PURE__ */ new Map();
-	#keydownListener = null;
-	#keyupListener = null;
-	#mouseListener = null;
-	#blurListener = null;
+	/** Window listeners as `[type, listener, capture]`, removed together on destroy. */
+	#listeners = [];
 	constructor() {
 		this.#setupListeners();
 	}
@@ -81,7 +79,7 @@ var KeyStateTracker = class KeyStateTracker {
 	*/
 	#setupListeners() {
 		if (typeof document === "undefined") return;
-		this.#keydownListener = (event) => {
+		const onKeydown = (event) => {
 			let changed = this.#reconcileModifiers(event);
 			const key = normalizeKeyName(event.key);
 			const identity = event.code || `key:${key}`;
@@ -94,7 +92,7 @@ var KeyStateTracker = class KeyStateTracker {
 			}
 			if (changed) this.#syncState();
 		};
-		this.#keyupListener = (event) => {
+		const onKeyup = (event) => {
 			const key = normalizeKeyName(event.key);
 			const identity = event.code || `key:${key}`;
 			this.#heldEntries.delete(identity);
@@ -107,20 +105,43 @@ var KeyStateTracker = class KeyStateTracker {
 			}
 			this.#syncState();
 		};
-		this.#mouseListener = (event) => {
+		const onMouse = (event) => {
 			if (this.#reconcileModifiers(event)) this.#syncState();
 		};
-		this.#blurListener = () => {
+		const onBlur = () => {
 			if (this.#heldEntries.size > 0) {
 				this.#heldEntries.clear();
 				this.#syncState();
 			}
 		};
-		window.addEventListener("keydown", this.#keydownListener, true);
-		window.addEventListener("keyup", this.#keyupListener, true);
-		window.addEventListener("mousemove", this.#mouseListener, true);
-		window.addEventListener("mousedown", this.#mouseListener, true);
-		window.addEventListener("blur", this.#blurListener);
+		this.#listeners = [
+			[
+				"keydown",
+				onKeydown,
+				true
+			],
+			[
+				"keyup",
+				onKeyup,
+				true
+			],
+			[
+				"mousemove",
+				onMouse,
+				true
+			],
+			[
+				"mousedown",
+				onMouse,
+				true
+			],
+			[
+				"blur",
+				onBlur,
+				false
+			]
+		];
+		for (const [type, listener, capture] of this.#listeners) window.addEventListener(type, listener, capture);
 	}
 	/**
 	* Removes modifiers whose release was missed without a window blur.
@@ -153,24 +174,8 @@ var KeyStateTracker = class KeyStateTracker {
 	* Removes the keyboard event listeners.
 	*/
 	#removeListeners() {
-		if (typeof document === "undefined") return;
-		if (this.#keydownListener) {
-			window.removeEventListener("keydown", this.#keydownListener, true);
-			this.#keydownListener = null;
-		}
-		if (this.#keyupListener) {
-			window.removeEventListener("keyup", this.#keyupListener, true);
-			this.#keyupListener = null;
-		}
-		if (this.#mouseListener) {
-			window.removeEventListener("mousemove", this.#mouseListener, true);
-			window.removeEventListener("mousedown", this.#mouseListener, true);
-			this.#mouseListener = null;
-		}
-		if (this.#blurListener) {
-			window.removeEventListener("blur", this.#blurListener);
-			this.#blurListener = null;
-		}
+		for (const [type, listener, capture] of this.#listeners) window.removeEventListener(type, listener, capture);
+		this.#listeners = [];
 	}
 	/**
 	* Gets an array of currently held key names.

package/dist/match.js

@@ -1,8 +1,9 @@
 import { normalizeKeyName } from "./constants.js";
 import { detectPlatform } from "./platform.js";
-import { keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { normalizeKeyboardEvent } from "./_keyboard-event.js";
 import { isHotkeySequence, isModifierKey, parseHotkey, parseRegisterableHotkey } from "./parse.js";
-import { matchKeyboardEvent } from "./_match.js";
+import { formatHotkey } from "./format.js";
+import { matchKeyboardEvent, parsedHotkeysEqual } from "./_match.js";
 
 //#region src/match.ts
 /**
@@ -58,7 +59,7 @@ function matchesKeyboardEvent(event, hotkey, platform = detectPlatform()) {
 function createHotkeyHandler(hotkey, callback, options = {}) {
 	const { preventDefault = true, stopPropagation = true, platform } = options;
 	const resolvedPlatform = platform ?? detectPlatform();
-	const hotkeyString = typeof hotkey === "string" ? hotkey : formatParsedHotkey(hotkey);
+	const hotkeyString = typeof hotkey === "string" ? hotkey : formatHotkey(hotkey);
 	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, resolvedPlatform) : hotkey;
 	const context = {
 		hotkey: hotkeyString,
@@ -114,19 +115,6 @@ function createMultiHotkeyHandler(handlers, options = {}) {
 	};
 }
 /**
-* Formats a ParsedHotkey back to a hotkey string.
-* Used internally to provide the hotkey string in callback context.
-*/
-function formatParsedHotkey(parsed) {
-	const parts = [];
-	if (parsed.ctrl) parts.push("Control");
-	if (parsed.alt) parts.push("Alt");
-	if (parsed.shift) parts.push("Shift");
-	if (parsed.meta) parts.push("Meta");
-	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : parsed.key);
-	return parts.join("+");
-}
-/**
 * Compares normalized hotkey identity, including all four modifiers.
 * Sequences are equal when every step is equal; a one-step sequence equals its chord.
 * Aliases resolve on the supplied platform. A physical code and a logical key
@@ -135,12 +123,7 @@ function formatParsedHotkey(parsed) {
 function areHotkeysEqual(left, right, platform = detectPlatform()) {
 	const a = isHotkeySequence(left) ? left : [left];
 	const b = isHotkeySequence(right) ? right : [right];
-	return a.length === b.length && a.every((step, index) => areChordsEqual(step, b[index], platform));
-}
-function areChordsEqual(left, right, platform) {
-	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));
+	return a.length === b.length && a.every((step, index) => parsedHotkeysEqual(parseRegisterableHotkey(step, platform), parseRegisterableHotkey(b[index], platform)));
 }
 /** Default timeout between sequence steps (in milliseconds). */
 const DEFAULT_SEQUENCE_TIMEOUT = 1e3;

package/dist/parse.d.ts

@@ -1,6 +1,5 @@
 import { Key } from "./key.types.js";
 import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkey, RawHotkey, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
-import { MODIFIER_ALIASES } from "./constants.js";
 //#region src/parse.d.ts
 /**
  * Whether a hotkey is a sequence. Use this instead of `Array.isArray`, which
@@ -49,6 +48,12 @@ export declare function parseHotkey(hotkey: HotkeyChord | (string & {}), platfor
  * ```
  */
 export declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+/**
+ * Same canonical string as {@link normalizeHotkey}, but from an already-parsed
+ * hotkey: `Mod` first when the platform allows, then `Alt`, then `Shift`;
+ * otherwise full `Control+Alt+Shift+Meta` order.
+ */
+export declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): HotkeyChord;
 /**
  * Normalizes a hotkey string to its canonical form.
  *
@@ -70,10 +75,6 @@ export declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac'
  * ```
  */
 export declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): HotkeyChord;
-/**
- * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
- */
-export declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): HotkeyChord;
 /**
  * Normalizes a chord (string or {@link RawHotkey} object) or a sequence to canonical form.
  * Each sequence step is normalized, and a one-step sequence becomes its chord.
@@ -90,7 +91,7 @@ export declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey,
  * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
  * @returns True if the string is a recognized modifier
  */
-export declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MODIFIER_ALIASES;
+export declare function isModifierKey(key: Key | (string & {})): boolean;
 /**
  * Parses a KeyboardEvent into a ParsedHotkey object.
  *

package/dist/parse.js

@@ -1,8 +1,25 @@
-import { MODIFIER_ALIASES, MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
+import { MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
 import { detectPlatform, resolveModifier } from "./platform.js";
-import { assertLogicalKey, normalizeKeyboardEvent, splitHotkeyParts } from "./_keyboard-event.js";
+import { assertLogicalKey, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitHotkeyParts } from "./_keyboard-event.js";
 
 //#region src/parse.ts
+/** Builds a ParsedHotkey, listing held modifiers in canonical order. */
+function toParsedHotkey(identity, ctrl, shift, alt, meta) {
+	const held = {
+		Control: ctrl,
+		Alt: alt,
+		Shift: shift,
+		Meta: meta
+	};
+	return {
+		...identity,
+		ctrl,
+		shift,
+		alt,
+		meta,
+		modifiers: MODIFIER_ORDER.filter((modifier) => held[modifier])
+	};
+}
 /**
 * Whether a hotkey is a sequence. Use this instead of `Array.isArray`, which
 * does not narrow readonly arrays.
@@ -35,7 +52,7 @@ function parseHotkey(hotkey, platform = detectPlatform()) {
 		const part = parts[i].trim();
 		if (i === parts.length - 1) key = normalizeKeyName(part);
 		else {
-			const alias = MODIFIER_ALIASES[part] ?? MODIFIER_ALIASES[part.toLowerCase()];
+			const alias = modifierAlias(part);
 			if (alias) {
 				const resolved = resolveModifier(alias, platform);
 				modifiers.add(resolved);
@@ -43,15 +60,8 @@ function parseHotkey(hotkey, platform = detectPlatform()) {
 		}
 	}
 	if (!key && parts.length > 0) key = normalizeKeyName(parts[parts.length - 1].trim());
-	const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(key)?.[1];
-	return {
-		...code !== void 0 ? { code } : { key },
-		ctrl: modifiers.has("Control"),
-		shift: modifiers.has("Shift"),
-		alt: modifiers.has("Alt"),
-		meta: modifiers.has("Meta"),
-		modifiers: MODIFIER_ORDER.filter((m) => modifiers.has(m))
-	};
+	const code = physicalCodeOf(key);
+	return toParsedHotkey(code !== void 0 ? { code } : { key }, modifiers.has("Control"), modifiers.has("Shift"), modifiers.has("Alt"), modifiers.has("Meta"));
 }
 /**
 * Converts a RawHotkey object to a ParsedHotkey.
@@ -84,30 +94,14 @@ function rawHotkeyToParsedHotkey(raw, platform = detectPlatform()) {
 		if (resolveModifier("Mod", platform) === "Control") ctrl = true;
 		else meta = true;
 	}
-	const modifiers = MODIFIER_ORDER.filter((m) => {
-		switch (m) {
-			case "Control": return ctrl;
-			case "Shift": return shift;
-			case "Alt": return alt;
-			case "Meta": return meta;
-			default: return false;
-		}
-	});
-	return {
-		...raw.code !== void 0 ? { code: raw.code } : { key: normalizeKeyName(raw.key) },
-		ctrl,
-		shift,
-		alt,
-		meta,
-		modifiers
-	};
+	return toParsedHotkey(raw.code !== void 0 ? { code: raw.code } : { key: normalizeKeyName(raw.key) }, ctrl, shift, alt, meta);
 }
 /**
-* Serializes a parsed hotkey to the canonical string form used for registration
-* and storage: `Mod` first when the platform allows, then `Alt`, then `Shift`;
+* Same canonical string as {@link normalizeHotkey}, but from an already-parsed
+* hotkey: `Mod` first when the platform allows, then `Alt`, then `Shift`;
 * otherwise full `Control+Alt+Shift+Meta` order.
 */
-function normalizedHotkeyStringFromParsed(parsed, platform) {
+function normalizeHotkeyFromParsed(parsed, platform = detectPlatform()) {
 	if (parsed.code === void 0) assertLogicalKey(parsed.key);
 	const canUseMod = platform === "mac" ? parsed.meta && !parsed.ctrl : parsed.ctrl && !parsed.meta;
 	const parts = [];
@@ -140,13 +134,7 @@ function normalizedHotkeyStringFromParsed(parsed, platform) {
 * ```
 */
 function normalizeHotkey(hotkey, platform = detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parseHotkey(hotkey, platform), platform);
-}
-/**
-* Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
-*/
-function normalizeHotkeyFromParsed(parsed, platform = detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parsed, platform);
+	return normalizeHotkeyFromParsed(parseHotkey(hotkey, platform), platform);
 }
 function normalizeRegisterableHotkey(hotkey, platform = detectPlatform()) {
 	if (isHotkeySequence(hotkey)) {
@@ -165,7 +153,7 @@ function normalizeRegisterableHotkey(hotkey, platform = detectPlatform()) {
 * @returns True if the string is a recognized modifier
 */
 function isModifierKey(key) {
-	return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES;
+	return modifierAlias(key) !== void 0;
 }
 /**
 * Parses a KeyboardEvent into a ParsedHotkey object.
@@ -190,19 +178,7 @@ function parseKeyboardEvent(event, platform) {
 	const ctrl = normalized.altGraph ? false : normalized.ctrl;
 	const alt = normalized.altGraph ? false : normalized.alt;
 	const shift = normalized.shift;
-	const modifiers = [];
-	if (ctrl) modifiers.push("Control");
-	if (alt) modifiers.push("Alt");
-	if (shift) modifiers.push("Shift");
-	if (normalized.meta) modifiers.push("Meta");
-	return {
-		key: normalized.key,
-		ctrl,
-		shift,
-		alt,
-		meta: normalized.meta,
-		modifiers
-	};
+	return toParsedHotkey({ key: normalized.key }, ctrl, shift, alt, normalized.meta);
 }
 /**
 * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
@@ -211,7 +187,7 @@ function parseKeyboardEvent(event, platform) {
 * @param platform - Target platform for `Mod` eligibility
 */
 function normalizeHotkeyFromEvent(event, platform = detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event, platform), platform);
+	return normalizeHotkeyFromParsed(parseKeyboardEvent(event, platform), platform);
 }
 /**
 * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.

package/dist/validate.js

@@ -1,5 +1,5 @@
-import { ALL_KEYS, MODIFIER_ALIASES, normalizeKeyName } from "./constants.js";
-import { splitHotkeyParts } from "./_keyboard-event.js";
+import { ALL_KEYS, normalizeKeyName } from "./constants.js";
+import { modifierAlias, physicalCodeOf, splitHotkeyParts } from "./_keyboard-event.js";
 
 //#region src/validate.ts
 /**
@@ -60,34 +60,18 @@ function validateChord(hotkey) {
 	};
 	const modifierParts = parts.slice(0, -1);
 	const keyPart = parts[parts.length - 1];
-	for (const modifier of modifierParts) if (!(MODIFIER_ALIASES[modifier] ?? MODIFIER_ALIASES[modifier.toLowerCase()])) errors.push(`Unknown modifier: '${modifier}'`);
-	if (keyPart.length > 1 && (keyPart.startsWith("[") || keyPart.endsWith("]")) && !/^\[[A-Za-z][A-Za-z0-9]*\]$/.test(keyPart)) errors.push("Invalid physical key: use a bracketed KeyboardEvent.code, such as [KeyS]");
-	if (!isKnownKey(normalizeKeyName(keyPart)) && !isKnownKey(keyPart)) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
+	for (const modifier of modifierParts) if (!modifierAlias(modifier)) errors.push(`Unknown modifier: '${modifier}'`);
+	if (keyPart.length > 1 && (keyPart.startsWith("[") || keyPart.endsWith("]")) && physicalCodeOf(keyPart) === void 0) errors.push("Invalid physical key: use a bracketed KeyboardEvent.code, such as [KeyS]");
+	if (!isKnownKey(normalizeKeyName(keyPart))) warnings.push(`Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`);
 	return {
 		valid: errors.length === 0,
 		warnings,
 		errors
 	};
 }
-/**
-* Checks if a key is in the known keys set.
-*/
+/** Physical codes, single characters, and named keys are known. */
 function isKnownKey(key) {
-	if (/^\[[A-Za-z][A-Za-z0-9]*\]$/.test(key)) return true;
-	if (Array.from(key).length === 1) return true;
-	if (ALL_KEYS.has(key)) return true;
-	if (key.length === 1 && ALL_KEYS.has(key.toUpperCase())) return true;
-	return key in {
-		Esc: true,
-		Return: true,
-		Space: true,
-		" ": true,
-		Del: true,
-		Up: true,
-		Down: true,
-		Left: true,
-		Right: true
-	};
+	return physicalCodeOf(key) !== void 0 || Array.from(key).length === 1 || ALL_KEYS.has(key);
 }
 /**
 * Validates a hotkey and throws an error if invalid.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",

package/dist/recorder-options.d.ts

@@ -1,34 +0,0 @@
-import { Hotkey, ParsedHotkey } from "./hotkey.types.js";
-import { HotkeyConflict, HotkeyConflictOptions } from "./conflicts.js";
-//#region src/recorder-options.d.ts
-/** Event property used to record a binding. Physical codes are the default. */
-export type RecorderKeyMode = 'code' | 'key';
-export interface RecorderRejection {
-  reason: 'missing-code' | 'alt-graph' | 'invalid' | 'conflict' | 'validation';
-  message: string;
-  /** The rejected chord or sequence, when one was recorded. */
-  hotkey?: Hotkey;
-  conflicts?: Array<HotkeyConflict>;
-}
-export interface RecorderOptions {
-  /** Physical code recording is the default. Choose key to record logical characters. */
-  recordBy?: RecorderKeyMode;
-  /** Platform used for Mod and AltGraph handling. Defaults to platform detection. */
-  platform?: 'mac' | 'windows' | 'linux';
-  /** Opt in to live-registry conflicts, including sequence prefixes. Default: false. */
-  detectConflicts?: boolean | HotkeyConflictOptions;
-  /** Rejected candidates leave recording active. */
-  onReject?: (rejection: RecorderRejection) => void;
-}
-/** Validation context for a recorded chord or sequence. */
-export interface HotkeyRecorderValidationContext {
-  /** The event that recorded the last chord. */
-  event: KeyboardEvent;
-  /** The last chord, parsed. */
-  parsedHotkey: ParsedHotkey;
-  /** The event that recorded each step. */
-  events: ReadonlyArray<KeyboardEvent>;
-  /** Every step, parsed. */
-  parsedSequence: ReadonlyArray<ParsedHotkey>;
-}
-//#endregion