@tanstack/hotkeys 0.18.0 → 0.20.0

package/dist/app-hotkeys.js

@@ -2,9 +2,10 @@ import { detectPlatform } from "./platform.js";
 import { isHotkeySequence, simplifyHotkey } from "./parse.js";
 import { validateHotkey } from "./validate.js";
 import { areHotkeysEqual } from "./match.js";
+import { createStore } from "./_store.js";
 import { GLOBAL_SCOPE } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
-import { Store } from "@tanstack/store";
+import { setAppHotkeysStoreFactory } from "./_app-hotkeys-factory.js";
 
 //#region src/app-hotkeys.ts
 /**
@@ -22,6 +23,7 @@ import { Store } from "@tanstack/store";
 * ```
 */
 function defineAppHotkeys(definitions) {
+	setAppHotkeysStoreFactory((appHotkeys, options) => new AppHotkeysStore(appHotkeys, options));
 	const result = {};
 	for (const [id, input] of Object.entries(definitions)) {
 		const hotkey = input.hotkey === null ? null : simplifyHotkey(input.hotkey);
@@ -73,13 +75,13 @@ function sanitizeCustomHotkeys(appHotkeys, saved) {
 	if (typeof saved !== "object" || saved === null) return result;
 	for (const [id, value] of Object.entries(saved)) {
 		if (value === void 0) continue;
-		if (!(id in appHotkeys)) {
-			console.warn(`Ignoring custom hotkey for unknown app hotkey '${id}'`);
+		if (!Object.hasOwn(appHotkeys, id)) {
+			if (process.env.NODE_ENV !== "production") console.warn(`Ignoring custom hotkey for unknown app hotkey '${id}'`);
 			continue;
 		}
 		const hotkey = parseCustomHotkey(value);
 		if (hotkey === void 0) {
-			console.warn(`Ignoring invalid custom hotkey for app hotkey '${id}':`, value);
+			if (process.env.NODE_ENV !== "production") console.warn(`Ignoring invalid custom hotkey for app hotkey '${id}':`, value);
 			continue;
 		}
 		result[id] = hotkey;
@@ -123,7 +125,7 @@ var AppHotkeysStore = class {
 		this.#declarations = appHotkeys;
 		this.#options = options;
 		const customHotkeys = sanitizeCustomHotkeys(appHotkeys, options.customHotkeys);
-		this.store = new Store({
+		this.store = createStore({
 			appHotkeys: applyCustomHotkeys(appHotkeys, customHotkeys),
 			customHotkeys
 		});
@@ -161,7 +163,8 @@ var AppHotkeysStore = class {
 	}
 	/** Effective app hotkey for an id, or `undefined` when it is not declared. */
 	get(id) {
-		return this.store.state.appHotkeys[id];
+		const { appHotkeys } = this.store.state;
+		return Object.hasOwn(appHotkeys, id) ? appHotkeys[id] : void 0;
 	}
 	/**
 	* Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
@@ -169,7 +172,7 @@ var AppHotkeysStore = class {
 	* hotkeys are equal or one sequence starts with the other.
 	*/
 	findConflicts(id, hotkey) {
-		const self = this.store.state.appHotkeys[id];
+		const self = this.get(id);
 		if (!self) return [];
 		const candidate = simplifyHotkey(hotkey);
 		return Object.values(this.store.state.appHotkeys).filter((other) => other.id !== id && other.hotkey !== null && scopesOverlap(self, other) && hotkeysOverlap(candidate, other.hotkey, this.#platform));
@@ -181,9 +184,9 @@ var AppHotkeysStore = class {
 	* @returns Conflicting app hotkeys. When any exist, nothing changes.
 	*/
 	setCustomHotkey(id, hotkey) {
-		const appHotkey = this.store.state.appHotkeys[id];
+		const appHotkey = this.get(id);
 		if (!appHotkey) {
-			console.warn(`Cannot set a custom hotkey for unknown app hotkey '${id}'`);
+			if (process.env.NODE_ENV !== "production") console.warn(`Cannot set a custom hotkey for unknown app hotkey '${id}'`);
 			return [];
 		}
 		const next = hotkey === null ? null : simplifyHotkey(hotkey);

package/dist/constants.d.ts

@@ -107,9 +107,9 @@ export declare const PUNCTUATION_CODE_MAP: Record<string, string>;
 /**
  * Set of all valid non-modifier keys.
  *
- * This is the union of all key type sets (letters, numbers, function keys, navigation,
- * editing, and punctuation). Used primarily for validation to check if a key string
- * is recognized and will have type-safe autocomplete support.
+ * This is the union of all key type sets (letters, numbers, function keys,
+ * navigation, editing, punctuation, and other named keys): every key with
+ * type-safe autocomplete support.
  *
  * @see {@link LETTER_KEYS}
  * @see {@link NUMBER_KEYS}
@@ -122,16 +122,17 @@ export declare const ALL_KEYS: Set<"CapsLock" | "ContextMenu" | "Convert" | "Kan
 /** 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.
+ * Normalizes a key name from a `KeyboardEvent` or a hotkey: single letters
+ * become uppercase, and the space character becomes `Space`. Other names are
+ * returned as written, because key names are case-sensitive.
  *
- * @param key - The key name to normalize (can be an alias, lowercase, etc.)
+ * @param key - The key name to normalize
  * @returns The canonical key name
  *
  * @example
  * ```ts
- * normalizeKeyName('esc') // 'Escape'
  * normalizeKeyName('a') // 'A'
- * normalizeKeyName('f1') // 'F1'
+ * normalizeKeyName(' ') // 'Space'
  * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
  * ```
  */

package/dist/constants.js

@@ -1,4 +1,4 @@
-import { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from "./_named-keys.js";
+import { EDITING_KEY_NAMES, LOGICAL_ONLY_NAMED_KEYS, NAVIGATION_KEY_NAMES, SHARED_NAMED_KEYS } from "./_named-keys.js";
 
 //#region src/constants.ts
 /**
@@ -80,34 +80,7 @@ const MODIFIER_ALIASES = {
 * Used for validation and type checking. Letter keys are matched case-insensitively
 * in hotkey matching, but normalized to uppercase in canonical form.
 */
-const LETTER_KEYS = /* @__PURE__ */ new Set([
-	"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"
-]);
+const LETTER_KEYS = /* @__PURE__ */ new Set("ABCDEFGHIJKLMNOPQRSTUVWXYZ");
 /**
 * Set of all valid number keys (0-9).
 *
@@ -115,50 +88,14 @@ const LETTER_KEYS = /* @__PURE__ */ new Set([
 * so they're excluded from Shift-based hotkey combinations to avoid
 * layout-dependent behavior.
 */
-const NUMBER_KEYS = /* @__PURE__ */ new Set([
-	"0",
-	"1",
-	"2",
-	"3",
-	"4",
-	"5",
-	"6",
-	"7",
-	"8",
-	"9"
-]);
+const NUMBER_KEYS = /* @__PURE__ */ new Set("0123456789");
 /**
 * Set of all valid function keys (F1-F24).
 *
 * Function keys are commonly used for system shortcuts (e.g., F12 for DevTools,
 * Alt+F4 to close windows) and application-specific commands.
 */
-const FUNCTION_KEYS = /* @__PURE__ */ new Set([
-	"F1",
-	"F2",
-	"F3",
-	"F4",
-	"F5",
-	"F6",
-	"F7",
-	"F8",
-	"F9",
-	"F10",
-	"F11",
-	"F12",
-	"F13",
-	"F14",
-	"F15",
-	"F16",
-	"F17",
-	"F18",
-	"F19",
-	"F20",
-	"F21",
-	"F22",
-	"F23",
-	"F24"
-]);
+const FUNCTION_KEYS = /* @__PURE__ */ new Set(Array.from({ length: 24 }, (_, i) => `F${i + 1}`));
 /**
 * Set of all valid navigation keys for cursor movement and document navigation.
 *
@@ -166,16 +103,7 @@ const FUNCTION_KEYS = /* @__PURE__ */ new Set([
 * These keys are commonly combined with modifiers for selection (Shift+ArrowUp) or
 * navigation shortcuts (Alt+ArrowLeft for back).
 */
-const NAVIGATION_KEYS = /* @__PURE__ */ new Set([
-	"ArrowUp",
-	"ArrowDown",
-	"ArrowLeft",
-	"ArrowRight",
-	"Home",
-	"End",
-	"PageUp",
-	"PageDown"
-]);
+const NAVIGATION_KEYS = /* @__PURE__ */ new Set(NAVIGATION_KEY_NAMES);
 /**
 * Set of all valid editing and special keys.
 *
@@ -183,14 +111,7 @@ const NAVIGATION_KEYS = /* @__PURE__ */ new Set([
 * special actions (Escape, Space). These keys are frequently combined with modifiers
 * for editor shortcuts (Mod+Enter to submit, Shift+Tab to go back).
 */
-const EDITING_KEYS = /* @__PURE__ */ new Set([
-	"Enter",
-	"Escape",
-	"Space",
-	"Tab",
-	"Backspace",
-	"Delete"
-]);
+const EDITING_KEYS = /* @__PURE__ */ new Set(EDITING_KEY_NAMES);
 /**
 * Set of all valid punctuation keys commonly used in keyboard shortcuts.
 *
@@ -203,40 +124,7 @@ const EDITING_KEYS = /* @__PURE__ */ new Set([
 * Note: Punctuation keys are affected by Shift (Shift+',' → '<' on US layout),
 * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.
 */
-const PUNCTUATION_KEYS = /* @__PURE__ */ new Set([
-	"/",
-	"[",
-	"]",
-	"\\",
-	"=",
-	"-",
-	",",
-	".",
-	";",
-	"`",
-	"'",
-	"+",
-	"?",
-	"!",
-	"@",
-	"#",
-	"$",
-	"%",
-	"^",
-	"&",
-	"*",
-	"(",
-	")",
-	"_",
-	"{",
-	"}",
-	"|",
-	":",
-	"\"",
-	"<",
-	">",
-	"~"
-]);
+const PUNCTUATION_KEYS = /* @__PURE__ */ new Set("/[]\\=-,.;`'+?!@#$%^&*()_{}|:\"<>~");
 /**
 * Maps `KeyboardEvent.code` values for punctuation keys to their canonical characters.
 *
@@ -259,12 +147,15 @@ const PUNCTUATION_CODE_MAP = {
 	Semicolon: ";",
 	Slash: "/"
 };
+function union(...groups) {
+	return new Set(groups.flatMap((group) => [...group]));
+}
 /**
 * Set of all valid non-modifier keys.
 *
-* This is the union of all key type sets (letters, numbers, function keys, navigation,
-* editing, and punctuation). Used primarily for validation to check if a key string
-* is recognized and will have type-safe autocomplete support.
+* This is the union of all key type sets (letters, numbers, function keys,
+* navigation, editing, punctuation, and other named keys): every key with
+* type-safe autocomplete support.
 *
 * @see {@link LETTER_KEYS}
 * @see {@link NUMBER_KEYS}
@@ -273,52 +164,23 @@ const PUNCTUATION_CODE_MAP = {
 * @see {@link EDITING_KEYS}
 * @see {@link PUNCTUATION_KEYS}
 */
-const ALL_KEYS = /* @__PURE__ */ new Set([
-	...LETTER_KEYS,
-	...NUMBER_KEYS,
-	...FUNCTION_KEYS,
-	...NAVIGATION_KEYS,
-	...EDITING_KEYS,
-	...PUNCTUATION_KEYS,
-	...SHARED_NAMED_KEYS,
-	...LOGICAL_ONLY_NAMED_KEYS
-]);
-/**
-* 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"]
-]);
+const ALL_KEYS = /* @__PURE__ */ union(LETTER_KEYS, NUMBER_KEYS, FUNCTION_KEYS, NAVIGATION_KEYS, EDITING_KEYS, PUNCTUATION_KEYS, SHARED_NAMED_KEYS, LOGICAL_ONLY_NAMED_KEYS);
 /** Whether a key is a single Unicode letter, such as `'a'` or `'é'`. */
 function isSingleLetterKey(key) {
 	return /^\p{Letter}$/u.test(key);
 }
 /**
-* Normalizes a key name to its canonical form.
+* Normalizes a key name from a `KeyboardEvent` or a hotkey: single letters
+* become uppercase, and the space character becomes `Space`. Other names are
+* returned as written, because key names are case-sensitive.
 *
-* @param key - The key name to normalize (can be an alias, lowercase, etc.)
+* @param key - The key name to normalize
 * @returns The canonical key name
 *
 * @example
 * ```ts
-* normalizeKeyName('esc') // 'Escape'
 * normalizeKeyName('a') // 'A'
-* normalizeKeyName('f1') // 'F1'
+* normalizeKeyName(' ') // 'Space'
 * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
 * ```
 */
@@ -328,7 +190,7 @@ function normalizeKeyName(key) {
 		const upper = key.toUpperCase();
 		return upper.length === 1 ? upper : key;
 	}
-	return CANONICAL_KEY_NAMES.get(key.toLowerCase()) ?? key;
+	return key === " " ? "Space" : key;
 }
 
 //#endregion

package/dist/format.d.ts

@@ -1,3 +1,4 @@
+import { CanonicalModifier } from "./key.types.js";
 import { ParsedHotkeyChord, RegisterableHotkeyChord } from "./hotkey.types.js";
 //#region src/format.d.ts
 /**
@@ -17,8 +18,11 @@ import { ParsedHotkeyChord, RegisterableHotkeyChord } from "./hotkey.types.js";
 export declare function formatHotkey(parsed: ParsedHotkeyChord): string;
 export declare function formatHotkey(parsed: ReadonlyArray<ParsedHotkeyChord>): Array<string>;
 export declare function formatHotkey(parsed: ParsedHotkeyChord | ReadonlyArray<ParsedHotkeyChord>): string | Array<string>;
-/** A single chord to display: a string, raw object, or parsed hotkey. */
-export type DisplayHotkeyChord = RegisterableHotkeyChord | ParsedHotkeyChord | (string & {});
+/**
+ * A single chord to display: a hotkey string, which includes single keys, a
+ * modifier on its own, a raw object such as `{ key }`, or a parsed hotkey.
+ */
+export type DisplayHotkeyChord = RegisterableHotkeyChord | ParsedHotkeyChord | CanonicalModifier;
 /** A hotkey to display: a chord or a sequence of chords. */
 export type DisplayHotkey = DisplayHotkeyChord | ReadonlyArray<DisplayHotkeyChord>;
 /**
@@ -35,7 +39,10 @@ export type DisplayHotkey = DisplayHotkeyChord | ReadonlyArray<DisplayHotkeyChor
  * Sequence steps are formatted individually and joined with `sequenceSeparator`
  * (a space by default).
  *
- * @param hotkey - A logical or physical string, raw object, ParsedHotkeyChord, or sequence
+ * A key reported by a `KeyboardEvent`, such as a held key from
+ * `KeyStateTracker`, can be outside the key types: pass it as `{ key }`.
+ *
+ * @param hotkey - A logical or physical hotkey string, raw object, ParsedHotkeyChord, or sequence
  * @param options - Formatting options
  * @returns Display text, or individual key labels when parts is true (one array per step for sequences)
  *
@@ -50,6 +57,12 @@ export type DisplayHotkey = DisplayHotkeyChord | ReadonlyArray<DisplayHotkeyChor
  * formatForDisplay('Escape')
  * // Returns: 'Esc' (on all platforms)
  *
+ * formatForDisplay('Shift', { platform: 'mac' })
+ * // Returns: '⇧'
+ *
+ * formatForDisplay({ key: heldKey })
+ * // A key from a KeyboardEvent, such as a held key
+ *
  * formatForDisplay(['G', 'H'])
  * // Returns: 'G H'
  * ```

package/dist/format.js

@@ -45,20 +45,25 @@ function formatChordParts(hotkey, options) {
 		};
 		segments.sort((a, b) => modifierIndex(a) - modifierIndex(b));
 	}
-	return segments.map((segment) => {
-		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) 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;
-	});
+	return segments.map((segment) => formatKey(segment, platform, modifierSymbols, keySymbols, options));
+}
+/** Own properties only, so names such as `toString` never read Object.prototype. */
+function lookup(table, name) {
+	return table && Object.hasOwn(table, name) ? table[name] : void 0;
+}
+function formatKey(segment, platform, modifierSymbols, keySymbols, options) {
+	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 = lookup(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) displayKey = numpad ? code.slice(6) : codeToLogicalKey(code) ?? code;
+	const display = lookup(keySymbols ? KEY_DISPLAY_SYMBOLS : PUNCTUATION_KEY_DISPLAY_LABELS, displayKey) ?? displayKey;
+	return numpad ? `Numpad ${display.replace(/([a-z])([A-Z])/g, "$1 $2")}` : display;
 }
 
 //#endregion

package/dist/hotkey-manager.d.ts

@@ -1,6 +1,6 @@
+import { Store } from "./_store.js";
 import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
-import { Store } from "@tanstack/store";
 //#region src/hotkey-manager.d.ts
 /** An element, document, or window that hotkeys can listen on. */
 export type Target = HTMLElement | Document | Window;
@@ -366,15 +366,6 @@ export declare class HotkeyManager {
    * Resets the progress of every in-progress sequence.
    */
   resetSequenceProgress(): void;
-  /**
-   * Triggers a registration's callback programmatically from devtools.
-   * Creates a synthetic KeyboardEvent from the chord (or a sequence's last step)
-   * and invokes the callback.
-   *
-   * @param id - The registration ID to trigger
-   * @returns True if the registration was found and triggered
-   */
-  triggerRegistration(id: string): boolean;
   /**
    * Gets the number of registered hotkeys, chords and sequences.
    */

package/dist/hotkey-manager.js

@@ -1,16 +1,16 @@
 import { normalizeKeyName } from "./constants.js";
 import { detectPlatform } from "./platform.js";
-import { keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { isKeyNameShape, keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
 import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
-import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
+import { getTargetDocument, isDocumentLevel, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
+import { createStore } from "./_store.js";
 import { TargetListeners } from "./_target-listeners.js";
 import { managerRef } from "./_manager-ref.js";
 import { isRecordingEvent } from "./_recording-guard.js";
 import { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
-import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
 /** Whether a registration can fire now. Without a manager, scopes don't apply. */
@@ -127,14 +127,14 @@ var HotkeyManager = class HotkeyManager {
 	* }
 	* ```
 	*/
-	registrations = new Store(/* @__PURE__ */ new Map());
+	registrations = createStore(/* @__PURE__ */ new Map());
 	/**
 	* The app hotkeys store published by a framework provider, so tools such as
 	* devtools can list declared hotkeys that are not registered.
 	*/
-	appHotkeys = new Store(null);
+	appHotkeys = createStore(null);
 	/** Active scopes. Subscribe to show which hotkeys are suspended. */
-	scopes = new Store({
+	scopes = createStore({
 		active: [],
 		exclusive: null,
 		allowed: [],
@@ -194,7 +194,7 @@ var HotkeyManager = class HotkeyManager {
 		if (scope === "global") return () => {};
 		const { exclusive } = options;
 		const allow = exclusive ? exclusive === true ? [] : exclusive.allow : null;
-		if (allow && [...this.#scopeActivations].some((other) => other.allow && other.scope === scope)) console.warn(`Exclusive hotkey scope '${scope}' is already active. Hotkeys from both activations will fire; give each a unique scope.`);
+		if (process.env.NODE_ENV !== "production" && allow && [...this.#scopeActivations].some((other) => other.allow && other.scope === scope)) console.warn(`Exclusive hotkey scope '${scope}' is already active. Hotkeys from both activations will fire; give each a unique scope.`);
 		const activation = {
 			scope,
 			parent: options.parent ?? "global",
@@ -286,7 +286,7 @@ var HotkeyManager = class HotkeyManager {
 	#handledByLiveHotkey(event, eventType) {
 		const path = event.composedPath();
 		for (const registration of this.registrations.state.values()) {
-			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !path.includes(registration.target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, registration.target, registration.target)) continue;
+			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !path.includes(registration.target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, registration.target)) continue;
 			if ((registration.kind === "chord" ? [registration.parsedChord] : [registration.parsedSequence[registration.currentIndex], registration.parsedSequence[0]]).some((step) => matchKeyboardEvent(event, step, registration.options.platform).matched)) return true;
 		}
 		return false;
@@ -353,6 +353,10 @@ var HotkeyManager = class HotkeyManager {
 				parsedChord
 			};
 		}
+		if (process.env.NODE_ENV !== "production") {
+			const steps = registration.kind === "sequence" ? registration.parsedSequence : [registration.parsedChord];
+			for (const { key } of steps) if (key !== void 0 && !isKeyNameShape(key)) console.warn(`Unknown key '${key}' in '${formatForMessage(registration.hotkey)}'. Key names are case-sensitive, such as 'Escape' and 'F1', so this hotkey may never fire.`);
+		}
 		const conflicting = this.#findConflictingRegistration(registration);
 		if (conflicting) handleConflict(conflicting.id, formatForMessage(registration.hotkey), options.conflictBehavior ?? "warn", (conflictId) => this.#unregister(conflictId));
 		this.registrations.setState((prev) => new Map(prev).set(id, registration));
@@ -477,7 +481,7 @@ var HotkeyManager = class HotkeyManager {
 		let reserved = false;
 		for (const registration of registrations) {
 			const live = this.#isLive(registration);
-			if (!live && registration.options.preventDefault !== "always" || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			if (!live && registration.options.preventDefault !== "always" || registration.options.eventType !== eventType || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target)) continue;
 			const result = matchKeyboardEvent(event, registration.parsedChord, registration.options.platform);
 			if (!result.matched) continue;
 			if (!live) {
@@ -533,7 +537,7 @@ var HotkeyManager = class HotkeyManager {
 		for (const registration of this.registrations.state.values()) {
 			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !this.#isLive(registration) || registration.options.eventType !== eventType || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
 			const target = registration.target;
-			if (path.includes(target.nodeType === 1 ? target : getTargetDocument(target)) && !(ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, target)) && matchKeyboardEvent(event, registration.parsedSequence[registration.currentIndex], registration.options.platform).matched) return true;
+			if (path.includes(isDocumentLevel(target) ? getTargetDocument(target) : target) && !(ignoresInputs(registration) && shouldIgnoreInputEvent(event, target)) && matchKeyboardEvent(event, registration.parsedSequence[registration.currentIndex], registration.options.platform).matched) return true;
 		}
 		return false;
 	}
@@ -556,7 +560,7 @@ var HotkeyManager = class HotkeyManager {
 		const candidates = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!isEventForTarget(event, target) || !this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
+			if (!this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target) || registration.options.eventType !== eventType) continue;
 			const timeout = registration.options.timeout ?? 1e3;
 			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
 				registration.currentIndex = 0;
@@ -662,31 +666,6 @@ var HotkeyManager = class HotkeyManager {
 		this.#notify();
 	}
 	/**
-	* Triggers a registration's callback programmatically from devtools.
-	* Creates a synthetic KeyboardEvent from the chord (or a sequence's last step)
-	* and invokes the callback.
-	*
-	* @param id - The registration ID to trigger
-	* @returns True if the registration was found and triggered
-	*/
-	triggerRegistration(id) {
-		const registration = this.registrations.state.get(id);
-		if (!registration) return false;
-		const context = this.#callbackContext(registration);
-		const parsed = registration.kind === "chord" ? registration.parsedChord : registration.parsedSequence[registration.parsedSequence.length - 1];
-		const syntheticEvent = new KeyboardEvent(registration.options.eventType ?? "keydown", {
-			...parsed.code !== void 0 ? { code: parsed.code } : { key: parsed.key },
-			ctrlKey: parsed.ctrl,
-			shiftKey: parsed.shift,
-			altKey: parsed.alt,
-			metaKey: parsed.meta,
-			bubbles: true,
-			cancelable: true
-		});
-		this.#fire(registration, syntheticEvent, context);
-		return true;
-	}
-	/**
 	* Gets the number of registered hotkeys, chords and sequences.
 	*/
 	getRegistrationCount() {

package/dist/hotkey-recorder.d.ts

@@ -1,6 +1,6 @@
+import { Store } from "./_store.js";
 import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord } 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';

package/dist/hotkey-recorder.js

@@ -1,12 +1,11 @@
 import { detectPlatform } from "./platform.js";
-import { normalizeKeyboardEvent } from "./_keyboard-event.js";
+import { normalizeKeyboardEvent, splitChordParts } from "./_keyboard-event.js";
 import { isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
-import { validateHotkey } from "./validate.js";
 import { isTypingEvent } from "./_event-target.js";
+import { createStore } from "./_store.js";
 import { beginRecording, captureRecordingEvent, endRecording } from "./_recording-guard.js";
 import { findHotkeyConflicts } from "./conflicts.js";
 import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
-import { Store } from "@tanstack/store";
 
 //#region src/hotkey-recorder.ts
 const initialState = {
@@ -49,7 +48,7 @@ const initialState = {
 * ```
 */
 var HotkeyRecorder = class {
-	store = new Store(initialState);
+	store = createStore(initialState);
 	#keydownHandler = null;
 	#optionsSource;
 	#optionOverrides = {};
@@ -101,7 +100,7 @@ var HotkeyRecorder = class {
 	* and records chords according to `maxSteps`.
 	*/
 	start() {
-		if (this.#keydownHandler) return;
+		if (this.#keydownHandler || typeof document === "undefined") return;
 		this.#clearIdleTimer();
 		this.#events = [];
 		beginRecording(this);
@@ -156,11 +155,10 @@ var HotkeyRecorder = class {
 			}
 			const chord = hotkeyChordFromKeydown(event, platform, options.recordBy);
 			if (chord === null) return;
-			const validation = validateHotkey(chord);
-			if (!validation.valid) {
+			if (splitChordParts(chord).some((part) => !part.trim())) {
 				options.onReject?.({
 					reason: "invalid",
-					message: validation.errors.join("; "),
+					message: "Whitespace keys cannot be recorded",
 					hotkey: chord
 				});
 				return;

package/dist/key-state-tracker.d.ts

@@ -1,4 +1,4 @@
-import { Store } from "@tanstack/store";
+import { Store } from "./_store.js";
 //#region src/key-state-tracker.d.ts
 /**
  * State interface for the KeyStateTracker.