rx-hotkeys 2.6.0 → 3.0.0

package/dist/hotkeys.js

@@ -1,4 +1,5 @@
-import { fromEvent, BehaviorSubject, EMPTY, filter, map, bufferCount, withLatestFrom, tap, catchError, scan, merge, } from "rxjs";
+import { fromEvent, BehaviorSubject, EMPTY, filter, map, bufferCount, withLatestFrom, tap, catchError, scan, merge, Subject, takeUntil, share, } from "rxjs";
+import { Keys, KeyAliases } from "./keys.js";
 // --- Enums, Interfaces and Types ---
 export var ShortcutTypes;
 (function (ShortcutTypes) {
@@ -26,6 +27,28 @@ function compareKey(eventKey, configuredKey) {
     }
     return eventKey === configuredKey;
 }
+/**
+ * Normalizes a string representation of a key into a canonical StandardKey.
+ * Handles case-insensitivity, aliases, and special characters.
+ * @param key The raw key string to normalize.
+ * @returns A StandardKey if valid, otherwise null.
+ */
+function normalizeKey(key) {
+    // 1. Handle spacebar explicitly to avoid trimming
+    if (key === Keys.Space) {
+        return Keys.Space;
+    }
+    // 2. Trim and convert to lower case for consistent matching
+    const normalizedStr = key.trim().toLowerCase();
+    if (normalizedStr === "") {
+        return null;
+    }
+    // 3. Look up in aliases, then in standard key values, then check for single char
+    const finalKey = KeyAliases[normalizedStr] ||
+        Object.values(Keys).find(k => k.toLowerCase() === normalizedStr) ||
+        (normalizedStr.length === 1 ? normalizedStr.toUpperCase() : undefined);
+    return finalKey || null;
+}
 // --- Hotkeys Library ---
 /**
  * Manages keyboard shortcuts for web applications.
@@ -34,8 +57,10 @@ function compareKey(eventKey, configuredKey) {
  */
 export class Hotkeys {
     static KEYDOWN_EVENT = "keydown";
+    static KEYUP_EVENT = "keyup";
     static LOG_PREFIX = "Hotkeys:";
-    keydown$;
+    keydownStreams;
+    keyupStreams;
     activeContext$;
     activeShortcuts;
     debugMode;
@@ -50,13 +75,32 @@ export class Hotkeys {
         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.`);
         }
-        this.keydown$ = fromEvent(document, Hotkeys.KEYDOWN_EVENT);
+        this.keydownStreams = new WeakMap();
+        this.keyupStreams = new WeakMap();
         this.activeContext$ = new BehaviorSubject(initialContext);
         this.activeShortcuts = new Map();
         if (this.debugMode) {
             console.log(`${Hotkeys.LOG_PREFIX} Library initialized. Initial context: "${initialContext}". Debug mode: ${debugMode}.`);
         }
     }
+    /**
+     * Gets or creates a shared event stream for a given event type and target.
+     * @param eventType The type of event ("keydown" or "keyup").
+     * @param target The DOM element to attach the listener to.
+     * @returns A shared Observable for the specified event.
+     */
+    _getEventStream(eventType, target) {
+        const streamCache = eventType === "keydown" ? this.keydownStreams : this.keyupStreams;
+        if (!streamCache.has(target)) {
+            const newStream = fromEvent(target, eventType).pipe(share());
+            streamCache.set(target, newStream);
+            if (this.debugMode) {
+                const targetName = target === document ? "document" : `element "${target.id || target.tagName}"`;
+                console.log(`${Hotkeys.LOG_PREFIX} Created new shared listener for "${eventType}" on ${targetName}.`);
+            }
+        }
+        return streamCache.get(target);
+    }
     /**
      * Sets the active context for shortcuts.
      * Only shortcuts matching this context (or shortcuts with no specific context defined)
@@ -159,31 +203,30 @@ export class Hotkeys {
      * @returns True if the shortcutConfig matches the event, false otherwise.
      */
     _shortcutMatchesEvent(shortcutConfig, event) {
-        const keyTriggers = Array.isArray(shortcutConfig.keys) ? shortcutConfig.keys : [shortcutConfig.keys];
+        // Use the same robust heuristic here for consistency ---
+        let keyTriggers;
+        const configKeys = shortcutConfig.keys;
+        if (typeof configKeys === "string" && configKeys.length > 1 && configKeys.includes("+")) {
+            keyTriggers = this._parseCombinationString(configKeys);
+        }
+        else {
+            keyTriggers = Array.isArray(configKeys) ? configKeys : [configKeys];
+        }
         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;
-            }
+            // This logic is now simplified because _parseKeyTrigger handles normalization
+            const parsed = this._parseKeyTrigger(keyInput, shortcutConfig.id);
+            if (!parsed)
+                continue;
+            configuredMainKey = parsed.configuredMainKey;
+            ctrlKeyConfig = parsed.ctrlKeyConfig;
+            altKeyConfig = parsed.altKeyConfig;
+            shiftKeyConfig = parsed.shiftKeyConfig;
+            metaKeyConfig = parsed.metaKeyConfig;
             const keyMatch = compareKey(event.key, configuredMainKey);
             if (!keyMatch)
                 continue;
@@ -212,17 +255,17 @@ export class Hotkeys {
             }
         }), map(([event, /* _activeCtx */]) => event));
     }
-    _registerShortcut(config, subscription, type, detailsForLog) {
+    _registerShortcut(config, terminator$, 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.`);
-            existingShortcut.subscription.unsubscribe();
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut with ID "${config.id}" already exists. The old instance will be terminated and overwritten.`);
+            existingShortcut.terminator$.next();
+            existingShortcut.terminator$.complete();
         }
-        this.activeShortcuts.set(config.id, { id: config.id, config, subscription });
+        this.activeShortcuts.set(config.id, { id: config.id, config, terminator$ });
         if (this.debugMode) {
             console.log(`${Hotkeys.LOG_PREFIX} ${type} shortcut "${config.id}" added. ${detailsForLog}, Context: ${config.context ?? "any"}`);
         }
-        return config.id;
     }
     /**
      * Parses a single key trigger definition (either shorthand StandardKey or an object with modifiers)
@@ -233,17 +276,18 @@ export class Hotkeys {
      */
     _parseKeyTrigger(keyInput, shortcutId) {
         if (typeof keyInput === "string") {
-            if (keyInput === "") {
-                console.warn(`${Hotkeys.LOG_PREFIX} Invalid key (shorthand) in shortcut "${shortcutId}". Key string must not be empty.`);
+            const finalKey = normalizeKey(keyInput);
+            if (!finalKey) {
+                console.warn(`${Hotkeys.LOG_PREFIX} Could not parse key: "${keyInput}" in shortcut "${shortcutId}".`);
                 return null;
             }
             return {
-                configuredMainKey: keyInput,
+                configuredMainKey: finalKey,
                 ctrlKeyConfig: false,
                 altKeyConfig: false,
                 shiftKeyConfig: false,
                 metaKeyConfig: false,
-                logDetails: `key: "${keyInput}" (no mods)`,
+                logDetails: `key: "${finalKey}" (no mods)`,
             };
         }
         else {
@@ -251,11 +295,22 @@ export class Hotkeys {
                 console.warn(`${Hotkeys.LOG_PREFIX} Invalid "key" property in shortcut "${shortcutId}". Key must be a non-empty string value from Keys.`);
                 return null;
             }
+            const hasModifiers = keyInput.ctrlKey || keyInput.altKey || keyInput.shiftKey || keyInput.metaKey;
+            if (!hasModifiers) {
+                return {
+                    configuredMainKey: keyInput.key,
+                    ctrlKeyConfig: false,
+                    altKeyConfig: false,
+                    shiftKeyConfig: false,
+                    metaKeyConfig: false,
+                    logDetails: `key: "${keyInput.key}" (no mods)`,
+                };
+            }
             const logDetails = `key: "${keyInput.key}"` +
-                (keyInput.ctrlKey !== undefined ? `, ctrl: ${keyInput.ctrlKey}` : "") +
-                (keyInput.altKey !== undefined ? `, alt: ${keyInput.altKey}` : "") +
-                (keyInput.shiftKey !== undefined ? `, shift: ${keyInput.shiftKey}` : "") +
-                (keyInput.metaKey !== undefined ? `, meta: ${keyInput.metaKey}` : "");
+                (keyInput.ctrlKey ? `, ctrl: true` : "") +
+                (keyInput.altKey ? `, alt: true` : "") +
+                (keyInput.shiftKey ? `, shift: true` : "") +
+                (keyInput.metaKey ? `, meta: true` : "");
             return {
                 configuredMainKey: keyInput.key,
                 ctrlKeyConfig: keyInput.ctrlKey,
@@ -266,53 +321,118 @@ export class Hotkeys {
             };
         }
     }
+    _parseCombinationString(shortcut) {
+        const parts = shortcut.toLowerCase().split("+").map(p => p.trim());
+        const mainKeyStr = parts.pop();
+        if (!mainKeyStr) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Invalid shortcut string: "${shortcut}". No main key found.`);
+            return [];
+        }
+        const trigger = {
+            key: "",
+            ctrlKey: false, altKey: false, shiftKey: false, metaKey: false
+        };
+        const finalKey = normalizeKey(mainKeyStr);
+        if (!finalKey) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Could not parse key: "${mainKeyStr}" in shortcut string "${shortcut}".`);
+            return [];
+        }
+        trigger.key = finalKey;
+        for (const part of parts) {
+            if (part === "ctrl" || part === "control")
+                trigger.ctrlKey = true;
+            else if (part === "alt" || part === "option")
+                trigger.altKey = true;
+            else if (part === "shift")
+                trigger.shiftKey = true;
+            else if (part === "meta" || part === "cmd" || part === "command" || part === "win")
+                trigger.metaKey = true;
+            else
+                console.warn(`${Hotkeys.LOG_PREFIX} Unknown modifier: "${part}" in shortcut string "${shortcut}".`);
+        }
+        return [trigger];
+    }
+    _parseSequenceString(sequence) {
+        const keyStrings = sequence.split("->").map(k => k.trim());
+        const results = [];
+        for (const keyStr of keyStrings) {
+            const finalKey = normalizeKey(keyStr);
+            if (finalKey) {
+                results.push(finalKey);
+            }
+            else {
+                console.warn(`${Hotkeys.LOG_PREFIX} Could not parse key: "${keyStr}" in sequence string "${sequence}".`);
+                return []; // Fail fast
+            }
+        }
+        return results;
+    }
     /**
-     * Registers a key combination shortcut (e.g., Ctrl+S, Shift+Enter, or a single key like Escape).
-     * The callback is triggered when the specified key and modifier keys (if any) are pressed.
+     * Registers a key combination shortcut (e.g., Ctrl+S, Shift+Enter, or a single key like Escape)
+     * and returns an Observable that emits the `KeyboardEvent` when the combination is triggered.
      * @param config - Configuration object for the key combination.
      * See {@link KeyCombinationConfig} for details.
-     * The `key` property (or the direct `StandardKey` if using shorthand) must be a value from the `Keys` object.
-     * @returns The ID of the registered shortcut if successful, or `undefined` if the configuration is invalid.
-     * A warning is logged to the console if the configuration is invalid or if a shortcut with the same ID is overwritten.
+     * @returns An `Observable<KeyboardEvent>` that you can subscribe to. The stream will be automatically
+     * completed if the shortcut is removed via `remove(id)` or `destroy()`, or if it's overwritten.
+     * If the configuration is invalid, an empty Observable is returned and a warning is logged.
      * @example
      * ```typescript
      * import { Keys } from "./keys";
      * // For Ctrl+S
-     * keyManager.addCombination({
+     * const save$ = keyManager.addCombination({
      * id: "saveFile",
      * keys: { key: Keys.S, ctrlKey: true },
-     * callback: () => console.log("File saved!"),
      * context: "editor"
      * });
+     * save$.subscribe(event => console.log("File saved!", event));
+     *
+     * // For Ctrl+S using a string
+     * const save$ = keyManager.addCombination({ id: "saveFile", keys: "ctrl+s" });
+     * save$.subscribe(event => console.log("File saved!", event));
+     *
      * // For just the Escape key, or Ctrl+Space
-     * keyManager.addCombination({
+     * const close$ = keyManager.addCombination({
      * id: "closeModal",
      * keys: [Keys.Escape, {key: Keys.Space, ctrlKey: true}],
-     * callback: () => console.log("Modal closed!")
      * });
+     * close$.subscribe(() => console.log("Modal closed!"));
+     *
+     * // For the Escape key on a specific element
+     * const myModal = document.getElementById("my-modal");
+     * const close$ = keyManager.addCombination({ id: "closeModal", keys: Keys.Escape, target: myModal });
+     * close$.subscribe(() => console.log("Modal closed!"));
      * ```
      */
     addCombination(config) {
-        const { keys, callback, context, preventDefault = false, id, strict = false } = config;
+        const { keys, context, preventDefault = false, id, strict = false, target = document, event: eventType = "keydown" } = config;
+        if (config.callback) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" was provided a callback, but "addCombination" now returns an Observable. The callback will be ignored. Please subscribe to the returned Observable instead.`);
+        }
         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.`);
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" has both a context(${context}) and the "strict" flag. The "strict" flag will be ignored.`);
+        }
+        let keyTriggers;
+        if (typeof keys === "string" && keys.length > 1 && keys.includes("+")) {
+            keyTriggers = this._parseCombinationString(keys);
+        }
+        else {
+            keyTriggers = Array.isArray(keys) ? keys : [keys];
         }
-        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.`);
-            return undefined;
+            console.warn(`${Hotkeys.LOG_PREFIX} "keys" definition for combination shortcut "${id}" is empty or invalid. Shortcut not added.`);
+            return EMPTY;
         }
+        const sourceStream$ = this._getEventStream(eventType, target);
         const observables = [];
         const logParts = [];
         for (const keyInput of keyTriggers) {
             const parsedTrigger = this._parseKeyTrigger(keyInput, id);
             if (!parsedTrigger) {
-                // Error already logged by _parseKeyTrigger
-                return undefined;
+                return EMPTY;
             }
             const { configuredMainKey, ctrlKeyConfig, altKeyConfig, shiftKeyConfig, metaKeyConfig, logDetails } = parsedTrigger;
             logParts.push(`{ ${logDetails} }`);
-            const stream = this.filterByContext(this.keydown$, context, strict).pipe(filter(event => {
+            const stream = this.filterByContext(sourceStream$, 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);
@@ -331,7 +451,7 @@ export class Hotkeys {
                 }
                 for (const [, otherAS] of this.activeShortcuts) {
                     if (otherAS.config.id !== id &&
-                        'keys' in otherAS.config &&
+                        "keys" in otherAS.config &&
                         otherAS.config.context === currentSpecificContext &&
                         this._shortcutMatchesEvent(otherAS.config, event)) {
                         if (this.debugMode) {
@@ -345,13 +465,15 @@ export class Hotkeys {
             observables.push(stream);
         }
         if (observables.length === 0) {
-            // Should be caught by keyTriggers.length === 0, but as a safeguard.
+            // This path should now be much harder to hit, but remains a safeguard.
             console.warn(`${Hotkeys.LOG_PREFIX} No valid key triggers for combination shortcut "${id}". Shortcut not added.`);
-            return undefined;
+            return EMPTY;
         }
+        const terminator$ = new Subject();
         const finalShortcut$ = merge(...observables);
-        const overallLogDetails = Array.isArray(keys) ? `Triggers: [ ${logParts.join(", ")} ]` : logParts[0];
-        const subscription = finalShortcut$.pipe(tap(event => {
+        const overallLogDetails = `Triggers: [ ${logParts.join(", ")} ]`;
+        this._registerShortcut(config, terminator$, ShortcutTypes.Combination, overallLogDetails);
+        return finalShortcut$.pipe(tap(event => {
             if (this.debugMode) {
                 const preventAction = preventDefault ? ", preventing default" : "";
                 console.log(`${Hotkeys.LOG_PREFIX} Combination "${id}" triggered by key "${event.key}" ${preventAction}.`);
@@ -361,54 +483,67 @@ export class Hotkeys {
         }), catchError(err => {
             console.error(`${Hotkeys.LOG_PREFIX} Error in combination stream for shortcut "${id}":`, err);
             return EMPTY;
-        })).subscribe(event => {
-            try {
-                callback(event);
-            }
-            catch (e) {
-                console.error(`${Hotkeys.LOG_PREFIX} Error in user callback for combination shortcut "${id}":`, e);
-            }
-        });
-        return this._registerShortcut(config, subscription, ShortcutTypes.Combination, overallLogDetails);
+        }), takeUntil(terminator$));
     }
     /**
-     * Registers a key sequence shortcut (e.g., g -> i, or ArrowUp -> ArrowUp -> ArrowDown).
-     * The callback is triggered when the specified keys are pressed in order.
+     * Registers a key sequence shortcut (e.g., g -> i, or ArrowUp -> ArrowUp -> ArrowDown)
+     * and returns an Observable that emits the final `KeyboardEvent` of the sequence when it's completed.
      * An optional timeout can be specified for the time allowed between key presses in the sequence.
      * @param config - Configuration object for the key sequence.
      * See {@link KeySequenceConfig} for details.
      * Each key in the `sequence` array must be a value from the `Keys` object.
-     * @returns The ID of the registered shortcut if successful, or `undefined` if the configuration is invalid (e.g., empty sequence or invalid keys).
-     * A warning is logged to the console if the configuration is invalid or if a shortcut with the same ID is overwritten.
+     * Or using string for `sequence`.
+     * @returns An `Observable<KeyboardEvent>` that you can subscribe to. The stream will be automatically
+     * completed if the shortcut is removed via `remove(id)` or `destroy()`, or if it's overwritten.
+     * If the configuration is invalid, an empty Observable is returned and a warning is logged.
      * @example
      * ```typescript
      * import { Keys } from "./keys";
-     * keyManager.addSequence({
+     * const konami$ = keyManager.addSequence({
      * id: "konamiCode",
      * sequence: [Keys.ArrowUp, Keys.ArrowUp, Keys.ArrowDown, Keys.ArrowDown, Keys.A, Keys.B],
-     * callback: () => console.log("Konami!"),
      * sequenceTimeoutMs: 2000 // 2 seconds between keys
      * });
+     * konami$.subscribe(event => console.log("Konami!", event));
+     * ```
+     * ```typescript
+     * // Using a string for the sequence
+     * const konami$ = keyManager.addSequence({
+     * id: "konamiCode",
+     * sequence: "up -> up -> down -> down -> a -> b",
+     * sequenceTimeoutMs: 2000
+     * });
+     * konami$.subscribe(event => console.log("Konami!", event));
      * ```
      */
     addSequence(config) {
-        const { sequence, callback, context, preventDefault = false, id, sequenceTimeoutMs, strict = false } = config;
-        if (!Array.isArray(sequence) || sequence.length === 0) {
+        const { sequence, context, preventDefault = false, id, sequenceTimeoutMs, strict = false, target = document, event: eventType = "keydown" } = config;
+        if (config.callback) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" was provided a callback, but "addSequence" now returns an Observable. The callback will be ignored. Please subscribe to the returned Observable instead.`);
+        }
+        let configuredSequence;
+        if (typeof sequence === "string") {
+            configuredSequence = this._parseSequenceString(sequence);
+        }
+        else {
+            configuredSequence = sequence;
+        }
+        if (!Array.isArray(configuredSequence) || configuredSequence.length === 0) {
             console.warn(`${Hotkeys.LOG_PREFIX} Sequence for shortcut "${id}" is empty or invalid. Shortcut not added.`);
-            return undefined;
+            return EMPTY;
         }
         // Corrected validation: Check for actual empty string, not a string that trims to empty.
-        if (sequence.some(key => typeof key !== "string" || key === "")) { // StandardKey type should prevent empty strings.
+        if (configuredSequence.some(key => typeof key !== "string" || key === "")) { // StandardKey type should prevent empty strings.
             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;
+            return EMPTY;
         }
         if (context && strict) {
-            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" has both a context and the 'strict' flag. The 'strict' flag will be ignored.`);
+            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, strict);
+        const sourceStream$ = this._getEventStream(eventType, target);
+        const baseKeydownStream$ = this.filterByContext(sourceStream$, context, strict);
         if (sequenceTimeoutMs && sequenceTimeoutMs > 0) {
             shortcut$ = baseKeydownStream$.pipe(scan((acc, event) => {
                 let { matchedEvents, lastEventTime } = acc;
@@ -465,6 +600,7 @@ export class Hotkeys {
                 return events.every((event, index) => compareKey(event.key, configuredSequence[index]));
             }));
         }
+        const terminator$ = new Subject();
         const finalShortcutWithPriority$ = shortcut$.pipe(filter((completedEvents) => {
             if (context != null || strict) { // This sequence is NOT global or strict
                 return true;
@@ -478,7 +614,7 @@ export class Hotkeys {
                 if (otherAS.config.id !== id &&
                     "sequence" in otherAS.config &&
                     otherAS.config.context === currentSpecificContext &&
-                    this._areSequencesIdentical(sequence, otherAS.config.sequence)) {
+                    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}".`);
                     }
@@ -499,22 +635,13 @@ export class Hotkeys {
             console.error(`${Hotkeys.LOG_PREFIX} Error in sequence stream for shortcut "${id}":`, err);
             return EMPTY;
         }));
-        const subscription = finalShortcutWithPriority$.subscribe((events) => {
-            try {
-                // Ensure callback receives the last event of the sequence, similar to combination.
-                if (events.length > 0)
-                    callback(events[events.length - 1]);
-            }
-            catch (e) {
-                console.error(`${Hotkeys.LOG_PREFIX} Error in user callback for sequence shortcut "${id}":`, e);
-            }
-        });
-        const logDetails = `Sequence: ${sequence.join(" -> ")}${sequenceTimeoutMs && sequenceTimeoutMs > 0 ? ` (timeout: ${sequenceTimeoutMs}ms)` : ""}`;
-        return this._registerShortcut(config, subscription, ShortcutTypes.Sequence, logDetails);
+        const logDetails = `Sequence: ${configuredSequence.join(" -> ")}${sequenceTimeoutMs && sequenceTimeoutMs > 0 ? ` (timeout: ${sequenceTimeoutMs}ms)` : ""}`;
+        this._registerShortcut(config, terminator$, ShortcutTypes.Sequence, logDetails);
+        return finalShortcutWithPriority$.pipe(map((events) => events[events.length - 1]), takeUntil(terminator$));
     }
     /**
      * Removes a registered shortcut by its ID.
-     * This will unsubscribe from the underlying keyboard event stream for that shortcut.
+     * This will complete the corresponding Observable stream for any subscribers.
      * @param id - The unique ID of the shortcut to remove.
      * @returns True if the shortcut was found and removed, false otherwise.
      * A warning is logged to the console if no shortcut with the given ID is found.
@@ -522,7 +649,8 @@ export class Hotkeys {
     remove(id) {
         const shortcut = this.activeShortcuts.get(id);
         if (shortcut) {
-            shortcut.subscription.unsubscribe();
+            shortcut.terminator$.next();
+            shortcut.terminator$.complete();
             this.activeShortcuts.delete(id);
             if (this.debugMode)
                 console.log(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" removed.`);
@@ -558,8 +686,11 @@ export class Hotkeys {
      */
     destroy() {
         if (this.debugMode)
-            console.log(`${Hotkeys.LOG_PREFIX} Destroying library instance and unsubscribing all shortcuts.`);
-        this.activeShortcuts.forEach(shortcut => shortcut.subscription.unsubscribe());
+            console.log(`${Hotkeys.LOG_PREFIX} Destroying library instance and terminating all shortcut streams.`);
+        this.activeShortcuts.forEach(shortcut => {
+            shortcut.terminator$.next();
+            shortcut.terminator$.complete();
+        });
         this.activeShortcuts.clear();
         this.activeContext$.complete();
         if (this.debugMode)