@tanstack/hotkeys 0.8.0 → 0.9.0

package/dist/parse.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"parse.cjs","names":["detectPlatform","normalizeKeyName","MODIFIER_ALIASES","resolveModifier","MODIFIER_ORDER"],"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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"}
+{"version":3,"file":"parse.cjs","names":["detectPlatform","splitHotkeyParts","normalizeKeyName","MODIFIER_ALIASES","resolveModifier","MODIFIER_ORDER","normalizeKeyboardEvent"],"sources":["../src/parse.ts"],"sourcesContent":["import {\n  assertLogicalKey,\n  normalizeKeyboardEvent,\n  splitHotkeyParts,\n} from './_keyboard-event'\nimport { MODIFIER_ALIASES, MODIFIER_ORDER, normalizeKeyName } from './constants'\nimport { detectPlatform, resolveModifier } from './platform'\nimport type { CanonicalModifier, Key } from './key.types'\nimport type {\n  Hotkey,\n  ParsedHotkey,\n  RawHotkey,\n  RegisterableHotkey,\n} from './hotkey.types'\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 with either logical key or physical code 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 = splitHotkeyParts(hotkey)\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  const code = /^\\[([A-Za-z][A-Za-z0-9]*)\\]$/.exec(key)?.[1]\n  return {\n    ...(code !== undefined ? { code } : { 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  if (raw.code === undefined) assertLogicalKey(raw.key)\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    ...(raw.code !== undefined\n      ? { code: raw.code }\n      : { key: normalizeKeyName(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  if (parsed.code === undefined) assertLogicalKey(parsed.key)\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(\n    parsed.code !== undefined\n      ? `[${parsed.code}]`\n      : normalizeKeyName(parsed.key),\n  )\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(\n  event: KeyboardEvent,\n  platform?: 'mac' | 'windows' | 'linux',\n): ParsedHotkey {\n  const normalized = normalizeKeyboardEvent(event, platform)\n  // AltGraph is a character-production modifier, not an ordinary Control+Alt\n  // shortcut. Record the produced glyph instead of a synthetic Ctrl+Alt chord.\n  const ctrl = normalized.altGraph ? false : normalized.ctrl\n  const alt = normalized.altGraph ? false : normalized.alt\n  // Shift is a real modifier even during AltGraph input; preserve it for replay.\n  const shift = normalized.shift\n\n  // Build modifiers array in canonical order\n  const modifiers: Array<CanonicalModifier> = []\n  if (ctrl) modifiers.push('Control')\n  if (alt) modifiers.push('Alt')\n  if (shift) modifiers.push('Shift')\n  if (normalized.meta) modifiers.push('Meta')\n\n  return {\n    key: normalized.key,\n    ctrl,\n    shift,\n    alt,\n    meta: normalized.meta,\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(\n    parseKeyboardEvent(event, platform),\n    platform,\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  if (parsed.code !== undefined) {\n    // Physical modifier codes identify a side, but still are not action keys.\n    return (\n      parsed.code.length > 0 &&\n      !/^(Control|Shift|Alt|Meta)(Left|Right)$/.test(parsed.code)\n    )\n  }\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\n/**\n * Parses a string or raw binding, resolving Mod for the supplied platform.\n * Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.\n */\nexport function parseRegisterableHotkey(\n  hotkey: RegisterableHotkey,\n  platform = detectPlatform(),\n): ParsedHotkey {\n  return typeof hotkey === 'string'\n    ? parseHotkey(hotkey, platform)\n    : rawHotkeyToParsedHotkey(hotkey, platform)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,YACd,QACA,WAAwCA,iCAAgB,EAC1C;CACd,MAAM,QAAQC,yCAAiB,OAAO;CACtC,MAAM,4BAAoC,IAAI,KAAK;CACnD,IAAI,MAAM;AAEV,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,OAAO,MAAM,GAAI,MAAM;AAE7B,MAAI,MAAM,MAAM,SAAS,EAEvB,OAAMC,mCAAiB,KAAK;OACvB;GAEL,MAAM,QACJC,mCAAiB,SAASA,mCAAiB,KAAK,aAAa;AAE/D,OAAI,OAAO;IACT,MAAM,WAAWC,iCAAgB,OAAO,SAAS;AACjD,cAAU,IAAI,SAAS;cAInB,MAAM,WAAW,EACnB,OAAMF,mCAAiB,KAAK;;;AAOpC,KAAI,CAAC,OAAO,MAAM,SAAS,EACzB,OAAMA,mCAAiB,MAAM,MAAM,SAAS,GAAI,MAAM,CAAC;CAGzD,MAAM,OAAO,+BAA+B,KAAK,IAAI,GAAG;AACxD,QAAO;EACL,GAAI,SAAS,SAAY,EAAE,MAAM,GAAG,EAAE,KAAK;EAC3C,MAAM,UAAU,IAAI,UAAU;EAC9B,OAAO,UAAU,IAAI,QAAQ;EAC7B,KAAK,UAAU,IAAI,MAAM;EACzB,MAAM,UAAU,IAAI,OAAO;EAC3B,WAAWG,iCAAe,QAAQ,MAAM,UAAU,IAAI,EAAE,CAAC;EAC1D;;;;;;;;;;;;;;;;;;;;;;;AAwBH,SAAgB,wBACd,KACA,WAAwCL,iCAAgB,EAC1C;AACd,KAAI,IAAI,SAAS,OAAW,0CAAiB,IAAI,IAAI;CACrD,IAAI,OAAO,IAAI,QAAQ;CACvB,MAAM,QAAQ,IAAI,SAAS;CAC3B,MAAM,MAAM,IAAI,OAAO;CACvB,IAAI,OAAO,IAAI,QAAQ;AAEvB,KAAI,IAAI,IAEN,KADiBI,iCAAgB,OAAO,SAAS,KAChC,UACf,QAAO;KAEP,QAAO;CAIX,MAAM,YAAsCC,iCAAe,QAAQ,MAAM;AACvE,UAAQ,GAAR;GACE,KAAK,UACH,QAAO;GACT,KAAK,QACH,QAAO;GACT,KAAK,MACH,QAAO;GACT,KAAK,OACH,QAAO;GACT,QACE,QAAO;;GAEX;AACF,QAAO;EACL,GAAI,IAAI,SAAS,SACb,EAAE,MAAM,IAAI,MAAM,GAClB,EAAE,KAAKH,mCAAiB,IAAI,IAAI,EAAE;EACtC;EACA;EACA;EACA;EACA;EACD;;;;;;;AAQH,SAAS,iCACP,QACA,UACQ;AACR,KAAI,OAAO,SAAS,OAAW,0CAAiB,OAAO,IAAI;CAC3D,MAAM,YACJ,aAAa,QACT,OAAO,QAAQ,CAAC,OAAO,OACvB,OAAO,QAAQ,CAAC,OAAO;CAE7B,MAAM,QAAuB,EAAE;AAE/B,KAAI,WAAW;AACb,QAAM,KAAK,MAAM;AACjB,MAAI,OAAO,IACT,OAAM,KAAK,MAAM;AAEnB,MAAI,OAAO,MACT,OAAM,KAAK,QAAQ;OAGrB,MAAK,MAAM,YAAYG,iCACrB,KAAI,OAAO,UAAU,SAAS,SAAS,CACrC,OAAM,KAAK,SAAS;AAK1B,OAAM,KACJ,OAAO,SAAS,SACZ,IAAI,OAAO,KAAK,KAChBH,mCAAiB,OAAO,IAAI,CACjC;AACD,QAAO,MAAM,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;AAuBxB,SAAgB,gBACd,QACA,WAAwCF,iCAAgB,EAChD;AACR,QAAO,iCACL,YAAY,QAAQ,SAAS,EAC7B,SACD;;;;;AAMH,SAAgB,0BACd,QACA,WAAwCA,iCAAgB,EAChD;AACR,QAAO,iCAAiC,QAAQ,SAAS;;;;;;AAO3D,SAAgB,4BACd,QACA,WAAwCA,iCAAgB,EAChD;AACR,QAAO,OAAO,WAAW,WACrB,gBAAgB,QAAQ,SAAS,GACjC,0BACE,wBAAwB,QAAQ,SAAS,EACzC,SACD;;;;;;;;;;;AAYP,SAAgB,cACd,KACsC;AACtC,QAAO,OAAOG,sCAAoB,IAAI,aAAa,IAAIA;;;;;;;;;;;;;;;;;;;;AAqBzD,SAAgB,mBACd,OACA,UACc;CACd,MAAM,aAAaG,+CAAuB,OAAO,SAAS;CAG1D,MAAM,OAAO,WAAW,WAAW,QAAQ,WAAW;CACtD,MAAM,MAAM,WAAW,WAAW,QAAQ,WAAW;CAErD,MAAM,QAAQ,WAAW;CAGzB,MAAM,YAAsC,EAAE;AAC9C,KAAI,KAAM,WAAU,KAAK,UAAU;AACnC,KAAI,IAAK,WAAU,KAAK,MAAM;AAC9B,KAAI,MAAO,WAAU,KAAK,QAAQ;AAClC,KAAI,WAAW,KAAM,WAAU,KAAK,OAAO;AAE3C,QAAO;EACL,KAAK,WAAW;EAChB;EACA;EACA;EACA,MAAM,WAAW;EACjB;EACD;;;;;;;;AASH,SAAgB,yBACd,OACA,WAAwCN,iCAAgB,EAChD;AACR,QAAO,iCACL,mBAAmB,OAAO,SAAS,EACnC,SACD;;;;;;;;;;;;;;;;;;;AAoBH,SAAgB,kBACd,QACA,WAAwCA,iCAAgB,EAC/C;CACT,MAAM,SACJ,OAAO,WAAW,WAAW,YAAY,QAAQ,SAAS,GAAG;AAE/D,KAAI,OAAO,SAAS,OAElB,QACE,OAAO,KAAK,SAAS,KACrB,CAAC,yCAAyC,KAAK,OAAO,KAAK;AAQ/D,QAAO,CAHe,cAAc,OAAO,IAAI,IAGtB,OAAO,IAAI,SAAS;;;;;;AAO/C,SAAgB,wBACd,QACA,WAAWA,iCAAgB,EACb;AACd,QAAO,OAAO,WAAW,WACrB,YAAY,QAAQ,SAAS,GAC7B,wBAAwB,QAAQ,SAAS"}

package/dist/parse.d.cts

@@ -1,5 +1,6 @@
-import { Hotkey, Key, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.cjs";
+import { Key } from "./key.types.cjs";
 import { MODIFIER_ALIASES } from "./constants.cjs";
+import { Hotkey, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.types.cjs";
 
 //#region src/parse.d.ts
 /**
@@ -7,7 +8,7 @@ import { MODIFIER_ALIASES } from "./constants.cjs";
  *
  * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
  * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
- * @returns A ParsedHotkey object with the key and modifier flags
+ * @returns A ParsedHotkey with either logical key or physical code and modifier flags
  *
  * @example
  * ```ts
@@ -97,7 +98,7 @@ declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MO
  * })
  * ```
  */
-declare function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey;
+declare function parseKeyboardEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
 /**
  * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
  *
@@ -123,6 +124,11 @@ declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac'
  * ```
  */
 declare function hasNonModifierKey(hotkey: Hotkey | ParsedHotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): boolean;
+/**
+ * Parses a string or raw binding, resolving Mod for the supplied platform.
+ * Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
+ */
+declare function parseRegisterableHotkey(hotkey: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): ParsedHotkey;
 //#endregion
-export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
+export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey };
 //# sourceMappingURL=parse.d.cts.map

package/dist/parse.d.ts

@@ -1,5 +1,6 @@
-import { Hotkey, Key, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.js";
+import { Key } from "./key.types.js";
 import { MODIFIER_ALIASES } from "./constants.js";
+import { Hotkey, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.types.js";
 
 //#region src/parse.d.ts
 /**
@@ -7,7 +8,7 @@ import { MODIFIER_ALIASES } from "./constants.js";
  *
  * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
  * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
- * @returns A ParsedHotkey object with the key and modifier flags
+ * @returns A ParsedHotkey with either logical key or physical code and modifier flags
  *
  * @example
  * ```ts
@@ -97,7 +98,7 @@ declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MO
  * })
  * ```
  */
-declare function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey;
+declare function parseKeyboardEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
 /**
  * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
  *
@@ -123,6 +124,11 @@ declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac'
  * ```
  */
 declare function hasNonModifierKey(hotkey: Hotkey | ParsedHotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): boolean;
+/**
+ * Parses a string or raw binding, resolving Mod for the supplied platform.
+ * Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
+ */
+declare function parseRegisterableHotkey(hotkey: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): ParsedHotkey;
 //#endregion
-export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
+export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey };
 //# sourceMappingURL=parse.d.ts.map

package/dist/parse.js

@@ -1,4 +1,6 @@
-import { MODIFIER_ALIASES, MODIFIER_ORDER, detectPlatform, normalizeKeyName, resolveModifier } from "./constants.js";
+import { MODIFIER_ALIASES, MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
+import { detectPlatform, resolveModifier } from "./platform.js";
+import { assertLogicalKey, normalizeKeyboardEvent, splitHotkeyParts } from "./_keyboard-event.js";
 
 //#region src/parse.ts
 /**
@@ -6,7 +8,7 @@ import { MODIFIER_ALIASES, MODIFIER_ORDER, detectPlatform, normalizeKeyName, res
 *
 * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
 * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
-* @returns A ParsedHotkey object with the key and modifier flags
+* @returns A ParsedHotkey with either logical key or physical code and modifier flags
 *
 * @example
 * ```ts
@@ -16,7 +18,7 @@ import { MODIFIER_ALIASES, MODIFIER_ORDER, detectPlatform, normalizeKeyName, res
 * ```
 */
 function parseHotkey(hotkey, platform = detectPlatform()) {
-	const parts = hotkey.split("+");
+	const parts = splitHotkeyParts(hotkey);
 	const modifiers = /* @__PURE__ */ new Set();
 	let key = "";
 	for (let i = 0; i < parts.length; i++) {
@@ -31,8 +33,9 @@ function parseHotkey(hotkey, platform = detectPlatform()) {
 		}
 	}
 	if (!key && parts.length > 0) key = normalizeKeyName(parts[parts.length - 1].trim());
+	const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(key)?.[1];
 	return {
-		key,
+		...code !== void 0 ? { code } : { key },
 		ctrl: modifiers.has("Control"),
 		shift: modifiers.has("Shift"),
 		alt: modifiers.has("Alt"),
@@ -62,6 +65,7 @@ function parseHotkey(hotkey, platform = detectPlatform()) {
 * ```
 */
 function rawHotkeyToParsedHotkey(raw, platform = detectPlatform()) {
+	if (raw.code === void 0) assertLogicalKey(raw.key);
 	let ctrl = raw.ctrl ?? false;
 	const shift = raw.shift ?? false;
 	const alt = raw.alt ?? false;
@@ -78,7 +82,7 @@ function rawHotkeyToParsedHotkey(raw, platform = detectPlatform()) {
 		}
 	});
 	return {
-		key: raw.key,
+		...raw.code !== void 0 ? { code: raw.code } : { key: normalizeKeyName(raw.key) },
 		ctrl,
 		shift,
 		alt,
@@ -92,6 +96,7 @@ function rawHotkeyToParsedHotkey(raw, platform = detectPlatform()) {
 * otherwise full `Control+Alt+Shift+Meta` order.
 */
 function normalizedHotkeyStringFromParsed(parsed, platform) {
+	if (parsed.code === void 0) assertLogicalKey(parsed.key);
 	const canUseMod = platform === "mac" ? parsed.meta && !parsed.ctrl : parsed.ctrl && !parsed.meta;
 	const parts = [];
 	if (canUseMod) {
@@ -99,7 +104,7 @@ function normalizedHotkeyStringFromParsed(parsed, platform) {
 		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));
+	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : normalizeKeyName(parsed.key));
 	return parts.join("+");
 }
 /**
@@ -168,19 +173,22 @@ function isModifierKey(key) {
 * })
 * ```
 */
-function parseKeyboardEvent(event) {
-	const normalizedKey = normalizeKeyName(event.key);
+function parseKeyboardEvent(event, platform) {
+	const normalized = normalizeKeyboardEvent(event, platform);
+	const ctrl = normalized.altGraph ? false : normalized.ctrl;
+	const alt = normalized.altGraph ? false : normalized.alt;
+	const shift = normalized.shift;
 	const modifiers = [];
-	if (event.ctrlKey) modifiers.push("Control");
-	if (event.altKey) modifiers.push("Alt");
-	if (event.shiftKey) modifiers.push("Shift");
-	if (event.metaKey) modifiers.push("Meta");
+	if (ctrl) modifiers.push("Control");
+	if (alt) modifiers.push("Alt");
+	if (shift) modifiers.push("Shift");
+	if (normalized.meta) modifiers.push("Meta");
 	return {
-		key: normalizedKey,
-		ctrl: event.ctrlKey,
-		shift: event.shiftKey,
-		alt: event.altKey,
-		meta: event.metaKey,
+		key: normalized.key,
+		ctrl,
+		shift,
+		alt,
+		meta: normalized.meta,
 		modifiers
 	};
 }
@@ -191,7 +199,7 @@ function parseKeyboardEvent(event) {
 * @param platform - Target platform for `Mod` eligibility
 */
 function normalizeHotkeyFromEvent(event, platform = detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform);
+	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event, platform), platform);
 }
 /**
 * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
@@ -212,9 +220,17 @@ function normalizeHotkeyFromEvent(event, platform = detectPlatform()) {
 */
 function hasNonModifierKey(hotkey, platform = detectPlatform()) {
 	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
+	if (parsed.code !== void 0) return parsed.code.length > 0 && !/^(Control|Shift|Alt|Meta)(Left|Right)$/.test(parsed.code);
 	return !isModifierKey(parsed.key) && parsed.key.length > 0;
 }
+/**
+* Parses a string or raw binding, resolving Mod for the supplied platform.
+* Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
+*/
+function parseRegisterableHotkey(hotkey, platform = detectPlatform()) {
+	return typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
+}
 
 //#endregion
-export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
+export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, 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  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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"}
+{"version":3,"file":"parse.js","names":[],"sources":["../src/parse.ts"],"sourcesContent":["import {\n  assertLogicalKey,\n  normalizeKeyboardEvent,\n  splitHotkeyParts,\n} from './_keyboard-event'\nimport { MODIFIER_ALIASES, MODIFIER_ORDER, normalizeKeyName } from './constants'\nimport { detectPlatform, resolveModifier } from './platform'\nimport type { CanonicalModifier, Key } from './key.types'\nimport type {\n  Hotkey,\n  ParsedHotkey,\n  RawHotkey,\n  RegisterableHotkey,\n} from './hotkey.types'\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 with either logical key or physical code 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 = splitHotkeyParts(hotkey)\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  const code = /^\\[([A-Za-z][A-Za-z0-9]*)\\]$/.exec(key)?.[1]\n  return {\n    ...(code !== undefined ? { code } : { 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  if (raw.code === undefined) assertLogicalKey(raw.key)\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    ...(raw.code !== undefined\n      ? { code: raw.code }\n      : { key: normalizeKeyName(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  if (parsed.code === undefined) assertLogicalKey(parsed.key)\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(\n    parsed.code !== undefined\n      ? `[${parsed.code}]`\n      : normalizeKeyName(parsed.key),\n  )\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(\n  event: KeyboardEvent,\n  platform?: 'mac' | 'windows' | 'linux',\n): ParsedHotkey {\n  const normalized = normalizeKeyboardEvent(event, platform)\n  // AltGraph is a character-production modifier, not an ordinary Control+Alt\n  // shortcut. Record the produced glyph instead of a synthetic Ctrl+Alt chord.\n  const ctrl = normalized.altGraph ? false : normalized.ctrl\n  const alt = normalized.altGraph ? false : normalized.alt\n  // Shift is a real modifier even during AltGraph input; preserve it for replay.\n  const shift = normalized.shift\n\n  // Build modifiers array in canonical order\n  const modifiers: Array<CanonicalModifier> = []\n  if (ctrl) modifiers.push('Control')\n  if (alt) modifiers.push('Alt')\n  if (shift) modifiers.push('Shift')\n  if (normalized.meta) modifiers.push('Meta')\n\n  return {\n    key: normalized.key,\n    ctrl,\n    shift,\n    alt,\n    meta: normalized.meta,\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(\n    parseKeyboardEvent(event, platform),\n    platform,\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  if (parsed.code !== undefined) {\n    // Physical modifier codes identify a side, but still are not action keys.\n    return (\n      parsed.code.length > 0 &&\n      !/^(Control|Shift|Alt|Meta)(Left|Right)$/.test(parsed.code)\n    )\n  }\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\n/**\n * Parses a string or raw binding, resolving Mod for the supplied platform.\n * Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.\n */\nexport function parseRegisterableHotkey(\n  hotkey: RegisterableHotkey,\n  platform = detectPlatform(),\n): ParsedHotkey {\n  return typeof hotkey === 'string'\n    ? parseHotkey(hotkey, platform)\n    : rawHotkeyToParsedHotkey(hotkey, platform)\n}\n"],"mappings":"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"}

package/dist/platform.cjs

@@ -0,0 +1,55 @@
+
+//#region src/platform.ts
+/**
+* Detects the current platform based on browser navigator properties.
+*
+* Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
+* Control elsewhere) and for platform-specific hotkey formatting.
+*
+* @returns The detected platform: 'mac', 'windows', or 'linux'
+* @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+*
+* @example
+* ```ts
+* const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
+* const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+* ```
+*/
+function detectPlatform() {
+	if (typeof navigator === "undefined") return "linux";
+	const platform = navigator.platform?.toLowerCase() ?? "";
+	const userAgent = navigator.userAgent?.toLowerCase() ?? "";
+	if (platform.includes("mac") || userAgent.includes("mac")) return "mac";
+	if (platform.includes("win") || userAgent.includes("win")) return "windows";
+	return "linux";
+}
+/**
+* Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
+*
+* The 'Mod' token represents the "primary modifier" on each platform:
+* - macOS: 'Meta' (Command key ⌘)
+* - Windows/Linux: 'Control' (Ctrl key)
+*
+* This enables cross-platform hotkey definitions like 'Mod+S' that automatically
+* map to Command+S on Mac and Ctrl+S on Windows/Linux.
+*
+* @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.
+* @param platform - The target platform. Defaults to auto-detection.
+* @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')
+*
+* @example
+* ```ts
+* resolveModifier('Mod', 'mac') // 'Meta'
+* resolveModifier('Mod', 'windows') // 'Control'
+* resolveModifier('Control', 'mac') // 'Control' (unchanged)
+* ```
+*/
+function resolveModifier(modifier, platform = detectPlatform()) {
+	if (modifier === "Mod") return platform === "mac" ? "Meta" : "Control";
+	return modifier;
+}
+
+//#endregion
+exports.detectPlatform = detectPlatform;
+exports.resolveModifier = resolveModifier;
+//# sourceMappingURL=platform.cjs.map

package/dist/platform.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.cjs","names":[],"sources":["../src/platform.ts"],"sourcesContent":["import type { CanonicalModifier } from './key.types'\n\n/**\n * Detects the current platform based on browser navigator properties.\n *\n * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n *\n * @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n *\n * @example\n * ```ts\n * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n */\nexport function detectPlatform(): 'mac' | 'windows' | 'linux' {\n  if (typeof navigator === 'undefined') {\n    return 'linux' // Default for SSR\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const platform = navigator.platform?.toLowerCase() ?? ''\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n  if (platform.includes('mac') || userAgent.includes('mac')) {\n    return 'mac'\n  }\n  if (platform.includes('win') || userAgent.includes('win')) {\n    return 'windows'\n  }\n  return 'linux'\n}\n\n/**\n * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n *\n * The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n *\n * This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n *\n * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n *\n * @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n */\nexport function resolveModifier(\n  modifier: CanonicalModifier | 'Mod',\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): CanonicalModifier {\n  if (modifier === 'Mod') {\n    return platform === 'mac' ? 'Meta' : 'Control'\n  }\n  return modifier\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,SAAgB,iBAA8C;AAC5D,KAAI,OAAO,cAAc,YACvB,QAAO;CAIT,MAAM,WAAW,UAAU,UAAU,aAAa,IAAI;CAEtD,MAAM,YAAY,UAAU,WAAW,aAAa,IAAI;AAExD,KAAI,SAAS,SAAS,MAAM,IAAI,UAAU,SAAS,MAAM,CACvD,QAAO;AAET,KAAI,SAAS,SAAS,MAAM,IAAI,UAAU,SAAS,MAAM,CACvD,QAAO;AAET,QAAO;;;;;;;;;;;;;;;;;;;;;;;AAwBT,SAAgB,gBACd,UACA,WAAwC,gBAAgB,EACrC;AACnB,KAAI,aAAa,MACf,QAAO,aAAa,QAAQ,SAAS;AAEvC,QAAO"}

package/dist/platform.d.cts

@@ -0,0 +1,44 @@
+import { CanonicalModifier } from "./key.types.cjs";
+
+//#region src/platform.d.ts
+/**
+ * Detects the current platform based on browser navigator properties.
+ *
+ * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
+ * Control elsewhere) and for platform-specific hotkey formatting.
+ *
+ * @returns The detected platform: 'mac', 'windows', or 'linux'
+ * @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+ *
+ * @example
+ * ```ts
+ * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
+ * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+ * ```
+ */
+declare function detectPlatform(): 'mac' | 'windows' | 'linux';
+/**
+ * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
+ *
+ * The 'Mod' token represents the "primary modifier" on each platform:
+ * - macOS: 'Meta' (Command key ⌘)
+ * - Windows/Linux: 'Control' (Ctrl key)
+ *
+ * This enables cross-platform hotkey definitions like 'Mod+S' that automatically
+ * map to Command+S on Mac and Ctrl+S on Windows/Linux.
+ *
+ * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.
+ * @param platform - The target platform. Defaults to auto-detection.
+ * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')
+ *
+ * @example
+ * ```ts
+ * resolveModifier('Mod', 'mac') // 'Meta'
+ * resolveModifier('Mod', 'windows') // 'Control'
+ * resolveModifier('Control', 'mac') // 'Control' (unchanged)
+ * ```
+ */
+declare function resolveModifier(modifier: CanonicalModifier | 'Mod', platform?: 'mac' | 'windows' | 'linux'): CanonicalModifier;
+//#endregion
+export { detectPlatform, resolveModifier };
+//# sourceMappingURL=platform.d.cts.map

package/dist/platform.d.ts

@@ -0,0 +1,44 @@
+import { CanonicalModifier } from "./key.types.js";
+
+//#region src/platform.d.ts
+/**
+ * Detects the current platform based on browser navigator properties.
+ *
+ * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
+ * Control elsewhere) and for platform-specific hotkey formatting.
+ *
+ * @returns The detected platform: 'mac', 'windows', or 'linux'
+ * @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+ *
+ * @example
+ * ```ts
+ * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
+ * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+ * ```
+ */
+declare function detectPlatform(): 'mac' | 'windows' | 'linux';
+/**
+ * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
+ *
+ * The 'Mod' token represents the "primary modifier" on each platform:
+ * - macOS: 'Meta' (Command key ⌘)
+ * - Windows/Linux: 'Control' (Ctrl key)
+ *
+ * This enables cross-platform hotkey definitions like 'Mod+S' that automatically
+ * map to Command+S on Mac and Ctrl+S on Windows/Linux.
+ *
+ * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.
+ * @param platform - The target platform. Defaults to auto-detection.
+ * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')
+ *
+ * @example
+ * ```ts
+ * resolveModifier('Mod', 'mac') // 'Meta'
+ * resolveModifier('Mod', 'windows') // 'Control'
+ * resolveModifier('Control', 'mac') // 'Control' (unchanged)
+ * ```
+ */
+declare function resolveModifier(modifier: CanonicalModifier | 'Mod', platform?: 'mac' | 'windows' | 'linux'): CanonicalModifier;
+//#endregion
+export { detectPlatform, resolveModifier };
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.js

@@ -0,0 +1,53 @@
+//#region src/platform.ts
+/**
+* Detects the current platform based on browser navigator properties.
+*
+* Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
+* Control elsewhere) and for platform-specific hotkey formatting.
+*
+* @returns The detected platform: 'mac', 'windows', or 'linux'
+* @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+*
+* @example
+* ```ts
+* const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
+* const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+* ```
+*/
+function detectPlatform() {
+	if (typeof navigator === "undefined") return "linux";
+	const platform = navigator.platform?.toLowerCase() ?? "";
+	const userAgent = navigator.userAgent?.toLowerCase() ?? "";
+	if (platform.includes("mac") || userAgent.includes("mac")) return "mac";
+	if (platform.includes("win") || userAgent.includes("win")) return "windows";
+	return "linux";
+}
+/**
+* Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
+*
+* The 'Mod' token represents the "primary modifier" on each platform:
+* - macOS: 'Meta' (Command key ⌘)
+* - Windows/Linux: 'Control' (Ctrl key)
+*
+* This enables cross-platform hotkey definitions like 'Mod+S' that automatically
+* map to Command+S on Mac and Ctrl+S on Windows/Linux.
+*
+* @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.
+* @param platform - The target platform. Defaults to auto-detection.
+* @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')
+*
+* @example
+* ```ts
+* resolveModifier('Mod', 'mac') // 'Meta'
+* resolveModifier('Mod', 'windows') // 'Control'
+* resolveModifier('Control', 'mac') // 'Control' (unchanged)
+* ```
+*/
+function resolveModifier(modifier, platform = detectPlatform()) {
+	if (modifier === "Mod") return platform === "mac" ? "Meta" : "Control";
+	return modifier;
+}
+
+//#endregion
+export { detectPlatform, resolveModifier };
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","names":[],"sources":["../src/platform.ts"],"sourcesContent":["import type { CanonicalModifier } from './key.types'\n\n/**\n * Detects the current platform based on browser navigator properties.\n *\n * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,\n * Control elsewhere) and for platform-specific hotkey formatting.\n *\n * @returns The detected platform: 'mac', 'windows', or 'linux'\n * @remarks Defaults to 'linux' in SSR environments where navigator is undefined\n *\n * @example\n * ```ts\n * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'\n * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere\n * ```\n */\nexport function detectPlatform(): 'mac' | 'windows' | 'linux' {\n  if (typeof navigator === 'undefined') {\n    return 'linux' // Default for SSR\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const platform = navigator.platform?.toLowerCase() ?? ''\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const userAgent = navigator.userAgent?.toLowerCase() ?? ''\n\n  if (platform.includes('mac') || userAgent.includes('mac')) {\n    return 'mac'\n  }\n  if (platform.includes('win') || userAgent.includes('win')) {\n    return 'windows'\n  }\n  return 'linux'\n}\n\n/**\n * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.\n *\n * The 'Mod' token represents the \"primary modifier\" on each platform:\n * - macOS: 'Meta' (Command key ⌘)\n * - Windows/Linux: 'Control' (Ctrl key)\n *\n * This enables cross-platform hotkey definitions like 'Mod+S' that automatically\n * map to Command+S on Mac and Ctrl+S on Windows/Linux.\n *\n * @param modifier - The modifier to resolve. If 'Mod', resolves based on platform.\n * @param platform - The target platform. Defaults to auto-detection.\n * @returns The canonical modifier name ('Control', 'Shift', 'Alt', or 'Meta')\n *\n * @example\n * ```ts\n * resolveModifier('Mod', 'mac') // 'Meta'\n * resolveModifier('Mod', 'windows') // 'Control'\n * resolveModifier('Control', 'mac') // 'Control' (unchanged)\n * ```\n */\nexport function resolveModifier(\n  modifier: CanonicalModifier | 'Mod',\n  platform: 'mac' | 'windows' | 'linux' = detectPlatform(),\n): CanonicalModifier {\n  if (modifier === 'Mod') {\n    return platform === 'mac' ? 'Meta' : 'Control'\n  }\n  return modifier\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,SAAgB,iBAA8C;AAC5D,KAAI,OAAO,cAAc,YACvB,QAAO;CAIT,MAAM,WAAW,UAAU,UAAU,aAAa,IAAI;CAEtD,MAAM,YAAY,UAAU,WAAW,aAAa,IAAI;AAExD,KAAI,SAAS,SAAS,MAAM,IAAI,UAAU,SAAS,MAAM,CACvD,QAAO;AAET,KAAI,SAAS,SAAS,MAAM,IAAI,UAAU,SAAS,MAAM,CACvD,QAAO;AAET,QAAO;;;;;;;;;;;;;;;;;;;;;;;AAwBT,SAAgB,gBACd,UACA,WAAwC,gBAAgB,EACrC;AACnB,KAAI,aAAa,MACf,QAAO,aAAa,QAAQ,SAAS;AAEvC,QAAO"}

package/dist/recorder-options.d.cts

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