@tanstack/hotkeys 0.8.0 → 0.10.0

package/dist/match.js

@@ -1,11 +1,14 @@
-import { PUNCTUATION_CODE_MAP, detectPlatform, isSingleLetterKey, normalizeKeyName } from "./constants.js";
-import { parseHotkey } from "./parse.js";
+import { detectPlatform } from "./platform.js";
+import { keysEqual } from "./_keyboard-event.js";
+import { parseHotkey, parseRegisterableHotkey } from "./parse.js";
+import { matchKeyboardEvent } from "./_match.js";
 
 //#region src/match.ts
 /**
 * Checks if a KeyboardEvent matches a hotkey.
 *
-* Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
+* Physical bindings such as `Mod+[KeyS]` match `event.code` exactly.
+* Logical bindings use `event.key`, with a fallback to `code`
 * for letter keys, digit keys (0-9), and punctuation keys when `key` produces special
 * characters (e.g., macOS Option+letter, Shift+number, or Option+punctuation).
 * Letter keys are matched case-insensitively.
@@ -31,30 +34,7 @@ import { parseHotkey } from "./parse.js";
 * ```
 */
 function matchesKeyboardEvent(event, hotkey, platform = detectPlatform()) {
-	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
-	if (event.ctrlKey !== parsed.ctrl) return false;
-	if (event.shiftKey !== parsed.shift) return false;
-	if (event.altKey !== parsed.alt) return false;
-	if (event.metaKey !== parsed.meta) return false;
-	const eventKey = normalizeKeyName(event.key);
-	const hotkeyKey = parsed.key;
-	if (eventKey !== "Dead" && eventKey.length === 1 && hotkeyKey.length === 1) {
-		if (eventKey.toUpperCase() === hotkeyKey.toUpperCase()) return true;
-		if (isSingleLetterKey(eventKey) && (/^[A-Za-z]$/.test(eventKey) || !event.altKey)) return false;
-	}
-	if (event.code && (eventKey === "Dead" || eventKey.length === 1 && hotkeyKey.length === 1)) {
-		if (event.code.startsWith("Key")) {
-			const codeLetter = event.code.slice(3);
-			if (codeLetter.length === 1 && /^[A-Za-z]$/.test(codeLetter)) return codeLetter.toUpperCase() === hotkeyKey.toUpperCase();
-		}
-		if (event.code.startsWith("Digit")) {
-			const codeDigit = event.code.slice(5);
-			if (codeDigit.length === 1 && /^[0-9]$/.test(codeDigit)) return codeDigit === hotkeyKey;
-		}
-		if (event.code in PUNCTUATION_CODE_MAP) return PUNCTUATION_CODE_MAP[event.code] === hotkeyKey;
-		return false;
-	}
-	return eventKey === hotkeyKey;
+	return matchKeyboardEvent(event, hotkey, platform).matched;
 }
 /**
 * Creates a keyboard event handler that calls the callback when the hotkey matches.
@@ -142,10 +122,19 @@ function formatParsedHotkey(parsed) {
 	if (parsed.alt) parts.push("Alt");
 	if (parsed.shift) parts.push("Shift");
 	if (parsed.meta) parts.push("Meta");
-	parts.push(parsed.key);
+	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : parsed.key);
 	return parts.join("+");
 }
+/**
+* Compares normalized binding identity, including all four modifiers.
+* Aliases resolve on the supplied platform. A physical code and a logical key
+* remain distinct even when one keyboard event could match both.
+*/
+function areHotkeysEqual(left, right, platform = detectPlatform()) {
+	const a = parseRegisterableHotkey(left, platform);
+	const b = parseRegisterableHotkey(right, platform);
+	return a.ctrl === b.ctrl && a.alt === b.alt && a.shift === b.shift && a.meta === b.meta && (a.code !== void 0 || b.code !== void 0 ? a.code === b.code : keysEqual(a.key, b.key));
+}
 
 //#endregion
-export { createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };
-//# sourceMappingURL=match.js.map
+export { areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent };

package/dist/parse.d.ts

@@ -1,13 +1,13 @@
-import { Hotkey, Key, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.js";
+import { Key } from "./key.types.js";
 import { MODIFIER_ALIASES } from "./constants.js";
-
+import { Hotkey, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.types.js";
 //#region src/parse.d.ts
 /**
  * Parses a hotkey string into its component parts.
  *
  * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
  * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
- * @returns A ParsedHotkey object with the key and modifier flags
+ * @returns A ParsedHotkey with either logical key or physical code and modifier flags
  *
  * @example
  * ```ts
@@ -16,7 +16,7 @@ import { MODIFIER_ALIASES } from "./constants.js";
  * parseHotkey('Control+Shift+A') // { key: 'A', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
  * ```
  */
-declare function parseHotkey(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+export declare function parseHotkey(hotkey: Hotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
 /**
  * Converts a RawHotkey object to a ParsedHotkey.
  * Optional modifier booleans default to false; modifiers array is derived from them.
@@ -38,7 +38,7 @@ declare function parseHotkey(hotkey: Hotkey | (string & {}), platform?: 'mac' |
  * // { key: 'S', ctrl: true, shift: true, alt: false, meta: false, modifiers: ['Control', 'Shift'] }
  * ```
  */
-declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
+export declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
 /**
  * Normalizes a hotkey string to its canonical form.
  *
@@ -59,16 +59,16 @@ declare function rawHotkeyToParsedHotkey(raw: RawHotkey, platform?: 'mac' | 'win
  * normalizeHotkey('esc') // 'Escape'
  * ```
  */
-declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+export declare function normalizeHotkey(hotkey: Key | (string & {}), platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
  * Same canonical string as {@link normalizeHotkey}, but from an already-parsed hotkey.
  */
-declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+export declare function normalizeHotkeyFromParsed(parsed: ParsedHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
  * Normalizes a string or {@link RawHotkey} object to the same canonical hotkey string.
  * Use this in framework adapters instead of branching on `formatHotkey(rawHotkeyToParsedHotkey(...))`.
  */
-declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+export declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
  * Checks if a string is a recognized modifier token (including aliases).
  *
@@ -78,7 +78,7 @@ declare function normalizeRegisterableHotkey(hotkey: RegisterableHotkey, platfor
  * @param key - Key name or alias (e.g. from a hotkey string or `event.key`)
  * @returns True if the string is a recognized modifier
  */
-declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MODIFIER_ALIASES;
+export declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MODIFIER_ALIASES;
 /**
  * Parses a KeyboardEvent into a ParsedHotkey object.
  *
@@ -97,14 +97,14 @@ declare function isModifierKey(key: Key | (string & {})): key is keyof typeof MO
  * })
  * ```
  */
-declare function parseKeyboardEvent(event: KeyboardEvent): ParsedHotkey;
+export declare function parseKeyboardEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): ParsedHotkey;
 /**
  * Normalizes a keyboard event to the same canonical hotkey string as {@link normalizeHotkey}.
  *
  * @param event - The keyboard event (typically `keydown`)
  * @param platform - Target platform for `Mod` eligibility
  */
-declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
+export declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac' | 'windows' | 'linux'): Hotkey;
 /**
  * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
  *
@@ -122,7 +122,10 @@ declare function normalizeHotkeyFromEvent(event: KeyboardEvent, platform?: 'mac'
  * hasNonModifierKey(parseHotkey('Mod+A')) // true
  * ```
  */
-declare function hasNonModifierKey(hotkey: Hotkey | ParsedHotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): boolean;
-//#endregion
-export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
-//# sourceMappingURL=parse.d.ts.map
+export declare function hasNonModifierKey(hotkey: Hotkey | ParsedHotkey | (string & {}), platform?: 'mac' | 'windows' | 'linux'): boolean;
+/**
+ * Parses a string or raw binding, resolving Mod for the supplied platform.
+ * Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
+ */
+export declare function parseRegisterableHotkey(hotkey: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): ParsedHotkey;
+//#endregion

package/dist/parse.js

@@ -1,4 +1,6 @@
-import { MODIFIER_ALIASES, MODIFIER_ORDER, detectPlatform, normalizeKeyName, resolveModifier } from "./constants.js";
+import { MODIFIER_ALIASES, MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
+import { detectPlatform, resolveModifier } from "./platform.js";
+import { assertLogicalKey, normalizeKeyboardEvent, splitHotkeyParts } from "./_keyboard-event.js";
 
 //#region src/parse.ts
 /**
@@ -6,7 +8,7 @@ import { MODIFIER_ALIASES, MODIFIER_ORDER, detectPlatform, normalizeKeyName, res
 *
 * @param hotkey - The hotkey string to parse (e.g., 'Mod+Shift+S')
 * @param platform - The target platform for resolving 'Mod' (defaults to auto-detection)
-* @returns A ParsedHotkey object with the key and modifier flags
+* @returns A ParsedHotkey with either logical key or physical code and modifier flags
 *
 * @example
 * ```ts
@@ -16,7 +18,7 @@ import { MODIFIER_ALIASES, MODIFIER_ORDER, detectPlatform, normalizeKeyName, res
 * ```
 */
 function parseHotkey(hotkey, platform = detectPlatform()) {
-	const parts = hotkey.split("+");
+	const parts = splitHotkeyParts(hotkey);
 	const modifiers = /* @__PURE__ */ new Set();
 	let key = "";
 	for (let i = 0; i < parts.length; i++) {
@@ -31,8 +33,9 @@ function parseHotkey(hotkey, platform = detectPlatform()) {
 		}
 	}
 	if (!key && parts.length > 0) key = normalizeKeyName(parts[parts.length - 1].trim());
+	const code = /^\[([A-Za-z][A-Za-z0-9]*)\]$/.exec(key)?.[1];
 	return {
-		key,
+		...code !== void 0 ? { code } : { key },
 		ctrl: modifiers.has("Control"),
 		shift: modifiers.has("Shift"),
 		alt: modifiers.has("Alt"),
@@ -62,12 +65,15 @@ function parseHotkey(hotkey, platform = detectPlatform()) {
 * ```
 */
 function rawHotkeyToParsedHotkey(raw, platform = detectPlatform()) {
+	if (raw.code === void 0) assertLogicalKey(raw.key);
 	let ctrl = raw.ctrl ?? false;
 	const shift = raw.shift ?? false;
 	const alt = raw.alt ?? false;
 	let meta = raw.meta ?? false;
-	if (raw.mod) if (resolveModifier("Mod", platform) === "Control") ctrl = true;
-	else meta = true;
+	if (raw.mod) {
+		if (resolveModifier("Mod", platform) === "Control") ctrl = true;
+		else meta = true;
+	}
 	const modifiers = MODIFIER_ORDER.filter((m) => {
 		switch (m) {
 			case "Control": return ctrl;
@@ -78,7 +84,7 @@ function rawHotkeyToParsedHotkey(raw, platform = detectPlatform()) {
 		}
 	});
 	return {
-		key: raw.key,
+		...raw.code !== void 0 ? { code: raw.code } : { key: normalizeKeyName(raw.key) },
 		ctrl,
 		shift,
 		alt,
@@ -92,6 +98,7 @@ function rawHotkeyToParsedHotkey(raw, platform = detectPlatform()) {
 * otherwise full `Control+Alt+Shift+Meta` order.
 */
 function normalizedHotkeyStringFromParsed(parsed, platform) {
+	if (parsed.code === void 0) assertLogicalKey(parsed.key);
 	const canUseMod = platform === "mac" ? parsed.meta && !parsed.ctrl : parsed.ctrl && !parsed.meta;
 	const parts = [];
 	if (canUseMod) {
@@ -99,7 +106,7 @@ function normalizedHotkeyStringFromParsed(parsed, platform) {
 		if (parsed.alt) parts.push("Alt");
 		if (parsed.shift) parts.push("Shift");
 	} else for (const modifier of MODIFIER_ORDER) if (parsed.modifiers.includes(modifier)) parts.push(modifier);
-	parts.push(normalizeKeyName(parsed.key));
+	parts.push(parsed.code !== void 0 ? `[${parsed.code}]` : normalizeKeyName(parsed.key));
 	return parts.join("+");
 }
 /**
@@ -168,19 +175,22 @@ function isModifierKey(key) {
 * })
 * ```
 */
-function parseKeyboardEvent(event) {
-	const normalizedKey = normalizeKeyName(event.key);
+function parseKeyboardEvent(event, platform) {
+	const normalized = normalizeKeyboardEvent(event, platform);
+	const ctrl = normalized.altGraph ? false : normalized.ctrl;
+	const alt = normalized.altGraph ? false : normalized.alt;
+	const shift = normalized.shift;
 	const modifiers = [];
-	if (event.ctrlKey) modifiers.push("Control");
-	if (event.altKey) modifiers.push("Alt");
-	if (event.shiftKey) modifiers.push("Shift");
-	if (event.metaKey) modifiers.push("Meta");
+	if (ctrl) modifiers.push("Control");
+	if (alt) modifiers.push("Alt");
+	if (shift) modifiers.push("Shift");
+	if (normalized.meta) modifiers.push("Meta");
 	return {
-		key: normalizedKey,
-		ctrl: event.ctrlKey,
-		shift: event.shiftKey,
-		alt: event.altKey,
-		meta: event.metaKey,
+		key: normalized.key,
+		ctrl,
+		shift,
+		alt,
+		meta: normalized.meta,
 		modifiers
 	};
 }
@@ -191,7 +201,7 @@ function parseKeyboardEvent(event) {
 * @param platform - Target platform for `Mod` eligibility
 */
 function normalizeHotkeyFromEvent(event, platform = detectPlatform()) {
-	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event), platform);
+	return normalizedHotkeyStringFromParsed(parseKeyboardEvent(event, platform), platform);
 }
 /**
 * Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
@@ -212,9 +222,16 @@ function normalizeHotkeyFromEvent(event, platform = detectPlatform()) {
 */
 function hasNonModifierKey(hotkey, platform = detectPlatform()) {
 	const parsed = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : hotkey;
+	if (parsed.code !== void 0) return parsed.code.length > 0 && !/^(Control|Shift|Alt|Meta)(Left|Right)$/.test(parsed.code);
 	return !isModifierKey(parsed.key) && parsed.key.length > 0;
 }
+/**
+* Parses a string or raw binding, resolving Mod for the supplied platform.
+* Physical tokens such as `[KeyQ]` retain `code`; they never become logical Q.
+*/
+function parseRegisterableHotkey(hotkey, platform = detectPlatform()) {
+	return typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
+}
 
 //#endregion
-export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, rawHotkeyToParsedHotkey };
-//# sourceMappingURL=parse.js.map
+export { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey };

package/dist/platform.d.ts

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

package/dist/platform.js

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

package/dist/recorder-options.d.ts

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

package/dist/sequence-manager.d.ts

@@ -1,14 +1,13 @@
-import { Hotkey, HotkeyCallback } from "./hotkey.js";
+import { Hotkey, HotkeyCallback, ParsedHotkey } from "./hotkey.types.js";
 import { HotkeyOptions } from "./hotkey-manager.js";
 import { Store } from "@tanstack/store";
-
 //#region src/sequence-manager.d.ts
-type Target = HTMLElement | Document | Window;
+export type Target = HTMLElement | Document | Window;
 /**
  * Options for hotkey sequence matching.
  * Extends HotkeyOptions but excludes requireReset (not applicable to sequences).
  */
-interface SequenceOptions extends Omit<HotkeyOptions, 'requireReset'> {
+export interface SequenceOptions extends Omit<HotkeyOptions, 'requireReset'> {
   /** Timeout between keys in milliseconds. Default: 1000 */
   timeout?: number;
 }
@@ -18,7 +17,7 @@ interface SequenceOptions extends Omit<HotkeyOptions, 'requireReset'> {
  * Each element is one step (a `Hotkey` string). Steps may include modifiers;
  * the same modifier can appear on consecutive steps (e.g. `Shift+R` then
  * `Shift+T`). Modifier-only key events do not advance or reset matching—see
- * `SequenceManager`.
+ * `SequenceManager`. Automatic keydown repeats and IME composition are also ignored.
  *
  * @example
  * ```ts
@@ -28,17 +27,17 @@ interface SequenceOptions extends Omit<HotkeyOptions, 'requireReset'> {
  * const chainedShift: HotkeySequence = ['Shift+R', 'Shift+T']
  * ```
  */
-type HotkeySequence = Array<Hotkey>;
+export type HotkeySequence = Array<Hotkey>;
 /**
  * Default timeout between keys in a sequence (in milliseconds).
  * Exported for consumers that display sequence state (e.g. devtools).
  */
-declare const DEFAULT_SEQUENCE_TIMEOUT = 1000;
+export declare const DEFAULT_SEQUENCE_TIMEOUT = 1000;
 /**
  * View of a sequence registration for devtools display.
  * Progress fields reflect an in-progress match (between first key and completion or timeout).
  */
-interface SequenceRegistrationView {
+export interface SequenceRegistrationView {
   id: string;
   sequence: HotkeySequence;
   options: SequenceOptions;
@@ -51,6 +50,21 @@ interface SequenceRegistrationView {
   /** `Date.now()` when the last step in the current attempt matched; 0 if none. */
   partialMatchLastKeyTime: number;
 }
+/**
+ * Internal representation of a sequence registration.
+ */
+export interface SequenceRegistration {
+  id: string;
+  sequence: HotkeySequence;
+  parsedSequence: Array<ParsedHotkey>;
+  callback: HotkeyCallback;
+  options: SequenceOptions;
+  target: Target;
+  currentIndex: number;
+  lastKeyTime: number;
+  triggerCount: number;
+  hasFired: boolean;
+}
 /**
  * A handle returned from SequenceManager.register() that allows updating
  * the callback and options without re-registering the sequence.
@@ -64,14 +78,14 @@ interface SequenceRegistrationView {
  * handle.unregister()
  * ```
  */
-interface SequenceRegistrationHandle {
+export interface SequenceRegistrationHandle {
   readonly id: string;
   readonly isActive: boolean;
   callback: HotkeyCallback;
   setOptions: (options: Partial<SequenceOptions>) => void;
   unregister: () => void;
 }
-declare class SequenceManager {
+export declare class SequenceManager {
   #private;
   /**
    * The TanStack Store containing sequence registration views for devtools.
@@ -121,7 +135,7 @@ declare class SequenceManager {
  * Gets the singleton SequenceManager instance.
  * Convenience function for accessing the manager.
  */
-declare function getSequenceManager(): SequenceManager;
+export declare function getSequenceManager(): SequenceManager;
 /**
  * Creates a simple sequence matcher for one-off use.
  *
@@ -144,7 +158,7 @@ declare function getSequenceManager(): SequenceManager;
  * })
  * ```
  */
-declare function createSequenceMatcher(sequence: HotkeySequence, options?: {
+export declare function createSequenceMatcher(sequence: HotkeySequence, options?: {
   timeout?: number;
   platform?: 'mac' | 'windows' | 'linux';
 }): {
@@ -152,6 +166,4 @@ declare function createSequenceMatcher(sequence: HotkeySequence, options?: {
   reset: () => void;
   getProgress: () => number;
 };
-//#endregion
-export { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistrationHandle, SequenceRegistrationView, createSequenceMatcher, getSequenceManager };
-//# sourceMappingURL=sequence-manager.d.ts.map
+//#endregion