@tanstack/hotkeys 0.16.1 → 0.18.0

package/dist/_event-target.js

@@ -17,6 +17,17 @@ function getTargetDocument(target) {
 	return target.ownerDocument;
 }
 /**
+* Whether key presses reach a listener on `target` right now. Document and
+* window listeners receive every key press in their document. An element
+* receives them only while focus is inside it, including inside a shadow
+* root it contains.
+*/
+function targetHasFocus(target) {
+	if (isWindow(target) || target.nodeType === 9) return true;
+	const active = target.getRootNode().activeElement;
+	return !!active && target.contains(active);
+}
+/**
 * Checks if an element is an input-like element that should be ignored for hotkeys.
 *
 * This includes:
@@ -191,4 +202,4 @@ function isEventForTarget(event, target) {
 }
 
 //#endregion
-export { getActiveElementForListenerTarget, getTargetDocument, isEventForTarget, isInputElement, isTypingEvent, shouldIgnoreInputEvent };
+export { getActiveElementForListenerTarget, getTargetDocument, isEventForTarget, isInputElement, isTypingEvent, shouldIgnoreInputEvent, targetHasFocus };

package/dist/app-hotkeys.js

@@ -227,13 +227,12 @@ var AppHotkeysStore = class {
 			if (list) list.push(registration);
 			else byId.set(id, [registration]);
 		}
-		const manager = getHotkeyManager();
 		return Object.values(this.store.state.appHotkeys).map((appHotkey) => {
 			const registered = byId.get(appHotkey.id) ?? [];
-			const enabled = registered.filter((r) => r.options.enabled !== false);
+			const has = (status) => registered.some((r) => r.status === status);
 			return {
 				appHotkey,
-				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : enabled.length === 0 ? "disabled" : enabled.some((r) => manager.isScopeActive(r.options.scope)) ? "active" : "suspended",
+				status: appHotkey.hotkey === null ? "unbound" : registered.length === 0 ? "inactive" : has("active") ? "active" : has("suspended") ? "suspended" : "disabled",
 				isCustom: isCustomHotkey(appHotkey, this.#platform),
 				registrations: registered
 			};

package/dist/hotkey-manager.d.ts

@@ -1,5 +1,5 @@
 import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
-import { AppHotkeysStore } from "./app-hotkeys.js";
+import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
 import { Store } from "@tanstack/store";
 //#region src/hotkey-manager.d.ts
 /** An element, document, or window that hotkeys can listen on. */
@@ -41,9 +41,14 @@ export interface HotkeyOptions {
   platform?: 'mac' | 'windows' | 'linux';
   /**
    * Prevent the default browser action when the hotkey matches. For a
-   * sequence, every step that advances it does. Defaults to true
+   * sequence, every step that advances it does. Defaults to true.
+   *
+   * `'always'` also prevents it while a chord can't fire because it is
+   * disabled or its scope is inactive or suspended, unless another hotkey
+   * handles the key. It never stops propagation for such a chord. Sequences
+   * treat `'always'` as `true`.
    */
-  preventDefault?: boolean;
+  preventDefault?: boolean | 'always';
   /**
    * Stop event propagation when the hotkey matches. For a sequence, only the
    * last step does, so earlier steps reach other listeners. Defaults to true
@@ -118,8 +123,18 @@ export interface HotkeySequenceRegistration extends RegistrationBase<HotkeySeque
 }
 /** A registered hotkey in the HotkeyManager. */
 export type HotkeyRegistration = HotkeyChordRegistration | HotkeySequenceRegistration;
+/**
+ * Whether a registration is on. Focus isn't checked: a registration on an
+ * element also needs focus inside that element to fire.
+ * - `'active'`: enabled, and its scope is active
+ * - `'suspended'`: enabled, but its scope is inactive or suspended by an exclusive scope
+ * - `'disabled'`: registered with `enabled: false`
+ */
+export type HotkeyRegistrationStatus = 'active' | 'suspended' | 'disabled';
 interface RegistrationViewBase {
   id: string;
+  /** Whether the registration is enabled and in an active scope. */
+  status: HotkeyRegistrationStatus;
   target: Target;
   triggerCount: number;
   hasFired: boolean;
@@ -372,6 +387,17 @@ export declare class HotkeyManager {
    * @returns True if a matching registration exists
    */
   isRegistered(hotkey: RegisterableHotkey, target?: Target): boolean;
+  /**
+   * Checks whether a hotkey can fire now: at least one registration is
+   * enabled, in an active scope, and listening where key presses go. A
+   * registration on `document` or `window` always is; one on an element is
+   * only while focus is inside that element. An app hotkey matches
+   * registrations by id, so custom hotkeys apply.
+   *
+   * @param hotkey - A chord, sequence, or app hotkey
+   * @returns True if a registration that can fire exists
+   */
+  hasActiveRegistration(hotkey: RegisterableHotkey | AppHotkey): boolean;
   /**
    * Destroys the manager and removes all listeners.
    */

package/dist/hotkey-manager.js

@@ -5,7 +5,7 @@ import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
-import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
+import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent, targetHasFocus } from "./_event-target.js";
 import { TargetListeners } from "./_target-listeners.js";
 import { managerRef } from "./_manager-ref.js";
 import { isRecordingEvent } from "./_recording-guard.js";
@@ -13,10 +13,16 @@ import { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConfl
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
+/** Whether a registration can fire now. Without a manager, scopes don't apply. */
+function getRegistrationStatus(options, manager) {
+	if (options.enabled === false) return "disabled";
+	return manager?.isScopeActive(options.scope) === false ? "suspended" : "active";
+}
 /** Creates a public view from an internal registration, stripping the callback. */
 function toHotkeyRegistrationView(reg) {
 	const base = {
 		id: reg.id,
+		status: getRegistrationStatus(reg.options, managerRef.current),
 		target: reg.target,
 		triggerCount: reg.triggerCount,
 		hasFired: reg.hasFired
@@ -270,7 +276,20 @@ var HotkeyManager = class HotkeyManager {
 	}
 	/** Whether a registration can fire now: enabled, in an active scope. */
 	#isLive(registration) {
-		return registration.options.enabled !== false && this.isScopeActive(registration.options.scope);
+		return getRegistrationStatus(registration.options, this) === "active";
+	}
+	/**
+	* Whether a hotkey that can fire would handle this key on any listener the
+	* event reaches, including other targets and phases. A sequence counts when
+	* the key matches its next step or its first step.
+	*/
+	#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, 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;
 	}
 	/** Notifies subscribers after in-place updates such as counts and sequence progress. */
 	#notify() {
@@ -455,14 +474,20 @@ var HotkeyManager = class HotkeyManager {
 		if (isRecordingEvent(event) || this.#sequenceOwned.get(event)) return;
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
+		let reserved = false;
 		for (const registration of registrations) {
-			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			const live = this.#isLive(registration);
+			if (!live && registration.options.preventDefault !== "always" || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
 			const result = matchKeyboardEvent(event, registration.parsedChord, registration.options.platform);
-			if (result.matched) {
-				matches.set(registration.id, result);
-				bestScore = Math.max(bestScore, result.score);
+			if (!result.matched) continue;
+			if (!live) {
+				reserved = true;
+				continue;
 			}
+			matches.set(registration.id, result);
+			bestScore = Math.max(bestScore, result.score);
 		}
+		if (reserved && matches.size === 0 && !this.#handledByLiveHotkey(event, eventType)) event.preventDefault();
 		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) {
@@ -679,6 +704,21 @@ var HotkeyManager = class HotkeyManager {
 		return false;
 	}
 	/**
+	* Checks whether a hotkey can fire now: at least one registration is
+	* enabled, in an active scope, and listening where key presses go. A
+	* registration on `document` or `window` always is; one on an element is
+	* only while focus is inside that element. An app hotkey matches
+	* registrations by id, so custom hotkeys apply.
+	*
+	* @param hotkey - A chord, sequence, or app hotkey
+	* @returns True if a registration that can fire exists
+	*/
+	hasActiveRegistration(hotkey) {
+		const id = typeof hotkey === "object" && "~appHotkey" in hotkey ? hotkey.id : void 0;
+		for (const registration of this.registrations.state.values()) if (this.#isLive(registration) && targetHasFocus(registration.target) && (id === void 0 ? areHotkeysEqual(registration.hotkey, hotkey, registration.options.platform) : registration.options.appHotkeyId === id)) return true;
+		return false;
+	}
+	/**
 	* Destroys the manager and removes all listeners.
 	*/
 	destroy() {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.js";
 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, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.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 { 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";
@@ -13,4 +13,4 @@ import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
 import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
 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";
-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, 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, 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, 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, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -21,7 +21,8 @@
     "keyboard",
     "shortcuts",
     "keybindings",
-    "typescript"
+    "typescript",
+    "tanstack-intent"
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -35,7 +36,8 @@
     "node": ">=20"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
     "@tanstack/store": "^0.11.2"

package/skills/app-hotkeys/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: app-hotkeys
+description: >-
+  Use when an app built with TanStack Hotkeys needs a keyboard shortcut cheat
+  sheet or help dialog, a command palette whose commands may have shortcuts, a
+  settings screen where users rebind, unbind, or reset shortcuts, recording the
+  shortcut a user presses, conflict checks between shortcuts, or saving custom
+  shortcuts to storage.
+metadata:
+  purpose: >-
+    Declare every shortcut once with defineAppHotkeys, then build cheat sheets,
+    rebinding, conflict checks, and persistence from those declarations instead
+    of a parallel shortcut registry.
+  type: core
+  library: '@tanstack/hotkeys'
+  library_version: '0.16.0'
+sources:
+  - src/app-hotkeys.ts
+  - src/hotkey-recorder.ts
+  - src/conflicts.ts
+  - TanStack/hotkeys:docs/framework/react/guides/app-hotkeys.md
+  - TanStack/hotkeys:docs/framework/react/guides/cheat-sheet-ui-helpers.md
+  - TanStack/hotkeys:docs/framework/react/guides/custom-hotkey-recording.md
+  - 'TanStack/hotkeys:packages/react-hotkeys/tests/skills/shortcut-settings/**'
+requires:
+  - hotkeys-core
+---
+
+# App hotkeys
+
+This skill builds on `hotkeys-core`. The adapter skill's app hotkeys reference shows the wiring in your framework.
+
+App hotkeys are the library's shortcut catalog. Use them instead of a separate shortcut config, context, or hand-written cheat sheet. One module declares every shortcut. The root provider holds the user's custom hotkeys. Components register the declared app hotkeys with their callbacks. Plain hotkeys with `meta` are enough when a list only needs what is mounted right now.
+
+```ts
+import { defineAppHotkeys } from '@tanstack/hotkeys'
+
+export const appHotkeys = defineAppHotkeys({
+  'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save' }, scope: 'document' },
+  'comment.post': {
+    hotkey: 'Mod+S',
+    meta: { name: 'Post comment' },
+    scope: 'comments',
+  },
+  'theme.toggle': { hotkey: null, meta: { name: 'Toggle theme' } },
+})
+```
+
+Augment `Register` in the adapter module you import from, such as `declare module '@tanstack/react-hotkeys' { interface Register { appHotkeys: typeof appHotkeys } }`, to type ids. Lit, Alpine, and Ember have no provider: call `provideAppHotkeys(appHotkeys, options)` once at startup.
+
+## Pitfalls
+
+- **Register the app hotkey, not its value.** Pass `appHotkeys['doc.save']`. Passing `.hotkey` registers the declared default, so the user's rebinding never applies, and the list reports the shortcut as `'inactive'`.
+- **The provider reads `customHotkeys` once.** When saved shortcuts load asynchronously, render the provider after they arrive, or key it by user. Change shortcuts afterwards through the adapter's custom hotkeys API, not by updating the prop.
+- **Save what `onCustomHotkeysChange` receives.** It holds only the shortcuts the user changed, so users still get new defaults. Saving every effective hotkey freezes today's defaults into their data.
+- **Ids are a storage contract.** Saved data is keyed by id, and unknown ids are dropped with a warning, so renaming an id discards users' customizations.
+- **`setCustomHotkey` returns conflicts and changes nothing when there are any.** Check the result before reporting success, or reject the key press earlier by calling `findConflicts` in the recorder's `validate`.
+- **Declare scopes on app hotkeys that share keys.** An app hotkey without a scope, or in `'global'`, conflicts with every other app hotkey on the same keys, so rebinding is rejected.
+- **Conflict checks treat physical and logical bindings as different.** A recorded `Mod+[KeyP]` doesn't conflict with a declared `Mod+P`, although Command+P runs both. Declaring rebindable defaults in the recorder's form, such as `Mod+[KeyP]`, makes them comparable.
+- **A cheat sheet dialog usually gets an exclusive scope.** Register the hotkey that opened it inside the dialog too, so the same keys close it.
+
+When building the "press a new shortcut" control, read [recording](references/recording.md).

package/skills/app-hotkeys/references/recording.md

@@ -0,0 +1,9 @@
+# Recording a shortcut
+
+Use the adapter's recorder instead of a `keydown` listener that builds a string. The recorder already handles the hard parts:
+
+- It pauses registered hotkeys while recording, so pressing `Mod+S` to record it doesn't save. Leave your hotkeys enabled.
+- It records `Mod` rather than Command or Control, and key positions such as `Mod+[KeyS]`, so Option+S records `Alt+[KeyS]` instead of `ß`. Save the recorded value as it is; `formatForDisplay` hides the brackets.
+- Escape cancels. Backspace or Delete removes the last step, or with nothing recorded calls `onClear`, which changes nothing on its own: decide whether clearing unbinds (`setCustomHotkey(id, null)`) or resets (`resetCustomHotkey(id)`).
+- With `maxSteps: Infinity`, the user can record a sequence, which commits on Enter or after `idleTimeoutMs`.
+- `detectConflicts: true` checks only hotkeys registered right now. For app hotkeys, call `findConflicts(id, hotkey)` in `validate` and return a message to reject; a rejected recording keeps listening.

package/skills/hotkeys-core/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: hotkeys-core
+description: >-
+  Use when adding, fixing, or reviewing keyboard shortcuts with TanStack
+  Hotkeys: replacing keydown listeners or another shortcut library, deciding
+  when a hotkey works (enabled, scopes, targets), dialogs that own the
+  keyboard, sequences, or testing hotkeys. Load the framework adapter's skill
+  with it.
+metadata:
+  purpose: >-
+    Framework-neutral rules for TanStack Hotkeys: the work the library already
+    does, how hotkeys turn on and off, and the pitfalls that don't surface as
+    errors.
+  type: core
+  library: '@tanstack/hotkeys'
+  library_version: '0.16.0'
+sources:
+  - src/hotkey-manager.ts
+  - src/match.ts
+  - TanStack/hotkeys:docs/guides/sensible-defaults.md
+  - TanStack/hotkeys:docs/framework/react/guides/hotkeys.md
+  - TanStack/hotkeys:docs/framework/react/guides/sequences.md
+  - TanStack/hotkeys:docs/framework/react/guides/hotkeys-provider-and-scopes.md
+  - 'TanStack/hotkeys:packages/react-hotkeys/tests/skills/editor-shortcuts/**'
+---
+
+# TanStack Hotkeys
+
+The library owns the keyboard. Register every shortcut with your framework adapter's hotkey API, such as `useHotkey`, `createHotkey`, `injectHotkey`, or `@hotkey`, in the component that owns the action. Import everything from the adapter package; it re-exports `@tanstack/hotkeys`. The adapter's skill covers its bindings.
+
+## Use the library instead of rebuilding it
+
+| Instead of                                                            | Use                                                                                                                                           |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| A `keydown` listener that checks `event.key`, `metaKey`, or `ctrlKey` | A registered hotkey such as `'Mod+S'`. Inside a widget's own key handler, `matchesKeyboardEvent(event, 'Mod+Enter')`.                         |
+| `isMac` checks and `⌘`/`Ctrl` label maps                              | `Mod` in the hotkey, and `formatForDisplay(hotkey)` for labels                                                                                |
+| Skipping events from text fields, calling `preventDefault`            | The defaults: single keys and Shift/Alt chords are skipped while typing, `Mod` chords and `Escape` still fire, and matched keys are prevented |
+| A shortcut registry, service, context, or wrapper hook                | The adapter API, called where each action lives. For one list of every shortcut, load `@tanstack/hotkeys#app-hotkeys`.                        |
+| A "shortcuts enabled" flag or topmost-dialog tracking                 | Scopes, with `exclusive` for dialogs                                                                                                          |
+| A hand-written shortcut list for a help dialog                        | `meta: { name }` and the adapter's registrations list, or app hotkeys                                                                         |
+| `keydown`/`keyup` state that tracks held keys                         | The adapter's held-key and hint APIs                                                                                                          |
+| Capturing the next key press for a settings screen                    | The adapter's recorder                                                                                                                        |
+
+A workaround loses what the library tracks: scopes stop suspending it, recorders stop pausing it, devtools stop listing it, and layout and platform handling disappear.
+
+## Turn hotkeys on and off
+
+Use the first mechanism that fits:
+
+1. **Lifetime.** A hotkey registered in a component exists while that component is mounted. A dialog's `Escape` belongs in the dialog.
+2. **`enabled`.** A condition inside a mounted component.
+3. **Scope.** A group that turns on and off together, such as a dialog, pane, or tab. An `exclusive` scope suspends every other scope, including global hotkeys, while it is active.
+4. **`target`.** Only while focus is inside one element, which must be focusable (`tabindex="0"`).
+
+When nesting scopes, stacking dialogs, or keeping some hotkeys working during an exclusive scope, read [scopes](references/scopes.md).
+
+## Pitfalls
+
+- **A disabled hotkey doesn't block the browser.** With `enabled: false`, `Mod+S` opens the Save Page dialog. Add `preventDefault: 'always'` to keep the action blocked while the hotkey can't fire, whether it's disabled or its scope is off. Skip it for hotkeys turned off to give the key back to the browser, such as `Mod+C`, `Mod+Z`, `Tab`, or single keys behind a user's off switch. Don't keep the hotkey enabled and return early from the callback; the hotkey would also stay `active` in app hotkey lists and show its hint.
+- **Modifiers match exactly.** `ArrowDown` never fires while Shift is held, so register `Shift+ArrowDown` instead of checking `event.shiftKey`. Shift that a symbol needs is the exception: `?` matches Shift+/.
+- **Chords repeat while held.** Set `requireReset: true` on toggles, or holding the keys flickers them.
+- **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.
+- **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.
+
+When writing tests for hotkeys, read [testing](references/testing.md).
+
+## API discovery
+
+Read the installed declarations for exact signatures: the adapter's `dist/*.d.ts`, then the core's `hotkey.types.d.ts` (hotkey strings) and `hotkey-manager.d.ts` (`HotkeyOptions`). With pnpm, the core package sits beside the adapter: `ls "$(realpath node_modules/@tanstack/react-hotkeys)/../hotkeys/dist"`, using your adapter's name.

package/skills/hotkeys-core/references/scopes.md

@@ -0,0 +1,13 @@
+# Scopes
+
+- A scope is a name, not an instance. Two mounted providers with the same scope share it, and it stays active until both are gone.
+- Hotkeys outside every scoped provider are in `'global'`, which is always active unless an exclusive scope suspends it.
+- When hotkeys in two active scopes match the same key, a nested scope beats the scopes around it; otherwise the most recently activated scope wins. Only the winning scope's hotkeys run.
+- The same hotkey in two scopes is not a duplicate, so there's no conflict warning.
+- An `exclusive` scope suspends every other scope except scopes nested in it and those in `exclusive: { allow: ['global'] }`. With several exclusive scopes active, the one with the highest precedence owns the keyboard, so a dialog opened from a dialog suspends the first until it closes.
+- A provider with `enabled: false` turns off its scope and every scope nested in it while staying mounted, for tabs and panes that stay rendered.
+- A hotkey's `scope` option, or an app hotkey's declared `scope`, overrides the provider's.
+- Scopes follow the component tree, not the DOM, so a portaled dialog keeps its scope.
+- The hotkey that opens an exclusive dialog is suspended with the rest of the page. To close the dialog with the same keys, register that hotkey inside the dialog too.
+- To show which scope owns the keyboard, use the adapter's scope state API, such as `useHotkeyScopesState()` in React. Don't subscribe to `manager.scopes` by hand.
+- To list only hotkeys that are on, filter the adapter's registrations by `status === 'active'`. `'suspended'` means the hotkey's scope is inactive or suspended, and `'disabled'` means `enabled: false`.

package/skills/hotkeys-core/references/testing.md

@@ -0,0 +1,7 @@
+# Testing hotkeys
+
+- **Set the platform.** Test DOMs don't report a real platform (happy-dom on macOS detects `windows`), so `Mod` changes meaning between machines. Pass `platform: 'mac'` in the provider's `defaultOptions.hotkey`, or on the hotkey.
+- **Reset between tests.** Call `HotkeyManager.resetInstance()`, plus `KeyStateTracker.resetInstance()` for held-key tests, in `afterEach`. Registrations and scope activations otherwise outlive a test that fails before unmounting.
+- **Dispatch real events.** Use `new KeyboardEvent('keydown', { key: 's', code: 'KeyS', metaKey: true, bubbles: true, cancelable: true })`. Physical bindings such as `[KeyS]` match only `code`. Check `event.defaultPrevented` to assert the browser action was blocked.
+- **Dispatch where focus is.** For a hotkey with a `target`, or to test typing in a field, focus the element and dispatch on it with `bubbles: true`.
+- **Repeats and sequences.** `repeat: true` simulates holding a key; it fires chords again unless they set `requireReset`, and it never advances a sequence. Use fake timers to test a sequence's `timeout` (1000 ms by default).