@tanstack/hotkeys 0.11.0 → 0.12.0

package/dist/adapter.d.ts

@@ -1,27 +1,116 @@
-import { HotkeyCallback, RegisterableHotkey } from "./hotkey.types.js";
-import { HotkeyOptions } from "./hotkey-manager.js";
-import { HotkeySequence, SequenceOptions } from "./sequence-manager.js";
+import { HotkeyCallback, HotkeyChord, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
+import { HotkeyChordOptions, HotkeyOptions, HotkeySequenceOptions, Target } from "./hotkey-manager.js";
+import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
 //#region src/adapter.d.ts
-/** A hotkey and its callback, with optional per-binding options. */
-export interface HotkeyDefinition {
-  hotkey: RegisterableHotkey;
+/**
+ * A hotkey and its callback, with optional per-binding options. Chords accept
+ * `requireReset`; sequences accept `timeout`.
+ */
+export type HotkeyDefinition = {
+  hotkey: RegisterableHotkeyChord;
   callback: HotkeyCallback;
-  options?: HotkeyOptions;
-}
-/** A sequence and its callback, with optional per-binding options. */
-export interface HotkeySequenceDefinition {
-  sequence: HotkeySequence;
+  options?: HotkeyChordOptions;
+} | {
+  hotkey: HotkeySequence;
   callback: HotkeyCallback;
-  options?: SequenceOptions;
-}
+  options?: HotkeySequenceOptions;
+};
+/** 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(): {
-  update(definitions: Array<HotkeyDefinition>, commonOptions?: HotkeyOptions): void;
-  destroy: () => void;
+  /**
+   * Registers new definitions, updates existing ones in place, and removes
+   * stale ones. Definitions with an empty sequence or a null target are skipped.
+   */
+  update(definitions: ReadonlyArray<HotkeyDefinition>, commonOptions?: HotkeyBindingsCommonOptions): void;
+  destroy(): void;
 };
-/** Reconciles sequence bindings; empty sequences and explicit null targets are skipped. */
-export declare function createHotkeySequenceBindings(): {
-  update(definitions: Array<HotkeySequenceDefinition>, commonOptions?: SequenceOptions): void;
-  destroy: () => void;
+/** Options with a framework-specific target, such as a ref. */
+export type WithTarget<TOptions, TTarget> = Omit<TOptions, 'target' | 'appHotkeyId'> & {
+  /** The element to listen on. Defaults to document. */
+  target?: TTarget;
 };
+/** Options shared by chords and sequences, with a framework target. */
+export type AdapterHotkeyOptions<TTarget> = WithTarget<HotkeyOptions, TTarget>;
+/** Options for a chord such as `'Mod+S'`, with a framework target. */
+export type AdapterChordOptions<TTarget> = WithTarget<HotkeyChordOptions, TTarget>;
+/** Options for a sequence such as `['G', 'G']`, with a framework target. */
+export type AdapterSequenceOptions<TTarget> = WithTarget<HotkeySequenceOptions, TTarget>;
+/** Options applied to every hotkey, such as defaults. Each applies to the kinds that support it. */
+export type AdapterCommonOptions<TTarget> = AdapterChordOptions<TTarget> & AdapterSequenceOptions<TTarget>;
+/** Chord options for chords, sequence options for sequences. */
+export type AdapterOptionsFor<T extends RegisterableHotkey, TTarget> = [T] extends [never] ? AdapterCommonOptions<TTarget> : T extends readonly [unknown] ? AdapterChordOptions<TTarget> : T extends ReadonlyArray<unknown> ? AdapterSequenceOptions<TTarget> : AdapterChordOptions<TTarget>;
+/**
+ * Call-site options for an app hotkey. `meta` comes from the declaration.
+ * Kind-specific options follow the declared default: `requireReset` for a
+ * chord, `timeout` for a sequence, both for an app hotkey without a default.
+ * If the user rebinds it to the other kind, options for the old kind no
+ * longer apply.
+ */
+export type AdapterAppHotkeyOptions<T extends AppHotkey, TTarget> = Omit<[T['defaultHotkey']] extends [HotkeySequence] ? AdapterSequenceOptions<TTarget> : [T['defaultHotkey']] extends [HotkeyChord] ? AdapterChordOptions<TTarget> : AdapterCommonOptions<TTarget>, 'meta'>;
+/**
+ * One hotkey and its callback for adapter APIs such as `useHotkeys`. Chords
+ * accept `requireReset`; sequences accept `timeout`; hotkeys of unknown kind
+ * accept only shared options.
+ */
+export type AdapterHotkeyDefinition<TTarget> = {
+  /** A chord string such as `'Mod+S'`, or a RawHotkey object */
+  hotkey: RegisterableHotkeyChord;
+  /** The function to call when the hotkey is pressed */
+  callback: HotkeyCallback;
+  /** Per-hotkey options (merged on top of common options) */
+  options?: AdapterChordOptions<TTarget>;
+} | {
+  /** A sequence such as `['G', 'G']` */
+  hotkey: HotkeySequence;
+  callback: HotkeyCallback;
+  options?: AdapterSequenceOptions<TTarget>;
+} | {
+  /**
+   * An app hotkey from `defineAppHotkeys`. Kind-specific options apply
+   * only while its effective hotkey has that kind.
+   */
+  hotkey: AppHotkey;
+  callback: HotkeyCallback;
+  options?: Omit<AdapterCommonOptions<TTarget>, 'meta'>;
+} | {
+  /**
+   * A hotkey whose kind is not known statically, such as user data typed
+   * `Hotkey`. Accepts only shared options.
+   */
+  hotkey: RegisterableHotkey;
+  callback: HotkeyCallback;
+  options?: AdapterHotkeyOptions<TTarget>;
+};
+/** Context for `prepareHotkeyDefinitions`. */
+export interface PrepareHotkeyDefinitionsOptions<TTarget> {
+  /** The provider's app hotkeys store, so app hotkeys use custom hotkeys. */
+  appHotkeysStore?: AppHotkeysStore | null;
+  /** Provider defaults, applied first. */
+  defaults?: AdapterCommonOptions<TTarget>;
+  /** Options for every definition, applied after app hotkey declarations. */
+  commonOptions?: AdapterCommonOptions<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.
+   */
+  resolveTarget?: (target: TTarget) => Target | null | undefined;
+}
+/**
+ * Converts adapter definitions into `createHotkeyBindings` definitions.
+ * Options merge in this order: defaults, app hotkey declaration, common
+ * options, per-definition options. App hotkeys resolve their effective hotkey
+ * from the store, and an unbound app hotkey keeps its position but registers
+ * nothing.
+ */
+export declare function prepareHotkeyDefinitions<TTarget>(definitions: ReadonlyArray<AdapterHotkeyDefinition<TTarget>>, options?: PrepareHotkeyDefinitionsOptions<TTarget>): Array<HotkeyDefinition>;
+/**
+ * Calls `onChange` when the store published with `publishAppHotkeysStore` or
+ * `provideAppHotkeys` changes, or when its app hotkeys or custom hotkeys
+ * change. For adapters that resolve app hotkeys without a provider. Returns an
+ * unsubscribe function.
+ */
+export declare function subscribePublishedAppHotkeys(onChange: () => void): () => void;
 //#endregion

package/dist/adapter.js

@@ -1,20 +1,51 @@
 import { detectPlatform } from "./platform.js";
-import { normalizeRegisterableHotkey, parseHotkey } from "./parse.js";
+import { isHotkeySequence, normalizeRegisterableHotkey, parseHotkey } from "./parse.js";
 import { defaultHotkeyOptions, getDefaultIgnoreInputs } from "./_registration.js";
 import { getHotkeyManager } from "./hotkey-manager.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, getSequenceManager } from "./sequence-manager.js";
+import { getAppHotkeyRegistrationOptions, isAppHotkey, resolveAppHotkey } from "./app-hotkeys.js";
 
 //#region src/adapter.ts
-function createBindings() {
+/** Reconciles adapter registrations while retaining handles for option updates. */
+function createHotkeyBindings() {
 	const registrations = /* @__PURE__ */ new Map();
 	return {
-		update(bindings) {
-			const keys = new Set(bindings.map((binding) => binding.key));
+		/**
+		* Registers new definitions, updates existing ones in place, and removes
+		* stale ones. Definitions with an empty sequence or a null target are skipped.
+		*/
+		update(definitions, commonOptions = {}) {
+			const prepared = [];
+			definitions.forEach((definition, index) => {
+				const merged = {
+					...commonOptions,
+					...definition.options
+				};
+				const options = {
+					...defaultHotkeyOptions,
+					...merged,
+					ignoreInputs: merged.ignoreInputs,
+					target: "target" in merged ? merged.target ?? null : typeof document === "undefined" ? null : document,
+					platform: merged.platform ?? detectPlatform()
+				};
+				if (!options.target || isHotkeySequence(definition.hotkey) && definition.hotkey.length === 0) return;
+				const hotkey = normalizeRegisterableHotkey(definition.hotkey, options.platform);
+				const first = isHotkeySequence(hotkey) ? hotkey[0] : hotkey;
+				options.ignoreInputs ??= getDefaultIgnoreInputs(parseHotkey(first, options.platform));
+				if (isHotkeySequence(hotkey)) delete options.requireReset;
+				else delete options.timeout;
+				prepared.push({
+					key: `${index}:${isHotkeySequence(hotkey) ? hotkey.join(" ") : hotkey}`,
+					callback: definition.callback,
+					options,
+					register: () => getHotkeyManager().register(hotkey, definition.callback, options)
+				});
+			});
+			const keys = new Set(prepared.map((binding) => binding.key));
 			for (const [key, registration] of registrations) if (!keys.has(key)) {
 				registration.handle.unregister();
 				registrations.delete(key);
 			}
-			for (const binding of bindings) {
+			for (const binding of prepared) {
 				const previous = registrations.get(binding.key);
 				const { target, platform } = binding.options;
 				if (previous?.handle.isActive && previous.target === target && previous.platform === platform) {
@@ -42,68 +73,62 @@ function createBindings() {
 		}
 	};
 }
-function resolveOptions(options) {
-	return {
-		...defaultHotkeyOptions,
-		requireReset: false,
-		...options,
-		ignoreInputs: options.ignoreInputs,
-		target: "target" in options ? options.target ?? null : typeof document === "undefined" ? null : document,
-		platform: options.platform ?? detectPlatform()
-	};
+/**
+* Converts adapter definitions into `createHotkeyBindings` definitions.
+* Options merge in this order: defaults, app hotkey declaration, common
+* options, per-definition options. App hotkeys resolve their effective hotkey
+* from the store, and an unbound app hotkey keeps its position but registers
+* nothing.
+*/
+function prepareHotkeyDefinitions(definitions, options = {}) {
+	return definitions.map((definition) => {
+		let hotkey = definition.hotkey;
+		let declared = {};
+		if (isAppHotkey(hotkey)) {
+			const appHotkey = resolveAppHotkey(hotkey, options.appHotkeysStore);
+			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;
+		return {
+			hotkey,
+			callback: definition.callback,
+			options: resolved === void 0 ? merged : {
+				...merged,
+				target: resolved
+			}
+		};
+	});
 }
-/** Reconciles adapter registrations while retaining handles for option updates. */
-function createHotkeyBindings() {
-	const bindings = createBindings();
-	return {
-		update(definitions, commonOptions = {}) {
-			const prepared = [];
-			definitions.forEach((definition, index) => {
-				const options = resolveOptions({
-					...commonOptions,
-					...definition.options
-				});
-				if (!options.target) return;
-				const hotkey = normalizeRegisterableHotkey(definition.hotkey, options.platform);
-				options.ignoreInputs ??= getDefaultIgnoreInputs(parseHotkey(hotkey, options.platform));
-				prepared.push({
-					key: `${index}:${hotkey}`,
-					callback: definition.callback,
-					options,
-					register: () => getHotkeyManager().register(hotkey, definition.callback, options)
-				});
-			});
-			bindings.update(prepared);
-		},
-		destroy: bindings.destroy
+/**
+* Calls `onChange` when the store published with `publishAppHotkeysStore` or
+* `provideAppHotkeys` changes, or when its app hotkeys or custom hotkeys
+* change. For adapters that resolve app hotkeys without a provider. Returns an
+* unsubscribe function.
+*/
+function subscribePublishedAppHotkeys(onChange) {
+	const slot = getHotkeyManager().appHotkeys;
+	let inner;
+	const follow = () => {
+		inner?.unsubscribe();
+		inner = slot.state?.store.subscribe(onChange);
 	};
-}
-/** Reconciles sequence bindings; empty sequences and explicit null targets are skipped. */
-function createHotkeySequenceBindings() {
-	const bindings = createBindings();
-	return {
-		update(definitions, commonOptions = {}) {
-			const prepared = [];
-			definitions.forEach((definition, index) => {
-				const options = resolveOptions({
-					timeout: DEFAULT_SEQUENCE_TIMEOUT,
-					...commonOptions,
-					...definition.options
-				});
-				if (!options.target || definition.sequence.length === 0) return;
-				options.ignoreInputs ??= getDefaultIgnoreInputs(parseHotkey(definition.sequence[0], options.platform));
-				prepared.push({
-					key: `${index}:${JSON.stringify(definition.sequence)}`,
-					callback: definition.callback,
-					options,
-					register: () => getSequenceManager().register(definition.sequence, definition.callback, options)
-				});
-			});
-			bindings.update(prepared);
-		},
-		destroy: bindings.destroy
+	follow();
+	const outer = slot.subscribe(() => {
+		follow();
+		onChange();
+	});
+	return () => {
+		outer.unsubscribe();
+		inner?.unsubscribe();
 	};
 }
 
 //#endregion
-export { createHotkeyBindings, createHotkeySequenceBindings };
+export { createHotkeyBindings, prepareHotkeyDefinitions, subscribePublishedAppHotkeys };

package/dist/app-hotkeys.d.ts

@@ -0,0 +1,239 @@
+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 = 'conflictBehavior' | 'eventType' | 'ignoreInputs' | 'preventDefault' | 'stopPropagation';
+/** Declared options for an app hotkey whose default is a chord. */
+export type AppHotkeyChordOptions = Pick<HotkeyChordOptions, DeclaredOptionKeys | 'requireReset'>;
+/** Declared options for an app hotkey whose default is a sequence. */
+export type AppHotkeySequenceOptions = Pick<HotkeySequenceOptions, DeclaredOptionKeys | 'timeout'>;
+/** Every declared option. Kind-specific options apply only while the effective hotkey has that kind. */
+export type AppHotkeyOptions = AppHotkeyChordOptions & AppHotkeySequenceOptions;
+/** One declaration passed to `defineAppHotkeys`. */
+export interface AppHotkeyInput {
+  /** Default hotkey: a chord, a sequence, or `null` for an action without a default. */
+  hotkey: Hotkey | null;
+  /** Display metadata for cheat sheets and settings screens. */
+  meta?: HotkeyMeta;
+  /**
+   * Label for where this hotkey applies, such as `'editor'`. App hotkeys with
+   * different contexts may share a hotkey; one without a context conflicts with
+   * any app hotkey that shares its hotkey. It does not affect matching.
+   */
+  context?: string;
+  /**
+   * Options that describe the hotkey itself. Chord defaults accept
+   * `requireReset`; sequence defaults accept `timeout`.
+   */
+  options?: AppHotkeyOptions;
+}
+/**
+ * A declared app hotkey. It never holds a callback: register it with
+ * `useHotkey(appHotkey, callback)` or the equivalent adapter API.
+ *
+ * `TDefault` is the kind of the declared default (`HotkeyChord`,
+ * `HotkeySequence`, or `null`). Adapters use it to type kind-specific options.
+ */
+export interface AppHotkey<TId extends string = string, TDefault extends HotkeyChord | HotkeySequence | null = HotkeyChord | HotkeySequence | null> {
+  /** Brand that distinguishes app hotkeys from raw hotkey objects. */
+  readonly '~appHotkey': true;
+  /** Stable id. Saved custom hotkeys are keyed by this value. */
+  readonly id: TId;
+  /** Effective hotkey: the user's custom hotkey, or the default. `null` means unbound. */
+  readonly hotkey: Hotkey | null;
+  /** Hotkey declared in `defineAppHotkeys`. */
+  readonly defaultHotkey: TDefault;
+  readonly meta?: HotkeyMeta;
+  readonly context?: string;
+  readonly options?: AppHotkeyOptions;
+}
+/** A map of app hotkeys keyed by id. */
+export type AppHotkeys = Readonly<Record<string, AppHotkey>>;
+type AllowedOptions<THotkey> = THotkey extends HotkeySequence ? AppHotkeySequenceOptions : THotkey extends null ? AppHotkeyOptions : AppHotkeyChordOptions;
+type StrictOptions<TOptions, TAllowed> = TOptions extends object ? { [P in Exclude<keyof TOptions, keyof TAllowed>]: never; } & TAllowed : TAllowed;
+/** Rejects options that do not apply to each declaration's default kind. */
+type ValidatedAppHotkeyInputs<T> = { [K in keyof T]: T[K] extends {
+  hotkey: infer THotkey;
+} ? Omit<T[K], 'options'> & {
+  options?: StrictOptions<T[K] extends {
+    options: infer TOptions;
+  } ? TOptions : {}, AllowedOptions<THotkey>>;
+} : never; };
+/** The kind of a declared default hotkey; a one-step sequence is a chord. */
+export type AppHotkeyDefaultKind<THotkey> = THotkey extends null ? null : THotkey extends readonly [unknown] ? HotkeyChord : THotkey extends ReadonlyArray<unknown> ? HotkeySequence : HotkeyChord;
+/** The app hotkeys returned by `defineAppHotkeys` for a declaration object. */
+export type DefinedAppHotkeys<T extends Record<string, AppHotkeyInput>> = { readonly [K in keyof T & string]: AppHotkey<K, AppHotkeyDefaultKind<T[K]['hotkey']>>; };
+/**
+ * Register your app hotkeys to type `useAppHotkeys()` and `CustomHotkeys`.
+ *
+ * @example
+ * ```ts
+ * declare module '@tanstack/react-hotkeys' {
+ *   interface Register {
+ *     appHotkeys: typeof appHotkeys
+ *   }
+ * }
+ * ```
+ */
+export interface Register {}
+/** The app hotkeys type from `Register`, or a generic map when none is registered. */
+export type RegisteredAppHotkeys = Register extends {
+  appHotkeys: infer T extends AppHotkeys;
+} ? T : AppHotkeys;
+/** Ids of the registered app hotkeys. */
+export type AppHotkeyId = keyof RegisteredAppHotkeys & string;
+/**
+ * The user's hotkeys that differ from the declared defaults, keyed by app
+ * hotkey id. This is the shape to save. `null` means the user unbound it.
+ */
+export type CustomHotkeys<T extends AppHotkeys = RegisteredAppHotkeys> = { -readonly [K in keyof T]?: Hotkey | null; };
+/**
+ * Declares every app hotkey up front, without registering any, so cheat
+ * sheets and settings screens can list hotkeys whose components have not
+ * mounted. Pass the result to `HotkeysProvider` as `appHotkeys`.
+ *
+ * @example
+ * ```ts
+ * export const appHotkeys = defineAppHotkeys({
+ *   'doc.save': { hotkey: 'Mod+S', meta: { name: 'Save', group: 'Document' } },
+ *   'nav.home': { hotkey: ['G', 'H'], meta: { name: 'Go home' }, options: { timeout: 800 } },
+ *   'palette.open': { hotkey: null, meta: { name: 'Command palette' } },
+ * })
+ * ```
+ */
+export declare function defineAppHotkeys<const T extends Record<string, AppHotkeyInput>>(definitions: T & ValidatedAppHotkeyInputs<T>): DefinedAppHotkeys<T>;
+/** Whether a value is an app hotkey created by `defineAppHotkeys`. */
+export declare function isAppHotkey(value: unknown): value is AppHotkey;
+/** Whether an app hotkey's effective hotkey differs from its default. */
+export declare function isCustomHotkey(appHotkey: AppHotkey, platform?: Platform): boolean;
+/**
+ * Status of an app hotkey in the running app.
+ * - `'active'`: at least one enabled registration
+ * - `'disabled'`: registered, but every registration has `enabled: false`
+ * - `'inactive'`: has a hotkey, but nothing has registered it
+ * - `'unbound'`: no hotkey assigned
+ */
+export type AppHotkeyStatus = 'active' | 'disabled' | 'inactive' | 'unbound';
+/** One row of an app hotkey cheat sheet. */
+export interface AppHotkeyListItem<T extends AppHotkey = AppHotkey> {
+  appHotkey: T;
+  status: AppHotkeyStatus;
+  /** Whether the effective hotkey differs from the declared default. */
+  isCustom: boolean;
+  /** Live registrations of this app hotkey (for example, one per list row). */
+  registrations: Array<HotkeyRegistrationView>;
+}
+/** State of an `AppHotkeysStore`. */
+export interface AppHotkeysState<T extends AppHotkeys = AppHotkeys> {
+  /** Effective app hotkeys: declarations with custom hotkeys applied. */
+  appHotkeys: T;
+  /** The user's hotkeys that differ from the defaults. */
+  customHotkeys: CustomHotkeys<T>;
+}
+/** Options for `AppHotkeysStore`. */
+export interface AppHotkeysStoreOptions<T extends AppHotkeys = AppHotkeys> {
+  /** Starting custom hotkeys, such as saved data. Invalid entries are ignored with a warning. */
+  customHotkeys?: CustomHotkeys<T> | null;
+  /** Called with the custom hotkeys after every change, ready to save. */
+  onCustomHotkeysChange?: (customHotkeys: CustomHotkeys<T>) => void;
+  /** Platform used to compare hotkeys. Defaults to detection. */
+  platform?: Platform;
+}
+/**
+ * Holds declared app hotkeys and the user's custom hotkeys. Framework
+ * providers create one and expose it through hooks; devtools read it from
+ * `HotkeyManager.appHotkeys`.
+ *
+ * @example
+ * ```ts
+ * const store = new AppHotkeysStore(appHotkeys, {
+ *   customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+ *   onCustomHotkeysChange: (custom) =>
+ *     localStorage.setItem('hotkeys', JSON.stringify(custom)),
+ * })
+ * store.setCustomHotkey('doc.save', 'Mod+Shift+S')
+ * ```
+ */
+export declare class AppHotkeysStore<T extends AppHotkeys = AppHotkeys> {
+  #private;
+  readonly store: Store<AppHotkeysState<T>>;
+  constructor(appHotkeys: T, options?: AppHotkeysStoreOptions<T>);
+  /** Effective app hotkeys. */
+  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;
+  /**
+   * Replaces the declarations, for example after hot module replacement.
+   * Custom hotkeys for ids that still exist are kept.
+   */
+  setAppHotkeys(appHotkeys: T): void;
+  /** Effective app hotkey for an id, or `undefined` when it is not declared. */
+  get(id: string): AppHotkey | undefined;
+  /**
+   * Other app hotkeys that would collide if `id` used `hotkey`. App hotkeys
+   * collide when their contexts match or either has no context, and their
+   * hotkeys are equal or one sequence starts with the other.
+   */
+  findConflicts(id: keyof T & string, hotkey: Hotkey): Array<AppHotkey>;
+  /**
+   * Sets the user's hotkey for an app hotkey. `null` unbinds it. A hotkey
+   * equal to the default removes the customization.
+   *
+   * @returns Conflicting app hotkeys. When any exist, nothing changes.
+   */
+  setCustomHotkey(id: keyof T & string, hotkey: Hotkey | null): Array<AppHotkey>;
+  /** Restores the default hotkey for an app hotkey. */
+  resetCustomHotkey(id: keyof T & string): void;
+  /** Restores every default hotkey. */
+  resetCustomHotkeys(): void;
+  /**
+   * Joins app hotkeys with live registrations, in declaration order.
+   * Adapters call this with the manager's registration views.
+   */
+  getList(registrations: Iterable<HotkeyRegistrationView>): Array<AppHotkeyListItem<T[keyof T]>>;
+}
+/**
+ * Returns the provider's version of an app hotkey, so custom hotkeys apply
+ * even when a component imports the declaration directly. Falls back to the
+ * given app hotkey when no store declares it.
+ */
+export declare function resolveAppHotkey(appHotkey: AppHotkey, store: AppHotkeysStore | null | undefined): AppHotkey;
+/**
+ * Options that adapters pass to the manager when registering an app hotkey:
+ * declared options, meta, and the app hotkey id. The manager drops options
+ * that do not apply to the effective hotkey's kind.
+ */
+export declare function getAppHotkeyRegistrationOptions(appHotkey: AppHotkey): AppHotkeyOptions & {
+  meta?: HotkeyMeta;
+  appHotkeyId: string;
+};
+/**
+ * Publishes a provider's store on the HotkeyManager so devtools can list
+ * declared hotkeys. Returns a cleanup function that unpublishes it if it is
+ * still the published store.
+ */
+export declare function publishAppHotkeysStore(store: AppHotkeysStore): () => void;
+/**
+ * Creates an app hotkeys store and publishes it on the HotkeyManager, for
+ * adapters without a provider component (such as Lit and Alpine). Hotkey
+ * APIs in those adapters resolve app hotkeys and custom hotkeys from the
+ * published store. Call it once at startup. Returns the store and a function
+ * that unpublishes it.
+ *
+ * @example
+ * ```ts
+ * provideAppHotkeys(appHotkeys, {
+ *   customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+ *   onCustomHotkeysChange: (custom) =>
+ *     localStorage.setItem('hotkeys', JSON.stringify(custom)),
+ * })
+ * ```
+ */
+export declare function provideAppHotkeys<T extends AppHotkeys>(appHotkeys: T, options?: AppHotkeysStoreOptions<T>): {
+  store: AppHotkeysStore<T>;
+  dispose: () => void;
+};
+//#endregion