@tanstack/hotkeys 0.4.3 → 0.6.0

package/dist/{recorder.d.ts → hotkey-recorder.d.ts}

@@ -1,7 +1,7 @@
 import { Hotkey } from "./hotkey.js";
 import { Store } from "@tanstack/store";
 
-//#region src/recorder.d.ts
+//#region src/hotkey-recorder.d.ts
 /**
  * State interface for the HotkeyRecorder.
  */
@@ -105,4 +105,4 @@ declare class HotkeyRecorder {
 }
 //#endregion
 export { HotkeyRecorder, HotkeyRecorderOptions, HotkeyRecorderState };
-//# sourceMappingURL=recorder.d.ts.map
+//# sourceMappingURL=hotkey-recorder.d.ts.map

package/dist/{recorder.js → hotkey-recorder.js}

@@ -1,8 +1,8 @@
 import { detectPlatform } from "./constants.js";
-import { convertToModFormat, hasNonModifierKey, isModifierKey, keyboardEventToHotkey } from "./parse.js";
+import { hotkeyChordFromKeydown } from "./recorder-chord.js";
 import { Store } from "@tanstack/store";
 
-//#region src/recorder.ts
+//#region src/hotkey-recorder.ts
 /**
 * Framework-agnostic class for recording keyboard shortcuts.
 *
@@ -93,20 +93,18 @@ var HotkeyRecorder = class {
 					return;
 				}
 			}
-			if (isModifierKey(event)) return;
-			const finalHotkey = convertToModFormat(keyboardEventToHotkey(event), this.#platform);
-			if (hasNonModifierKey(finalHotkey, this.#platform)) {
-				const handlerToRemove = this.#keydownHandler;
-				if (handlerToRemove) {
-					this.#removeListener(handlerToRemove);
-					this.#keydownHandler = null;
-				}
-				this.store.setState(() => ({
-					isRecording: false,
-					recordedHotkey: finalHotkey
-				}));
-				this.#options.onRecord(finalHotkey);
+			const finalHotkey = hotkeyChordFromKeydown(event, this.#platform);
+			if (finalHotkey === null) return;
+			const handlerToRemove = this.#keydownHandler;
+			if (handlerToRemove) {
+				this.#removeListener(handlerToRemove);
+				this.#keydownHandler = null;
 			}
+			this.store.setState(() => ({
+				isRecording: false,
+				recordedHotkey: finalHotkey
+			}));
+			this.#options.onRecord(finalHotkey);
 		};
 		this.#keydownHandler = handler;
 		this.#addListener(handler);
@@ -174,4 +172,4 @@ var HotkeyRecorder = class {
 
 //#endregion
 export { HotkeyRecorder };
-//# sourceMappingURL=recorder.js.map
+//# sourceMappingURL=hotkey-recorder.js.map

package/dist/hotkey-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotkey-recorder.js","names":["#options","#platform","#keydownHandler","#removeListener","#addListener"],"sources":["../src/hotkey-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\nimport { hotkeyChordFromKeydown } from './recorder-chord'\nimport type { Hotkey } from './hotkey'\n\n/**\n * State interface for the HotkeyRecorder.\n */\nexport interface HotkeyRecorderState {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n}\n\n/**\n * Options for configuring a HotkeyRecorder instance.\n */\nexport interface HotkeyRecorderOptions {\n  /** Callback when a hotkey is successfully recorded */\n  onRecord: (hotkey: Hotkey) => void\n  /** Optional callback when recording is cancelled (Escape pressed) */\n  onCancel?: () => void\n  /** Optional callback when shortcut is cleared (Backspace/Delete pressed) */\n  onClear?: () => void\n}\n\n/**\n * Framework-agnostic class for recording keyboard shortcuts.\n *\n * This class handles all the complexity of capturing keyboard events,\n * converting them to hotkey strings, and handling edge cases like\n * Escape to cancel or Backspace/Delete to clear.\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - State can be accessed via `recorder.store.state` when using the class directly\n * - When using framework adapters (React), use `useStore` hooks for reactive state\n *\n * @example\n * ```ts\n * const recorder = new HotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     console.log('Recorded:', hotkey)\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n *\n * // Start recording\n * recorder.start()\n *\n * // Access state directly\n * console.log(recorder.store.state.isRecording) // true\n *\n * // Subscribe to changes with TanStack Store\n * const unsubscribe = recorder.store.subscribe(() => {\n *   console.log('Recording:', recorder.store.state.isRecording)\n * })\n *\n * // Cleanup\n * recorder.destroy()\n * unsubscribe()\n * ```\n */\nexport class HotkeyRecorder {\n  /**\n   * The TanStack Store instance containing the recorder state.\n   * Use this to subscribe to state changes or access current state.\n   */\n  readonly store: Store<HotkeyRecorderState> = new Store<HotkeyRecorderState>({\n    isRecording: false,\n    recordedHotkey: null,\n  })\n\n  #keydownHandler: ((event: KeyboardEvent) => void) | null = null\n  #options: HotkeyRecorderOptions\n  #platform: 'mac' | 'windows' | 'linux'\n\n  constructor(options: HotkeyRecorderOptions) {\n    this.#options = options\n    this.#platform = detectPlatform()\n  }\n\n  /**\n   * Updates the recorder options, including callbacks.\n   * This allows framework adapters to sync callback changes without recreating the recorder.\n   */\n  setOptions(options: Partial<HotkeyRecorderOptions>): void {\n    this.#options = {\n      ...this.#options,\n      ...options,\n    }\n  }\n\n  /**\n   * Start recording a new hotkey.\n   *\n   * Sets up a keydown event listener that captures keyboard events\n   * and converts them to hotkey strings. Recording continues until\n   * a valid hotkey is recorded, Escape is pressed, or stop/cancel is called.\n   */\n  start(): void {\n    // Prevent starting recording if already recording\n    if (this.#keydownHandler) {\n      return\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: true,\n      recordedHotkey: null,\n    }))\n\n    // Create keydown handler\n    const handler = (event: KeyboardEvent) => {\n      // Check if we're still recording (handler might be called after stop/cancel)\n      if (!this.#keydownHandler) {\n        return\n      }\n\n      event.preventDefault()\n      event.stopPropagation()\n\n      // Handle Escape to cancel\n      if (event.key === 'Escape') {\n        this.cancel()\n        return\n      }\n\n      // Handle Backspace/Delete to clear shortcut\n      if (event.key === 'Backspace' || event.key === 'Delete') {\n        if (\n          !event.ctrlKey &&\n          !event.shiftKey &&\n          !event.altKey &&\n          !event.metaKey\n        ) {\n          this.#options.onClear?.()\n          this.#options.onRecord('' as Hotkey)\n          this.stop()\n          return\n        }\n      }\n\n      const finalHotkey = hotkeyChordFromKeydown(event, this.#platform)\n      if (finalHotkey === null) {\n        return\n      }\n\n      // Remove listener FIRST to prevent any additional events\n      const handlerToRemove = this.#keydownHandler as\n        | ((event: KeyboardEvent) => void)\n        | null\n      if (handlerToRemove) {\n        this.#removeListener(handlerToRemove)\n        this.#keydownHandler = null\n      }\n\n      // Update store state immediately\n      this.store.setState(() => ({\n        isRecording: false,\n        recordedHotkey: finalHotkey,\n      }))\n\n      // Call callback AFTER listener is removed and state is set\n      this.#options.onRecord(finalHotkey)\n    }\n\n    this.#keydownHandler = handler\n    this.#addListener(handler)\n  }\n\n  /**\n   * Stop recording (same as cancel, but doesn't call onCancel).\n   *\n   * Removes the event listener and resets the recording state.\n   */\n  stop(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n\n  /**\n   * Cancel recording without saving.\n   *\n   * Removes the event listener, resets the recording state, and calls\n   * the onCancel callback if provided.\n   */\n  cancel(): void {\n    // Remove event listener immediately\n    if (this.#keydownHandler) {\n      this.#removeListener(this.#keydownHandler)\n      this.#keydownHandler = null\n    }\n\n    // Update store state\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n\n    // Call cancel callback\n    this.#options.onCancel?.()\n  }\n\n  /**\n   * Adds the keydown event listener to the document.\n   */\n  #addListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return // SSR safety\n    }\n\n    document.addEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Removes the keydown event listener from the document.\n   */\n  #removeListener(handler: (event: KeyboardEvent) => void): void {\n    if (typeof document === 'undefined') {\n      return\n    }\n\n    document.removeEventListener('keydown', handler, true)\n  }\n\n  /**\n   * Clean up event listeners and reset state.\n   *\n   * Call this when you're done with the recorder to ensure\n   * all event listeners are properly removed.\n   */\n  destroy(): void {\n    this.stop()\n    this.store.setState(() => ({\n      isRecording: false,\n      recordedHotkey: null,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,IAAa,iBAAb,MAA4B;CAU1B,kBAA2D;CAC3D;CACA;CAEA,YAAY,SAAgC;eATC,IAAI,MAA2B;GAC1E,aAAa;GACb,gBAAgB;GACjB,CAAC;AAOA,QAAKA,UAAW;AAChB,QAAKC,WAAY,gBAAgB;;;;;;CAOnC,WAAW,SAA+C;AACxD,QAAKD,UAAW;GACd,GAAG,MAAKA;GACR,GAAG;GACJ;;;;;;;;;CAUH,QAAc;AAEZ,MAAI,MAAKE,eACP;AAIF,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;EAGH,MAAM,WAAW,UAAyB;AAExC,OAAI,CAAC,MAAKA,eACR;AAGF,SAAM,gBAAgB;AACtB,SAAM,iBAAiB;AAGvB,OAAI,MAAM,QAAQ,UAAU;AAC1B,SAAK,QAAQ;AACb;;AAIF,OAAI,MAAM,QAAQ,eAAe,MAAM,QAAQ,UAC7C;QACE,CAAC,MAAM,WACP,CAAC,MAAM,YACP,CAAC,MAAM,UACP,CAAC,MAAM,SACP;AACA,WAAKF,QAAS,WAAW;AACzB,WAAKA,QAAS,SAAS,GAAa;AACpC,UAAK,MAAM;AACX;;;GAIJ,MAAM,cAAc,uBAAuB,OAAO,MAAKC,SAAU;AACjE,OAAI,gBAAgB,KAClB;GAIF,MAAM,kBAAkB,MAAKC;AAG7B,OAAI,iBAAiB;AACnB,UAAKC,eAAgB,gBAAgB;AACrC,UAAKD,iBAAkB;;AAIzB,QAAK,MAAM,gBAAgB;IACzB,aAAa;IACb,gBAAgB;IACjB,EAAE;AAGH,SAAKF,QAAS,SAAS,YAAY;;AAGrC,QAAKE,iBAAkB;AACvB,QAAKE,YAAa,QAAQ;;;;;;;CAQ5B,OAAa;AAEX,MAAI,MAAKF,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;;;;;;;;CASL,SAAe;AAEb,MAAI,MAAKA,gBAAiB;AACxB,SAAKC,eAAgB,MAAKD,eAAgB;AAC1C,SAAKA,iBAAkB;;AAIzB,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE;AAGH,QAAKF,QAAS,YAAY;;;;;CAM5B,aAAa,SAA+C;AAC1D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,iBAAiB,WAAW,SAAS,KAAK;;;;;CAMrD,gBAAgB,SAA+C;AAC7D,MAAI,OAAO,aAAa,YACtB;AAGF,WAAS,oBAAoB,WAAW,SAAS,KAAK;;;;;;;;CASxD,UAAgB;AACd,OAAK,MAAM;AACX,OAAK,MAAM,gBAAgB;GACzB,aAAa;GACb,gBAAgB;GACjB,EAAE"}

package/dist/hotkey-sequence-recorder.cjs

@@ -0,0 +1,188 @@
+const require_constants = require('./constants.cjs');
+const require_recorder_chord = require('./recorder-chord.cjs');
+let _tanstack_store = require("@tanstack/store");
+
+//#region src/hotkey-sequence-recorder.ts
+const defaultHotkeySequenceRecorderOptions = {
+	commitOnEnter: true,
+	commitKeys: "enter"
+};
+function resolvedCommitOnEnter(options) {
+	if (options.commitKeys === "none") return false;
+	return options.commitOnEnter !== false;
+}
+/**
+* Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).
+*
+* Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit
+* when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,
+* **Backspace/Delete** to remove the last step or clear when empty.
+*/
+var HotkeySequenceRecorder = class {
+	#keydownHandler = null;
+	#options;
+	#platform;
+	#idleTimer = null;
+	constructor(options) {
+		this.store = new _tanstack_store.Store({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		});
+		this.#options = {
+			...defaultHotkeySequenceRecorderOptions,
+			...options
+		};
+		this.#platform = require_constants.detectPlatform();
+	}
+	setOptions(options) {
+		this.#options = {
+			...defaultHotkeySequenceRecorderOptions,
+			...this.#options,
+			...options
+		};
+	}
+	#clearIdleTimer() {
+		if (this.#idleTimer !== null) {
+			clearTimeout(this.#idleTimer);
+			this.#idleTimer = null;
+		}
+	}
+	#scheduleIdleTimer() {
+		this.#clearIdleTimer();
+		const ms = this.#options.idleTimeoutMs;
+		if (ms === void 0 || ms <= 0) return;
+		if (this.store.state.steps.length === 0) return;
+		this.#idleTimer = setTimeout(() => {
+			this.#idleTimer = null;
+			if (!this.#keydownHandler) return;
+			if (this.store.state.steps.length >= 1) this.commit();
+		}, ms);
+	}
+	#patchSteps(updater) {
+		this.store.setState((s) => ({
+			...s,
+			steps: updater(s.steps)
+		}));
+	}
+	start() {
+		if (this.#keydownHandler) return;
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: true,
+			steps: [],
+			recordedSequence: null
+		}));
+		const handler = (event) => {
+			if (!this.#keydownHandler) return;
+			event.preventDefault();
+			event.stopPropagation();
+			if (event.key === "Escape") {
+				this.cancel();
+				return;
+			}
+			if (event.key === "Backspace" || event.key === "Delete") {
+				if (!event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey) {
+					if (this.store.state.steps.length === 0) {
+						this.#options.onClear?.();
+						this.#options.onRecord([]);
+						this.#finishWithoutCommitCallback();
+						return;
+					}
+					this.#patchSteps((prev) => prev.slice(0, -1));
+					if (this.store.state.steps.length === 0) this.#clearIdleTimer();
+					else this.#scheduleIdleTimer();
+					return;
+				}
+			}
+			const enterCommits = resolvedCommitOnEnter(this.#options) && event.key === "Enter" && !event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey;
+			if (enterCommits && this.store.state.steps.length >= 1) {
+				this.commit();
+				return;
+			}
+			if (enterCommits && this.store.state.steps.length === 0) return;
+			const finalHotkey = require_recorder_chord.hotkeyChordFromKeydown(event, this.#platform);
+			if (finalHotkey === null) return;
+			this.#patchSteps((prev) => [...prev, finalHotkey]);
+			this.#scheduleIdleTimer();
+		};
+		this.#keydownHandler = handler;
+		this.#addListener(handler);
+	}
+	/**
+	* Commit the current steps as a sequence. No-op if fewer than one step.
+	*/
+	commit() {
+		const steps = this.store.state.steps;
+		if (steps.length < 1) return;
+		const sequence = [...steps];
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: sequence
+		}));
+		this.#options.onRecord(sequence);
+	}
+	#finishWithoutCommitCallback() {
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		}));
+	}
+	stop() {
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		}));
+	}
+	cancel() {
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		}));
+		this.#options.onCancel?.();
+	}
+	#addListener(handler) {
+		if (typeof document === "undefined") return;
+		document.addEventListener("keydown", handler, true);
+	}
+	#removeListener(handler) {
+		if (typeof document === "undefined") return;
+		document.removeEventListener("keydown", handler, true);
+	}
+	destroy() {
+		this.stop();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		}));
+	}
+};
+
+//#endregion
+exports.HotkeySequenceRecorder = HotkeySequenceRecorder;
+//# sourceMappingURL=hotkey-sequence-recorder.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hotkey-sequence-recorder.cjs","names":["Store","#options","#platform","detectPlatform","#idleTimer","#clearIdleTimer","#keydownHandler","#finishWithoutCommitCallback","#patchSteps","#scheduleIdleTimer","hotkeyChordFromKeydown","#addListener","#removeListener"],"sources":["../src/hotkey-sequence-recorder.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { detectPlatform } from './constants'\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\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      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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"}

package/dist/hotkey-sequence-recorder.d.cts

@@ -0,0 +1,71 @@
+import { HotkeySequence } from "./sequence-manager.cjs";
+import { Store } from "@tanstack/store";
+
+//#region src/hotkey-sequence-recorder.d.ts
+/**
+ * How the user can commit a recorded sequence from the keyboard.
+ * - `'enter'`: plain Enter (no modifiers) commits when at least one step exists.
+ * - `'none'`: only {@link HotkeySequenceRecorder.commit} finishes recording (or idle timeout if set).
+ */
+type HotkeySequenceRecorderCommitKeys = 'enter' | 'none';
+/**
+ * State interface for the HotkeySequenceRecorder.
+ */
+interface HotkeySequenceRecorderState {
+  /** Whether recording is currently active */
+  isRecording: boolean;
+  /** Chords captured so far in the current recording session */
+  steps: HotkeySequence;
+  /** The last successfully committed sequence, or null if none / after starting a new session */
+  recordedSequence: HotkeySequence | null;
+}
+/**
+ * Options for configuring a HotkeySequenceRecorder instance.
+ */
+interface HotkeySequenceRecorderOptions {
+  /** Callback when a sequence is successfully recorded (including empty array when cleared) */
+  onRecord: (sequence: HotkeySequence) => void;
+  /** Optional callback when recording is cancelled (Escape pressed) */
+  onCancel?: () => void;
+  /** Optional callback when the sequence is cleared (Backspace/Delete with no steps) */
+  onClear?: () => void;
+  /**
+   * Whether plain Enter commits the current steps. Ignored when {@link commitKeys} is `'none'`.
+   * @default true
+   */
+  commitOnEnter?: boolean;
+  /**
+   * Keyboard commit mode. When `'none'`, use {@link HotkeySequenceRecorder.commit} (and optional idle timeout).
+   * @default 'enter'
+   */
+  commitKeys?: HotkeySequenceRecorderCommitKeys;
+  /**
+   * Milliseconds of inactivity after the **last completed chord** before auto-committing.
+   * The timer does not run while waiting for the first chord (`steps.length === 0`).
+   */
+  idleTimeoutMs?: number;
+}
+/**
+ * Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).
+ *
+ * Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit
+ * when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,
+ * **Backspace/Delete** to remove the last step or clear when empty.
+ */
+declare class HotkeySequenceRecorder {
+  #private;
+  readonly store: Store<HotkeySequenceRecorderState>;
+  constructor(options: HotkeySequenceRecorderOptions);
+  setOptions(options: Partial<HotkeySequenceRecorderOptions>): void;
+  start(): void;
+  /**
+   * Commit the current steps as a sequence. No-op if fewer than one step.
+   */
+  commit(): void;
+  stop(): void;
+  cancel(): void;
+  destroy(): void;
+}
+//#endregion
+export { HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState };
+//# sourceMappingURL=hotkey-sequence-recorder.d.cts.map

package/dist/hotkey-sequence-recorder.d.ts

@@ -0,0 +1,71 @@
+import { HotkeySequence } from "./sequence-manager.js";
+import { Store } from "@tanstack/store";
+
+//#region src/hotkey-sequence-recorder.d.ts
+/**
+ * How the user can commit a recorded sequence from the keyboard.
+ * - `'enter'`: plain Enter (no modifiers) commits when at least one step exists.
+ * - `'none'`: only {@link HotkeySequenceRecorder.commit} finishes recording (or idle timeout if set).
+ */
+type HotkeySequenceRecorderCommitKeys = 'enter' | 'none';
+/**
+ * State interface for the HotkeySequenceRecorder.
+ */
+interface HotkeySequenceRecorderState {
+  /** Whether recording is currently active */
+  isRecording: boolean;
+  /** Chords captured so far in the current recording session */
+  steps: HotkeySequence;
+  /** The last successfully committed sequence, or null if none / after starting a new session */
+  recordedSequence: HotkeySequence | null;
+}
+/**
+ * Options for configuring a HotkeySequenceRecorder instance.
+ */
+interface HotkeySequenceRecorderOptions {
+  /** Callback when a sequence is successfully recorded (including empty array when cleared) */
+  onRecord: (sequence: HotkeySequence) => void;
+  /** Optional callback when recording is cancelled (Escape pressed) */
+  onCancel?: () => void;
+  /** Optional callback when the sequence is cleared (Backspace/Delete with no steps) */
+  onClear?: () => void;
+  /**
+   * Whether plain Enter commits the current steps. Ignored when {@link commitKeys} is `'none'`.
+   * @default true
+   */
+  commitOnEnter?: boolean;
+  /**
+   * Keyboard commit mode. When `'none'`, use {@link HotkeySequenceRecorder.commit} (and optional idle timeout).
+   * @default 'enter'
+   */
+  commitKeys?: HotkeySequenceRecorderCommitKeys;
+  /**
+   * Milliseconds of inactivity after the **last completed chord** before auto-committing.
+   * The timer does not run while waiting for the first chord (`steps.length === 0`).
+   */
+  idleTimeoutMs?: number;
+}
+/**
+ * Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).
+ *
+ * Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit
+ * when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,
+ * **Backspace/Delete** to remove the last step or clear when empty.
+ */
+declare class HotkeySequenceRecorder {
+  #private;
+  readonly store: Store<HotkeySequenceRecorderState>;
+  constructor(options: HotkeySequenceRecorderOptions);
+  setOptions(options: Partial<HotkeySequenceRecorderOptions>): void;
+  start(): void;
+  /**
+   * Commit the current steps as a sequence. No-op if fewer than one step.
+   */
+  commit(): void;
+  stop(): void;
+  cancel(): void;
+  destroy(): void;
+}
+//#endregion
+export { HotkeySequenceRecorder, HotkeySequenceRecorderCommitKeys, HotkeySequenceRecorderOptions, HotkeySequenceRecorderState };
+//# sourceMappingURL=hotkey-sequence-recorder.d.ts.map

package/dist/hotkey-sequence-recorder.js

@@ -0,0 +1,188 @@
+import { detectPlatform } from "./constants.js";
+import { hotkeyChordFromKeydown } from "./recorder-chord.js";
+import { Store } from "@tanstack/store";
+
+//#region src/hotkey-sequence-recorder.ts
+const defaultHotkeySequenceRecorderOptions = {
+	commitOnEnter: true,
+	commitKeys: "enter"
+};
+function resolvedCommitOnEnter(options) {
+	if (options.commitKeys === "none") return false;
+	return options.commitOnEnter !== false;
+}
+/**
+* Framework-agnostic class for recording multi-chord sequences (Vim-style shortcuts).
+*
+* Each step is captured like a single hotkey chord. Press **Enter** (no modifiers) to commit
+* when {@link HotkeySequenceRecorderOptions.commitKeys} is `'enter'` (default), **Escape** to cancel,
+* **Backspace/Delete** to remove the last step or clear when empty.
+*/
+var HotkeySequenceRecorder = class {
+	#keydownHandler = null;
+	#options;
+	#platform;
+	#idleTimer = null;
+	constructor(options) {
+		this.store = new Store({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		});
+		this.#options = {
+			...defaultHotkeySequenceRecorderOptions,
+			...options
+		};
+		this.#platform = detectPlatform();
+	}
+	setOptions(options) {
+		this.#options = {
+			...defaultHotkeySequenceRecorderOptions,
+			...this.#options,
+			...options
+		};
+	}
+	#clearIdleTimer() {
+		if (this.#idleTimer !== null) {
+			clearTimeout(this.#idleTimer);
+			this.#idleTimer = null;
+		}
+	}
+	#scheduleIdleTimer() {
+		this.#clearIdleTimer();
+		const ms = this.#options.idleTimeoutMs;
+		if (ms === void 0 || ms <= 0) return;
+		if (this.store.state.steps.length === 0) return;
+		this.#idleTimer = setTimeout(() => {
+			this.#idleTimer = null;
+			if (!this.#keydownHandler) return;
+			if (this.store.state.steps.length >= 1) this.commit();
+		}, ms);
+	}
+	#patchSteps(updater) {
+		this.store.setState((s) => ({
+			...s,
+			steps: updater(s.steps)
+		}));
+	}
+	start() {
+		if (this.#keydownHandler) return;
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: true,
+			steps: [],
+			recordedSequence: null
+		}));
+		const handler = (event) => {
+			if (!this.#keydownHandler) return;
+			event.preventDefault();
+			event.stopPropagation();
+			if (event.key === "Escape") {
+				this.cancel();
+				return;
+			}
+			if (event.key === "Backspace" || event.key === "Delete") {
+				if (!event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey) {
+					if (this.store.state.steps.length === 0) {
+						this.#options.onClear?.();
+						this.#options.onRecord([]);
+						this.#finishWithoutCommitCallback();
+						return;
+					}
+					this.#patchSteps((prev) => prev.slice(0, -1));
+					if (this.store.state.steps.length === 0) this.#clearIdleTimer();
+					else this.#scheduleIdleTimer();
+					return;
+				}
+			}
+			const enterCommits = resolvedCommitOnEnter(this.#options) && event.key === "Enter" && !event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey;
+			if (enterCommits && this.store.state.steps.length >= 1) {
+				this.commit();
+				return;
+			}
+			if (enterCommits && this.store.state.steps.length === 0) return;
+			const finalHotkey = hotkeyChordFromKeydown(event, this.#platform);
+			if (finalHotkey === null) return;
+			this.#patchSteps((prev) => [...prev, finalHotkey]);
+			this.#scheduleIdleTimer();
+		};
+		this.#keydownHandler = handler;
+		this.#addListener(handler);
+	}
+	/**
+	* Commit the current steps as a sequence. No-op if fewer than one step.
+	*/
+	commit() {
+		const steps = this.store.state.steps;
+		if (steps.length < 1) return;
+		const sequence = [...steps];
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: sequence
+		}));
+		this.#options.onRecord(sequence);
+	}
+	#finishWithoutCommitCallback() {
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		}));
+	}
+	stop() {
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		}));
+	}
+	cancel() {
+		if (this.#keydownHandler) {
+			this.#removeListener(this.#keydownHandler);
+			this.#keydownHandler = null;
+		}
+		this.#clearIdleTimer();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		}));
+		this.#options.onCancel?.();
+	}
+	#addListener(handler) {
+		if (typeof document === "undefined") return;
+		document.addEventListener("keydown", handler, true);
+	}
+	#removeListener(handler) {
+		if (typeof document === "undefined") return;
+		document.removeEventListener("keydown", handler, true);
+	}
+	destroy() {
+		this.stop();
+		this.store.setState(() => ({
+			isRecording: false,
+			steps: [],
+			recordedSequence: null
+		}));
+	}
+};
+
+//#endregion
+export { HotkeySequenceRecorder };
+//# sourceMappingURL=hotkey-sequence-recorder.js.map

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

@@ -0,0 +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 { 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\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      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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"}

package/dist/hotkey.d.cts

@@ -237,6 +237,8 @@ type RegisterableHotkey = Hotkey | RawHotkey;
 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;
 }
 /**
  * Result of validating a hotkey string.