@tanstack/svelte-hotkeys 0.12.1 → 0.14.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/HotkeysCtx.d.ts

@@ -1,23 +1,59 @@
-import type { HotkeyRecorderOptions, HotkeySequenceRecorderOptions } from '@tanstack/hotkeys';
-import type { CreateHotkeyOptions } from './createHotkey.svelte';
+import { AppHotkeysStore } from '@tanstack/hotkeys';
+import type { AppHotkeys, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from '@tanstack/hotkeys';
+import type { CreateHotkeyCommonOptions } from './createHotkey.svelte';
 import type { Snippet } from 'svelte';
-import type { CreateHotkeySequenceOptions } from './createHotkeySequence.svelte';
 export interface HotkeysProviderOptions {
-    hotkey?: Partial<CreateHotkeyOptions>;
-    hotkeyRecorder?: Partial<HotkeyRecorderOptions>;
-    hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>;
-    hotkeySequence?: Partial<CreateHotkeySequenceOptions>;
+    /**
+     * Defaults for every hotkey registered by `createHotkey` and `createHotkeys`.
+     * `requireReset` applies to chords and `timeout` applies to sequences.
+     */
+    hotkey?: CreateHotkeyCommonOptions;
+    /** Defaults for every `createHotkeyRecorder`. */
+    hotkeyRecorder?: Partial<Omit<HotkeyChordRecorderOptions & HotkeySequenceRecorderOptions, 'maxSteps' | 'onRecord' | 'validate'>>;
 }
-export interface HotkeysProviderProps {
-    children: Snippet;
+/** Options for `setHotkeysContext` and props for `HotkeysProvider`. */
+export interface HotkeysContextOptions {
     defaultOptions?: HotkeysProviderOptions;
+    /**
+     * Every app hotkey, from `defineAppHotkeys`. Read when the context is set;
+     * listed by `getAppHotkeyList` whether or not they are registered.
+     */
+    appHotkeys?: AppHotkeys;
+    /**
+     * Starting custom hotkeys, such as saved data. Read once; the context owns
+     * the state afterwards. Invalid entries are ignored with a warning.
+     */
+    customHotkeys?: CustomHotkeys | null;
+    /** Called with the custom hotkeys after every change, ready to save. */
+    onCustomHotkeysChange?: (customHotkeys: CustomHotkeys) => void;
+}
+export interface HotkeysProviderProps extends HotkeysContextOptions {
+    children: Snippet;
 }
 export declare const DEFAULT_OPTIONS: HotkeysProviderOptions;
 interface HotkeysContextValue {
-    defaultOptions: HotkeysProviderOptions;
+    readonly appHotkeysStore: AppHotkeysStore | null;
+    readonly defaultOptions: HotkeysProviderOptions;
 }
-export declare function setHotkeysContext(defaultOptions?: HotkeysProviderOptions): HotkeysContextValue;
-export declare function setHotkeysContextSource(defaultOptions: () => HotkeysProviderOptions): HotkeysContextValue;
+/**
+ * Sets the hotkeys context for descendants. `HotkeysProvider` calls this; call
+ * it directly in a root component's script instead of rendering the provider.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   setHotkeysContext({
+ *     appHotkeys,
+ *     customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+ *     onCustomHotkeysChange: (custom) =>
+ *       localStorage.setItem('hotkeys', JSON.stringify(custom)),
+ *   })
+ * </script>
+ * ```
+ */
+export declare function setHotkeysContext(options?: HotkeysContextOptions): HotkeysContextValue;
+/** Sets the context from a getter, so default options stay reactive. */
+export declare function setHotkeysContextSource(source: () => HotkeysContextOptions): HotkeysContextValue;
 export declare function getHotkeysContext(): HotkeysContextValue | null;
 export declare function getDefaultHotkeysOptions(): HotkeysProviderOptions;
 export {};

package/dist/HotkeysCtx.js

@@ -1,17 +1,42 @@
-import { createContext } from 'svelte';
+import { createContext, onMount } from 'svelte';
+import { AppHotkeysStore, publishAppHotkeysStore } from '@tanstack/hotkeys';
 export const DEFAULT_OPTIONS = {};
 const [useHotkeysContext, setHotkeysContextValue] = createContext();
-export function setHotkeysContext(defaultOptions = DEFAULT_OPTIONS) {
-    return setHotkeysContextValue({
-        get defaultOptions() {
-            return defaultOptions;
-        },
-    });
+/**
+ * Sets the hotkeys context for descendants. `HotkeysProvider` calls this; call
+ * it directly in a root component's script instead of rendering the provider.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   setHotkeysContext({
+ *     appHotkeys,
+ *     customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+ *     onCustomHotkeysChange: (custom) =>
+ *       localStorage.setItem('hotkeys', JSON.stringify(custom)),
+ *   })
+ * </script>
+ * ```
+ */
+export function setHotkeysContext(options = {}) {
+    return setHotkeysContextSource(() => options);
 }
-export function setHotkeysContextSource(defaultOptions) {
+/** Sets the context from a getter, so default options stay reactive. */
+export function setHotkeysContextSource(source) {
+    const { appHotkeys, customHotkeys } = source();
+    const store = appHotkeys
+        ? new AppHotkeysStore(appHotkeys, {
+            customHotkeys,
+            onCustomHotkeysChange: (custom) => source().onCustomHotkeysChange?.(custom),
+        })
+        : null;
+    // Publish the store so devtools can list declared hotkeys.
+    if (store)
+        onMount(() => publishAppHotkeysStore(store));
     return setHotkeysContextValue({
+        appHotkeysStore: store,
         get defaultOptions() {
-            return defaultOptions();
+            return source().defaultOptions ?? DEFAULT_OPTIONS;
         },
     });
 }

package/dist/HotkeysProvider.svelte

@@ -1,12 +1,27 @@
 <script lang="ts">
-  import { DEFAULT_OPTIONS, setHotkeysContextSource } from './HotkeysCtx'
+  import { setHotkeysContextSource } from './HotkeysCtx'
 
   import type { HotkeysProviderProps } from './HotkeysCtx'
 
-  let { children, defaultOptions = DEFAULT_OPTIONS }: HotkeysProviderProps =
-    $props()
+  let {
+    children,
+    defaultOptions,
+    appHotkeys,
+    customHotkeys,
+    onCustomHotkeysChange,
+  }: HotkeysProviderProps = $props()
 
-  setHotkeysContextSource(() => defaultOptions)
+  const context = setHotkeysContextSource(() => ({
+    defaultOptions,
+    appHotkeys,
+    customHotkeys,
+    onCustomHotkeysChange,
+  }))
+
+  // Keep declarations current (for example after hot module replacement).
+  $effect(() => {
+    if (appHotkeys) context.appHotkeysStore?.setAppHotkeys(appHotkeys)
+  })
 </script>
 
 {@render children()}

package/dist/createHotkey.svelte.d.ts

@@ -1,42 +1,55 @@
-import type { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from '@tanstack/hotkeys';
-import type { MaybeGetter } from './internal.svelte';
 import type { Attachment } from 'svelte/attachments';
-export interface CreateHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
-    target?: Document | Window;
-}
+import type { AppHotkey, HotkeyCallback, RegisterableHotkey } from '@tanstack/hotkeys';
+import type { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from '@tanstack/hotkeys/adapter';
+import type { MaybeGetter } from './internal.svelte';
+/** The document or window to listen on. Use an attachment for elements. */
+export type CreateHotkeyTarget = Document | Window;
+/** Options shared by chords and sequences. */
+export type CreateHotkeyOptions = AdapterHotkeyOptions<CreateHotkeyTarget>;
+/** Options for a chord such as `'Mod+S'`. */
+export type CreateHotkeyChordOptions = AdapterChordOptions<CreateHotkeyTarget>;
+/** Options for a sequence such as `['G', 'G']`. */
+export type CreateHotkeySequenceOptions = AdapterSequenceOptions<CreateHotkeyTarget>;
+/** Options applied to every hotkey, such as provider defaults. Each applies to the kinds that support it. */
+export type CreateHotkeyCommonOptions = AdapterCommonOptions<CreateHotkeyTarget>;
+/** The options type for a hotkey: chord options for chords, sequence options for sequences. */
+export type CreateHotkeyOptionsFor<T extends RegisterableHotkey> = AdapterOptionsFor<T, CreateHotkeyTarget>;
+/** Call-site options for an app hotkey, typed by its declared default kind. */
+export type CreateAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHotkeyOptions<T, CreateHotkeyTarget>;
 /**
- * Register a global hotkey for the current component.
+ * Svelte function for registering a hotkey on the document: a chord such as
+ * `'Mod+S'`, a sequence such as `['G', 'G']`, or an app hotkey from
+ * `defineAppHotkeys`. Pass getters for reactive values. Use
+ * `createHotkeyAttachment` for element-scoped hotkeys.
+ *
+ * Chords accept `requireReset`; sequences accept `timeout`. A one-step
+ * sequence registers as its chord. An app hotkey uses its effective hotkey
+ * from `HotkeysProvider` (including the user's custom hotkey) and its
+ * declared meta and options, and registers nothing while unbound.
  *
  * @example
  * ```svelte
  * <script lang="ts">
- *   import { createHotkey } from '@tanstack/svelte-hotkeys'
- *
- *   createHotkey('Mod+S', () => {
- *     console.log('Mod+S pressed')
- *   })
+ *   createHotkey('Mod+S', () => save())
+ *   createHotkey(['G', 'G'], () => scrollToTop(), { timeout: 500 })
+ *   createHotkey('Escape', () => close(), () => ({ enabled: isOpen }))
  * </script>
  * ```
  */
-export declare function createHotkey(hotkey: MaybeGetter<RegisterableHotkey>, callback: HotkeyCallback, options?: MaybeGetter<CreateHotkeyOptions>): void;
+export declare function createHotkey<T extends AppHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<CreateAppHotkeyOptions<T>>): void;
+export declare function createHotkey<T extends RegisterableHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<CreateHotkeyOptionsFor<T>>): void;
 /**
- * Create an attachment for element-scoped hotkeys.
+ * Create an attachment for an element-scoped hotkey: a chord, a sequence, or
+ * an app hotkey that listens on the attached element.
  *
  * @example
  * ```svelte
  * <script lang="ts">
- *   import { createHotkeyAttachment } from '@tanstack/svelte-hotkeys'
- *
- *   let count = $state(0)
- *   const saveHotkey = createHotkeyAttachment('Mod+S', () => {
- *     count++
- *   })
- *
+ *   const saveKey = createHotkeyAttachment('Mod+S', () => save())
  * </script>
  *
- * <div tabindex="0" {@attach saveHotkey}>
- *   Count: {count}
- * </div>
+ * <div tabindex="0" {@attach saveKey}>Editor content</div>
  * ```
  */
-export declare function createHotkeyAttachment(hotkey: MaybeGetter<RegisterableHotkey>, callback: HotkeyCallback, options?: MaybeGetter<CreateHotkeyOptions>): Attachment<HTMLElement>;
+export declare function createHotkeyAttachment<T extends AppHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<CreateAppHotkeyOptions<T>>): Attachment<HTMLElement>;
+export declare function createHotkeyAttachment<T extends RegisterableHotkey>(hotkey: MaybeGetter<T>, callback: HotkeyCallback, options?: MaybeGetter<CreateHotkeyOptionsFor<T>>): Attachment<HTMLElement>;

package/dist/createHotkey.svelte.js

@@ -1,110 +1,7 @@
-import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey, } from '@tanstack/hotkeys';
-import { onDestroy } from 'svelte';
-import { getDefaultHotkeysOptions } from './HotkeysCtx';
-import { resolveMaybeGetter } from './internal.svelte';
-function registerHotkey(target, hotkey, callback, mergedOptions) {
-    return getHotkeyManager().register(normalizeRegisterableHotkey(hotkey, mergedOptions.platform ?? detectPlatform()), callback, {
-        ...mergedOptions,
-        target,
-    });
-}
-/**
- * Register a global hotkey for the current component.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkey } from '@tanstack/svelte-hotkeys'
- *
- *   createHotkey('Mod+S', () => {
- *     console.log('Mod+S pressed')
- *   })
- * </script>
- * ```
- */
+import { createHotkeys, createHotkeysAttachment } from './createHotkeys.svelte';
 export function createHotkey(hotkey, callback, options = {}) {
-    let registration = null;
-    let lastHotkeyStr = null;
-    $effect(() => {
-        if (typeof document === 'undefined') {
-            return;
-        }
-        const resolvedHotkey = resolveMaybeGetter(hotkey);
-        const resolvedOptions = resolveMaybeGetter(options);
-        const mergedOptions = {
-            ...getDefaultHotkeysOptions().hotkey,
-            ...resolvedOptions,
-        };
-        const hotkeyStr = normalizeRegisterableHotkey(resolvedHotkey, mergedOptions.platform ?? detectPlatform());
-        const { target: _t, ...optionsWithoutTarget } = mergedOptions;
-        if (registration?.isActive && lastHotkeyStr === hotkeyStr) {
-            registration.callback = callback;
-            registration.setOptions(optionsWithoutTarget);
-            return;
-        }
-        if (registration?.isActive) {
-            registration.unregister();
-            registration = null;
-        }
-        registration = registerHotkey(document, resolvedHotkey, callback, mergedOptions);
-        lastHotkeyStr = hotkeyStr;
-    });
-    onDestroy(() => {
-        if (registration?.isActive) {
-            registration.unregister();
-            registration = null;
-        }
-    });
+    createHotkeys([{ hotkey, callback, options }]);
 }
-/**
- * Create an attachment for element-scoped hotkeys.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   import { createHotkeyAttachment } from '@tanstack/svelte-hotkeys'
- *
- *   let count = $state(0)
- *   const saveHotkey = createHotkeyAttachment('Mod+S', () => {
- *     count++
- *   })
- *
- * </script>
- *
- * <div tabindex="0" {@attach saveHotkey}>
- *   Count: {count}
- * </div>
- * ```
- */
 export function createHotkeyAttachment(hotkey, callback, options = {}) {
-    return (element) => {
-        let registration = null;
-        let lastHotkeyStr = null;
-        $effect(() => {
-            const resolvedHotkey = resolveMaybeGetter(hotkey);
-            const resolvedOptions = resolveMaybeGetter(options);
-            const mergedOptions = {
-                ...getDefaultHotkeysOptions().hotkey,
-                ...resolvedOptions,
-            };
-            const hotkeyStr = normalizeRegisterableHotkey(resolvedHotkey, mergedOptions.platform ?? detectPlatform());
-            const { target: _t, ...optionsWithoutTarget } = mergedOptions;
-            if (registration?.isActive && lastHotkeyStr === hotkeyStr) {
-                registration.callback = callback;
-                registration.setOptions(optionsWithoutTarget);
-                return;
-            }
-            if (registration?.isActive) {
-                registration.unregister();
-                registration = null;
-            }
-            registration = registerHotkey(element, resolvedHotkey, callback, mergedOptions);
-            lastHotkeyStr = hotkeyStr;
-        });
-        return () => {
-            if (registration?.isActive) {
-                registration.unregister();
-            }
-        };
-    };
+    return createHotkeysAttachment([{ hotkey, callback, options }]);
 }

package/dist/createHotkeyRecorder.svelte.d.ts

@@ -1,15 +1,42 @@
-import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys';
-import type { MaybeGetter } from './internal.svelte';
-export interface SvelteHotkeyRecorder {
+import type { Hotkey, HotkeyChord, HotkeyChordRecorderOptions, HotkeyRecorderOptions, HotkeySequence, HotkeySequenceRecorderOptions } from '@tanstack/hotkeys';
+export interface SvelteHotkeyRecorder<THotkey extends Hotkey = Hotkey> {
     /** Whether recording is currently active */
     readonly isRecording: boolean;
-    /** The currently recorded hotkey (for live preview) */
-    readonly recordedHotkey: Hotkey | null;
+    /** Chords recorded so far in a multi-step recording (for live preview) */
+    readonly steps: HotkeySequence;
+    /** The last committed hotkey */
+    readonly recordedHotkey: THotkey | null;
     /** Start recording a new hotkey */
     startRecording: () => void;
-    /** Stop recording (same as cancel) */
+    /** Stop recording without calling onCancel */
     stopRecording: () => void;
-    /** Cancel recording without saving */
+    /** Cancel recording and call onCancel */
     cancelRecording: () => void;
+    /** Commit the recorded steps now (multi-step recordings) */
+    commitRecording: () => void;
 }
-export declare function createHotkeyRecorder(options: MaybeGetter<HotkeyRecorderOptions>): SvelteHotkeyRecorder;
+/**
+ * Svelte function for recording keyboard shortcuts. Options may be a getter.
+ *
+ * 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.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   const recorder = createHotkeyRecorder({ onRecord: (hotkey) => (shortcut = hotkey) })
+ *   const sequenceRecorder = createHotkeyRecorder({ maxSteps: 3, onRecord: save })
+ * </script>
+ *
+ * <button onclick={recorder.startRecording}>
+ *   {recorder.isRecording ? 'Press keys…' : formatForDisplay(shortcut)}
+ * </button>
+ * ```
+ */
+export declare function createHotkeyRecorder(options: HotkeyChordRecorderOptions): SvelteHotkeyRecorder<HotkeyChord>;
+export declare function createHotkeyRecorder(options: HotkeySequenceRecorderOptions): SvelteHotkeyRecorder;
+export declare function createHotkeyRecorder(options: () => HotkeySequenceRecorderOptions): SvelteHotkeyRecorder;
+export declare function createHotkeyRecorder(options: () => HotkeyChordRecorderOptions): SvelteHotkeyRecorder<HotkeyChord>;
+export declare function createHotkeyRecorder(options: () => HotkeyRecorderOptions): SvelteHotkeyRecorder;

package/dist/createHotkeyRecorder.svelte.js

@@ -2,42 +2,6 @@ import { HotkeyRecorder } from '@tanstack/hotkeys';
 import { onDestroy } from 'svelte';
 import { getDefaultHotkeysOptions } from './HotkeysCtx';
 import { createStoreSubscriber, resolveMaybeGetter } from './internal.svelte';
-/**
- * Svelte function for recording keyboard shortcuts.
- *
- * This function provides a thin wrapper around 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.
- *
- * @param options - Configuration options for the recorder
- * @returns An object with recording state and control functions
- *
- * @example
- * ```svelte
- * <script>
- *   import { createHotkeyRecorder } from '@tanstack/svelte-hotkeys'
- *
- *   const recorder = createHotkeyRecorder({
- *     onRecord: (hotkey) => {
- *       console.log('Recorded:', hotkey) // e.g., "Mod+Shift S"
- *     },
- *     onCancel: () => {
- *       console.log('Recording cancelled')
- *     },
- *   })
- * </script>
- *
- * <div>
- *   <button onclick={recorder.startRecording}>
- *     {recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}
- *   </button>
- *   {#if recorder.recordedHotkey}
- *     <div>Recording: {recorder.recordedHotkey}</div>
- *   {/if}
- * </div>
- * ```
- */
 class SvelteHotkeyRecorderState {
     #recorder;
     #subscribe;
@@ -49,6 +13,10 @@ class SvelteHotkeyRecorderState {
         this.#subscribe();
         return this.#recorder.store.state.isRecording;
     }
+    get steps() {
+        this.#subscribe();
+        return this.#recorder.store.state.steps;
+    }
     get recordedHotkey() {
         this.#subscribe();
         return this.#recorder.store.state.recordedHotkey;
@@ -56,32 +24,32 @@ class SvelteHotkeyRecorderState {
     setOptions(options) {
         this.#recorder.setOptions(options);
     }
-    // Keep the recorder receiver when used directly as an event handler.
+    // Arrow functions keep the receiver when used directly as event handlers.
     startRecording = () => {
         this.#recorder.start();
     };
-    // Keep the recorder receiver when used directly as an event handler.
     stopRecording = () => {
         this.#recorder.stop();
     };
-    // Keep the recorder receiver when used directly as an event handler.
     cancelRecording = () => {
         this.#recorder.cancel();
     };
+    commitRecording = () => {
+        this.#recorder.commit();
+    };
     destroy() {
         this.#recorder.destroy();
     }
 }
 export function createHotkeyRecorder(options) {
-    const recorder = new SvelteHotkeyRecorderState({
+    const resolve = () => ({
         ...getDefaultHotkeysOptions().hotkeyRecorder,
         ...resolveMaybeGetter(options),
     });
+    // Overloads already checked the options; either shape is valid here.
+    const recorder = new SvelteHotkeyRecorderState(resolve());
     $effect(() => {
-        recorder.setOptions({
-            ...getDefaultHotkeysOptions().hotkeyRecorder,
-            ...resolveMaybeGetter(options),
-        });
+        recorder.setOptions(resolve());
     });
     onDestroy(() => {
         recorder.destroy();

package/dist/createHotkeys.svelte.d.ts

@@ -1,52 +1,69 @@
-import type { HotkeyCallback, RegisterableHotkey } from '@tanstack/hotkeys';
-import type { CreateHotkeyOptions } from './createHotkey.svelte';
-import type { MaybeGetter } from './internal.svelte';
 import type { Attachment } from 'svelte/attachments';
+import type { AppHotkey, HotkeyCallback, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord } from '@tanstack/hotkeys';
+import type { MaybeGetter } from './internal.svelte';
+import type { CreateAppHotkeyOptions, CreateHotkeyChordOptions, CreateHotkeyCommonOptions, CreateHotkeyOptions, CreateHotkeySequenceOptions } from './createHotkey.svelte';
 /**
- * A single hotkey definition for use with `createHotkeys`.
+ * One hotkey for `createHotkeys`. The hotkey and options may be getters.
+ * Chords accept `requireReset`; sequences accept `timeout`; hotkeys of unknown
+ * kind accept only shared options.
  */
-export interface CreateHotkeyDefinition {
-    /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
-    hotkey: MaybeGetter<RegisterableHotkey>;
+export type CreateHotkeyDefinition = {
+    /** A chord string such as `'Mod+S'`, or a RawHotkey object */
+    hotkey: MaybeGetter<RegisterableHotkeyChord>;
     /** The function to call when the hotkey is pressed */
     callback: HotkeyCallback;
     /** Per-hotkey options (merged on top of commonOptions) */
+    options?: MaybeGetter<CreateHotkeyChordOptions>;
+} | {
+    /** A sequence such as `['G', 'G']` */
+    hotkey: MaybeGetter<HotkeySequence>;
+    callback: HotkeyCallback;
+    options?: MaybeGetter<CreateHotkeySequenceOptions>;
+} | {
+    /** An app hotkey from `defineAppHotkeys` */
+    hotkey: MaybeGetter<AppHotkey>;
+    callback: HotkeyCallback;
+    options?: MaybeGetter<CreateAppHotkeyOptions>;
+} | {
+    /** A hotkey whose kind is not known statically. Accepts only shared options. */
+    hotkey: MaybeGetter<RegisterableHotkey>;
+    callback: HotkeyCallback;
     options?: MaybeGetter<CreateHotkeyOptions>;
-}
+};
 /**
- * Register multiple global hotkeys for the current component.
+ * Svelte function for registering several hotkeys at once on the document:
+ * chords, sequences, and app hotkeys. Pass getters for reactive values. Use
+ * `createHotkeysAttachment` for element-scoped hotkeys.
+ *
+ * Options merge in this order: provider defaults, app hotkey declaration,
+ * commonOptions, per-hotkey options. Each option applies only to the kinds
+ * that support it. Unbound app hotkeys and empty sequences register nothing.
  *
  * @example
  * ```svelte
  * <script lang="ts">
- *   import { createHotkeys } from '@tanstack/svelte-hotkeys'
- *
  *   createHotkeys([
  *     { hotkey: 'Mod+S', callback: () => save() },
- *     { hotkey: 'Mod+Z', callback: () => undo() },
- *     { hotkey: 'Escape', callback: () => close() },
+ *     { hotkey: ['G', 'G'], callback: () => scrollToTop(), options: { timeout: 500 } },
  *   ])
  * </script>
  * ```
  */
-export declare function createHotkeys(hotkeys: MaybeGetter<Array<CreateHotkeyDefinition>>, commonOptions?: MaybeGetter<CreateHotkeyOptions>): void;
+export declare function createHotkeys(hotkeys: MaybeGetter<ReadonlyArray<CreateHotkeyDefinition>>, commonOptions?: MaybeGetter<CreateHotkeyCommonOptions>): void;
 /**
- * Create an attachment for element-scoped multi-hotkey registration.
+ * Create an attachment for element-scoped hotkeys: chords, sequences, and app
+ * hotkeys listen on the attached element.
  *
  * @example
  * ```svelte
  * <script lang="ts">
- *   import { createHotkeysAttachment } from '@tanstack/svelte-hotkeys'
- *
  *   const editorKeys = createHotkeysAttachment([
  *     { hotkey: 'Mod+S', callback: () => save() },
- *     { hotkey: 'Mod+Z', callback: () => undo() },
+ *     { hotkey: ['G', 'G'], callback: () => scrollToTop() },
  *   ])
  * </script>
  *
- * <div tabindex="0" {@attach editorKeys}>
- *   Editor content
- * </div>
+ * <div tabindex="0" {@attach editorKeys}>Editor content</div>
  * ```
  */
-export declare function createHotkeysAttachment(hotkeys: MaybeGetter<Array<CreateHotkeyDefinition>>, commonOptions?: MaybeGetter<CreateHotkeyOptions>): Attachment<HTMLElement>;
+export declare function createHotkeysAttachment(hotkeys: MaybeGetter<ReadonlyArray<CreateHotkeyDefinition>>, commonOptions?: MaybeGetter<CreateHotkeyCommonOptions>): Attachment<HTMLElement>;