rx-hotkeys 2.4.1 → 2.5.0

package/dist/hotkeys.d.ts

@@ -34,15 +34,19 @@ type KeyCombinationTrigger = {
 } | StandardKey;
 export interface KeyCombinationConfig extends ShortcutConfigBase {
     /**
-     * Defines the key or key combination.
-     * Can be an object specifying the main `key` (from `StandardKey`) and optional
+     * Defines the key or key combination(s) that trigger the shortcut.
+     * Can be a single trigger or an array of triggers.
+     * Each trigger can be an object specifying the main `key` (from `StandardKey`) and optional
      * modifiers (`ctrlKey`, `altKey`, `shiftKey`, `metaKey`).
      * Example: `{ key: Keys.S, ctrlKey: true }` for Ctrl+S.
      *
-     * Alternatively, for a simple key press without any modifiers, this can be
+     * Alternatively, for a simple key press without any modifiers, a trigger can be
      * a `StandardKey` directly.
      * Example: `Keys.Escape` for the Escape key. When using this shorthand,
      * it implies that no modifier keys (Ctrl, Alt, Shift, Meta) should be active.
+     *
+     * To define multiple triggers for the same action:
+     * Example: `keys: [Keys.Enter, { key: Keys.Space, ctrlKey: true }]`
      */
     keys: KeyCombinationTrigger | KeyCombinationTrigger[];
 }
@@ -95,7 +99,7 @@ export declare class Hotkeys {
      * will be active and can be triggered.
      * @param contextName - The name of the context (e.g., "modal", "editor", "global").
      * Pass `null` to activate shortcuts with no context or to deactivate context-specific shortcuts.
-     * @returns boolean
+     * @returns `true` if the context was changed, `false` if the new context was the same as the current one.
      */
     setContext(contextName: string | null): boolean;
     /**
@@ -109,6 +113,12 @@ export declare class Hotkeys {
      * @param enable - True to enable debug logs, false to disable.
      */
     setDebugMode(enable: boolean): void;
+    /**
+     * Checks if a shortcut with the given ID is currently registered and active.
+     * @param id - The unique ID of the shortcut to check.
+     * @returns True if a shortcut with the specified ID exists, false otherwise.
+     */
+    hasShortcut(id: string): boolean;
     /**
      * An Observable that emits the new context name (or null) whenever the active context changes.
      * This allows external parts of the application to react to context transitions.
@@ -129,11 +139,20 @@ export declare class Hotkeys {
      */
     get onContextChange$(): Observable<string | null>;
     /**
-     * Checks if a shortcut with the given ID is currently registered and active.
-     * @param id - The unique ID of the shortcut to check.
-     * @returns True if a shortcut with the specified ID exists, false otherwise.
+     * Compares two sequences of StandardKey arrays to see if they are identical.
+     * @param seq1 - The first sequence array.
+     * @param seq2 - The second sequence array.
+     * @returns True if the sequences are identical, false otherwise.
      */
-    hasShortcut(id: string): boolean;
+    private _areSequencesIdentical;
+    /**
+     * Checks if a given KeyCombinationConfig matches a given KeyboardEvent.
+     * This is used internally for priority checking.
+     * @param shortcutConfig The KeyCombinationConfig to check.
+     * @param event The KeyboardEvent to match against.
+     * @returns True if the shortcutConfig matches the event, false otherwise.
+     */
+    private _shortcutMatchesEvent;
     private filterByContext;
     private _registerShortcut;
     /**
@@ -162,10 +181,10 @@ export declare class Hotkeys {
      * callback: () => console.log("File saved!"),
      * context: "editor"
      * });
-     * // For just the Escape key
+     * // For just the Escape key, or Ctrl+Space
      * keyManager.addCombination({
      * id: "closeModal",
-     * keys: Keys.Escape, // Shorthand syntax
+     * keys: [Keys.Escape, {key: Keys.Space, ctrlKey: true}],
      * callback: () => console.log("Modal closed!")
      * });
      * ```
@@ -205,7 +224,7 @@ export declare class Hotkeys {
      * This can be useful for displaying available shortcuts to the user or for debugging.
      * @returns An array of objects, where each object represents an active shortcut
      * and includes its `id`, `description` (if provided), `context` (if any),
-     * and `type` ("combination" or "sequence").
+     * and `type` (from `ShortcutTypes` enum).
      */
     getActiveShortcuts(): {
         id: string;

package/dist/hotkeys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../src/hotkeys.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../src/hotkeys.ts"],"names":[],"mappings":"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"}

package/dist/hotkeys.js

@@ -5,6 +5,12 @@ export var ShortcutTypes;
     ShortcutTypes["Combination"] = "combination";
     ShortcutTypes["Sequence"] = "sequence";
 })(ShortcutTypes || (ShortcutTypes = {}));
+var EmitStates;
+(function (EmitStates) {
+    EmitStates[EmitStates["Emit"] = 0] = "Emit";
+    EmitStates[EmitStates["Ignore"] = 1] = "Ignore";
+    EmitStates[EmitStates["InProgress"] = 2] = "InProgress";
+})(EmitStates || (EmitStates = {}));
 // --- Helper function to compare keys ---
 /**
  * Compares a browser event's key with a configured key.
@@ -21,12 +27,6 @@ function compareKey(eventKey, configuredKey) {
     return eventKey === configuredKey;
 }
 // --- Hotkeys Library ---
-var EmitStates;
-(function (EmitStates) {
-    EmitStates[EmitStates["Emit"] = 0] = "Emit";
-    EmitStates[EmitStates["Ignore"] = 1] = "Ignore";
-    EmitStates[EmitStates["InProgress"] = 2] = "InProgress";
-})(EmitStates || (EmitStates = {}));
 /**
  * Manages keyboard shortcuts for web applications.
  * Allows registration of single key combinations (e.g., Ctrl+S) and key sequences (e.g., g -> i).
@@ -63,7 +63,7 @@ export class Hotkeys {
      * will be active and can be triggered.
      * @param contextName - The name of the context (e.g., "modal", "editor", "global").
      * Pass `null` to activate shortcuts with no context or to deactivate context-specific shortcuts.
-     * @returns boolean
+     * @returns `true` if the context was changed, `false` if the new context was the same as the current one.
      */
     setContext(contextName) {
         const currentContext = this.activeContext$.getValue();
@@ -72,14 +72,14 @@ export class Hotkeys {
                 // Optional: Log that no change is happening, or simply do nothing.
                 console.log(`${Hotkeys.LOG_PREFIX} setContext called with the same context "${contextName}". No change made.`);
             }
-            return false; // Context is the same, so no further action is needed.
+            return false; // Context was NOT updated
         }
         // If we reach here, the context is actually changing.
         if (this.debugMode) {
             console.log(`${Hotkeys.LOG_PREFIX} Context changed from "${currentContext}" to "${contextName}".`);
         }
         this.activeContext$.next(contextName);
-        return true;
+        return true; // Context WAS updated
     }
     /**
      * Gets the current active context.
@@ -94,17 +94,25 @@ export class Hotkeys {
      * @param enable - True to enable debug logs, false to disable.
      */
     setDebugMode(enable) {
-        if (this.debugMode === enable) { // Check if state is actually changing
-            return; // If no change, do nothing (no log)
+        if (this.debugMode === enable) {
+            return;
         }
-        this.debugMode = enable; // Set the new state
-        if (enable) { // Log based on the NEW state after a change
+        this.debugMode = enable;
+        if (enable) {
             console.log(`${Hotkeys.LOG_PREFIX} Debug mode enabled.`);
         }
         else {
             console.log(`${Hotkeys.LOG_PREFIX} Debug mode disabled.`);
         }
     }
+    /**
+     * Checks if a shortcut with the given ID is currently registered and active.
+     * @param id - The unique ID of the shortcut to check.
+     * @returns True if a shortcut with the specified ID exists, false otherwise.
+     */
+    hasShortcut(id) {
+        return this.activeShortcuts.has(id);
+    }
     /**
      * An Observable that emits the new context name (or null) whenever the active context changes.
      * This allows external parts of the application to react to context transitions.
@@ -127,18 +135,72 @@ export class Hotkeys {
         return this.activeContext$.asObservable();
     }
     /**
-     * Checks if a shortcut with the given ID is currently registered and active.
-     * @param id - The unique ID of the shortcut to check.
-     * @returns True if a shortcut with the specified ID exists, false otherwise.
+     * Compares two sequences of StandardKey arrays to see if they are identical.
+     * @param seq1 - The first sequence array.
+     * @param seq2 - The second sequence array.
+     * @returns True if the sequences are identical, false otherwise.
      */
-    hasShortcut(id) {
-        return this.activeShortcuts.has(id);
+    _areSequencesIdentical(seq1, seq2) {
+        if (seq1.length !== seq2.length) {
+            return false;
+        }
+        for (let i = 0; i < seq1.length; i++) {
+            if (seq1[i] !== seq2[i]) { // Direct comparison for canonical StandardKey values
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Checks if a given KeyCombinationConfig matches a given KeyboardEvent.
+     * This is used internally for priority checking.
+     * @param shortcutConfig The KeyCombinationConfig to check.
+     * @param event The KeyboardEvent to match against.
+     * @returns True if the shortcutConfig matches the event, false otherwise.
+     */
+    _shortcutMatchesEvent(shortcutConfig, event) {
+        const keyTriggers = Array.isArray(shortcutConfig.keys) ? shortcutConfig.keys : [shortcutConfig.keys];
+        for (const keyInput of keyTriggers) {
+            let configuredMainKey;
+            let ctrlKeyConfig;
+            let altKeyConfig;
+            let shiftKeyConfig;
+            let metaKeyConfig;
+            if (typeof keyInput === "string") {
+                if (keyInput === "")
+                    continue; // Invalid trigger, skip
+                configuredMainKey = keyInput;
+                ctrlKeyConfig = false;
+                altKeyConfig = false;
+                shiftKeyConfig = false;
+                metaKeyConfig = false;
+            }
+            else {
+                if (!keyInput.key || keyInput.key === "")
+                    continue; // Invalid trigger, skip
+                configuredMainKey = keyInput.key;
+                ctrlKeyConfig = keyInput.ctrlKey;
+                altKeyConfig = keyInput.altKey;
+                shiftKeyConfig = keyInput.shiftKey;
+                metaKeyConfig = keyInput.metaKey;
+            }
+            const keyMatch = compareKey(event.key, configuredMainKey);
+            if (!keyMatch)
+                continue;
+            const ctrlMatch = (ctrlKeyConfig === undefined) ? true : (event.ctrlKey === ctrlKeyConfig);
+            const altMatch = (altKeyConfig === undefined) ? true : (event.altKey === altKeyConfig);
+            const shiftMatch = (shiftKeyConfig === undefined) ? true : (event.shiftKey === shiftKeyConfig);
+            const metaMatch = (metaKeyConfig === undefined) ? true : (event.metaKey === metaKeyConfig);
+            if (ctrlMatch && altMatch && shiftMatch && metaMatch) {
+                return true;
+            }
+        }
+        return false;
     }
     filterByContext(source$, context) {
         return source$.pipe(withLatestFrom(this.activeContext$), filter(([/* event */ , activeCtx]) => context == null || context === activeCtx), map(([event, /* _activeCtx */]) => event));
     }
-    _registerShortcut(config, subscription, type, // Changed to use Enum
-    detailsForLog) {
+    _registerShortcut(config, subscription, type, detailsForLog) {
         const existingShortcut = this.activeShortcuts.get(config.id);
         if (existingShortcut) {
             console.warn(`${Hotkeys.LOG_PREFIX} Shortcut with ID "${config.id}" already exists. It will be overwritten.`);
@@ -163,11 +225,18 @@ export class Hotkeys {
                 console.warn(`${Hotkeys.LOG_PREFIX} Invalid key (shorthand) in shortcut "${shortcutId}". Key string must not be empty.`);
                 return null;
             }
-            return { configuredMainKey: keyInput, ctrlKeyConfig: false, altKeyConfig: false, shiftKeyConfig: false, metaKeyConfig: false, logDetails: `key: "${keyInput}" (no mods)` };
+            return {
+                configuredMainKey: keyInput,
+                ctrlKeyConfig: false,
+                altKeyConfig: false,
+                shiftKeyConfig: false,
+                metaKeyConfig: false,
+                logDetails: `key: "${keyInput}" (no mods)`,
+            };
         }
         else {
-            if (!keyInput.key || keyInput.key === "") {
-                console.warn(`${Hotkeys.LOG_PREFIX} Invalid "key" property in shortcut "${shortcutId}". Key must be a non-empty value from Keys.`);
+            if (!keyInput.key || typeof keyInput.key !== "string" || keyInput.key === "") {
+                console.warn(`${Hotkeys.LOG_PREFIX} Invalid "key" property in shortcut "${shortcutId}". Key must be a non-empty string value from Keys.`);
                 return null;
             }
             const logDetails = `key: "${keyInput.key}"` +
@@ -175,7 +244,14 @@ export class Hotkeys {
                 (keyInput.altKey !== undefined ? `, alt: ${keyInput.altKey}` : "") +
                 (keyInput.shiftKey !== undefined ? `, shift: ${keyInput.shiftKey}` : "") +
                 (keyInput.metaKey !== undefined ? `, meta: ${keyInput.metaKey}` : "");
-            return { configuredMainKey: keyInput.key, ctrlKeyConfig: keyInput.ctrlKey, altKeyConfig: keyInput.altKey, shiftKeyConfig: keyInput.shiftKey, metaKeyConfig: keyInput.metaKey, logDetails };
+            return {
+                configuredMainKey: keyInput.key,
+                ctrlKeyConfig: keyInput.ctrlKey,
+                altKeyConfig: keyInput.altKey,
+                shiftKeyConfig: keyInput.shiftKey,
+                metaKeyConfig: keyInput.metaKey,
+                logDetails,
+            };
         }
     }
     /**
@@ -196,10 +272,10 @@ export class Hotkeys {
      * callback: () => console.log("File saved!"),
      * context: "editor"
      * });
-     * // For just the Escape key
+     * // For just the Escape key, or Ctrl+Space
      * keyManager.addCombination({
      * id: "closeModal",
-     * keys: Keys.Escape, // Shorthand syntax
+     * keys: [Keys.Escape, {key: Keys.Space, ctrlKey: true}],
      * callback: () => console.log("Modal closed!")
      * });
      * ```
@@ -229,7 +305,30 @@ export class Hotkeys {
                 const shiftMatch = (shiftKeyConfig === undefined) ? true : (event.shiftKey === shiftKeyConfig);
                 const metaMatch = (metaKeyConfig === undefined) ? true : (event.metaKey === metaKeyConfig);
                 return ctrlMatch && altMatch && shiftMatch && metaMatch;
-            }), filter(event => compareKey(event.key, configuredMainKey)));
+            }), filter(event => compareKey(event.key, configuredMainKey)), 
+            // New filter for priority: Specific context > Global context
+            filter(event => {
+                if (config.context != null) { // This shortcut is NOT global
+                    return true;
+                }
+                // This shortcut IS global. Check for specific overrides.
+                const currentSpecificContext = this.activeContext$.getValue();
+                if (currentSpecificContext == null) { // No specific context active
+                    return true;
+                }
+                for (const [, otherAS] of this.activeShortcuts) {
+                    if (otherAS.config.id !== config.id &&
+                        'keys' in otherAS.config &&
+                        otherAS.config.context === currentSpecificContext &&
+                        this._shortcutMatchesEvent(otherAS.config, event)) {
+                        if (this.debugMode) {
+                            console.log(`${Hotkeys.LOG_PREFIX} Global shortcut "${config.id}" (key: "${event.key}") suppressed by specific context shortcut "${otherAS.config.id}".`);
+                        }
+                        return false; // Suppress global
+                    }
+                }
+                return true; // Global can proceed
+            }));
             observables.push(stream);
         }
         if (observables.length === 0) {
@@ -320,7 +419,7 @@ export class Hotkeys {
                 if (compareKey(event.key, configuredSequence[nextExpectedKeyIndex])) {
                     const newMatchedEvents = [...matchedEvents, event];
                     if (newMatchedEvents.length === sequenceLength) {
-                        if (this.debugMode && !acc.emitState)
+                        if (this.debugMode && acc.emitState !== EmitStates.Emit)
                             console.log(`${Hotkeys.LOG_PREFIX} Sequence "${id}" (timeout: ${sequenceTimeoutMs}ms) matched.`);
                         return { matchedEvents: newMatchedEvents, lastEventTime: currentTime, emitState: EmitStates.Emit };
                     }
@@ -350,7 +449,28 @@ export class Hotkeys {
                 return events.every((event, index) => compareKey(event.key, configuredSequence[index]));
             }));
         }
-        const finalShortcut$ = shortcut$.pipe(tap((events) => {
+        const finalShortcutWithPriority$ = shortcut$.pipe(filter((completedEvents) => {
+            if (config.context != null) { // This sequence is NOT global
+                return true;
+            }
+            // This sequence IS global. Check for specific overrides.
+            const currentSpecificContext = this.activeContext$.getValue();
+            if (currentSpecificContext == null) { // No specific context active
+                return true;
+            }
+            for (const [, otherAS] of this.activeShortcuts) {
+                if (otherAS.config.id !== config.id &&
+                    "sequence" in otherAS.config &&
+                    otherAS.config.context === currentSpecificContext &&
+                    this._areSequencesIdentical(config.sequence, otherAS.config.sequence)) {
+                    if (this.debugMode) {
+                        console.log(`${Hotkeys.LOG_PREFIX} Global sequence shortcut "${config.id}" suppressed by identical specific-context shortcut "${otherAS.config.id}".`);
+                    }
+                    return false; // Suppress global
+                }
+            }
+            return true; // Global sequence can proceed
+        }), tap((events) => {
             if (this.debugMode) {
                 const timeoutInfo = (sequenceTimeoutMs && sequenceTimeoutMs > 0) ? ` (with timeout logic)` : ` (no timeout logic)`;
                 const preventAction = preventDefault ? ", preventing default for last event" : "";
@@ -363,7 +483,7 @@ export class Hotkeys {
             console.error(`${Hotkeys.LOG_PREFIX} Error in sequence stream for shortcut "${id}":`, err);
             return EMPTY;
         }));
-        const subscription = finalShortcut$.subscribe((events) => {
+        const subscription = finalShortcutWithPriority$.subscribe((events) => {
             try {
                 // Ensure callback receives the last event of the sequence, similar to combination.
                 if (events.length > 0)
@@ -374,7 +494,7 @@ export class Hotkeys {
             }
         });
         const logDetails = `Sequence: ${sequence.join(" -> ")}${sequenceTimeoutMs && sequenceTimeoutMs > 0 ? ` (timeout: ${sequenceTimeoutMs}ms)` : ""}`;
-        return this._registerShortcut(config, subscription, ShortcutTypes.Sequence, logDetails); // Use Enum
+        return this._registerShortcut(config, subscription, ShortcutTypes.Sequence, logDetails);
     }
     /**
      * Removes a registered shortcut by its ID.
@@ -400,7 +520,7 @@ export class Hotkeys {
      * This can be useful for displaying available shortcuts to the user or for debugging.
      * @returns An array of objects, where each object represents an active shortcut
      * and includes its `id`, `description` (if provided), `context` (if any),
-     * and `type` ("combination" or "sequence").
+     * and `type` (from `ShortcutTypes` enum).
      */
     getActiveShortcuts() {
         const shortcuts = [];
@@ -409,7 +529,7 @@ export class Hotkeys {
                 id,
                 description: activeShortcut.config.description,
                 context: activeShortcut.config.context,
-                type: ("sequence" in activeShortcut.config) ? ShortcutTypes.Sequence : ShortcutTypes.Combination // Use Enum values
+                type: ("sequence" in activeShortcut.config) ? ShortcutTypes.Sequence : ShortcutTypes.Combination
             });
         }
         return shortcuts;
@@ -425,7 +545,7 @@ export class Hotkeys {
             console.log(`${Hotkeys.LOG_PREFIX} Destroying library instance and unsubscribing all shortcuts.`);
         this.activeShortcuts.forEach(shortcut => shortcut.subscription.unsubscribe());
         this.activeShortcuts.clear();
-        this.activeContext$.complete(); // Complete the BehaviorSubject to release its resources
+        this.activeContext$.complete();
         if (this.debugMode)
             console.log(`${Hotkeys.LOG_PREFIX} Library destroyed.`);
     }

package/dist/hotkeys.test.js

@@ -257,7 +257,7 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             const result = keyManager.addCombination(config);
             assert.strictEqual(result, undefined, "Should return undefined for null key");
             assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
-            assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid "key" property in shortcut "nullKey". Key must be a non-empty value from Keys.`));
+            assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid "key" property in shortcut "nullKey". Key must be a non-empty string value from Keys.`));
         });
         it("should pass the KeyboardEvent to the callback", () => {
             const config = { id: "eventPass", keys: { key: Keys.E }, callback: mockCallback };
@@ -442,6 +442,84 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             });
         });
     });
+    describe("Context Priority (Specific > Global)", () => {
+        let globalCallback;
+        let specificCallback;
+        beforeEach(() => {
+            globalCallback = createMockFn();
+            specificCallback = createMockFn();
+            // Global shortcut: Ctrl+G
+            keyManager.addCombination({
+                id: "globalCtrlG",
+                keys: { key: Keys.G, ctrlKey: true },
+                callback: globalCallback,
+                context: null // Explicitly global
+            });
+            // Specific context shortcut: Ctrl+G in "editor" context
+            keyManager.addCombination({
+                id: "editorCtrlG",
+                keys: { key: Keys.G, ctrlKey: true },
+                callback: specificCallback,
+                context: "editor"
+            });
+        });
+        it("should only trigger specific context callback when specific context is active", () => {
+            keyManager.setContext("editor");
+            dispatchKeyEvent(Keys.G, { ctrlKey: true });
+            assert.strictEqual(specificCallback.calledCount, 1, "Specific callback should have been called");
+            assert.strictEqual(globalCallback.calledCount, 0, "Global callback should NOT have been called");
+        });
+        it("should only trigger global callback when no specific context is active (or context doesn't match)", () => {
+            keyManager.setContext(null); // No specific context
+            dispatchKeyEvent(Keys.G, { ctrlKey: true });
+            assert.strictEqual(specificCallback.calledCount, 0, "Specific callback should NOT have been called");
+            assert.strictEqual(globalCallback.calledCount, 1, "Global callback should have been called");
+            globalCallback.mockClear();
+            keyManager.setContext("anotherContext"); // Different specific context
+            dispatchKeyEvent(Keys.G, { ctrlKey: true });
+            assert.strictEqual(specificCallback.calledCount, 0, `Specific callback should NOT have been called for "anotherContext"`);
+            assert.strictEqual(globalCallback.calledCount, 1, `Global callback should have been called when in "anotherContext"`);
+        });
+    });
+    describe("Sequence Context Priority (Specific > Global)", () => {
+        let globalSeqCallback;
+        let specificSeqCallback;
+        const testSequence = [Keys.G, Keys.I];
+        beforeEach(() => {
+            globalSeqCallback = createMockFn();
+            specificSeqCallback = createMockFn();
+            keyManager.addSequence({
+                id: "globalGI",
+                sequence: testSequence,
+                callback: globalSeqCallback,
+                context: null // Global
+            });
+            keyManager.addSequence({
+                id: "editorGI",
+                sequence: testSequence,
+                callback: specificSeqCallback,
+                context: "editor" // Specific
+            });
+        });
+        it("should only trigger specific context sequence callback when specific context is active", () => {
+            keyManager.setContext("editor");
+            testSequence.forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(specificSeqCallback.calledCount, 1, "Specific sequence callback should have been called");
+            assert.strictEqual(globalSeqCallback.calledCount, 0, "Global sequence callback should NOT have been called");
+        });
+        it("should only trigger global sequence callback when no specific context is active (or context doesn't match)", () => {
+            keyManager.setContext(null); // No specific context
+            testSequence.forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(specificSeqCallback.calledCount, 0, "Specific sequence callback should NOT have been called");
+            assert.strictEqual(globalSeqCallback.calledCount, 1, "Global sequence callback should have been called");
+            globalSeqCallback.mockClear();
+            specificSeqCallback.mockClear(); // Clear for next part of test
+            keyManager.setContext("anotherContext"); // Different specific context
+            testSequence.forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(specificSeqCallback.calledCount, 0, `Specific sequence callback should NOT have been called for "anotherContext"`);
+            assert.strictEqual(globalSeqCallback.calledCount, 1, `Global sequence callback should have been called when in "anotherContext"`);
+        });
+    });
     describe("addSequence", () => {
         it("should trigger callback for a simple key sequence", () => {
             const config = { id: "seqGI", sequence: [Keys.G, Keys.I], callback: mockCallback };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rx-hotkeys",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "type": "module",
   "scripts": {
     "build": "tsc",