@tanstack/hotkeys 0.12.1 → 0.14.0

package/dist/_event-target.js

@@ -1,4 +1,21 @@
+import { normalizeKeyName } from "./constants.js";
+
 //#region src/_event-target.ts
+function isNode(target) {
+	return typeof target?.nodeType === "number";
+}
+function isElement(target) {
+	return isNode(target) && target.nodeType === 1;
+}
+function isWindow(target) {
+	return "document" in target;
+}
+/** Returns the document a listener target belongs to, in any frame. */
+function getTargetDocument(target) {
+	if (isWindow(target)) return target.document;
+	if (target.nodeType === 9) return target;
+	return target.ownerDocument;
+}
 /**
 * Checks if an element is an input-like element that should be ignored for hotkeys.
 *
@@ -12,15 +29,13 @@
 * Mod+S and Escape fire when the user has tabbed to a form button.
 */
 function isInputElement(element) {
-	if (!element) return false;
-	if (element instanceof HTMLInputElement) {
+	if (!isElement(element)) return false;
+	if (element.localName === "input") {
 		const type = element.type.toLowerCase();
-		if (type === "button" || type === "submit" || type === "reset") return false;
-		return true;
+		return type !== "button" && type !== "submit" && type !== "reset";
 	}
-	if (element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) return true;
-	if (element instanceof HTMLElement && element.isContentEditable) return true;
-	return false;
+	if (element.localName === "textarea" || element.localName === "select") return true;
+	return element.isContentEditable === true;
 }
 /**
 * Returns the focused element for the document associated with where hotkey
@@ -30,41 +45,150 @@ function isInputElement(element) {
 */
 function getActiveElementForListenerTarget(target) {
 	if (typeof document === "undefined") return null;
-	if (typeof Document !== "undefined" && target instanceof Document || typeof Node !== "undefined" && target.nodeType === Node.DOCUMENT_NODE) return target.activeElement;
-	if (typeof HTMLElement !== "undefined" && target instanceof HTMLElement) return target.ownerDocument.activeElement ?? null;
-	return target.document.activeElement ?? null;
+	return getTargetDocument(target).activeElement;
 }
+const VERTICAL = ["ArrowUp", "ArrowDown"];
+const HORIZONTAL = ["ArrowLeft", "ArrowRight"];
+const ARROWS = [...VERTICAL, ...HORIZONTAL];
+const EDGES = ["Home", "End"];
+const PAGES = ["PageUp", "PageDown"];
+const ACTIVATION = ["Enter", "Space"];
+const TYPEAHEAD = "typeahead";
 /**
-* Returns whether an event should be ignored because it originated from an
-* input-like element other than the registration target.
-*
-* This checks:
-* - the currently focused element for the listener target
-* - the event's composed path (for shadow DOM)
-* - the event target as a final fallback
+* Returns the keys a control handles itself: activation for buttons and
+* links, and navigation for ARIA widgets, following the WAI-ARIA Authoring
+* Practices keyboard patterns (https://www.w3.org/WAI/ARIA/apg/patterns/).
 */
-function shouldIgnoreInputEvent(event, listenerTarget, registrationTarget) {
+function getOwnedKeys(element) {
+	const orientation = element.getAttribute("aria-orientation");
+	switch (element.getAttribute("role")?.trim().split(/\s+/)[0]) {
+		case "button":
+		case "tab":
+		case "option":
+		case "treeitem":
+		case "menuitem":
+		case "menuitemcheckbox":
+		case "menuitemradio": return ACTIVATION;
+		case "link": return ["Enter"];
+		case "checkbox":
+		case "switch":
+		case "radio": return ["Space"];
+		case "menu":
+		case "menubar":
+		case "tree": return [
+			...ARROWS,
+			...EDGES,
+			...ACTIVATION,
+			TYPEAHEAD
+		];
+		case "listbox": return [
+			...orientation === "horizontal" ? HORIZONTAL : VERTICAL,
+			...EDGES,
+			...ACTIVATION,
+			TYPEAHEAD
+		];
+		case "combobox": return [
+			...VERTICAL,
+			...EDGES,
+			...ACTIVATION,
+			TYPEAHEAD
+		];
+		case "tablist": return [
+			...orientation === "vertical" ? VERTICAL : HORIZONTAL,
+			...EDGES,
+			...ACTIVATION
+		];
+		case "toolbar": return [...orientation === "vertical" ? VERTICAL : HORIZONTAL, ...EDGES];
+		case "grid":
+		case "treegrid": return [
+			...ARROWS,
+			...EDGES,
+			...PAGES,
+			...ACTIVATION
+		];
+		case "radiogroup": return [...ARROWS, "Space"];
+		case "slider": return [
+			...ARROWS,
+			...EDGES,
+			...PAGES
+		];
+		case "spinbutton": return [
+			...VERTICAL,
+			...EDGES,
+			...PAGES
+		];
+	}
+	switch (element.localName) {
+		case "button":
+		case "summary": return ACTIVATION;
+		case "input": {
+			const type = element.type;
+			return type === "button" || type === "submit" || type === "reset" ? ACTIVATION : [];
+		}
+		case "a":
+		case "area": return element.hasAttribute("href") ? ["Enter"] : [];
+	}
+	return [];
+}
+/**
+* Whether a control handles this key itself. Ctrl, Meta, and Alt combinations
+* are never owned; Enter and Space are owned only without modifiers, while
+* navigation and typeahead keys allow Shift (for example, to extend a selection).
+*/
+function ownsKey(element, event, key) {
+	if (event.ctrlKey || event.metaKey || event.altKey) return false;
+	const owned = getOwnedKeys(element);
+	if (key === "Enter" || key === "Space") return !event.shiftKey && owned.includes(key);
+	return owned.includes(key) || owned.includes(TYPEAHEAD) && /^\S$/u.test(event.key);
+}
+/**
+* Whether the focused element or an element on the event's path passes `test`.
+* Only elements inside the registration target count: walking outward from
+* the event's origin stops at the registration target, so a hotkey targeted
+* at a control, or at an element inside it, is not blocked by that control.
+*/
+function someElementInsideTarget(event, listenerTarget, registrationTarget, test) {
+	const scoped = !isWindow(registrationTarget) && registrationTarget.nodeType !== 9;
 	const focused = getActiveElementForListenerTarget(listenerTarget);
-	if (focused && isInputElement(focused) && focused !== registrationTarget) return true;
-	if (event.composedPath().some((element) => isInputElement(element) && element !== registrationTarget)) return true;
-	return isInputElement(event.target) && event.target !== registrationTarget;
+	if (focused && focused !== registrationTarget && (!scoped || registrationTarget.contains(focused)) && test(focused)) return true;
+	const path = event.composedPath();
+	for (const element of path.length > 0 ? path : [event.target]) {
+		if (element === registrationTarget) break;
+		if (isElement(element) && test(element)) return true;
+	}
+	return false;
+}
+/**
+* Returns whether a hotkey should skip an event because a focused control
+* inside the registration target handles the key itself:
+* - text inputs, textareas, selects, and contenteditable elements (typing)
+* - buttons, links, and `<summary>` elements (Enter and Space activation)
+* - ARIA widgets such as menus, listboxes, tabs, and grids (navigation keys)
+*/
+function shouldIgnoreInputEvent(event, listenerTarget, registrationTarget) {
+	const key = normalizeKeyName(event.key);
+	return someElementInsideTarget(event, listenerTarget, registrationTarget, (element) => isInputElement(element) || ownsKey(element, event, key));
+}
+/**
+* Returns whether an event comes from a text input, textarea, select, or
+* contenteditable element in the target's document. Unlike
+* `shouldIgnoreInputEvent`, buttons, links, and ARIA widgets don't count.
+*/
+function isTypingEvent(event, target) {
+	return someElementInsideTarget(event, target, target, isInputElement);
 }
 /**
 * Checks if an event is for the given target (originated from or bubbled to it).
 *
-* For document/window targets, also accepts document.documentElement as currentTarget
-* to handle Brave and other browsers where currentTarget may be documentElement
-* instead of document when listeners are attached to document.
+* For document/window targets, also accepts the document's root element as
+* currentTarget to handle Brave and other browsers where currentTarget may be
+* documentElement instead of document when listeners are attached to document.
 */
 function isEventForTarget(event, target) {
-	if (target === document || target === window) return event.currentTarget === target || event.currentTarget === document.documentElement;
-	if (target === window) return event.currentTarget === window || event.currentTarget === document || event.currentTarget === document.documentElement;
-	if (target instanceof HTMLElement) {
-		if (event.currentTarget === target) return true;
-		if (event.target instanceof Node && target.contains(event.target)) return true;
-	}
-	return false;
+	if (event.currentTarget === target) return true;
+	if (isWindow(target) || target.nodeType === 9) return event.currentTarget === getTargetDocument(target).documentElement;
+	return isNode(event.target) && target.contains(event.target);
 }
 
 //#endregion
-export { getActiveElementForListenerTarget, isEventForTarget, isInputElement, shouldIgnoreInputEvent };
+export { getActiveElementForListenerTarget, getTargetDocument, isEventForTarget, isInputElement, isTypingEvent, shouldIgnoreInputEvent };

package/dist/_registration.js

@@ -4,15 +4,16 @@
 * Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).
 */
 const defaultHotkeyOptions = {
+	capture: false,
 	preventDefault: true,
 	stopPropagation: true,
 	eventType: "keydown",
 	enabled: true,
-	ignoreInputs: true,
+	ignoreInputs: "auto",
 	conflictBehavior: "warn"
 };
 /**
-* Computes the default ignoreInputs value based on the hotkey.
+* Resolves `ignoreInputs: 'auto'` from the hotkey (the first step of a sequence).
 * Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
 */
 function getDefaultIgnoreInputs(parsedHotkey) {
@@ -31,7 +32,7 @@ function getDefaultIgnoreInputs(parsedHotkey) {
 function handleConflict(conflictingId, keyDisplay, conflictBehavior, unregister) {
 	if (conflictBehavior === "allow") return;
 	if (conflictBehavior === "warn") {
-		console.warn(`'${keyDisplay}' is already registered. Multiple handlers will be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
+		console.warn(`'${keyDisplay}' is already registered. Multiple handlers may be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
 		return;
 	}
 	if (conflictBehavior === "error") throw new Error(`'${keyDisplay}' is already registered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to allow multiple registrations.`);

package/dist/_target-listeners.js

@@ -0,0 +1,72 @@
+//#region src/_target-listeners.ts
+/** Shares keyboard listeners within each target and capture phase. */
+var TargetListeners = class {
+	dispatch;
+	#targets = /* @__PURE__ */ new Map();
+	#processed = /* @__PURE__ */ new WeakMap();
+	constructor(dispatch) {
+		this.dispatch = dispatch;
+	}
+	add(target, capture, id) {
+		if (typeof document === "undefined") return;
+		let phases = this.#targets.get(target);
+		if (!phases) {
+			phases = /* @__PURE__ */ new Map();
+			this.#targets.set(target, phases);
+		}
+		let group = phases.get(capture);
+		if (!group) {
+			const ids = /* @__PURE__ */ new Set();
+			const listener = (eventType) => (rawEvent) => {
+				const event = rawEvent;
+				let processed = this.#processed.get(event);
+				if (!processed || processed.groups.has(ids)) {
+					processed = {
+						ids: /* @__PURE__ */ new Set(),
+						groups: /* @__PURE__ */ new Set()
+					};
+					this.#processed.set(event, processed);
+				}
+				processed.groups.add(ids);
+				const pending = /* @__PURE__ */ new Set();
+				for (const registrationId of ids) if (!processed.ids.has(registrationId)) {
+					processed.ids.add(registrationId);
+					pending.add(registrationId);
+				}
+				this.dispatch(event, target, eventType, capture, pending);
+			};
+			group = {
+				ids,
+				keydown: listener("keydown"),
+				keyup: listener("keyup")
+			};
+			phases.set(capture, group);
+			target.addEventListener("keydown", group.keydown, capture);
+			target.addEventListener("keyup", group.keyup, capture);
+		}
+		group.ids.add(id);
+	}
+	remove(target, capture, id) {
+		const phases = this.#targets.get(target);
+		const group = phases?.get(capture);
+		if (!group) return;
+		group.ids.delete(id);
+		if (group.ids.size === 0) {
+			target.removeEventListener("keydown", group.keydown, capture);
+			target.removeEventListener("keyup", group.keyup, capture);
+			phases.delete(capture);
+			if (phases.size === 0) this.#targets.delete(target);
+		}
+	}
+	destroy() {
+		for (const [target, phases] of this.#targets) for (const [capture, group] of phases) {
+			target.removeEventListener("keydown", group.keydown, capture);
+			target.removeEventListener("keyup", group.keyup, capture);
+		}
+		this.#targets.clear();
+		this.#processed = /* @__PURE__ */ new WeakMap();
+	}
+};
+
+//#endregion
+export { TargetListeners };

package/dist/adapter.js

@@ -1,6 +1,6 @@
 import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, normalizeRegisterableHotkey, parseHotkey } from "./parse.js";
-import { defaultHotkeyOptions, getDefaultIgnoreInputs } from "./_registration.js";
+import { isHotkeySequence, normalizeRegisterableHotkey } from "./parse.js";
+import { defaultHotkeyOptions } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
 import { getAppHotkeyRegistrationOptions, isAppHotkey, resolveAppHotkey } from "./app-hotkeys.js";
 
@@ -23,14 +23,12 @@ function createHotkeyBindings() {
 				const options = {
 					...defaultHotkeyOptions,
 					...merged,
-					ignoreInputs: merged.ignoreInputs,
+					ignoreInputs: merged.ignoreInputs ?? "auto",
 					target: "target" in merged ? merged.target ?? null : typeof document === "undefined" ? null : document,
 					platform: merged.platform ?? detectPlatform()
 				};
 				if (!options.target || isHotkeySequence(definition.hotkey) && definition.hotkey.length === 0) return;
 				const hotkey = normalizeRegisterableHotkey(definition.hotkey, options.platform);
-				const first = isHotkeySequence(hotkey) ? hotkey[0] : hotkey;
-				options.ignoreInputs ??= getDefaultIgnoreInputs(parseHotkey(first, options.platform));
 				if (isHotkeySequence(hotkey)) delete options.requireReset;
 				else delete options.timeout;
 				prepared.push({

package/dist/app-hotkeys.d.ts

@@ -3,7 +3,7 @@ import { HotkeyChordOptions, HotkeyRegistrationView, HotkeySequenceOptions } fro
 import { Store } from "@tanstack/store";
 //#region src/app-hotkeys.d.ts
 type Platform = 'mac' | 'windows' | 'linux';
-type DeclaredOptionKeys = 'conflictBehavior' | 'eventType' | 'ignoreInputs' | 'preventDefault' | 'stopPropagation';
+type DeclaredOptionKeys = 'capture' | 'conflictBehavior' | 'eventType' | 'ignoreInputs' | 'preventDefault' | 'stopPropagation';
 /** Declared options for an app hotkey whose default is a chord. */
 export type AppHotkeyChordOptions = Pick<HotkeyChordOptions, DeclaredOptionKeys | 'requireReset'>;
 /** Declared options for an app hotkey whose default is a sequence. */

package/dist/conflicts.js

@@ -2,18 +2,14 @@ import { detectPlatform } from "./platform.js";
 import { keysEqual } from "./_keyboard-event.js";
 import { isHotkeySequence, parseRegisterableHotkey } from "./parse.js";
 import { matchesKeyboardEvent } from "./match.js";
+import { getTargetDocument } from "./_event-target.js";
 import { getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 
 //#region src/conflicts.ts
 /** Whether two targets share a document and one contains the other (or is its window). */
 function targetsOverlap(a, b) {
 	if (a === b) return true;
-	const documentOf = (target) => {
-		if ("document" in target) return target.document;
-		if (target.nodeType === 9) return target;
-		return target.ownerDocument;
-	};
-	if (documentOf(a) !== documentOf(b)) return false;
+	if (getTargetDocument(a) !== getTargetDocument(b)) return false;
 	if (!("contains" in a) || !("contains" in b)) return true;
 	return a.contains(b) || b.contains(a);
 }

package/dist/hotkey-manager.d.ts

@@ -8,6 +8,14 @@ export type Target = HTMLElement | Document | Window;
  * Options shared by chords and sequences.
  */
 export interface HotkeyOptions {
+  /**
+   * Listen during capture, before descendant listeners. Defaults to `false` (bubble).
+   * With `stopPropagation: true`, a match on an ancestor prevents the event from
+   * reaching descendant widgets. Other listeners on the same target still run.
+   * Applies to both `keydown` and `keyup`, for chords and sequences.
+   * Changing this option preserves held-key reset state and sequence progress.
+   */
+  capture?: boolean;
   /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */
   conflictBehavior?: ConflictBehavior;
   /**
@@ -18,8 +26,17 @@ export interface HotkeyOptions {
   enabled?: boolean;
   /** The event type to listen for. Defaults to 'keydown' */
   eventType?: 'keydown' | 'keyup';
-  /** Whether to ignore hotkeys when keyboard events originate from input-like elements (text inputs, textarea, select, contenteditable — button-type inputs like type=button/submit/reset are not ignored). Defaults based on the hotkey (the first step of a sequence): true for single keys and Shift/Alt combos; false for Ctrl/Meta shortcuts and Escape */
-  ignoreInputs?: boolean;
+  /**
+   * Skip keys that a focused control inside the target uses itself: typing in
+   * text inputs, textarea, select, and contenteditable; Enter/Space on buttons
+   * and summary elements; Enter on links; and navigation keys in ARIA widgets
+   * such as menus, listboxes, tabs, and grids. A hotkey targeted at the control
+   * itself still receives them. Defaults to `'auto'`, which chooses from the
+   * hotkey (the first step of a sequence): true for single keys and Shift/Alt
+   * combos; false for Ctrl/Meta shortcuts and Escape. Set false to handle keys
+   * even in these controls.
+   */
+  ignoreInputs?: boolean | 'auto';
   /** The target platform for resolving 'Mod' */
   platform?: 'mac' | 'windows' | 'linux';
   /** Prevent the default browser action when the hotkey matches. Defaults to true */
@@ -147,6 +164,9 @@ export interface HotkeyRegistrationHandle<TOptions extends HotkeyOptions = Hotke
   /**
    * Update options (merged with existing options).
    * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.
+   * Changing `capture` moves the listener phase without clearing `requireReset`
+   * state or sequence progress. A registration already processed for an event
+   * cannot process it again in another phase.
    */
   setOptions: (options: Partial<TOptions>) => void;
   /** Unregister this hotkey */
@@ -156,8 +176,8 @@ export interface HotkeyRegistrationHandle<TOptions extends HotkeyOptions = Hotke
  * Singleton manager for hotkey registrations, including sequences.
  *
  * This class provides a centralized way to register and manage keyboard
- * hotkeys. It attaches one keydown and one keyup listener per target,
- * regardless of how many hotkeys are registered.
+ * hotkeys. It shares one keydown and one keyup listener per target and
+ * capture phase across registrations.
  *
  * Sequences (Vim-style hotkeys such as `['G', 'G']`) match when every step is
  * pressed within the timeout. Modifier-only events (Shift, Control, Alt, or

package/dist/hotkey-manager.js

@@ -5,9 +5,10 @@ import { isHotkeySequence, isModifierKey, parseHotkey, rawHotkeyToParsedHotkey,
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
+import { isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
+import { TargetListeners } from "./_target-listeners.js";
 import { isRecordingEvent } from "./_recording-guard.js";
 import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
-import { isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
@@ -58,6 +59,11 @@ function optionsForKind(kind, options) {
 function resolvedSteps(registration) {
 	return registration.kind === "chord" ? [registration.parsedHotkey] : registration.parsedSequence;
 }
+/** Whether a registration skips keys that focused controls use, resolving `'auto'`. */
+function ignoresInputs(registration) {
+	const { ignoreInputs = "auto" } = registration.options;
+	return ignoreInputs === "auto" ? getDefaultIgnoreInputs(resolvedSteps(registration)[0]) : ignoreInputs;
+}
 function sameResolvedSteps(left, right) {
 	return left.length === right.length && left.every((step, index) => areHotkeysEqual(step, right[index]));
 }
@@ -68,8 +74,8 @@ function formatForMessage(hotkey) {
 * Singleton manager for hotkey registrations, including sequences.
 *
 * This class provides a centralized way to register and manage keyboard
-* hotkeys. It attaches one keydown and one keyup listener per target,
-* regardless of how many hotkeys are registered.
+* hotkeys. It shares one keydown and one keyup listener per target and
+* capture phase across registrations.
 *
 * Sequences (Vim-style hotkeys such as `['G', 'G']`) match when every step is
 * pressed within the timeout. Modifier-only events (Shift, Control, Alt, or
@@ -118,8 +124,7 @@ var HotkeyManager = class HotkeyManager {
 	*/
 	appHotkeys = new Store(null);
 	#platform;
-	#targetListeners = /* @__PURE__ */ new Map();
-	#targetRegistrations = /* @__PURE__ */ new Map();
+	#listeners = new TargetListeners((...args) => this.#processTargetEvent(...args));
 	constructor() {
 		this.#platform = detectPlatform();
 	}
@@ -167,28 +172,26 @@ var HotkeyManager = class HotkeyManager {
 		const platform = options.platform ?? this.#platform;
 		const target = options.target ?? document;
 		let registration;
-		if (isHotkeySequence(hotkey)) {
-			const parsedSequence = hotkey.map((step) => parseHotkey(step, platform));
-			registration = {
-				kind: "sequence",
-				id,
-				hotkey,
-				parsedSequence,
-				callback,
-				options: {
-					...defaultHotkeyOptions,
-					timeout: DEFAULT_SEQUENCE_TIMEOUT,
-					...optionsForKind("sequence", options),
-					platform,
-					ignoreInputs: options.ignoreInputs ?? getDefaultIgnoreInputs(parsedSequence[0])
-				},
-				target,
-				currentIndex: 0,
-				lastKeyTime: 0,
-				triggerCount: 0,
-				hasFired: false
-			};
-		} else {
+		if (isHotkeySequence(hotkey)) registration = {
+			kind: "sequence",
+			id,
+			hotkey,
+			parsedSequence: hotkey.map((step) => parseHotkey(step, platform)),
+			callback,
+			options: {
+				...defaultHotkeyOptions,
+				timeout: DEFAULT_SEQUENCE_TIMEOUT,
+				...optionsForKind("sequence", options),
+				platform,
+				ignoreInputs: options.ignoreInputs ?? "auto"
+			},
+			target,
+			currentIndex: 0,
+			lastKeyTime: 0,
+			triggerCount: 0,
+			hasFired: false
+		};
+		else {
 			const parsedHotkey = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
 			registration = {
 				kind: "chord",
@@ -201,7 +204,7 @@ var HotkeyManager = class HotkeyManager {
 					requireReset: false,
 					...optionsForKind("chord", options),
 					platform,
-					ignoreInputs: options.ignoreInputs ?? getDefaultIgnoreInputs(parsedHotkey)
+					ignoreInputs: options.ignoreInputs ?? "auto"
 				},
 				target,
 				hasFired: false,
@@ -211,9 +214,7 @@ var HotkeyManager = class HotkeyManager {
 		const conflicting = this.#findConflictingRegistration(registration);
 		if (conflicting) handleConflict(conflicting.id, formatForMessage(registration.hotkey), options.conflictBehavior ?? "warn", (conflictId) => this.#unregister(conflictId));
 		this.registrations.setState((prev) => new Map(prev).set(id, registration));
-		if (!this.#targetRegistrations.has(target)) this.#targetRegistrations.set(target, /* @__PURE__ */ new Set());
-		this.#targetRegistrations.get(target).add(id);
-		this.#ensureListenersForTarget(target);
+		this.#listeners.add(target, !!registration.options.capture, id);
 		const manager = this;
 		return {
 			get id() {
@@ -238,6 +239,11 @@ var HotkeyManager = class HotkeyManager {
 						...optionsForKind(reg.kind, newOptions)
 					};
 					if (optionsEqual(reg.options, options)) return prev;
+					const capture = !!reg.options.capture;
+					if (capture !== !!options.capture) {
+						manager.#listeners.remove(reg.target, capture, id);
+						manager.#listeners.add(reg.target, !!options.capture, id);
+					}
 					return new Map(prev).set(id, {
 						...reg,
 						options
@@ -261,58 +267,31 @@ var HotkeyManager = class HotkeyManager {
 			next.delete(id);
 			return next;
 		});
-		const targetRegs = this.#targetRegistrations.get(target);
-		if (targetRegs) {
-			targetRegs.delete(id);
-			if (targetRegs.size === 0) this.#removeListenersForTarget(target);
-		}
-	}
-	/**
-	* Ensures event listeners are attached for a specific target.
-	*/
-	#ensureListenersForTarget(target) {
-		if (typeof document === "undefined") return;
-		if (this.#targetListeners.has(target)) return;
-		const keydown = (event) => this.#processTargetEvent(event, target, "keydown");
-		const keyup = (event) => this.#processTargetEvent(event, target, "keyup");
-		target.addEventListener("keydown", keydown);
-		target.addEventListener("keyup", keyup);
-		this.#targetListeners.set(target, {
-			keydown,
-			keyup
-		});
-	}
-	/**
-	* Removes event listeners for a specific target.
-	*/
-	#removeListenersForTarget(target) {
-		if (typeof document === "undefined") return;
-		const listeners = this.#targetListeners.get(target);
-		if (!listeners) return;
-		target.removeEventListener("keydown", listeners.keydown);
-		target.removeEventListener("keyup", listeners.keyup);
-		this.#targetListeners.delete(target);
-		this.#targetRegistrations.delete(target);
+		this.#listeners.remove(target, !!registration.options.capture, id);
 	}
-	/** Registrations of one kind on a target, in registration order. */
-	#registrationsOn(target, kind) {
+	/** Registrations of one kind in the listener phase, in registration order. */
+	#registrationsIn(ids, capture, kind) {
 		const result = [];
-		for (const id of this.#targetRegistrations.get(target) ?? []) {
+		for (const id of ids) {
 			const registration = this.registrations.state.get(id);
-			if (registration?.kind === kind) result.push(registration);
+			if (registration?.kind === kind && !!registration.options.capture === capture) result.push(registration);
 		}
 		return result;
 	}
+	/** The live registration, unless it was removed or moved to another phase. */
+	#currentIn(registration, capture) {
+		const current = this.registrations.state.get(registration.id);
+		return current && !!current.options.capture === capture ? current : void 0;
+	}
 	/**
 	* Processes keyboard events for a specific target and event type.
 	* Chords and sequences match independently; both may fire for one event.
 	*/
-	#processTargetEvent(event, target, eventType) {
-		this.#processChords(event, target, eventType);
-		this.#processSequences(event, target, eventType);
+	#processTargetEvent(event, target, eventType, capture, ids) {
+		this.#processChords(event, target, eventType, capture, this.#registrationsIn(ids, capture, "chord"));
+		this.#processSequences(event, target, eventType, capture, this.#registrationsIn(ids, capture, "sequence"));
 	}
-	#processChords(event, target, eventType) {
-		const registrations = this.#registrationsOn(target, "chord");
+	#processChords(event, target, eventType, capture, registrations) {
 		if (eventType === "keyup") {
 			for (const registration of registrations) if (registration.hasFired && this.#shouldResetRegistration(registration, event)) {
 				registration.hasFired = false;
@@ -323,16 +302,18 @@ var HotkeyManager = class HotkeyManager {
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!registration.options.enabled || registration.options.eventType !== eventType || !isEventForTarget(event, target) || registration.options.ignoreInputs !== false && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			if (!registration.options.enabled || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
 			const result = matchKeyboardEvent(event, registration.parsedHotkey, registration.options.platform);
 			if (result.matched) {
 				matches.set(registration.id, result);
 				bestScore = Math.max(bestScore, result.score);
 			}
 		}
-		for (const registration of registrations) {
-			const match = matches.get(registration.id);
+		for (const snapshot of registrations) {
+			const match = matches.get(snapshot.id);
 			if (!match?.matched || match.score !== bestScore) continue;
+			const registration = this.#currentIn(snapshot, capture);
+			if (!registration) continue;
 			if (eventType === "keyup") {
 				this.#executeCallback(registration, event);
 				continue;
@@ -340,16 +321,15 @@ var HotkeyManager = class HotkeyManager {
 			if (registration.options.preventDefault) event.preventDefault();
 			if (registration.options.stopPropagation) event.stopPropagation();
 			if (!registration.options.requireReset || !registration.hasFired) {
-				this.#executeCallback(registration, event);
 				if (registration.options.requireReset) {
 					registration.hasFired = true;
 					registration.activeMatch = match.identity;
 				}
+				this.#executeCallback(registration, event);
 			}
 		}
 	}
-	#processSequences(event, target, eventType) {
-		const registrations = this.#registrationsOn(target, "sequence");
+	#processSequences(event, target, eventType, capture, registrations) {
 		if (registrations.length === 0) return;
 		if (isRecordingEvent(event)) {
 			let changed = false;
@@ -367,7 +347,7 @@ var HotkeyManager = class HotkeyManager {
 		const candidates = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!isEventForTarget(event, target) || !registration.options.enabled || registration.options.ignoreInputs !== false && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
+			if (!isEventForTarget(event, target) || !registration.options.enabled || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
 			const timeout = registration.options.timeout ?? 1e3;
 			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
 				registration.currentIndex = 0;
@@ -407,7 +387,10 @@ var HotkeyManager = class HotkeyManager {
 			}
 		}
 		if (changed && completed.length === 0) this.#notify();
-		for (const registration of completed) this.#executeCallback(registration, event);
+		for (const snapshot of completed) {
+			const registration = this.#currentIn(snapshot, capture);
+			if (registration) this.#executeCallback(registration, event);
+		}
 	}
 	/**
 	* Executes a hotkey callback with proper event handling.
@@ -514,11 +497,9 @@ var HotkeyManager = class HotkeyManager {
 	* Destroys the manager and removes all listeners.
 	*/
 	destroy() {
-		for (const target of this.#targetListeners.keys()) this.#removeListenersForTarget(target);
+		this.#listeners.destroy();
 		this.registrations.setState(() => /* @__PURE__ */ new Map());
 		this.appHotkeys.setState(() => null);
-		this.#targetListeners.clear();
-		this.#targetRegistrations.clear();
 	}
 };
 /**

package/dist/hotkey-recorder.js

@@ -2,8 +2,8 @@ import { detectPlatform } from "./platform.js";
 import { normalizeKeyboardEvent } from "./_keyboard-event.js";
 import { isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
 import { validateHotkey } from "./validate.js";
+import { isTypingEvent } from "./_event-target.js";
 import { beginRecording, captureRecordingEvent, endRecording } from "./_recording-guard.js";
-import { shouldIgnoreInputEvent } from "./_event-target.js";
 import { findHotkeyConflicts } from "./conflicts.js";
 import { chordRejection, hotkeyChordFromKeydown } from "./_recorder-chord.js";
 import { Store } from "@tanstack/store";
@@ -111,7 +111,7 @@ var HotkeyRecorder = class {
 		}));
 		const handler = (event) => {
 			if (!this.#keydownHandler) return;
-			if (this.#options.ignoreInputs !== false && event.key !== "Escape" && shouldIgnoreInputEvent(event, document, document)) return;
+			if (this.#options.ignoreInputs !== false && event.key !== "Escape" && isTypingEvent(event, document)) return;
 			const platform = this.#options.platform ?? this.#platform;
 			if (normalizeKeyboardEvent(event, platform).isComposing) return;
 			captureRecordingEvent(event);

package/dist/key-state-tracker.js

@@ -55,6 +55,7 @@ var KeyStateTracker = class KeyStateTracker {
 	#heldEntries = /* @__PURE__ */ new Map();
 	#keydownListener = null;
 	#keyupListener = null;
+	#mouseListener = null;
 	#blurListener = null;
 	constructor() {
 		this.#setupListeners();
@@ -81,6 +82,7 @@ var KeyStateTracker = class KeyStateTracker {
 	#setupListeners() {
 		if (typeof document === "undefined") return;
 		this.#keydownListener = (event) => {
+			let changed = this.#reconcileModifiers(event);
 			const key = normalizeKeyName(event.key);
 			const identity = event.code || `key:${key}`;
 			if (!this.#heldEntries.has(identity)) {
@@ -88,8 +90,9 @@ var KeyStateTracker = class KeyStateTracker {
 					key,
 					code: event.code
 				});
-				this.#syncState();
+				changed = true;
 			}
+			if (changed) this.#syncState();
 		};
 		this.#keyupListener = (event) => {
 			const key = normalizeKeyName(event.key);
@@ -98,22 +101,44 @@ var KeyStateTracker = class KeyStateTracker {
 			if (!event.code) {
 				for (const [entryIdentity, entry] of this.#heldEntries) if (entry.key === key) this.#heldEntries.delete(entryIdentity);
 			}
+			this.#reconcileModifiers(event);
 			if (MODIFIER_KEYS.has(key)) {
 				for (const [entryIdentity, entry] of this.#heldEntries) if (!MODIFIER_KEYS.has(entry.key)) this.#heldEntries.delete(entryIdentity);
 			}
 			this.#syncState();
 		};
+		this.#mouseListener = (event) => {
+			if (this.#reconcileModifiers(event)) this.#syncState();
+		};
 		this.#blurListener = () => {
 			if (this.#heldEntries.size > 0) {
 				this.#heldEntries.clear();
 				this.#syncState();
 			}
 		};
-		document.addEventListener("keydown", this.#keydownListener, true);
-		document.addEventListener("keyup", this.#keyupListener, true);
+		window.addEventListener("keydown", this.#keydownListener, true);
+		window.addEventListener("keyup", this.#keyupListener, true);
+		window.addEventListener("mousemove", this.#mouseListener, true);
+		window.addEventListener("mousedown", this.#mouseListener, true);
 		window.addEventListener("blur", this.#blurListener);
 	}
 	/**
+	* Removes modifiers whose release was missed without a window blur.
+	* Event modifier state is shared by left/right keys, so a true flag keeps
+	* both physical entries until their individual keyup events arrive.
+	* Only real user input counts: events dispatched by page code report no
+	* modifiers and would clear keys the user is still holding.
+	*/
+	#reconcileModifiers(event) {
+		if (!event.isTrusted) return false;
+		let changed = false;
+		for (const [identity, entry] of this.#heldEntries) if (entry.key === "Control" && !event.ctrlKey || entry.key === "Alt" && !event.altKey || entry.key === "Shift" && !event.shiftKey || entry.key === "Meta" && !event.metaKey) {
+			this.#heldEntries.delete(identity);
+			changed = true;
+		}
+		return changed;
+	}
+	/**
 	* Syncs the internal Set to the Store state.
 	*/
 	#syncState() {
@@ -130,13 +155,18 @@ var KeyStateTracker = class KeyStateTracker {
 	#removeListeners() {
 		if (typeof document === "undefined") return;
 		if (this.#keydownListener) {
-			document.removeEventListener("keydown", this.#keydownListener, true);
+			window.removeEventListener("keydown", this.#keydownListener, true);
 			this.#keydownListener = null;
 		}
 		if (this.#keyupListener) {
-			document.removeEventListener("keyup", this.#keyupListener, true);
+			window.removeEventListener("keyup", this.#keyupListener, true);
 			this.#keyupListener = null;
 		}
+		if (this.#mouseListener) {
+			window.removeEventListener("mousemove", this.#mouseListener, true);
+			window.removeEventListener("mousedown", this.#mouseListener, true);
+			this.#mouseListener = null;
+		}
 		if (this.#blurListener) {
 			window.removeEventListener("blur", this.#blurListener);
 			this.#blurListener = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",