rx-hotkeys 2.6.0 → 3.0.0

package/dist/hotkeys.test.js

@@ -2,7 +2,7 @@ import { describe, it, before, beforeEach, afterEach, mock } from "node:test";
 import assert from "node:assert";
 import { Hotkeys, ShortcutTypes } from "./hotkeys.js";
 import { Keys } from "./keys.js";
-import { fromEvent, BehaviorSubject } from "rxjs";
+import { fromEvent, BehaviorSubject, Observable, EMPTY } from "rxjs";
 import { createMockFn, dispatchKeyEvent } from "./testutils.js";
 import { JSDOM } from "jsdom";
 // --- JSDOM and RxJS setup for Node.js tests ---
@@ -10,21 +10,31 @@ let dom;
 let window;
 let document;
 let originalPerformanceNow;
+let testArea; // For target tests
 before(() => {
-    dom = new JSDOM("<!DOCTYPE html><html><body></body></html>", {
+    dom = new JSDOM(`<!DOCTYPE html><html><body><div id="test-area"></div></body></html>`, {
         url: "http://localhost",
     });
     window = dom.window;
     document = window.document;
+    testArea = document.getElementById("test-area");
     // @ts-ignore
     global.document = document;
     // @ts-ignore
+    global.window = window;
+    // @ts-ignore
+    global.HTMLElement = window.HTMLElement;
+    // @ts-ignore
     global.KeyboardEvent = window.KeyboardEvent;
     // @ts-ignore
     global.BehaviorSubject = BehaviorSubject;
     // @ts-ignore
     global.fromEvent = fromEvent;
     // @ts-ignore
+    global.Observable = Observable;
+    // @ts-ignore
+    global.EMPTY = EMPTY;
+    // @ts-ignore
     if (typeof global.performance === "undefined") {
         // @ts-ignore
         global.performance = {};
@@ -242,82 +252,92 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
         });
     });
     describe("addCombination", () => {
-        it(`should trigger callback for a simple key combination (e.g., "A")`, () => {
-            const config = { id: "simpleA", keys: { key: Keys.A }, callback: mockCallback };
-            const result = keyManager.addCombination(config);
-            assert.strictEqual(result, "simpleA");
-            dispatchKeyEvent("a");
+        it(`should return an Observable that emits on a simple key combination (e.g., "A")`, () => {
+            const config = { id: "simpleA", keys: { key: Keys.A } };
+            const combo$ = keyManager.addCombination(config);
+            assert(combo$ instanceof Observable, "Did not return an Observable");
+            combo$.subscribe(mockCallback);
+            dispatchKeyEvent(document, "a");
             assert.strictEqual(mockCallback.calledCount, 1, `Callback for "a" not called`);
             mockCallback.mockClear();
-            dispatchKeyEvent("A");
+            dispatchKeyEvent(document, "A");
             assert.strictEqual(mockCallback.calledCount, 1, `Callback for "A" not called`);
         });
-        it("should return undefined and warn if keys.key is null or undefined (runtime check in object form)", () => {
-            const config = { id: "nullKey", keys: { key: null }, callback: mockCallback };
-            const result = keyManager.addCombination(config);
-            assert.strictEqual(result, undefined, "Should return undefined for null key");
+        it("should return an empty observable and warn if keys.key is null or undefined", () => {
+            const config = { id: "nullKey", keys: { key: null } };
+            const combo$ = keyManager.addCombination(config);
+            combo$.subscribe(mockCallback);
             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 string value from Keys.`));
+            assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid "key" property in shortcut "nullKey"`));
+            dispatchKeyEvent(document, "a");
+            assert.strictEqual(mockCallback.calledCount, 0);
         });
-        it("should pass the KeyboardEvent to the callback", () => {
-            const config = { id: "eventPass", keys: { key: Keys.E }, callback: mockCallback };
-            keyManager.addCombination(config);
-            const event = dispatchKeyEvent("e");
+        it("should pass the KeyboardEvent to the subscriber", () => {
+            const config = { id: "eventPass", keys: { key: Keys.E } };
+            keyManager.addCombination(config).subscribe(mockCallback);
+            const event = dispatchKeyEvent(document, "e");
             assert.strictEqual(mockCallback.calledCount, 1);
             assert.deepStrictEqual(mockCallback.lastArgs, [event]);
         });
-        it("should trigger callback for a combination with Ctrl key", () => {
-            const config = { id: "ctrlS", keys: { key: Keys.S, ctrlKey: true }, callback: mockCallback };
-            keyManager.addCombination(config);
-            dispatchKeyEvent("s", { ctrlKey: true });
+        it("should emit for a combination with Ctrl key", () => {
+            const config = { id: "ctrlS", keys: { key: Keys.S, ctrlKey: true } };
+            keyManager.addCombination(config).subscribe(mockCallback);
+            dispatchKeyEvent(document, "s", "keydown", { ctrlKey: true });
             assert.strictEqual(mockCallback.calledCount, 1);
         });
-        it("should NOT trigger callback if specified modifier key (ctrlKey: false) is false and event has it true", () => {
-            const config = { id: "noCtrlA", keys: { key: Keys.A, ctrlKey: false }, callback: mockCallback };
-            keyManager.addCombination(config);
-            dispatchKeyEvent("a", { ctrlKey: true });
+        it("should NOT emit if specified modifier key (ctrlKey: false) is false and event has it true", () => {
+            const config = { id: "noCtrlA", keys: { key: Keys.A, ctrlKey: false } };
+            keyManager.addCombination(config).subscribe(mockCallback);
+            dispatchKeyEvent(document, "a", "keydown", { ctrlKey: true });
             assert.strictEqual(mockCallback.calledCount, 0);
-            dispatchKeyEvent("a", { ctrlKey: false });
+            dispatchKeyEvent(document, "a", "keydown", { ctrlKey: false });
             assert.strictEqual(mockCallback.calledCount, 1);
         });
-        it("should trigger for special keys like Escape (object form)", () => {
-            const config = { id: "escapeKeyObj", keys: { key: Keys.Escape }, callback: mockCallback };
-            keyManager.addCombination(config);
-            dispatchKeyEvent("Escape"); // Event key matches Keys.Escape
+        it("should emit for special keys like Escape (object form)", () => {
+            const config = { id: "escapeKeyObj", keys: { key: Keys.Escape } };
+            keyManager.addCombination(config).subscribe(mockCallback);
+            dispatchKeyEvent(document, "Escape"); // Event key matches Keys.Escape
             assert.strictEqual(mockCallback.calledCount, 1);
         });
         it("should handle preventDefault correctly (object form)", () => {
-            const config = { id: "preventAObj", keys: { key: Keys.A }, callback: mockCallback, preventDefault: true };
-            keyManager.addCombination(config);
-            const event = dispatchKeyEvent("a");
+            const config = { id: "preventAObj", keys: { key: Keys.A }, preventDefault: true };
+            keyManager.addCombination(config).subscribe(mockCallback);
+            const event = dispatchKeyEvent(document, "a");
             assert.strictEqual(mockCallback.calledCount, 1);
             assert.strictEqual(event.defaultPrevented, true);
         });
-        it("should overwrite an existing combination with the same ID and warn", () => {
+        it("should overwrite an existing combination, warn, and terminate the old stream", () => {
             const firstCallback = createMockFn();
+            const firstComplete = createMockFn();
             const secondCallback = createMockFn();
-            keyManager.addCombination({ id: "combo1", keys: { key: Keys.K }, callback: firstCallback });
+            const first$ = keyManager.addCombination({ id: "combo1", keys: { key: Keys.K } });
+            first$.subscribe({ next: firstCallback, complete: firstComplete });
             consoleWarnMock.mock.resetCalls();
-            keyManager.addCombination({ id: "combo1", keys: { key: Keys.K, ctrlKey: true }, callback: secondCallback });
+            const second$ = keyManager.addCombination({ id: "combo1", keys: { key: Keys.K, ctrlKey: true } });
+            second$.subscribe(secondCallback);
             assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
             assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Shortcut with ID "combo1" already exists`));
-            dispatchKeyEvent("k");
+            assert.strictEqual(firstComplete.calledCount, 1, "First observable should have completed");
+            dispatchKeyEvent(document, "k");
             assert.strictEqual(firstCallback.calledCount, 0);
-            dispatchKeyEvent("k", { ctrlKey: true });
+            dispatchKeyEvent(document, "k", "keydown", { ctrlKey: true });
             assert.strictEqual(secondCallback.calledCount, 1);
         });
-        it("should log an error via console.error if callback throws, and not affect other shortcuts", () => {
-            const errorCallback = () => { throw new Error("Test callback error"); };
+        it("should not affect other shortcuts if one subscription throws an error", () => {
             const workingCallback = createMockFn();
-            keyManager.addCombination({ id: "errorCombo", keys: { key: Keys.E }, callback: errorCallback });
-            keyManager.addCombination({ id: "workingCombo", keys: { key: Keys.W }, callback: workingCallback });
-            dispatchKeyEvent("e");
-            assert.strictEqual(consoleErrorMock.mock.calls.length, 1);
-            assert.ok(consoleErrorMock.mock.calls[0].arguments[0].includes(`Error in user callback for combination shortcut "errorCombo"`));
-            dispatchKeyEvent("w");
-            assert.strictEqual(workingCallback.calledCount, 1);
-        });
-        it("should trigger callback if any of multiple key combinations are pressed", () => {
+            const erroringCallback = () => { throw new Error("Test callback error"); };
+            const error$ = keyManager.addCombination({ id: "errorCombo", keys: { key: Keys.E } });
+            // Suppress unhandled exception message in test runner output
+            error$.subscribe(erroringCallback, () => { });
+            const working$ = keyManager.addCombination({ id: "workingCombo", keys: { key: Keys.W } });
+            working$.subscribe(workingCallback);
+            // Dispatch event that causes an error in the subscription
+            //dispatchKeyEvent(document, "e");
+            // Dispatch another event to ensure the other shortcut still works
+            dispatchKeyEvent(document, "w");
+            assert.strictEqual(workingCallback.calledCount, 1, "Working callback should have been called");
+        });
+        it("should emit if any of multiple key combinations are pressed", () => {
             const config = {
                 id: "multiCombo",
                 keys: [
@@ -325,102 +345,124 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
                     Keys.Escape, // Escape
                     { key: Keys.B, shiftKey: true, altKey: true } // Shift+Alt+B
                 ],
-                callback: mockCallback
             };
-            keyManager.addCombination(config);
-            dispatchKeyEvent("A", { ctrlKey: true });
+            keyManager.addCombination(config).subscribe(mockCallback);
+            dispatchKeyEvent(document, "A", "keydown", { ctrlKey: true });
             assert.strictEqual(mockCallback.calledCount, 1, "Ctrl+A did not trigger");
-            dispatchKeyEvent("Escape");
+            dispatchKeyEvent(document, "Escape");
             assert.strictEqual(mockCallback.calledCount, 2, "Escape did not trigger");
-            dispatchKeyEvent("B", { shiftKey: true, altKey: true });
+            dispatchKeyEvent(document, "B", "keydown", { shiftKey: true, altKey: true });
             assert.strictEqual(mockCallback.calledCount, 3, "Shift+Alt+B did not trigger");
-            dispatchKeyEvent("C"); // Should not trigger
+            dispatchKeyEvent(document, "C"); // Should not trigger
             assert.strictEqual(mockCallback.calledCount, 3, "Unrelated key C triggered");
         });
-        it(`should return undefined and warn if "keys" array is empty`, () => {
-            const config = { id: "emptyKeysArray", keys: [], callback: mockCallback };
-            const result = keyManager.addCombination(config);
-            assert.strictEqual(result, undefined);
-            assert.ok(consoleWarnMock.mock.calls.some(call => call.arguments[0].includes(`"keys" array for combination shortcut "emptyKeysArray" is empty`)));
-        });
-        it(`should return undefined and warn if a key in "keys" array is invalid (shorthand)`, () => {
-            const config = { id: "invalidInArrayShorthand", keys: [Keys.A, ""], callback: mockCallback };
-            const result = keyManager.addCombination(config);
-            assert.strictEqual(result, undefined);
-            assert.ok(consoleWarnMock.mock.calls.some(call => call.arguments[0].includes(`Invalid key (shorthand) in shortcut "invalidInArrayShorthand"`)));
-        });
-        it(`should return undefined and warn if a key in "keys" array is invalid (object)`, () => {
-            const config = { id: "invalidInArrayObject", keys: [Keys.A, { key: "" }], callback: mockCallback };
-            const result = keyManager.addCombination(config);
-            assert.strictEqual(result, undefined);
+        it(`should return an empty observable and warn if "keys" array is empty`, () => {
+            const config = { id: "emptyKeysArray", keys: [] };
+            const combo$ = keyManager.addCombination(config);
+            combo$.subscribe(mockCallback);
+            assert.ok(consoleWarnMock.mock.calls.some(call => call.arguments[0].includes(`"keys" definition for combination shortcut "emptyKeysArray" is empty`)));
+            dispatchKeyEvent(document, "a");
+            assert.strictEqual(mockCallback.calledCount, 0);
+        });
+        it(`should return an empty observable and warn if a key in "keys" array is invalid (shorthand)`, () => {
+            const config = { id: "invalidInArrayShorthand", keys: [Keys.A, ""] };
+            const combo$ = keyManager.addCombination(config);
+            combo$.subscribe(mockCallback);
+            assert.ok(consoleWarnMock.mock.calls.some(call => call.arguments[0].includes(`Could not parse key: "" in shortcut "invalidInArrayShorthand"`)));
+        });
+        it(`should return an empty observable and warn if a key in "keys" array is invalid (object)`, () => {
+            const config = { id: "invalidInArrayObject", keys: [Keys.A, { key: "" }] };
+            const combo$ = keyManager.addCombination(config);
+            combo$.subscribe(mockCallback);
             assert.ok(consoleWarnMock.mock.calls.some(call => call.arguments[0].includes(`Invalid "key" property in shortcut "invalidInArrayObject"`)));
         });
         it("should correctly log multiple key triggers in debug mode", () => {
             const consoleLogMock = mock.method(console, "log");
             keyManager.setDebugMode(true);
-            keyManager.addCombination({ id: "multiLog", keys: [Keys.F1, { key: Keys.F2, ctrlKey: true }], callback: mockCallback });
+            keyManager.addCombination({ id: "multiLog", keys: [Keys.F1, { key: Keys.F2, ctrlKey: true }] });
             assert.ok(consoleLogMock.mock.calls.some(call => call.arguments[0].includes(`Triggers: [ { key: "F1" (no mods) }, { key: "F2", ctrl: true } ]`)), "Multi-trigger log format incorrect");
             consoleLogMock.mock.restore();
         });
         describe("addCombination - Shorthand Syntax", () => {
-            it("should trigger callback for a simple key using shorthand (e.g., Keys.X)", () => {
-                const config = { id: "shorthandX", keys: Keys.X, callback: mockCallback };
-                keyManager.addCombination(config);
-                dispatchKeyEvent(Keys.X.toLowerCase());
+            it("should emit for a simple key using shorthand (e.g., Keys.X)", () => {
+                const config = { id: "shorthandX", keys: Keys.X };
+                keyManager.addCombination(config).subscribe(mockCallback);
+                dispatchKeyEvent(document, Keys.X.toLowerCase());
                 assert.strictEqual(mockCallback.calledCount, 1, `Callback for "x" (shorthand) not called`);
                 mockCallback.mockClear();
-                dispatchKeyEvent(Keys.X);
+                dispatchKeyEvent(document, Keys.X);
                 assert.strictEqual(mockCallback.calledCount, 1, `Callback for "X" (shorthand) not called`);
             });
-            it("should NOT trigger callback for shorthand if modifier is pressed", () => {
-                const config = { id: "shorthandY", keys: Keys.Y, callback: mockCallback };
-                keyManager.addCombination(config);
-                dispatchKeyEvent(Keys.Y, { ctrlKey: true });
+            it("should NOT emit for shorthand if modifier is pressed", () => {
+                const config = { id: "shorthandY", keys: Keys.Y };
+                keyManager.addCombination(config).subscribe(mockCallback);
+                dispatchKeyEvent(document, Keys.Y, "keydown", { ctrlKey: true });
                 assert.strictEqual(mockCallback.calledCount, 0, `Callback for "y" (shorthand) should not be called with Ctrl`);
                 mockCallback.mockClear();
-                dispatchKeyEvent(Keys.Y, { altKey: true });
+                dispatchKeyEvent(document, Keys.Y, "keydown", { altKey: true });
                 assert.strictEqual(mockCallback.calledCount, 0, `Callback for "y" (shorthand) should not be called with Alt`);
                 mockCallback.mockClear();
-                dispatchKeyEvent(Keys.Y, { shiftKey: true });
+                dispatchKeyEvent(document, Keys.Y, "keydown", { shiftKey: true });
                 assert.strictEqual(mockCallback.calledCount, 0, `Callback for "y" (shorthand) should not be called with Shift`);
                 mockCallback.mockClear();
-                dispatchKeyEvent(Keys.Y, { metaKey: true });
+                dispatchKeyEvent(document, Keys.Y, "keydown", { metaKey: true });
                 assert.strictEqual(mockCallback.calledCount, 0, `Callback for "y" (shorthand) should not be called with Meta`);
             });
-            it("should trigger callback for shorthand if ONLY the key is pressed (no modifiers)", () => {
-                const config = { id: "shorthandZ", keys: Keys.Z, callback: mockCallback };
-                keyManager.addCombination(config);
-                dispatchKeyEvent(Keys.Z, { ctrlKey: false, altKey: false, shiftKey: false, metaKey: false });
+            it("should emit for shorthand if ONLY the key is pressed (no modifiers)", () => {
+                const config = { id: "shorthandZ", keys: Keys.Z };
+                keyManager.addCombination(config).subscribe(mockCallback);
+                dispatchKeyEvent(document, Keys.Z, "keydown", { ctrlKey: false, altKey: false, shiftKey: false, metaKey: false });
                 assert.strictEqual(mockCallback.calledCount, 1);
             });
             it("should handle preventDefault correctly for shorthand", () => {
-                const config = { id: "shorthandPrevent", keys: Keys.P, callback: mockCallback, preventDefault: true };
-                keyManager.addCombination(config);
-                const event = dispatchKeyEvent(Keys.P.toLowerCase());
+                const config = { id: "shorthandPrevent", keys: Keys.P, preventDefault: true };
+                keyManager.addCombination(config).subscribe(mockCallback);
+                const event = dispatchKeyEvent(document, Keys.P.toLowerCase());
                 assert.strictEqual(mockCallback.calledCount, 1);
                 assert.strictEqual(event.defaultPrevented, true);
             });
             it("should respect context for shorthand", () => {
-                const config = { id: "shorthandContext", keys: Keys.C, callback: mockCallback, context: "editor" };
-                keyManager.addCombination(config);
+                const config = { id: "shorthandContext", keys: Keys.C, context: "editor" };
+                keyManager.addCombination(config).subscribe(mockCallback);
                 keyManager.setContext("other");
-                dispatchKeyEvent(Keys.C.toLowerCase());
+                dispatchKeyEvent(document, Keys.C.toLowerCase());
                 assert.strictEqual(mockCallback.calledCount, 0);
                 keyManager.setContext("editor");
-                dispatchKeyEvent(Keys.C.toLowerCase());
+                dispatchKeyEvent(document, Keys.C.toLowerCase());
                 assert.strictEqual(mockCallback.calledCount, 1);
             });
-            it("should return undefined and warn if shorthand key is an empty string", () => {
-                const config = { id: "emptyShorthand", keys: "", callback: mockCallback };
-                const result = keyManager.addCombination(config);
-                assert.strictEqual(result, undefined);
+            it("should return an empty observable and warn if shorthand key is an empty string", () => {
+                const config = { id: "emptyShorthand", keys: "" };
+                const combo$ = keyManager.addCombination(config);
+                combo$.subscribe(mockCallback);
+                assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
+                assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Could not parse key: "" in shortcut "emptyShorthand"`));
+            });
+            it("should return an empty observable and warn if shorthand key is an empty array", () => {
+                const config = { id: "emptyArrayShorthand", keys: [] };
+                const combo$ = keyManager.addCombination(config);
+                combo$.subscribe(mockCallback);
+                assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
+                assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`"keys" definition for combination shortcut "emptyArrayShorthand" is empty or invalid. Shortcut not added.`));
+            });
+            it("should return an empty observable and warn if shorthand key is an empty string in array", () => {
+                const config = { id: "emptyStringShorthand", keys: [""] };
+                const combo$ = keyManager.addCombination(config);
+                combo$.subscribe(mockCallback);
                 assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
-                assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid key (shorthand) in shortcut "emptyShorthand". Key string must not be empty.`));
+                assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Could not parse key: "" in shortcut "emptyStringShorthand"`));
+            });
+            it("should return an empty observable and warn if shorthand key is invalid", () => {
+                const config = { id: "invalidKeyPropertyShorthand", keys: { key: "" } };
+                const combo$ = keyManager.addCombination(config);
+                combo$.subscribe(mockCallback);
+                assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
+                assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid "key" property in shortcut "invalidKeyPropertyShorthand". Key must be a non-empty string value from Keys.`));
             });
             it("should correctly log shorthand key details in debug mode", () => {
                 const consoleLogMock = mock.method(console, "log");
                 keyManager.setDebugMode(true);
-                const config = { id: "debugShorthand", keys: Keys.D, callback: mockCallback };
+                const config = { id: "debugShorthand", keys: Keys.D };
                 keyManager.addCombination(config);
                 const logMessage = consoleLogMock.mock.calls.find(call => call.arguments[0].includes(`combination shortcut "debugShorthand" added.`));
                 assert.ok(logMessage, "Debug log for adding shortcut not found");
@@ -428,20 +470,153 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
                 consoleLogMock.mock.restore();
                 keyManager.setDebugMode(false);
             });
-            it("should trigger callback for Keys.Space using shorthand", () => {
-                const config = { id: "spaceShorthand", keys: Keys.Space, callback: mockCallback };
-                keyManager.addCombination(config);
-                dispatchKeyEvent(" "); // Event key for space is " "
+            it("should emit for Keys.Space using shorthand", () => {
+                const config = { id: "spaceShorthand", keys: Keys.Space };
+                keyManager.addCombination(config).subscribe(mockCallback);
+                dispatchKeyEvent(document, " "); // Event key for space is " "
                 assert.strictEqual(mockCallback.calledCount, 1, "Callback for Keys.Space (shorthand) not called");
             });
-            it("should trigger callback for Keys.Space using object form", () => {
-                const config = { id: "spaceObject", keys: { key: Keys.Space }, callback: mockCallback };
-                keyManager.addCombination(config);
-                dispatchKeyEvent(" ");
+            it("should emit for Keys.Space using object form", () => {
+                const config = { id: "spaceObject", keys: { key: Keys.Space } };
+                keyManager.addCombination(config).subscribe(mockCallback);
+                dispatchKeyEvent(document, " ");
                 assert.strictEqual(mockCallback.calledCount, 1, "Callback for Keys.Space (object form) not called");
             });
         });
     });
+    describe("String-based Definitions", () => {
+        it(`should parse and trigger a simple string "ctrl+s"`, () => {
+            keyManager.addCombination({ id: "strSave", keys: "ctrl+s" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "s", "keydown", { ctrlKey: true });
+            assert.strictEqual(mockCallback.calledCount, 1);
+            dispatchKeyEvent(document, "s");
+            assert.strictEqual(mockCallback.calledCount, 1);
+        });
+        it(`should parse and trigger "shift+alt+k"`, () => {
+            keyManager.addCombination({ id: "strComplex", keys: "shift+alt+k" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "k", "keydown", { shiftKey: true, altKey: true });
+            assert.strictEqual(mockCallback.calledCount, 1);
+        });
+        it(`should parse aliases like "cmd+p"`, () => {
+            keyManager.addCombination({ id: "strAlias", keys: "cmd+p" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "p", "keydown", { metaKey: true });
+            assert.strictEqual(mockCallback.calledCount, 1);
+        });
+        it(`should parse special key strings like "escape"`, () => {
+            keyManager.addCombination({ id: "strSpecial", keys: "escape" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "Escape");
+            assert.strictEqual(mockCallback.calledCount, 1);
+        });
+        it(`should parse sequence string "g -> i"`, () => {
+            keyManager.addSequence({ id: "strSeq", sequence: "g -> i" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "g");
+            dispatchKeyEvent(document, "i");
+            assert.strictEqual(mockCallback.calledCount, 1);
+        });
+        it(`should parse sequence string with special keys "up -> down -> enter"`, () => {
+            keyManager.addSequence({ id: "strSeqSpecial", sequence: "up -> down -> enter" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "ArrowUp");
+            dispatchKeyEvent(document, "ArrowDown");
+            dispatchKeyEvent(document, "Enter");
+            assert.strictEqual(mockCallback.calledCount, 1);
+        });
+        it("should warn and return empty on invalid string", () => {
+            const combo$ = keyManager.addCombination({ id: "invalid", keys: "ctrl+badkey" });
+            combo$.subscribe(mockCallback);
+            assert.ok(consoleWarnMock.mock.calls.some(c => c.arguments[0].includes(`Could not parse key: "badkey"`)));
+            assert.strictEqual(mockCallback.calledCount, 0);
+        });
+    });
+    describe("Normalization and Edge Case Tests", () => {
+        it(`should handle the "+" key as a shorthand, not a combination`, () => {
+            keyManager.addCombination({ id: "plusKey", keys: Keys.KeypadAdd }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "+");
+            assert.strictEqual(mockCallback.calledCount, 1, `Callback for "+" key not called`);
+        });
+        it(`should handle "escape" (lowercase) and normalize it to match the "Escape" event key`, () => {
+            keyManager.addCombination({ id: "lowerEscape", keys: "escape" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "Escape"); // Event key from browser is capitalized
+            assert.strictEqual(mockCallback.calledCount, 1, `Lowercase "escape" did not match event`);
+        });
+        it(`should handle "ESC" (uppercase) and normalize it`, () => {
+            keyManager.addCombination({ id: "upperEsc", keys: "ESC" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "Escape");
+            assert.strictEqual(mockCallback.calledCount, 1, `Uppercase "ESC" did not match event`);
+        });
+        it(`should handle a single-word modifier alias like "cmd" as a shorthand for the "Meta" key`, () => {
+            keyManager.addCombination({ id: "cmdKey", keys: "cmd" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "Meta"); // Event key for command key is "Meta"
+            assert.strictEqual(mockCallback.calledCount, 1, `Alias "cmd" did not match "Meta" key event`);
+        });
+        it(`should handle combination string with extra spaces like " ctrl + s "`, () => {
+            keyManager.addCombination({ id: "paddedCombo", keys: " ctrl + s " }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "s", "keydown", { ctrlKey: true });
+            assert.strictEqual(mockCallback.calledCount, 1, "Padded combination string failed to parse");
+        });
+    });
+    describe("New Feature: Element-Scoped Listeners", () => {
+        let el1, el2;
+        beforeEach(() => {
+            el1 = document.createElement("div");
+            el2 = document.createElement("div");
+            document.body.append(el1, el2);
+        });
+        afterEach(() => {
+            el1.remove();
+            el2.remove();
+        });
+        it("should only trigger shortcut on the specified target element", () => {
+            keyManager.addCombination({ id: "scoped", keys: "a", target: el1 }).subscribe(mockCallback);
+            dispatchKeyEvent(el1, "a");
+            assert.strictEqual(mockCallback.calledCount, 1, "Should trigger on target element");
+            dispatchKeyEvent(el2, "a");
+            assert.strictEqual(mockCallback.calledCount, 1, "Should NOT trigger on another element");
+            dispatchKeyEvent(document, "a");
+            assert.strictEqual(mockCallback.calledCount, 1, "Should NOT trigger on document");
+        });
+        it("should trigger global shortcut if no target is specified", () => {
+            keyManager.addCombination({ id: "global", keys: "b" }).subscribe(mockCallback);
+            // Event bubbles up from el1 to document
+            dispatchKeyEvent(el1, "b");
+            assert.strictEqual(mockCallback.calledCount, 1, "Should trigger on event from child element");
+            dispatchKeyEvent(document, "b");
+            assert.strictEqual(mockCallback.calledCount, 2, "Should trigger on document directly");
+        });
+        it("should work for sequences on a specific target", () => {
+            keyManager.addSequence({ id: "scopedSeq", sequence: "a -> b", target: el1 }).subscribe(mockCallback);
+            dispatchKeyEvent(el1, "a");
+            dispatchKeyEvent(el1, "b");
+            assert.strictEqual(mockCallback.calledCount, 1, "Sequence should trigger on target");
+            dispatchKeyEvent(document, "a");
+            dispatchKeyEvent(document, "b");
+            assert.strictEqual(mockCallback.calledCount, 1, "Sequence should not trigger on document");
+        });
+    });
+    describe("New Feature: keyup Event Support", () => {
+        it("should trigger combination on keyup when specified", () => {
+            keyManager.addCombination({ id: "keyupCombo", keys: "a", event: "keyup" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "a", "keydown");
+            assert.strictEqual(mockCallback.calledCount, 0, "Should not trigger on keydown");
+            dispatchKeyEvent(document, "a", "keyup");
+            assert.strictEqual(mockCallback.calledCount, 1, "Should trigger on keyup");
+        });
+        it("should trigger sequence on keyup when specified", () => {
+            keyManager.addSequence({ id: "keyupSeq", sequence: "a -> b", event: "keyup" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "a", "keydown");
+            dispatchKeyEvent(document, "b", "keydown");
+            assert.strictEqual(mockCallback.calledCount, 0, "Sequence should not trigger on keydown events");
+            dispatchKeyEvent(document, "a", "keyup");
+            dispatchKeyEvent(document, "b", "keyup");
+            assert.strictEqual(mockCallback.calledCount, 1, "Sequence should trigger on keyup events");
+        });
+        it("should default to keydown if event type is not specified", () => {
+            keyManager.addCombination({ id: "keydownDefault", keys: "c" }).subscribe(mockCallback);
+            dispatchKeyEvent(document, "c", "keyup");
+            assert.strictEqual(mockCallback.calledCount, 0);
+            dispatchKeyEvent(document, "c", "keydown");
+            assert.strictEqual(mockCallback.calledCount, 1);
+        });
+    });
     describe("Context Priority (Specific > Global)", () => {
         let globalCallback;
         let specificCallback;
@@ -452,31 +627,29 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             keyManager.addCombination({
                 id: "globalCtrlG",
                 keys: { key: Keys.G, ctrlKey: true },
-                callback: globalCallback,
                 context: null // Explicitly global
-            });
+            }).subscribe(globalCallback);
             // Specific context shortcut: Ctrl+G in "editor" context
             keyManager.addCombination({
                 id: "editorCtrlG",
                 keys: { key: Keys.G, ctrlKey: true },
-                callback: specificCallback,
                 context: "editor"
-            });
+            }).subscribe(specificCallback);
         });
         it("should only trigger specific context callback when specific context is active", () => {
             keyManager.setContext("editor");
-            dispatchKeyEvent(Keys.G, { ctrlKey: true });
+            dispatchKeyEvent(document, Keys.G, "keydown", { 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 });
+            dispatchKeyEvent(document, Keys.G, "keydown", { 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 });
+            dispatchKeyEvent(document, Keys.G, "keydown", { 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"`);
         });
@@ -491,31 +664,29 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             keyManager.addSequence({
                 id: "globalGI",
                 sequence: testSequence,
-                callback: globalSeqCallback,
                 context: null // Global
-            });
+            }).subscribe(globalSeqCallback);
             keyManager.addSequence({
                 id: "editorGI",
                 sequence: testSequence,
-                callback: specificSeqCallback,
                 context: "editor" // Specific
-            });
+            }).subscribe(specificSeqCallback);
         });
         it("should only trigger specific context sequence callback when specific context is active", () => {
             keyManager.setContext("editor");
-            testSequence.forEach(key => dispatchKeyEvent(key));
+            testSequence.forEach(key => dispatchKeyEvent(document, 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));
+            testSequence.forEach(key => dispatchKeyEvent(document, 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));
+            testSequence.forEach(key => dispatchKeyEvent(document, 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"`);
         });
@@ -532,47 +703,43 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             keyManager.addCombination({
                 id: "editorSave",
                 keys: { key: Keys.S, ctrlKey: true },
-                callback: specificContextCallback,
                 context: "editor"
-            });
+            }).subscribe(specificContextCallback);
             // 2. A "strictly global" shortcut, which only runs when context is null
             keyManager.addCombination({
                 id: "strictGlobalOpen",
-                keys: { key: Keys.O, ctrlKey: true }, // Using shorthand is now possible!
-                callback: strictGlobalCallback,
-                strict: true, // `strict` is at the top level
-            });
+                keys: { key: Keys.O, ctrlKey: true },
+                strict: true,
+            }).subscribe(strictGlobalCallback);
             // 3. A default global shortcut, which runs in any context unless overridden
             keyManager.addCombination({
                 id: "defaultGlobalSave",
                 keys: { key: Keys.S, ctrlKey: true },
-                callback: defaultGlobalCallback,
-                // No `strict` flag here
-            });
+            }).subscribe(defaultGlobalCallback);
         });
         it("should trigger both strict and default global shortcuts when context is null", () => {
             keyManager.setContext(null);
-            dispatchKeyEvent(Keys.O, { ctrlKey: true });
+            dispatchKeyEvent(document, Keys.O, "keydown", { ctrlKey: true });
             assert.strictEqual(strictGlobalCallback.calledCount, 1, "Strictly global (Ctrl+O) should fire");
-            dispatchKeyEvent(Keys.S, { ctrlKey: true });
+            dispatchKeyEvent(document, Keys.S, "keydown", { ctrlKey: true });
             assert.strictEqual(defaultGlobalCallback.calledCount, 1, "Default global (Ctrl+S) should fire");
             assert.strictEqual(specificContextCallback.calledCount, 0, "Specific context callback should not fire");
         });
         it("should suppress strict global but allow default global (which is then suppressed by priority)", () => {
             keyManager.setContext("editor");
-            dispatchKeyEvent(Keys.O, { ctrlKey: true });
-            assert.strictEqual(strictGlobalCallback.calledCount, 0, "Strictly global (Ctrl+O) should NOT fire in 'editor' context");
-            dispatchKeyEvent(Keys.S, { ctrlKey: true });
+            dispatchKeyEvent(document, Keys.O, "keydown", { ctrlKey: true });
+            assert.strictEqual(strictGlobalCallback.calledCount, 0, `Strictly global (Ctrl+O) should NOT fire in "editor" context`);
+            dispatchKeyEvent(document, Keys.S, "keydown", { ctrlKey: true });
             assert.strictEqual(defaultGlobalCallback.calledCount, 0, "Default global (Ctrl+S) should be suppressed by the specific one");
-            assert.strictEqual(specificContextCallback.calledCount, 1, "Specific 'editor' callback (Ctrl+S) should fire and take priority");
+            assert.strictEqual(specificContextCallback.calledCount, 1, `Specific "editor" callback (Ctrl+S) should fire and take priority`);
         });
         it("should suppress strict global but trigger default global in a non-conflicting context", () => {
             keyManager.setContext("someOtherContext");
-            dispatchKeyEvent(Keys.O, { ctrlKey: true });
-            assert.strictEqual(strictGlobalCallback.calledCount, 0, "Strictly global (Ctrl+O) should NOT fire in 'someOtherContext'");
-            dispatchKeyEvent(Keys.S, { ctrlKey: true });
+            dispatchKeyEvent(document, Keys.O, "keydown", { ctrlKey: true });
+            assert.strictEqual(strictGlobalCallback.calledCount, 0, `Strictly global (Ctrl+O) should NOT fire in "someOtherContext"`);
+            dispatchKeyEvent(document, Keys.S, "keydown", { ctrlKey: true });
             assert.strictEqual(defaultGlobalCallback.calledCount, 1, "Default global (Ctrl+S) should fire since no override exists for this context");
-            assert.strictEqual(specificContextCallback.calledCount, 0, "Specific 'editor' callback should not fire");
+            assert.strictEqual(specificContextCallback.calledCount, 0, `Specific "editor" callback should not fire`);
         });
     });
     describe("Sequence Context Behavior (`strict` flag)", () => {
@@ -585,116 +752,107 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             strictSeqCallback = createMockFn();
             defaultSeqCallback = createMockFn();
             specificSeqCallback = createMockFn();
-            keyManager.addSequence({ id: "strictSeq", sequence: [Keys.G, Keys.O], callback: strictSeqCallback, strict: true });
-            keyManager.addSequence({ id: "defaultSeq", sequence: testSequence, callback: defaultSeqCallback });
-            keyManager.addSequence({ id: "specificSeq", sequence: testSequence, callback: specificSeqCallback, context: "editor" });
+            keyManager.addSequence({ id: "strictSeq", sequence: [Keys.G, Keys.O], strict: true }).subscribe(strictSeqCallback);
+            keyManager.addSequence({ id: "defaultSeq", sequence: testSequence }).subscribe(defaultSeqCallback);
+            keyManager.addSequence({ id: "specificSeq", sequence: testSequence, context: "editor" }).subscribe(specificSeqCallback);
         });
         it("should trigger both strict and default global sequences when context is null", () => {
             keyManager.setContext(null);
-            [Keys.G, Keys.O].forEach(key => dispatchKeyEvent(key));
+            [Keys.G, Keys.O].forEach(key => dispatchKeyEvent(document, key));
             assert.strictEqual(strictSeqCallback.calledCount, 1, "Strict sequence should fire");
-            testSequence.forEach(key => dispatchKeyEvent(key));
+            testSequence.forEach(key => dispatchKeyEvent(document, key));
             assert.strictEqual(defaultSeqCallback.calledCount, 1, "Default sequence should fire");
             assert.strictEqual(specificSeqCallback.calledCount, 0, "Specific sequence should not fire");
         });
         it("should suppress strict sequence and prioritize specific sequence in a matching context", () => {
             keyManager.setContext("editor");
-            [Keys.G, Keys.O].forEach(key => dispatchKeyEvent(key));
-            assert.strictEqual(strictSeqCallback.calledCount, 0, "Strict sequence should NOT fire in 'editor' context");
-            testSequence.forEach(key => dispatchKeyEvent(key));
+            [Keys.G, Keys.O].forEach(key => dispatchKeyEvent(document, key));
+            assert.strictEqual(strictSeqCallback.calledCount, 0, `Strict sequence should NOT fire in "editor" context`);
+            testSequence.forEach(key => dispatchKeyEvent(document, key));
             assert.strictEqual(defaultSeqCallback.calledCount, 0, "Default global sequence should be suppressed");
-            assert.strictEqual(specificSeqCallback.calledCount, 1, "Specific 'editor' sequence should fire");
+            assert.strictEqual(specificSeqCallback.calledCount, 1, `Specific "editor" sequence should fire`);
         });
         it("should suppress strict sequence but trigger default global sequence in a non-conflicting context", () => {
             keyManager.setContext("someOtherContext");
-            [Keys.G, Keys.O].forEach(key => dispatchKeyEvent(key));
+            [Keys.G, Keys.O].forEach(key => dispatchKeyEvent(document, key));
             assert.strictEqual(strictSeqCallback.calledCount, 0, "Strict sequence should NOT fire");
-            testSequence.forEach(key => dispatchKeyEvent(key));
+            testSequence.forEach(key => dispatchKeyEvent(document, key));
             assert.strictEqual(defaultSeqCallback.calledCount, 1, "Default global sequence should fire");
-            assert.strictEqual(specificSeqCallback.calledCount, 0, "Specific 'editor' sequence should not fire");
+            assert.strictEqual(specificSeqCallback.calledCount, 0, `Specific "editor" sequence should not fire`);
         });
     });
     describe("addSequence", () => {
-        it("should trigger callback for a simple key sequence", () => {
-            const config = { id: "seqGI", sequence: [Keys.G, Keys.I], callback: mockCallback };
-            const result = keyManager.addSequence(config);
-            assert.strictEqual(result, "seqGI");
-            dispatchKeyEvent("g"); // Dispatch "g" (lowercase)
-            dispatchKeyEvent("i"); // Dispatch "i" (lowercase)
+        it("should return an Observable that emits on a simple key sequence", () => {
+            const config = { id: "seqGI", sequence: [Keys.G, Keys.I] };
+            const seq$ = keyManager.addSequence(config);
+            assert(seq$ instanceof Observable, "Did not return an Observable");
+            seq$.subscribe(mockCallback);
+            dispatchKeyEvent(document, "g");
+            dispatchKeyEvent(document, "i");
             assert.strictEqual(mockCallback.calledCount, 1);
         });
-        it("should trigger callback for Konami code using Keys", () => {
+        it("should emit on Konami code using Keys", () => {
             const konamiSequence = [
                 Keys.ArrowUp, Keys.ArrowUp, Keys.ArrowDown, Keys.ArrowDown,
                 Keys.ArrowLeft, Keys.ArrowRight, Keys.ArrowLeft, Keys.ArrowRight,
-                Keys.B, Keys.A // Using "B" and "A" from Keys
+                Keys.B, Keys.A
             ];
-            const config = { id: "konami", sequence: konamiSequence, callback: mockCallback };
-            keyManager.addSequence(config);
-            // Dispatch events using the string values that browser events would produce
-            ["ArrowUp", "ArrowUp", "ArrowDown", "ArrowDown", "ArrowLeft", "ArrowRight", "ArrowLeft", "ArrowRight", "b", "a"].forEach(key => dispatchKeyEvent(key));
+            const config = { id: "konami", sequence: konamiSequence };
+            keyManager.addSequence(config).subscribe(mockCallback);
+            ["ArrowUp", "ArrowUp", "ArrowDown", "ArrowDown", "ArrowLeft", "ArrowRight", "ArrowLeft", "ArrowRight", "b", "a"].forEach(key => dispatchKeyEvent(document, key));
             assert.strictEqual(mockCallback.calledCount, 1, "Konami sequence callback not triggered");
         });
-        it("should return undefined and warn if sequence is empty", () => {
-            const config = { id: "emptySeq", sequence: [], callback: mockCallback };
-            const result = keyManager.addSequence(config);
-            assert.strictEqual(result, undefined);
+        it("should return an empty observable and warn if sequence is empty", () => {
+            const config = { id: "emptySeq", sequence: [] };
+            const seq$ = keyManager.addSequence(config);
+            seq$.subscribe(mockCallback);
             assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
             assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Sequence for shortcut "emptySeq" is empty`));
+            dispatchKeyEvent(document, "a");
+            assert.strictEqual(mockCallback.calledCount, 0);
         });
-        it(`should return undefined and warn if sequence contains an invalid key (runtime check with "as any")`, () => {
-            // This test checks runtime robustness if `any` is used to bypass StandardKey[]
-            const config = { id: "invalidKeyInSeq", sequence: [Keys.A, "", Keys.C], callback: mockCallback };
-            const result = keyManager.addSequence(config);
-            assert.strictEqual(result, undefined, "addSequence should return undefined for sequence with empty string");
+        it(`should return an empty observable and warn if sequence contains an invalid key`, () => {
+            const config = { id: "invalidKeyInSeq", sequence: [Keys.A, "", Keys.C] };
+            const seq$ = keyManager.addSequence(config);
+            seq$.subscribe(mockCallback);
             assert.strictEqual(consoleWarnMock.mock.calls.length, 1, "console.warn was not called for invalid key in sequence");
             assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid key in sequence for shortcut "invalidKeyInSeq"`));
         });
-        it("should pass the last KeyboardEvent of the sequence to the callback", () => {
-            const config = { id: "seqEventPass", sequence: [Keys.X, Keys.Y], callback: mockCallback };
-            keyManager.addSequence(config);
-            dispatchKeyEvent("x");
-            const lastEvent = dispatchKeyEvent("y");
+        it("should pass the last KeyboardEvent of the sequence to the subscriber", () => {
+            const config = { id: "seqEventPass", sequence: [Keys.X, Keys.Y] };
+            keyManager.addSequence(config).subscribe(mockCallback);
+            dispatchKeyEvent(document, "x");
+            const lastEvent = dispatchKeyEvent(document, "y");
             assert.strictEqual(mockCallback.calledCount, 1);
             assert.deepStrictEqual(mockCallback.lastArgs, [lastEvent]);
         });
         it("should prevent default for the last key event in the sequence when preventDefault is true", () => {
-            const config = { id: "seqPrevent", sequence: [Keys.M, Keys.N], callback: mockCallback, preventDefault: true };
-            keyManager.addSequence(config);
-            dispatchKeyEvent("m");
-            const eventN = dispatchKeyEvent("n");
+            const config = { id: "seqPrevent", sequence: [Keys.M, Keys.N], preventDefault: true };
+            keyManager.addSequence(config).subscribe(mockCallback);
+            dispatchKeyEvent(document, "m");
+            const eventN = dispatchKeyEvent(document, "n");
             assert.strictEqual(mockCallback.calledCount, 1);
             assert.strictEqual(eventN.defaultPrevented, true);
         });
-        it("should log an error via console.error if sequence callback throws", () => {
-            const errorCallback = () => { throw new Error("Test sequence callback error"); };
-            keyManager.addSequence({ id: "errorSeq", sequence: [Keys.E, Keys.S], callback: errorCallback });
-            dispatchKeyEvent("e");
-            dispatchKeyEvent("s");
-            assert.strictEqual(consoleErrorMock.mock.calls.length, 1);
-            assert.ok(consoleErrorMock.mock.calls[0].arguments[0].includes(`Error in user callback for sequence shortcut "errorSeq"`));
-        });
-        it("should trigger callback for a sequence including Keys.Space", () => {
+        it("should emit for a sequence including Keys.Space", () => {
             const config = {
                 id: "seqWithSpace",
                 sequence: [Keys.G, Keys.Space, Keys.I],
-                callback: mockCallback
             };
-            keyManager.addSequence(config);
-            dispatchKeyEvent(Keys.G);
-            dispatchKeyEvent(Keys.Space); // Dispatch " " for space
-            dispatchKeyEvent(Keys.I);
+            keyManager.addSequence(config).subscribe(mockCallback);
+            dispatchKeyEvent(document, Keys.G);
+            dispatchKeyEvent(document, Keys.Space); // Dispatch " " for space
+            dispatchKeyEvent(document, Keys.I);
             assert.strictEqual(mockCallback.calledCount, 1, "Callback for sequence with Keys.Space not called");
         });
-        it("should trigger callback for a sequence starting or ending with Keys.Space", () => {
+        it("should emit for a sequence starting or ending with Keys.Space", () => {
             const config = {
                 id: "seqStartSpace",
                 sequence: [Keys.Space, Keys.A],
-                callback: mockCallback
             };
-            keyManager.addSequence(config);
-            dispatchKeyEvent(Keys.Space);
-            dispatchKeyEvent(Keys.A);
+            keyManager.addSequence(config).subscribe(mockCallback);
+            dispatchKeyEvent(document, Keys.Space);
+            dispatchKeyEvent(document, Keys.A);
             assert.strictEqual(mockCallback.calledCount, 1, "Callback for sequence starting with Keys.Space not called");
         });
         describe("Sequence Contextual Triggering", () => {
@@ -703,14 +861,13 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
                 editorSequenceConfig = {
                     id: "sequenceInEditor",
                     sequence: [Keys.C, Keys.O, Keys.D, Keys.E],
-                    callback: mockCallback,
                     context: "editor",
                 };
             });
-            it("should trigger sequence in matching context", () => {
-                keyManager.addSequence(editorSequenceConfig);
+            it("should emit sequence in matching context", () => {
+                keyManager.addSequence(editorSequenceConfig).subscribe(mockCallback);
                 keyManager.setContext("editor");
-                [Keys.C, Keys.O, Keys.D, Keys.E].forEach(k => dispatchKeyEvent(k));
+                [Keys.C, Keys.O, Keys.D, Keys.E].forEach(k => dispatchKeyEvent(document, k));
                 assert.strictEqual(mockCallback.calledCount, 1);
             });
         });
@@ -737,48 +894,54 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
                 }
                 mock.timers.reset();
             });
-            it("should trigger sequence if keys are pressed within specified timeout", () => {
-                const config = { id: "seqTimeoutOk", sequence: [Keys.T, Keys.O, Keys.K], callback: mockCallback, sequenceTimeoutMs: TIMEOUT_MS };
-                keyManager.addSequence(config);
-                dispatchKeyEvent(Keys.T);
+            it("should emit if keys are pressed within specified timeout", () => {
+                const config = { id: "seqTimeoutOk", sequence: [Keys.T, Keys.O, Keys.K], sequenceTimeoutMs: TIMEOUT_MS };
+                keyManager.addSequence(config).subscribe(mockCallback);
+                dispatchKeyEvent(document, Keys.T);
                 mock.timers.tick(TIMEOUT_MS / 2);
-                dispatchKeyEvent(Keys.O);
+                dispatchKeyEvent(document, Keys.O);
                 mock.timers.tick(TIMEOUT_MS / 2);
-                const lastEvent = dispatchKeyEvent(Keys.K);
+                const lastEvent = dispatchKeyEvent(document, Keys.K);
                 assert.strictEqual(mockCallback.calledCount, 1);
                 assert.deepStrictEqual(mockCallback.lastArgs, [lastEvent]);
             });
-            it("should NOT trigger sequence if a key press is delayed beyond timeout", () => {
-                const config = { id: "seqTimeoutFail", sequence: [Keys.D, Keys.E, Keys.L], callback: mockCallback, sequenceTimeoutMs: TIMEOUT_MS };
-                keyManager.addSequence(config);
-                dispatchKeyEvent(Keys.D);
+            it("should NOT emit if a key press is delayed beyond timeout", () => {
+                const config = { id: "seqTimeoutFail", sequence: [Keys.D, Keys.E, Keys.L], sequenceTimeoutMs: TIMEOUT_MS };
+                keyManager.addSequence(config).subscribe(mockCallback);
+                dispatchKeyEvent(document, Keys.D);
                 mock.timers.tick(TIMEOUT_MS / 2);
-                dispatchKeyEvent(Keys.E);
+                dispatchKeyEvent(document, Keys.E);
                 mock.timers.tick(TIMEOUT_MS + 1);
-                dispatchKeyEvent(Keys.L);
+                dispatchKeyEvent(document, Keys.L);
                 assert.strictEqual(mockCallback.calledCount, 0);
             });
         });
     });
     describe("remove", () => {
-        it("should remove a combination shortcut", () => {
-            keyManager.addCombination({ id: "remA", keys: { key: Keys.A }, callback: mockCallback });
+        it("should remove a combination shortcut and complete its observable", () => {
+            const completeCallback = createMockFn();
+            const combo$ = keyManager.addCombination({ id: "remA", keys: { key: Keys.A } });
+            combo$.subscribe({ next: mockCallback, complete: completeCallback });
             assert.strictEqual(keyManager.remove("remA"), true);
-            dispatchKeyEvent(Keys.A);
+            assert.strictEqual(completeCallback.calledCount, 1, "Observable should have completed");
+            dispatchKeyEvent(document, Keys.A);
             assert.strictEqual(mockCallback.calledCount, 0);
         });
-        it("should remove a sequence shortcut", () => {
-            keyManager.addSequence({ id: "remSeq", sequence: [Keys.A, Keys.B], callback: mockCallback });
+        it("should remove a sequence shortcut and complete its observable", () => {
+            const completeCallback = createMockFn();
+            const seq$ = keyManager.addSequence({ id: "remSeq", sequence: [Keys.A, Keys.B] });
+            seq$.subscribe({ next: mockCallback, complete: completeCallback });
             assert.strictEqual(keyManager.remove("remSeq"), true);
-            dispatchKeyEvent(Keys.A);
-            dispatchKeyEvent(Keys.B);
+            assert.strictEqual(completeCallback.calledCount, 1, "Observable should have completed");
+            dispatchKeyEvent(document, Keys.A);
+            dispatchKeyEvent(document, Keys.B);
             assert.strictEqual(mockCallback.calledCount, 0);
         });
     });
     describe("getActiveShortcuts", () => {
         it("should return active combination and sequence shortcuts with enum types", () => {
-            keyManager.addCombination({ id: "combo1", keys: { key: Keys.A }, callback: createMockFn(), description: "Test A" });
-            keyManager.addSequence({ id: "seq1", sequence: [Keys.B, Keys.C], callback: createMockFn(), context: "modal", description: "Test BC" });
+            keyManager.addCombination({ id: "combo1", keys: { key: Keys.A }, description: "Test A" });
+            keyManager.addSequence({ id: "seq1", sequence: [Keys.B, Keys.C], context: "modal", description: "Test BC" });
             const active = keyManager.getActiveShortcuts();
             assert.strictEqual(active.length, 2);
             const combo = active.find(s => s.id === "combo1");
@@ -791,29 +954,30 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
     });
     describe("hasShortcut", () => {
         it("should return true for an existing combination shortcut", () => {
-            keyManager.addCombination({ id: "existsCombo", keys: { key: Keys.E }, callback: mockCallback });
+            keyManager.addCombination({ id: "existsCombo", keys: { key: Keys.E } });
             assert.strictEqual(keyManager.hasShortcut("existsCombo"), true);
         });
         it("should return false for a shortcut that failed to add (e.g. invalid key object)", () => {
-            // This test now relies on the runtime check for !keys.key, as TS would catch `key: null` directly.
-            const config = { id: "invalidKeyCombo", keys: { key: null }, callback: mockCallback };
+            const config = { id: "invalidKeyCombo", keys: { key: null } };
             keyManager.addCombination(config);
             assert.strictEqual(keyManager.hasShortcut("invalidKeyCombo"), false);
         });
     });
     describe("destroy", () => {
-        it("should clear active shortcuts and prevent further triggers", () => {
-            keyManager.addCombination({ id: "destroyTestCombo", keys: { key: Keys.D }, callback: mockCallback });
-            keyManager.addSequence({ id: "destroyTestSeq", sequence: [Keys.X, Keys.Y], callback: mockCallback });
+        it("should clear active shortcuts and complete all observables", () => {
+            const comboComplete = createMockFn();
+            const seqComplete = createMockFn();
+            const combo$ = keyManager.addCombination({ id: "destroyTestCombo", keys: { key: Keys.D } });
+            combo$.subscribe({ complete: comboComplete });
+            const seq$ = keyManager.addSequence({ id: "destroyTestSeq", sequence: [Keys.X, Keys.Y] });
+            seq$.subscribe({ complete: seqComplete });
             // @ts-ignore
             assert.strictEqual(keyManager["activeShortcuts"].size, 2);
             keyManager.destroy();
             // @ts-ignore
             assert.strictEqual(keyManager["activeShortcuts"].size, 0);
-            dispatchKeyEvent(Keys.D);
-            dispatchKeyEvent(Keys.X);
-            dispatchKeyEvent(Keys.Y);
-            assert.strictEqual(mockCallback.calledCount, 0);
+            assert.strictEqual(comboComplete.calledCount, 1, "Combination observable should have completed");
+            assert.strictEqual(seqComplete.calledCount, 1, "Sequence observable should have completed");
         });
     });
 });