@tanstack/hotkeys 0.8.0 → 0.9.0

package/dist/hotkey-sequence-recorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"hotkey-sequence-recorder.js","names":["#options","#platform","#idleTimer","#clearIdleTimer","#keydownHandler","#finishWithoutCommitCallback","#patchSteps","#scheduleIdleTimer","#addListener","#removeListener"],"sources":["../src/hotkey-sequence-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport { isInputElement } from './manager.utils'\nimport { hotkeyChordFromKeydown } from './recorder-chord'\nimport type { HotkeySequence } from './sequence-manager'\n\n/**\n * How the user can commit a recorded sequence from the keyboard.\n * - `'enter'`: plain Enter (no modifiers) commits when at least one step exists.\n * - `'none'`: only {@link HotkeySequenceRecorder.commit} finishes recording (or idle timeout if set).\n */\nexport type HotkeySequenceRecorderCommitKeys = 'enter' | 'none'\n\n/**\n * State interface for the HotkeySequenceRecorder.\n */\nexport interface HotkeySequenceRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** Chords captured so far in the current recording session */\n  steps: HotkeySequence\n  /** The last successfully committed sequence, or null if none / after starting a new session */\n  recordedSequence: HotkeySequence | null\n}\n\n/**\n * Options for configuring a HotkeySequenceRecorder instance.\n */\nexport interface HotkeySequenceRecorderOptions {\n  /** Callback when a sequence is successfully recorded (including empty array when cleared) */\n  onRecord: (sequence: HotkeySequence) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when the sequence is cleared (Backspace/Delete with no steps) */\n  onClear?: () => void\n  /**\n   * Whether plain Enter commits the current steps. Ignored when {@link commitKeys} is `'none'`.\n   * @default true\n   */\n  commitOnEnter?: boolean\n  /**\n   * Keyboard commit mode. When `'none'`, use {@link HotkeySequenceRecorder.commit} (and optional idle timeout).\n   * @default 'enter'\n   */\n  commitKeys?: HotkeySequenceRecorderCommitKeys\n  /**\n   * Milliseconds of inactivity after the **last completed chord** before auto-committing.\n   * The timer does not run while waiting for the first chord (`steps.length === 0`).\n   */\n  idleTimeoutMs?: number\n  /**\n   * Whether to ignore keyboard events from input-like elements (text inputs,\n   * textarea, select, contenteditable). When true, typing in inputs passes\n   * through normally instead of being captured as a sequence recording.\n   * Escape always works regardless of this setting.\n   * @default true\n   */\n  ignoreInputs?: boolean\n}\n\nconst defaultHotkeySequenceRecorderOptions: Pick<\n  HotkeySequenceRecorderOptions,\n  'commitOnEnter' | 'commitKeys'\n> = {\n  commitOnEnter: true,\n  commitKeys: 'enter',\n}\n\nfunction resolvedCommitOnEnter(\n  options: HotkeySequenceRecorderOptions,\n): boolean {\n  if (options.commitKeys === 'none') {\n    return false\n  }\n  return options.commitOnEnter !== false\n}\n\n/**\n * Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).\n *\n * Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit\n * when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,\n * **Backspace/Delete** to remove the last step or clear when empty.\n */\nexport class HotkeySequenceRecorder {\n  readonly store: Store<HotkeySequenceRecorderState> =\n    new Store<HotkeySequenceRecorderState>({\n      isRecording: false,\n      steps: [],\n      recordedSequence: null,\n    })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeySequenceRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n  #idleTimer: ReturnType<typeof setTimeout> | null = null\n\n  constructor(options: HotkeySequenceRecorderOptions) {\n    this.#options = {\n      ...defaultHotkeySequenceRecorderOptions,\n      ...options,\n    }\n    this.#platform = detectPlatform()\n  }\n\n  setOptions(options: Partial<HotkeySequenceRecorderOptions>): void {\n    this.#options = {\n      ...defaultHotkeySequenceRecorderOptions,\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  #clearIdleTimer(): void {\n    if (this.#idleTimer !== null) {\n      clearTimeout(this.#idleTimer)\n      this.#idleTimer = null\n    }\n  }\n\n  #scheduleIdleTimer(): void {\n    this.#clearIdleTimer()\n    const ms = this.#options.idleTimeoutMs\n    if (ms === undefined || ms <= 0) {\n      return\n    }\n    const steps = this.store.state.steps\n    if (steps.length === 0) {\n      return\n    }\n    this.#idleTimer = setTimeout(() => {\n      this.#idleTimer = null\n      if (!this.#keydownHandler) {\n        return\n      }\n      if (this.store.state.steps.length >= 1) {\n        this.commit()\n      }\n    }, ms)\n  }\n\n  #patchSteps(updater: (prev: HotkeySequence) => HotkeySequence): void {\n    this.store.setState((s) => ({\n      ...s,\n      steps: updater(s.steps),\n    }))\n  }\n\n  start(): void {\n    if (this.#keydownHandler) {\n      return\n    }\n\n    this.#clearIdleTimer()\n    this.store.setState(() => ({\n      isRecording: true,\n      steps: [],\n      recordedSequence: null,\n    }))\n\n    const handler = (event: KeyboardEvent) => {\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      // If ignoreInputs is enabled (default) and focus is in an input element,\n      // let the event pass through so the user can type normally.\n      // Escape is the exception — it should always cancel recording.\n      if (this.#options.ignoreInputs !== false) {\n        const activeEl =\n          typeof document !== 'undefined' ? document.activeElement : null\n        if (isInputElement(activeEl) && event.key !== 'Escape') {\n          return\n        }\n      }\n\n      event.preventDefault()\n      event.stopPropagation()\n\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          const steps = this.store.state.steps\n          if (steps.length === 0) {\n            this.#options.onClear?.()\n            this.#options.onRecord([])\n            this.#finishWithoutCommitCallback()\n            return\n          }\n          this.#patchSteps((prev) => prev.slice(0, -1))\n          const next = this.store.state.steps\n          if (next.length === 0) {\n            this.#clearIdleTimer()\n          } else {\n            this.#scheduleIdleTimer()\n          }\n          return\n        }\n      }\n\n      const enterCommits =\n        resolvedCommitOnEnter(this.#options) &&\n        event.key === 'Enter' &&\n        !event.ctrlKey &&\n        !event.shiftKey &&\n        !event.altKey &&\n        !event.metaKey\n\n      if (enterCommits && this.store.state.steps.length >= 1) {\n        this.commit()\n        return\n      }\n\n      if (enterCommits && this.store.state.steps.length === 0) {\n        return\n      }\n\n      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)\n      if (finalHotkey === null) {\n        return\n      }\n\n      this.#patchSteps((prev) => [...prev, finalHotkey])\n      this.#scheduleIdleTimer()\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Commit the current steps as a sequence. No-op if fewer than one step.\n   */\n  commit(): void {\n    const steps = this.store.state.steps\n    if (steps.length < 1) {\n      return\n    }\n\n    const sequence = [...steps]\n\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n    this.#clearIdleTimer()\n\n    this.store.setState(() => ({\n      isRecording: false,\n      steps: [],\n      recordedSequence: sequence,\n    }))\n\n    this.#options.onRecord(sequence)\n  }\n\n  #finishWithoutCommitCallback(): void {\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n    this.#clearIdleTimer()\n    this.store.setState(() => ({\n      isRecording: false,\n      steps: [],\n      recordedSequence: null,\n    }))\n  }\n\n  stop(): void {\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n    this.#clearIdleTimer()\n    this.store.setState(() => ({\n      isRecording: false,\n      steps: [],\n      recordedSequence: null,\n    }))\n  }\n\n  cancel(): void {\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n    this.#clearIdleTimer()\n    this.store.setState(() => ({\n      isRecording: false,\n      steps: [],\n      recordedSequence: null,\n    }))\n    this.#options.onCancel?.()\n  }\n\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n    document.addEventListener('keydown', handler, true)\n  }\n\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      steps: [],\n      recordedSequence: null,\n    }))\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"hotkey-sequence-recorder.js","names":["#options","#platform","#idleTimer","#clearIdleTimer","#keydownHandler","#events","#patchSteps","#scheduleIdleTimer","#addListener","#removeListener"],"sources":["../src/hotkey-sequence-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { findHotkeyConflicts } from './conflicts'\nimport {\n  beginRecording,\n  captureRecordingEvent,\n  endRecording,\n} from './_recording-guard'\nimport { chordRejection, hotkeyChordFromKeydown } from './_recorder-chord'\nimport { normalizeKeyboardEvent } from './_keyboard-event'\nimport { isModifierKey, parseHotkey } from './parse'\nimport { validateHotkey } from './validate'\nimport { detectPlatform } from './platform'\nimport { shouldIgnoreInputEvent } from './_event-target'\nimport type {\n  HotkeySequenceRecorderValidationContext,\n  RecorderOptions,\n} from './recorder-options'\nimport type { HotkeySequence } from './sequence-manager'\n\n/**\n * How the user can commit a recorded sequence from the keyboard.\n * - `'enter'`: plain Enter (no modifiers) commits when at least one step exists.\n * - `'none'`: only {@link HotkeySequenceRecorder.commit} finishes recording (or idle timeout if set).\n */\nexport type HotkeySequenceRecorderCommitKeys = 'enter' | 'none'\n\n/**\n * State interface for the HotkeySequenceRecorder.\n */\nexport interface HotkeySequenceRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** Chords captured so far in the current recording session */\n  steps: HotkeySequence\n  /** The last successfully committed sequence, or null if none / after starting a new session */\n  recordedSequence: HotkeySequence | null\n}\n\n/**\n * Options for configuring a HotkeySequenceRecorder instance.\n */\nexport interface HotkeySequenceRecorderOptions extends RecorderOptions {\n  /** Validate the completed sequence. Rejection preserves the steps for editing. */\n  validate?: (\n    sequence: HotkeySequence,\n    context: HotkeySequenceRecorderValidationContext,\n  ) => boolean | string\n  /** Callback when a sequence is successfully recorded */\n  onRecord: (sequence: HotkeySequence) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when the sequence is cleared (Backspace/Delete with no steps) */\n  onClear?: () => void\n  /**\n   * Whether plain Enter commits the current steps. Ignored when {@link commitKeys} is `'none'`.\n   * @default true\n   */\n  commitOnEnter?: boolean\n  /**\n   * Keyboard commit mode. When `'none'`, use {@link HotkeySequenceRecorder.commit} (and optional idle timeout).\n   * @default 'enter'\n   */\n  commitKeys?: HotkeySequenceRecorderCommitKeys\n  /**\n   * Milliseconds of inactivity after the **last completed chord** before auto-committing.\n   * The timer does not run while waiting for the first chord (`steps.length === 0`).\n   */\n  idleTimeoutMs?: number\n  /**\n   * Whether to ignore keyboard events from input-like elements (text inputs,\n   * textarea, select, contenteditable). When true, typing in inputs passes\n   * through normally instead of being captured as a sequence recording.\n   * Escape always works regardless of this setting.\n   * @default true\n   */\n  ignoreInputs?: boolean\n}\n\nconst defaultHotkeySequenceRecorderOptions: Pick<\n  HotkeySequenceRecorderOptions,\n  'commitOnEnter' | 'commitKeys'\n> = {\n  commitOnEnter: true,\n  commitKeys: 'enter',\n}\n\n/** Resolves the Enter policy, with commitKeys: none overriding the legacy boolean. */\nfunction resolvedCommitOnEnter(\n  options: HotkeySequenceRecorderOptions,\n): boolean {\n  if (options.commitKeys === 'none') {\n    return false\n  }\n  return options.commitOnEnter !== false\n}\n\n/**\n * Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).\n *\n * Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit\n * when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,\n * **Backspace/Delete** to remove the last step or clear when empty.\n */\nexport class HotkeySequenceRecorder {\n  readonly store: Store<HotkeySequenceRecorderState> =\n    new Store<HotkeySequenceRecorderState>({\n      isRecording: false,\n      steps: [],\n      recordedSequence: null,\n    })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeySequenceRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n  #events: Array<KeyboardEvent> = []\n  #idleTimer: ReturnType<typeof setTimeout> | null = null\n\n  constructor(options: HotkeySequenceRecorderOptions) {\n    this.#options = {\n      ...defaultHotkeySequenceRecorderOptions,\n      ...options,\n    }\n    this.#platform = detectPlatform()\n  }\n\n  /** Merges current callbacks and options without discarding recorded steps. */\n  setOptions(options: Partial<HotkeySequenceRecorderOptions>): void {\n    this.#options = {\n      ...defaultHotkeySequenceRecorderOptions,\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /** Cancels a pending idle commit so it cannot fire after editing or stopping. */\n  #clearIdleTimer(): void {\n    if (this.#idleTimer !== null) {\n      clearTimeout(this.#idleTimer)\n      this.#idleTimer = null\n    }\n  }\n\n  /** Restarts optional idle commit after a step is recorded or edited. */\n  #scheduleIdleTimer(): void {\n    this.#clearIdleTimer()\n    const ms = this.#options.idleTimeoutMs\n    if (ms === undefined || ms <= 0) {\n      return\n    }\n    const steps = this.store.state.steps\n    if (steps.length === 0) {\n      return\n    }\n    this.#idleTimer = setTimeout(() => {\n      this.#idleTimer = null\n      if (!this.#keydownHandler) {\n        return\n      }\n      if (this.store.state.steps.length >= 1) {\n        this.commit()\n      }\n    }, ms)\n  }\n\n  /** Publishes edited steps while preserving the remaining recorder state. */\n  #patchSteps(updater: (prev: HotkeySequence) => HotkeySequence): void {\n    this.store.setState((s) => ({\n      ...s,\n      steps: updater(s.steps),\n    }))\n  }\n\n  /** Starts a fresh recording; repeated starts during an active session are ignored. */\n  start(): void {\n    if (this.#keydownHandler) {\n      return\n    }\n\n    this.#clearIdleTimer()\n    this.#events = []\n    beginRecording(this)\n    this.store.setState(() => ({\n      isRecording: true,\n      steps: [],\n      recordedSequence: null,\n    }))\n\n    const handler = (event: KeyboardEvent) => {\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      // If ignoreInputs is enabled (default) and focus is in an input element,\n      // let the event pass through so the user can type normally.\n      // Escape is the exception — it should always cancel recording.\n      if (\n        this.#options.ignoreInputs !== false &&\n        event.key !== 'Escape' &&\n        shouldIgnoreInputEvent(event, document, document)\n      )\n        return\n\n      const platform = this.#options.platform ?? this.#platform\n      if (normalizeKeyboardEvent(event, platform).isComposing) return\n      captureRecordingEvent(event)\n      event.preventDefault()\n      event.stopPropagation()\n      if (event.repeat) return\n\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          const steps = this.store.state.steps\n          if (steps.length === 0) {\n            this.stop()\n            this.#options.onClear?.()\n            return\n          }\n          this.#events.pop()\n          this.#patchSteps((prev) => prev.slice(0, -1))\n          const next = this.store.state.steps\n          if (next.length === 0) {\n            this.#clearIdleTimer()\n          } else {\n            this.#scheduleIdleTimer()\n          }\n          return\n        }\n      }\n\n      const enterCommits =\n        resolvedCommitOnEnter(this.#options) &&\n        event.key === 'Enter' &&\n        !event.ctrlKey &&\n        !event.shiftKey &&\n        !event.altKey &&\n        !event.metaKey\n\n      if (enterCommits && this.store.state.steps.length >= 1) {\n        this.commit()\n        return\n      }\n\n      if (enterCommits && this.store.state.steps.length === 0) {\n        return\n      }\n\n      if (isModifierKey(event.key) || event.key === 'AltGraph') return\n      const rejection = chordRejection(event, { ...this.#options, platform })\n      if (rejection) {\n        this.#options.onReject?.(rejection)\n        return\n      }\n      const finalHotkey = hotkeyChordFromKeydown(\n        event,\n        platform,\n        this.#options.recordBy,\n      )\n      if (finalHotkey === null) {\n        return\n      }\n\n      const validation = validateHotkey(finalHotkey)\n      if (!validation.valid) {\n        this.#options.onReject?.({\n          reason: 'invalid',\n          message: validation.errors.join('; '),\n          hotkey: finalHotkey,\n        })\n        return\n      }\n      this.#events.push(event)\n      this.#patchSteps((prev) => [...prev, finalHotkey])\n      this.#scheduleIdleTimer()\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Commit the current steps as a sequence. No-op if fewer than one step.\n   */\n  commit(): void {\n    const steps = this.store.state.steps\n    if (steps.length < 1) {\n      return\n    }\n\n    const sequence = [...steps]\n    const platform = this.#options.platform ?? this.#platform\n    this.#clearIdleTimer()\n    const accepted = this.#options.validate?.(sequence, {\n      events: [...this.#events],\n      parsedSequence: sequence.map((step) => parseHotkey(step, platform)),\n    })\n    if (accepted !== undefined && accepted !== true) {\n      this.#options.onReject?.({\n        reason: 'validation',\n        message:\n          typeof accepted === 'string'\n            ? accepted\n            : 'This sequence is not allowed.',\n        sequence,\n      })\n      return\n    }\n    if (this.#options.detectConflicts) {\n      const conflicts = findHotkeyConflicts(sequence, {\n        ...(typeof this.#options.detectConflicts === 'object'\n          ? this.#options.detectConflicts\n          : {}),\n        platform,\n        events: this.#events,\n      })\n      if (conflicts.length) {\n        this.#options.onReject?.({\n          reason: 'conflict',\n          message: 'This sequence conflicts with a registered binding.',\n          sequence,\n          conflicts,\n        })\n        return\n      }\n    }\n    endRecording(this)\n    this.#events = []\n\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n    this.#clearIdleTimer()\n\n    this.store.setState(() => ({\n      isRecording: false,\n      steps: [],\n      recordedSequence: sequence,\n    }))\n\n    this.#options.onRecord(sequence)\n  }\n\n  /** Stops and discards in-progress steps without invoking onCancel. */\n  stop(): void {\n    endRecording(this)\n    this.#events = []\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n    this.#clearIdleTimer()\n    this.store.setState(() => ({\n      isRecording: false,\n      steps: [],\n      recordedSequence: null,\n    }))\n  }\n\n  /** Stops, discards in-progress steps, and notifies onCancel. */\n  cancel(): void {\n    endRecording(this)\n    this.#events = []\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n    this.#clearIdleTimer()\n    this.store.setState(() => ({\n      isRecording: false,\n      steps: [],\n      recordedSequence: null,\n    }))\n    this.#options.onCancel?.()\n  }\n\n  /** Captures keydowns before application handlers, with an SSR-safe document check. */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /** Detaches the capture listener when recording ends. */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      steps: [],\n      recordedSequence: null,\n    }))\n  }\n}\n"],"mappings":"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"}

package/dist/{hotkey.d.ts → hotkey.types.d.cts}

@@ -1,66 +1,9 @@
-//#region src/hotkey.d.ts
-/**
- * All supported modifier key names, including aliases.
- * - Control/Ctrl: The Control key
- * - Shift: The Shift key
- * - Alt/Option: The Alt key (Option on macOS)
- * - Command/Cmd: The Command key (macOS only)
- * - CommandOrControl/Mod: Command on macOS, Control on other platforms
- */
-type Modifier = 'Control' | 'Ctrl' | 'Shift' | 'Alt' | 'Option' | 'Command' | 'Cmd' | 'CommandOrControl' | 'Mod';
-/**
- * Canonical modifier names that map to KeyboardEvent properties.
- */
-type CanonicalModifier = 'Control' | 'Shift' | 'Alt' | 'Meta';
-/**
- * Letter keys A-Z (case-insensitive in matching).
- */
-type LetterKey = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
-/**
- * Number keys 0-9.
- */
-type NumberKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
-/**
- * Function keys F1-F12.
- */
-type FunctionKey = 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12';
-/**
- * Navigation keys for cursor movement.
- */
-type NavigationKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
-/**
- * Editing and special keys.
- */
-type EditingKey = 'Enter' | 'Escape' | 'Space' | 'Tab' | 'Backspace' | 'Delete';
-/**
- * Punctuation keys commonly used in keyboard shortcuts.
- * These are the literal characters as they appear in KeyboardEvent.key
- * (layout-dependent, typically US keyboard layout).
- */
-type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | ';' | '`';
-/**
- * Keys that don't change their value when Shift is pressed.
- * These keys produce the same `KeyboardEvent.key` value whether Shift is held or not.
- *
- * Excludes NumberKey (Shift+1 produces '!' on US layout) and PunctuationKey
- * (Shift+',' produces '<' on US layout).
- *
- * Used in hotkey type definitions to prevent layout-dependent issues when Shift
- * is part of the modifier combination.
- */
-type NonPunctuationKey = LetterKey | NumberKey | EditingKey | NavigationKey | FunctionKey;
-/**
- * All supported non-modifier keys.
- */
-type Key = NonPunctuationKey | PunctuationKey;
-/**
- * Includes both modifier keys and regular keys.
- */
-type IndividualKey = CanonicalModifier | Key;
+import { CanonicalModifier, Key, LogicalKey } from "./key.types.cjs";
+
+//#region src/hotkey.types.d.ts
 /**
  * Single modifier + key combinations.
  * Uses canonical modifiers (4) + Mod (1) = 5 modifiers.
- * Shift combinations exclude PunctuationKey to avoid layout-dependent issues.
  *
  * The `Mod` modifier is platform-adaptive:
  * - **macOS**: Resolves to `Meta` (Command key ⌘)
@@ -69,10 +12,9 @@ type IndividualKey = CanonicalModifier | Key;
  * This enables cross-platform hotkey definitions that automatically adapt to the platform.
  * For example, `Mod+S` becomes `Command+S` on Mac and `Ctrl+S` on Windows/Linux.
  */
-type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${NonPunctuationKey}` | `Meta+${Key}` | `Mod+${Key}`;
+type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${Key}` | `Meta+${Key}` | `Mod+${Key}`;
 /**
  * Two modifier + key combinations.
- * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
  *
  * **Platform-adaptive `Mod` combinations:**
  * - `Mod+Alt` and `Mod+Shift` are included (safe on all platforms)
@@ -80,10 +22,9 @@ type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${NonPunctu
  *   - `Mod+Control` duplicates `Control` on Windows/Linux (Mod = Control)
  *   - `Mod+Meta` duplicates `Meta` on macOS (Mod = Meta)
  */
-type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${NonPunctuationKey}` | `Control+Meta+${Key}` | `Alt+Shift+${NonPunctuationKey}` | `Alt+Meta+${Key}` | `Shift+Meta+${NonPunctuationKey}` | `Mod+Alt+${Key}` | `Mod+Shift+${NonPunctuationKey}`;
+type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${Key}` | `Control+Meta+${Key}` | `Alt+Shift+${Key}` | `Alt+Meta+${Key}` | `Shift+Meta+${Key}` | `Mod+Alt+${Key}` | `Mod+Shift+${Key}`;
 /**
  * Three modifier + key combinations.
- * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
  *
  * **Platform-adaptive `Mod` combinations:**
  * - `Mod+Alt+Shift` is included (safe on all platforms)
@@ -91,10 +32,9 @@ type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${NonPunctuationK
  *   - `Mod+Control+Shift` duplicates `Control` on Windows/Linux (Mod = Control)
  *   - `Mod+Shift+Meta` duplicates `Meta` on macOS (Mod = Meta)
  */
-type ThreeModifierHotkey = `Control+Alt+Shift+${NonPunctuationKey}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${NonPunctuationKey}` | `Alt+Shift+Meta+${NonPunctuationKey}` | `Mod+Alt+Shift+${NonPunctuationKey}`;
+type ThreeModifierHotkey = `Control+Alt+Shift+${Key}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${Key}` | `Alt+Shift+Meta+${Key}` | `Mod+Alt+Shift+${Key}`;
 /**
  * Four modifier + key combinations.
- * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
  *
  * Only the canonical `Control+Alt+Shift+Meta` combination is included.
  *
@@ -105,7 +45,7 @@ type ThreeModifierHotkey = `Control+Alt+Shift+${NonPunctuationKey}` | `Control+A
  * - `Mod+Control+Alt+Shift` → duplicates `Control` on Windows/Linux
  * - `Mod+Alt+Shift+Meta` → duplicates `Meta` on macOS
  */
-type FourModifierHotkey = `Control+Alt+Shift+Meta+${NonPunctuationKey}`;
+type FourModifierHotkey = `Control+Alt+Shift+Meta+${Key}`;
 /**
  * A type-safe hotkey string.
  *
@@ -159,38 +99,35 @@ type FourModifierHotkey = `Control+Alt+Shift+Meta+${NonPunctuationKey}`;
  * ```
  */
 type Hotkey = Key | SingleModifierHotkey | TwoModifierHotkey | ThreeModifierHotkey | FourModifierHotkey;
-/**
- * A parsed representation of a hotkey string.
- *
- * This interface provides a flexible fallback when the `Hotkey` type doesn't
- * fit your use case. You can pass a `ParsedHotkey` directly to hotkey functions
- * instead of a hotkey string, allowing for more dynamic or complex scenarios
- * that aren't covered by the type-safe `Hotkey` union.
- *
- * @example
- * ```ts
- * // Type-safe hotkey string
- * useHotkey('Mod+S', handler)
- *
- * // Fallback: parsed hotkey for dynamic scenarios
- * const parsed = parseHotkey(userInput)
- * useHotkey(parsed, handler) // Works even if userInput isn't in Hotkey type
- * ```
- */
-interface ParsedHotkey {
-  /** The non-modifier key (e.g., 'S', 'Escape', 'F1', '/', '['). Can be any string for flexibility. */
-  key: Key | (string & {});
-  /** Whether the Control key is required */
+/** Resolved modifier flags shared by both parsed binding variants. */
+interface ParsedModifiers {
+  /** Whether Control is required. */
   ctrl: boolean;
-  /** Whether the Shift key is required */
+  /** Whether Shift is required. */
   shift: boolean;
-  /** Whether the Alt key is required */
+  /** Whether Alt is required. */
   alt: boolean;
-  /** Whether the Meta (Command) key is required */
+  /** Whether Meta (Command) is required. */
   meta: boolean;
-  /** List of canonical modifier names that are required, in canonical order */
+  /** Required modifiers in canonical order. */
   modifiers: Array<CanonicalModifier>;
 }
+/**
+ * A parsed binding matches either a logical key or a physical code, never both.
+ * Check `code !== undefined` to narrow to a physical binding. Its logical
+ * character is unknown without a keyboard event and is not stored in `key`.
+ *
+ * @example
+ * parseHotkey('Alt+S') // { key: 'S', alt: true, ... }
+ * parseHotkey('Alt+[KeyS]') // { code: 'KeyS', alt: true, ... } — no key property
+ */
+type ParsedHotkey = ParsedModifiers & ({
+  key: LogicalKey | (string & {});
+  code?: never;
+} | {
+  code: string;
+  key?: never;
+});
 /**
  * A raw hotkey object for programmatic registration.
  *
@@ -209,11 +146,13 @@ interface ParsedHotkey {
  * useHotkey({ key: 'Escape' }, handler)                   // Escape (no modifiers)
  * useHotkey({ key: 'A', shift: true, meta: true }, handler) // Shift+Meta+A
  * useHotkey({ key: 'S', mod: true, shift: true }, handler)  // Mod+Shift+S
+ * useHotkey({ code: 'KeyW', mod: true }, handler)           // Physical Mod+KeyW
+ * useHotkey({ code: 'NumpadAdd', mod: true }, handler)      // Physical numpad plus
  * ```
  */
-interface RawHotkey {
+/** Modifier flags shared by logical-key and physical-code registrations. */
+interface RawModifiers {
   /** The non-modifier key (e.g., 'S', 'Escape', 'F1'). */
-  key: Key | (string & {});
   /** Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults to false. */
   mod?: boolean;
   /** Whether the Control key is required. Defaults to false. */
@@ -225,33 +164,18 @@ interface RawHotkey {
   /** Whether the Meta (Command) key is required. Defaults to false. */
   meta?: boolean;
 }
+type RawHotkey = ({
+  key: LogicalKey | (string & {});
+  code?: never;
+} & RawModifiers) | ({
+  code: string;
+  key?: never;
+} & RawModifiers);
 /**
  * A hotkey that can be passed to `HotkeyManager.register()` and `useHotkey()`.
  * Either a type-safe string (`Hotkey`) or a raw object (`RawHotkey`).
  */
 type RegisterableHotkey = Hotkey | RawHotkey;
-/**
- * Options for formatting hotkeys for display.
- */
-interface FormatDisplayOptions {
-  /** The target platform. Defaults to auto-detection. */
-  platform?: 'mac' | 'windows' | 'linux';
-  /** Whether to use symbols for the display. Defaults to true. */
-  useSymbols?: boolean;
-  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
-  separatorToken?: string | null;
-}
-/**
- * Result of validating a hotkey string.
- */
-interface ValidationResult {
-  /** Whether the hotkey is valid (can still have warnings) */
-  valid: boolean;
-  /** Warning messages about potential issues */
-  warnings: Array<string>;
-  /** Error messages about invalid syntax */
-  errors: Array<string>;
-}
 /**
  * Context passed to hotkey callbacks along with the keyboard event.
  */
@@ -278,7 +202,7 @@ interface HotkeyCallbackContext {
 type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
 /**
  * Metadata for hotkey and sequence registrations.
- * Includes `name` and `description` by default. Extend via declaration merging:
+ * Includes `name`, `description`, and `group` by default. Extend via declaration merging:
  *
  * @example
  * ```ts
@@ -295,7 +219,18 @@ interface HotkeyMeta {
   name?: string;
   /** Description of what this hotkey does */
   description?: string;
+  /** Optional display group. Does not affect matching or scope. */
+  group?: string;
 }
+/**
+ * Behavior when registering a hotkey/sequence that conflicts with an existing registration.
+ *
+ * - `'warn'` - Log a warning to the console but allow both registrations (default)
+ * - `'error'` - Throw an error and prevent the new registration
+ * - `'replace'` - Unregister the existing registration and register the new one
+ * - `'allow'` - Allow multiple registrations without warning
+ */
+type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
 //#endregion
-export { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, IndividualKey, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult };
-//# sourceMappingURL=hotkey.d.ts.map
+export { ConflictBehavior, FourModifierHotkey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, ParsedHotkey, ParsedModifiers, RawHotkey, RawModifiers, RegisterableHotkey, SingleModifierHotkey, ThreeModifierHotkey, TwoModifierHotkey };
+//# sourceMappingURL=hotkey.types.d.cts.map

package/dist/{hotkey.d.cts → hotkey.types.d.ts}

@@ -1,66 +1,9 @@
-//#region src/hotkey.d.ts
-/**
- * All supported modifier key names, including aliases.
- * - Control/Ctrl: The Control key
- * - Shift: The Shift key
- * - Alt/Option: The Alt key (Option on macOS)
- * - Command/Cmd: The Command key (macOS only)
- * - CommandOrControl/Mod: Command on macOS, Control on other platforms
- */
-type Modifier = 'Control' | 'Ctrl' | 'Shift' | 'Alt' | 'Option' | 'Command' | 'Cmd' | 'CommandOrControl' | 'Mod';
-/**
- * Canonical modifier names that map to KeyboardEvent properties.
- */
-type CanonicalModifier = 'Control' | 'Shift' | 'Alt' | 'Meta';
-/**
- * Letter keys A-Z (case-insensitive in matching).
- */
-type LetterKey = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
-/**
- * Number keys 0-9.
- */
-type NumberKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
-/**
- * Function keys F1-F12.
- */
-type FunctionKey = 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12';
-/**
- * Navigation keys for cursor movement.
- */
-type NavigationKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
-/**
- * Editing and special keys.
- */
-type EditingKey = 'Enter' | 'Escape' | 'Space' | 'Tab' | 'Backspace' | 'Delete';
-/**
- * Punctuation keys commonly used in keyboard shortcuts.
- * These are the literal characters as they appear in KeyboardEvent.key
- * (layout-dependent, typically US keyboard layout).
- */
-type PunctuationKey = '/' | '[' | ']' | '\\' | '=' | '-' | ',' | '.' | ';' | '`';
-/**
- * Keys that don't change their value when Shift is pressed.
- * These keys produce the same `KeyboardEvent.key` value whether Shift is held or not.
- *
- * Excludes NumberKey (Shift+1 produces '!' on US layout) and PunctuationKey
- * (Shift+',' produces '<' on US layout).
- *
- * Used in hotkey type definitions to prevent layout-dependent issues when Shift
- * is part of the modifier combination.
- */
-type NonPunctuationKey = LetterKey | NumberKey | EditingKey | NavigationKey | FunctionKey;
-/**
- * All supported non-modifier keys.
- */
-type Key = NonPunctuationKey | PunctuationKey;
-/**
- * Includes both modifier keys and regular keys.
- */
-type IndividualKey = CanonicalModifier | Key;
+import { CanonicalModifier, Key, LogicalKey } from "./key.types.js";
+
+//#region src/hotkey.types.d.ts
 /**
  * Single modifier + key combinations.
  * Uses canonical modifiers (4) + Mod (1) = 5 modifiers.
- * Shift combinations exclude PunctuationKey to avoid layout-dependent issues.
  *
  * The `Mod` modifier is platform-adaptive:
  * - **macOS**: Resolves to `Meta` (Command key ⌘)
@@ -69,10 +12,9 @@ type IndividualKey = CanonicalModifier | Key;
  * This enables cross-platform hotkey definitions that automatically adapt to the platform.
  * For example, `Mod+S` becomes `Command+S` on Mac and `Ctrl+S` on Windows/Linux.
  */
-type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${NonPunctuationKey}` | `Meta+${Key}` | `Mod+${Key}`;
+type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${Key}` | `Meta+${Key}` | `Mod+${Key}`;
 /**
  * Two modifier + key combinations.
- * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
  *
  * **Platform-adaptive `Mod` combinations:**
  * - `Mod+Alt` and `Mod+Shift` are included (safe on all platforms)
@@ -80,10 +22,9 @@ type SingleModifierHotkey = `Control+${Key}` | `Alt+${Key}` | `Shift+${NonPunctu
  *   - `Mod+Control` duplicates `Control` on Windows/Linux (Mod = Control)
  *   - `Mod+Meta` duplicates `Meta` on macOS (Mod = Meta)
  */
-type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${NonPunctuationKey}` | `Control+Meta+${Key}` | `Alt+Shift+${NonPunctuationKey}` | `Alt+Meta+${Key}` | `Shift+Meta+${NonPunctuationKey}` | `Mod+Alt+${Key}` | `Mod+Shift+${NonPunctuationKey}`;
+type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${Key}` | `Control+Meta+${Key}` | `Alt+Shift+${Key}` | `Alt+Meta+${Key}` | `Shift+Meta+${Key}` | `Mod+Alt+${Key}` | `Mod+Shift+${Key}`;
 /**
  * Three modifier + key combinations.
- * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
  *
  * **Platform-adaptive `Mod` combinations:**
  * - `Mod+Alt+Shift` is included (safe on all platforms)
@@ -91,10 +32,9 @@ type TwoModifierHotkey = `Control+Alt+${Key}` | `Control+Shift+${NonPunctuationK
  *   - `Mod+Control+Shift` duplicates `Control` on Windows/Linux (Mod = Control)
  *   - `Mod+Shift+Meta` duplicates `Meta` on macOS (Mod = Meta)
  */
-type ThreeModifierHotkey = `Control+Alt+Shift+${NonPunctuationKey}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${NonPunctuationKey}` | `Alt+Shift+Meta+${NonPunctuationKey}` | `Mod+Alt+Shift+${NonPunctuationKey}`;
+type ThreeModifierHotkey = `Control+Alt+Shift+${Key}` | `Control+Alt+Meta+${Key}` | `Control+Shift+Meta+${Key}` | `Alt+Shift+Meta+${Key}` | `Mod+Alt+Shift+${Key}`;
 /**
  * Four modifier + key combinations.
- * Shift combinations exclude Numbers and PunctuationKeys to avoid layout-dependent issues.
  *
  * Only the canonical `Control+Alt+Shift+Meta` combination is included.
  *
@@ -105,7 +45,7 @@ type ThreeModifierHotkey = `Control+Alt+Shift+${NonPunctuationKey}` | `Control+A
  * - `Mod+Control+Alt+Shift` → duplicates `Control` on Windows/Linux
  * - `Mod+Alt+Shift+Meta` → duplicates `Meta` on macOS
  */
-type FourModifierHotkey = `Control+Alt+Shift+Meta+${NonPunctuationKey}`;
+type FourModifierHotkey = `Control+Alt+Shift+Meta+${Key}`;
 /**
  * A type-safe hotkey string.
  *
@@ -159,38 +99,35 @@ type FourModifierHotkey = `Control+Alt+Shift+Meta+${NonPunctuationKey}`;
  * ```
  */
 type Hotkey = Key | SingleModifierHotkey | TwoModifierHotkey | ThreeModifierHotkey | FourModifierHotkey;
-/**
- * A parsed representation of a hotkey string.
- *
- * This interface provides a flexible fallback when the `Hotkey` type doesn't
- * fit your use case. You can pass a `ParsedHotkey` directly to hotkey functions
- * instead of a hotkey string, allowing for more dynamic or complex scenarios
- * that aren't covered by the type-safe `Hotkey` union.
- *
- * @example
- * ```ts
- * // Type-safe hotkey string
- * useHotkey('Mod+S', handler)
- *
- * // Fallback: parsed hotkey for dynamic scenarios
- * const parsed = parseHotkey(userInput)
- * useHotkey(parsed, handler) // Works even if userInput isn't in Hotkey type
- * ```
- */
-interface ParsedHotkey {
-  /** The non-modifier key (e.g., 'S', 'Escape', 'F1', '/', '['). Can be any string for flexibility. */
-  key: Key | (string & {});
-  /** Whether the Control key is required */
+/** Resolved modifier flags shared by both parsed binding variants. */
+interface ParsedModifiers {
+  /** Whether Control is required. */
   ctrl: boolean;
-  /** Whether the Shift key is required */
+  /** Whether Shift is required. */
   shift: boolean;
-  /** Whether the Alt key is required */
+  /** Whether Alt is required. */
   alt: boolean;
-  /** Whether the Meta (Command) key is required */
+  /** Whether Meta (Command) is required. */
   meta: boolean;
-  /** List of canonical modifier names that are required, in canonical order */
+  /** Required modifiers in canonical order. */
   modifiers: Array<CanonicalModifier>;
 }
+/**
+ * A parsed binding matches either a logical key or a physical code, never both.
+ * Check `code !== undefined` to narrow to a physical binding. Its logical
+ * character is unknown without a keyboard event and is not stored in `key`.
+ *
+ * @example
+ * parseHotkey('Alt+S') // { key: 'S', alt: true, ... }
+ * parseHotkey('Alt+[KeyS]') // { code: 'KeyS', alt: true, ... } — no key property
+ */
+type ParsedHotkey = ParsedModifiers & ({
+  key: LogicalKey | (string & {});
+  code?: never;
+} | {
+  code: string;
+  key?: never;
+});
 /**
  * A raw hotkey object for programmatic registration.
  *
@@ -209,11 +146,13 @@ interface ParsedHotkey {
  * useHotkey({ key: 'Escape' }, handler)                   // Escape (no modifiers)
  * useHotkey({ key: 'A', shift: true, meta: true }, handler) // Shift+Meta+A
  * useHotkey({ key: 'S', mod: true, shift: true }, handler)  // Mod+Shift+S
+ * useHotkey({ code: 'KeyW', mod: true }, handler)           // Physical Mod+KeyW
+ * useHotkey({ code: 'NumpadAdd', mod: true }, handler)      // Physical numpad plus
  * ```
  */
-interface RawHotkey {
+/** Modifier flags shared by logical-key and physical-code registrations. */
+interface RawModifiers {
   /** The non-modifier key (e.g., 'S', 'Escape', 'F1'). */
-  key: Key | (string & {});
   /** Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults to false. */
   mod?: boolean;
   /** Whether the Control key is required. Defaults to false. */
@@ -225,33 +164,18 @@ interface RawHotkey {
   /** Whether the Meta (Command) key is required. Defaults to false. */
   meta?: boolean;
 }
+type RawHotkey = ({
+  key: LogicalKey | (string & {});
+  code?: never;
+} & RawModifiers) | ({
+  code: string;
+  key?: never;
+} & RawModifiers);
 /**
  * A hotkey that can be passed to `HotkeyManager.register()` and `useHotkey()`.
  * Either a type-safe string (`Hotkey`) or a raw object (`RawHotkey`).
  */
 type RegisterableHotkey = Hotkey | RawHotkey;
-/**
- * Options for formatting hotkeys for display.
- */
-interface FormatDisplayOptions {
-  /** The target platform. Defaults to auto-detection. */
-  platform?: 'mac' | 'windows' | 'linux';
-  /** Whether to use symbols for the display. Defaults to true. */
-  useSymbols?: boolean;
-  /** Override the separator between display tokens. Defaults to platform-specific formatting when null/undefined. */
-  separatorToken?: string | null;
-}
-/**
- * Result of validating a hotkey string.
- */
-interface ValidationResult {
-  /** Whether the hotkey is valid (can still have warnings) */
-  valid: boolean;
-  /** Warning messages about potential issues */
-  warnings: Array<string>;
-  /** Error messages about invalid syntax */
-  errors: Array<string>;
-}
 /**
  * Context passed to hotkey callbacks along with the keyboard event.
  */
@@ -278,7 +202,7 @@ interface HotkeyCallbackContext {
 type HotkeyCallback = (event: KeyboardEvent, context: HotkeyCallbackContext) => void;
 /**
  * Metadata for hotkey and sequence registrations.
- * Includes `name` and `description` by default. Extend via declaration merging:
+ * Includes `name`, `description`, and `group` by default. Extend via declaration merging:
  *
  * @example
  * ```ts
@@ -295,7 +219,18 @@ interface HotkeyMeta {
   name?: string;
   /** Description of what this hotkey does */
   description?: string;
+  /** Optional display group. Does not affect matching or scope. */
+  group?: string;
 }
+/**
+ * Behavior when registering a hotkey/sequence that conflicts with an existing registration.
+ *
+ * - `'warn'` - Log a warning to the console but allow both registrations (default)
+ * - `'error'` - Throw an error and prevent the new registration
+ * - `'replace'` - Unregister the existing registration and register the new one
+ * - `'allow'` - Allow multiple registrations without warning
+ */
+type ConflictBehavior = 'warn' | 'error' | 'replace' | 'allow';
 //#endregion
-export { CanonicalModifier, EditingKey, FormatDisplayOptions, FunctionKey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, IndividualKey, Key, LetterKey, Modifier, NavigationKey, NumberKey, ParsedHotkey, PunctuationKey, RawHotkey, RegisterableHotkey, ValidationResult };
-//# sourceMappingURL=hotkey.d.cts.map
+export { ConflictBehavior, FourModifierHotkey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, ParsedHotkey, ParsedModifiers, RawHotkey, RawModifiers, RegisterableHotkey, SingleModifierHotkey, ThreeModifierHotkey, TwoModifierHotkey };
+//# sourceMappingURL=hotkey.types.d.ts.map