@tanstack/hotkeys 0.23.0 → 0.25.0

package/dist/index.d.ts

@@ -1,17 +1,17 @@
-import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.js";
-import { ConflictBehavior, FourModifierHotkeyChord, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyMeta, HotkeySequence, HotkeySequenceCallbackContext, ParsedHotkeyChord, ParsedModifiers, RawHotkeyChord, RawModifiers, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, SingleModifierHotkeyChord, ThreeModifierHotkeyChord, TwoModifierHotkeyChord } from "./hotkey.types.js";
-import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
-import { AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CustomHotkeys, DefinedAppHotkeys, Register, RegisteredAppHotkeys, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
-import { HotkeyPlatform, detectPlatform, resolveModifier } from "./platform.js";
 import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, 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 { HotkeyPlatform, detectPlatform, resolveModifier } from "./platform.js";
+import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.js";
+import { ConflictBehavior, FourModifierHotkeyChord, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyMeta, HotkeySequence, HotkeySequenceCallbackContext, ParsedHotkeyChord, ParsedModifiers, RawHotkeyChord, RawModifiers, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, SingleModifierHotkeyChord, ThreeModifierHotkeyChord, TwoModifierHotkeyChord } from "./hotkey.types.js";
 import { DisplayHotkey, DisplayHotkeyChord, FormatDisplayOptions, formatForDisplay, formatHotkey } from "./format.js";
 import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey } from "./parse.js";
-import { ValidatableHotkey, ValidationResult, assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
+import { HotkeyIssue, HotkeyIssueReason, ValidatableHotkey, ValidationResult, assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
 import { CreateHotkeyChordHandlerOptions, DEFAULT_SEQUENCE_TIMEOUT, KeyboardEventMatch, MultiHotkeyChordHandler, areHotkeysEqual, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, matchesKeyboardEvent } from "./match.js";
 import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
 import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
+import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CustomHotkeys, DefinedAppHotkeys, Register, RegisteredAppHotkeys, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
-import { HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./hotkey-recorder.js";
+import { HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection, RecorderRejectionReason } from "./hotkey-recorder.js";
 import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
-export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyPlatform, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, 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, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createAppHotkeysStore, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyIssue, HotkeyIssueReason, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyPlatform, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, 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, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, RecorderRejectionReason, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createAppHotkeysStore, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/dist/index.js

@@ -1,16 +1,16 @@
 import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, 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, resolveModifier } from "./platform.js";
-import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey } from "./parse.js";
 import { formatForDisplay, formatHotkey } from "./format.js";
+import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey } from "./parse.js";
 import { assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, matchesKeyboardEvent } from "./match.js";
 import { matchesHeldModifiers } from "./hint.js";
-import { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { findHotkeyConflicts } from "./conflicts.js";
-import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
+import { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { AppHotkeysStore, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
 import { KeyStateTracker, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyRecorder } from "./hotkey-recorder.js";
+import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
 
 export { ALL_KEYS, AppHotkeysStore, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createAppHotkeysStore, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

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

@@ -1,5 +1,4 @@
 import { Store } from "./_store.js";
-//#region src/key-state-tracker.d.ts
 /**
  * State interface for the KeyStateTracker.
  */
@@ -100,5 +99,4 @@ export declare class KeyStateTracker {
  * Gets the singleton KeyStateTracker instance.
  * Convenience function for accessing the tracker.
  */
-export declare function getKeyStateTracker(): KeyStateTracker;
-//#endregion
+export declare function getKeyStateTracker(): KeyStateTracker;

package/dist/key-state-tracker.js

@@ -1,7 +1,7 @@
-import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
 import { createStore } from "./_store.js";
+import { MODIFIER_KEYS, normalizeKeyName } from "./constants.js";
 
-//#region src/key-state-tracker.ts
+// src/key-state-tracker.ts
 /**
 * Returns the default state for KeyStateTracker.
 */
@@ -252,5 +252,4 @@ function getKeyStateTracker() {
 	return KeyStateTracker.getInstance();
 }
 
-//#endregion
 export { KeyStateTracker, getKeyStateTracker };

package/dist/key.types.d.ts

@@ -1,5 +1,4 @@
 import { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS } from "./_named-keys.js";
-//#region src/key.types.d.ts
 /**
  * All supported modifier key names, including aliases.
  * - Control/Ctrl: The Control key
@@ -44,12 +43,13 @@ export type NamedKey = (typeof SHARED_NAMED_KEYS)[number] | (typeof LOGICAL_ONLY
 export type NonPunctuationKey = LetterKey | NumberKey | EditingKey | NavigationKey | FunctionKey | NamedKey;
 /**
  * Supported physical KeyboardEvent.code names, independent of keyboard layout.
- * Letter, digit, numpad, and sided modifier names use finite template unions.
- * `Unidentified` is excluded because it cannot identify a physical key.
+ * Letter, digit, and numpad names use finite template unions. Modifier codes
+ * such as `ShiftLeft` are excluded, because modifier-only hotkeys aren't
+ * supported. `Unidentified` is excluded because it cannot identify a physical key.
  *
  * @see https://www.w3.org/TR/uievents-code/
  */
-export type PhysicalKeyCode = `Key${LetterKey}` | `Digit${NumberKey}` | `Numpad${NumberKey}` | `${'Alt' | 'Control' | 'Meta' | 'Shift'}${'Left' | 'Right'}` | EditingKey | NavigationKey | FunctionKey | (typeof SHARED_NAMED_KEYS)[number] | 'Backquote' | 'Backslash' | 'BracketLeft' | 'BracketRight' | 'Comma' | 'Equal' | 'IntlBackslash' | 'IntlRo' | 'IntlYen' | 'Minus' | 'Period' | 'Quote' | 'Semicolon' | 'Slash' | `Lang${1 | 2 | 3 | 4 | 5}` | `Numpad${'Add' | 'Backspace' | 'Clear' | 'ClearEntry' | 'Comma' | 'Decimal' | 'Divide' | 'Enter' | 'Equal' | 'Hash' | 'MemoryAdd' | 'MemoryClear' | 'MemoryRecall' | 'MemoryStore' | 'MemorySubtract' | 'Multiply' | 'ParenLeft' | 'ParenRight' | 'Star' | 'Subtract'}` | 'LaunchApp1' | 'LaunchApp2' | 'MediaSelect' | 'Sleep' | 'Turbo' | 'Abort' | 'Resume' | 'Suspend';
+export type PhysicalKeyCode = `Key${LetterKey}` | `Digit${NumberKey}` | `Numpad${NumberKey}` | EditingKey | NavigationKey | FunctionKey | (typeof SHARED_NAMED_KEYS)[number] | 'Backquote' | 'Backslash' | 'BracketLeft' | 'BracketRight' | 'Comma' | 'Equal' | 'IntlBackslash' | 'IntlRo' | 'IntlYen' | 'Minus' | 'Period' | 'Quote' | 'Semicolon' | 'Slash' | `Lang${1 | 2 | 3 | 4 | 5}` | `Numpad${'Add' | 'Backspace' | 'Clear' | 'ClearEntry' | 'Comma' | 'Decimal' | 'Divide' | 'Enter' | 'Equal' | 'Hash' | 'MemoryAdd' | 'MemoryClear' | 'MemoryRecall' | 'MemoryStore' | 'MemorySubtract' | 'Multiply' | 'ParenLeft' | 'ParenRight' | 'Star' | 'Subtract'}` | 'LaunchApp1' | 'LaunchApp2' | 'MediaSelect' | 'Sleep' | 'Turbo' | 'Abort' | 'Resume' | 'Suspend';
 /**
  * An explicit physical key token. All codes use brackets, including names such
  * as `[Enter]` that also exist as logical keys. Invalid code names are rejected
@@ -75,5 +75,4 @@ export interface NormalizedKeyboardEvent {
   altGraph: boolean;
   location: number;
   isComposing: boolean;
-}
-//#endregion
+}

package/dist/match.d.ts

@@ -1,6 +1,5 @@
-import { HotkeyCallback, HotkeyChord, HotkeyChordCallbackContext, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { HotkeyPlatform } from "./platform.js";
-//#region src/match.d.ts
+import { HotkeyCallback, HotkeyChord, HotkeyChordCallbackContext, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeySequence } from "./hotkey.types.js";
 export interface KeyboardEventMatch {
   matched: boolean;
   score: 0 | 1 | 2 | 3;
@@ -22,7 +21,8 @@ export interface KeyboardEventMatch {
  * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
  * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,
  * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.
- * In these cases, `event.code` is used to determine the physical key.
+ * In these cases, `event.code` is used to determine the physical key. An
+ * `'Unidentified'` key also falls back to `code`, except on letter keys.
  *
  * @param event - The KeyboardEvent to check
  * @param chord - The chord string or parsed chord to match against
@@ -129,5 +129,4 @@ export declare function createSequenceMatcher(sequence: RegisterableHotkeySequen
   match: (event: KeyboardEvent) => boolean;
   reset: () => void;
   getProgress: () => number;
-};
-//#endregion
+};

package/dist/match.js

@@ -1,12 +1,12 @@
-import { normalizeKeyName } from "./constants.js";
-import { detectPlatform } from "./platform.js";
 import { normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isHotkeySequence, isModifierKey, parseHotkey } from "./parse.js";
-import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 import { chordHasKey } from "./_registration.js";
+import { normalizeKeyName } from "./constants.js";
+import { formatHotkey } from "./format.js";
+import { isHotkeySequence, isModifierKey, parseHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
 
-//#region src/match.ts
+// src/match.ts
 /**
 * Checks if a KeyboardEvent matches a hotkey.
 *
@@ -19,7 +19,8 @@ import { chordHasKey } from "./_registration.js";
 * Also handles "dead key" events where `event.key` is `'Dead'` instead of the expected
 * character. This commonly occurs on macOS with Option+letter combinations (e.g., Option+E,
 * Option+I, Option+U, Option+N) and on Windows/Linux with international keyboard layouts.
-* In these cases, `event.code` is used to determine the physical key.
+* In these cases, `event.code` is used to determine the physical key. An
+* `'Unidentified'` key also falls back to `code`, except on letter keys.
 *
 * @param event - The KeyboardEvent to check
 * @param chord - The chord string or parsed chord to match against
@@ -193,5 +194,4 @@ function createSequenceMatcher(sequence, options = {}) {
 	};
 }
 
-//#endregion
 export { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, matchesKeyboardEvent };

package/dist/parse.d.ts

@@ -1,6 +1,5 @@
-import { Key } from "./key.types.js";
 import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
-//#region src/parse.d.ts
+import { Key } from "./key.types.js";
 type Platform = 'mac' | 'windows' | 'linux';
 /** A chord in any form: a string, a chord object, or an already-parsed chord. */
 type AnyChord = RegisterableHotkeyChord | ParsedHotkeyChord | (string & {});
@@ -103,4 +102,4 @@ export declare function parseKeyboardEvent(event: KeyboardEvent, platform?: Plat
  * ```
  */
 export declare function hasNonModifierKey(chord: HotkeyChord | ParsedHotkeyChord | (string & {}), platform?: Platform): boolean;
-//#endregion
+export {};

package/dist/parse.js

@@ -1,8 +1,9 @@
+import { assertLogicalKey, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
+import { chordHasKey } from "./_registration.js";
 import { MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
 import { detectPlatform, resolveModifier } from "./platform.js";
-import { assertLogicalKey, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 
-//#region src/parse.ts
+// src/parse.ts
 /** Builds a ParsedHotkeyChord, listing held modifiers in canonical order. */
 function toParsedChord(identity, ctrl, shift, alt, meta) {
 	const held = {
@@ -31,21 +32,14 @@ function simplifyHotkey(hotkey) {
 	return isHotkeySequence(hotkey) && hotkey.length === 1 ? hotkey[0] : hotkey;
 }
 function parseChordString(chord, platform) {
-	const parts = splitChordParts(chord);
+	const parts = splitChordParts(chord).map((part) => part.trim());
+	const key = normalizeKeyName(parts.pop());
 	const modifiers = /* @__PURE__ */ new Set();
-	let key = "";
-	for (let i = 0; i < parts.length; i++) {
-		const part = parts[i].trim();
-		if (i === parts.length - 1) key = normalizeKeyName(part);
-		else {
-			const alias = modifierAlias(part);
-			if (alias) {
-				const resolved = resolveModifier(alias, platform);
-				modifiers.add(resolved);
-			} else if (parts.length === 1) key = normalizeKeyName(part);
-		}
+	for (const part of parts) {
+		const alias = modifierAlias(part);
+		if (!alias) return toParsedChord({ key: "" }, false, false, false, false);
+		modifiers.add(resolveModifier(alias, platform));
 	}
-	if (!key && parts.length > 0) key = normalizeKeyName(parts[parts.length - 1].trim());
 	const code = physicalCodeOf(key);
 	return toParsedChord(code !== void 0 ? { code } : { key }, modifiers.has("Control"), modifiers.has("Shift"), modifiers.has("Alt"), modifiers.has("Meta"));
 }
@@ -145,10 +139,7 @@ function parseKeyboardEvent(event, platform) {
 * ```
 */
 function hasNonModifierKey(chord, platform = detectPlatform()) {
-	const parsed = typeof chord === "string" ? parseChordString(chord, platform) : chord;
-	if (parsed.code !== void 0) return parsed.code.length > 0 && !/^(Control|Shift|Alt|Meta)(Left|Right)$/.test(parsed.code);
-	return !isModifierKey(parsed.key) && parsed.key.length > 0;
+	return chordHasKey(typeof chord === "string" ? parseChordString(chord, platform) : chord);
 }
 
-//#endregion
 export { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey };

package/dist/platform.d.ts

@@ -1,5 +1,4 @@
 import { CanonicalModifier } from "./key.types.js";
-//#region src/platform.d.ts
 /** A platform for resolving `Mod` and formatting labels. */
 export type HotkeyPlatform = 'mac' | 'windows' | 'linux';
 /**
@@ -49,5 +48,4 @@ export declare function detectPlatform(userAgent?: string | null): HotkeyPlatfor
  * resolveModifier('Control', 'mac') // 'Control' (unchanged)
  * ```
  */
-export declare function resolveModifier(modifier: CanonicalModifier | 'Mod', platform?: 'mac' | 'windows' | 'linux'): CanonicalModifier;
-//#endregion
+export declare function resolveModifier(modifier: CanonicalModifier | 'Mod', platform?: 'mac' | 'windows' | 'linux'): CanonicalModifier;

package/dist/platform.js

@@ -1,6 +1,6 @@
 import { isServerRuntime } from "./_server.js";
 
-//#region src/platform.ts
+// src/platform.ts
 /**
 * Detects a platform from a user agent string, or from the browser's
 * `navigator` when called without one.
@@ -65,5 +65,4 @@ function resolveModifier(modifier, platform = detectPlatform()) {
 	return modifier;
 }
 
-//#endregion
 export { detectPlatform, resolveModifier };

package/dist/validate.d.ts

@@ -1,14 +1,15 @@
 import { Hotkey } from "./hotkey.types.js";
-//#region src/validate.d.ts
 /** A hotkey to validate: a chord string, a sequence, or untyped input such as saved data. */
 export type ValidatableHotkey = Hotkey | (string & {}) | ReadonlyArray<string>;
 /**
  * Validates a hotkey and returns any warnings or errors.
- * Sequences are validated step by step, and messages name the failing step.
+ * Each issue has a `reason` code, so apps can write their own messages.
+ * Issues in a sequence carry the index of their `step`.
  *
  * Checks for:
  * - Valid syntax (modifier+...+key format)
  * - Known modifiers
+ * - A key that isn't a modifier
  * - Known keys
  *
  * @param hotkey - The hotkey string to validate
@@ -20,10 +21,10 @@ export type ValidatableHotkey = Hotkey | (string & {}) | ReadonlyArray<string>;
  * // { valid: true, warnings: [], errors: [] }
  *
  * validateHotkey('')
- * // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+ * // { valid: false, warnings: [], errors: [{ reason: 'empty' }] }
  *
  * validateHotkey(['G', 'Foo+H'])
- * // { valid: false, warnings: [], errors: ["Step 2: Unknown modifier: 'Foo'"] }
+ * // { valid: false, warnings: [], errors: [{ reason: 'unknown-modifier', part: 'Foo', step: 1 }] }
  * ```
  */
 export declare function validateHotkey(hotkey: ValidatableHotkey): ValidationResult;
@@ -37,7 +38,7 @@ export declare function validateHotkey(hotkey: ValidatableHotkey): ValidationRes
  * @example
  * ```ts
  * assertValidHotkey('Mod+S') // OK
- * assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
+ * assertValidHotkey('') // Throws Error: [hotkeys] Invalid hotkey '': empty
  * ```
  */
 export declare function assertValidHotkey(hotkey: ValidatableHotkey): void;
@@ -51,24 +52,43 @@ export declare function assertValidHotkey(hotkey: ValidatableHotkey): void;
  * @example
  * ```ts
  * checkHotkey('Control+escape')
- * // Console: Hotkey 'Control+escape' warnings: Unknown key: 'escape'. Key names are case-sensitive, such as 'Escape' and 'F1'.
+ * // Console: [hotkeys] Hotkey 'Control+escape' may never fire: unknown-key 'escape'
  * // Returns: true
  *
  * checkHotkey('Ctl+K')
- * // Console: Hotkey 'Ctl+K' errors: Unknown modifier: 'Ctl'
+ * // Console: [hotkeys] Invalid hotkey 'Ctl+K': unknown-modifier 'Ctl'
  * // Returns: false
  * ```
  */
 export declare function checkHotkey(hotkey: ValidatableHotkey): boolean;
+/**
+ * Why a hotkey is invalid or may never fire:
+ *
+ * - `'empty'`: the hotkey or sequence is empty.
+ * - `'empty-part'`: a part between `+` signs is empty or whitespace.
+ * - `'unknown-modifier'`: a modifier isn't one the library knows, such as `Ctl`.
+ * - `'invalid-physical-key'`: a bracketed key isn't a `KeyboardEvent.code`.
+ * - `'modifier-only'`: the key is a modifier, such as `Shift` or `[ShiftLeft]`.
+ * - `'unknown-key'` (warning): the key isn't written like a known key name.
+ *   Key names are case-sensitive, so `escape` never matches `Escape`.
+ */
+export type HotkeyIssueReason = 'empty' | 'empty-part' | 'unknown-modifier' | 'invalid-physical-key' | 'modifier-only' | 'unknown-key';
+/** One problem found by `validateHotkey`. */
+export interface HotkeyIssue {
+  reason: HotkeyIssueReason;
+  /** The part of the chord with the problem, such as `'Ctl'` in `'Ctl+K'`. */
+  part?: string;
+  /** For a sequence, the index of the step with the problem. */
+  step?: number;
+}
 /**
  * Result of validating a hotkey string.
  */
 export interface ValidationResult {
   /** Whether the hotkey is valid (can still have warnings) */
   valid: boolean;
-  /** Warning messages about potential issues */
-  warnings: Array<string>;
-  /** Error messages about invalid syntax */
-  errors: Array<string>;
-}
-//#endregion
+  /** Problems that may stop the hotkey from firing, such as an unknown key */
+  warnings: Array<HotkeyIssue>;
+  /** Problems that stop the hotkey from registering */
+  errors: Array<HotkeyIssue>;
+}

package/dist/validate.js

@@ -1,13 +1,15 @@
-import { isKeyNameShape, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
+import { isKeyNameShape, isModifierCode, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 
-//#region src/validate.ts
+// src/validate.ts
 /**
 * Validates a hotkey and returns any warnings or errors.
-* Sequences are validated step by step, and messages name the failing step.
+* Each issue has a `reason` code, so apps can write their own messages.
+* Issues in a sequence carry the index of their `step`.
 *
 * Checks for:
 * - Valid syntax (modifier+...+key format)
 * - Known modifiers
+* - A key that isn't a modifier
 * - Known keys
 *
 * @param hotkey - The hotkey string to validate
@@ -19,55 +21,71 @@ import { isKeyNameShape, modifierAlias, physicalCodeOf, splitChordParts } from "
 * // { valid: true, warnings: [], errors: [] }
 *
 * validateHotkey('')
-* // { valid: false, warnings: [], errors: ['Hotkey cannot be empty'] }
+* // { valid: false, warnings: [], errors: [{ reason: 'empty' }] }
 *
 * validateHotkey(['G', 'Foo+H'])
-* // { valid: false, warnings: [], errors: ["Step 2: Unknown modifier: 'Foo'"] }
+* // { valid: false, warnings: [], errors: [{ reason: 'unknown-modifier', part: 'Foo', step: 1 }] }
 * ```
 */
 function validateHotkey(hotkey) {
 	if (typeof hotkey !== "string") {
-		if (hotkey.length === 0) return {
-			valid: false,
-			warnings: [],
-			errors: ["Sequence cannot be empty"]
-		};
+		if (hotkey.length === 0) return invalid("empty");
 		if (hotkey.length === 1) return validateChord(hotkey[0]);
 		const results = hotkey.map(validateChord);
-		const prefixed = (key) => results.flatMap((result, i) => result[key].map((message) => `Step ${i + 1}: ${message}`));
+		const withStep = (key) => results.flatMap((result, step) => result[key].map((issue) => ({
+			...issue,
+			step
+		})));
 		return {
 			valid: results.every((result) => result.valid),
-			warnings: prefixed("warnings"),
-			errors: prefixed("errors")
+			warnings: withStep("warnings"),
+			errors: withStep("errors")
 		};
 	}
 	return validateChord(hotkey);
 }
-function validateChord(hotkey) {
-	const warnings = [];
-	const errors = [];
-	if (!hotkey || hotkey.trim() === "") return {
+function invalid(reason) {
+	return {
 		valid: false,
 		warnings: [],
-		errors: ["Hotkey cannot be empty"]
+		errors: [{ reason }]
 	};
+}
+function validateChord(hotkey) {
+	const warnings = [];
+	const errors = [];
+	if (!hotkey || hotkey.trim() === "") return invalid("empty");
 	const parts = splitChordParts(hotkey).map((p) => p.trim());
-	if (parts.length === 0 || parts.some((p) => p === "")) return {
-		valid: false,
-		warnings: [],
-		errors: ["Invalid hotkey format: empty parts detected"]
-	};
+	if (parts.length === 0 || parts.some((p) => p === "")) return invalid("empty-part");
 	const modifierParts = parts.slice(0, -1);
 	const keyPart = parts[parts.length - 1];
-	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 (physicalCodeOf(keyPart) === void 0 && !isKeyNameShape(keyPart)) warnings.push(`Unknown key: '${keyPart}'. Key names are case-sensitive, such as 'Escape' and 'F1'.`);
+	for (const modifier of modifierParts) if (!modifierAlias(modifier)) errors.push({
+		reason: "unknown-modifier",
+		part: modifier
+	});
+	const code = physicalCodeOf(keyPart);
+	if (keyPart.length > 1 && (keyPart.startsWith("[") || keyPart.endsWith("]")) && code === void 0) errors.push({
+		reason: "invalid-physical-key",
+		part: keyPart
+	});
+	if (code !== void 0 ? isModifierCode(code) : modifierAlias(keyPart)) errors.push({
+		reason: "modifier-only",
+		part: keyPart
+	});
+	if (code === void 0 && !isKeyNameShape(keyPart)) warnings.push({
+		reason: "unknown-key",
+		part: keyPart
+	});
 	return {
 		valid: errors.length === 0,
 		warnings,
 		errors
 	};
 }
+/** Lists issues for a console message, such as `unknown-modifier 'Ctl'`. */
+function describeIssues(issues) {
+	return issues.map(({ reason, part, step }) => (step === void 0 ? "" : `step ${step + 1} `) + reason + (part === void 0 ? "" : ` '${part}'`)).join(", ");
+}
 /**
 * Validates a hotkey and throws an error if invalid.
 * Useful for development-time validation.
@@ -78,12 +96,12 @@ function validateChord(hotkey) {
 * @example
 * ```ts
 * assertValidHotkey('Mod+S') // OK
-* assertValidHotkey('') // Throws Error: Invalid hotkey: Hotkey cannot be empty
+* assertValidHotkey('') // Throws Error: [hotkeys] Invalid hotkey '': empty
 * ```
 */
 function assertValidHotkey(hotkey) {
 	const result = validateHotkey(hotkey);
-	if (!result.valid) throw new Error(`Invalid hotkey '${String(hotkey)}': ${result.errors.join(", ")}`);
+	if (!result.valid) throw new Error(`[hotkeys] Invalid hotkey '${String(hotkey)}': ${describeIssues(result.errors)}`);
 }
 /**
 * Validates a hotkey and logs errors and warnings to the console.
@@ -95,22 +113,21 @@ function assertValidHotkey(hotkey) {
 * @example
 * ```ts
 * checkHotkey('Control+escape')
-* // Console: Hotkey 'Control+escape' warnings: Unknown key: 'escape'. Key names are case-sensitive, such as 'Escape' and 'F1'.
+* // Console: [hotkeys] Hotkey 'Control+escape' may never fire: unknown-key 'escape'
 * // Returns: true
 *
 * checkHotkey('Ctl+K')
-* // Console: Hotkey 'Ctl+K' errors: Unknown modifier: 'Ctl'
+* // Console: [hotkeys] Invalid hotkey 'Ctl+K': unknown-modifier 'Ctl'
 * // Returns: false
 * ```
 */
 function checkHotkey(hotkey) {
 	const result = validateHotkey(hotkey);
-	if (process.env.NODE_ENV !== "production") {
-		if (result.errors.length > 0) console.error(`Hotkey '${String(hotkey)}' errors:`, result.errors.join("; "));
-		if (result.warnings.length > 0) console.warn(`Hotkey '${String(hotkey)}' warnings:`, result.warnings.join("; "));
+	if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+		if (result.errors.length > 0) console.error(`[hotkeys] Invalid hotkey '${String(hotkey)}': ${describeIssues(result.errors)}`);
+		if (result.warnings.length > 0) console.warn(`[hotkeys] Hotkey '${String(hotkey)}' may never fire: ${describeIssues(result.warnings)}`);
 	}
 	return result.valid;
 }
 
-//#endregion
 export { assertValidHotkey, checkHotkey, validateHotkey };

package/dist/vendor/@tanstack/store/dist/store.d.ts

@@ -1,5 +1,4 @@
 import { Observer, Subscription } from "./types.js";
-//#region ../../node_modules/.pnpm/@tanstack+store@0.11.2/node_modules/@tanstack/store/dist/store.d.ts
 //#region src/store.d.ts
 type StoreAction = (...args: Array<any>) => any;
 type StoreActionMap = Record<string, StoreAction>;
@@ -19,5 +18,4 @@ declare class Store<T, TActions extends StoreActionMap = never> {
   get(): T;
   subscribe(observerOrFn: Observer<T> | ((value: T) => void)): Subscription;
 }
-//#endregion
 export { Store, StoreAction, StoreActionMap, StoreActionsFactory };

package/dist/vendor/@tanstack/store/dist/types.d.ts

@@ -1,4 +1,3 @@
-//#region ../../node_modules/.pnpm/@tanstack+store@0.11.2/node_modules/@tanstack/store/dist/types.d.ts
 type Observer<T> = {
   next?: (value: T) => void;
   error?: (err: unknown) => void;
@@ -7,5 +6,4 @@ type Observer<T> = {
 interface Subscription {
   unsubscribe: () => void;
 }
-//#endregion
 export { Observer, Subscription };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -47,9 +47,9 @@
   },
   "scripts": {
     "clean": "premove ./build ./dist",
-    "lint": "eslint ./src",
-    "lint:fix": "eslint ./src --fix",
-    "test:eslint": "eslint ./src",
+    "lint": "oxlint ./src",
+    "lint:fix": "oxlint ./src --fix",
+    "test:oxlint": "oxlint ./src",
     "test:lib": "vitest",
     "test:lib:dev": "pnpm test:lib --watch",
     "test:types": "tsc",

package/skills/app-hotkeys/SKILL.md

@@ -52,7 +52,7 @@ Augment `Register` in the adapter module you import from, such as `declare modul
 
 - **Register the app hotkey, not its value.** Pass `appHotkeys['doc.save']`. Passing `.hotkey` registers the declared default, so the user's rebinding never applies, and the list reports the shortcut as `'inactive'`.
 - **Save what `onCustomHotkeysChange` receives.** It holds only the shortcuts the user changed, so users still get new defaults. Saving every effective hotkey freezes today's defaults into their data.
-- **Ids are a storage contract.** Saved data is keyed by id, and unknown ids are dropped with a warning, so renaming an id discards users' customizations.
+- **Ids are a storage contract.** Saved data is keyed by id, and unknown ids are silently dropped, so renaming an id discards users' customizations.
 - **`setCustomHotkey` returns conflicts and changes nothing when there are any.** Check the result before reporting success, or reject the key press earlier by calling `findConflicts` in the recorder's `validate`.
 - **Declare scopes on app hotkeys that share keys.** An app hotkey without a scope, or in `'global'`, conflicts with every other app hotkey on the same keys, so rebinding is rejected.
 - **Conflict checks treat physical and logical bindings as different.** A recorded `Mod+[KeyP]` doesn't conflict with a declared `Mod+P`, although Command+P runs both. Declaring rebindable defaults in the recorder's form, such as `Mod+[KeyP]`, makes them comparable.

package/skills/hotkeys-core/SKILL.md

@@ -59,10 +59,12 @@ When nesting scopes, stacking dialogs, or keeping some hotkeys working during an
 - **A disabled hotkey doesn't block the browser.** With `enabled: false`, `Mod+S` opens the Save Page dialog. Add `preventDefault: 'always'` to keep the action blocked while the hotkey can't fire, whether it's disabled or its scope is off. Skip it for hotkeys turned off to give the key back to the browser, such as `Mod+C`, `Mod+Z`, `Tab`, or single keys behind a user's off switch. Don't keep the hotkey enabled and return early from the callback; the hotkey would also stay `active` in app hotkey lists and show its hint.
 - **Modifiers match exactly.** `ArrowDown` never fires while Shift is held, so register `Shift+ArrowDown` instead of checking `event.shiftKey`. Shift that a symbol needs is the exception: `?` matches Shift+/.
 - **Chords repeat while held.** Set `requireReset: true` on toggles, or holding the keys flickers them.
-- **Key names are case-sensitive.** Write `Escape`, `ArrowUp`, `F1`, and `+` as the types spell them; `escape`, `Esc`, `f1`, and `Plus` never match. Only letters match in any case. Hotkeys from plain JavaScript or saved data skip the types, so check them with `validateHotkey`.
+- **Key names are case-sensitive.** Write `Escape`, `ArrowUp`, `F1`, and `+` as the types spell them; `escape`, `Esc`, `f1`, and `Plus` never match. Only letters match in any case. Hotkeys from plain JavaScript or saved data skip the types, so check them with `validateHotkey`. Its errors and warnings are reason codes such as `{ reason: 'unknown-key', part: 'escape' }`, not text, so map them to your own messages. A modifier-only hotkey, or one with an unknown modifier such as `Ctl+K`, registers nothing.
 - **Letters follow the typed character.** For position-based controls such as WASD, use physical bindings such as `'[KeyW]'`. Keep letters for mnemonic commands such as `Mod+S`.
 - **Each open exclusive scope needs its own name.** A reusable dialog with a fixed scope name breaks when one dialog opens another: both share one scope and both handle `Escape`. Build the name per instance.
 - **A chord on a sequence's first key runs every time the sequence starts.** With `G` and `['G', 'G']`, the first `G` runs the chord. Later keys belong to the sequence. To show "waiting for the next key", read `matchedStepCount` from the adapter's registrations list.
+- **A sequence that starts a longer one doesn't wait for it.** With `['G', 'G']` and `['G', 'G', 'G']`, three G presses run both, with no warning. Pick sequences where neither one starts the other.
+- **Component libraries handle Escape too.** A global `Escape` hotkey can run alongside a library's dropdown or dialog closing, or keep a library's overlay open. Native modal dialogs and popovers get Escape on their own, except `popover="manual"`: hotkeys outside them skip it. Set `ignoreDefaultPrevented: true` in the adapter's shared defaults (on each hotkey in Lit) for libraries that call `preventDefault()` before the hotkey runs, such as Radix UI and shadcn/ui in React. The option can't see a `preventDefault()` that comes after the hotkey, as in Bits UI, so give open overlays an exclusive scope for those and the rest. The sensible defaults guide lists libraries per framework.
 - **Single-character shortcuts need an off switch.** For WCAG 2.1.4, `K`, `?`, and `['G', 'H']` need a user setting passed as `enabled`, or an app hotkey users can remap.
 - **react-hotkeys-hook names don't carry over.** `useHotkeys` and `HotkeysProvider` share names, not signatures: there's no dependency array, `preventDefault` is on by default, and sequences are arrays. Remove the old library, so two libraries don't handle the same keys.
 - **Install only the adapter.** A separately installed `@tanstack/hotkeys` at another version is a second copy, and scopes don't apply across copies.