@tanstack/hotkeys 0.4.3 → 0.6.0

package/dist/parse.d.ts

@@ -1,4 +1,5 @@
-import { Hotkey, Key, ParsedHotkey, RawHotkey } from "./hotkey.js";
+import { Hotkey, Key, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.js";
+import { MODIFIER_ALIASES } from "./constants.js";
 
 //#region src/parse.d.ts
 /**
@@ -41,31 +42,43 @@ declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'win
 /**
  * Normalizes a hotkey string to its canonical form.
  *
- * The canonical form uses:
- * - Full modifier names (Control, Alt, Shift, Meta)
- * - Modifiers in order: Control+Alt+Shift+Meta
- * - Uppercase letters for single-character keys
- * - Proper casing for special keys (Escape, not escape)
+ * - When `Mod` is allowed for the platform (Command on Mac without Control;
+ *   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,
+ *   then the key (e.g. `Mod+Shift+E`, `Mod+S`).
+ * - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.
+ * - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).
  *
  * @param hotkey - The hotkey string to normalize
- * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+ * @param platform - The target platform for resolving `Mod` (defaults to auto-detection)
  * @returns The normalized hotkey string
  *
  * @example
  * ```ts
- * normalizeHotkey('mod+shift+s') // On Mac: 'Shift+Meta+S'
- * normalizeHotkey('ctrl+a') // 'Control+A'
+ * normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
+ * normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
  * normalizeHotkey('esc') // 'Escape'
  * ```
  */
-declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): string;
+declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+/**
+ * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
+ */
+declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+/**
+ * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
+ * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
+ */
+declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
- * Checks if a string represents a modifier key.
+ * Checks if a string is a recognized modifier token (including aliases).
+ *
+ * For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM
+ * spellings like `OS` / `Win` match the same alias table.
  *
- * @param key - The string to check
+ * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
  * @returns True if the string is a recognized modifier
  */
-declare function isModifier(key: string): boolean;
+declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MODIFIER_ALIASES;
 /**
  * Parses a KeyboardEvent into a ParsedHotkey object.
  *
@@ -86,48 +99,12 @@ declare function isModifier(key: string): boolean;
  */
 declare function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey;
 /**
- * Converts a KeyboardEvent directly to a hotkey string.
- *
- * This is a convenience function that combines `parseKeyboardEvent()` and formatting.
- * The resulting hotkey string uses canonical modifier names (Control, Alt, Shift, Meta)
- * and is suitable for use with `useHotkey()` and other hotkey functions.
- *
- * @param event - The KeyboardEvent to convert
- * @param platform - The target platform (defaults to auto-detection)
- * @returns A hotkey string in canonical form (e.g., 'Control+Shift+S')
+ * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
  *
- * @example
- * ```ts
- * document.addEventListener('keydown', (event) => {
- *   const hotkey = keyboardEventToHotkey(event)
- *   console.log(hotkey) // 'Control+Shift+S'
- *   useHotkey(hotkey, () => console.log('Shortcut triggered'))
- * })
- * ```
+ * @param event - The keyboard event (typically `keydown`)
+ * @param platform - Target platform for `Mod` eligibility
  */
-declare function keyboardEventToHotkey(event: KeyboardEvent): Hotkey;
-/**
- * Checks if a KeyboardEvent represents a modifier-only key press.
- *
- * Modifier-only keys are keys like 'Control', 'Shift', 'Alt', 'Meta', etc.
- * that don't have an associated character or action key. This is useful
- * for filtering out modifier key presses when recording shortcuts.
- *
- * @param event - The KeyboardEvent to check
- * @returns True if the event represents a modifier-only key
- *
- * @example
- * ```ts
- * document.addEventListener('keydown', (event) => {
- *   if (isModifierKey(event)) {
- *     console.log('Modifier key pressed, waiting for action key...')
- *     return
- *   }
- *   // Process non-modifier key
- * })
- * ```
- */
-declare function isModifierKey(event: KeyboardEvent): boolean;
+declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
  * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
  *
@@ -146,24 +123,6 @@ declare function isModifierKey(event: KeyboardEvent): boolean;
  * ```
  */
 declare function hasNonModifierKey(hotkey: Hotkey | ParsedHotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): boolean;
-/**
- * Converts a hotkey string to use 'Mod' format for portability.
- *
- * On macOS, converts 'Meta' to 'Mod'. On Windows/Linux, converts 'Control' to 'Mod'.
- * This enables cross-platform hotkey definitions that work consistently.
- *
- * @param hotkey - The hotkey string to convert
- * @param platform - The target platform (defaults to auto-detection)
- * @returns The hotkey string with 'Mod' format applied
- *
- * @example
- * ```ts
- * convertToModFormat('Meta+S', 'mac') // 'Mod+S'
- * convertToModFormat('Control+S', 'windows') // 'Mod+S'
- * convertToModFormat('Control+Meta+S', 'mac') // 'Control+Meta+S' (both present, no conversion)
- * ```
- */
-declare function convertToModFormat(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 //#endregion
-export { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
+export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
 //# sourceMappingURL=parse.d.ts.map

package/dist/parse.js

@@ -87,39 +87,67 @@ function rawHotkeyToParsedHotkey(raw, platform = detectPlatform()) {
 	};
 }
 /**
+* Serializes a parsed hotkey to the canonical string form used for registration
+* and storage: `Mod` first when the platform allows, then `Alt`, then `Shift`;
+* otherwise full `Control+Alt+Shift+Meta` order.
+*/
+function normalizedHotkeyStringFromParsed(parsed, platform) {
+	const canUseMod = platform === "mac" ? parsed.meta && !parsed.ctrl : parsed.ctrl && !parsed.meta;
+	const parts = [];
+	if (canUseMod) {
+		parts.push("Mod");
+		if (parsed.alt) parts.push("Alt");
+		if (parsed.shift) parts.push("Shift");
+	} else for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
+	parts.push(normalizeKeyName(parsed.key));
+	return parts.join("+");
+}
+/**
 * Normalizes a hotkey string to its canonical form.
 *
-* The canonical form uses:
-* - Full modifier names (Control, Alt, Shift, Meta)
-* - Modifiers in order: Control+Alt+Shift+Meta
-* - Uppercase letters for single-character keys
-* - Proper casing for special keys (Escape, not escape)
+* - When `Mod` is allowed for the platform (Command on Mac without Control;
+*   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,
+*   then the key (e.g. `Mod+Shift+E`, `Mod+S`).
+* - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.
+* - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).
 *
 * @param hotkey - The hotkey string to normalize
-* @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
+* @param platform - The target platform for resolving `Mod` (defaults to auto-detection)
 * @returns The normalized hotkey string
 *
 * @example
 * ```ts
-* normalizeHotkey('mod+shift+s') // On Mac: 'Shift+Meta+S'
-* normalizeHotkey('ctrl+a') // 'Control+A'
+* normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'
+* normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'
 * normalizeHotkey('esc') // 'Escape'
 * ```
 */
 function normalizeHotkey(hotkey, platform = detectPlatform()) {
-	const parsed = parseHotkey(hotkey, platform);
-	const parts = [];
-	for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
-	parts.push(parsed.key);
-	return parts.join("+");
+	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);
 }
 /**
-* Checks if a string represents a modifier key.
+* Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
+* Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
+*/
+function normalizeRegisterableHotkey(hotkey, platform = detectPlatform()) {
+	return typeof hotkey === "string" ? normalizeHotkey(hotkey, platform) : normalizeHotkeyFromParsed(rawHotkeyToParsedHotkey(hotkey, platform), platform);
+}
+/**
+* Checks if a string is a recognized modifier token (including aliases).
 *
-* @param key - The string to check
+* For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM
+* spellings like `OS` / `Win` match the same alias table.
+*
+* @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
 * @returns True if the string is a recognized modifier
 */
-function isModifier(key) {
+function isModifierKey(key) {
 	return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES;
 }
 /**
@@ -157,56 +185,13 @@ function parseKeyboardEvent(event) {
 	};
 }
 /**
-* Converts a KeyboardEvent directly to a hotkey string.
-*
-* This is a convenience function that combines `parseKeyboardEvent()` and formatting.
-* The resulting hotkey string uses canonical modifier names (Control, Alt, Shift, Meta)
-* and is suitable for use with `useHotkey()` and other hotkey functions.
-*
-* @param event - The KeyboardEvent to convert
-* @param platform - The target platform (defaults to auto-detection)
-* @returns A hotkey string in canonical form (e.g., 'Control+Shift+S')
-*
-* @example
-* ```ts
-* document.addEventListener('keydown', (event) => {
-*   const hotkey = keyboardEventToHotkey(event)
-*   console.log(hotkey) // 'Control+Shift+S'
-*   useHotkey(hotkey, () => console.log('Shortcut triggered'))
-* })
-* ```
-*/
-function keyboardEventToHotkey(event) {
-	const parsed = parseKeyboardEvent(event);
-	const parts = [];
-	for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
-	parts.push(parsed.key);
-	return parts.join("+");
-}
-/**
-* Checks if a KeyboardEvent represents a modifier-only key press.
+* Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
 *
-* Modifier-only keys are keys like 'Control', 'Shift', 'Alt', 'Meta', etc.
-* that don't have an associated character or action key. This is useful
-* for filtering out modifier key presses when recording shortcuts.
-*
-* @param event - The KeyboardEvent to check
-* @returns True if the event represents a modifier-only key
-*
-* @example
-* ```ts
-* document.addEventListener('keydown', (event) => {
-*   if (isModifierKey(event)) {
-*     console.log('Modifier key pressed, waiting for action key...')
-*     return
-*   }
-*   // Process non-modifier key
-* })
-* ```
+* @param event - The keyboard event (typically `keydown`)
+* @param platform - Target platform for `Mod` eligibility
 */
-function isModifierKey(event) {
-	const key = event.key;
-	return key === "Control" || key === "Shift" || key === "Alt" || key === "Meta" || key === "Command" || key === "OS" || key === "Win";
+function normalizeHotkeyFromEvent(event, platform = detectPlatform()) {
+	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform);
 }
 /**
 * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
@@ -227,32 +212,9 @@ function isModifierKey(event) {
 */
 function hasNonModifierKey(hotkey, platform = detectPlatform()) {
 	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
-	return !isModifier(parsed.key) && parsed.key.length > 0;
-}
-/**
-* Converts a hotkey string to use 'Mod' format for portability.
-*
-* On macOS, converts 'Meta' to 'Mod'. On Windows/Linux, converts 'Control' to 'Mod'.
-* This enables cross-platform hotkey definitions that work consistently.
-*
-* @param hotkey - The hotkey string to convert
-* @param platform - The target platform (defaults to auto-detection)
-* @returns The hotkey string with 'Mod' format applied
-*
-* @example
-* ```ts
-* convertToModFormat('Meta+S', 'mac') // 'Mod+S'
-* convertToModFormat('Control+S', 'windows') // 'Mod+S'
-* convertToModFormat('Control+Meta+S', 'mac') // 'Control+Meta+S' (both present, no conversion)
-* ```
-*/
-function convertToModFormat(hotkey, platform = detectPlatform()) {
-	const parsed = parseHotkey(hotkey, platform);
-	if (platform === "mac" && parsed.meta && !parsed.ctrl) return hotkey.split("+").map((part) => part === "Meta" ? "Mod" : part).join("+");
-	else if (platform !== "mac" && parsed.ctrl && !parsed.meta) return hotkey.split("+").map((part) => part === "Control" ? "Mod" : part).join("+");
-	return hotkey;
+	return !isModifierKey(parsed.key) && parsed.key.length > 0;
 }
 
 //#endregion
-export { convertToModFormat, hasNonModifierKey, isModifier, isModifierKey, keyboardEventToHotkey, normalizeHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
+export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
 //# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse.js","names":[],"sources":["../src/parse.ts"],"sourcesContent":["import {\n  MODIFIER_ALIASES,\n  MODIFIER_ORDER,\n  detectPlatform,\n  normalizeKeyName,\n  resolveModifier,\n} from './constants'\nimport type {\n  CanonicalModifier,\n  Hotkey,\n  Key,\n  ParsedHotkey,\n  RawHotkey,\n} from './hotkey'\n\n/**\n * Parses a hotkey string into its component parts.\n *\n * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey object with the key and modifier flags\n *\n * @example\n * ```ts\n * parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n * parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }\n * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function parseHotkey(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  const parts = hotkey.split('+')\n  const modifiers: Set<CanonicalModifier> = new Set()\n  let key = ''\n\n  for (let i = 0; i < parts.length; i++) {\n    const part = parts[i]!.trim()\n\n    if (i === parts.length - 1) {\n      // Last part is always the key\n      key = normalizeKeyName(part)\n    } else {\n      // All other parts are modifiers\n      const alias =\n        MODIFIER_ALIASES[part] ?? MODIFIER_ALIASES[part.toLowerCase()]\n\n      if (alias) {\n        const resolved = resolveModifier(alias, platform)\n        modifiers.add(resolved)\n      } else {\n        // Unknown modifier, treat as part of the key if it's the only part\n        // or ignore if there are more parts\n        if (parts.length === 1) {\n          key = normalizeKeyName(part)\n        }\n      }\n    }\n  }\n\n  // If no key was found (empty string), use the last part as-is\n  if (!key && parts.length > 0) {\n    key = normalizeKeyName(parts[parts.length - 1]!.trim())\n  }\n\n  return {\n    key,\n    ctrl: modifiers.has('Control'),\n    shift: modifiers.has('Shift'),\n    alt: modifiers.has('Alt'),\n    meta: modifiers.has('Meta'),\n    modifiers: MODIFIER_ORDER.filter((m) => modifiers.has(m)),\n  }\n}\n\n/**\n * Converts a RawHotkey object to a ParsedHotkey.\n * Optional modifier booleans default to false; modifiers array is derived from them.\n * When `mod` is true, it is resolved to Control or Meta based on platform.\n *\n * @param raw - The raw hotkey object\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey suitable for matching and formatting\n *\n * @example\n * ```ts\n * rawHotkeyToParsedHotkey({ key: 'Escape' })\n * // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')\n * // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')\n * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function rawHotkeyToParsedHotkey(\n  raw: RawHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  let ctrl = raw.ctrl ?? false\n  const shift = raw.shift ?? false\n  const alt = raw.alt ?? false\n  let meta = raw.meta ?? false\n\n  if (raw.mod) {\n    const resolved = resolveModifier('Mod', platform)\n    if (resolved === 'Control') {\n      ctrl = true\n    } else {\n      meta = true\n    }\n  }\n\n  const modifiers: Array<CanonicalModifier> = MODIFIER_ORDER.filter((m) => {\n    switch (m) {\n      case 'Control':\n        return ctrl\n      case 'Shift':\n        return shift\n      case 'Alt':\n        return alt\n      case 'Meta':\n        return meta\n      default:\n        return false\n    }\n  })\n  return {\n    key: raw.key,\n    ctrl,\n    shift,\n    alt,\n    meta,\n    modifiers,\n  }\n}\n\n/**\n * Normalizes a hotkey string to its canonical form.\n *\n * The canonical form uses:\n * - Full modifier names (Control, Alt, Shift, Meta)\n * - Modifiers in order: Control+Alt+Shift+Meta\n * - Uppercase letters for single-character keys\n * - Proper casing for special keys (Escape, not escape)\n *\n * @param hotkey - The hotkey string to normalize\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns The normalized hotkey string\n *\n * @example\n * ```ts\n * normalizeHotkey('mod+shift+s') // On Mac: 'Shift+Meta+S'\n * normalizeHotkey('ctrl+a') // 'Control+A'\n * normalizeHotkey('esc') // 'Escape'\n * ```\n */\nexport function normalizeHotkey(\n  hotkey: Key | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): string {\n  const parsed = parseHotkey(hotkey, platform)\n  const parts: Array<string> = []\n\n  // Add modifiers in canonical order\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(modifier)\n    }\n  }\n\n  // Add the key\n  parts.push(parsed.key)\n\n  return parts.join('+')\n}\n\n/**\n * Checks if a string represents a modifier key.\n *\n * @param key - The string to check\n * @returns True if the string is a recognized modifier\n */\nexport function isModifier(key: string): boolean {\n  return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES\n}\n\n/**\n * Parses a KeyboardEvent into a ParsedHotkey object.\n *\n * This function extracts the key and modifier state from a keyboard event\n * and converts it into the same format used by `parseHotkey()`.\n *\n * @param event - The KeyboardEvent to parse\n * @param platform - The target platform for resolving modifiers (defaults to auto-detection)\n * @returns A ParsedHotkey object representing the keyboard event\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   const parsed = parseKeyboardEvent(event)\n *   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }\n * })\n * ```\n */\nexport function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey {\n  const normalizedKey = normalizeKeyName(event.key)\n\n  // Build modifiers array in canonical order\n  const modifiers: Array<CanonicalModifier> = []\n  if (event.ctrlKey) modifiers.push('Control')\n  if (event.altKey) modifiers.push('Alt')\n  if (event.shiftKey) modifiers.push('Shift')\n  if (event.metaKey) modifiers.push('Meta')\n\n  return {\n    key: normalizedKey,\n    ctrl: event.ctrlKey,\n    shift: event.shiftKey,\n    alt: event.altKey,\n    meta: event.metaKey,\n    modifiers,\n  }\n}\n\n/**\n * Converts a KeyboardEvent directly to a hotkey string.\n *\n * This is a convenience function that combines `parseKeyboardEvent()` and formatting.\n * The resulting hotkey string uses canonical modifier names (Control, Alt, Shift, Meta)\n * and is suitable for use with `useHotkey()` and other hotkey functions.\n *\n * @param event - The KeyboardEvent to convert\n * @param platform - The target platform (defaults to auto-detection)\n * @returns A hotkey string in canonical form (e.g., 'Control+Shift+S')\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   const hotkey = keyboardEventToHotkey(event)\n *   console.log(hotkey) // 'Control+Shift+S'\n *   useHotkey(hotkey, () => console.log('Shortcut triggered'))\n * })\n * ```\n */\nexport function keyboardEventToHotkey(event: KeyboardEvent): Hotkey {\n  const parsed = parseKeyboardEvent(event)\n\n  // Build hotkey string in canonical order (same as formatHotkey)\n  const parts: Array<string> = []\n  for (const modifier of MODIFIER_ORDER) {\n    if (parsed.modifiers.includes(modifier)) {\n      parts.push(modifier)\n    }\n  }\n  parts.push(parsed.key)\n\n  return parts.join('+') as Hotkey\n}\n\n/**\n * Checks if a KeyboardEvent represents a modifier-only key press.\n *\n * Modifier-only keys are keys like 'Control', 'Shift', 'Alt', 'Meta', etc.\n * that don't have an associated character or action key. This is useful\n * for filtering out modifier key presses when recording shortcuts.\n *\n * @param event - The KeyboardEvent to check\n * @returns True if the event represents a modifier-only key\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   if (isModifierKey(event)) {\n *     console.log('Modifier key pressed, waiting for action key...')\n *     return\n *   }\n *   // Process non-modifier key\n * })\n * ```\n */\nexport function isModifierKey(event: KeyboardEvent): boolean {\n  const key = event.key\n  return (\n    key === 'Control' ||\n    key === 'Shift' ||\n    key === 'Alt' ||\n    key === 'Meta' ||\n    key === 'Command' ||\n    key === 'OS' ||\n    key === 'Win'\n  )\n}\n\n/**\n * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.\n *\n * This is useful for validating that a recorded hotkey is complete and not\n * just a combination of modifiers without an action key.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to check\n * @param platform - The target platform for parsing (defaults to auto-detection)\n * @returns True if the hotkey contains at least one non-modifier key\n *\n * @example\n * ```ts\n * hasNonModifierKey('Control+Shift+S') // true\n * hasNonModifierKey('Control+Shift') // false (no action key)\n * hasNonModifierKey(parseHotkey('Mod+A')) // true\n * ```\n */\nexport function hasNonModifierKey(\n  hotkey: Hotkey | ParsedHotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check if the key part is actually a modifier\n  const keyIsModifier = isModifier(parsed.key)\n\n  // A valid hotkey must have a non-modifier key\n  return !keyIsModifier && parsed.key.length > 0\n}\n\n/**\n * Converts a hotkey string to use 'Mod' format for portability.\n *\n * On macOS, converts 'Meta' to 'Mod'. On Windows/Linux, converts 'Control' to 'Mod'.\n * This enables cross-platform hotkey definitions that work consistently.\n *\n * @param hotkey - The hotkey string to convert\n * @param platform - The target platform (defaults to auto-detection)\n * @returns The hotkey string with 'Mod' format applied\n *\n * @example\n * ```ts\n * convertToModFormat('Meta+S', 'mac') // 'Mod+S'\n * convertToModFormat('Control+S', 'windows') // 'Mod+S'\n * convertToModFormat('Control+Meta+S', 'mac') // 'Control+Meta+S' (both present, no conversion)\n * ```\n */\nexport function convertToModFormat(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  const parsed = parseHotkey(hotkey, platform)\n\n  // Only convert if we have exactly one primary modifier\n  if (platform === 'mac' && parsed.meta && !parsed.ctrl) {\n    // Convert Meta to Mod on Mac\n    const parts = hotkey.split('+')\n    return parts\n      .map((part) => (part === 'Meta' ? 'Mod' : part))\n      .join('+') as Hotkey\n  } else if (platform !== 'mac' && parsed.ctrl && !parsed.meta) {\n    // Convert Control to Mod on Windows/Linux\n    const parts = hotkey.split('+')\n    return parts\n      .map((part) => (part === 'Control' ? 'Mod' : part))\n      .join('+') as Hotkey\n  }\n\n  // No conversion needed\n  return hotkey as Hotkey\n}\n"],"mappings":"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"}
+{"version":3,"file":"parse.js","names":[],"sources":["../src/parse.ts"],"sourcesContent":["import {\n  MODIFIER_ALIASES,\n  MODIFIER_ORDER,\n  detectPlatform,\n  normalizeKeyName,\n  resolveModifier,\n} from './constants'\nimport type {\n  CanonicalModifier,\n  Hotkey,\n  Key,\n  ParsedHotkey,\n  RawHotkey,\n  RegisterableHotkey,\n} from './hotkey'\n\n/**\n * Parses a hotkey string into its component parts.\n *\n * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey object with the key and modifier flags\n *\n * @example\n * ```ts\n * parseHotkey('Mod+S') // On Mac: { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n * parseHotkey('Mod+S') // On Windows: { key: 'S', ctrl: true, shift: false, alt: false, meta: false, modifiers: ['Control'] }\n * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function parseHotkey(\n  hotkey: Hotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  const parts = hotkey.split('+')\n  const modifiers: Set<CanonicalModifier> = new Set()\n  let key = ''\n\n  for (let i = 0; i < parts.length; i++) {\n    const part = parts[i]!.trim()\n\n    if (i === parts.length - 1) {\n      // Last part is always the key\n      key = normalizeKeyName(part)\n    } else {\n      // All other parts are modifiers\n      const alias =\n        MODIFIER_ALIASES[part] ?? MODIFIER_ALIASES[part.toLowerCase()]\n\n      if (alias) {\n        const resolved = resolveModifier(alias, platform)\n        modifiers.add(resolved)\n      } else {\n        // Unknown modifier, treat as part of the key if it's the only part\n        // or ignore if there are more parts\n        if (parts.length === 1) {\n          key = normalizeKeyName(part)\n        }\n      }\n    }\n  }\n\n  // If no key was found (empty string), use the last part as-is\n  if (!key && parts.length > 0) {\n    key = normalizeKeyName(parts[parts.length - 1]!.trim())\n  }\n\n  return {\n    key,\n    ctrl: modifiers.has('Control'),\n    shift: modifiers.has('Shift'),\n    alt: modifiers.has('Alt'),\n    meta: modifiers.has('Meta'),\n    modifiers: MODIFIER_ORDER.filter((m) => modifiers.has(m)),\n  }\n}\n\n/**\n * Converts a RawHotkey object to a ParsedHotkey.\n * Optional modifier booleans default to false; modifiers array is derived from them.\n * When `mod` is true, it is resolved to Control or Meta based on platform.\n *\n * @param raw - The raw hotkey object\n * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)\n * @returns A ParsedHotkey suitable for matching and formatting\n *\n * @example\n * ```ts\n * rawHotkeyToParsedHotkey({ key: 'Escape' })\n * // { key: 'Escape', ctrl: false, shift: false, alt: false, meta: false, modifiers: [] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true }, 'mac')\n * // { key: 'S', ctrl: false, shift: false, alt: false, meta: true, modifiers: ['Meta'] }\n *\n * rawHotkeyToParsedHotkey({ key: 'S', mod: true, shift: true }, 'windows')\n * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }\n * ```\n */\nexport function rawHotkeyToParsedHotkey(\n  raw: RawHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): ParsedHotkey {\n  let ctrl = raw.ctrl ?? false\n  const shift = raw.shift ?? false\n  const alt = raw.alt ?? false\n  let meta = raw.meta ?? false\n\n  if (raw.mod) {\n    const resolved = resolveModifier('Mod', platform)\n    if (resolved === 'Control') {\n      ctrl = true\n    } else {\n      meta = true\n    }\n  }\n\n  const modifiers: Array<CanonicalModifier> = MODIFIER_ORDER.filter((m) => {\n    switch (m) {\n      case 'Control':\n        return ctrl\n      case 'Shift':\n        return shift\n      case 'Alt':\n        return alt\n      case 'Meta':\n        return meta\n      default:\n        return false\n    }\n  })\n  return {\n    key: raw.key,\n    ctrl,\n    shift,\n    alt,\n    meta,\n    modifiers,\n  }\n}\n\n/**\n * Serializes a parsed hotkey to the canonical string form used for registration\n * and storage: `Mod` first when the platform allows, then `Alt`, then `Shift`;\n * otherwise full `Control+Alt+Shift+Meta` order.\n */\nfunction normalizedHotkeyStringFromParsed(\n  parsed: ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux',\n): Hotkey {\n  const canUseMod =\n    platform === 'mac'\n      ? parsed.meta && !parsed.ctrl\n      : parsed.ctrl && !parsed.meta\n\n  const parts: Array<string> = []\n\n  if (canUseMod) {\n    parts.push('Mod')\n    if (parsed.alt) {\n      parts.push('Alt')\n    }\n    if (parsed.shift) {\n      parts.push('Shift')\n    }\n  } else {\n    for (const modifier of MODIFIER_ORDER) {\n      if (parsed.modifiers.includes(modifier)) {\n        parts.push(modifier)\n      }\n    }\n  }\n\n  parts.push(normalizeKeyName(parsed.key))\n  return parts.join('+') as Hotkey\n}\n\n/**\n * Normalizes a hotkey string to its canonical form.\n *\n * - When `Mod` is allowed for the platform (Command on Mac without Control;\n *   Control on Windows/Linux without Meta): emits `Mod`, then `Alt`, then `Shift`,\n *   then the key (e.g. `Mod+Shift+E`, `Mod+S`).\n * - Otherwise: literal modifiers in `Control+Alt+Shift+Meta` order, then the key.\n * - Resolves aliases and normalizes key casing (e.g. `esc` → `Escape`, `a` → `A`).\n *\n * @param hotkey - The hotkey string to normalize\n * @param platform - The target platform for resolving `Mod` (defaults to auto-detection)\n * @returns The normalized hotkey string\n *\n * @example\n * ```ts\n * normalizeHotkey('shift+meta+e', 'mac') // 'Mod+Shift+E'\n * normalizeHotkey('ctrl+a', 'windows') // 'Mod+A'\n * normalizeHotkey('esc') // 'Escape'\n * ```\n */\nexport function normalizeHotkey(\n  hotkey: Key | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return normalizedHotkeyStringFromParsed(\n    parseHotkey(hotkey, platform),\n    platform,\n  )\n}\n\n/**\n * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.\n */\nexport function normalizeHotkeyFromParsed(\n  parsed: ParsedHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return normalizedHotkeyStringFromParsed(parsed, platform)\n}\n\n/**\n * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.\n * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.\n */\nexport function normalizeRegisterableHotkey(\n  hotkey: RegisterableHotkey,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return typeof hotkey === 'string'\n    ? normalizeHotkey(hotkey, platform)\n    : normalizeHotkeyFromParsed(\n        rawHotkeyToParsedHotkey(hotkey, platform),\n        platform,\n      )\n}\n\n/**\n * Checks if a string is a recognized modifier token (including aliases).\n *\n * For a `KeyboardEvent`, use `isModifier(normalizeKeyName(event.key))` so DOM\n * spellings like `OS` / `Win` match the same alias table.\n *\n * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)\n * @returns True if the string is a recognized modifier\n */\nexport function isModifierKey(\n  key: Key | (string & {}),\n): key is keyof typeof MODIFIER_ALIASES {\n  return key in MODIFIER_ALIASES || key.toLowerCase() in MODIFIER_ALIASES\n}\n\n/**\n * Parses a KeyboardEvent into a ParsedHotkey object.\n *\n * This function extracts the key and modifier state from a keyboard event\n * and converts it into the same format used by `parseHotkey()`.\n *\n * @param event - The KeyboardEvent to parse\n * @param platform - The target platform for resolving modifiers (defaults to auto-detection)\n * @returns A ParsedHotkey object representing the keyboard event\n *\n * @example\n * ```ts\n * document.addEventListener('keydown', (event) => {\n *   const parsed = parseKeyboardEvent(event)\n *   console.log(parsed) // { key: 'S', ctrl: true, shift: false, ... }\n * })\n * ```\n */\nexport function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey {\n  const normalizedKey = normalizeKeyName(event.key)\n\n  // Build modifiers array in canonical order\n  const modifiers: Array<CanonicalModifier> = []\n  if (event.ctrlKey) modifiers.push('Control')\n  if (event.altKey) modifiers.push('Alt')\n  if (event.shiftKey) modifiers.push('Shift')\n  if (event.metaKey) modifiers.push('Meta')\n\n  return {\n    key: normalizedKey,\n    ctrl: event.ctrlKey,\n    shift: event.shiftKey,\n    alt: event.altKey,\n    meta: event.metaKey,\n    modifiers,\n  }\n}\n\n/**\n * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.\n *\n * @param event - The keyboard event (typically `keydown`)\n * @param platform - Target platform for `Mod` eligibility\n */\nexport function normalizeHotkeyFromEvent(\n  event: KeyboardEvent,\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): Hotkey {\n  return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform)\n}\n\n/**\n * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.\n *\n * This is useful for validating that a recorded hotkey is complete and not\n * just a combination of modifiers without an action key.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to check\n * @param platform - The target platform for parsing (defaults to auto-detection)\n * @returns True if the hotkey contains at least one non-modifier key\n *\n * @example\n * ```ts\n * hasNonModifierKey('Control+Shift+S') // true\n * hasNonModifierKey('Control+Shift') // false (no action key)\n * hasNonModifierKey(parseHotkey('Mod+A')) // true\n * ```\n */\nexport function hasNonModifierKey(\n  hotkey: Hotkey | ParsedHotkey | (string & {}),\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): boolean {\n  const parsed =\n    typeof hotkey === 'string' ? parseHotkey(hotkey, platform) : hotkey\n\n  // Check if the key part is actually a modifier\n  const keyIsModifier = isModifierKey(parsed.key)\n\n  // A valid hotkey must have a non-modifier key\n  return !keyIsModifier && parsed.key.length > 0\n}\n"],"mappings":"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"}

package/dist/recorder-chord.cjs

@@ -0,0 +1,18 @@
+const require_constants = require('./constants.cjs');
+const require_parse = require('./parse.cjs');
+
+//#region src/recorder-chord.ts
+/**
+* Parses a keydown event into a single normalized hotkey chord, or null if
+* the event should be ignored (modifier-only or invalid).
+*/
+function hotkeyChordFromKeydown(event, platform) {
+	if (require_parse.isModifierKey(require_constants.normalizeKeyName(event.key))) return null;
+	const finalHotkey = require_parse.normalizeHotkeyFromEvent(event, platform);
+	if (!require_parse.hasNonModifierKey(finalHotkey, platform)) return null;
+	return finalHotkey;
+}
+
+//#endregion
+exports.hotkeyChordFromKeydown = hotkeyChordFromKeydown;
+//# sourceMappingURL=recorder-chord.cjs.map

package/dist/recorder-chord.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder-chord.cjs","names":["isModifierKey","normalizeKeyName","normalizeHotkeyFromEvent","hasNonModifierKey"],"sources":["../src/recorder-chord.ts"],"sourcesContent":["import { normalizeKeyName } from './constants'\nimport {\n  hasNonModifierKey,\n  isModifierKey,\n  normalizeHotkeyFromEvent,\n} from './parse'\nimport type { Hotkey } from './hotkey'\n\n/**\n * Parses a keydown event into a single normalized hotkey chord, or null if\n * the event should be ignored (modifier-only or invalid).\n */\nexport function hotkeyChordFromKeydown(\n  event: KeyboardEvent,\n  platform: 'mac' | 'windows' | 'linux',\n): Hotkey | null {\n  if (isModifierKey(normalizeKeyName(event.key))) {\n    return null\n  }\n  const finalHotkey = normalizeHotkeyFromEvent(event, platform)\n  if (!hasNonModifierKey(finalHotkey, platform)) {\n    return null\n  }\n  return finalHotkey\n}\n"],"mappings":";;;;;;;;AAYA,SAAgB,uBACd,OACA,UACe;AACf,KAAIA,4BAAcC,mCAAiB,MAAM,IAAI,CAAC,CAC5C,QAAO;CAET,MAAM,cAAcC,uCAAyB,OAAO,SAAS;AAC7D,KAAI,CAACC,gCAAkB,aAAa,SAAS,CAC3C,QAAO;AAET,QAAO"}

package/dist/recorder-chord.js

@@ -0,0 +1,18 @@
+import { normalizeKeyName } from "./constants.js";
+import { hasNonModifierKey, isModifierKey, normalizeHotkeyFromEvent } from "./parse.js";
+
+//#region src/recorder-chord.ts
+/**
+* Parses a keydown event into a single normalized hotkey chord, or null if
+* the event should be ignored (modifier-only or invalid).
+*/
+function hotkeyChordFromKeydown(event, platform) {
+	if (isModifierKey(normalizeKeyName(event.key))) return null;
+	const finalHotkey = normalizeHotkeyFromEvent(event, platform);
+	if (!hasNonModifierKey(finalHotkey, platform)) return null;
+	return finalHotkey;
+}
+
+//#endregion
+export { hotkeyChordFromKeydown };
+//# sourceMappingURL=recorder-chord.js.map

package/dist/recorder-chord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder-chord.js","names":[],"sources":["../src/recorder-chord.ts"],"sourcesContent":["import { normalizeKeyName } from './constants'\nimport {\n  hasNonModifierKey,\n  isModifierKey,\n  normalizeHotkeyFromEvent,\n} from './parse'\nimport type { Hotkey } from './hotkey'\n\n/**\n * Parses a keydown event into a single normalized hotkey chord, or null if\n * the event should be ignored (modifier-only or invalid).\n */\nexport function hotkeyChordFromKeydown(\n  event: KeyboardEvent,\n  platform: 'mac' | 'windows' | 'linux',\n): Hotkey | null {\n  if (isModifierKey(normalizeKeyName(event.key))) {\n    return null\n  }\n  const finalHotkey = normalizeHotkeyFromEvent(event, platform)\n  if (!hasNonModifierKey(finalHotkey, platform)) {\n    return null\n  }\n  return finalHotkey\n}\n"],"mappings":";;;;;;;;AAYA,SAAgB,uBACd,OACA,UACe;AACf,KAAI,cAAc,iBAAiB,MAAM,IAAI,CAAC,CAC5C,QAAO;CAET,MAAM,cAAc,yBAAyB,OAAO,SAAS;AAC7D,KAAI,CAAC,kBAAkB,aAAa,SAAS,CAC3C,QAAO;AAET,QAAO"}

package/dist/sequence-manager.cjs

@@ -8,6 +8,7 @@ let _tanstack_store = require("@tanstack/store");
 //#region src/sequence-manager.ts
 /**
 * Default timeout between keys in a sequence (in milliseconds).
+* Exported for consumers that display sequence state (e.g. devtools).
 */
 const DEFAULT_SEQUENCE_TIMEOUT = 1e3;
 let sequenceIdCounter = 0;
@@ -52,12 +53,16 @@ function sequenceKey(sequence) {
 * Builds a devtools view from an internal registration.
 */
 function toRegistrationView(reg) {
+	const len = reg.parsedSequence.length;
+	const inProgress = reg.currentIndex > 0 && reg.currentIndex < len;
 	return {
 		id: reg.id,
 		sequence: reg.sequence,
 		options: reg.options,
 		target: reg.target,
-		triggerCount: reg.triggerCount
+		triggerCount: reg.triggerCount,
+		matchedStepCount: inProgress ? reg.currentIndex : 0,
+		partialMatchLastKeyTime: inProgress ? reg.lastKeyTime : 0
 	};
 }
 var SequenceManager = class SequenceManager {
@@ -86,6 +91,9 @@ var SequenceManager = class SequenceManager {
 			SequenceManager.#instance = null;
 		}
 	}
+	#syncRegistrationView(registration) {
+		this.registrations.setState((prev) => new Map(prev).set(registration.id, toRegistrationView(registration)));
+	}
 	/**
 	* Registers a hotkey sequence handler.
 	*
@@ -223,7 +231,7 @@ var SequenceManager = class SequenceManager {
 	* Processes keyboard events for a specific target and event type.
 	*/
 	#processTargetEvent(event, target, eventType) {
-		if (require_parse.isModifierKey(event)) return;
+		if (require_parse.isModifierKey(require_constants.normalizeKeyName(event.key))) return;
 		const targetRegs = this.#targetRegistrations.get(target);
 		if (!targetRegs) return;
 		const now = Date.now();
@@ -238,8 +246,11 @@ var SequenceManager = class SequenceManager {
 				}
 			}
 			if (registration.options.eventType !== eventType) continue;
-			const timeout = registration.options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT;
-			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) registration.currentIndex = 0;
+			const timeout = registration.options.timeout ?? 1e3;
+			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
+				registration.currentIndex = 0;
+				this.#syncRegistrationView(registration);
+			}
 			const expectedHotkey = registration.parsedSequence[registration.currentIndex];
 			if (!expectedHotkey) continue;
 			if (require_match.matchesKeyboardEvent(event, expectedHotkey, registration.options.platform)) {
@@ -252,15 +263,18 @@ var SequenceManager = class SequenceManager {
 						hotkey: registration.sequence.join(" "),
 						parsedHotkey: registration.parsedSequence[registration.parsedSequence.length - 1]
 					};
-					registration.callback(event, context);
+					registration.triggerCount++;
 					registration.currentIndex = 0;
-				}
+					this.#syncRegistrationView(registration);
+					registration.callback(event, context);
+				} else this.#syncRegistrationView(registration);
 			} else if (registration.currentIndex > 0) {
 				const firstHotkey = registration.parsedSequence[0];
 				if (require_match.matchesKeyboardEvent(event, firstHotkey, registration.options.platform)) {
 					registration.currentIndex = 1;
 					registration.lastKeyTime = now;
 				} else registration.currentIndex = 0;
+				this.#syncRegistrationView(registration);
 			}
 		}
 	}
@@ -279,6 +293,7 @@ var SequenceManager = class SequenceManager {
 		for (const registration of this.#registrations.values()) {
 			registration.currentIndex = 0;
 			registration.lastKeyTime = 0;
+			this.#syncRegistrationView(registration);
 		}
 	}
 	/**
@@ -303,7 +318,7 @@ var SequenceManager = class SequenceManager {
 			cancelable: true
 		});
 		registration.triggerCount++;
-		this.registrations.setState((prev) => new Map(prev).set(id, toRegistrationView(registration)));
+		this.#syncRegistrationView(registration);
 		const context = {
 			hotkey: registration.sequence.join(" "),
 			parsedHotkey: lastParsed
@@ -357,7 +372,7 @@ function getSequenceManager() {
 */
 function createSequenceMatcher(sequence, options = {}) {
 	const platform = options.platform ?? require_constants.detectPlatform();
-	const timeout = options.timeout ?? DEFAULT_SEQUENCE_TIMEOUT;
+	const timeout = options.timeout ?? 1e3;
 	const parsedSequence = sequence.map((hotkey) => require_parse.parseHotkey(hotkey, platform));
 	let currentIndex = 0;
 	let lastKeyTime = 0;
@@ -391,6 +406,7 @@ function createSequenceMatcher(sequence, options = {}) {
 }
 
 //#endregion
+exports.DEFAULT_SEQUENCE_TIMEOUT = DEFAULT_SEQUENCE_TIMEOUT;
 exports.SequenceManager = SequenceManager;
 exports.createSequenceMatcher = createSequenceMatcher;
 exports.getSequenceManager = getSequenceManager;