@tanstack/hotkeys 0.15.1 → 0.16.1

package/dist/hotkey-manager.d.ts

@@ -1,4 +1,4 @@
-import { ConflictBehavior, HotkeyCallback, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkey, RegisterableHotkey, RegisterableHotkeyChord } from "./hotkey.types.js";
+import { ConflictBehavior, HotkeyCallback, HotkeyCallbackContextFor, HotkeyChord, HotkeyMeta, HotkeySequence, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { AppHotkeysStore } from "./app-hotkeys.js";
 import { Store } from "@tanstack/store";
 //#region src/hotkey-manager.d.ts
@@ -39,14 +39,30 @@ export interface HotkeyOptions {
   ignoreInputs?: boolean | 'auto';
   /** The target platform for resolving 'Mod' */
   platform?: 'mac' | 'windows' | 'linux';
-  /** Prevent the default browser action when the hotkey matches. Defaults to true */
+  /**
+   * Prevent the default browser action when the hotkey matches. For a
+   * sequence, every step that advances it does. Defaults to true
+   */
   preventDefault?: boolean;
-  /** Stop event propagation when the hotkey matches. Defaults to true */
+  /**
+   * Stop event propagation when the hotkey matches. For a sequence, only the
+   * last step does, so earlier steps reach other listeners. Defaults to true
+   */
   stopPropagation?: boolean;
   /** The DOM element to attach the event listener to. Defaults to document. */
   target?: Target | null;
   /** Optional metadata (name, description, custom fields via declaration merging) */
   meta?: HotkeyMeta;
+  /**
+   * Scope this hotkey belongs to. Defaults to `'global'`, which is always
+   * active. Other scopes are active while activated with
+   * `HotkeyManager.activateScope`, which framework providers do while
+   * mounted. While an exclusive scope is active, only its hotkeys, those of
+   * scopes nested in it, and those of scopes it allows fire.
+   * When active scopes share a hotkey on the same target, the most recently
+   * activated scope handles it.
+   */
+  scope?: string;
   /** Id of the app hotkey this registration implements. Adapters set this when registering an app hotkey from `defineAppHotkeys`. */
   appHotkeyId?: string;
 }
@@ -64,7 +80,7 @@ export interface HotkeySequenceOptions extends HotkeyOptions {
  * The options type for a hotkey: chord options for chords (including one-step
  * tuples), sequence options for sequences.
  */
-export type HotkeyOptionsFor<T extends RegisterableHotkey> = [T] extends [never] ? HotkeyChordOptions & HotkeySequenceOptions : T extends readonly [RegisterableHotkeyChord] ? HotkeyChordOptions : T extends HotkeySequence ? HotkeySequenceOptions : HotkeyChordOptions;
+export type HotkeyOptionsFor<T extends RegisterableHotkey> = [T] extends [never] ? HotkeyChordOptions & HotkeySequenceOptions : T extends readonly [RegisterableHotkeyChord] ? HotkeyChordOptions : T extends RegisterableHotkeySequence ? HotkeySequenceOptions : HotkeyChordOptions;
 interface RegistrationBase<TOptions extends HotkeyOptions> {
   /** Unique identifier for this registration */
   id: string;
@@ -83,7 +99,7 @@ interface RegistrationBase<TOptions extends HotkeyOptions> {
 export interface HotkeyChordRegistration extends RegistrationBase<HotkeyChordOptions> {
   kind: 'chord';
   hotkey: HotkeyChord;
-  parsedHotkey: ParsedHotkey;
+  parsedChord: ParsedHotkeyChord;
   /** The concrete key/code that activated a requireReset registration. */
   activeMatch?: {
     key: string;
@@ -94,7 +110,7 @@ export interface HotkeyChordRegistration extends RegistrationBase<HotkeyChordOpt
 export interface HotkeySequenceRegistration extends RegistrationBase<HotkeySequenceOptions> {
   kind: 'sequence';
   hotkey: HotkeySequence;
-  parsedSequence: Array<ParsedHotkey>;
+  parsedSequence: Array<ParsedHotkeyChord>;
   /** Steps matched in the current attempt */
   currentIndex: number;
   /** `Date.now()` when the last step in the current attempt matched */
@@ -112,14 +128,14 @@ interface RegistrationViewBase {
 export interface HotkeyChordRegistrationView extends RegistrationViewBase {
   kind: 'chord';
   hotkey: HotkeyChord;
-  parsedHotkey: ParsedHotkey;
+  parsedChord: ParsedHotkeyChord;
   options: HotkeyChordOptions;
 }
 /** Public view of a sequence registration, without its callback. */
 export interface HotkeySequenceRegistrationView extends RegistrationViewBase {
   kind: 'sequence';
   hotkey: HotkeySequence;
-  parsedSequence: Array<ParsedHotkey>;
+  parsedSequence: Array<ParsedHotkeyChord>;
   options: HotkeySequenceOptions;
   /** Steps matched in the current attempt (0 when idle or just completed). */
   matchedStepCount: number;
@@ -172,6 +188,44 @@ export interface HotkeyRegistrationHandle<TOptions extends HotkeyOptions = Hotke
   /** Unregister this hotkey */
   unregister: () => void;
 }
+/** Active hotkey scopes, published on `HotkeyManager.scopes`. */
+export interface HotkeyScopesState {
+  /**
+   * Activated scopes, lowest precedence first. `'global'` is always active
+   * and not listed.
+   */
+  active: ReadonlyArray<string>;
+  /** The exclusive scope that owns the keyboard, or `null` when none is active. */
+  exclusive: string | null;
+  /**
+   * Scopes the exclusive scope allows that are active, possibly including
+   * `'global'`. Empty when no scope is exclusive.
+   */
+  allowed: ReadonlyArray<string>;
+  /**
+   * Scopes that are active but cannot fire because another scope is
+   * exclusive, possibly including `'global'`.
+   */
+  suspended: ReadonlyArray<string>;
+}
+/** Options for `HotkeyManager.activateScope`. */
+export interface ActivateHotkeyScopeOptions {
+  /**
+   * Suspend every other scope, including `'global'`, until this activation is
+   * released. Scopes nested in this one stay active. Pass `{ allow }` to keep
+   * other scopes active too, such as `{ allow: ['global'] }`. An allowed scope
+   * still has to be activated, except `'global'`.
+   */
+  exclusive?: boolean | {
+    allow: ReadonlyArray<string>;
+  };
+  /**
+   * The scope this one is nested in. A nested scope takes precedence over its
+   * ancestors even when it was activated first, as nested providers are when
+   * their effects run child-first. Defaults to `'global'`.
+   */
+  parent?: string;
+}
 /**
  * Singleton manager for hotkey registrations, including sequences.
  *
@@ -225,6 +279,8 @@ export declare class HotkeyManager {
    * devtools can list declared hotkeys that are not registered.
    */
   readonly appHotkeys: Store<AppHotkeysStore | null>;
+  /** Active scopes. Subscribe to show which hotkeys are suspended. */
+  readonly scopes: Store<HotkeyScopesState>;
   private constructor();
   /**
    * Gets the singleton instance of HotkeyManager.
@@ -234,17 +290,44 @@ export declare class HotkeyManager {
    * Resets the singleton instance. Useful for testing.
    */
   static resetInstance(): void;
+  /**
+   * Activates a scope until the returned function is called. Activations are
+   * counted, so a scope stays active until every activation is released.
+   * Framework providers call this while mounted.
+   *
+   * When active scopes share a hotkey, a nested scope takes precedence over
+   * its ancestors, and otherwise the most recently activated scope wins. The
+   * same order picks the exclusive scope when several are active, and only
+   * that scope's `allow` list applies.
+   *
+   * @example
+   * ```ts
+   * const release = manager.activateScope('dialog', { exclusive: true })
+   * // Only hotkeys with scope 'dialog', or scopes nested in it, fire now.
+   * release()
+   *
+   * manager.activateScope('dialog', { exclusive: { allow: ['global'] } })
+   * // Hotkeys with scope 'global' fire too.
+   * ```
+   */
+  activateScope(scope: string, options?: ActivateHotkeyScopeOptions): () => void;
+  /**
+   * Whether hotkeys in a scope can fire: the scope is `'global'` or
+   * activated, and either no scope is exclusive or this scope is the
+   * exclusive one, nested in it, or allowed by it.
+   */
+  isScopeActive(scope?: string): boolean;
   /**
    * Registers a hotkey handler and returns a handle for updating the registration.
    *
-   * Pass a chord (`'Mod+S'` or a RawHotkey object) or a sequence (`['G', 'G']`).
+   * Pass a chord (`'Mod+S'` or a RawHotkeyChord object) or a sequence (`['G', 'G']`).
    * A one-step sequence registers as its chord. Chords accept `requireReset`;
    * sequences accept `timeout`.
    *
    * The returned handle allows updating the callback and options without
    * re-registering, which is useful for avoiding stale closures in React.
    *
-   * @param hotkey - A chord string, RawHotkey object, or sequence
+   * @param hotkey - A chord string, RawHotkeyChord object, or sequence
    * @param callback - The function to call when the hotkey is pressed
    * @param options - Options for the hotkey behavior
    * @returns A handle for managing the registration
@@ -263,7 +346,7 @@ export declare class HotkeyManager {
    * handle.unregister()
    * ```
    */
-  register<T extends RegisterableHotkey>(hotkey: T, callback: HotkeyCallback, options?: HotkeyOptionsFor<T>): HotkeyRegistrationHandle<HotkeyOptionsFor<T>>;
+  register<const T extends RegisterableHotkey>(hotkey: T, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: HotkeyOptionsFor<T>): HotkeyRegistrationHandle<HotkeyOptionsFor<T>>;
   /**
    * Resets the progress of every in-progress sequence.
    */

package/dist/hotkey-manager.js

@@ -1,15 +1,15 @@
 import { normalizeKeyName } from "./constants.js";
 import { detectPlatform } from "./platform.js";
 import { keysEqual, normalizeKeyboardEvent } from "./_keyboard-event.js";
-import { isHotkeySequence, isModifierKey, parseHotkey, rawHotkeyToParsedHotkey, simplifyHotkey } from "./parse.js";
+import { isHotkeySequence, isModifierKey, parseHotkey, simplifyHotkey } from "./parse.js";
 import { formatHotkey } from "./format.js";
-import { matchKeyboardEvent, parsedHotkeysEqual } from "./_match.js";
+import { matchKeyboardEvent, parsedChordsEqual } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
 import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
 import { TargetListeners } from "./_target-listeners.js";
 import { managerRef } from "./_manager-ref.js";
 import { isRecordingEvent } from "./_recording-guard.js";
-import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
+import { GLOBAL_SCOPE, defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
 import { Store } from "@tanstack/store";
 
 //#region src/hotkey-manager.ts
@@ -25,7 +25,7 @@ function toHotkeyRegistrationView(reg) {
 		...base,
 		kind: "chord",
 		hotkey: reg.hotkey,
-		parsedHotkey: reg.parsedHotkey,
+		parsedChord: reg.parsedChord,
 		options: reg.options
 	};
 	const length = reg.parsedSequence.length;
@@ -41,6 +41,10 @@ function toHotkeyRegistrationView(reg) {
 	};
 }
 let registrationIdCounter = 0;
+/** The string a chord registers as: strings as written, objects formatted from their parsed form. */
+function chordString(chord, parsed) {
+	return typeof chord === "string" ? chord : formatHotkey(parsed);
+}
 /**
 * Generates a unique ID for hotkey registrations.
 */
@@ -58,7 +62,7 @@ function optionsForKind(kind, options) {
 }
 /** Steps with Mod already resolved for the registration's platform. */
 function resolvedSteps(registration) {
-	return registration.kind === "chord" ? [registration.parsedHotkey] : registration.parsedSequence;
+	return registration.kind === "chord" ? [registration.parsedChord] : registration.parsedSequence;
 }
 /** Whether a registration skips keys that focused controls use, resolving `'auto'`. */
 function ignoresInputs(registration) {
@@ -66,7 +70,7 @@ function ignoresInputs(registration) {
 	return ignoreInputs === "auto" ? getDefaultIgnoreInputs(resolvedSteps(registration)[0]) : ignoreInputs;
 }
 function sameResolvedSteps(left, right) {
-	return left.length === right.length && left.every((step, index) => parsedHotkeysEqual(step, right[index]));
+	return left.length === right.length && left.every((step, index) => parsedChordsEqual(step, right[index]));
 }
 function formatForMessage(hotkey) {
 	return isHotkeySequence(hotkey) ? hotkey.join(" ") : hotkey;
@@ -123,12 +127,27 @@ var HotkeyManager = class HotkeyManager {
 	* devtools can list declared hotkeys that are not registered.
 	*/
 	appHotkeys = new Store(null);
+	/** Active scopes. Subscribe to show which hotkeys are suspended. */
+	scopes = new Store({
+		active: [],
+		exclusive: null,
+		allowed: [],
+		suspended: []
+	});
 	#platform;
+	#scopeActivations = /* @__PURE__ */ new Set();
+	#scopeActivationCount = 0;
+	/** Active scopes, lowest precedence first, derived from activations. */
+	#scopeOrder = [];
+	/** Scopes that can fire while a scope is exclusive, or `null` when none is. */
+	#liveScopes = null;
 	#listeners = new TargetListeners((...args) => this.#processTargetEvent(...args));
 	/** Events that continue a sequence in progress, decided before any listener runs. */
 	#sequenceOwned = /* @__PURE__ */ new WeakMap();
 	/** Physical keys whose keydown a sequence owned, so their repeats and keyup are owned too. */
 	#sequenceOwnedKeys = /* @__PURE__ */ new Set();
+	/** Timers that clear a sequence's progress once its timeout passes. */
+	#sequenceResetTimers = /* @__PURE__ */ new Map();
 	constructor() {
 		this.#platform = detectPlatform();
 	}
@@ -145,6 +164,114 @@ var HotkeyManager = class HotkeyManager {
 		managerRef.current?.destroy();
 		managerRef.current = null;
 	}
+	/**
+	* Activates a scope until the returned function is called. Activations are
+	* counted, so a scope stays active until every activation is released.
+	* Framework providers call this while mounted.
+	*
+	* When active scopes share a hotkey, a nested scope takes precedence over
+	* its ancestors, and otherwise the most recently activated scope wins. The
+	* same order picks the exclusive scope when several are active, and only
+	* that scope's `allow` list applies.
+	*
+	* @example
+	* ```ts
+	* const release = manager.activateScope('dialog', { exclusive: true })
+	* // Only hotkeys with scope 'dialog', or scopes nested in it, fire now.
+	* release()
+	*
+	* manager.activateScope('dialog', { exclusive: { allow: ['global'] } })
+	* // Hotkeys with scope 'global' fire too.
+	* ```
+	*/
+	activateScope(scope, options = {}) {
+		if (scope === "global") return () => {};
+		const { exclusive } = options;
+		const allow = exclusive ? exclusive === true ? [] : exclusive.allow : null;
+		if (allow && [...this.#scopeActivations].some((other) => other.allow && other.scope === scope)) console.warn(`Exclusive hotkey scope '${scope}' is already active. Hotkeys from both activations will fire; give each a unique scope.`);
+		const activation = {
+			scope,
+			parent: options.parent ?? "global",
+			allow,
+			order: ++this.#scopeActivationCount
+		};
+		this.#scopeActivations.add(activation);
+		this.#updateScopes();
+		return () => {
+			if (this.#scopeActivations.delete(activation)) this.#updateScopes();
+		};
+	}
+	/**
+	* Whether hotkeys in a scope can fire: the scope is `'global'` or
+	* activated, and either no scope is exclusive or this scope is the
+	* exclusive one, nested in it, or allowed by it.
+	*/
+	isScopeActive(scope = GLOBAL_SCOPE) {
+		if (this.#liveScopes) return this.#liveScopes.has(scope);
+		return scope === "global" || this.#scopeOrder.includes(scope);
+	}
+	/** Higher for scopes with higher precedence; `'global'` is 0. */
+	#scopeRank(scope = GLOBAL_SCOPE) {
+		return this.#scopeOrder.indexOf(scope) + 1;
+	}
+	/** Recomputes scope precedence and publishes it. */
+	#updateScopes() {
+		const parents = /* @__PURE__ */ new Map();
+		const latest = /* @__PURE__ */ new Map();
+		for (const activation of this.#scopeActivations) {
+			parents.set(activation.scope, activation.parent);
+			latest.set(activation.scope, Math.max(latest.get(activation.scope) ?? 0, activation.order));
+		}
+		const depth = (scope) => {
+			let result = 0;
+			const seen = /* @__PURE__ */ new Set();
+			for (let current = parents.get(scope); current !== void 0 && !seen.has(current); current = parents.get(current)) {
+				seen.add(current);
+				result++;
+			}
+			return result;
+		};
+		const since = /* @__PURE__ */ new Map();
+		for (const [scope, order] of latest) {
+			const seen = /* @__PURE__ */ new Set();
+			for (let current = scope; current !== void 0 && !seen.has(current); current = parents.get(current)) {
+				seen.add(current);
+				const own = latest.get(current);
+				if (own !== void 0) since.set(current, Math.min(since.get(current) ?? own, order));
+			}
+		}
+		const compare = (a, b) => since.get(a) - since.get(b) || depth(a) - depth(b) || latest.get(a) - latest.get(b);
+		this.#scopeOrder = [...latest.keys()].sort(compare);
+		const exclusive = [...this.#scopeActivations].filter((activation) => activation.allow).sort((a, b) => compare(a.scope, b.scope) || a.order - b.order).pop();
+		const activated = [GLOBAL_SCOPE, ...this.#scopeOrder];
+		let allowed = [];
+		this.#liveScopes = null;
+		if (exclusive?.allow) {
+			const { allow } = exclusive;
+			const isNested = (scope) => {
+				const seen = /* @__PURE__ */ new Set();
+				for (let current = scope; current !== void 0 && !seen.has(current); current = parents.get(current)) {
+					if (current === exclusive.scope) return true;
+					seen.add(current);
+				}
+				return false;
+			};
+			allowed = activated.filter((scope) => !isNested(scope) && allow.includes(scope));
+			this.#liveScopes = /* @__PURE__ */ new Set([...activated.filter(isNested), ...allowed]);
+		}
+		const live = this.#liveScopes;
+		this.scopes.setState(() => ({
+			active: this.#scopeOrder,
+			exclusive: exclusive?.scope ?? null,
+			allowed,
+			suspended: live ? activated.filter((scope) => !live.has(scope)) : []
+		}));
+		this.#notify();
+	}
+	/** Whether a registration can fire now: enabled, in an active scope. */
+	#isLive(registration) {
+		return registration.options.enabled !== false && this.isScopeActive(registration.options.scope);
+	}
 	/** Notifies subscribers after in-place updates such as counts and sequence progress. */
 	#notify() {
 		this.registrations.setState((prev) => new Map(prev));
@@ -188,21 +315,23 @@ var HotkeyManager = class HotkeyManager {
 			hasFired: false
 		};
 		let registration;
-		if (sequence) registration = {
-			...common,
-			kind: "sequence",
-			hotkey,
-			parsedSequence: hotkey.map((step) => parseHotkey(step, platform)),
-			currentIndex: 0,
-			lastKeyTime: 0
-		};
-		else {
-			const parsedHotkey = typeof hotkey === "string" ? parseHotkey(hotkey, platform) : rawHotkeyToParsedHotkey(hotkey, platform);
+		if (sequence) {
+			const parsedSequence = parseHotkey(hotkey, platform);
+			registration = {
+				...common,
+				kind: "sequence",
+				hotkey: hotkey.map((step, index) => chordString(step, parsedSequence[index])),
+				parsedSequence,
+				currentIndex: 0,
+				lastKeyTime: 0
+			};
+		} else {
+			const parsedChord = parseHotkey(hotkey, platform);
 			registration = {
 				...common,
 				kind: "chord",
-				hotkey: typeof hotkey === "string" ? hotkey : formatHotkey(parsedHotkey),
-				parsedHotkey
+				hotkey: chordString(hotkey, parsedChord),
+				parsedChord
 			};
 		}
 		const conflicting = this.#findConflictingRegistration(registration);
@@ -262,6 +391,35 @@ var HotkeyManager = class HotkeyManager {
 			return next;
 		});
 		this.#listeners.remove(target, !!registration.options.capture, id);
+		this.#clearSequenceReset(id);
+	}
+	/**
+	* Clears a sequence's progress, and notifies subscribers, once its timeout
+	* passes without another step. Key presses check the timeout too, so this
+	* only keeps views such as `matchedStepCount` current.
+	*/
+	#scheduleSequenceReset(id, delay) {
+		this.#clearSequenceReset(id);
+		this.#sequenceResetTimers.set(id, setTimeout(() => {
+			this.#sequenceResetTimers.delete(id);
+			const registration = this.registrations.state.get(id);
+			if (registration?.kind !== "sequence" || registration.currentIndex === 0) return;
+			const timeout = registration.options.timeout ?? 1e3;
+			const remaining = registration.lastKeyTime + timeout - Date.now();
+			if (remaining >= 0) {
+				this.#scheduleSequenceReset(id, remaining + 1);
+				return;
+			}
+			registration.currentIndex = 0;
+			registration.lastKeyTime = 0;
+			this.#notify();
+		}, delay));
+	}
+	#clearSequenceReset(id) {
+		const timer = this.#sequenceResetTimers.get(id);
+		if (timer === void 0) return;
+		clearTimeout(timer);
+		this.#sequenceResetTimers.delete(id);
 	}
 	/** Registrations of one kind in the listener phase, in registration order. */
 	#registrationsIn(ids, capture, kind) {
@@ -298,16 +456,18 @@ var HotkeyManager = class HotkeyManager {
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!registration.options.enabled || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
-			const result = matchKeyboardEvent(event, registration.parsedHotkey, registration.options.platform);
+			if (!this.#isLive(registration) || registration.options.eventType !== eventType || !isEventForTarget(event, target) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target)) continue;
+			const result = matchKeyboardEvent(event, registration.parsedChord, registration.options.platform);
 			if (result.matched) {
 				matches.set(registration.id, result);
 				bestScore = Math.max(bestScore, result.score);
 			}
 		}
+		let bestRank = -1;
+		for (const registration of registrations) if (matches.get(registration.id)?.score === bestScore) bestRank = Math.max(bestRank, this.#scopeRank(registration.options.scope));
 		for (const snapshot of registrations) {
 			const match = matches.get(snapshot.id);
-			if (!match?.matched || match.score !== bestScore) continue;
+			if (!match?.matched || match.score !== bestScore || this.#scopeRank(snapshot.options.scope) !== bestRank) continue;
 			const registration = this.#currentIn(snapshot, capture);
 			if (!registration) continue;
 			this.#consume(registration, event);
@@ -346,7 +506,7 @@ var HotkeyManager = class HotkeyManager {
 		const path = event.composedPath();
 		const now = Date.now();
 		for (const registration of this.registrations.state.values()) {
-			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !registration.options.enabled || registration.options.eventType !== eventType || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
+			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !this.#isLive(registration) || registration.options.eventType !== eventType || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
 			const target = registration.target;
 			if (path.includes(target.nodeType === 1 ? target : getTargetDocument(target)) && !(ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, target)) && matchKeyboardEvent(event, registration.parsedSequence[registration.currentIndex], registration.options.platform).matched) return true;
 		}
@@ -358,6 +518,7 @@ var HotkeyManager = class HotkeyManager {
 			let changed = false;
 			for (const registration of registrations) if (registration.currentIndex > 0) {
 				registration.currentIndex = 0;
+				this.#clearSequenceReset(registration.id);
 				changed = true;
 			}
 			if (changed) this.#notify();
@@ -370,7 +531,7 @@ var HotkeyManager = class HotkeyManager {
 		const candidates = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
-			if (!isEventForTarget(event, target) || !registration.options.enabled || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
+			if (!isEventForTarget(event, target) || !this.#isLive(registration) || ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, registration.target) || registration.options.eventType !== eventType) continue;
 			const timeout = registration.options.timeout ?? 1e3;
 			if (registration.currentIndex > 0 && now - registration.lastKeyTime > timeout) {
 				registration.currentIndex = 0;
@@ -402,12 +563,19 @@ var HotkeyManager = class HotkeyManager {
 					this.#consume(registration, event);
 					registration.currentIndex = 0;
 					completed.push(registration);
-				}
+				} else if (registration.options.preventDefault) event.preventDefault();
 			} else if (registration.currentIndex > 0) {
 				registration.currentIndex = 0;
 				changed = true;
 			}
 		}
+		for (const registration of registrations) {
+			if (!candidates.has(registration.id)) continue;
+			if (registration.currentIndex > 0) {
+				const timeout = registration.options.timeout ?? 1e3;
+				this.#scheduleSequenceReset(registration.id, timeout + 1);
+			} else this.#clearSequenceReset(registration.id);
+		}
 		if (changed && completed.length === 0) this.#notify();
 		for (const snapshot of completed) {
 			const registration = this.#currentIn(snapshot, capture);
@@ -427,26 +595,31 @@ var HotkeyManager = class HotkeyManager {
 		registration.callback(event, context);
 	}
 	#callbackContext(registration) {
-		return {
+		return registration.kind === "chord" ? {
+			kind: "chord",
+			hotkey: registration.hotkey,
+			parsedChord: registration.parsedChord
+		} : {
+			kind: "sequence",
 			hotkey: registration.hotkey,
-			parsedHotkey: registration.kind === "chord" ? registration.parsedHotkey : registration.parsedSequence[registration.parsedSequence.length - 1]
+			parsedSequence: registration.parsedSequence
 		};
 	}
 	/**
-	* Finds an existing registration on the same target whose steps resolve to
-	* the same identity. Each side keeps its own platform, so `Mod+S` on macOS
+	* Finds an existing registration on the same target and scope whose steps
+	* resolve to the same identity. Each side keeps its own platform, so `Mod+S` on macOS
 	* and `Mod+S` on Windows are different bindings.
 	*/
 	#findConflictingRegistration(candidate) {
 		const steps = resolvedSteps(candidate);
-		for (const registration of this.registrations.state.values()) if (registration.target === candidate.target && sameResolvedSteps(resolvedSteps(registration), steps)) return registration;
+		for (const registration of this.registrations.state.values()) if (registration.target === candidate.target && registration.options.scope === candidate.options.scope && sameResolvedSteps(resolvedSteps(registration), steps)) return registration;
 		return null;
 	}
 	/**
 	* Determines if a registration should be reset based on the keyup event.
 	*/
 	#shouldResetRegistration(registration, event) {
-		const parsed = registration.parsedHotkey;
+		const parsed = registration.parsedChord;
 		const releasedKey = normalizeKeyName(event.key);
 		if (registration.activeMatch?.code && event.code === registration.activeMatch.code) return true;
 		return (parsed.code !== void 0 ? event.code === parsed.code : keysEqual(releasedKey, parsed.key)) || parsed.modifiers.includes(releasedKey);
@@ -459,6 +632,8 @@ var HotkeyManager = class HotkeyManager {
 			registration.currentIndex = 0;
 			registration.lastKeyTime = 0;
 		}
+		for (const timer of this.#sequenceResetTimers.values()) clearTimeout(timer);
+		this.#sequenceResetTimers.clear();
 		this.#notify();
 	}
 	/**
@@ -473,7 +648,7 @@ var HotkeyManager = class HotkeyManager {
 		const registration = this.registrations.state.get(id);
 		if (!registration) return false;
 		const context = this.#callbackContext(registration);
-		const parsed = context.parsedHotkey;
+		const parsed = registration.kind === "chord" ? registration.parsedChord : registration.parsedSequence[registration.parsedSequence.length - 1];
 		const syntheticEvent = new KeyboardEvent(registration.options.eventType ?? "keydown", {
 			...parsed.code !== void 0 ? { code: parsed.code } : { key: parsed.key },
 			ctrlKey: parsed.ctrl,
@@ -507,6 +682,8 @@ var HotkeyManager = class HotkeyManager {
 	* Destroys the manager and removes all listeners.
 	*/
 	destroy() {
+		for (const timer of this.#sequenceResetTimers.values()) clearTimeout(timer);
+		this.#sequenceResetTimers.clear();
 		this.#listeners.destroy();
 		this.registrations.setState(() => /* @__PURE__ */ new Map());
 		this.appHotkeys.setState(() => null);

package/dist/hotkey-recorder.d.ts

@@ -1,4 +1,4 @@
-import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkey } from "./hotkey.types.js";
+import { Hotkey, HotkeyChord, HotkeySequence, ParsedHotkeyChord } from "./hotkey.types.js";
 import { HotkeyConflict, HotkeyConflictOptions } from "./conflicts.js";
 import { Store } from "@tanstack/store";
 //#region src/hotkey-recorder.d.ts
@@ -21,17 +21,27 @@ export interface RecorderOptions {
   /** Rejected candidates leave recording active. */
   onReject?: (rejection: RecorderRejection) => void;
 }
-/** Validation context for a recorded chord or sequence. */
-export interface HotkeyRecorderValidationContext {
-  /** The event that recorded the last chord. */
+/** Validation context for a recorded chord. */
+export interface HotkeyChordRecorderValidationContext {
+  kind: 'chord';
+  /** The event that recorded the chord. */
   event: KeyboardEvent;
-  /** The last chord, parsed. */
-  parsedHotkey: ParsedHotkey;
+  /** The chord with `Mod` resolved for the recorder's platform. */
+  parsedChord: ParsedHotkeyChord;
+}
+/** Validation context for a recorded sequence. */
+export interface HotkeySequenceRecorderValidationContext {
+  kind: 'sequence';
   /** The event that recorded each step. */
   events: ReadonlyArray<KeyboardEvent>;
-  /** Every step, parsed. */
-  parsedSequence: ReadonlyArray<ParsedHotkey>;
+  /** Each step with `Mod` resolved for the recorder's platform. */
+  parsedSequence: Array<ParsedHotkeyChord>;
 }
+/**
+ * Validation context for a recorded chord or sequence. Narrow with `kind` to
+ * read `parsedChord` or `parsedSequence`.
+ */
+export type HotkeyRecorderValidationContext = HotkeyChordRecorderValidationContext | HotkeySequenceRecorderValidationContext;
 /**
  * State interface for the HotkeyRecorder.
  */
@@ -65,7 +75,7 @@ export interface HotkeyChordRecorderOptions extends HotkeyRecorderBaseOptions {
   /** Maximum number of chords to record. Default: 1 */
   maxSteps?: 1;
   /** Return true to accept, or false/a message to reject while staying in recording mode. */
-  validate?: (hotkey: HotkeyChord, context: HotkeyRecorderValidationContext) => boolean | string;
+  validate?: (hotkey: HotkeyChord, context: HotkeyChordRecorderValidationContext) => boolean | string;
   /** Callback when a chord is successfully recorded */
   onRecord: (hotkey: HotkeyChord) => void;
 }
@@ -113,7 +123,7 @@ export type HotkeyRecorderOptions = HotkeyChordRecorderOptions | HotkeySequenceR
  * })
  *
  * const sequenceRecorder = new HotkeyRecorder({
- *   maxSteps: 3,
+ *   maxSteps: Infinity,
  *   onRecord: (hotkey) => {
  *     console.log('Recorded:', hotkey) // 'Mod+S' or ['G', 'H']
  *   },