@tanstack/hotkeys 0.19.0 → 0.21.0

package/dist/_app-hotkeys-factory.d.ts

@@ -0,0 +1,5 @@
+import { AppHotkeys, AppHotkeysStore, AppHotkeysStoreOptions } from "./app-hotkeys.js";
+//#region src/_app-hotkeys-factory.d.ts
+/** Creates the store for app hotkeys from `defineAppHotkeys`. */
+export declare function createAppHotkeysStore<T extends AppHotkeys>(appHotkeys: T, options: AppHotkeysStoreOptions<T>): AppHotkeysStore<T>;
+//#endregion

package/dist/_app-hotkeys-factory.js

@@ -0,0 +1,13 @@
+//#region src/_app-hotkeys-factory.ts
+let factory;
+function setAppHotkeysStoreFactory(create) {
+	factory = create;
+}
+/** Creates the store for app hotkeys from `defineAppHotkeys`. */
+function createAppHotkeysStore(appHotkeys, options) {
+	if (!factory) throw new Error("[hotkeys] App hotkeys must come from defineAppHotkeys.");
+	return factory(appHotkeys, options);
+}
+
+//#endregion
+export { createAppHotkeysStore, setAppHotkeysStoreFactory };

package/dist/_keyboard-event.js

@@ -34,9 +34,8 @@ function codeToLogicalKey(code) {
 	if (/^Key[A-Z]$/i.test(code)) return code.slice(3).toUpperCase();
 	if (/^Digit[0-9]$/i.test(code)) return code.slice(5);
 	if (/^Numpad[0-9]$/i.test(code)) return code.slice(6);
-	const punctuation = PUNCTUATION_CODE_MAP[code];
-	if (punctuation) return punctuation;
-	return {
+	if (Object.hasOwn(PUNCTUATION_CODE_MAP, code)) return PUNCTUATION_CODE_MAP[code];
+	const named = {
 		NumpadAdd: "+",
 		NumpadSubtract: "-",
 		NumpadMultiply: "*",
@@ -44,7 +43,8 @@ function codeToLogicalKey(code) {
 		NumpadDecimal: ".",
 		NumpadEnter: "Enter",
 		Space: "Space"
-	}[code];
+	};
+	return Object.hasOwn(named, code) ? named[code] : void 0;
 }
 /**
 * Whether AltGr changed what a key typed, as in AltGr+Q typing `@`. False when
@@ -102,6 +102,14 @@ function keysEqual(left, right) {
 function assertLogicalKey(key) {
 	if (/^\[.*\]$/s.test(key.trim())) throw new Error("Logical key must not contain a bracketed physical code. Use the code field instead.");
 }
+/**
+* Whether a key is written like a key the library knows: one character,
+* F1-F24, or a capitalized name such as `Escape`. Key names are
+* case-sensitive, so `escape` and `f1` don't qualify.
+*/
+function isKeyNameShape(key) {
+	return /^(?:.|F(?:[1-9]|1\d|2[0-4])|[A-Z][a-z][A-Za-z\d]*)$/su.test(key);
+}
 
 //#endregion
-export { altGraphTypedCharacter, assertLogicalKey, codeToLogicalKey, isAsciiLetter, isCodeName, isLatinLetter, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts };
+export { altGraphTypedCharacter, assertLogicalKey, codeToLogicalKey, isAsciiLetter, isCodeName, isKeyNameShape, isLatinLetter, isPrintableKey, keysEqual, modifierAlias, normalizeKeyboardEvent, physicalCodeOf, splitChordParts };

package/dist/_named-keys.js

@@ -60,6 +60,26 @@ const LOGICAL_ONLY_NAMED_KEYS = [
 	"Hankaku",
 	"ZenkakuHankaku"
 ];
+/** Arrow, Home/End, and PageUp/PageDown keys. */
+const NAVIGATION_KEY_NAMES = [
+	"ArrowUp",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"Home",
+	"End",
+	"PageUp",
+	"PageDown"
+];
+/** Editing and special keys. */
+const EDITING_KEY_NAMES = [
+	"Enter",
+	"Escape",
+	"Space",
+	"Tab",
+	"Backspace",
+	"Delete"
+];
 
 //#endregion
-export { LOGICAL_ONLY_NAMED_KEYS, SHARED_NAMED_KEYS };
+export { EDITING_KEY_NAMES, LOGICAL_ONLY_NAMED_KEYS, NAVIGATION_KEY_NAMES, SHARED_NAMED_KEYS };

package/dist/_registration.d.ts

@@ -0,0 +1,14 @@
+//#region src/_registration.d.ts
+/**
+ * Merges option layers left to right. A key set to `undefined` keeps the
+ * earlier layer's value, so an unset option keeps its default. Getters are
+ * read once.
+ */
+export declare function definedOptions<T extends object>(...layers: ReadonlyArray<object | undefined>): T;
+/**
+ * Merges options over defaults for an API whose `setOptions` treats
+ * `undefined` as "clear". An unset option takes its default, or stays
+ * `undefined` to clear an earlier value when it has no default.
+ */
+export declare function withDefaults<T extends object>(defaults: object | undefined, options: T | undefined): T;
+//#endregion

package/dist/_registration.js

@@ -16,6 +16,37 @@ const defaultHotkeyOptions = {
 	scope: GLOBAL_SCOPE
 };
 /**
+* Merges option layers left to right. A key set to `undefined` keeps the
+* earlier layer's value, so an unset option keeps its default. Getters are
+* read once.
+*/
+function definedOptions(...layers) {
+	const result = {};
+	for (const layer of layers) {
+		if (!layer) continue;
+		for (const key of Object.keys(layer)) {
+			const value = layer[key];
+			if (value !== void 0) result[key] = value;
+		}
+	}
+	return result;
+}
+/**
+* Merges options over defaults for an API whose `setOptions` treats
+* `undefined` as "clear". An unset option takes its default, or stays
+* `undefined` to clear an earlier value when it has no default.
+*/
+function withDefaults(defaults, options) {
+	return {
+		...options,
+		...definedOptions(defaults, options)
+	};
+}
+/** Whether a parsed chord has a key. An empty one would match key-less events. */
+function chordHasKey(chord) {
+	return chord.code !== void 0 || !!chord.key;
+}
+/**
 * Resolves `ignoreInputs: 'auto'` from the hotkey (the first step of a sequence).
 * Ctrl/Meta shortcuts and Escape fire in inputs; single keys and Shift/Alt combos are ignored.
 */
@@ -35,7 +66,7 @@ function getDefaultIgnoreInputs(parsedChord) {
 function handleConflict(conflictingId, keyDisplay, conflictBehavior, unregister) {
 	if (conflictBehavior === "allow") return;
 	if (conflictBehavior === "warn") {
-		console.warn(`'${keyDisplay}' is already registered. Multiple handlers may be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
+		if (process.env.NODE_ENV !== "production") console.warn(`'${keyDisplay}' is already registered. Multiple handlers may be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
 		return;
 	}
 	if (conflictBehavior === "error") throw new Error(`'${keyDisplay}' is already registered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to allow multiple registrations.`);
@@ -50,4 +81,4 @@ function optionsEqual(left, right) {
 }
 
 //#endregion
-export { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual };
+export { GLOBAL_SCOPE, chordHasKey, defaultHotkeyOptions, definedOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual, withDefaults };

package/dist/_store.d.ts

@@ -0,0 +1,14 @@
+import { Store as Store$1 } from "./vendor/@tanstack/store/dist/store.js";
+//#region src/_store.d.ts
+/**
+ * The part of TanStack Store's `Store` that TanStack Hotkeys uses. Its stores
+ * work with TanStack Store's framework adapters, such as `useSelector` from
+ * `@tanstack/react-store`.
+ */
+export type Store<T> = Pick<Store$1<T>, 'state' | 'get' | 'setState' | 'subscribe'>;
+/**
+ * Creates a store. Listeners run synchronously after each change, and an
+ * update to an equal value (by `Object.is`) notifies no one.
+ */
+export declare function createStore<T>(initialState: T): Store<T>;
+//#endregion

package/dist/_store.js

@@ -0,0 +1,43 @@
+//#region src/_store.ts
+const queue = /* @__PURE__ */ new Set();
+function notify(listeners) {
+	for (const listener of listeners) queue.add(listener);
+	for (const listener of queue) {
+		queue.delete(listener);
+		listener();
+	}
+}
+/**
+* Creates a store. Listeners run synchronously after each change, and an
+* update to an equal value (by `Object.is`) notifies no one.
+*/
+function createStore(initialState) {
+	let state = initialState;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		get state() {
+			return state;
+		},
+		get: () => state,
+		setState(updater) {
+			const next = updater(state);
+			if (Object.is(state, next)) return;
+			state = next;
+			notify(listeners);
+		},
+		subscribe(observerOrFn) {
+			const listener = () => {
+				if (typeof observerOrFn === "function") observerOrFn(state);
+				else observerOrFn.next?.(state);
+			};
+			listeners.add(listener);
+			return { unsubscribe() {
+				listeners.delete(listener);
+				queue.delete(listener);
+			} };
+		}
+	};
+}
+
+//#endregion
+export { createStore };

package/dist/adapter.d.ts

@@ -1,6 +1,9 @@
+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 { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
+import { definedOptions, withDefaults } from "./_registration.js";
 //#region src/adapter.d.ts
 /**
  * A hotkey and its callback, with optional per-binding options. Chords accept
@@ -14,6 +17,11 @@ export type HotkeyDefinition = {
   hotkey: RegisterableHotkeySequence;
   callback: HotkeyCallback;
   options?: HotkeySequenceOptions;
+} | {
+  /** No hotkey. Registers nothing. */
+  hotkey: null | undefined;
+  callback: HotkeyCallback;
+  options?: HotkeyChordOptions & HotkeySequenceOptions;
 };
 /** Options shared by every definition. Each option applies only to the kinds that support it. */
 export type HotkeyBindingsCommonOptions = HotkeyChordOptions & HotkeySequenceOptions;
@@ -21,7 +29,8 @@ export type HotkeyBindingsCommonOptions = HotkeyChordOptions & HotkeySequenceOpt
 export declare function createHotkeyBindings(): {
   /**
    * Registers new definitions, updates existing ones in place, and removes
-   * stale ones. Definitions with an empty sequence or a null target are skipped.
+   * stale ones. Definitions with no hotkey (undefined, null, empty string, or
+   * empty sequence) or a null target are skipped.
    */
   update(definitions: ReadonlyArray<HotkeyDefinition>, commonOptions?: HotkeyBindingsCommonOptions): void;
   destroy(): void;
@@ -77,9 +86,10 @@ export type AdapterHotkeyDefinition<TTarget> = {
 } | {
   /**
    * A hotkey whose kind is not known statically, such as user data typed
-   * `Hotkey`. Accepts only shared options.
+   * `Hotkey`. Accepts only shared options. `undefined`, `null`, and `''`
+   * register nothing, for an optional shortcut.
    */
-  hotkey: RegisterableHotkey;
+  hotkey: RegisterableHotkey | null | undefined;
   callback: HotkeyCallback;
   options?: AdapterHotkeyOptions<TTarget>;
 };
@@ -94,7 +104,7 @@ export interface PrepareHotkeyDefinitionsOptions<TTarget> {
   /**
    * Resolves a framework target, such as a ref. Return `undefined` for the
    * document or `null` to skip registration until the target exists.
-   * Without it, targets pass through and `null` means document.
+   * Without it, targets pass through, so `null` skips registration.
    */
   resolveTarget?: (target: TTarget) => Target | null | undefined;
 }
@@ -160,4 +170,5 @@ export declare function getHotkeysProviderScopeKey(options: {
  * Returns a function that releases the activation.
  */
 export declare function activateHotkeysProviderScope(key: string): () => void;
-//#endregion
+//#endregion
+export { type Store, createAppHotkeysStore, createStore, definedOptions, withDefaults };

package/dist/adapter.js

@@ -1,7 +1,9 @@
 import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, normalizeHotkey } from "./parse.js";
-import { defaultHotkeyOptions } from "./_registration.js";
+import { isHotkeySequence, normalizeHotkey, parseHotkey } from "./parse.js";
+import { chordHasKey, defaultHotkeyOptions, definedOptions, withDefaults } from "./_registration.js";
+import { createStore } from "./_store.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
+import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
 import { getAppHotkeyRegistrationOptions, isAppHotkey, resolveAppHotkey } from "./app-hotkeys.js";
 
 //#region src/adapter.ts
@@ -11,24 +13,23 @@ function createHotkeyBindings() {
 	return {
 		/**
 		* Registers new definitions, updates existing ones in place, and removes
-		* stale ones. Definitions with an empty sequence or a null target are skipped.
+		* stale ones. Definitions with no hotkey (undefined, null, empty string, or
+		* empty sequence) or a null target are skipped.
 		*/
 		update(definitions, commonOptions = {}) {
 			const prepared = [];
 			definitions.forEach((definition, index) => {
-				const merged = {
-					...commonOptions,
-					...definition.options
-				};
+				const merged = definedOptions(commonOptions, definition.options);
 				const options = {
 					...defaultHotkeyOptions,
 					...merged,
-					ignoreInputs: merged.ignoreInputs ?? "auto",
 					target: "target" in merged ? merged.target ?? null : typeof document === "undefined" ? null : document,
 					platform: merged.platform ?? detectPlatform()
 				};
-				if (!options.target || isHotkeySequence(definition.hotkey) && definition.hotkey.length === 0) return;
-				const hotkey = normalizeHotkey(definition.hotkey, options.platform);
+				if (!options.target || !definition.hotkey || isHotkeySequence(definition.hotkey) && definition.hotkey.length === 0) return;
+				const parsed = parseHotkey(definition.hotkey, options.platform);
+				if (!(Array.isArray(parsed) ? parsed : [parsed]).every(chordHasKey)) return;
+				const hotkey = normalizeHotkey(parsed, options.platform);
 				if (isHotkeySequence(hotkey)) delete options.requireReset;
 				else delete options.timeout;
 				prepared.push({
@@ -87,13 +88,8 @@ function prepareHotkeyDefinitions(definitions, options = {}) {
 			declared = getAppHotkeyRegistrationOptions(appHotkey);
 			hotkey = appHotkey.hotkey ?? [];
 		}
-		const { target, ...merged } = {
-			...options.defaults,
-			...declared,
-			...options.commonOptions,
-			...definition.options
-		};
-		const resolved = target === void 0 ? void 0 : options.resolveTarget ? options.resolveTarget(target) : target ?? void 0;
+		const { target, ...merged } = definedOptions(options.defaults, declared, options.commonOptions, definition.options);
+		const resolved = target === void 0 ? void 0 : options.resolveTarget ? options.resolveTarget(target) : target;
 		return {
 			hotkey,
 			callback: definition.callback,
@@ -134,14 +130,10 @@ function subscribePublishedAppHotkeys(onChange) {
 function mergeHotkeysProviderDefaults(parent, own, scope) {
 	return {
 		hotkey: {
-			...parent?.hotkey,
-			...own?.hotkey,
+			...definedOptions(parent?.hotkey, own?.hotkey),
 			...scope && { scope }
 		},
-		hotkeyRecorder: {
-			...parent?.hotkeyRecorder,
-			...own?.hotkeyRecorder
-		}
+		hotkeyRecorder: definedOptions(parent?.hotkeyRecorder, own?.hotkeyRecorder)
 	};
 }
 /**
@@ -171,4 +163,4 @@ function activateHotkeysProviderScope(key) {
 }
 
 //#endregion
-export { activateHotkeysProviderScope, createHotkeyBindings, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys };
+export { activateHotkeysProviderScope, createAppHotkeysStore, createHotkeyBindings, createStore, definedOptions, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys, withDefaults };

package/dist/app-hotkeys.d.ts

@@ -1,6 +1,6 @@
+import { Store } from "./_store.js";
 import { Hotkey, HotkeyChord, HotkeyMeta, HotkeySequence } from "./hotkey.types.js";
 import { HotkeyChordOptions, HotkeyRegistrationView, HotkeySequenceOptions } from "./hotkey-manager.js";
-import { Store } from "@tanstack/store";
 //#region src/app-hotkeys.d.ts
 type Platform = 'mac' | 'windows' | 'linux';
 type DeclaredOptionKeys = 'capture' | 'conflictBehavior' | 'eventType' | 'ignoreInputs' | 'preventDefault' | 'stopPropagation';
@@ -135,7 +135,13 @@ export interface AppHotkeysState<T extends AppHotkeys = AppHotkeys> {
 }
 /** Options for `AppHotkeysStore`. */
 export interface AppHotkeysStoreOptions<T extends AppHotkeys = AppHotkeys> {
-  /** Starting custom hotkeys, such as saved data. Invalid entries are ignored with a warning. */
+  /**
+   * The user's saved custom hotkeys. Invalid entries are ignored with a
+   * warning. Passing a different value to `setOptions` later, such as data
+   * that finished loading or another user's data, replaces the current
+   * custom hotkeys. `undefined` leaves them unchanged; a change to `null`
+   * clears them.
+   */
   customHotkeys?: CustomHotkeys<T> | null;
   /** Called with the custom hotkeys after every change, ready to save. */
   onCustomHotkeysChange?: (customHotkeys: CustomHotkeys<T>) => void;
@@ -165,8 +171,17 @@ export declare class AppHotkeysStore<T extends AppHotkeys = AppHotkeys> {
   get appHotkeys(): T;
   /** The user's hotkeys that differ from the defaults. */
   get customHotkeys(): CustomHotkeys<T>;
-  /** Updates callbacks and other options without resetting custom hotkeys. */
-  setOptions(options: Omit<AppHotkeysStoreOptions<T>, 'customHotkeys'>): void;
+  /**
+   * Updates options. Providers call it with their props on every update.
+   *
+   * When `customHotkeys` differs from the value last passed in, it replaces
+   * the current custom hotkeys. An equal value, such as the same saved data
+   * parsed again, keeps changes the user made since. `undefined` changes
+   * nothing, such as while saved data loads; `null` clears them, such as on
+   * sign-out. Replacing does not call `onCustomHotkeysChange`, because the
+   * data came from the app.
+   */
+  setOptions(options: AppHotkeysStoreOptions<T>): void;
   /**
    * Replaces the declarations, for example after hot module replacement.
    * Custom hotkeys for ids that still exist are kept.

package/dist/app-hotkeys.js

@@ -1,10 +1,11 @@
 import { detectPlatform } from "./platform.js";
 import { isHotkeySequence, simplifyHotkey } from "./parse.js";
 import { validateHotkey } from "./validate.js";
-import { areHotkeysEqual } from "./match.js";
 import { GLOBAL_SCOPE } from "./_registration.js";
+import { areHotkeysEqual } from "./match.js";
+import { createStore } from "./_store.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
-import { Store } from "@tanstack/store";
+import { setAppHotkeysStoreFactory } from "./_app-hotkeys-factory.js";
 
 //#region src/app-hotkeys.ts
 /**
@@ -22,6 +23,7 @@ import { Store } from "@tanstack/store";
 * ```
 */
 function defineAppHotkeys(definitions) {
+	setAppHotkeysStoreFactory((appHotkeys, options) => new AppHotkeysStore(appHotkeys, options));
 	const result = {};
 	for (const [id, input] of Object.entries(definitions)) {
 		const hotkey = input.hotkey === null ? null : simplifyHotkey(input.hotkey);
@@ -73,19 +75,44 @@ function sanitizeCustomHotkeys(appHotkeys, saved) {
 	if (typeof saved !== "object" || saved === null) return result;
 	for (const [id, value] of Object.entries(saved)) {
 		if (value === void 0) continue;
-		if (!(id in appHotkeys)) {
-			console.warn(`Ignoring custom hotkey for unknown app hotkey '${id}'`);
+		if (!Object.hasOwn(appHotkeys, id)) {
+			if (process.env.NODE_ENV !== "production") console.warn(`Ignoring custom hotkey for unknown app hotkey '${id}'`);
 			continue;
 		}
 		const hotkey = parseCustomHotkey(value);
 		if (hotkey === void 0) {
-			console.warn(`Ignoring invalid custom hotkey for app hotkey '${id}':`, value);
+			if (process.env.NODE_ENV !== "production") console.warn(`Ignoring invalid custom hotkey for app hotkey '${id}':`, value);
 			continue;
 		}
 		result[id] = hotkey;
 	}
 	return result;
 }
+/** Whether two saved values hold the same data. Nothing saved equals `{}`. */
+function sameSavedValue(left, right) {
+	if (Object.is(left, right)) return true;
+	if (Array.isArray(left) || Array.isArray(right)) return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((step, i) => Object.is(step, right[i]));
+	if (typeof left !== "object" || typeof right !== "object") return false;
+	if (left === null || right === null) return false;
+	const keys = Object.keys(left);
+	return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && sameSavedValue(left[key], right[key]));
+}
+/** Copies saved custom hotkeys, so later changes made in place are detected. */
+function copySavedCustomHotkeys(saved) {
+	if (typeof saved !== "object" || saved === null) return saved;
+	const copy = {};
+	for (const [id, value] of Object.entries(saved)) copy[id] = Array.isArray(value) ? [...value] : value;
+	return copy;
+}
+/** Whether two saved custom hotkeys objects hold the same data. */
+function sameSavedCustomHotkeys(left, right) {
+	return sameSavedValue(left === void 0 ? {} : left, right === void 0 ? {} : right);
+}
+/** Whether two sanitized custom hotkeys objects bind the same hotkeys. */
+function sameCustomHotkeys(left, right, platform) {
+	const keys = Object.keys(left);
+	return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && hotkeysEqual(left[key] ?? null, right[key] ?? null, platform));
+}
 /** Whether two app hotkeys can apply at the same time. */
 function scopesOverlap(a, b) {
 	const left = a.scope ?? "global";
@@ -119,11 +146,14 @@ var AppHotkeysStore = class {
 	store;
 	#declarations;
 	#options;
+	/** The `customHotkeys` option last passed in, compared by value. */
+	#savedCustomHotkeys;
 	constructor(appHotkeys, options = {}) {
 		this.#declarations = appHotkeys;
 		this.#options = options;
+		this.#savedCustomHotkeys = copySavedCustomHotkeys(options.customHotkeys);
 		const customHotkeys = sanitizeCustomHotkeys(appHotkeys, options.customHotkeys);
-		this.store = new Store({
+		this.store = createStore({
 			appHotkeys: applyCustomHotkeys(appHotkeys, customHotkeys),
 			customHotkeys
 		});
@@ -139,12 +169,31 @@ var AppHotkeysStore = class {
 	get customHotkeys() {
 		return this.store.state.customHotkeys;
 	}
-	/** Updates callbacks and other options without resetting custom hotkeys. */
+	/**
+	* Updates options. Providers call it with their props on every update.
+	*
+	* When `customHotkeys` differs from the value last passed in, it replaces
+	* the current custom hotkeys. An equal value, such as the same saved data
+	* parsed again, keeps changes the user made since. `undefined` changes
+	* nothing, such as while saved data loads; `null` clears them, such as on
+	* sign-out. Replacing does not call `onCustomHotkeysChange`, because the
+	* data came from the app.
+	*/
 	setOptions(options) {
+		const { customHotkeys, ...rest } = options;
 		this.#options = {
 			...this.#options,
-			...options
+			...rest
 		};
+		if (customHotkeys === void 0) return;
+		if (sameSavedCustomHotkeys(customHotkeys, this.#savedCustomHotkeys)) return;
+		this.#savedCustomHotkeys = copySavedCustomHotkeys(customHotkeys);
+		const next = sanitizeCustomHotkeys(this.#declarations, customHotkeys);
+		if (sameCustomHotkeys(next, this.store.state.customHotkeys, this.#platform)) return;
+		this.store.setState(() => ({
+			appHotkeys: applyCustomHotkeys(this.#declarations, next),
+			customHotkeys: next
+		}));
 	}
 	/**
 	* Replaces the declarations, for example after hot module replacement.
@@ -161,7 +210,8 @@ var AppHotkeysStore = class {
 	}
 	/** Effective app hotkey for an id, or `undefined` when it is not declared. */
 	get(id) {
-		return this.store.state.appHotkeys[id];
+		const { appHotkeys } = this.store.state;
+		return Object.hasOwn(appHotkeys, id) ? appHotkeys[id] : void 0;
 	}
 	/**
 	* Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
@@ -169,7 +219,7 @@ var AppHotkeysStore = class {
 	* hotkeys are equal or one sequence starts with the other.
 	*/
 	findConflicts(id, hotkey) {
-		const self = this.store.state.appHotkeys[id];
+		const self = this.get(id);
 		if (!self) return [];
 		const candidate = simplifyHotkey(hotkey);
 		return Object.values(this.store.state.appHotkeys).filter((other) => other.id !== id && other.hotkey !== null && scopesOverlap(self, other) && hotkeysOverlap(candidate, other.hotkey, this.#platform));
@@ -181,9 +231,9 @@ var AppHotkeysStore = class {
 	* @returns Conflicting app hotkeys. When any exist, nothing changes.
 	*/
 	setCustomHotkey(id, hotkey) {
-		const appHotkey = this.store.state.appHotkeys[id];
+		const appHotkey = this.get(id);
 		if (!appHotkey) {
-			console.warn(`Cannot set a custom hotkey for unknown app hotkey '${id}'`);
+			if (process.env.NODE_ENV !== "production") console.warn(`Cannot set a custom hotkey for unknown app hotkey '${id}'`);
 			return [];
 		}
 		const next = hotkey === null ? null : simplifyHotkey(hotkey);

package/dist/constants.d.ts

@@ -107,9 +107,9 @@ export declare const PUNCTUATION_CODE_MAP: Record<string, string>;
 /**
  * Set of all valid non-modifier keys.
  *
- * This is the union of all key type sets (letters, numbers, function keys, navigation,
- * editing, and punctuation). Used primarily for validation to check if a key string
- * is recognized and will have type-safe autocomplete support.
+ * This is the union of all key type sets (letters, numbers, function keys,
+ * navigation, editing, punctuation, and other named keys): every key with
+ * type-safe autocomplete support.
  *
  * @see {@link LETTER_KEYS}
  * @see {@link NUMBER_KEYS}
@@ -122,16 +122,17 @@ export declare const ALL_KEYS: Set<"CapsLock" | "ContextMenu" | "Convert" | "Kan
 /** Whether a key is a single Unicode letter, such as `'a'` or `'é'`. */
 export declare function isSingleLetterKey(key: string): boolean;
 /**
- * Normalizes a key name to its canonical form.
+ * Normalizes a key name from a `KeyboardEvent` or a hotkey: single letters
+ * become uppercase, and the space character becomes `Space`. Other names are
+ * returned as written, because key names are case-sensitive.
  *
- * @param key - The key name to normalize (can be an alias, lowercase, etc.)
+ * @param key - The key name to normalize
  * @returns The canonical key name
  *
  * @example
  * ```ts
- * normalizeKeyName('esc') // 'Escape'
  * normalizeKeyName('a') // 'A'
- * normalizeKeyName('f1') // 'F1'
+ * normalizeKeyName(' ') // 'Space'
  * normalizeKeyName('ArrowUp') // 'ArrowUp' (already canonical)
  * ```
  */