@tanstack/hotkeys 0.8.0 → 0.9.0

package/dist/format.js

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

package/dist/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","names":[],"sources":["../src/format.ts"],"sourcesContent":["import {\n  KEY_DISPLAY_SYMBOLS,\n  LINUX_MODIFIER_LABELS,\n  MAC_MODIFIER_LABELS,\n  MAC_MODIFIER_SYMBOLS,\n  MODIFIER_ALIASES,\n  MODIFIER_ORDER,\n  PUNCTUATION_KEY_DISPLAY_LABELS,\n  WINDOWS_MODIFIER_LABELS,\n  detectPlatform,\n} from './constants'\nimport {\n  isModifierKey,\n  normalizeHotkeyFromParsed,\n  normalizeRegisterableHotkey,\n} from './parse'\nimport type {\n  CanonicalModifier,\n  FormatDisplayOptions,\n  Hotkey,\n  ParsedHotkey,\n  RegisterableHotkey,\n} from './hotkey'\n\n/**\n * Converts a hotkey sequence array to a display string.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @returns A space-separated string (e.g. ['G','G'] → 'G G')\n *\n * @example\n * ```ts\n * formatHotkeySequence(['G', 'G'])      // 'G G'\n * formatHotkeySequence(['D', 'I', 'W']) // 'D I W'\n * ```\n */\nexport function formatHotkeySequence(sequence: Array<Hotkey>): string {\n  return sequence.join(' ')\n}\n\n/**\n * Converts a ParsedHotkey back to a hotkey string.\n *\n * @param parsed - The parsed hotkey object\n * @returns A hotkey string in canonical form\n *\n * @example\n * ```ts\n * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })\n * // Returns: 'Control+Shift+S'\n * ```\n */\nexport function formatHotkey(parsed: ParsedHotkey): string {\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 * Formats a hotkey for display in a user interface.\n *\n * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.\n * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.\n * The separator can be customized with `separatorToken`.\n *\n * @param hotkey - The hotkey string or ParsedHotkey to format\n * @param options - Formatting options\n * @returns A formatted string suitable for display\n *\n * @example\n * ```ts\n * formatForDisplay('Mod+Shift+S', { platform: 'mac' })\n * // Returns: '⌘ ⇧ S' (symbols separated by spaces on macOS)\n *\n * formatForDisplay('Mod+Shift+S', { platform: 'windows' })\n * // Returns: 'Ctrl+Shift+S'\n *\n * formatForDisplay('Escape')\n * // Returns: 'Esc' (on all platforms)\n * ```\n */\nexport function formatForDisplay(\n  hotkey: RegisterableHotkey | (string & {}),\n  options: FormatDisplayOptions = {},\n): string {\n  const platform = options.platform ?? detectPlatform()\n  const useSymbols = options.useSymbols ?? true\n  const separatorToken =\n    options.separatorToken ?? (platform === 'mac' && useSymbols ? ' ' : '+')\n  const normalizedHotkey = normalizeRegisterableHotkey(\n    hotkey as RegisterableHotkey,\n    platform,\n  )\n  return normalizedHotkey\n    .split('+')\n    .map((segment) => {\n      if (isModifierKey(segment)) {\n        const modifierToken = (MODIFIER_ALIASES[segment] ??\n          MODIFIER_ALIASES[segment.toLowerCase()]) as CanonicalModifier | 'Mod'\n        return platform === 'mac'\n          ? useSymbols\n            ? MAC_MODIFIER_SYMBOLS[modifierToken]\n            : MAC_MODIFIER_LABELS[modifierToken]\n          : platform === 'windows'\n            ? WINDOWS_MODIFIER_LABELS[modifierToken]\n            : LINUX_MODIFIER_LABELS[modifierToken]\n      } else {\n        const keyDisplaySymbol =\n          useSymbols &&\n          KEY_DISPLAY_SYMBOLS[segment as keyof typeof KEY_DISPLAY_SYMBOLS]\n        if (keyDisplaySymbol) return keyDisplaySymbol\n\n        const punctuationKeyDisplayLabel =\n          !useSymbols &&\n          PUNCTUATION_KEY_DISPLAY_LABELS[\n            segment as keyof typeof PUNCTUATION_KEY_DISPLAY_LABELS\n          ]\n        return punctuationKeyDisplayLabel || segment\n      }\n    })\n    .join(separatorToken)\n}\n\n/**\n * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.\n */\nexport function formatWithLabels(\n  hotkey: RegisterableHotkey,\n  options: Omit<FormatDisplayOptions, 'useSymbols'> = {},\n): string {\n  return formatForDisplay(hotkey, { ...options, useSymbols: false })\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAoCA,SAAgB,qBAAqB,UAAiC;AACpE,QAAO,SAAS,KAAK,IAAI;;;;;;;;;;;;;;AAe3B,SAAgB,aAAa,QAA8B;CACzD,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,SAAS;AAKxB,OAAM,KAAK,OAAO,IAAI;AAEtB,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;AA0BxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EAC1B;CACR,MAAM,WAAW,QAAQ,YAAY,gBAAgB;CACrD,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,iBACJ,QAAQ,mBAAmB,aAAa,SAAS,aAAa,MAAM;AAKtE,QAJyB,4BACvB,QACA,SACD,CAEE,MAAM,IAAI,CACV,KAAK,YAAY;AAChB,MAAI,cAAc,QAAQ,EAAE;GAC1B,MAAM,gBAAiB,iBAAiB,YACtC,iBAAiB,QAAQ,aAAa;AACxC,UAAO,aAAa,QAChB,aACE,qBAAqB,iBACrB,oBAAoB,iBACtB,aAAa,YACX,wBAAwB,iBACxB,sBAAsB;SACvB;GACL,MAAM,mBACJ,cACA,oBAAoB;AACtB,OAAI,iBAAkB,QAAO;AAO7B,UAJE,CAAC,cACD,+BACE,YAEiC;;GAEvC,CACD,KAAK,eAAe;;;;;AAMzB,SAAgB,iBACd,QACA,UAAoD,EAAE,EAC9C;AACR,QAAO,iBAAiB,QAAQ;EAAE,GAAG;EAAS,YAAY;EAAO,CAAC"}
+{"version":3,"file":"format.js","names":[],"sources":["../src/format.ts"],"sourcesContent":["import {\n  KEY_DISPLAY_SYMBOLS,\n  LINUX_MODIFIER_LABELS,\n  MAC_MODIFIER_LABELS,\n  MAC_MODIFIER_SYMBOLS,\n  PUNCTUATION_KEY_DISPLAY_LABELS,\n  WINDOWS_MODIFIER_LABELS,\n} from './display-labels'\nimport {\n  MODIFIER_ALIASES,\n  MODIFIER_ORDER,\n  PUNCTUATION_CODE_MAP,\n  normalizeKeyName,\n} from './constants'\nimport { detectPlatform } from './platform'\nimport { assertLogicalKey, splitHotkeyParts } from './_keyboard-event'\nimport {\n  isModifierKey,\n  normalizeHotkeyFromParsed,\n  normalizeRegisterableHotkey,\n} from './parse'\nimport type { CanonicalModifier } from './key.types'\nimport type { Hotkey, ParsedHotkey, RegisterableHotkey } from './hotkey.types'\n\n/**\n * Joins stored sequence steps with spaces, preserving physical code tokens.\n * For user-facing labels, call formatForDisplay on each step instead.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @returns A space-separated string (e.g. ['G','G'] → 'G G')\n *\n * @example\n * ```ts\n * formatHotkeySequence(['G', 'G'])      // 'G G'\n * formatHotkeySequence(['D', 'I', 'W']) // 'D I W'\n * ```\n */\nexport function formatHotkeySequence(sequence: Array<Hotkey>): string {\n  return sequence.join(' ')\n}\n\n/**\n * Converts a ParsedHotkey back to a hotkey string.\n *\n * @param parsed - The parsed hotkey object\n * @returns A hotkey string in canonical form\n *\n * @example\n * ```ts\n * formatHotkey({ key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] })\n * // Returns: 'Control+Shift+S'\n * ```\n */\nexport function formatHotkey(parsed: ParsedHotkey): string {\n  if (parsed.code === undefined) assertLogicalKey(parsed.key)\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.code !== undefined ? `[${parsed.code}]` : parsed.key)\n\n  return parts.join('+')\n}\n\nexport type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {})\n\n/**\n * Formats a hotkey for display in a user interface.\n *\n * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.\n * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.\n * The separator can be customized with `separatorToken`.\n * Physical codes use conventional display labels: `[KeyS]` becomes `S` and\n * `[Digit2]` becomes `2`. These labels do not infer the active keyboard layout\n * or change matching. Supply a resolved `layoutMap` for layout-aware labels;\n * `keyLabels` overrides both layout entries and fallback labels.\n *\n * @param hotkey - A logical or physical string, raw binding, or ParsedHotkey\n * @param options - Formatting options\n * @returns Display text, or individual key labels when parts is true\n *\n * @example\n * ```ts\n * formatForDisplay('Mod+Shift+S', { platform: 'mac' })\n * // Returns: '⌘ ⇧ S' (symbols separated by spaces on macOS)\n *\n * formatForDisplay('Mod+Shift+S', { platform: 'windows' })\n * // Returns: 'Ctrl+Shift+S'\n *\n * formatForDisplay('Escape')\n * // Returns: 'Esc' (on all platforms)\n * ```\n */\nexport function formatForDisplay(\n  hotkey: DisplayHotkey,\n  options: FormatDisplayOptions & { parts: true },\n): Array<string>\nexport function formatForDisplay(\n  hotkey: DisplayHotkey,\n  options?: FormatDisplayOptions & { parts?: false },\n): string\nexport function formatForDisplay(\n  hotkey: DisplayHotkey,\n  options: FormatDisplayOptions,\n): string | Array<string>\nexport function formatForDisplay(\n  hotkey: DisplayHotkey,\n  options: FormatDisplayOptions = {},\n): string | Array<string> {\n  const platform = options.platform ?? detectPlatform()\n  const symbols = options.useSymbols ?? true\n  const modifierSymbols =\n    typeof symbols === 'boolean' ? symbols : (symbols.modifiers ?? true)\n  const keySymbols =\n    typeof symbols === 'boolean' ? symbols : (symbols.keys ?? true)\n  const separator =\n    options.separatorToken ??\n    (platform === 'mac' && modifierSymbols ? ' ' : '+')\n  const normalized =\n    typeof hotkey === 'object' && 'modifiers' in hotkey\n      ? normalizeHotkeyFromParsed(hotkey, platform)\n      : normalizeRegisterableHotkey(hotkey as RegisterableHotkey, platform)\n  const parts = splitHotkeyParts(normalized).map((segment) => {\n    if (isModifierKey(segment)) {\n      const modifier = (MODIFIER_ALIASES[segment] ??\n        MODIFIER_ALIASES[segment.toLowerCase()]) as CanonicalModifier | 'Mod'\n      return platform === 'mac'\n        ? modifierSymbols\n          ? MAC_MODIFIER_SYMBOLS[modifier]\n          : MAC_MODIFIER_LABELS[modifier]\n        : platform === 'windows'\n          ? WINDOWS_MODIFIER_LABELS[modifier]\n          : LINUX_MODIFIER_LABELS[modifier]\n    }\n    const code = /^\\[([A-Za-z][A-Za-z0-9]*)\\]$/.exec(segment)?.[1]\n    const label = options.keyLabels?.[code ?? segment]\n    if (label !== undefined) return label\n    // Shorten conventional position labels for display only; stored identity is unchanged.\n    const numpad = code?.startsWith('Numpad') ?? false\n    let displayKey = code ?? segment\n    const mappedKey = code ? options.layoutMap?.get(code) : undefined\n    if (mappedKey) {\n      // Layout entries are logical labels; normalize their case and whitespace names.\n      displayKey = normalizeKeyName(mappedKey)\n    } else if (code) {\n      if (/^Key[A-Z]$/.test(code)) displayKey = code.slice(3)\n      else if (/^Digit[0-9]$/.test(code)) displayKey = code.slice(5)\n      else if (numpad) displayKey = code.slice(6)\n      else displayKey = PUNCTUATION_CODE_MAP[code] ?? code\n    }\n    const labels = keySymbols\n      ? KEY_DISPLAY_SYMBOLS\n      : PUNCTUATION_KEY_DISPLAY_LABELS\n    const display =\n      (labels as Partial<Record<string, string>>)[displayKey] ?? displayKey\n    // Retain numpad identity while making longer names such as MemoryAdd readable.\n    return numpad\n      ? `Numpad ${display.replace(/([a-z])([A-Z])/g, '$1 $2')}`\n      : display\n  })\n  return options.parts ? parts : parts.join(separator)\n}\n\n/**\n * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.\n */\nexport function formatWithLabels(\n  hotkey: RegisterableHotkey,\n  options: Omit<FormatDisplayOptions, 'useSymbols' | 'parts'> = {},\n): string {\n  return formatForDisplay(hotkey, { ...options, useSymbols: false })\n}\n\n/**\n * Options for formatting hotkeys for display.\n */\nexport interface FormatDisplayOptions {\n  /** The target platform. Defaults to auto-detection. */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Whether to use symbols for the display. Defaults to true. */\n  useSymbols?: boolean | { modifiers?: boolean; keys?: boolean }\n  /** Return individual key labels instead of a joined string. Default: false. */\n  parts?: boolean\n  /**\n   * An already-resolved code-to-key map, such as KeyboardLayoutMap or Map.\n   * Used only for physical bindings. Mapped keys receive normal display formatting;\n   * missing or empty entries use conventional fallback labels. The caller owns\n   * loading and refreshing the map; this formatter never calls browser APIs.\n   */\n  layoutMap?: { get: (code: string) => string | undefined }\n  /** Final display overrides for logical keys or physical codes; take precedence over layoutMap. Never changes matching. */\n  keyLabels?: Readonly<Record<string, string>>\n  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */\n  separatorToken?: string | null\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqCA,SAAgB,qBAAqB,UAAiC;AACpE,QAAO,SAAS,KAAK,IAAI;;;;;;;;;;;;;;AAe3B,SAAgB,aAAa,QAA8B;AACzD,KAAI,OAAO,SAAS,OAAW,kBAAiB,OAAO,IAAI;CAC3D,MAAM,QAAuB,EAAE;AAG/B,MAAK,MAAM,YAAY,eACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,SAAS;AAKxB,OAAM,KAAK,OAAO,SAAS,SAAY,IAAI,OAAO,KAAK,KAAK,OAAO,IAAI;AAEvE,QAAO,MAAM,KAAK,IAAI;;AA4CxB,SAAgB,iBACd,QACA,UAAgC,EAAE,EACV;CACxB,MAAM,WAAW,QAAQ,YAAY,gBAAgB;CACrD,MAAM,UAAU,QAAQ,cAAc;CACtC,MAAM,kBACJ,OAAO,YAAY,YAAY,UAAW,QAAQ,aAAa;CACjE,MAAM,aACJ,OAAO,YAAY,YAAY,UAAW,QAAQ,QAAQ;CAC5D,MAAM,YACJ,QAAQ,mBACP,aAAa,SAAS,kBAAkB,MAAM;CAKjD,MAAM,QAAQ,iBAHZ,OAAO,WAAW,YAAY,eAAe,SACzC,0BAA0B,QAAQ,SAAS,GAC3C,4BAA4B,QAA8B,SAAS,CAC/B,CAAC,KAAK,YAAY;AAC1D,MAAI,cAAc,QAAQ,EAAE;GAC1B,MAAM,WAAY,iBAAiB,YACjC,iBAAiB,QAAQ,aAAa;AACxC,UAAO,aAAa,QAChB,kBACE,qBAAqB,YACrB,oBAAoB,YACtB,aAAa,YACX,wBAAwB,YACxB,sBAAsB;;EAE9B,MAAM,OAAO,+BAA+B,KAAK,QAAQ,GAAG;EAC5D,MAAM,QAAQ,QAAQ,YAAY,QAAQ;AAC1C,MAAI,UAAU,OAAW,QAAO;EAEhC,MAAM,SAAS,MAAM,WAAW,SAAS,IAAI;EAC7C,IAAI,aAAa,QAAQ;EACzB,MAAM,YAAY,OAAO,QAAQ,WAAW,IAAI,KAAK,GAAG;AACxD,MAAI,UAEF,cAAa,iBAAiB,UAAU;WAC/B,KACT,KAAI,aAAa,KAAK,KAAK,CAAE,cAAa,KAAK,MAAM,EAAE;WAC9C,eAAe,KAAK,KAAK,CAAE,cAAa,KAAK,MAAM,EAAE;WACrD,OAAQ,cAAa,KAAK,MAAM,EAAE;MACtC,cAAa,qBAAqB,SAAS;EAKlD,MAAM,WAHS,aACX,sBACA,gCAE0C,eAAe;AAE7D,SAAO,SACH,UAAU,QAAQ,QAAQ,mBAAmB,QAAQ,KACrD;GACJ;AACF,QAAO,QAAQ,QAAQ,QAAQ,MAAM,KAAK,UAAU;;;;;AAMtD,SAAgB,iBACd,QACA,UAA8D,EAAE,EACxD;AACR,QAAO,iBAAiB,QAAQ;EAAE,GAAG;EAAS,YAAY;EAAO,CAAC"}

package/dist/hint.cjs

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

package/dist/hint.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hint.cjs","names":["normalizeKeyName","MODIFIER_KEYS","parseRegisterableHotkey"],"sources":["../src/hint.ts"],"sourcesContent":["import { MODIFIER_KEYS, normalizeKeyName } from './constants'\nimport { parseRegisterableHotkey } from './parse'\nimport type { CanonicalModifier } from './key.types'\nimport type { RegisterableHotkey } from './hotkey.types'\n\nexport interface HeldModifierOptions {\n  /** Resolve Mod for this platform. Defaults to platform detection. */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Require every binding modifier to be held. Default: false (nonempty subset). */\n  exact?: boolean\n}\n\n/**\n * Returns whether held modifiers should reveal a shortcut hint.\n * By default, any nonempty subset of the binding's modifiers qualifies; an\n * unrelated modifier hides the hint. `exact` requires every binding modifier.\n * Nonmodifier keys are ignored. This does not check registration or focus.\n *\n * @example\n * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true\n * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt', 'Control']) // false\n */\nexport function matchesHeldModifiers(\n  hotkey: RegisterableHotkey,\n  heldKeys: ReadonlyArray<string>,\n  options: HeldModifierOptions = {},\n): boolean {\n  // AltGraph (AltGr) types alternate characters such as @ or € on many layouts.\n  // It can synthesize Ctrl+Alt; character entry should not reveal shortcut hints.\n  if (heldKeys.includes('AltGraph')) return false\n  const held = [\n    ...new Set(\n      heldKeys.map(normalizeKeyName).filter((key) => MODIFIER_KEYS.has(key)),\n    ),\n  ]\n  const { modifiers } = parseRegisterableHotkey(hotkey, options.platform)\n  return (\n    held.length > 0 &&\n    held.every((key) => modifiers.includes(key as CanonicalModifier)) &&\n    (!options.exact || held.length === modifiers.length)\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;AAsBA,SAAgB,qBACd,QACA,UACA,UAA+B,EAAE,EACxB;AAGT,KAAI,SAAS,SAAS,WAAW,CAAE,QAAO;CAC1C,MAAM,OAAO,CACX,GAAG,IAAI,IACL,SAAS,IAAIA,mCAAiB,CAAC,QAAQ,QAAQC,gCAAc,IAAI,IAAI,CAAC,CACvE,CACF;CACD,MAAM,EAAE,cAAcC,sCAAwB,QAAQ,QAAQ,SAAS;AACvE,QACE,KAAK,SAAS,KACd,KAAK,OAAO,QAAQ,UAAU,SAAS,IAAyB,CAAC,KAChE,CAAC,QAAQ,SAAS,KAAK,WAAW,UAAU"}

package/dist/hint.d.cts

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

package/dist/hint.d.ts

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

package/dist/hint.js

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

package/dist/hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hint.js","names":[],"sources":["../src/hint.ts"],"sourcesContent":["import { MODIFIER_KEYS, normalizeKeyName } from './constants'\nimport { parseRegisterableHotkey } from './parse'\nimport type { CanonicalModifier } from './key.types'\nimport type { RegisterableHotkey } from './hotkey.types'\n\nexport interface HeldModifierOptions {\n  /** Resolve Mod for this platform. Defaults to platform detection. */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Require every binding modifier to be held. Default: false (nonempty subset). */\n  exact?: boolean\n}\n\n/**\n * Returns whether held modifiers should reveal a shortcut hint.\n * By default, any nonempty subset of the binding's modifiers qualifies; an\n * unrelated modifier hides the hint. `exact` requires every binding modifier.\n * Nonmodifier keys are ignored. This does not check registration or focus.\n *\n * @example\n * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt']) // true\n * matchesHeldModifiers('Alt+Shift+[KeyK]', ['Alt', 'Control']) // false\n */\nexport function matchesHeldModifiers(\n  hotkey: RegisterableHotkey,\n  heldKeys: ReadonlyArray<string>,\n  options: HeldModifierOptions = {},\n): boolean {\n  // AltGraph (AltGr) types alternate characters such as @ or € on many layouts.\n  // It can synthesize Ctrl+Alt; character entry should not reveal shortcut hints.\n  if (heldKeys.includes('AltGraph')) return false\n  const held = [\n    ...new Set(\n      heldKeys.map(normalizeKeyName).filter((key) => MODIFIER_KEYS.has(key)),\n    ),\n  ]\n  const { modifiers } = parseRegisterableHotkey(hotkey, options.platform)\n  return (\n    held.length > 0 &&\n    held.every((key) => modifiers.includes(key as CanonicalModifier)) &&\n    (!options.exact || held.length === modifiers.length)\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;AAsBA,SAAgB,qBACd,QACA,UACA,UAA+B,EAAE,EACxB;AAGT,KAAI,SAAS,SAAS,WAAW,CAAE,QAAO;CAC1C,MAAM,OAAO,CACX,GAAG,IAAI,IACL,SAAS,IAAI,iBAAiB,CAAC,QAAQ,QAAQ,cAAc,IAAI,IAAI,CAAC,CACvE,CACF;CACD,MAAM,EAAE,cAAc,wBAAwB,QAAQ,QAAQ,SAAS;AACvE,QACE,KAAK,SAAS,KACd,KAAK,OAAO,QAAQ,UAAU,SAAS,IAAyB,CAAC,KAChE,CAAC,QAAQ,SAAS,KAAK,WAAW,UAAU"}

package/dist/hotkey-manager.cjs

@@ -1,8 +1,12 @@
 const require_constants = require('./constants.cjs');
+const require_platform = require('./platform.cjs');
 const require_parse = require('./parse.cjs');
 const require_format = require('./format.cjs');
+const require__match = require('./_match.cjs');
 const require_match = require('./match.cjs');
-const require_manager_utils = require('./manager.utils.cjs');
+const require__recording_guard = require('./_recording-guard.cjs');
+const require__registration = require('./_registration.cjs');
+const require__event_target = require('./_event-target.cjs');
 let _tanstack_store = require("@tanstack/store");
 
 //#region src/hotkey-manager.ts
@@ -54,7 +58,7 @@ var HotkeyManager = class HotkeyManager {
 	#targetRegistrations = /* @__PURE__ */ new Map();
 	constructor() {
 		this.registrations = new _tanstack_store.Store(/* @__PURE__ */ new Map());
-		this.#platform = require_constants.detectPlatform();
+		this.#platform = require_platform.detectPlatform();
 	}
 	/**
 	* Gets the singleton instance of HotkeyManager.
@@ -122,15 +126,15 @@ var HotkeyManager = class HotkeyManager {
 		const target = options.target ?? document;
 		const conflictBehavior = options.conflictBehavior ?? "warn";
 		const conflictingRegistration = this.#findConflictingRegistration(hotkeyStr, target);
-		if (conflictingRegistration) require_manager_utils.handleConflict(conflictingRegistration.id, hotkeyStr, conflictBehavior, (id) => this.#unregister(id));
-		const resolvedIgnoreInputs = options.ignoreInputs ?? require_manager_utils.getDefaultIgnoreInputs(parsedHotkey);
+		if (conflictingRegistration) require__registration.handleConflict(conflictingRegistration.id, hotkeyStr, conflictBehavior, (id) => this.#unregister(id));
+		const resolvedIgnoreInputs = options.ignoreInputs ?? require__registration.getDefaultIgnoreInputs(parsedHotkey);
 		const registration = {
 			id,
 			hotkey: hotkeyStr,
 			parsedHotkey,
 			callback,
 			options: {
-				...require_manager_utils.defaultHotkeyOptions,
+				...require__registration.defaultHotkeyOptions,
 				requireReset: false,
 				...options,
 				platform,
@@ -162,7 +166,10 @@ var HotkeyManager = class HotkeyManager {
 			setOptions: (newOptions) => {
 				manager.registrations.setState((prev) => {
 					const reg = prev.get(id);
-					if (reg) {
+					if (reg && !require__registration.optionsEqual(reg.options, {
+						...reg.options,
+						...newOptions
+					})) {
 						const next = new Map(prev);
 						next.set(id, {
 							...reg,
@@ -230,33 +237,52 @@ var HotkeyManager = class HotkeyManager {
 	* Processes keyboard events for a specific target and event type.
 	*/
 	#processTargetEvent(event, target, eventType) {
+		if (eventType === "keyup") for (const id of this.#targetRegistrations.get(target) ?? []) {
+			const registration = this.registrations.state.get(id);
+			if (registration?.hasFired && this.#shouldResetRegistration(registration, event)) {
+				registration.hasFired = false;
+				registration.activeMatch = void 0;
+			}
+		}
+		if (require__recording_guard.isRecordingEvent(event)) return;
 		const targetRegs = this.#targetRegistrations.get(target);
 		if (!targetRegs) return;
+		const matches = /* @__PURE__ */ new Map();
+		let bestScore = 0;
+		for (const id of targetRegs) {
+			const registration = this.registrations.state.get(id);
+			if (!registration || !registration.options.enabled || registration.options.eventType !== eventType || !require__event_target.isEventForTarget(event, target) || registration.options.ignoreInputs !== false && require__event_target.shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			const result = require__match.matchKeyboardEvent(event, registration.parsedHotkey, registration.options.platform);
+			if (result.matched) {
+				matches.set(id, result);
+				bestScore = Math.max(bestScore, result.score);
+			}
+		}
 		for (const id of targetRegs) {
 			const registration = this.registrations.state.get(id);
 			if (!registration) continue;
-			if (!require_manager_utils.isEventForTarget(event, target)) continue;
+			if (!require__event_target.isEventForTarget(event, target)) continue;
 			if (!registration.options.enabled) continue;
 			if (registration.options.ignoreInputs !== false) {
-				if (require_manager_utils.shouldIgnoreInputEvent(event, target, registration.target)) continue;
+				if (require__event_target.shouldIgnoreInputEvent(event, target, registration.target)) continue;
 			}
 			if (eventType === "keydown") {
 				if (registration.options.eventType !== "keydown") continue;
-				if (require_match.matchesKeyboardEvent(event, registration.parsedHotkey, registration.options.platform)) {
+				const match = matches.get(id);
+				if (match?.matched && match.score === bestScore) {
 					if (registration.options.preventDefault) event.preventDefault();
 					if (registration.options.stopPropagation) event.stopPropagation();
 					if (!registration.options.requireReset || !registration.hasFired) {
 						this.#executeHotkeyCallback(registration, event);
-						if (registration.options.requireReset) registration.hasFired = true;
+						if (registration.options.requireReset) {
+							registration.hasFired = true;
+							registration.activeMatch = match.identity;
+						}
 					}
 				}
-			} else {
-				if (registration.options.eventType === "keyup") {
-					if (require_match.matchesKeyboardEvent(event, registration.parsedHotkey, registration.options.platform)) this.#executeHotkeyCallback(registration, event);
-				}
-				if (registration.options.requireReset && registration.hasFired) {
-					if (this.#shouldResetRegistration(registration, event)) registration.hasFired = false;
-				}
+			} else if (registration.options.eventType === "keyup") {
+				const match = matches.get(id);
+				if (match?.matched && match.score === bestScore) this.#executeHotkeyCallback(registration, event);
 			}
 		}
 	}
@@ -294,7 +320,7 @@ var HotkeyManager = class HotkeyManager {
 	* Finds an existing registration with the same hotkey and target.
 	*/
 	#findConflictingRegistration(hotkey, target) {
-		for (const registration of this.registrations.state.values()) if (registration.hotkey === hotkey && registration.target === target) return registration;
+		for (const registration of this.registrations.state.values()) if (require_match.areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform) && registration.target === target) return registration;
 		return null;
 	}
 	/**
@@ -303,8 +329,13 @@ var HotkeyManager = class HotkeyManager {
 	#shouldResetRegistration(registration, event) {
 		const parsed = registration.parsedHotkey;
 		const releasedKey = require_constants.normalizeKeyName(event.key);
-		const parsedKeyNormalized = parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key;
-		if ((releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey) === parsedKeyNormalized) return true;
+		if (registration.activeMatch?.code && event.code === registration.activeMatch.code) return true;
+		if (parsed.code !== void 0) {
+			if (event.code === parsed.code) return true;
+		} else {
+			const parsedKeyNormalized = parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key;
+			if ((releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey) === parsedKeyNormalized) return true;
+		}
 		if (parsed.ctrl && releasedKey === "Control") return true;
 		if (parsed.shift && releasedKey === "Shift") return true;
 		if (parsed.alt && releasedKey === "Alt") return true;
@@ -323,7 +354,7 @@ var HotkeyManager = class HotkeyManager {
 		if (!registration) return false;
 		const parsed = registration.parsedHotkey;
 		const syntheticEvent = new KeyboardEvent(registration.options.eventType ?? "keydown", {
-			key: parsed.key,
+			...parsed.code !== void 0 ? { code: parsed.code } : { key: parsed.key },
 			ctrlKey: parsed.ctrl,
 			shiftKey: parsed.shift,
 			altKey: parsed.alt,
@@ -353,7 +384,7 @@ var HotkeyManager = class HotkeyManager {
 	* @returns True if a matching registration exists
 	*/
 	isRegistered(hotkey, target) {
-		for (const registration of this.registrations.state.values()) if (registration.hotkey === hotkey) {
+		for (const registration of this.registrations.state.values()) if (require_match.areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform)) {
 			if (target === void 0 || registration.target === target) return true;
 		}
 		return false;

package/dist/hotkey-manager.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"hotkey-manager.cjs","names":["#instance","Store","#platform","detectPlatform","parseHotkey","rawHotkeyToParsedHotkey","formatHotkey","#findConflictingRegistration","#unregister","getDefaultIgnoreInputs","defaultHotkeyOptions","#targetRegistrations","#ensureListenersForTarget","#removeListenersForTarget","#targetListeners","#createTargetKeyDownHandler","#createTargetKeyUpHandler","isEventForTarget","shouldIgnoreInputEvent","matchesKeyboardEvent","#executeHotkeyCallback","#shouldResetRegistration","#processTargetEvent","normalizeKeyName"],"sources":["../src/hotkey-manager.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform, normalizeKeyName } from './constants'\nimport { formatHotkey } from './format'\nimport { parseHotkey, rawHotkeyToParsedHotkey } from './parse'\nimport { matchesKeyboardEvent } from './match'\nimport {\n  defaultHotkeyOptions,\n  getDefaultIgnoreInputs,\n  handleConflict,\n  isEventForTarget,\n  shouldIgnoreInputEvent,\n} from './manager.utils'\nimport type { ConflictBehavior } from './manager.utils'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeyMeta,\n  ParsedHotkey,\n  RegisterableHotkey,\n} from './hotkey'\n\nexport type { ConflictBehavior }\n\n/**\n * Options for registering a hotkey.\n */\nexport interface HotkeyOptions {\n  /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */\n  conflictBehavior?: ConflictBehavior\n  /**\n   * Soft-disable: when `false`, the callback does not run but the registration\n   * stays in `HotkeyManager` (and in devtools). Toggling this should update the\n   * existing handle via `setOptions` rather than unregistering. Defaults to `true`.\n   */\n  enabled?: boolean\n  /** The event type to listen for. Defaults to 'keydown' */\n  eventType?: 'keydown' | 'keyup'\n  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on hotkey: true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */\n  ignoreInputs?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** If true, only trigger once until all keys are released. Default: false */\n  requireReset?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The DOM element to attach the event listener to. Defaults to document. */\n  target?: HTMLElement | Document | Window | null\n  /** Optional metadata (name, description, custom fields via declaration merging) */\n  meta?: HotkeyMeta\n}\n\n/**\n * A registered hotkey handler in the HotkeyManager.\n */\nexport interface HotkeyRegistration {\n  /** The callback to invoke */\n  callback: HotkeyCallback\n  /** Whether this registration has fired and needs reset (for requireReset) */\n  hasFired: boolean\n  /** The original hotkey string */\n  hotkey: Hotkey\n  /** Unique identifier for this registration */\n  id: string\n  /** Options for this registration */\n  options: HotkeyOptions\n  /** The parsed hotkey */\n  parsedHotkey: ParsedHotkey\n  /** The resolved target element for this registration */\n  target: HTMLElement | Document | Window\n  /** How many times this registration's callback has been triggered */\n  triggerCount: number\n}\n\n/**\n * Public view of a hotkey registration for display and introspection.\n * Omits the callback function which is an internal implementation detail.\n */\nexport interface HotkeyRegistrationView {\n  /** The original hotkey string */\n  hotkey: Hotkey\n  /** Unique identifier for this registration */\n  id: string\n  /** Options for this registration */\n  options: HotkeyOptions\n  /** The parsed hotkey */\n  parsedHotkey: ParsedHotkey\n  /** The resolved target element for this registration */\n  target: HTMLElement | Document | Window\n  /** How many times this registration's callback has been triggered */\n  triggerCount: number\n  /** Whether this registration has fired and needs reset (for requireReset) */\n  hasFired: boolean\n}\n\n/**\n * Creates a public view from an internal registration,\n * stripping the callback function.\n */\nexport function toHotkeyRegistrationView(\n  reg: HotkeyRegistration,\n): HotkeyRegistrationView {\n  return {\n    hotkey: reg.hotkey,\n    id: reg.id,\n    options: reg.options,\n    parsedHotkey: reg.parsedHotkey,\n    target: reg.target,\n    triggerCount: reg.triggerCount,\n    hasFired: reg.hasFired,\n  }\n}\n\n/**\n * A handle returned from HotkeyManager.register() that allows updating\n * the callback and options without re-registering the hotkey.\n *\n * @example\n * ```ts\n * const handle = manager.register('Mod+S', callback, options)\n *\n * // Update callback without re-registering (avoids stale closures)\n * handle.callback = newCallback\n *\n * // Update options without re-registering\n * handle.setOptions({ enabled: false })\n *\n * // Check if still active\n * if (handle.isActive) {\n *   // ...\n * }\n *\n * // Unregister when done\n * handle.unregister()\n * ```\n */\nexport interface HotkeyRegistrationHandle {\n  /**\n   * The callback function. Can be set directly to update without re-registering.\n   * This avoids stale closures when the callback references React state.\n   */\n  callback: HotkeyCallback\n  /** Unique identifier for this registration */\n  readonly id: string\n  /** Check if this registration is still active (not unregistered) */\n  readonly isActive: boolean\n  /**\n   * Update options (merged with existing options).\n   * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.\n   */\n  setOptions: (options: Partial<HotkeyOptions>) => void\n  /** Unregister this hotkey */\n  unregister: () => void\n}\n\nlet registrationIdCounter = 0\n\n/**\n * Generates a unique ID for hotkey registrations.\n */\nfunction generateId(): string {\n  return `hotkey_${++registrationIdCounter}`\n}\n\n/**\n * Singleton manager for hotkey registrations.\n *\n * This class provides a centralized way to register and manage keyboard hotkeys.\n * It uses a single event listener for efficiency, regardless of how many hotkeys\n * are registered.\n *\n * @example\n * ```ts\n * const manager = HotkeyManager.getInstance()\n *\n * const unregister = manager.register('Mod+S', (event, context) => {\n *   console.log('Save triggered!')\n * })\n *\n * // Later, to unregister:\n * unregister()\n * ```\n */\nexport class HotkeyManager {\n  static #instance: HotkeyManager | null = null\n\n  /**\n   * The TanStack Store containing all hotkey registrations.\n   * Use this to subscribe to registration changes or access current registrations.\n   *\n   * @example\n   * ```ts\n   * const manager = HotkeyManager.getInstance()\n   *\n   * // Subscribe to registration changes\n   * const unsubscribe = manager.registrations.subscribe(() => {\n   *   console.log('Registrations changed:', manager.registrations.state.size)\n   * })\n   *\n   * // Access current registrations\n   * for (const [id, reg] of manager.registrations.state) {\n   *   console.log(reg.hotkey, reg.options.enabled)\n   * }\n   * ```\n   */\n  readonly registrations: Store<Map<string, HotkeyRegistration>> = new Store(\n    new Map(),\n  )\n  #platform: 'mac' | 'windows' | 'linux'\n  #targetListeners: Map<\n    HTMLElement | Document | Window,\n    {\n      keydown: (event: KeyboardEvent) => void\n      keyup: (event: KeyboardEvent) => void\n    }\n  > = new Map()\n  #targetRegistrations: Map<HTMLElement | Document | Window, Set<string>> =\n    new Map()\n\n  private constructor() {\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Gets the singleton instance of HotkeyManager.\n   */\n  static getInstance(): HotkeyManager {\n    if (!HotkeyManager.#instance) {\n      HotkeyManager.#instance = new HotkeyManager()\n    }\n    return HotkeyManager.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (HotkeyManager.#instance) {\n      HotkeyManager.#instance.destroy()\n      HotkeyManager.#instance = null\n    }\n  }\n\n  /**\n   * Registers a hotkey handler and returns a handle for updating the registration.\n   *\n   * The returned handle allows updating the callback and options without\n   * re-registering, which is useful for avoiding stale closures in React.\n   *\n   * @param hotkey - The hotkey string (e.g., 'Mod+S') or RawHotkey object\n   * @param callback - The function to call when the hotkey is pressed\n   * @param options - Options for the hotkey behavior\n   * @returns A handle for managing the registration\n   *\n   * @example\n   * ```ts\n   * const handle = manager.register('Mod+S', callback)\n   *\n   * // Update callback without re-registering (avoids stale closures)\n   * handle.callback = newCallback\n   *\n   * // Update options\n   * handle.setOptions({ enabled: false })\n   *\n   * // Unregister when done\n   * handle.unregister()\n   * ```\n   */\n  register(\n    hotkey: RegisterableHotkey,\n    callback: HotkeyCallback,\n    options: HotkeyOptions = {},\n  ): HotkeyRegistrationHandle {\n    // In SSR environments, return a no-op handle since there's no DOM to attach listeners to\n    if (typeof document === 'undefined' && !options.target) {\n      let currentCallback = callback\n      return {\n        id: generateId(),\n        unregister: () => {},\n        get callback() {\n          return currentCallback\n        },\n        set callback(newCallback: HotkeyCallback) {\n          currentCallback = newCallback\n        },\n        setOptions: () => {},\n        get isActive() {\n          return false\n        },\n      }\n    }\n\n    const id = generateId()\n    const platform = options.platform ?? this.#platform\n    const parsedHotkey =\n      typeof hotkey === 'string'\n        ? parseHotkey(hotkey, platform)\n        : rawHotkeyToParsedHotkey(hotkey, platform)\n    const hotkeyStr = (\n      typeof hotkey === 'string' ? hotkey : formatHotkey(parsedHotkey)\n    ) as Hotkey\n\n    // Resolve target: default to document if not provided\n    // Note: SSR case without explicit target is handled above\n    const target = options.target ?? document\n\n    // Resolve conflict behavior\n    const conflictBehavior = options.conflictBehavior ?? 'warn'\n\n    // Check for existing registrations with the same hotkey and target\n    const conflictingRegistration = this.#findConflictingRegistration(\n      hotkeyStr,\n      target,\n    )\n\n    if (conflictingRegistration) {\n      handleConflict(\n        conflictingRegistration.id,\n        hotkeyStr,\n        conflictBehavior,\n        (id) => this.#unregister(id),\n      )\n    }\n\n    const resolvedIgnoreInputs =\n      options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey)\n\n    const baseOptions = {\n      ...defaultHotkeyOptions,\n      requireReset: false,\n      ...options,\n      platform,\n    }\n\n    const registration: HotkeyRegistration = {\n      id,\n      hotkey: hotkeyStr,\n      parsedHotkey,\n      callback,\n      options: { ...baseOptions, ignoreInputs: resolvedIgnoreInputs },\n      hasFired: false,\n      triggerCount: 0,\n      target,\n    }\n\n    this.registrations.setState((prev) => new Map(prev).set(id, registration))\n\n    // Track registration for this target\n    if (!this.#targetRegistrations.has(target)) {\n      this.#targetRegistrations.set(target, new Set())\n    }\n    this.#targetRegistrations.get(target)!.add(id)\n\n    // Ensure listeners are attached for this target\n    this.#ensureListenersForTarget(target)\n\n    // Create and return the handle\n    const manager = this\n    const handle: HotkeyRegistrationHandle = {\n      get id() {\n        return id\n      },\n      unregister: () => {\n        manager.#unregister(id)\n      },\n      get callback() {\n        const reg = manager.registrations.state.get(id)\n        return reg?.callback ?? callback\n      },\n      set callback(newCallback: HotkeyCallback) {\n        const reg = manager.registrations.state.get(id)\n        if (reg) {\n          reg.callback = newCallback\n        }\n      },\n      setOptions: (newOptions: Partial<HotkeyOptions>) => {\n        manager.registrations.setState((prev) => {\n          const reg = prev.get(id)\n          if (reg) {\n            const next = new Map(prev)\n            next.set(id, { ...reg, options: { ...reg.options, ...newOptions } })\n            return next\n          }\n          return prev\n        })\n      },\n      get isActive() {\n        return manager.registrations.state.has(id)\n      },\n    }\n\n    return handle\n  }\n\n  /**\n   * Unregisters a hotkey by its registration ID.\n   */\n  #unregister(id: string): void {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return\n    }\n\n    const target = registration.target\n\n    // Remove registration\n    this.registrations.setState((prev) => {\n      const next = new Map(prev)\n      next.delete(id)\n      return next\n    })\n\n    // Remove from target registrations tracking\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (targetRegs) {\n      targetRegs.delete(id)\n      // If no more registrations for this target, remove listeners\n      if (targetRegs.size === 0) {\n        this.#removeListenersForTarget(target)\n      }\n    }\n  }\n\n  /**\n   * Ensures event listeners are attached for a specific target.\n   */\n  #ensureListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    // Skip if listeners already exist for this target\n    if (this.#targetListeners.has(target)) {\n      return\n    }\n\n    const keydownHandler = this.#createTargetKeyDownHandler(target)\n    const keyupHandler = this.#createTargetKeyUpHandler(target)\n\n    target.addEventListener('keydown', keydownHandler as EventListener)\n    target.addEventListener('keyup', keyupHandler as EventListener)\n\n    this.#targetListeners.set(target, {\n      keydown: keydownHandler,\n      keyup: keyupHandler,\n    })\n  }\n\n  /**\n   * Removes event listeners for a specific target.\n   */\n  #removeListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    const listeners = this.#targetListeners.get(target)\n    if (!listeners) {\n      return\n    }\n\n    target.removeEventListener('keydown', listeners.keydown as EventListener)\n    target.removeEventListener('keyup', listeners.keyup as EventListener)\n\n    this.#targetListeners.delete(target)\n    this.#targetRegistrations.delete(target)\n  }\n\n  /**\n   * Processes keyboard events for a specific target and event type.\n   */\n  #processTargetEvent(\n    event: KeyboardEvent,\n    target: HTMLElement | Document | Window,\n    eventType: 'keydown' | 'keyup',\n  ): void {\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (!targetRegs) {\n      return\n    }\n\n    for (const id of targetRegs) {\n      const registration = this.registrations.state.get(id)\n      if (!registration) {\n        continue\n      }\n\n      // Check if event originated from or bubbled to this target\n      if (!isEventForTarget(event, target)) {\n        continue\n      }\n\n      if (!registration.options.enabled) {\n        continue\n      }\n\n      // Check if we should ignore input elements (defaults to true)\n      if (registration.options.ignoreInputs !== false) {\n        if (shouldIgnoreInputEvent(event, target, registration.target)) {\n          continue\n        }\n      }\n\n      // Handle keydown events\n      if (eventType === 'keydown') {\n        if (registration.options.eventType !== 'keydown') {\n          continue\n        }\n\n        // Check if the hotkey matches first\n        const matches = matchesKeyboardEvent(\n          event,\n          registration.parsedHotkey,\n          registration.options.platform,\n        )\n\n        if (matches) {\n          // Always apply preventDefault/stopPropagation if the hotkey matches,\n          // even when requireReset is active and has already fired\n          if (registration.options.preventDefault) {\n            event.preventDefault()\n          }\n          if (registration.options.stopPropagation) {\n            event.stopPropagation()\n          }\n\n          // Only execute callback if requireReset is not active or hasn't fired yet\n          if (!registration.options.requireReset || !registration.hasFired) {\n            this.#executeHotkeyCallback(registration, event)\n\n            // Mark as fired if requireReset is enabled\n            if (registration.options.requireReset) {\n              registration.hasFired = true\n            }\n          }\n        }\n      }\n      // Handle keyup events\n      else {\n        if (registration.options.eventType === 'keyup') {\n          if (\n            matchesKeyboardEvent(\n              event,\n              registration.parsedHotkey,\n              registration.options.platform,\n            )\n          ) {\n            this.#executeHotkeyCallback(registration, event)\n          }\n        }\n\n        // Reset hasFired when any key in the hotkey is released\n        if (registration.options.requireReset && registration.hasFired) {\n          if (this.#shouldResetRegistration(registration, event)) {\n            registration.hasFired = false\n          }\n        }\n      }\n    }\n  }\n\n  /**\n   * Executes a hotkey callback with proper event handling.\n   */\n  #executeHotkeyCallback(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): void {\n    if (registration.options.preventDefault) {\n      event.preventDefault()\n    }\n    if (registration.options.stopPropagation) {\n      event.stopPropagation()\n    }\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count.\n    // We create a new Map but keep the same registration reference to preserve\n    // identity for mutation-based fields like hasFired.\n    this.registrations.setState((prev) => new Map(prev))\n\n    const context: HotkeyCallbackContext = {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    }\n\n    registration.callback(event, context)\n  }\n\n  /**\n   * Creates a keydown handler for a specific target.\n   */\n  #createTargetKeyDownHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keydown')\n    }\n  }\n\n  /**\n   * Creates a keyup handler for a specific target.\n   */\n  #createTargetKeyUpHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keyup')\n    }\n  }\n\n  /**\n   * Finds an existing registration with the same hotkey and target.\n   */\n  #findConflictingRegistration(\n    hotkey: Hotkey,\n    target: HTMLElement | Document | Window,\n  ): HotkeyRegistration | null {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey && registration.target === target) {\n        return registration\n      }\n    }\n    return null\n  }\n\n  /**\n   * Determines if a registration should be reset based on the keyup event.\n   */\n  #shouldResetRegistration(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): boolean {\n    const parsed = registration.parsedHotkey\n    const releasedKey = normalizeKeyName(event.key)\n\n    // Reset if the main key is released\n    // Compare case-insensitively for single-letter keys\n    const parsedKeyNormalized =\n      parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key\n    const releasedKeyNormalized =\n      releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey\n\n    if (releasedKeyNormalized === parsedKeyNormalized) {\n      return true\n    }\n\n    // Reset if any required modifier is released\n    // Use normalized key names and check against canonical modifier names\n    if (parsed.ctrl && releasedKey === 'Control') {\n      return true\n    }\n    if (parsed.shift && releasedKey === 'Shift') {\n      return true\n    }\n    if (parsed.alt && releasedKey === 'Alt') {\n      return true\n    }\n    if (parsed.meta && releasedKey === 'Meta') {\n      return true\n    }\n\n    return false\n  }\n\n  /**\n   * Triggers a registration's callback programmatically from devtools.\n   * Creates a synthetic KeyboardEvent and invokes the callback.\n   *\n   * @param id - The registration ID to trigger\n   * @returns True if the registration was found and triggered\n   */\n  triggerRegistration(id: string): boolean {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return false\n    }\n\n    const parsed = registration.parsedHotkey\n    const syntheticEvent = new KeyboardEvent(\n      registration.options.eventType ?? 'keydown',\n      {\n        key: parsed.key,\n        ctrlKey: parsed.ctrl,\n        shiftKey: parsed.shift,\n        altKey: parsed.alt,\n        metaKey: parsed.meta,\n        bubbles: true,\n        cancelable: true,\n      },\n    )\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count\n    this.registrations.setState((prev) => new Map(prev))\n\n    registration.callback(syntheticEvent, {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    })\n\n    return true\n  }\n\n  /**\n   * Gets the number of registered hotkeys.\n   */\n  getRegistrationCount(): number {\n    return this.registrations.state.size\n  }\n\n  /**\n   * Checks if a specific hotkey is registered.\n   *\n   * @param hotkey - The hotkey string to check\n   * @param target - Optional target element to match (if provided, both hotkey and target must match)\n   * @returns True if a matching registration exists\n   */\n  isRegistered(\n    hotkey: Hotkey,\n    target?: HTMLElement | Document | Window,\n  ): boolean {\n    for (const registration of this.registrations.state.values()) {\n      if (registration.hotkey === hotkey) {\n        // If target is specified, both must match\n        if (target === undefined || registration.target === target) {\n          return true\n        }\n      }\n    }\n    return false\n  }\n\n  /**\n   * Destroys the manager and removes all listeners.\n   */\n  destroy(): void {\n    // Remove all target listeners\n    for (const target of this.#targetListeners.keys()) {\n      this.#removeListenersForTarget(target)\n    }\n\n    this.registrations.setState(() => new Map())\n    this.#targetListeners.clear()\n    this.#targetRegistrations.clear()\n  }\n}\n\n/**\n * Gets the singleton HotkeyManager instance.\n * Convenience function for accessing the manager.\n */\nexport function getHotkeyManager(): HotkeyManager {\n  return HotkeyManager.getInstance()\n}\n"],"mappings":"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"}
+{"version":3,"file":"hotkey-manager.cjs","names":["#instance","Store","#platform","detectPlatform","parseHotkey","rawHotkeyToParsedHotkey","formatHotkey","#findConflictingRegistration","#unregister","getDefaultIgnoreInputs","defaultHotkeyOptions","#targetRegistrations","#ensureListenersForTarget","optionsEqual","#removeListenersForTarget","#targetListeners","#createTargetKeyDownHandler","#createTargetKeyUpHandler","#shouldResetRegistration","isRecordingEvent","isEventForTarget","shouldIgnoreInputEvent","matchKeyboardEvent","#executeHotkeyCallback","#processTargetEvent","areHotkeysEqual","normalizeKeyName"],"sources":["../src/hotkey-manager.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { isRecordingEvent } from './_recording-guard'\nimport { areHotkeysEqual } from './match'\nimport { detectPlatform } from './platform'\nimport { normalizeKeyName } from './constants'\nimport { formatHotkey } from './format'\nimport { parseHotkey, rawHotkeyToParsedHotkey } from './parse'\nimport { matchKeyboardEvent } from './_match'\nimport {\n  defaultHotkeyOptions,\n  getDefaultIgnoreInputs,\n  handleConflict,\n  optionsEqual,\n} from './_registration'\nimport { isEventForTarget, shouldIgnoreInputEvent } from './_event-target'\nimport type {\n  ConflictBehavior,\n  Hotkey,\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeyMeta,\n  ParsedHotkey,\n  RegisterableHotkey,\n} from './hotkey.types'\n\nexport type { ConflictBehavior }\n\n/**\n * Options for registering a hotkey.\n */\nexport interface HotkeyOptions {\n  /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */\n  conflictBehavior?: ConflictBehavior\n  /**\n   * Soft-disable: when `false`, the callback does not run but the registration\n   * stays in `HotkeyManager` (and in devtools). Toggling this should update the\n   * existing handle via `setOptions` rather than unregistering. Defaults to `true`.\n   */\n  enabled?: boolean\n  /** The event type to listen for. Defaults to 'keydown' */\n  eventType?: 'keydown' | 'keyup'\n  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on hotkey: true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */\n  ignoreInputs?: boolean\n  /** The target platform for resolving 'Mod' */\n  platform?: 'mac' | 'windows' | 'linux'\n  /** Prevent the default browser action when the hotkey matches. Defaults to true */\n  preventDefault?: boolean\n  /** If true, only trigger once until all keys are released. Default: false */\n  requireReset?: boolean\n  /** Stop event propagation when the hotkey matches. Defaults to true */\n  stopPropagation?: boolean\n  /** The DOM element to attach the event listener to. Defaults to document. */\n  target?: HTMLElement | Document | Window | null\n  /** Optional metadata (name, description, custom fields via declaration merging) */\n  meta?: HotkeyMeta\n}\n\n/**\n * A registered hotkey handler in the HotkeyManager.\n */\nexport interface HotkeyRegistration {\n  /** The callback to invoke */\n  callback: HotkeyCallback\n  /** Whether this registration has fired and needs reset (for requireReset) */\n  hasFired: boolean\n  /** The concrete key/code that activated a requireReset registration. */\n  activeMatch?: { key: string; code: string }\n  /** The original hotkey string */\n  hotkey: Hotkey\n  /** Unique identifier for this registration */\n  id: string\n  /** Options for this registration */\n  options: HotkeyOptions\n  /** The parsed hotkey */\n  parsedHotkey: ParsedHotkey\n  /** The resolved target element for this registration */\n  target: HTMLElement | Document | Window\n  /** How many times this registration's callback has been triggered */\n  triggerCount: number\n}\n\n/**\n * Public view of a hotkey registration for display and introspection.\n * Omits the callback function which is an internal implementation detail.\n */\nexport interface HotkeyRegistrationView {\n  /** The original hotkey string */\n  hotkey: Hotkey\n  /** Unique identifier for this registration */\n  id: string\n  /** Options for this registration */\n  options: HotkeyOptions\n  /** The parsed hotkey */\n  parsedHotkey: ParsedHotkey\n  /** The resolved target element for this registration */\n  target: HTMLElement | Document | Window\n  /** How many times this registration's callback has been triggered */\n  triggerCount: number\n  /** Whether this registration has fired and needs reset (for requireReset) */\n  hasFired: boolean\n}\n\n/**\n * Creates a public view from an internal registration,\n * stripping the callback function.\n */\nexport function toHotkeyRegistrationView(\n  reg: HotkeyRegistration,\n): HotkeyRegistrationView {\n  return {\n    hotkey: reg.hotkey,\n    id: reg.id,\n    options: reg.options,\n    parsedHotkey: reg.parsedHotkey,\n    target: reg.target,\n    triggerCount: reg.triggerCount,\n    hasFired: reg.hasFired,\n  }\n}\n\n/**\n * A handle returned from HotkeyManager.register() that allows updating\n * the callback and options without re-registering the hotkey.\n *\n * @example\n * ```ts\n * const handle = manager.register('Mod+S', callback, options)\n *\n * // Update callback without re-registering (avoids stale closures)\n * handle.callback = newCallback\n *\n * // Update options without re-registering\n * handle.setOptions({ enabled: false })\n *\n * // Check if still active\n * if (handle.isActive) {\n *   // ...\n * }\n *\n * // Unregister when done\n * handle.unregister()\n * ```\n */\nexport interface HotkeyRegistrationHandle {\n  /**\n   * The callback function. Can be set directly to update without re-registering.\n   * This avoids stale closures when the callback references React state.\n   */\n  callback: HotkeyCallback\n  /** Unique identifier for this registration */\n  readonly id: string\n  /** Check if this registration is still active (not unregistered) */\n  readonly isActive: boolean\n  /**\n   * Update options (merged with existing options).\n   * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.\n   */\n  setOptions: (options: Partial<HotkeyOptions>) => void\n  /** Unregister this hotkey */\n  unregister: () => void\n}\n\nlet registrationIdCounter = 0\n\n/**\n * Generates a unique ID for hotkey registrations.\n */\nfunction generateId(): string {\n  return `hotkey_${++registrationIdCounter}`\n}\n\n/**\n * Singleton manager for hotkey registrations.\n *\n * This class provides a centralized way to register and manage keyboard hotkeys.\n * It uses a single event listener for efficiency, regardless of how many hotkeys\n * are registered.\n *\n * @example\n * ```ts\n * const manager = HotkeyManager.getInstance()\n *\n * const unregister = manager.register('Mod+S', (event, context) => {\n *   console.log('Save triggered!')\n * })\n *\n * // Later, to unregister:\n * unregister()\n * ```\n */\nexport class HotkeyManager {\n  static #instance: HotkeyManager | null = null\n\n  /**\n   * The TanStack Store containing all hotkey registrations.\n   * Use this to subscribe to registration changes or access current registrations.\n   *\n   * @example\n   * ```ts\n   * const manager = HotkeyManager.getInstance()\n   *\n   * // Subscribe to registration changes\n   * const unsubscribe = manager.registrations.subscribe(() => {\n   *   console.log('Registrations changed:', manager.registrations.state.size)\n   * })\n   *\n   * // Access current registrations\n   * for (const [id, reg] of manager.registrations.state) {\n   *   console.log(reg.hotkey, reg.options.enabled)\n   * }\n   * ```\n   */\n  readonly registrations: Store<Map<string, HotkeyRegistration>> = new Store(\n    new Map(),\n  )\n  #platform: 'mac' | 'windows' | 'linux'\n  #targetListeners: Map<\n    HTMLElement | Document | Window,\n    {\n      keydown: (event: KeyboardEvent) => void\n      keyup: (event: KeyboardEvent) => void\n    }\n  > = new Map()\n  #targetRegistrations: Map<HTMLElement | Document | Window, Set<string>> =\n    new Map()\n\n  private constructor() {\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Gets the singleton instance of HotkeyManager.\n   */\n  static getInstance(): HotkeyManager {\n    if (!HotkeyManager.#instance) {\n      HotkeyManager.#instance = new HotkeyManager()\n    }\n    return HotkeyManager.#instance\n  }\n\n  /**\n   * Resets the singleton instance. Useful for testing.\n   */\n  static resetInstance(): void {\n    if (HotkeyManager.#instance) {\n      HotkeyManager.#instance.destroy()\n      HotkeyManager.#instance = null\n    }\n  }\n\n  /**\n   * Registers a hotkey handler and returns a handle for updating the registration.\n   *\n   * The returned handle allows updating the callback and options without\n   * re-registering, which is useful for avoiding stale closures in React.\n   *\n   * @param hotkey - The hotkey string (e.g., 'Mod+S') or RawHotkey object\n   * @param callback - The function to call when the hotkey is pressed\n   * @param options - Options for the hotkey behavior\n   * @returns A handle for managing the registration\n   *\n   * @example\n   * ```ts\n   * const handle = manager.register('Mod+S', callback)\n   *\n   * // Update callback without re-registering (avoids stale closures)\n   * handle.callback = newCallback\n   *\n   * // Update options\n   * handle.setOptions({ enabled: false })\n   *\n   * // Unregister when done\n   * handle.unregister()\n   * ```\n   */\n  register(\n    hotkey: RegisterableHotkey,\n    callback: HotkeyCallback,\n    options: HotkeyOptions = {},\n  ): HotkeyRegistrationHandle {\n    // In SSR environments, return a no-op handle since there's no DOM to attach listeners to\n    if (typeof document === 'undefined' && !options.target) {\n      let currentCallback = callback\n      return {\n        id: generateId(),\n        unregister: () => {},\n        get callback() {\n          return currentCallback\n        },\n        set callback(newCallback: HotkeyCallback) {\n          currentCallback = newCallback\n        },\n        setOptions: () => {},\n        get isActive() {\n          return false\n        },\n      }\n    }\n\n    const id = generateId()\n    const platform = options.platform ?? this.#platform\n    const parsedHotkey =\n      typeof hotkey === 'string'\n        ? parseHotkey(hotkey, platform)\n        : rawHotkeyToParsedHotkey(hotkey, platform)\n    const hotkeyStr = (\n      typeof hotkey === 'string' ? hotkey : formatHotkey(parsedHotkey)\n    ) as Hotkey\n\n    // Resolve target: default to document if not provided\n    // Note: SSR case without explicit target is handled above\n    const target = options.target ?? document\n\n    // Resolve conflict behavior\n    const conflictBehavior = options.conflictBehavior ?? 'warn'\n\n    // Check for existing registrations with the same hotkey and target\n    const conflictingRegistration = this.#findConflictingRegistration(\n      hotkeyStr,\n      target,\n    )\n\n    if (conflictingRegistration) {\n      handleConflict(\n        conflictingRegistration.id,\n        hotkeyStr,\n        conflictBehavior,\n        (id) => this.#unregister(id),\n      )\n    }\n\n    const resolvedIgnoreInputs =\n      options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey)\n\n    const baseOptions = {\n      ...defaultHotkeyOptions,\n      requireReset: false,\n      ...options,\n      platform,\n    }\n\n    const registration: HotkeyRegistration = {\n      id,\n      hotkey: hotkeyStr,\n      parsedHotkey,\n      callback,\n      options: { ...baseOptions, ignoreInputs: resolvedIgnoreInputs },\n      hasFired: false,\n      triggerCount: 0,\n      target,\n    }\n\n    this.registrations.setState((prev) => new Map(prev).set(id, registration))\n\n    // Track registration for this target\n    if (!this.#targetRegistrations.has(target)) {\n      this.#targetRegistrations.set(target, new Set())\n    }\n    this.#targetRegistrations.get(target)!.add(id)\n\n    // Ensure listeners are attached for this target\n    this.#ensureListenersForTarget(target)\n\n    // Create and return the handle\n    const manager = this\n    const handle: HotkeyRegistrationHandle = {\n      get id() {\n        return id\n      },\n      unregister: () => {\n        manager.#unregister(id)\n      },\n      get callback() {\n        const reg = manager.registrations.state.get(id)\n        return reg?.callback ?? callback\n      },\n      set callback(newCallback: HotkeyCallback) {\n        const reg = manager.registrations.state.get(id)\n        if (reg) {\n          reg.callback = newCallback\n        }\n      },\n      setOptions: (newOptions: Partial<HotkeyOptions>) => {\n        manager.registrations.setState((prev) => {\n          const reg = prev.get(id)\n          if (\n            reg &&\n            !optionsEqual(reg.options, { ...reg.options, ...newOptions })\n          ) {\n            const next = new Map(prev)\n            next.set(id, { ...reg, options: { ...reg.options, ...newOptions } })\n            return next\n          }\n          return prev\n        })\n      },\n      get isActive() {\n        return manager.registrations.state.has(id)\n      },\n    }\n\n    return handle\n  }\n\n  /**\n   * Unregisters a hotkey by its registration ID.\n   */\n  #unregister(id: string): void {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return\n    }\n\n    const target = registration.target\n\n    // Remove registration\n    this.registrations.setState((prev) => {\n      const next = new Map(prev)\n      next.delete(id)\n      return next\n    })\n\n    // Remove from target registrations tracking\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (targetRegs) {\n      targetRegs.delete(id)\n      // If no more registrations for this target, remove listeners\n      if (targetRegs.size === 0) {\n        this.#removeListenersForTarget(target)\n      }\n    }\n  }\n\n  /**\n   * Ensures event listeners are attached for a specific target.\n   */\n  #ensureListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    // Skip if listeners already exist for this target\n    if (this.#targetListeners.has(target)) {\n      return\n    }\n\n    const keydownHandler = this.#createTargetKeyDownHandler(target)\n    const keyupHandler = this.#createTargetKeyUpHandler(target)\n\n    target.addEventListener('keydown', keydownHandler as EventListener)\n    target.addEventListener('keyup', keyupHandler as EventListener)\n\n    this.#targetListeners.set(target, {\n      keydown: keydownHandler,\n      keyup: keyupHandler,\n    })\n  }\n\n  /**\n   * Removes event listeners for a specific target.\n   */\n  #removeListenersForTarget(target: HTMLElement | Document | Window): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    const listeners = this.#targetListeners.get(target)\n    if (!listeners) {\n      return\n    }\n\n    target.removeEventListener('keydown', listeners.keydown as EventListener)\n    target.removeEventListener('keyup', listeners.keyup as EventListener)\n\n    this.#targetListeners.delete(target)\n    this.#targetRegistrations.delete(target)\n  }\n\n  /**\n   * Processes keyboard events for a specific target and event type.\n   */\n  #processTargetEvent(\n    event: KeyboardEvent,\n    target: HTMLElement | Document | Window,\n    eventType: 'keydown' | 'keyup',\n  ): void {\n    // Releases clear latches even when focus or enabled state now prevents callbacks.\n    if (eventType === 'keyup') {\n      for (const id of this.#targetRegistrations.get(target) ?? []) {\n        const registration = this.registrations.state.get(id)\n        if (\n          registration?.hasFired &&\n          this.#shouldResetRegistration(registration, event)\n        ) {\n          registration.hasFired = false\n          registration.activeMatch = undefined\n        }\n      }\n    }\n    if (isRecordingEvent(event)) return\n    const targetRegs = this.#targetRegistrations.get(target)\n    if (!targetRegs) {\n      return\n    }\n\n    const matches = new Map<string, ReturnType<typeof matchKeyboardEvent>>()\n    let bestScore = 0\n\n    // Exact logical/explicit-code matches outrank compatibility fallbacks.\n    for (const id of targetRegs) {\n      const registration = this.registrations.state.get(id)\n      if (\n        !registration ||\n        !registration.options.enabled ||\n        registration.options.eventType !== eventType ||\n        !isEventForTarget(event, target) ||\n        (registration.options.ignoreInputs !== false &&\n          shouldIgnoreInputEvent(event, target, registration.target))\n      ) {\n        continue\n      }\n      const result = matchKeyboardEvent(\n        event,\n        registration.parsedHotkey,\n        registration.options.platform,\n      )\n      if (result.matched) {\n        matches.set(id, result)\n        bestScore = Math.max(bestScore, result.score)\n      }\n    }\n\n    for (const id of targetRegs) {\n      const registration = this.registrations.state.get(id)\n      if (!registration) {\n        continue\n      }\n\n      // Check if event originated from or bubbled to this target\n      if (!isEventForTarget(event, target)) {\n        continue\n      }\n\n      if (!registration.options.enabled) {\n        continue\n      }\n\n      // Check if we should ignore input elements (defaults to true)\n      if (registration.options.ignoreInputs !== false) {\n        if (shouldIgnoreInputEvent(event, target, registration.target)) {\n          continue\n        }\n      }\n\n      // Handle keydown events\n      if (eventType === 'keydown') {\n        if (registration.options.eventType !== 'keydown') {\n          continue\n        }\n\n        const match = matches.get(id)\n\n        if (match?.matched && match.score === bestScore) {\n          // Always apply preventDefault/stopPropagation if the hotkey matches,\n          // even when requireReset is active and has already fired\n          if (registration.options.preventDefault) {\n            event.preventDefault()\n          }\n          if (registration.options.stopPropagation) {\n            event.stopPropagation()\n          }\n\n          // Only execute callback if requireReset is not active or hasn't fired yet\n          if (!registration.options.requireReset || !registration.hasFired) {\n            this.#executeHotkeyCallback(registration, event)\n\n            // Mark as fired if requireReset is enabled\n            if (registration.options.requireReset) {\n              registration.hasFired = true\n              registration.activeMatch = match.identity\n            }\n          }\n        }\n      }\n      // Handle keyup events\n      else {\n        if (registration.options.eventType === 'keyup') {\n          const match = matches.get(id)\n          if (match?.matched && match.score === bestScore) {\n            this.#executeHotkeyCallback(registration, event)\n          }\n        }\n      }\n    }\n  }\n\n  /**\n   * Executes a hotkey callback with proper event handling.\n   */\n  #executeHotkeyCallback(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): void {\n    if (registration.options.preventDefault) {\n      event.preventDefault()\n    }\n    if (registration.options.stopPropagation) {\n      event.stopPropagation()\n    }\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count.\n    // We create a new Map but keep the same registration reference to preserve\n    // identity for mutation-based fields like hasFired.\n    this.registrations.setState((prev) => new Map(prev))\n\n    const context: HotkeyCallbackContext = {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    }\n\n    registration.callback(event, context)\n  }\n\n  /**\n   * Creates a keydown handler for a specific target.\n   */\n  #createTargetKeyDownHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keydown')\n    }\n  }\n\n  /**\n   * Creates a keyup handler for a specific target.\n   */\n  #createTargetKeyUpHandler(\n    target: HTMLElement | Document | Window,\n  ): (event: KeyboardEvent) => void {\n    return (event: KeyboardEvent) => {\n      this.#processTargetEvent(event, target, 'keyup')\n    }\n  }\n\n  /**\n   * Finds an existing registration with the same hotkey and target.\n   */\n  #findConflictingRegistration(\n    hotkey: Hotkey,\n    target: HTMLElement | Document | Window,\n  ): HotkeyRegistration | null {\n    for (const registration of this.registrations.state.values()) {\n      if (\n        areHotkeysEqual(\n          registration.hotkey,\n          hotkey,\n          registration.options.platform,\n        ) &&\n        registration.target === target\n      ) {\n        return registration\n      }\n    }\n    return null\n  }\n\n  /**\n   * Determines if a registration should be reset based on the keyup event.\n   */\n  #shouldResetRegistration(\n    registration: HotkeyRegistration,\n    event: KeyboardEvent,\n  ): boolean {\n    const parsed = registration.parsedHotkey\n    const releasedKey = normalizeKeyName(event.key)\n\n    if (\n      registration.activeMatch?.code &&\n      event.code === registration.activeMatch.code\n    ) {\n      return true\n    }\n\n    // Compare the release against the identity this binding actually stores.\n    if (parsed.code !== undefined) {\n      if (event.code === parsed.code) return true\n    } else {\n      const parsedKeyNormalized =\n        parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key\n      const releasedKeyNormalized =\n        releasedKey.length === 1 ? releasedKey.toUpperCase() : releasedKey\n      if (releasedKeyNormalized === parsedKeyNormalized) return true\n    }\n\n    // Reset if any required modifier is released\n    // Use normalized key names and check against canonical modifier names\n    if (parsed.ctrl && releasedKey === 'Control') {\n      return true\n    }\n    if (parsed.shift && releasedKey === 'Shift') {\n      return true\n    }\n    if (parsed.alt && releasedKey === 'Alt') {\n      return true\n    }\n    if (parsed.meta && releasedKey === 'Meta') {\n      return true\n    }\n\n    return false\n  }\n\n  /**\n   * Triggers a registration's callback programmatically from devtools.\n   * Creates a synthetic KeyboardEvent and invokes the callback.\n   *\n   * @param id - The registration ID to trigger\n   * @returns True if the registration was found and triggered\n   */\n  triggerRegistration(id: string): boolean {\n    const registration = this.registrations.state.get(id)\n    if (!registration) {\n      return false\n    }\n\n    const parsed = registration.parsedHotkey\n    const syntheticEvent = new KeyboardEvent(\n      registration.options.eventType ?? 'keydown',\n      {\n        ...(parsed.code !== undefined\n          ? { code: parsed.code }\n          : { key: parsed.key }),\n        ctrlKey: parsed.ctrl,\n        shiftKey: parsed.shift,\n        altKey: parsed.alt,\n        metaKey: parsed.meta,\n        bubbles: true,\n        cancelable: true,\n      },\n    )\n\n    registration.triggerCount++\n\n    // Notify the store so subscribers (e.g. devtools) see the updated count\n    this.registrations.setState((prev) => new Map(prev))\n\n    registration.callback(syntheticEvent, {\n      hotkey: registration.hotkey,\n      parsedHotkey: registration.parsedHotkey,\n    })\n\n    return true\n  }\n\n  /**\n   * Gets the number of registered hotkeys.\n   */\n  getRegistrationCount(): number {\n    return this.registrations.state.size\n  }\n\n  /**\n   * Checks if a specific hotkey is registered.\n   *\n   * @param hotkey - The hotkey string to check\n   * @param target - Optional target element to match (if provided, both hotkey and target must match)\n   * @returns True if a matching registration exists\n   */\n  isRegistered(\n    hotkey: Hotkey,\n    target?: HTMLElement | Document | Window,\n  ): boolean {\n    for (const registration of this.registrations.state.values()) {\n      if (\n        areHotkeysEqual(\n          registration.hotkey,\n          hotkey,\n          registration.options.platform,\n        )\n      ) {\n        // If target is specified, both must match\n        if (target === undefined || registration.target === target) {\n          return true\n        }\n      }\n    }\n    return false\n  }\n\n  /**\n   * Destroys the manager and removes all listeners.\n   */\n  destroy(): void {\n    // Remove all target listeners\n    for (const target of this.#targetListeners.keys()) {\n      this.#removeListenersForTarget(target)\n    }\n\n    this.registrations.setState(() => new Map())\n    this.#targetListeners.clear()\n    this.#targetRegistrations.clear()\n  }\n}\n\n/**\n * Gets the singleton HotkeyManager instance.\n * Convenience function for accessing the manager.\n */\nexport function getHotkeyManager(): HotkeyManager {\n  return HotkeyManager.getInstance()\n}\n"],"mappings":"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"}

package/dist/hotkey-manager.d.cts

@@ -1,5 +1,4 @@
-import { Hotkey, HotkeyCallback, HotkeyMeta, ParsedHotkey, RegisterableHotkey } from "./hotkey.cjs";
-import { ConflictBehavior } from "./manager.utils.cjs";
+import { ConflictBehavior, Hotkey, HotkeyCallback, HotkeyMeta, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.cjs";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.d.ts
@@ -40,6 +39,11 @@ interface HotkeyRegistration {
   callback: HotkeyCallback;
   /** Whether this registration has fired and needs reset (for requireReset) */
   hasFired: boolean;
+  /** The concrete key/code that activated a requireReset registration. */
+  activeMatch?: {
+    key: string;
+    code: string;
+  };
   /** The original hotkey string */
   hotkey: Hotkey;
   /** Unique identifier for this registration */

package/dist/hotkey-manager.d.ts

@@ -1,5 +1,4 @@
-import { Hotkey, HotkeyCallback, HotkeyMeta, ParsedHotkey, RegisterableHotkey } from "./hotkey.js";
-import { ConflictBehavior } from "./manager.utils.js";
+import { ConflictBehavior, Hotkey, HotkeyCallback, HotkeyMeta, ParsedHotkey, RegisterableHotkey } from "./hotkey.types.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.d.ts
@@ -40,6 +39,11 @@ interface HotkeyRegistration {
   callback: HotkeyCallback;
   /** Whether this registration has fired and needs reset (for requireReset) */
   hasFired: boolean;
+  /** The concrete key/code that activated a requireReset registration. */
+  activeMatch?: {
+    key: string;
+    code: string;
+  };
   /** The original hotkey string */
   hotkey: Hotkey;
   /** Unique identifier for this registration */