@tanstack/hotkeys 0.22.1 → 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

@@ -0,0 +1,21 @@
+//#region src/_server.ts
+const SERVER_AGENT = /^(?:Node\.js\/|Deno\/|Bun\/|Cloudflare-Workers)/;
+/** Whether this runs on a server: no `navigator`, or a server runtime's. */
+function isServerRuntime() {
+	return typeof navigator === "undefined" || SERVER_AGENT.test(String(navigator.userAgent));
+}
+let warned = false;
+/**
+* Warns once, in development, when a label's platform is detected during
+* server rendering. The server then renders 'linux' labels, which differ for
+* users on macOS and Windows after hydration.
+*/
+function warnServerPlatform() {
+	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.");
+	}
+}
+
+//#endregion
+export { isServerRuntime, warnServerPlatform };

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

@@ -2,6 +2,7 @@ import { Store, createStore } from "./_store.js";
 import { HotkeyCallback, HotkeyChord, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyOptions, HotkeySequenceOptions, Target } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
+import { HotkeyPlatform } from "./platform.js";
 import { definedOptions, withDefaults } from "./_registration.js";
 import { createAppHotkeysStore } from "@tanstack/hotkeys";
 //#region src/adapter.d.ts
@@ -25,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
@@ -36,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;
 };
@@ -147,11 +152,20 @@ export interface HotkeysProviderScopeProps {
 /**
  * Merges a provider's default options over its parent's. A provider with a
  * `scope` sets `hotkey.scope`, so hotkeys registered inside it use that scope.
+ * A provider's `platform` is inherited, and is the default platform for its
+ * hotkeys and recorders; `hotkey.platform` and `hotkeyRecorder.platform` win.
  */
 export declare function mergeHotkeysProviderDefaults<T extends {
+  platform?: HotkeyPlatform;
   hotkey?: object;
   hotkeyRecorder?: object;
 }>(parent: T | undefined, own: T | undefined, scope: string | undefined): T;
+/**
+ * The platform to render with during server rendering and hydration when no
+ * provider sets one, for a `useSyncExternalStore` server snapshot. Warns once
+ * in development on the server.
+ */
+export declare function getServerPlatformSnapshot(): HotkeyPlatform;
 /**
  * A key for a provider's scope activation, or `null` when the scope should not
  * be active. Equal keys mean the same activation, so adapters reactivate only

package/dist/adapter.js

@@ -1,10 +1,15 @@
+import { warnServerPlatform } from "./_server.js";
 import { chordHasKey, defaultHotkeyOptions, definedOptions, withDefaults } from "./_registration.js";
 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 {
 		/**
@@ -19,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()
 				};
@@ -122,17 +128,31 @@ function subscribePublishedAppHotkeys(onChange) {
 /**
 * Merges a provider's default options over its parent's. A provider with a
 * `scope` sets `hotkey.scope`, so hotkeys registered inside it use that scope.
+* A provider's `platform` is inherited, and is the default platform for its
+* hotkeys and recorders; `hotkey.platform` and `hotkeyRecorder.platform` win.
 */
 function mergeHotkeysProviderDefaults(parent, own, scope) {
+	const parentPlatform = { platform: parent?.platform };
+	const ownPlatform = { platform: own?.platform };
 	return {
+		...definedOptions(parentPlatform, ownPlatform),
 		hotkey: {
-			...definedOptions(parent?.hotkey, own?.hotkey),
+			...definedOptions(parentPlatform, parent?.hotkey, ownPlatform, own?.hotkey),
 			...scope && { scope }
 		},
-		hotkeyRecorder: definedOptions(parent?.hotkeyRecorder, own?.hotkeyRecorder)
+		hotkeyRecorder: definedOptions(parentPlatform, parent?.hotkeyRecorder, ownPlatform, own?.hotkeyRecorder)
 	};
 }
 /**
+* The platform to render with during server rendering and hydration when no
+* provider sets one, for a `useSyncExternalStore` server snapshot. Warns once
+* in development on the server.
+*/
+function getServerPlatformSnapshot() {
+	warnServerPlatform();
+	return "linux";
+}
+/**
 * A key for a provider's scope activation, or `null` when the scope should not
 * be active. Equal keys mean the same activation, so adapters reactivate only
 * when the key changes, not when an inline `exclusive` object is recreated.
@@ -159,4 +179,4 @@ function activateHotkeysProviderScope(key) {
 }
 
 //#endregion
-export { activateHotkeysProviderScope, createAppHotkeysStore, createHotkeyBindings, createStore, definedOptions, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys, withDefaults };
+export { activateHotkeysProviderScope, createAppHotkeysStore, createHotkeyBindings, createStore, definedOptions, getHotkeysProviderScopeKey, getServerPlatformSnapshot, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys, withDefaults };

package/dist/format.js

@@ -1,5 +1,6 @@
 import { MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
 import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
+import { warnServerPlatform } from "./_server.js";
 import { detectPlatform } from "./platform.js";
 import { assertLogicalKey, codeToLogicalKey, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 import { normalizeHotkey } from "./parse.js";
@@ -23,16 +24,21 @@ function formatForDisplay(hotkey, options = {}) {
 	const parts = formatChordParts(hotkey, options);
 	return options.parts ? parts : parts.join(chordSeparator(options));
 }
+/** Detects the platform for a label, warning in development on a server. */
+function detectDisplayPlatform() {
+	warnServerPlatform();
+	return detectPlatform();
+}
 function modifierSymbolsEnabled(options) {
 	const symbols = options.useSymbols ?? true;
 	return typeof symbols === "boolean" ? symbols : symbols.modifiers ?? true;
 }
 function chordSeparator(options) {
-	const platform = options.platform ?? detectPlatform();
+	const platform = options.platform ?? detectDisplayPlatform();
 	return options.separatorToken ?? (platform === "mac" && modifierSymbolsEnabled(options) ? " " : "+");
 }
 function formatChordParts(hotkey, options) {
-	const platform = options.platform ?? detectPlatform();
+	const platform = options.platform ?? detectDisplayPlatform();
 	const symbols = options.useSymbols ?? true;
 	const modifierSymbols = modifierSymbolsEnabled(options);
 	const keySymbols = typeof symbols === "boolean" ? symbols : symbols.keys ?? true;

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/dist/index.d.ts

@@ -2,9 +2,9 @@ import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterK
 import { ConflictBehavior, FourModifierHotkeyChord, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyMeta, HotkeySequence, HotkeySequenceCallbackContext, ParsedHotkeyChord, ParsedModifiers, RawHotkeyChord, RawModifiers, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, SingleModifierHotkeyChord, ThreeModifierHotkeyChord, TwoModifierHotkeyChord } from "./hotkey.types.js";
 import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CustomHotkeys, DefinedAppHotkeys, Register, RegisteredAppHotkeys, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
+import { HotkeyPlatform, detectPlatform, resolveModifier } from "./platform.js";
 import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, normalizeKeyName } from "./constants.js";
 import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
-import { detectPlatform, resolveModifier } from "./platform.js";
 import { DisplayHotkey, DisplayHotkeyChord, FormatDisplayOptions, formatForDisplay, formatHotkey } from "./format.js";
 import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey } from "./parse.js";
 import { ValidatableHotkey, ValidationResult, assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
@@ -14,4 +14,4 @@ import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./co
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./hotkey-recorder.js";
 import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
-export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createAppHotkeysStore, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyPlatform, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createAppHotkeysStore, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/dist/match.d.ts

@@ -1,4 +1,5 @@
 import { HotkeyCallback, HotkeyChord, HotkeyChordCallbackContext, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeySequence } from "./hotkey.types.js";
+import { HotkeyPlatform } from "./platform.js";
 //#region src/match.d.ts
 export interface KeyboardEventMatch {
   matched: boolean;
@@ -96,7 +97,7 @@ export declare function createMultiHotkeyChordHandler(handlers: MultiHotkeyChord
  * Aliases resolve on the supplied platform. A physical code and a logical key
  * remain distinct even when one keyboard event could match both.
  */
-export declare function areHotkeysEqual(left: RegisterableHotkey, right: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): boolean;
+export declare function areHotkeysEqual(left: RegisterableHotkey, right: RegisterableHotkey, platform?: HotkeyPlatform): boolean;
 /** Default timeout between sequence steps (in milliseconds). */
 export declare const DEFAULT_SEQUENCE_TIMEOUT = 1000;
 /**

package/dist/platform.d.ts

@@ -1,21 +1,33 @@
 import { CanonicalModifier } from "./key.types.js";
 //#region src/platform.d.ts
+/** A platform for resolving `Mod` and formatting labels. */
+export type HotkeyPlatform = 'mac' | 'windows' | 'linux';
 /**
- * Detects the current platform based on browser navigator properties.
+ * Detects a platform from a user agent string, or from the browser's
+ * `navigator` when called without one.
  *
  * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
- * Control elsewhere) and for platform-specific hotkey formatting.
+ * Control elsewhere) and for platform-specific hotkey formatting. During server
+ * rendering, pass the request's `User-Agent` header to detect the user's
+ * platform instead of the server's.
  *
+ * @param userAgent - A user agent string, such as a request's `User-Agent` header.
+ * When omitted or `null` (a missing header), reads `navigator`.
  * @returns The detected platform: 'mac', 'windows', or 'linux'
- * @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+ * @remarks Without a user agent, returns 'linux' on a server runtime (no
+ * `navigator`, or Node, Deno, Bun, or Cloudflare Workers), where `navigator`
+ * describes the server.
  *
  * @example
  * ```ts
  * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
  * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+ *
+ * // On the server
+ * detectPlatform(request.headers.get('user-agent'))
  * ```
  */
-export declare function detectPlatform(): 'mac' | 'windows' | 'linux';
+export declare function detectPlatform(userAgent?: string | null): HotkeyPlatform;
 /**
  * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
  *

package/dist/platform.js

@@ -1,25 +1,42 @@
+import { isServerRuntime } from "./_server.js";
+
 //#region src/platform.ts
 /**
-* Detects the current platform based on browser navigator properties.
+* Detects a platform from a user agent string, or from the browser's
+* `navigator` when called without one.
 *
 * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
-* Control elsewhere) and for platform-specific hotkey formatting.
+* Control elsewhere) and for platform-specific hotkey formatting. During server
+* rendering, pass the request's `User-Agent` header to detect the user's
+* platform instead of the server's.
 *
+* @param userAgent - A user agent string, such as a request's `User-Agent` header.
+* When omitted or `null` (a missing header), reads `navigator`.
 * @returns The detected platform: 'mac', 'windows', or 'linux'
-* @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+* @remarks Without a user agent, returns 'linux' on a server runtime (no
+* `navigator`, or Node, Deno, Bun, or Cloudflare Workers), where `navigator`
+* describes the server.
 *
 * @example
 * ```ts
 * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
 * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+*
+* // On the server
+* detectPlatform(request.headers.get('user-agent'))
 * ```
 */
-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";
+function detectPlatform(userAgent) {
+	let platform = "";
+	let agent = userAgent;
+	if (agent == null) {
+		if (isServerRuntime()) return "linux";
+		platform = navigator.platform?.toLowerCase() ?? "";
+		agent = navigator.userAgent ?? "";
+	}
+	agent = agent.toLowerCase();
+	if (platform.includes("mac") || agent.includes("mac")) return "mac";
+	if (platform.includes("win") || agent.includes("win")) return "windows";
 	return "linux";
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.22.1",
+  "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,9 +63,12 @@ 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.
+- **Server-rendered labels need the user's platform.** On a server, `formatForDisplay` renders Linux labels, because the server can't see the user's OS. Read the request's `User-Agent` header, pass `detectPlatform(userAgent)` as the platform of the adapter's provider or scope, and format labels with the adapter's formatter, such as `useFormatForDisplay`. Those pages then depend on the user agent, so keep them out of shared caches or add the platform to the cache key.
 
 When writing tests for hotkeys, read [testing](references/testing.md).