@tanstack/hotkeys 0.23.0 → 0.24.0

package/dist/_event-target.js

@@ -250,6 +250,29 @@ function findBlocker(event, doc, test) {
 function blocks({ elements, index }, target) {
 	return index >= 0 && (isDocumentLevel(target) || index < elements.indexOf(target));
 }
+/** Open modal dialogs and popovers that close on Escape, per event. */
+const layerCache = /* @__PURE__ */ new WeakMap();
+/**
+* Returns whether Escape will close a modal `<dialog>` or an open popover that
+* `target` isn't inside. The browser closes it only when Escape's keydown
+* isn't prevented, so hotkeys outside it leave Escape alone.
+*/
+function closesNativeLayer(event, target) {
+	if (event.type !== "keydown" || event.key !== "Escape") return false;
+	let layers = layerCache.get(event);
+	if (!layers) {
+		const found = [];
+		for (const selector of ["dialog:modal", ":popover-open"]) try {
+			found.push(...getTargetDocument(target).querySelectorAll(selector));
+		} catch {}
+		layers = found.filter((layer) => layer.popover !== "manual");
+		layerCache.set(event, layers);
+	}
+	return layers.some((layer) => {
+		for (let node = isDocumentLevel(target) ? null : target; node; node = composedParent(node)) if (node === layer) return false;
+		return true;
+	});
+}
 const ignoreCache = /* @__PURE__ */ new WeakMap();
 /**
 * Returns whether a hotkey on `target` should skip an event because a control
@@ -280,4 +303,4 @@ function isTypingEvent(event, target) {
 }
 
 //#endregion
-export { getTargetDocument, isDocumentLevel, isInputElement, isTypingEvent, shouldIgnoreInputEvent, targetHasFocus };
+export { closesNativeLayer, getTargetDocument, isDocumentLevel, isInputElement, isTypingEvent, shouldIgnoreInputEvent, targetHasFocus };

package/dist/_server.js

@@ -11,7 +11,7 @@ let warned = false;
 * users on macOS and Windows after hydration.
 */
 function warnServerPlatform() {
-	if (process.env.NODE_ENV !== "production" && !warned && isServerRuntime()) {
+	if (typeof process !== "undefined" && process.env.NODE_ENV !== "production" && !warned && isServerRuntime()) {
 		warned = true;
 		console.warn("[TanStack Hotkeys] A hotkey label was formatted during server rendering without a platform, so it uses 'linux'. Mac and Windows users get a different label after hydration. Read the platform from the request with `detectPlatform(userAgent)`, set it as the `platform` of your hotkeys provider or scope, and format labels with your adapter's formatter, such as `useFormatForDisplay`. Or render the labels only in the browser. See the server rendering section of the Displaying Hotkeys guide.");
 	}

package/dist/_target-listeners.js

@@ -7,10 +7,19 @@ var TargetListeners = class {
 	constructor(dispatch) {
 		this.dispatch = dispatch;
 	}
-	add(target, capture, id) {
+	/**
+	* Adds a registration to the target's shared listener. With `last`, an
+	* existing listener moves after listeners added since it, such as one a
+	* framework attached later to delegate key events.
+	*/
+	add(target, capture, id, last = false) {
 		if (typeof document === "undefined") return;
 		const phases = this.#targets.get(target) ?? /* @__PURE__ */ new Map();
 		let group = phases.get(capture);
+		if (group && last) for (const type of ["keydown", "keyup"]) {
+			target.removeEventListener(type, group[type], capture);
+			target.addEventListener(type, group[type], capture);
+		}
 		if (!group) {
 			const ids = /* @__PURE__ */ new Set();
 			const listener = (eventType) => (rawEvent) => {

package/dist/adapter.d.ts

@@ -26,8 +26,12 @@ export type HotkeyDefinition = {
 };
 /** Options shared by every definition. Each option applies only to the kinds that support it. */
 export type HotkeyBindingsCommonOptions = HotkeyChordOptions & HotkeySequenceOptions;
-/** Reconciles adapter registrations while retaining handles for option updates. */
-export declare function createHotkeyBindings(): {
+/**
+ * Reconciles adapter registrations while retaining handles for option updates.
+ * Adapters for frameworks that delegate key events, such as React, pass
+ * `{ afterDelegatedHandlers: true }`.
+ */
+export declare function createHotkeyBindings(adapterOptions?: Pick<HotkeyOptions, 'afterDelegatedHandlers'>): {
   /**
    * Registers new definitions, updates existing ones in place, and removes
    * stale ones. Definitions with no hotkey (undefined, null, empty string, or
@@ -37,7 +41,7 @@ export declare function createHotkeyBindings(): {
   destroy(): void;
 };
 /** Options with a framework-specific target, such as a ref. */
-export type WithTarget<TOptions, TTarget> = Omit<TOptions, 'target' | 'appHotkeyId'> & {
+export type WithTarget<TOptions, TTarget> = Omit<TOptions, 'target' | 'appHotkeyId' | 'afterDelegatedHandlers'> & {
   /** The element to listen on. Defaults to document. */
   target?: TTarget;
 };

package/dist/adapter.js

@@ -4,8 +4,12 @@ import { createStore } from "./_store.js";
 import { createAppHotkeysStore, detectPlatform, getAppHotkeyRegistrationOptions, getHotkeyManager, isAppHotkey, isHotkeySequence, normalizeHotkey, parseHotkey, resolveAppHotkey } from "@tanstack/hotkeys";
 
 //#region src/adapter.ts
-/** Reconciles adapter registrations while retaining handles for option updates. */
-function createHotkeyBindings() {
+/**
+* Reconciles adapter registrations while retaining handles for option updates.
+* Adapters for frameworks that delegate key events, such as React, pass
+* `{ afterDelegatedHandlers: true }`.
+*/
+function createHotkeyBindings(adapterOptions = {}) {
 	const registrations = /* @__PURE__ */ new Map();
 	return {
 		/**
@@ -20,6 +24,7 @@ function createHotkeyBindings() {
 				const options = {
 					...defaultHotkeyOptions,
 					...merged,
+					...adapterOptions,
 					target: "target" in merged ? merged.target ?? null : typeof document === "undefined" ? null : document,
 					platform: merged.platform ?? detectPlatform()
 				};

package/dist/hotkey-manager.d.ts

@@ -24,8 +24,19 @@ export interface HotkeyOptions {
    * existing handle via `setOptions` rather than unregistering. Defaults to `true`.
    */
   enabled?: boolean;
-  /** The event type to listen for. Defaults to 'keydown' */
+  /**
+   * The event type to listen for. Defaults to 'keydown'. A 'keyup' chord fires
+   * when its key or one of its modifiers is released, whichever comes first,
+   * unless another key was pressed in between. `preventDefault` applies to
+   * its keydown too.
+   */
   eventType?: 'keydown' | 'keyup';
+  /**
+   * Skip a key press that a listener outside TanStack Hotkeys already handled
+   * by calling `preventDefault()`, such as a component library's dialog that
+   * closes on Escape. Defaults to `false`.
+   */
+  ignoreDefaultPrevented?: boolean;
   /**
    * Skip keys that a focused control inside the target uses itself: typing in
    * text inputs, textarea, select, and contenteditable; Enter/Space on buttons
@@ -70,6 +81,16 @@ export interface HotkeyOptions {
   scope?: string;
   /** Id of the app hotkey this registration implements. Adapters set this when registering an app hotkey from `defineAppHotkeys`. */
   appHotkeyId?: string;
+  /**
+   * Run after key handlers that a framework calls from one listener on its
+   * root or the document, such as React's `onKeyDown`, so handlers inside the
+   * target run first and can stop the hotkey. An element target then listens
+   * on its document, or on its closed shadow root, instead of the element. A
+   * stop by an earlier listener there skips the hotkey. Applies only to the
+   * bubble phase.
+   * Adapters for frameworks that delegate key events set this.
+   */
+  afterDelegatedHandlers?: boolean;
 }
 /** Options for a single chord such as `'Mod+S'`. */
 export interface HotkeyChordOptions extends HotkeyOptions {

package/dist/hotkey-manager.js

@@ -6,7 +6,7 @@ import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 import { GLOBAL_SCOPE, chordHasKey, defaultHotkeyOptions, definedOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
-import { getTargetDocument, isDocumentLevel, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
+import { closesNativeLayer, getTargetDocument, isDocumentLevel, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
 import { createStore } from "./_store.js";
 import { TargetListeners } from "./_target-listeners.js";
 import { managerRef } from "./_manager-ref.js";
@@ -91,6 +91,23 @@ function optionsForKind(kind, options) {
 	const { requireReset: _requireReset, ...rest } = options;
 	return rest;
 }
+/**
+* Where a registration listens: its target, or for an element target that
+* runs after delegated handlers in the bubble phase, the node where handlers
+* delegated around it have already run. That is its document, unless the
+* element is in a closed shadow root, which hides it from listeners outside,
+* or in a tree outside any document, which events never leave.
+*/
+function listenerTarget({ target, options }) {
+	if (!options.afterDelegatedHandlers || options.capture || isDocumentLevel(target)) return target;
+	let root = target.getRootNode();
+	while ("host" in root && root.mode === "open") root = root.host.getRootNode();
+	return root;
+}
+/** Whether a registration's shared listener moves after listeners added before it joins. */
+function movesAfterDelegatedHandlers(options) {
+	return !!options.afterDelegatedHandlers && !options.capture;
+}
 /** Steps with Mod already resolved for the registration's platform. */
 function resolvedSteps(registration) {
 	return registration.kind === "chord" ? [registration.parsedChord] : registration.parsedSequence;
@@ -173,8 +190,20 @@ var HotkeyManager = class HotkeyManager {
 	/** Scopes that can fire while a scope is exclusive, or `null` when none is. */
 	#liveScopes = null;
 	#listeners = new TargetListeners((...args) => this.#processTargetEvent(...args));
+	/** Where each registration listens, kept so cleanup finds a target that moved documents. */
+	#listenerTargets = /* @__PURE__ */ new Map();
 	/** Events that continue a sequence in progress, decided before any listener runs. */
 	#sequenceOwned = /* @__PURE__ */ new WeakMap();
+	/**
+	* Keyup chords whose keydown matched. Releasing one of the chord's
+	* modifiers fires them, because the key's own keyup may come after the
+	* modifier's or, on macOS while Command is held, not at all. `null` marks a
+	* press that another key cancelled or that `ignoreDefaultPrevented`
+	* skipped, so its release doesn't fire.
+	*/
+	#pendingReleases = /* @__PURE__ */ new Map();
+	/** Events this manager prevented, so its own prevention never skips a hotkey. */
+	#prevented = /* @__PURE__ */ new WeakSet();
 	/** Physical keys whose keydown a sequence owned, so their repeats and keyup are owned too. */
 	#sequenceOwnedKeys = /* @__PURE__ */ new Set();
 	/** Timers that clear a sequence's progress once its timeout passes. */
@@ -250,7 +279,7 @@ var HotkeyManager = class HotkeyManager {
 		const parents = /* @__PURE__ */ new Map();
 		const latest = /* @__PURE__ */ new Map();
 		for (const activation of this.#scopeActivations) {
-			parents.set(activation.scope, activation.parent);
+			if (activation.parent !== activation.scope) parents.set(activation.scope, activation.parent);
 			latest.set(activation.scope, Math.max(latest.get(activation.scope) ?? 0, activation.order));
 		}
 		const depth = (scope) => {
@@ -311,7 +340,7 @@ var HotkeyManager = class HotkeyManager {
 	#handledByLiveHotkey(event, eventType) {
 		const path = event.composedPath();
 		for (const registration of this.registrations.state.values()) {
-			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !path.includes(registration.target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, registration.target)) continue;
+			if (!this.#isLive(registration) || registration.options.eventType !== eventType || this.#skips(registration, event) || !path.includes(registration.target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, registration.target)) continue;
 			if ((registration.kind === "chord" ? [registration.parsedChord] : [registration.parsedSequence[registration.currentIndex], registration.parsedSequence[0]]).some((step) => matchKeyboardEvent(event, step, registration.options.platform).matched)) return true;
 		}
 		return false;
@@ -367,7 +396,9 @@ 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.#listeners.add(target, !!registration.options.capture, id);
+		const listenOn = listenerTarget(registration);
+		this.#listeners.add(listenOn, !!registration.options.capture, id, movesAfterDelegatedHandlers(registration.options));
+		this.#listenerTargets.set(id, listenOn);
 		this.registrations.setState((prev) => new Map(prev).set(id, registration));
 		const manager = this;
 		return {
@@ -399,10 +430,16 @@ var HotkeyManager = class HotkeyManager {
 					else delete options[key];
 					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);
-					}
+					const from = manager.#listenerTargets.get(id) ?? reg.target;
+					const to = listenerTarget({
+						target: reg.target,
+						options
+					});
+					if (capture !== !!options.capture || from !== to) {
+						manager.#listeners.remove(from, capture, id);
+						manager.#listeners.add(to, !!options.capture, id, movesAfterDelegatedHandlers(options));
+						manager.#listenerTargets.set(id, to);
+					} else if (movesAfterDelegatedHandlers(options) && !movesAfterDelegatedHandlers(reg.options)) manager.#listeners.add(to, capture, id, true);
 					return new Map(prev).set(id, {
 						...reg,
 						options
@@ -420,13 +457,14 @@ var HotkeyManager = class HotkeyManager {
 	#unregister(id) {
 		const registration = this.registrations.state.get(id);
 		if (!registration) return;
-		const target = registration.target;
 		this.registrations.setState((prev) => {
 			const next = new Map(prev);
 			next.delete(id);
 			return next;
 		});
-		this.#listeners.remove(target, !!registration.options.capture, id);
+		this.#listeners.remove(this.#listenerTargets.get(id) ?? registration.target, !!registration.options.capture, id);
+		this.#listenerTargets.delete(id);
+		this.#pendingReleases.delete(id);
 		this.#clearSequenceReset(id);
 	}
 	/**
@@ -478,6 +516,30 @@ var HotkeyManager = class HotkeyManager {
 	*/
 	#processTargetEvent(event, target, eventType, capture, ids, first) {
 		if (first) this.#sequenceOwned.set(event, this.#isOwnedBySequence(event, eventType));
+		if (capture) {
+			this.#processRound(event, target, eventType, capture, ids);
+			return;
+		}
+		const rounds = /* @__PURE__ */ new Map();
+		for (const id of ids) {
+			const registration = this.registrations.state.get(id);
+			if (!registration) continue;
+			const round = rounds.get(registration.target) ?? /* @__PURE__ */ new Set();
+			rounds.set(registration.target, round.add(id));
+		}
+		const path = rounds.size > 1 || !rounds.has(target) ? event.composedPath() : [];
+		const order = [...rounds.keys()].filter((other) => other === target || path.includes(other)).sort((a, b) => a === target ? 1 : b === target ? -1 : path.indexOf(a) - path.indexOf(b));
+		const arrivedStopped = event.cancelBubble;
+		for (const roundTarget of order) {
+			const round = /* @__PURE__ */ new Set();
+			for (const id of rounds.get(roundTarget)) {
+				const delegated = this.registrations.state.get(id)?.options.afterDelegatedHandlers;
+				if (!event.cancelBubble || !delegated && arrivedStopped) round.add(id);
+			}
+			this.#processRound(event, roundTarget, eventType, capture, round);
+		}
+	}
+	#processRound(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"));
 	}
@@ -488,15 +550,47 @@ var HotkeyManager = class HotkeyManager {
 				registration.activeMatch = void 0;
 			}
 		}
+		if (eventType === "keydown" && !event.repeat) {
+			for (const { id } of registrations) if (this.#pendingReleases.get(id)) this.#pendingReleases.set(id, null);
+		}
 		if (isRecordingEvent(event) || this.#sequenceOwned.get(event)) return;
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		let reserved = false;
+		const eventKey = normalizeKeyName(event.key);
 		for (const registration of registrations) {
 			const live = this.#isLive(registration);
-			if (!live && registration.options.preventDefault !== "always" || registration.options.eventType !== eventType || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target)) continue;
-			const result = matchKeyboardEvent(event, registration.parsedChord, registration.options.platform);
-			if (!result.matched) continue;
+			const { eventType: firesOn, preventDefault } = registration.options;
+			const press = eventType === "keydown" && firesOn === "keyup";
+			const skipped = this.#skips(registration, event);
+			const { parsedChord, id } = registration;
+			const { platform } = registration.options;
+			let result;
+			let released;
+			if (eventType === "keyup" && firesOn === "keyup" && this.#pendingReleases.has(id)) {
+				result = matchKeyboardEvent(event, parsedChord, platform);
+				if (result.matched || parsedChord.modifiers.includes(eventKey) && !event.getModifierState(eventKey)) {
+					released = this.#pendingReleases.get(id);
+					this.#pendingReleases.delete(id);
+				}
+			}
+			if (!live && preventDefault !== "always" || firesOn !== eventType && !press || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target)) continue;
+			result ??= matchKeyboardEvent(event, parsedChord, platform);
+			if (press) {
+				if (result.matched) {
+					if (skipped) this.#pendingReleases.set(id, null);
+					else {
+						if (preventDefault) this.#prevent(event);
+						if (live) this.#pendingReleases.set(id, result);
+					}
+				}
+				continue;
+			}
+			if (released !== void 0) {
+				if (!released || skipped) continue;
+				if (!result.matched) result = released;
+			}
+			if (skipped || !result.matched) continue;
 			if (!live) {
 				reserved = true;
 				continue;
@@ -504,7 +598,7 @@ var HotkeyManager = class HotkeyManager {
 			matches.set(registration.id, result);
 			bestScore = Math.max(bestScore, result.score);
 		}
-		if (reserved && matches.size === 0 && !this.#handledByLiveHotkey(event, eventType)) event.preventDefault();
+		if (reserved && matches.size === 0 && !this.#handledByLiveHotkey(event, eventType)) this.#prevent(event);
 		let bestRank = -1;
 		for (const registration of registrations) if (matches.get(registration.id)?.score === bestScore) bestRank = Math.max(bestRank, this.#scopeRank(registration.options.scope));
 		for (const snapshot of registrations) {
@@ -548,7 +642,7 @@ var HotkeyManager = class HotkeyManager {
 		const path = event.composedPath();
 		const now = Date.now();
 		for (const registration of this.registrations.state.values()) {
-			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !this.#isLive(registration) || registration.options.eventType !== eventType || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
+			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !this.#isLive(registration) || registration.options.eventType !== eventType || this.#skips(registration, event) || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
 			const target = registration.target;
 			if (path.includes(isDocumentLevel(target) ? getTargetDocument(target) : target) && !(ignoresInputs(registration) && shouldIgnoreInputEvent(event, target)) && matchKeyboardEvent(event, registration.parsedSequence[registration.currentIndex], registration.options.platform).matched) return true;
 		}
@@ -573,7 +667,7 @@ var HotkeyManager = class HotkeyManager {
 		const candidates = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target) || registration.options.eventType !== eventType) continue;
+			if (!this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target) || registration.options.eventType !== eventType || this.#skips(registration, event)) continue;
 			const timeout = registration.options.timeout ?? 1e3;
 			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
 				registration.currentIndex = 0;
@@ -605,7 +699,7 @@ var HotkeyManager = class HotkeyManager {
 					this.#consume(registration, event);
 					registration.currentIndex = 0;
 					completed.push(registration);
-				} else if (registration.options.preventDefault) event.preventDefault();
+				} else if (registration.options.preventDefault) this.#prevent(event);
 			} else if (registration.currentIndex > 0) {
 				registration.currentIndex = 0;
 				changed = true;
@@ -624,9 +718,21 @@ var HotkeyManager = class HotkeyManager {
 			if (registration) this.#fire(registration, event);
 		}
 	}
+	#prevent(event) {
+		if (!event.defaultPrevented) this.#prevented.add(event);
+		event.preventDefault();
+	}
+	/**
+	* Whether the registration skips the event: Escape belongs to an open modal
+	* dialog or popover outside its target, or another listener prevented the
+	* event and the registration skips such events.
+	*/
+	#skips(registration, event) {
+		return closesNativeLayer(event, registration.target) || !!registration.options.ignoreDefaultPrevented && event.defaultPrevented && !this.#prevented.has(event);
+	}
 	/** Applies a matched registration's preventDefault and stopPropagation options. */
 	#consume(registration, event) {
-		if (registration.options.preventDefault) event.preventDefault();
+		if (registration.options.preventDefault) this.#prevent(event);
 		if (registration.options.stopPropagation) event.stopPropagation();
 	}
 	/** Counts a trigger, notifies subscribers (such as devtools), and runs the callback. */
@@ -634,7 +740,9 @@ var HotkeyManager = class HotkeyManager {
 		registration.triggerCount++;
 		if (registration.kind === "sequence") registration.hasFired = true;
 		this.#notify();
+		const prevented = event.defaultPrevented;
 		registration.callback(event, context);
+		if (!prevented && event.defaultPrevented) this.#prevented.add(event);
 	}
 	#callbackContext(registration) {
 		return registration.kind === "chord" ? {
@@ -719,6 +827,7 @@ var HotkeyManager = class HotkeyManager {
 		for (const timer of this.#sequenceResetTimers.values()) clearTimeout(timer);
 		this.#sequenceResetTimers.clear();
 		this.#listeners.destroy();
+		this.#listenerTargets.clear();
 		this.registrations.setState(() => /* @__PURE__ */ new Map());
 		this.appHotkeys.setState(() => null);
 	}

package/package.json

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

package/skills/hotkeys-core/SKILL.md

@@ -63,6 +63,8 @@ When nesting scopes, stacking dialogs, or keeping some hotkeys working during an
 - **Letters follow the typed character.** For position-based controls such as WASD, use physical bindings such as `'[KeyW]'`. Keep letters for mnemonic commands such as `Mod+S`.
 - **Each open exclusive scope needs its own name.** A reusable dialog with a fixed scope name breaks when one dialog opens another: both share one scope and both handle `Escape`. Build the name per instance.
 - **A chord on a sequence's first key runs every time the sequence starts.** With `G` and `['G', 'G']`, the first `G` runs the chord. Later keys belong to the sequence. To show "waiting for the next key", read `matchedStepCount` from the adapter's registrations list.
+- **A sequence that starts a longer one doesn't wait for it.** With `['G', 'G']` and `['G', 'G', 'G']`, three G presses run both, with no warning. Pick sequences where neither one starts the other.
+- **Component libraries handle Escape too.** A global `Escape` hotkey can run alongside a library's dropdown or dialog closing, or keep a library's overlay open. Native modal dialogs and popovers get Escape on their own, except `popover="manual"`: hotkeys outside them skip it. Set `ignoreDefaultPrevented: true` in the adapter's shared defaults (on each hotkey in Lit) for libraries that call `preventDefault()` before the hotkey runs, such as Radix UI and shadcn/ui in React. The option can't see a `preventDefault()` that comes after the hotkey, as in Bits UI, so give open overlays an exclusive scope for those and the rest. The sensible defaults guide lists libraries per framework.
 - **Single-character shortcuts need an off switch.** For WCAG 2.1.4, `K`, `?`, and `['G', 'H']` need a user setting passed as `enabled`, or an app hotkey users can remap.
 - **react-hotkeys-hook names don't carry over.** `useHotkeys` and `HotkeysProvider` share names, not signatures: there's no dependency array, `preventDefault` is on by default, and sequences are arrays. Remove the old library, so two libraries don't handle the same keys.
 - **Install only the adapter.** A separately installed `@tanstack/hotkeys` at another version is a second copy, and scopes don't apply across copies.