rx-hotkeys 3.0.0 → 4.0.0

package/README.md

@@ -4,12 +4,15 @@ rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard s
 
 ## ✨ Features
 
+* **Official React Hooks**: Provides an official wrapper (`HotkeysProvider`, `useHotkeys`, `useScopedHotkeysContext`) for seamless, idiomatic integration with React.
 * **Fully Observable API**: Returns an RxJS `Observable` for each shortcut, allowing for powerful stream manipulation like chaining, filtering, debouncing, and merging with other streams.
 * **Flexible Shortcut Definitions**: Define shortcuts using simple, intuitive strings (e.g., `"ctrl+s"` or `"g -> i"`) in addition to the classic object-based configuration.
 * **Element-Scoped Listeners**: Attach shortcuts to specific DOM elements, so they are only active within a certain component or area, not just on the global `document`.
 * **`keyup` Event Support**: Trigger actions on key release (`keyup`) in addition to the default key press (`keydown`).
 * **Key Combinations & Sequences**: Supports both simultaneous key presses (`Ctrl+S`) and ordered key sequences (`g` -> `c`).
 * **Context Management**: Activate or deactivate groups of shortcuts based on the application's current state (e.g., "editor", "modal", "global").
+* **Stack-Based Context Management**: Natively handles nested contexts with an `enter`/`leave` API, perfect for hierarchical UIs like pages, modals, and dropdowns.
+* **Temporary Context Override**: Safely override all contexts with a high-priority temporary context, ideal for global application states like "saving" or "loading".
 * **Strict Global Shortcuts**: Option to register global shortcuts that *only* fire when no other context is active.
 * **Type-Safe Key Definitions**: Uses an exported `Keys` object based on standard `KeyboardEvent.key` values for a superior developer experience and fewer errors.
 * **Sequence Timeouts**: Optional timeout between key presses in a sequence to prevent accidental triggers.
@@ -21,40 +24,17 @@ rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard s
 npm install rxjs rx-hotkeys
 ```
 
-## ⚠️ Breaking Changes (v3.0+)
+## ⚠️ Breaking Changes (v4.0+)
 
-Starting with v3.0, the API has been significantly updated for a more powerful and idiomatic RxJS experience. This is a major breaking change.
+Starting with v4.0, the context management API has been fundamentally redesigned into a more powerful and robust dual-mode system.
 
-* `addCombination` and `addSequence` no longer accept a `callback` property in their configuration.
-* They now return an **`Observable<KeyboardEvent>`**.
-* You **must** now call `.subscribe()` on the returned Observable to execute your action.
+* The old `setContext` method (which returned a boolean) has been replaced.
+* The library now offers two distinct ways to manage contexts:
+    1.  **Context Stack (`enterContext`/`leaveContext`)**: For hierarchical UI states.
+    2.  **Context Override (`setContext` returns a `restore` function)**: For temporary, global state overrides.
+* `getContext` method rename to `getActiveContext`.
 
-**Migration Example:**
-
-**Old (v1.x):**
-```typescript
-// The old way
-keyManager.addCombination({
-  id: "save",
-  keys: { key: Keys.S, ctrlKey: true },
-  callback: () => console.log("File saved!"),
-});
-```
-
-**New (v3.0+):**
-```typescript
-// The new, observable-based way
-const save$ = keyManager.addCombination({
-  id: "save",
-  keys: { key: Keys.S, ctrlKey: true }
-});
-
-const subscription = save$.subscribe(() => console.log("File saved!"));
-
-// Don't forget to unsubscribe when your component is destroyed!
-// The stream will also complete automatically if the shortcut is removed or keyManager.destroy() is called.
-// subscription.unsubscribe();
-```
+Please review the "Context Management" section below for details.
 
 ## Basic Usage
 
@@ -142,16 +122,55 @@ const submit$ = keyManager.addCombination({
 submit$.subscribe(() => console.log("Form submitted on Enter keyup!"));
 ```
 
-### 6. Manage Contexts
+### 6. Context Management
+
+You now have two powerful tools for managing contexts.
 
-Control which shortcuts are active by setting the context.
+#### A) Context Stack (`enterContext` / `leaveContext`)
+
+Use this for nested UI scopes that follow a clear hierarchy.
 
 ```typescript
-// Assuming some shortcuts are configured with context: "editor"
-keyManager.setContext("editor"); // Activates "editor" shortcuts and global shortcuts
+// A shortcut with context: "editor" will NOT be active here.
+console.log(keyManager.getActiveContext()); // null
+
+// Activate the "editor" context
+keyManager.enterContext("editor");
+// Now, pressing Ctrl+S will trigger the "saveFile" shortcut.
+console.log(keyManager.getActiveContext()); // 'editor'
 
-// To activate only global shortcuts (those with no context or context: null)
-keyManager.setContext(null);
+// Imagine opening a dropdown menu inside the editor
+keyManager.enterContext("dropdown-menu");
+console.log(keyManager.getActiveContext()); // 'dropdown-menu'
+
+// When the dropdown closes, leave its context
+keyManager.leaveContext();
+console.log(keyManager.getActiveContext()); // 'editor' (restored automatically)
+```
+
+#### B) Context Override (`setContext` and `restore`)
+
+Use this for temporary, high-priority states that should override everything else.
+
+```typescript
+async function performSave() {
+  // Set a temporary "saving" context that overrides the stack.
+  const restore = keyManager.setContext('saving');
+
+  // Any shortcuts with context: 'saving' are now active.
+  // All other shortcuts (editor, etc.) are inactive.
+  console.log(keyManager.getActiveContext()); // 'saving'
+
+  try {
+    await someAsyncSaveOperation();
+  } finally {
+    // No matter what happens, call restore() to clear the override
+    // and return control to the context stack.
+    restore();
+  }
+
+  console.log(keyManager.getActiveContext()); // e.g., 'editor' (restored from the stack)
+}
 ```
 
 ### 7. Clean Up
@@ -163,6 +182,99 @@ When the Hotkeys instance is no longer needed (e.g., component unmount), call `d
 keyManager.destroy();
 ```
 
+---
+
+## Usage with React
+
+The library provides a dedicated React wrapper for the best developer experience.
+
+### Step 1: Wrap Your App with `HotkeysProvider`
+
+First, import `HotkeysProvider` and wrap your root application component with it. This creates a single, shared instance of the hotkeys manager for your entire app.
+
+```jsx
+// In your main App.js or index.js
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { HotkeysProvider } from 'rx-hotkeys/react';
+import App from './App';
+
+const root = ReactDOM.createRoot(document.getElementById('root'));
+root.render(
+  <React.StrictMode>
+    <HotkeysProvider debugMode={true}>
+      <App />
+    </HotkeysProvider>
+  </React.StrictMode>
+);
+```
+
+### Step 2: Use the `useHotkeys` Hook in Your Components
+
+Now, you can use the `useHotkeys` and `useSequence` hooks anywhere in your component tree. The hook automatically handles registration, cleanup, and stale closures. You no longer need to provide a dependency array for your callback.
+
+```jsx
+// src/components/Counter.jsx
+import React, { useState } from 'react';
+import { useHotkeys, useSequence } from 'rx-hotkeys/react';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+
+  // The callback can safely use the latest component state (like `count`)
+  // without you needing to worry about stale closures or dependency arrays.
+  const handleIncrement = () => {
+    console.log(`Incrementing from ${count}...`);
+    setCount(count + 1);
+  };
+
+  // Register '+' key to increment.
+  useHotkeys('+', handleIncrement);
+
+  // Register 'c' key to increment, with options.
+  useHotkeys('c', handleIncrement, { preventDefault: true });
+
+  // Register a sequence to reset the counter.
+  useSequence('r -> e -> s -> e -> t', () => {
+    console.log('Resetting counter!');
+    setCount(0);
+  });
+
+  return (
+    <div>
+      <h2>Count: {count}</h2>
+      <p>Press '+' or 'c' to increment. Type 'reset' to reset.</p>
+    </div>
+  );
+}
+```
+
+### Step 3: Manage Context with `useScopedHotkeysContext`
+
+This hook allows a component (like a modal) to activate a specific context only while it is mounted.
+
+```jsx
+// src/components/MyModal.jsx
+import { useHotkeys, useScopedHotkeysContext } from 'rx-hotkeys/react';
+
+export function MyModal({ onClose }) {
+  // This activates the 'modal' context for all children of this component.
+  // When MyModal unmounts, this context is automatically removed from the stack.
+  useScopedHotkeysContext('modal');
+
+  // This hotkey will only be active when the 'modal' context is active.
+  useHotkeys('escape', onClose, { context: 'modal' });
+
+  return (
+    <div className="modal">
+      <p>This is a modal. Press ESC to close.</p>
+      {/* ... other modal content ... */}
+    </div>
+  );
+}
+```
+
+---
 
 ## API Reference
 
@@ -171,7 +283,7 @@ keyManager.destroy();
 * `Keys`: An exported constant object containing standard `KeyboardEvent.key` string values (e.g., `Keys.Enter`, `Keys.ArrowUp`, `Keys.A`). It's highly recommended to use these for type safety and to avoid typos.
 * `StandardKey`: A TypeScript type representing any valid key string from the `Keys` object.
 
-### `Hotkeys` Class
+### `Hotkeys` Class (Core)
 
 `constructor(initialContext?: string | null, debugMode?: boolean)`
 
@@ -189,13 +301,25 @@ Registers a key sequence shortcut.
 * `config`: The `KeySequenceConfig` object.
 * Returns an `Observable<KeyboardEvent>` that emits the final `KeyboardEvent` when the sequence is completed.
 
-`setContext(contextName: string | null): boolean`
+`enterContext(contextName: string | null): void`
+
+Pushes a context onto the **context stack**. It becomes active if no override is set.
+
+`leaveContext(): string | null | undefined`
 
-Sets the active context. Only shortcuts matching this context or global shortcuts will trigger.
+Pops a context from the **context stack**, returning the context that was left.
 
-`getContext(): string | null`
+`setContext(contextName: string | null): () => void`
 
-Returns the current active context name, or `null`.
+Sets a temporary **override context**. Returns a `restore` function to clear the override.
+
+`getActiveContext(): string | null`
+
+Returns the current active context (checks for an override first, then the stack top).
+
+`onContextChange$: Observable<string | null>`
+
+A public `Observable` property that emits the active context whenever it changes.
 
 `remove(id: string): boolean`
 
@@ -219,6 +343,33 @@ Enables or disables console logging for debug purposes.
 
 Cleans up all subscriptions and resources. Essential to call to prevent memory leaks.
 
+### React Hooks (`rx-hotkeys/react`)
+
+`HotkeysProvider({ children, initialContext?, debugMode? })`
+
+A React component that provides the Hotkeys instance to its children.
+
+`useHotkeys(keys, callback, options?)`
+
+A React hook to register a key combination.
+* `keys: string | string[]`: The shortcut definition (e.g., `'ctrl+s'`).
+* `callback: (event: KeyboardEvent) => void`: The function to execute.
+* `options?: HotkeyHookOptions`: Optional config for `preventDefault`, `context`, `target`, etc.
+
+`useSequence(sequence, callback, options?)`
+
+A React hook to register a key sequence.
+* `sequence: string | string[]`: The sequence definition (e.g., `'g -> i'`).
+* `callback: (event: KeyboardEvent) => void`: The function to execute.
+* `options?: SequenceHookOptions`: Optional config for `preventDefault`, `context`, etc.
+
+`useScopedHotkeysContext(context, enabled: boolean = true)`
+
+A React hook to apply a specific context for the lifetime of the component.
+
+`useHotkeysManager(): Hotkeys`
+A hook to get direct access to the `Hotkeys` manager instance.
+
 ### Configuration Interfaces
 
 #### `KeyCombinationConfig`
@@ -252,6 +403,8 @@ Cleans up all subscriptions and resources. Essential to call to prevent memory l
 * **Aliases**: Common aliases are supported in string definitions, such as `cmd` for `Meta`, `option` for `Alt`, and `esc` for `Escape`.
 * **Special Keys**: For full type-safety, it is recommended to use the exported `Keys` object (e.g., `Keys.Enter`, `Keys.ArrowUp`).
 
+---
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit issues, fork the repository, and create pull requests.

package/dist/{hotkeys.d.ts → core/hotkeys.d.ts}

@@ -111,18 +111,30 @@ export declare class Hotkeys {
     private static readonly KEYDOWN_EVENT;
     private static readonly KEYUP_EVENT;
     private static readonly LOG_PREFIX;
+    private static readonly NO_OVERRIDE;
     private keydownStreams;
     private keyupStreams;
-    private activeContext$;
     private activeShortcuts;
     private debugMode;
+    private contextStack$;
+    private overrideContext$;
+    /**
+     * An Observable that emits the new active context name (or null) whenever it changes.
+     * The active context is the override context if one is set, otherwise it's the context
+     * from the top of the stack.
+     */
+    private readonly activeContext$;
     /**
      * Creates an instance of Hotkeys.
-     * @param initialContext - Optional initial context name. Shortcuts will only trigger if their context matches this, or if they have no context defined.
+     * @param initialContext - Optional initial context name. This forms the base of the context stack.
      * @param debugMode - Optional. If true, debug messages will be logged to the console. Defaults to false.
      * @throws Error if not in a browser environment (i.e., `document` or `performance` is undefined).
      */
     constructor(initialContext?: string | null, debugMode?: boolean);
+    /**
+     * Helper method to determine the active context based on override and stack.
+     */
+    private _resolveActiveContext;
     /**
      * Gets or creates a shared event stream for a given event type and target.
      * @param eventType The type of event ("keydown" or "keyup").
@@ -131,19 +143,32 @@ export declare class Hotkeys {
      */
     private _getEventStream;
     /**
-     * Sets the active context for shortcuts.
-     * Only shortcuts matching this context (or shortcuts with no specific context defined)
-     * 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 `true` if the context was changed, `false` if the new context was the same as the current one.
+     * Sets a temporary, high-priority override context that takes precedence over the context stack.
+     * @param contextName The override context to activate (can be a string or `null`).
+     * @returns A `restore` function that, when called, clears the override context, reverting to the stack.
      */
-    setContext(contextName: string | null): boolean;
+    setContext(contextName: string | null): () => void;
     /**
-     * Gets the current active context.
+     * @deprecated Rename to `getActiveContext`
+     * Gets the current active context, considering any override.
      * @returns The current context name as a string, or `null` if no context is set.
      */
     getContext(): string | null;
+    /**
+     * Gets the current active context, considering any override.
+     * @returns The current context name as a string, or `null` if no context is set.
+     */
+    getActiveContext(): string | null;
+    /**
+     * Pushes a new context onto the context stack. It will become active if no override context is set.
+     * @param contextName The name of the context to enter (e.g., "modal", "editor").
+     */
+    enterContext(contextName: string | null): void;
+    /**
+     * Pops the current context from the stack.
+     * @returns The context that was just left from the stack, or `undefined` if at the base.
+     */
+    leaveContext(): string | null | undefined;
     /**
      * Enables or disables debug logging for the Hotkeys instance.
      * When enabled, various internal actions and shortcut triggers will be logged to the console.
@@ -158,10 +183,6 @@ export declare class Hotkeys {
     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.
-     *
-     * Note: This observable benefits from the distinct check within the `setContext` method,
-     * meaning it will only emit when the context value actually changes.
      *
      * @example
      * ```typescript

package/dist/core/hotkeys.d.ts.map

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

package/dist/{hotkeys.js → core/hotkeys.js}

@@ -1,4 +1,4 @@
-import { fromEvent, BehaviorSubject, EMPTY, filter, map, bufferCount, withLatestFrom, tap, catchError, scan, merge, Subject, takeUntil, share, } from "rxjs";
+import { fromEvent, BehaviorSubject, EMPTY, filter, map, bufferCount, withLatestFrom, tap, catchError, scan, merge, Subject, takeUntil, share, distinctUntilChanged, combineLatest, } from "rxjs";
 import { Keys, KeyAliases } from "./keys.js";
 // --- Enums, Interfaces and Types ---
 export var ShortcutTypes;
@@ -59,30 +59,57 @@ export class Hotkeys {
     static KEYDOWN_EVENT = "keydown";
     static KEYUP_EVENT = "keyup";
     static LOG_PREFIX = "Hotkeys:";
+    // --- Sentinel value for no override ---
+    static NO_OVERRIDE = Symbol("No Hotkey Override");
     keydownStreams;
     keyupStreams;
-    activeContext$;
     activeShortcuts;
     debugMode;
+    // --- Separate states for stack and override ---
+    contextStack$;
+    overrideContext$;
+    /**
+     * An Observable that emits the new active context name (or null) whenever it changes.
+     * The active context is the override context if one is set, otherwise it's the context
+     * from the top of the stack.
+     */
+    activeContext$;
     /**
      * Creates an instance of Hotkeys.
-     * @param initialContext - Optional initial context name. Shortcuts will only trigger if their context matches this, or if they have no context defined.
+     * @param initialContext - Optional initial context name. This forms the base of the context stack.
      * @param debugMode - Optional. If true, debug messages will be logged to the console. Defaults to false.
      * @throws Error if not in a browser environment (i.e., `document` or `performance` is undefined).
      */
     constructor(initialContext = null, debugMode = false) {
         this.debugMode = debugMode;
         if (typeof document === "undefined" || typeof performance === "undefined") {
-            throw new Error(`${Hotkeys.LOG_PREFIX} Hotkeys can only be used in a browser environment with global "document" and "performance" objects.`);
+            throw new Error(`${Hotkeys.LOG_PREFIX} Hotkeys can only be used in a browser environment.`);
         }
         this.keydownStreams = new WeakMap();
         this.keyupStreams = new WeakMap();
-        this.activeContext$ = new BehaviorSubject(initialContext);
         this.activeShortcuts = new Map();
+        // The context stack is the source of truth for the active context.
+        this.contextStack$ = new BehaviorSubject([initialContext]);
+        this.overrideContext$ = new BehaviorSubject(Hotkeys.NO_OVERRIDE);
+        // The public activeContext$ now correctly handles the sentinel value.
+        this.activeContext$ = combineLatest([
+            this.overrideContext$,
+            this.contextStack$.pipe(map(stack => stack.length > 0 ? stack[stack.length - 1] : null))
+        ]).pipe(map(([overrideCtx, stackCtx]) => this._resolveActiveContext(overrideCtx, stackCtx)), distinctUntilChanged());
         if (this.debugMode) {
             console.log(`${Hotkeys.LOG_PREFIX} Library initialized. Initial context: "${initialContext}". Debug mode: ${debugMode}.`);
+            // Optional: Log context changes for debugging
+            this.activeContext$.subscribe(newContext => {
+                console.log(`${Hotkeys.LOG_PREFIX} Active context changed to: ${newContext}`);
+            });
         }
     }
+    /**
+     * Helper method to determine the active context based on override and stack.
+     */
+    _resolveActiveContext(overrideCtx, stackCtx) {
+        return overrideCtx !== Hotkeys.NO_OVERRIDE ? overrideCtx : stackCtx;
+    }
     /**
      * Gets or creates a shared event stream for a given event type and target.
      * @param eventType The type of event ("keydown" or "keyup").
@@ -102,35 +129,78 @@ export class Hotkeys {
         return streamCache.get(target);
     }
     /**
-     * Sets the active context for shortcuts.
-     * Only shortcuts matching this context (or shortcuts with no specific context defined)
-     * 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 `true` if the context was changed, `false` if the new context was the same as the current one.
+     * Sets a temporary, high-priority override context that takes precedence over the context stack.
+     * @param contextName The override context to activate (can be a string or `null`).
+     * @returns A `restore` function that, when called, clears the override context, reverting to the stack.
      */
     setContext(contextName) {
-        const currentContext = this.activeContext$.getValue();
-        if (currentContext === contextName) {
-            if (this.debugMode) {
-                // 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 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; // Context WAS updated
+            console.log(`${Hotkeys.LOG_PREFIX} Setting override context to: "${contextName}".`);
+        }
+        this.overrideContext$.next(contextName);
+        const restore = () => {
+            // Only clear the override if it's still the one we set.
+            if (this.overrideContext$.getValue() === contextName) {
+                if (this.debugMode) {
+                    console.log(`${Hotkeys.LOG_PREFIX} Restoring/clearing override context from: "${contextName}".`);
+                }
+                // Restore now sets the special "NO_OVERRIDE" value.
+                this.overrideContext$.next(Hotkeys.NO_OVERRIDE);
+            }
+        };
+        return restore;
     }
     /**
-     * Gets the current active context.
+     * @deprecated Rename to `getActiveContext`
+     * Gets the current active context, considering any override.
      * @returns The current context name as a string, or `null` if no context is set.
      */
     getContext() {
-        return this.activeContext$.getValue();
+        console.warn(`${Hotkeys.LOG_PREFIX} "getContext" is deprecated. Use "getActiveContext()" or subscribe to "onContextChange$" instead.`);
+        return this.getActiveContext();
+    }
+    /**
+     * Gets the current active context, considering any override.
+     * @returns The current context name as a string, or `null` if no context is set.
+     */
+    getActiveContext() {
+        const overrideCtx = this.overrideContext$.getValue();
+        const stack = this.contextStack$.getValue();
+        const stackCtx = stack.length > 0 ? stack[stack.length - 1] : null;
+        // Also uses the abstracted helper method.
+        return this._resolveActiveContext(overrideCtx, stackCtx);
+    }
+    /**
+     * Pushes a new context onto the context stack. It will become active if no override context is set.
+     * @param contextName The name of the context to enter (e.g., "modal", "editor").
+     */
+    enterContext(contextName) {
+        const currentStack = this.contextStack$.getValue();
+        const newStack = [...currentStack, contextName];
+        if (this.debugMode) {
+            console.log(`${Hotkeys.LOG_PREFIX} Entering context: "${contextName}". New stack: [${newStack.join(", ")}]`);
+        }
+        this.contextStack$.next(newStack);
+    }
+    /**
+     * Pops the current context from the stack.
+     * @returns The context that was just left from the stack, or `undefined` if at the base.
+     */
+    leaveContext() {
+        const currentStack = this.contextStack$.getValue();
+        if (currentStack.length <= 1) {
+            if (this.debugMode) {
+                console.log(`${Hotkeys.LOG_PREFIX} Attempted to leave the base stack context. No change made.`);
+            }
+            return undefined; // Nothing was left
+        }
+        const leavingContext = currentStack[currentStack.length - 1];
+        const newStack = currentStack.slice(0, -1);
+        if (this.debugMode) {
+            console.log(`${Hotkeys.LOG_PREFIX} Leaving context: "${leavingContext}". New stack: [${newStack.join(", ")}]`);
+        }
+        this.contextStack$.next(newStack);
+        return leavingContext;
     }
     /**
      * Enables or disables debug logging for the Hotkeys instance.
@@ -159,10 +229,6 @@ export class Hotkeys {
     }
     /**
      * 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.
-     *
-     * Note: This observable benefits from the distinct check within the `setContext` method,
-     * meaning it will only emit when the context value actually changes.
      *
      * @example
      * ```typescript
@@ -176,7 +242,7 @@ export class Hotkeys {
      * ```
      */
     get onContextChange$() {
-        return this.activeContext$.asObservable();
+        return this.activeContext$;
     }
     /**
      * Compares two sequences of StandardKey arrays to see if they are identical.
@@ -440,19 +506,18 @@ export class Hotkeys {
                 return ctrlMatch && altMatch && shiftMatch && metaMatch;
             }), filter(event => compareKey(event.key, configuredMainKey)), 
             // New filter for priority: Specific context > Global context
-            filter(event => {
+            withLatestFrom(this.activeContext$), filter(([event, activeCtx]) => {
                 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
+                if (activeCtx == 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 &&
+                        otherAS.config.context === activeCtx &&
                         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}".`);
@@ -461,7 +526,7 @@ export class Hotkeys {
                     }
                 }
                 return true; // Global can proceed
-            }));
+            }), map(([event]) => event));
             observables.push(stream);
         }
         if (observables.length === 0) {
@@ -601,19 +666,18 @@ export class Hotkeys {
             }));
         }
         const terminator$ = new Subject();
-        const finalShortcutWithPriority$ = shortcut$.pipe(filter((completedEvents) => {
+        const finalShortcutWithPriority$ = shortcut$.pipe(withLatestFrom(this.activeContext$), filter(([_completedEvents, activeCtx]) => {
             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
+            if (activeCtx == 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 &&
+                    otherAS.config.context === activeCtx &&
                     this._areSequencesIdentical(configuredSequence, typeof otherAS.config.sequence === "string" ? this._parseSequenceString(otherAS.config.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}".`);
@@ -622,7 +686,7 @@ export class Hotkeys {
                 }
             }
             return true; // Global sequence can proceed
-        }), tap((events) => {
+        }), map(([events]) => events), tap((events) => {
             if (this.debugMode) {
                 const timeoutInfo = (sequenceTimeoutMs && sequenceTimeoutMs > 0) ? ` (with timeout logic)` : ` (no timeout logic)`;
                 const preventAction = preventDefault ? ", preventing default for last event" : "";
@@ -692,8 +756,9 @@ export class Hotkeys {
             shortcut.terminator$.complete();
         });
         this.activeShortcuts.clear();
-        this.activeContext$.complete();
+        this.contextStack$.complete();
         if (this.debugMode)
             console.log(`${Hotkeys.LOG_PREFIX} Library destroyed.`);
     }
 }
+//# sourceMappingURL=hotkeys.js.map