rx-hotkeys 2.4.1 → 2.6.0

package/README.md

@@ -8,6 +8,7 @@ rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard s
 * **Key Sequences:** Define shortcuts that trigger when a series of keys are pressed in a specific order.
 * **Sequence Timeouts:** Optional timeout between key presses in a sequence to prevent accidental triggers or indefinite waiting.
 * **Context Management:** Activate or deactivate groups of shortcuts based on the application's current state (e.g., "editor", "modal", "global").
+* **Strict Global Shortcuts:** Option to register global shortcuts that *only* fire when no other context is active, preventing them from triggering unintentionally.
 * **Type-Safe Key Definitions:** Uses an exported `Keys` object based on standard `KeyboardEvent.key` values for improved developer experience and fewer errors.
 * **RxJS Powered:** Built on RxJS for robust and efficient event handling.
 * **Prevent Default:** Option to prevent the default browser action for a triggered shortcut.
@@ -29,7 +30,7 @@ First, ensure you have the `rx-hotkeys` library and its helper Keys imported:
 import { Hotkeys, Keys, KeyCombinationConfig, KeySequenceConfig } from 'rx-hotkeys';
 ```
 
-1. Initialize Hotkeys
+### 1. Initialize Hotkeys
 
 Create an instance of the `Hotkeys` class. You can optionally provide an initial context and enable debug mode.
 
@@ -40,7 +41,7 @@ const keyManager = new Hotkeys(); // No initial context, debug mode off
 // const keyManager = new Hotkeys('editor', true);
 ```
 
-2. Add a Key Combination
+### 2. Add a Key Combination
 
 Register a shortcut for a key combination, like Ctrl+S.
 
@@ -58,7 +59,9 @@ const saveConfig: KeyCombinationConfig = {
 keyManager.addCombination(saveConfig);
 ```
 
-3. Add a Key SequenceRegister a shortcut for a sequence of keys, like the Konami code.
+### 3. Add a Key Sequence
+
+Register a shortcut for a sequence of keys, like the Konami code.
 
 ```typescript
 const konamiConfig: KeySequenceConfig = {
@@ -81,7 +84,9 @@ const konamiConfig: KeySequenceConfig = {
 keyManager.addSequence(konamiConfig);
 ```
 
-4. Manage ContextsControl which shortcuts are active by setting the context.
+### 4. Manage Contexts
+
+Control which shortcuts are active by setting the context.
 
 ```typescript
 // Assuming some shortcuts are configured with context: "editor"
@@ -91,7 +96,25 @@ keyManager.setContext("editor"); // Activates "editor" shortcuts and global shor
 keyManager.setContext(null);
 ```
 
-5. Clean Up
+#### Global vs. Strict Global Shortcuts
+
+Global shortcuts (those without a `context` property) have two behaviors:
+
+* **Default Global**: By default, a global shortcut will fire in *any* context, unless a more specific shortcut for the same key combination exists for that context.
+
+    ```typescript
+    // This shortcut for Ctrl+P will fire in the "editor" context, "modal" context, or any other,
+    // unless a specific "editor" shortcut for Ctrl+P exists.
+    keyManager.addCombination({ id: 'globalPrint', keys: { key: Keys.P, ctrlKey: true }, callback: myCallback });
+    ```
+* **Strict Global**: By passing `true` as the second argument to `addCombination` or `addSequence`, you can register a "strict" global shortcut. This shortcut will **only** fire when no context is active (`keyManager.getContext()` returns `null`).
+
+    ```typescript
+    // This help shortcut for "?" will ONLY fire when no other context is active.
+    keyManager.addCombination({ id: 'strictHelp', keys: Keys.QuestionMark, callback: openHelpModal }, true);
+    ```
+
+### 5. Clean Up
 
 When the Hotkeys instance is no longer needed (e.g., component unmount), call `destroy()` to clean up subscriptions and prevent memory leaks.
 
@@ -170,6 +193,7 @@ Cleans up all subscriptions and resources. Essential to call to prevent memory l
 * `context?: string | null`: Specifies the context in which this shortcut is active. If `null` or `undefined`, it's a global shortcut.
 * `preventDefault?: boolean`: If true, `event.preventDefault()` will be called when the shortcut triggers. Defaults to `false`.
 * `description?: string`: An optional description for the shortcut (e.g., for help menus).
+* `strict?: boolean` (optional): If `true` and the shortcut has no `context`, it will only fire when no other context is active. Defaults to `false`.
 
 `KeySequenceConfig`
 
@@ -180,13 +204,13 @@ Cleans up all subscriptions and resources. Essential to call to prevent memory l
 * `preventDefault?: boolean`: If true, `event.preventDefault()` is called for the last event in the sequence. Defaults to `false`.
 * `description?: string`: Optional description.
 * `sequenceTimeoutMs?: number`: Optional. Maximum time (in milliseconds) allowed between consecutive key presses in the sequence. If exceeded, the sequence resets. If `0` or `undefined`, no inter-key timeout is applied (uses simpler buffer-based matching).
+* `strict?: boolean` (optional): If `true` and the shortcut has no `context`, it will only fire when no other context is active. Defaults to `false`.
 
 
 ## Key Matching Logic
 
-* Single Character Keys (e.g., `Keys.A`, `Keys.Digit7`): When you configure a shortcut with a single character key from `Keys`, the library matches it case-insensitively against the `event.key` from the browser. For example, if you configure `Keys.A`, it will trigger for both "a" and "A" key presses (assuming Shift isn't a required modifier).
-* Special Keys (e.g., `Keys.Enter`, `Keys.ArrowUp`, `Keys.Escape`): These are multi-character `event.key` values. The library matches these case-sensitively against the `event.key`. Using the `Keys` object ensures you provide the correct, standard case-sensitive string.
-
+* **Single Character Keys** (e.g., `Keys.A`, `Keys.Digit7`): When you configure a shortcut with a single character key from `Keys`, the library matches it case-insensitively against the `event.key` from the browser. For example, if you configure `Keys.A`, it will trigger for both "a" and "A" key presses (assuming Shift isn't a required modifier).
+* **Special Keys** (e.g., `Keys.Enter`, `Keys.ArrowUp`, `Keys.Escape`): These are multi-character `event.key` values. The library matches these case-sensitively against the `event.key`. Using the `Keys` object ensures you provide the correct, standard case-sensitive string.
 
 ## Contributing
 

package/dist/hotkeys.d.ts

@@ -10,6 +10,15 @@ interface ShortcutConfigBase {
     context?: string | null;
     preventDefault?: boolean;
     description?: string;
+    /**
+     * **Only applicable if the shortcut has no top-level `context` defined.**
+     * If `true`, this shortcut is **strictly global** and will only fire when the active
+     * hotkey context is `null`.
+     * If `false` or `undefined` (the default), the shortcut can fire in *any* context,
+     * but will be suppressed by an identical shortcut that belongs to the active context.
+     * @default false
+     */
+    strict?: boolean;
 }
 /**
  * Defines a single key trigger, which can be a StandardKey (for simple presses like "Escape")
@@ -34,15 +43,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 +108,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 +122,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 +148,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 +190,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 +233,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,84 @@ 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));
+    filterByContext(source$, context, strict) {
+        return source$.pipe(withLatestFrom(this.activeContext$), filter(([/* event */ , activeCtx]) => {
+            if (context == null) {
+                if (strict) {
+                    return activeCtx == null;
+                }
+                else {
+                    return true;
+                }
+            }
+            else {
+                return 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 +237,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 +256,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,18 +284,19 @@ 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!")
      * });
      * ```
      */
     addCombination(config) {
-        const { keys, callback, context, preventDefault = false, id } = config;
-        let finalShortcut$;
-        let overallLogDetails = "";
+        const { keys, callback, context, preventDefault = false, id, strict = false } = config;
+        if (context != null && strict) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" has both a context(${context}) and the 'strict' flag. The 'strict' flag will be ignored.`);
+        }
         const keyTriggers = Array.isArray(keys) ? keys : [keys];
         if (keyTriggers.length === 0) {
             console.warn(`${Hotkeys.LOG_PREFIX} "keys" array for combination shortcut "${id}" is empty. Shortcut not added.`);
@@ -223,13 +312,36 @@ export class Hotkeys {
             }
             const { configuredMainKey, ctrlKeyConfig, altKeyConfig, shiftKeyConfig, metaKeyConfig, logDetails } = parsedTrigger;
             logParts.push(`{ ${logDetails} }`);
-            const stream = this.filterByContext(this.keydown$, context).pipe(filter(event => {
+            const stream = this.filterByContext(this.keydown$, context, strict).pipe(filter(event => {
                 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);
                 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 (context != null || strict) { // This shortcut is NOT global or strict
+                    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 !== id &&
+                        'keys' in otherAS.config &&
+                        otherAS.config.context === currentSpecificContext &&
+                        this._shortcutMatchesEvent(otherAS.config, event)) {
+                        if (this.debugMode) {
+                            console.log(`${Hotkeys.LOG_PREFIX} Global shortcut "${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) {
@@ -237,8 +349,8 @@ export class Hotkeys {
             console.warn(`${Hotkeys.LOG_PREFIX} No valid key triggers for combination shortcut "${id}". Shortcut not added.`);
             return undefined;
         }
-        finalShortcut$ = merge(...observables);
-        overallLogDetails = Array.isArray(keys) ? `Triggers: [ ${logParts.join(", ")} ]` : logParts[0];
+        const finalShortcut$ = merge(...observables);
+        const overallLogDetails = Array.isArray(keys) ? `Triggers: [ ${logParts.join(", ")} ]` : logParts[0];
         const subscription = finalShortcut$.pipe(tap(event => {
             if (this.debugMode) {
                 const preventAction = preventDefault ? ", preventing default" : "";
@@ -280,7 +392,7 @@ export class Hotkeys {
      * ```
      */
     addSequence(config) {
-        const { sequence, callback, context, preventDefault = false, id, sequenceTimeoutMs } = config;
+        const { sequence, callback, context, preventDefault = false, id, sequenceTimeoutMs, strict = false } = config;
         if (!Array.isArray(sequence) || sequence.length === 0) {
             console.warn(`${Hotkeys.LOG_PREFIX} Sequence for shortcut "${id}" is empty or invalid. Shortcut not added.`);
             return undefined;
@@ -290,10 +402,13 @@ export class Hotkeys {
             console.warn(`${Hotkeys.LOG_PREFIX} Invalid key in sequence for shortcut "${id}". All keys must be non-empty string values from Keys. Shortcut not added.`);
             return undefined;
         }
+        if (context && strict) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" has both a context and the 'strict' flag. The 'strict' flag will be ignored.`);
+        }
         const configuredSequence = sequence;
         const sequenceLength = configuredSequence.length;
         let shortcut$;
-        const baseKeydownStream$ = this.filterByContext(this.keydown$, context);
+        const baseKeydownStream$ = this.filterByContext(this.keydown$, context, strict);
         if (sequenceTimeoutMs && sequenceTimeoutMs > 0) {
             shortcut$ = baseKeydownStream$.pipe(scan((acc, event) => {
                 let { matchedEvents, lastEventTime } = acc;
@@ -320,7 +435,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 +465,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 (context != null || strict) { // This sequence is NOT global or strict
+                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 !== id &&
+                    "sequence" in otherAS.config &&
+                    otherAS.config.context === currentSpecificContext &&
+                    this._areSequencesIdentical(sequence, otherAS.config.sequence)) {
+                    if (this.debugMode) {
+                        console.log(`${Hotkeys.LOG_PREFIX} Global sequence shortcut "${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 +499,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 +510,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 +536,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 +545,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 +561,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.`);
     }