node-native-win-utils 2.1.5 → 2.2.2

package/binding.gyp

@@ -17,6 +17,7 @@
             "libraries": [
                 "dwmapi.lib",
                 "windowsapp.lib",
+                "Shcore.lib",
                 "-lgdi32", 
                 "-lgdiplus",
                 "<!(node -p \"require('path').resolve('libs/libjpeg-turbo.lib')\")",

package/dist/index.d.mts

@@ -75,6 +75,16 @@ export type Color = [r: number, g: number, b: number];
 export type ROI = [x: number, y: number, width: number, height: number];
 export type Imread = (path: string) => ImageData;
 export type Imwrite = (image: ImageData) => Buffer;
+export type StartMouseListener = (callback: (data: {
+    x: number;
+    y: number;
+    type: string;
+}) => void) => void;
+export type StopMouseListener = () => {
+    success: boolean;
+    error?: string;
+    errorCode?: number;
+};
 export type MatchTemplate = (image: ImageData, template: ImageData, method?: number | null, mask?: ImageData) => MatchData;
 export type Blur = (image: ImageData, sizeX: number, sizeY: number) => ImageData;
 export type BgrToGray = (image: ImageData) => ImageData;
@@ -85,7 +95,8 @@ export type DrawRectangle = (image: ImageData, start: Point, end: Point, rgb: Co
 export type GetRegion = (image: ImageData, region: ROI) => ImageData;
 export type TextRecognition = (trainedDataPath: string, dataLang: string, imagePath: string) => string;
 export type CaptureScreenAsync = () => Promise<Buffer>;
-declare const getWindowData: GetWindowData, captureWindowN: CaptureWindow, captureScreenAsync: CaptureScreenAsync, mouseMove: MouseMove, mouseClick: MouseClick, mouseDrag: MouseDrag, typeString: TypeString, textRecognition: TextRecognition;
+export type BringWindowToFront = (windowName: string) => boolean;
+declare const getWindowData: GetWindowData, captureWindowN: CaptureWindow, captureScreenAsync: CaptureScreenAsync, mouseMove: MouseMove, mouseClick: MouseClick, mouseDrag: MouseDrag, typeString: TypeString, textRecognition: TextRecognition, bringWindowToFront: BringWindowToFront, startMouseListener: StartMouseListener, stopMouseListener: StopMouseListener;
 declare const rawPressKey: PressKey;
 /**
  * Captures a window and saves it to a file.
@@ -252,7 +263,7 @@ declare class OpenCV {
       * @returns A new OpenCV instance with the equalized image data.
       */
     equalizeHist(): OpenCV;
-    rgbToHsv(rgb: ColorBound): number[];
+    rgbToHsv(rgb: ColorBound): number[][];
     darkenColor(lowerBound: ColorBound, upperBound: ColorBound, darkenFactor: number): OpenCV;
     /**
      * Draws a rectangle on the image.
@@ -276,4 +287,4 @@ declare class OpenCV {
     imwrite(path: string): void;
 }
 declare function keyPress(keyCode: number, repeat?: number): Promise<boolean>;
-export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, captureScreenAsync, KeyboardListener, OpenCV };
+export { getWindowData, bringWindowToFront, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, captureScreenAsync, startMouseListener, stopMouseListener, KeyboardListener, OpenCV };

package/dist/index.mjs

@@ -8,7 +8,7 @@ const nodeGypBuild = __require("node-gyp-build");
 import { keyCodes, KeyCodeHelper } from "./keyCodes.mjs";
 import { __dirnameLocal } from "./dirnameLocal.mjs";
 const bindings = nodeGypBuild(path.resolve(__dirnameLocal, ".."));
-const { setKeyDownCallback, setKeyUpCallback, unsetKeyDownCallback, unsetKeyUpCallback, getWindowData, captureWindowN, captureScreenAsync, mouseMove, mouseClick, mouseDrag, typeString, pressKey, imread, imwrite, matchTemplate, blur, bgrToGray, drawRectangle, getRegion, textRecognition, equalizeHist, darkenColor } = bindings;
+const { setKeyDownCallback, setKeyUpCallback, unsetKeyDownCallback, unsetKeyUpCallback, getWindowData, captureWindowN, captureScreenAsync, mouseMove, mouseClick, mouseDrag, typeString, pressKey, imread, imwrite, matchTemplate, blur, bgrToGray, drawRectangle, getRegion, textRecognition, equalizeHist, darkenColor, bringWindowToFront, startMouseListener, stopMouseListener } = bindings;
 const rawPressKey = pressKey;
 /**
  * Captures a window and saves it to a file.
@@ -209,11 +209,8 @@ class OpenCV {
         if (Cmax !== 0)
             Saturation = (delta / Cmax) * 100;
         let Value = Cmax * 100;
-        // 🛠 Convert to OpenCV format
         return [
-            Math.round((Hue / 360) * 179), // Scale H from [0, 360] → [0, 179]
-            Math.round((Saturation / 100) * 255), // Scale S from [0, 100] → [0, 255]
-            Math.round((Value / 100) * 255) // Scale V from [0, 100] → [0, 255]
+            [Hue, Saturation, Value]
         ];
     }
     darkenColor(lowerBound, upperBound, darkenFactor) {
@@ -265,4 +262,4 @@ function keyPress(keyCode, repeat) {
         return resolve(true);
     });
 }
-export { getWindowData, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, captureScreenAsync, KeyboardListener, OpenCV };
+export { getWindowData, bringWindowToFront, captureWindow, captureWindowN, mouseMove, mouseClick, mouseDrag, typeString, keyPress, rawPressKey, KeyCodeHelper, textRecognition, captureScreenToFile, captureScreenAsync, startMouseListener, stopMouseListener, KeyboardListener, OpenCV };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-native-win-utils",
-  "version": "2.1.5",
+  "version": "2.2.2",
   "author": "Andrew K.",
   "license": "MIT",
   "repository": "https://github.com/T-Rumibul/node-native-win-utils.git",
@@ -40,21 +40,16 @@
     "install": "node-gyp-build",
     "build": "node-gyp clean && npx prebuildify --napi && node ./buildHelpers/dllCopy.js && npm run buildts",
     "buildts": "node ./buildHelpers/cjsCompatBuild.js",
-    "test": "tap run "
+    "test": "tap run"
   },
   "dependencies": {
-    "node-addon-api": "^8.3.1",
-    "node-gyp": "^11.1.0",
+    "node-addon-api": "^8.6.0",
+    "node-gyp": "^12.2.0",
     "node-gyp-build": "^4.8.4"
   },
   "devDependencies": {
-    "@types/node": "^20.2.5",
-    "node-api-headers": "^1.5.0",
-    "tap": "^21.1.0"
-  },
-  "tap": {
-    "plugin": [
-      "@tapjs/sinon"
-    ]
+    "@types/node": "^25.3.5",
+    "node-api-headers": "^1.8.0",
+    "tap": "^21.6.2"
   }
 }

package/src/cpp/getWindowData.cpp

@@ -42,5 +42,78 @@ Napi::Value GetWindowData(const Napi::CallbackInfo &info)
     result.Set("x", Napi::Number::New(env, x));
     result.Set("y", Napi::Number::New(env, y));
 
+    return result;
+}
+
+Napi::Value BringWindowToFront(const Napi::CallbackInfo &info)
+{   
+    Napi::Env env = info.Env();
+    Napi::Object result = Napi::Object::New(env);
+
+    auto returnError = [&](const std::string& message, DWORD errorCode = 0) {
+        result.Set("success", false);
+        result.Set("error", message);
+        if (errorCode != 0) {
+            result.Set("errorCode", Napi::Number::New(env, errorCode));
+        }
+        return result;
+    };
+
+    if (info.Length() < 1 || !info[0].IsString())
+    {
+        return returnError("Window name must be provided as a string");
+    }
+
+    std::string windowName = info[0].As<Napi::String>().Utf8Value();
+
+    HWND hWnd = GetWindowByName(windowName.c_str());
+    if (!hWnd || !IsWindow(hWnd))
+    {
+        return returnError("Window not found or invalid: " + windowName);
+    }
+
+    // Restore if minimized
+    if (IsIconic(hWnd))
+    {
+        ShowWindow(hWnd, SW_RESTORE);
+        // Give the window a moment to restore before trying to focus it
+        Sleep(50);
+    }
+
+    HWND fg = GetForegroundWindow();
+
+    // Bug fix 1: must attach the TARGET window's thread, not just the foreground
+    // window's thread. We need a triangle: cur <-> fg thread <-> target thread.
+    DWORD fgThread  = fg ? GetWindowThreadProcessId(fg, nullptr) : 0;
+    DWORD tgtThread = GetWindowThreadProcessId(hWnd, nullptr);
+    DWORD curThread = GetCurrentThreadId();
+
+    // Bug fix 2: attach all relevant thread pairs so input state is fully shared
+    bool attachedFg  = (fgThread  && fgThread  != curThread) ? AttachThreadInput(curThread, fgThread,  TRUE) != 0 : false;
+    bool attachedTgt = (tgtThread && tgtThread != curThread) ? AttachThreadInput(curThread, tgtThread, TRUE) != 0 : false;
+
+    // Bug fix 3: use AllowSetForegroundWindow to explicitly grant permission,
+    // which bypasses Windows' focus-stealing prevention for cross-process calls
+    AllowSetForegroundWindow(ASFW_ANY);
+
+    // Bring the window to front using the full sequence
+    SetForegroundWindow(hWnd);
+    SetActiveWindow(hWnd);
+    BringWindowToTop(hWnd);
+    // Bug fix 4: SetFocus only works reliably once input queues are attached
+    SetFocus(hWnd);
+
+    // Always detach — don't leave threads attached on any code path
+    if (attachedFg)  AttachThreadInput(curThread, fgThread,  FALSE);
+    if (attachedTgt) AttachThreadInput(curThread, tgtThread, FALSE);
+
+    // Verify it actually worked
+    HWND newFg = GetForegroundWindow();
+    if (newFg != hWnd)
+    {
+        return returnError("Window did not come to foreground (focus-stealing prevention may be active)");
+    }
+
+    result.Set("success", true);
     return result;
 }

package/src/cpp/main.cpp

@@ -6,9 +6,10 @@
 #include <mouse.cpp>
 #include <opencv.cpp>
 #include <tesseract.cpp>
-
+#include <ShellScalingApi.h>
 Napi::Object Init(Napi::Env env, Napi::Object exports)
 {
+    SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE);
     exports.Set("getWindowData", Napi::Function::New(env, GetWindowData));
     exports.Set("captureWindowN", Napi::Function::New(env, CaptureWindow));
     exports.Set("captureScreenAsync", Napi::Function::New(env, CaptureScreenAsync));
@@ -31,6 +32,9 @@ Napi::Object Init(Napi::Env env, Napi::Object exports)
     exports.Set("drawRectangle", Napi::Function::New(env, DrawRectangle));
     exports.Set("getRegion", Napi::Function::New(env, GetRegion));
     exports.Set("textRecognition", Napi::Function::New(env, TextRecognition));
+    exports.Set("bringWindowToFront", Napi::Function::New(env, BringWindowToFront));
+    exports.Set("startMouseListener", Napi::Function::New(env, StartMouseListener));
+    exports.Set("stopMouseListener", Napi::Function::New(env, StopMouseListener));
     static GdiPlusInitializer gdiplusInitializer;
      // Register cleanup hook
     env.AddCleanupHook(CleanupHook);

package/src/cpp/mouse.cpp

@@ -1,6 +1,36 @@
 // patrially used code from https://github.com/octalmage/robotjs witch is under MIT License Copyright (c) 2014 Jason Stallings
 #include <napi.h>
 #include <windows.h>
+#include <atomic>
+#include <cmath>
+
+HHOOK mouseHook;
+Napi::ThreadSafeFunction tsfn;
+static HANDLE hHookThread = NULL;
+static DWORD hookThreadId = 0;
+static std::atomic_flag listenerRunning = ATOMIC_FLAG_INIT;
+static std::atomic<bool> listenerStopping = false;
+static HANDLE hHookReady = NULL;
+
+struct Position
+{
+    int x;
+    int y;
+};
+
+Position calcAbsolutePosition(int x, int y)
+{
+    int vLeft = GetSystemMetrics(SM_XVIRTUALSCREEN);
+    int vTop = GetSystemMetrics(SM_YVIRTUALSCREEN);
+    int vWidth = GetSystemMetrics(SM_CXVIRTUALSCREEN);
+    int vHeight = GetSystemMetrics(SM_CYVIRTUALSCREEN);
+    if (vWidth <= 1 || vHeight <= 1)
+        return {0, 0}; // No virtual screen
+    int absoluteX = static_cast<int>((static_cast<long long>(x - vLeft) * 65535) / (vWidth - 1));
+    int absoluteY = static_cast<int>((static_cast<long long>(y - vTop) * 65535) / (vHeight - 1));
+    return {absoluteX, absoluteY};
+}
+
 /**
  * Move the mouse to a specific point.
  * @param point The coordinates to move the mouse to (x, y).
@@ -19,13 +49,9 @@ Napi::Value MoveMouse(const Napi::CallbackInfo &info)
     int posX = info[0].As<Napi::Number>();
     int posY = info[1].As<Napi::Number>();
 
-    // Get the screen metrics
-    int screenWidth = GetSystemMetrics(SM_CXSCREEN);
-    int screenHeight = GetSystemMetrics(SM_CYSCREEN);
-
-    // Convert coordinates to absolute values
-    int absoluteX = static_cast<int>((65536 * posX) / screenWidth);
-    int absoluteY = static_cast<int>((65536 * posY) / screenHeight);
+    Position pos = calcAbsolutePosition(posX, posY);
+    int absoluteX = pos.x;
+    int absoluteY = pos.y;
 
     // Move the mouse
     INPUT mouseInput = {0};
@@ -34,9 +60,9 @@ Napi::Value MoveMouse(const Napi::CallbackInfo &info)
     mouseInput.mi.dy = absoluteY;
     mouseInput.mi.dwFlags = MOUSEEVENTF_ABSOLUTE | MOUSEEVENTF_MOVE | MOUSEEVENTF_VIRTUALDESK;
     mouseInput.mi.time = 0; // System will provide the timestamp
-
-    SendInput(1, &mouseInput, sizeof(mouseInput));
-
+    UINT sent = SendInput(1, &mouseInput, sizeof(INPUT));
+    if (sent == 0)
+        return Napi::Boolean::New(env, false);
     return Napi::Boolean::New(env, true);
 }
 
@@ -50,19 +76,22 @@ Napi::Value ClickMouse(const Napi::CallbackInfo &info)
     else
         button = info[0].As<Napi::String>();
 
-    WORD mouseEvent = 0;
+    WORD downFlag = 0, upFlag = 0;
 
     if (button == "left")
     {
-        mouseEvent = MOUSEEVENTF_LEFTDOWN | MOUSEEVENTF_LEFTUP;
+        downFlag = MOUSEEVENTF_LEFTDOWN;
+        upFlag = MOUSEEVENTF_LEFTUP;
     }
     else if (button == "right")
     {
-        mouseEvent = MOUSEEVENTF_RIGHTDOWN | MOUSEEVENTF_RIGHTUP;
+        downFlag = MOUSEEVENTF_RIGHTDOWN;
+        upFlag = MOUSEEVENTF_RIGHTUP;
     }
     else if (button == "middle")
     {
-        mouseEvent = MOUSEEVENTF_MIDDLEDOWN | MOUSEEVENTF_MIDDLEUP;
+        downFlag = MOUSEEVENTF_MIDDLEDOWN;
+        upFlag = MOUSEEVENTF_MIDDLEUP;
     }
     else
     {
@@ -71,13 +100,15 @@ Napi::Value ClickMouse(const Napi::CallbackInfo &info)
     }
 
     // Perform the mouse click
-    INPUT mouseInput = {0};
-    mouseInput.type = INPUT_MOUSE;
-    mouseInput.mi.dwFlags = mouseEvent;
-    mouseInput.mi.time = 0; // System will provide the timestamp
-
-    SendInput(1, &mouseInput, sizeof(mouseInput));
-
+    INPUT inputs[2] = {};
+    inputs[0].type = INPUT_MOUSE;
+    inputs[0].mi.dwFlags = downFlag;
+    inputs[1].type = INPUT_MOUSE;
+    inputs[1].mi.dwFlags = upFlag;
+
+    UINT sent = SendInput(2, inputs, sizeof(INPUT));
+    if (sent == 0)
+        return Napi::Boolean::New(env, false);
     return Napi::Boolean::New(env, true);
 }
 
@@ -90,7 +121,7 @@ Napi::Value DragMouse(const Napi::CallbackInfo &info)
         Napi::TypeError::New(env, "You should provide startX, startY, endX, endY").ThrowAsJavaScriptException();
         return env.Null();
     }
-
+    bool success = true;
     int startX = info[0].As<Napi::Number>();
     int startY = info[1].As<Napi::Number>();
     int endX = info[2].As<Napi::Number>();
@@ -100,23 +131,26 @@ Napi::Value DragMouse(const Napi::CallbackInfo &info)
     {
         speed = info[4].As<Napi::Number>();
     }
-
+    // Use pixel coords for timing
+    double pixelDistX = endX - startX;
+    double pixelDistY = endY - startY;
+    double pixelDistance = sqrt(pixelDistX * pixelDistX + pixelDistY * pixelDistY);
+    if (speed <= 0)
+        speed = 1; // guard div/0
+    double duration = pixelDistance / speed;
     // Get the screen metrics
-    int screenWidth = GetSystemMetrics(SM_CXSCREEN);
-    int screenHeight = GetSystemMetrics(SM_CYSCREEN);
 
+    Position startPos = calcAbsolutePosition(startX, startY);
+    Position endPos = calcAbsolutePosition(endX, endY);
     // Convert coordinates to absolute values
-    int absoluteStartX = static_cast<int>((65536 * startX) / screenWidth);
-    int absoluteStartY = static_cast<int>((65536 * startY) / screenHeight);
-    int absoluteEndX = static_cast<int>((65536 * endX) / screenWidth);
-    int absoluteEndY = static_cast<int>((65536 * endY) / screenHeight);
+    int absoluteStartX = startPos.x;
+    int absoluteStartY = startPos.y;
+    int absoluteEndX = endPos.x;
+    int absoluteEndY = endPos.y;
 
     // Calculate the distance and duration based on speed
     double distanceX = absoluteEndX - absoluteStartX;
     double distanceY = absoluteEndY - absoluteStartY;
-    double distance = sqrt(distanceX * distanceX + distanceY * distanceY);
-    double duration = distance / speed;
-
     // Move the mouse to the starting position
     INPUT startMouseInput = {0};
     startMouseInput.type = INPUT_MOUSE;
@@ -125,7 +159,9 @@ Napi::Value DragMouse(const Napi::CallbackInfo &info)
     startMouseInput.mi.dwFlags = MOUSEEVENTF_ABSOLUTE | MOUSEEVENTF_MOVE | MOUSEEVENTF_VIRTUALDESK;
     startMouseInput.mi.time = 0; // System will provide the timestamp
 
-    SendInput(1, &startMouseInput, sizeof(startMouseInput));
+    if (SendInput(1, &startMouseInput, sizeof(INPUT)) == 0)
+        return Napi::Boolean::New(env, false);
+    ;
 
     // Perform mouse button down event
     INPUT mouseDownInput = {0};
@@ -133,7 +169,9 @@ Napi::Value DragMouse(const Napi::CallbackInfo &info)
     mouseDownInput.mi.dwFlags = MOUSEEVENTF_LEFTDOWN;
     mouseDownInput.mi.time = 0; // System will provide the timestamp
 
-    SendInput(1, &mouseDownInput, sizeof(mouseDownInput));
+    if (SendInput(1, &mouseDownInput, sizeof(INPUT)) == 0)
+        return Napi::Boolean::New(env, false);
+    ;
 
     // Calculate the number of steps based on the duration and desired speed
     const int steps = 100; // Adjust the number of steps for smoother movement
@@ -143,7 +181,7 @@ Napi::Value DragMouse(const Napi::CallbackInfo &info)
     double stepY = distanceY / steps;
 
     // Move the mouse in increments to simulate dragging with speed control
-    for (int i = 0; i < steps; ++i)
+    for (int i = 0; i <= steps; ++i)
     {
         // Calculate the position for the current step
         int currentX = static_cast<int>(absoluteStartX + (stepX * i));
@@ -157,10 +195,15 @@ Napi::Value DragMouse(const Napi::CallbackInfo &info)
         mouseMoveInput.mi.dwFlags = MOUSEEVENTF_ABSOLUTE | MOUSEEVENTF_MOVE | MOUSEEVENTF_VIRTUALDESK;
         mouseMoveInput.mi.time = 0; // System will provide the timestamp
 
-        SendInput(1, &mouseMoveInput, sizeof(mouseMoveInput));
+        if (SendInput(1, &mouseMoveInput, sizeof(INPUT)) == 0)
+            return Napi::Boolean::New(env, false);
+        ;
 
         // Sleep for a short duration to control the speed
-        Sleep(static_cast<DWORD>(duration / steps));
+        if (i < steps)
+        {
+            Sleep(static_cast<DWORD>(duration / steps));
+        }
     }
 
     // Perform mouse button up event
@@ -169,7 +212,197 @@ Napi::Value DragMouse(const Napi::CallbackInfo &info)
     mouseUpInput.mi.dwFlags = MOUSEEVENTF_LEFTUP;
     mouseUpInput.mi.time = 0; // System will provide the timestamp
 
-    SendInput(1, &mouseUpInput, sizeof(mouseUpInput));
+    if (SendInput(1, &mouseUpInput, sizeof(INPUT)) == 0)
+        return Napi::Boolean::New(env, false);
+    return Napi::Boolean::New(env, success);
+}
+
+LRESULT CALLBACK MouseProc(int nCode, WPARAM wParam, LPARAM lParam)
+{
+    if (nCode >= 0 && !listenerStopping.load())
+    {
+        MSLLHOOKSTRUCT *mouse = (MSLLHOOKSTRUCT *)lParam;
+
+        int x = mouse->pt.x;
+        int y = mouse->pt.y;
+
+        std::string type = "move";
+
+        switch (wParam)
+        {
+        case WM_LBUTTONDOWN:
+            type = "leftDown";
+            break;
+        case WM_LBUTTONUP:
+            type = "leftUp";
+            break;
+        case WM_RBUTTONDOWN:
+            type = "rightDown";
+            break;
+        case WM_RBUTTONUP:
+            type = "rightUp";
+            break;
+        case WM_MBUTTONDOWN:
+            type = "middleDown";
+            break;
+        case WM_MBUTTONUP:
+            type = "middleUp";
+            break;
+        case WM_MOUSEMOVE:
+            type = "move";
+            break;
+        }
+
+        auto callback = [x, y, type](Napi::Env env, Napi::Function jsCallback)
+        {
+            Napi::Object event = Napi::Object::New(env);
+            event.Set("x", x);
+            event.Set("y", y);
+            event.Set("type", type);
+
+            jsCallback.Call({event});
+        };
+
+        napi_status status = tsfn.NonBlockingCall(callback);
+        if (status != napi_ok)
+        {
+            // tsfn is already closing
+            return CallNextHookEx(mouseHook, nCode, wParam, lParam);
+        }
+    }
+
+    return CallNextHookEx(mouseHook, nCode, wParam, lParam);
+}
+
+DWORD WINAPI HookThread(LPVOID)
+{
+    mouseHook = SetWindowsHookEx(WH_MOUSE_LL, MouseProc, NULL, 0);
+    SetEvent(hHookReady);
+    if (mouseHook == NULL)
+        return 1;
+    MSG msg;
+    while (GetMessage(&msg, NULL, 0, 0))
+    {
+        TranslateMessage(&msg);
+        DispatchMessage(&msg);
+    }
+
+    UnhookWindowsHookEx(mouseHook);
+    mouseHook = NULL;
+    return 0;
+}
+
+Napi::Value StartMouseListener(const Napi::CallbackInfo &info)
+{
+    Napi::Env env = info.Env();
 
+    if (!info[0].IsFunction())
+    {
+        Napi::TypeError::New(env, "Callback expected").ThrowAsJavaScriptException();
+        return env.Null();
+    }
+    // Bug fix: prevent double-start leaking a thread and hook
+    if (listenerRunning.test_and_set())
+    {
+        Napi::TypeError::New(env, "Mouse listener already running").ThrowAsJavaScriptException();
+        return env.Null();
+    }
+    Napi::Function callback = info[0].As<Napi::Function>();
+
+    tsfn = Napi::ThreadSafeFunction::New(
+        env,
+        callback,
+        "MouseListener",
+        0,
+        1);
+
+    // Store handle and thread ID so StopMouseListener can signal and wait
+    hHookReady = CreateEvent(NULL, TRUE, FALSE, NULL);
+    if (hHookReady == NULL)
+    {
+        tsfn.Release();
+        listenerRunning.clear();
+        Napi::Error::New(env, "Failed to create sync event").ThrowAsJavaScriptException();
+        return env.Null();
+    }
+    hHookThread = CreateThread(NULL, 0, HookThread, NULL, 0, &hookThreadId);
+    if (hHookThread == NULL)
+    {
+        tsfn.Release();
+        CloseHandle(hHookReady);
+        hHookReady = NULL;
+        listenerRunning.clear(); // release the guard so caller can retry
+        Napi::Error::New(env, "Failed to create hook thread").ThrowAsJavaScriptException();
+        return env.Null();
+    }
+    WaitForSingleObject(hHookReady, 2000);
+    CloseHandle(hHookReady);
+    hHookReady = NULL;
+    DWORD exitCode = 0;
+    GetExitCodeThread(hHookThread, &exitCode);
+    if (exitCode == 1)
+    {
+        WaitForSingleObject(hHookThread, 1000);
+        CloseHandle(hHookThread);
+        hHookThread = NULL;
+        hookThreadId = 0;
+        tsfn.Release();
+        listenerRunning.clear();
+        Napi::Error::New(env, "Failed to install mouse hook").ThrowAsJavaScriptException();
+        return env.Null();
+    }
     return Napi::Boolean::New(env, true);
 }
+
+Napi::Value StopMouseListener(const Napi::CallbackInfo &info)
+{
+    Napi::Env env = info.Env();
+    Napi::Object result = Napi::Object::New(env);
+
+    if (hHookThread == NULL)
+    {
+        result.Set("success", false);
+        result.Set("error", "No listener is running");
+        return result;
+    }
+
+    listenerStopping.store(true);
+    // PostThreadMessage with WM_QUIT breaks the GetMessage loop in HookThread,
+    // which then runs UnhookWindowsHookEx and exits
+    if (!PostThreadMessage(hookThreadId, WM_QUIT, 0, 0))
+    {
+        listenerStopping.store(false);
+        listenerRunning.clear();
+        result.Set("success", false);
+        result.Set("error", "Failed to signal hook thread");
+        result.Set("errorCode", Napi::Number::New(env, GetLastError()));
+        return result;
+    }
+
+    // Wait for the thread to fully exit before releasing resources
+    DWORD waitResult = WaitForSingleObject(hHookThread, 3000);
+    if (waitResult != WAIT_OBJECT_0)
+    {
+        // Thread didn't exit in time - kill it
+        TerminateThread(hHookThread, 1);
+        // Best-effort: reduce chance a concurrent NonBlockingCall is still
+        // in-flight before tsfn.Release() below. Not a hard guarantee.
+        Sleep(50);
+        result.Set("success", false);
+        result.Set("error", "Hook thread did not exit cleanly, was forcefully terminated");
+    }
+    else
+    {
+        result.Set("success", true);
+    }
+
+    // Release the TSFN so Node.js can garbage collect the JS callback
+    tsfn.Release();
+
+    CloseHandle(hHookThread);
+    hHookThread = NULL;
+    hookThreadId = 0;
+    listenerRunning.clear();
+    listenerStopping.store(false);
+    return result;
+}

package/src/index.mts

@@ -107,6 +107,8 @@ export type Imread = (path: string) => ImageData;
 
 export type Imwrite = (image: ImageData) => Buffer;
 
+export type StartMouseListener = (callback: (data: {x: number, y: number, type: string}) => void) => void;
+export type StopMouseListener = () => {success: boolean, error?: string, errorCode?: number};
 export type MatchTemplate = (
   image: ImageData,
   template: ImageData,
@@ -135,7 +137,7 @@ export type GetRegion = (image: ImageData, region: ROI) => ImageData;
 
 export type TextRecognition = (trainedDataPath: string, dataLang: string, imagePath: string) => string;
 export type CaptureScreenAsync = () => Promise<Buffer>;
-
+export type BringWindowToFront = (windowName: string) => boolean;
 const {
   setKeyDownCallback,
   setKeyUpCallback,
@@ -158,7 +160,11 @@ const {
   getRegion,
   textRecognition,
   equalizeHist,
-  darkenColor
+  darkenColor,
+  bringWindowToFront,
+  startMouseListener,
+  stopMouseListener
+  
 }: {
   setKeyDownCallback: SetKeyCallback;
   setKeyUpCallback: SetKeyCallback;
@@ -182,6 +188,9 @@ const {
   captureScreenAsync: CaptureScreenAsync;
   equalizeHist: EqualizeHist;
   darkenColor: DarkenColor;
+  bringWindowToFront: BringWindowToFront;
+  startMouseListener: StartMouseListener;
+  stopMouseListener: StopMouseListener
 } = bindings;
 
 const rawPressKey = pressKey;
@@ -525,6 +534,7 @@ function keyPress(keyCode: number, repeat?: number): Promise<boolean> {
 
 export {
   getWindowData,
+  bringWindowToFront,
   captureWindow,
   captureWindowN,
   mouseMove,
@@ -537,6 +547,8 @@ export {
   textRecognition,
   captureScreenToFile,
   captureScreenAsync,
+  startMouseListener,
+  stopMouseListener,
   KeyboardListener,
   OpenCV
 };