@tanstack/lit-hotkeys 0.13.1 → 0.15.0

package/README.md

@@ -67,6 +67,9 @@ Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objec
 > [!NOTE]
 > You may know **TanStack Hotkeys** by our adapter names, too!
 >
+> - [**Alpine Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/alpine/quick-start)
+> - [**Ember Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/ember/quick-start)
+> - [**Octane Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/octane/quick-start)
 > - [**React Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/react/react-hotkeys)
 > - [**Preact Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/preact/preact-hotkeys)
 > - [**Solid Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/solid/reference)

package/dist/controllers/_app-hotkeys.js

@@ -0,0 +1,11 @@
+import { getHotkeyManager } from "@tanstack/hotkeys";
+import { subscribePublishedAppHotkeys as subscribeAppHotkeys } from "@tanstack/hotkeys/adapter";
+
+//#region src/controllers/_app-hotkeys.ts
+/** The app hotkeys store published by `provideAppHotkeys`, if any. */
+function getAppHotkeysStore() {
+	return getHotkeyManager().appHotkeys.state;
+}
+
+//#endregion
+export { getAppHotkeysStore, subscribeAppHotkeys };

package/dist/controllers/app-hotkeys.d.ts

@@ -0,0 +1,48 @@
+import { AppHotkey, AppHotkeyListItem, CustomHotkeys, Hotkey, RegisteredAppHotkeys } from "@tanstack/hotkeys";
+import { ReactiveController, ReactiveControllerHost } from "lit";
+//#region src/controllers/app-hotkeys.d.ts
+/**
+ * A Lit ReactiveController for app hotkeys provided with `provideAppHotkeys`:
+ * the effective app hotkeys, a cheat sheet list with live status, and the
+ * user's custom hotkeys. Requests an update when any of them change.
+ *
+ * @example
+ * ```ts
+ * class CheatSheet extends LitElement {
+ *   private app = new AppHotkeysController(this)
+ *
+ *   render() {
+ *     return html`<ul>
+ *       ${this.app.list.map(
+ *         ({ appHotkey, status }) => html`<li>${appHotkey.meta?.name}: ${status}</li>`,
+ *       )}
+ *     </ul>`
+ *   }
+ * }
+ * ```
+ */
+export declare class AppHotkeysController implements ReactiveController {
+  private _host;
+  private _unsubscribe;
+  constructor(_host: ReactiveControllerHost);
+  /** Effective app hotkeys, typed by `Register`. */
+  get appHotkeys(): RegisteredAppHotkeys;
+  /** Every app hotkey with its live status, in declaration order. */
+  get list(): Array<AppHotkeyListItem<RegisteredAppHotkeys[keyof RegisteredAppHotkeys]>>;
+  /** The user's hotkeys that differ from the defaults. */
+  get customHotkeys(): CustomHotkeys;
+  /**
+   * Sets the user's hotkey for an app hotkey. `null` unbinds it.
+   * Returns conflicting app hotkeys; when any exist, nothing changes.
+   */
+  setCustomHotkey(id: keyof RegisteredAppHotkeys & string, hotkey: Hotkey | null): Array<AppHotkey>;
+  /** Restores the default hotkey for an app hotkey. */
+  resetCustomHotkey(id: keyof RegisteredAppHotkeys & string): void;
+  /** Restores every default hotkey. */
+  resetCustomHotkeys(): void;
+  /** Other app hotkeys that would collide if `id` used `hotkey`. */
+  findConflicts(id: keyof RegisteredAppHotkeys & string, hotkey: Hotkey): Array<AppHotkey>;
+  hostConnected(): void;
+  hostDisconnected(): void;
+}
+//#endregion

package/dist/controllers/app-hotkeys.js

@@ -0,0 +1,84 @@
+import { getAppHotkeysStore, subscribeAppHotkeys } from "./_app-hotkeys.js";
+import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
+
+//#region src/controllers/app-hotkeys.ts
+function requireStore() {
+	const store = getAppHotkeysStore();
+	if (!store) throw new Error("AppHotkeysController requires provideAppHotkeys()");
+	return store;
+}
+/**
+* A Lit ReactiveController for app hotkeys provided with `provideAppHotkeys`:
+* the effective app hotkeys, a cheat sheet list with live status, and the
+* user's custom hotkeys. Requests an update when any of them change.
+*
+* @example
+* ```ts
+* class CheatSheet extends LitElement {
+*   private app = new AppHotkeysController(this)
+*
+*   render() {
+*     return html`<ul>
+*       ${this.app.list.map(
+*         ({ appHotkey, status }) => html`<li>${appHotkey.meta?.name}: ${status}</li>`,
+*       )}
+*     </ul>`
+*   }
+* }
+* ```
+*/
+var AppHotkeysController = class {
+	_host;
+	_unsubscribe;
+	constructor(_host) {
+		this._host = _host;
+		this._host.addController(this);
+	}
+	/** Effective app hotkeys, typed by `Register`. */
+	get appHotkeys() {
+		return requireStore().appHotkeys;
+	}
+	/** Every app hotkey with its live status, in declaration order. */
+	get list() {
+		return requireStore().getList(Array.from(getHotkeyManager().registrations.state.values()).map(toHotkeyRegistrationView));
+	}
+	/** The user's hotkeys that differ from the defaults. */
+	get customHotkeys() {
+		return requireStore().customHotkeys;
+	}
+	/**
+	* Sets the user's hotkey for an app hotkey. `null` unbinds it.
+	* Returns conflicting app hotkeys; when any exist, nothing changes.
+	*/
+	setCustomHotkey(id, hotkey) {
+		return requireStore().setCustomHotkey(id, hotkey);
+	}
+	/** Restores the default hotkey for an app hotkey. */
+	resetCustomHotkey(id) {
+		requireStore().resetCustomHotkey(id);
+	}
+	/** Restores every default hotkey. */
+	resetCustomHotkeys() {
+		requireStore().resetCustomHotkeys();
+	}
+	/** Other app hotkeys that would collide if `id` used `hotkey`. */
+	findConflicts(id, hotkey) {
+		return requireStore().findConflicts(id, hotkey);
+	}
+	hostConnected() {
+		const update = () => this._host.requestUpdate();
+		const unsubscribeAppHotkeys = subscribeAppHotkeys(update);
+		const registrations = getHotkeyManager().registrations.subscribe(update);
+		this._unsubscribe = () => {
+			unsubscribeAppHotkeys();
+			registrations.unsubscribe();
+		};
+	}
+	hostDisconnected() {
+		this._unsubscribe?.();
+		this._unsubscribe = void 0;
+	}
+};
+
+//#endregion
+export { AppHotkeysController };

package/dist/controllers/hotkey-hint.d.ts

@@ -1,4 +1,4 @@
-import { HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
 import { ReactiveController, ReactiveControllerHost } from "lit";
 //#region src/controllers/hotkey-hint.d.ts
 /** Modifier hint controller. Getter arguments can read reactive host properties. */
@@ -9,7 +9,7 @@ export declare class HotkeyHintController implements ReactiveController {
   private unsubscribe?;
   private visible;
   /** Attaches to the host; getter arguments can read changing reactive properties. */
-  constructor(host: ReactiveControllerHost, hotkey: RegisterableHotkey | (() => RegisterableHotkey), options?: HeldModifierOptions | (() => HeldModifierOptions));
+  constructor(host: ReactiveControllerHost, hotkey: RegisterableHotkey | AppHotkey | (() => RegisterableHotkey | AppHotkey), options?: HeldModifierOptions | (() => HeldModifierOptions));
   /** Current visibility; combine with the action’s enabled state when rendering. */
   get value(): boolean;
   /** Subscribes on connection and requests renders only when hint visibility changes. */

package/dist/controllers/hotkey-hint.js

@@ -1,4 +1,5 @@
-import { getKeyStateTracker, matchesHeldModifiers } from "@tanstack/hotkeys";
+import { getAppHotkeysStore, subscribeAppHotkeys } from "./_app-hotkeys.js";
+import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 
 //#region src/controllers/hotkey-hint.ts
 /** Modifier hint controller. Getter arguments can read reactive host properties. */
@@ -22,10 +23,15 @@ var HotkeyHintController = class {
 	/** Subscribes on connection and requests renders only when hint visibility changes. */
 	hostConnected() {
 		this.update();
-		const subscription = getKeyStateTracker().store.subscribe(() => {
+		const refresh = () => {
 			if (this.update()) this.host.requestUpdate();
-		});
-		this.unsubscribe = () => subscription.unsubscribe();
+		};
+		const subscription = getKeyStateTracker().store.subscribe(refresh);
+		const unsubscribeAppHotkeys = subscribeAppHotkeys(refresh);
+		this.unsubscribe = () => {
+			subscription.unsubscribe();
+			unsubscribeAppHotkeys();
+		};
 	}
 	/** Re-evaluates getter arguments when host properties trigger an update. */
 	hostUpdate() {
@@ -39,7 +45,9 @@ var HotkeyHintController = class {
 	}
 	/** Recomputes visibility and reports whether the host needs another render. */
 	update() {
-		const next = matchesHeldModifiers(typeof this.hotkey === "function" ? this.hotkey() : this.hotkey, getKeyStateTracker().store.state.heldKeys, typeof this.options === "function" ? this.options() : this.options);
+		const value = typeof this.hotkey === "function" ? this.hotkey() : this.hotkey;
+		const hotkey = isAppHotkey(value) ? resolveAppHotkey(value, getAppHotkeysStore()).hotkey : value;
+		const next = hotkey !== null && matchesHeldModifiers(hotkey, getKeyStateTracker().store.state.heldKeys, typeof this.options === "function" ? this.options() : this.options);
 		const changed = next !== this.visible;
 		this.visible = next;
 		return changed;

package/dist/controllers/hotkey-recorder.d.ts

@@ -1,12 +1,14 @@
-import { Hotkey, HotkeyRecorderOptions } from "@tanstack/hotkeys";
+import { Hotkey, HotkeyChordRecorderOptions, HotkeyRecorderOptions, HotkeySequence, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import { ReactiveController, ReactiveControllerHost } from "lit";
 //#region src/controllers/hotkey-recorder.d.ts
 /**
  * A Lit ReactiveController that records keyboard shortcuts.
  *
- * Wraps the framework-agnostic `HotkeyRecorder` class, managing all the
- * complexity of capturing keyboard events, converting them to hotkey strings,
- * and handling edge cases like Escape to cancel or Backspace/Delete to clear.
+ * With the default `maxSteps: 1`, the first valid chord is recorded. With a
+ * larger `maxSteps`, each chord adds a step; the recording commits on Enter
+ * (unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+ * `onRecord` receives a chord (one step) or a sequence. Escape cancels;
+ * Backspace/Delete removes the last step or clears.
  *
  * @example
  * ```ts
@@ -41,21 +43,30 @@ export declare class HotkeyRecorderController implements ReactiveController {
   private _options;
   /** The recorder instance. */
   private _recorder;
+  private _optionOverrides;
   /** The unsubscribe function to unsubscribe from the recorder store. */
   private _unsubscribe;
   /** Whether recording is currently active. */
   private _isRecording;
-  /** The currently recorded hotkey (for live preview). */
+  /** The last committed hotkey. */
   private _recordedHotkey;
+  /** Chords recorded so far in a multi-step recording. */
+  private _steps;
   /** Whether recording is currently active. */
   get isRecording(): boolean;
-  /** The currently recorded hotkey (for live preview). */
+  /** The last committed hotkey: a chord, or a sequence of two or more steps. */
   get recordedHotkey(): Hotkey | null;
+  /** Chords recorded so far in a multi-step recording (for live preview). */
+  get steps(): HotkeySequence;
   /**
-   * @param _host - The Lit component that owns this controller.
-   * @param _options - Configuration options for the recorder.
+   * @param host - The Lit component that owns this controller.
+   * @param options - Options or a getter, read during recording.
    */
-  constructor(_host: ReactiveControllerHost, _options: HotkeyRecorderOptions);
+  constructor(host: ReactiveControllerHost, options: HotkeyChordRecorderOptions);
+  constructor(host: ReactiveControllerHost, options: HotkeySequenceRecorderOptions);
+  constructor(host: ReactiveControllerHost, options: () => HotkeySequenceRecorderOptions);
+  constructor(host: ReactiveControllerHost, options: () => HotkeyChordRecorderOptions);
+  constructor(host: ReactiveControllerHost, options: () => HotkeyRecorderOptions);
   /** Subscribes to the recorder store and updates the internal state when changes occur. */
   hostConnected(): void;
   /** Unsubscribes from the recorder store and destroys the recorder instance to prevent memory leaks. */
@@ -68,5 +79,7 @@ export declare class HotkeyRecorderController implements ReactiveController {
   stopRecording(): void;
   /** Cancel recording without saving. */
   cancelRecording(): void;
+  /** Commit the recorded steps now (multi-step recordings). */
+  commitRecording(): void;
 }
 //#endregion

package/dist/controllers/hotkey-recorder.js

@@ -4,9 +4,11 @@ import { HotkeyRecorder } from "@tanstack/hotkeys";
 /**
 * A Lit ReactiveController that records keyboard shortcuts.
 *
-* Wraps the framework-agnostic `HotkeyRecorder` class, managing all the
-* complexity of capturing keyboard events, converting them to hotkey strings,
-* and handling edge cases like Escape to cancel or Backspace/Delete to clear.
+* With the default `maxSteps: 1`, the first valid chord is recorded. With a
+* larger `maxSteps`, each chord adds a step; the recording commits on Enter
+* (unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+* `onRecord` receives a chord (one step) or a sequence. Escape cancels;
+* Backspace/Delete removes the last step or clears.
 *
 * @example
 * ```ts
@@ -41,37 +43,44 @@ var HotkeyRecorderController = class {
 	_options;
 	/** The recorder instance. */
 	_recorder;
+	_optionOverrides = {};
 	/** The unsubscribe function to unsubscribe from the recorder store. */
 	_unsubscribe;
 	/** Whether recording is currently active. */
 	_isRecording = false;
-	/** The currently recorded hotkey (for live preview). */
+	/** The last committed hotkey. */
 	_recordedHotkey = null;
+	/** Chords recorded so far in a multi-step recording. */
+	_steps = [];
 	/** Whether recording is currently active. */
 	get isRecording() {
 		return this._isRecording;
 	}
-	/** The currently recorded hotkey (for live preview). */
+	/** The last committed hotkey: a chord, or a sequence of two or more steps. */
 	get recordedHotkey() {
 		return this._recordedHotkey;
 	}
-	/**
-	* @param _host - The Lit component that owns this controller.
-	* @param _options - Configuration options for the recorder.
-	*/
+	/** Chords recorded so far in a multi-step recording (for live preview). */
+	get steps() {
+		return this._steps;
+	}
 	constructor(_host, _options) {
 		this._host = _host;
 		this._options = _options;
-		this._recorder = new HotkeyRecorder(_options);
+		this._recorder = new HotkeyRecorder(() => ({
+			...typeof this._options === "function" ? this._options() : this._options,
+			...this._optionOverrides
+		}));
 		this._host.addController(this);
 	}
 	/** Subscribes to the recorder store and updates the internal state when changes occur. */
 	hostConnected() {
 		const subscription = this._recorder.store.subscribe(() => {
-			const { isRecording, recordedHotkey } = this._recorder.store.state;
-			if (isRecording !== this._isRecording || recordedHotkey !== this._recordedHotkey) {
+			const { isRecording, recordedHotkey, steps } = this._recorder.store.state;
+			if (isRecording !== this._isRecording || recordedHotkey !== this._recordedHotkey || steps !== this._steps) {
 				this._isRecording = isRecording;
 				this._recordedHotkey = recordedHotkey;
+				this._steps = steps;
 				this._host.requestUpdate();
 			}
 		});
@@ -84,14 +93,14 @@ var HotkeyRecorderController = class {
 		this._recorder.stop();
 		this._isRecording = false;
 		this._recordedHotkey = null;
+		this._steps = [];
 	}
 	/** Updates the recorder options (e.g. callbacks). */
 	setOptions(options) {
-		this._options = {
-			...this._options,
+		this._optionOverrides = {
+			...this._optionOverrides,
 			...options
 		};
-		this._recorder.setOptions(this._options);
 	}
 	/** Start recording a new hotkey. */
 	startRecording() {
@@ -105,6 +114,10 @@ var HotkeyRecorderController = class {
 	cancelRecording() {
 		this._recorder.cancel();
 	}
+	/** Commit the recorded steps now (multi-step recordings). */
+	commitRecording() {
+		this._recorder.commit();
+	}
 };
 
 //#endregion

package/dist/controllers/hotkey-registrations.d.ts

@@ -1,11 +1,10 @@
-import { HotkeyRegistrationView, SequenceRegistrationView } from "@tanstack/hotkeys";
+import { HotkeyRegistrationView } from "@tanstack/hotkeys";
 import { ReactiveController, ReactiveControllerHost } from "lit";
 //#region src/controllers/hotkey-registrations.d.ts
 /**
- * A Lit ReactiveController that tracks all hotkey and sequence registrations.
- *
- * Subscribes to the singleton HotkeyManager and SequenceManager stores and
- * triggers host updates whenever registrations change.
+ * A Lit ReactiveController that reads every hotkey registration, chords and
+ * sequences, from the singleton HotkeyManager and requests an update when
+ * they change. Narrow each view with `kind`.
  *
  * @example
  * ```ts
@@ -13,27 +12,21 @@ import { ReactiveController, ReactiveControllerHost } from "lit";
  *   private registrations = new HotkeyRegistrationsController(this)
  *
  *   render() {
- *     return html`
- *       <ul>
- *         ${this.registrations.hotkeys.map(
- *           (reg) => html`<li>${reg.options.meta?.name ?? reg.hotkey}</li>`,
- *         )}
- *       </ul>
- *     `
+ *     return html`<ul>
+ *       ${this.registrations.hotkeys.map(
+ *         (reg) => html`<li>${reg.options.meta?.name}: ${formatForDisplay(reg.hotkey)}</li>`,
+ *       )}
+ *     </ul>`
  *   }
  * }
  * ```
  */
 export declare class HotkeyRegistrationsController implements ReactiveController {
   private _host;
-  private _unsubscribeHotkeys;
-  private _unsubscribeSequences;
+  private _unsubscribe;
   private _hotkeys;
-  private _sequences;
-  /** All registered hotkeys (public view, no callbacks). */
+  /** Every registration, chords and sequences (public view, no callbacks). */
   get hotkeys(): Array<HotkeyRegistrationView>;
-  /** All registered sequences. */
-  get sequences(): Array<SequenceRegistrationView>;
   constructor(_host: ReactiveControllerHost);
   hostConnected(): void;
   hostDisconnected(): void;

package/dist/controllers/hotkey-registrations.js

@@ -1,11 +1,10 @@
-import { getHotkeyManager, getSequenceManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
+import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
 
 //#region src/controllers/hotkey-registrations.ts
 /**
-* A Lit ReactiveController that tracks all hotkey and sequence registrations.
-*
-* Subscribes to the singleton HotkeyManager and SequenceManager stores and
-* triggers host updates whenever registrations change.
+* A Lit ReactiveController that reads every hotkey registration, chords and
+* sequences, from the singleton HotkeyManager and requests an update when
+* they change. Narrow each view with `kind`.
 *
 * @example
 * ```ts
@@ -13,58 +12,41 @@ import { getHotkeyManager, getSequenceManager, toHotkeyRegistrationView } from "
 *   private registrations = new HotkeyRegistrationsController(this)
 *
 *   render() {
-*     return html`
-*       <ul>
-*         ${this.registrations.hotkeys.map(
-*           (reg) => html`<li>${reg.options.meta?.name ?? reg.hotkey}</li>`,
-*         )}
-*       </ul>
-*     `
+*     return html`<ul>
+*       ${this.registrations.hotkeys.map(
+*         (reg) => html`<li>${reg.options.meta?.name}: ${formatForDisplay(reg.hotkey)}</li>`,
+*       )}
+*     </ul>`
 *   }
 * }
 * ```
 */
 var HotkeyRegistrationsController = class {
 	_host;
-	_unsubscribeHotkeys;
-	_unsubscribeSequences;
+	_unsubscribe;
 	_hotkeys = [];
-	_sequences = [];
-	/** All registered hotkeys (public view, no callbacks). */
+	/** Every registration, chords and sequences (public view, no callbacks). */
 	get hotkeys() {
 		return this._hotkeys;
 	}
-	/** All registered sequences. */
-	get sequences() {
-		return this._sequences;
-	}
 	constructor(_host) {
 		this._host = _host;
 		this._host.addController(this);
 	}
 	hostConnected() {
-		const hotkeyManager = getHotkeyManager();
-		const sequenceManager = getSequenceManager();
-		const hotkeysSub = hotkeyManager.registrations.subscribe(() => {
-			this._hotkeys = Array.from(hotkeyManager.registrations.state.values()).map(toHotkeyRegistrationView);
-			this._host.requestUpdate();
-		});
-		const sequencesSub = sequenceManager.registrations.subscribe(() => {
-			this._sequences = Array.from(sequenceManager.registrations.state.values());
+		const manager = getHotkeyManager();
+		const read = () => Array.from(manager.registrations.state.values()).map(toHotkeyRegistrationView);
+		const subscription = manager.registrations.subscribe(() => {
+			this._hotkeys = read();
 			this._host.requestUpdate();
 		});
-		this._unsubscribeHotkeys = () => hotkeysSub.unsubscribe();
-		this._unsubscribeSequences = () => sequencesSub.unsubscribe();
-		this._hotkeys = Array.from(hotkeyManager.registrations.state.values()).map(toHotkeyRegistrationView);
-		this._sequences = Array.from(sequenceManager.registrations.state.values());
+		this._unsubscribe = () => subscription.unsubscribe();
+		this._hotkeys = read();
 	}
 	hostDisconnected() {
-		this._unsubscribeHotkeys?.();
-		this._unsubscribeSequences?.();
-		this._unsubscribeHotkeys = void 0;
-		this._unsubscribeSequences = void 0;
+		this._unsubscribe?.();
+		this._unsubscribe = void 0;
 		this._hotkeys = [];
-		this._sequences = [];
 	}
 };
 

package/dist/controllers/hotkey.d.ts

@@ -1,18 +1,42 @@
-import { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, RegisterableHotkey, Target } from "@tanstack/hotkeys";
+import { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from "@tanstack/hotkeys/adapter";
 import { ReactiveController, ReactiveControllerHost } from "lit";
 //#region src/controllers/hotkey.d.ts
+/** The element to listen on. A `null` target skips registration until it is set. */
+export type HotkeyControllerTarget = Target | null;
+/** Options shared by chords and sequences. */
+export type HotkeyControllerOptions = AdapterHotkeyOptions<HotkeyControllerTarget>;
+/** Options for a chord such as `'Mod+S'`. */
+export type HotkeyControllerChordOptions = AdapterChordOptions<HotkeyControllerTarget>;
+/** Options for a sequence such as `['G', 'G']`. */
+export type HotkeyControllerSequenceOptions = AdapterSequenceOptions<HotkeyControllerTarget>;
+/** Options for every kind; each applies to the kinds that support it. */
+export type HotkeyControllerCommonOptions = AdapterCommonOptions<HotkeyControllerTarget>;
+/** The options type for a hotkey: chord options for chords, sequence options for sequences. */
+export type HotkeyControllerOptionsFor<T extends RegisterableHotkey> = AdapterOptionsFor<T, HotkeyControllerTarget>;
+/** Call-site options for an app hotkey, typed by its declared default kind. */
+export type AppHotkeyControllerOptions<T extends AppHotkey = AppHotkey> = AdapterAppHotkeyOptions<T, HotkeyControllerTarget>;
+type MaybeGetter<T> = T | (() => T);
 /**
- * A Lit ReactiveController that registers a keyboard hotkey when the host
- * element is connected and unregisters it when the host is disconnected.
+ * A Lit ReactiveController that registers a hotkey when the host element is
+ * connected and unregisters it when the host is disconnected. The hotkey can
+ * be a chord such as `'Mod+S'`, a sequence such as `['G', 'G']`, or an app
+ * hotkey from `defineAppHotkeys`, which uses its custom hotkey from
+ * `provideAppHotkeys`.
+ *
+ * Chords accept `requireReset`; sequences accept `timeout`. Pass a getter for
+ * the hotkey or options to re-read them after each host update.
  *
  * @example
  * ```ts
  * class MyElement extends LitElement {
- *   private hotkey = new HotkeyController(this, 'Mod+S', () => this.save())
+ *   private save = new HotkeyController(this, 'Mod+S', () => this.doSave())
+ *   private top = new HotkeyController(this, ['G', 'G'], () => this.scrollToTop())
  *
  *   constructor() {
  *     super()
- *     this.addController(this.hotkey)
+ *     this.addController(this.save)
+ *     this.addController(this.top)
  *   }
  * }
  * ```
@@ -20,23 +44,25 @@ import { ReactiveController, ReactiveControllerHost } from "lit";
 export declare class HotkeyController implements ReactiveController {
   private _host;
   private _hotkey;
-  private _callback;
   private _options;
-  /** The hotkey registration handle. */
-  private _registration;
-  /**
-   * @param _host - The Lit component that owns this controller (use `this` and pass it to `addController()`).
-   * @param _hotkey - The key or key combo to listen for (e.g. `'Mod+S'` or a raw hotkey object).
-   * @param _callback - Function to run when the hotkey is pressed; called with the host as `this`.
-   * @param _options - Optional registration options (target, platform, enabled, etc.).
-   */
-  constructor(_host: ReactiveControllerHost, _hotkey: RegisterableHotkey, _callback: HotkeyCallback, _options?: HotkeyOptions);
+  private _bindings;
+  private _connected;
+  private _boundCallback;
+  private _unsubscribe;
   /**
-   * Registers the hotkey with the global manager when the host is connected to the DOM.
-   * Skips registration if no target is available (e.g. no document or options.target is null).
+   * @param host - The Lit component that owns this controller. Add the controller with `addController()`.
+   * @param hotkey - The chord, sequence, or app hotkey to register, or a getter. A getter is read on connection and after host updates.
+   * @param callback - Called with the host as `this`.
+   * @param options - Options or a getter. Property getters are read on connection and after host updates.
    */
+  constructor(host: ReactiveControllerHost, hotkey: MaybeGetter<AppHotkey>, callback: HotkeyCallback, options?: MaybeGetter<AppHotkeyControllerOptions>);
+  constructor(host: ReactiveControllerHost, hotkey: MaybeGetter<RegisterableHotkey>, callback: HotkeyCallback, options?: MaybeGetter<HotkeyControllerCommonOptions>);
+  /** Registers when connected and a target is available. */
   hostConnected(): void;
-  /** Unregisters the hotkey when the host is disconnected from the DOM. */
+  /** Refreshes options after rendering, when scoped targets are available. */
+  hostUpdated(): void;
+  private _sync;
+  /** Releases registrations when the host disconnects. */
   hostDisconnected(): void;
 }
 //#endregion