@aspiresys/visor 1.0.0

package/dist/index.js

@@ -0,0 +1,1098 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visor = exports.Visor = void 0;
+const screen_1 = require("./screen");
+const matcher_1 = require("./matcher");
+const mouse_1 = require("./mouse");
+const text_1 = require("./text");
+const ocr_1 = require("./ocr");
+const config_1 = require("./config");
+const app_1 = require("./app");
+const nut_js_1 = require("@nut-tree-fork/nut-js");
+const path_1 = require("./path");
+class Visor {
+    constructor() {
+        this.mouse = nut_js_1.mouse;
+        this.keyboard = nut_js_1.keyboard;
+        this.Key = nut_js_1.Key;
+        this.Button = nut_js_1.Button;
+    }
+    /**
+   * Finds an image on screen using OpenCV
+   * and performs a left mouse click
+   * on the matched region.
+   *
+   * @param image Optional image filename or path.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * Lower confidence increases
+   * flexibility but may increase
+   * false positives.
+   *
+   * @example
+   * await visor.click("save.png");
+   *
+   * @example
+   * await visor.click("./images/save.png", 0.9);
+   */
+    async click(image, confidence = 0.8) {
+        if (!image) {
+            await this.mouse.click(this.Button.LEFT);
+            console.log("[MOUSE] Left click completed");
+            return;
+        }
+        const region = await this.find(image, confidence);
+        if (!region) {
+            throw new Error(`Image not found: ${image}`);
+        }
+        console.log("[CV] Match found:", region);
+        await (0, mouse_1.clickRegion)(region);
+    }
+    /**
+   * Performs a right mouse click.
+   *
+   * If an image is provided, the framework
+   * first finds the image on screen and
+   * moves the mouse to the matched region
+   * before performing the click.
+   *
+   * @param image Image filename or path.
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   * @throws Error if image is not found.
+   *
+   * @example
+   * await visor.rightClick("file.png");
+   *
+   * @example
+   * await visor.rightClick();
+   */
+    async rightClick(image, confidence = 0.8) {
+        if (image) {
+            const region = await this.find(image, confidence);
+            if (!region) {
+                throw new Error(`Image not found: ${image}`);
+            }
+            await (0, mouse_1.moveToRegion)(region);
+        }
+        await this.mouse.click(this.Button.RIGHT);
+        console.log("[MOUSE] Right click completed");
+    }
+    /**
+   * Performs a double left mouse click.
+   *
+   * If an image is provided, the framework
+   * first finds the image on screen and
+   * moves the mouse to the matched region
+   * before performing the click.
+   *
+   * @param image Image filename or path.
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * @throws Error if image is not found.
+   *
+   * @example
+   * await visor.doubleClick("folder.png");
+   *
+   * @example
+   * await visor.doubleClick();
+   */
+    async doubleClick(image, confidence = 0.8) {
+        if (image) {
+            const region = await this.find(image, confidence);
+            if (!region) {
+                throw new Error(`Image not found: ${image}`);
+            }
+            await (0, mouse_1.moveToRegion)(region);
+        }
+        await this.mouse.doubleClick(this.Button.LEFT);
+        console.log("[MOUSE] Double click completed");
+    }
+    /**
+   * Finds the best matching image on screen
+   * using OpenCV template matching.
+   *
+   * @param image Image filename or path.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * Higher confidence improves
+   * matching accuracy but may fail
+   * on scaled or slightly modified UI.
+   *
+   * @returns Best matched region or null.
+   *
+   * @example
+   * const region =
+   *   await visor.find("save.png");
+   */
+    async find(image, confidence = 0.8) {
+        const screen = await (0, screen_1.captureScreen)();
+        const template = (0, matcher_1.loadTemplate)((0, path_1.resolveImagePath)(image));
+        try {
+            return (0, matcher_1.matchTemplate)(screen, template, confidence);
+        }
+        finally {
+            screen.delete();
+            template.delete();
+        }
+    }
+    /**
+   * Checks whether an image exists
+   * on the current screen.
+   *
+   * @param image Image filename or path.
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * @returns True if image exists.
+   *
+   * @example
+   * const exists =
+   *   await visor.exists("login.png");
+   */
+    async exists(image, confidence = 0.8) {
+        return (await this.find(image, confidence)) !== null;
+    }
+    /**
+   * Finds all matching occurrences of an image
+   * on the current screen using OpenCV.
+   *
+   * @param image Image filename or path.
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Lower confidence may return
+   * more false-positive matches.
+   *
+   * @returns Array of matched regions.
+   *
+   * @example
+   * const matches =
+   *   await visor.findAll("icon.png");
+   */
+    async findAll(image, confidence = 0.8) {
+        const screen = await (0, screen_1.captureScreen)();
+        const template = (0, matcher_1.loadTemplate)((0, path_1.resolveImagePath)(image));
+        try {
+            return (0, matcher_1.findAllMatches)(screen, template, confidence);
+        }
+        finally {
+            screen.delete();
+            template.delete();
+        }
+    }
+    /**
+   * Finds all image matches and prints
+   * a formatted match preview including
+   * coordinates and confidence values.
+   *
+   * Useful for debugging and visual
+   * automation tuning.
+   *
+   * @param image Image filename or path.
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * @returns Array of matched regions.
+   *
+   * @example
+   * await visor.previewMatches("button.png");
+   */
+    async previewMatches(image, confidence = 0.8) {
+        const matches = await this.findAll(image, confidence);
+        console.log("\n=== MATCH PREVIEW ===\n");
+        matches.forEach((m, i) => {
+            console.log(`#${i + 1}
+X:${m.x}
+Y:${m.y}
+W:${m.width}
+H:${m.height}
+CONF:${m.confidence.toFixed(3)}
+`);
+        });
+        return matches;
+    }
+    /**
+   * Waits until an image appears
+   * on the screen.
+   *
+   * @param image Image filename or path.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * @param timeout Timeout duration
+   * in milliseconds.
+   *
+   * Default:
+   * 5000ms
+   *
+   * Recommended range:
+   * 1000ms to 30000ms
+   *
+   * @throws Error if timeout occurs.
+   *
+   * @example
+   * await visor.wait("loading-done.png");
+   */
+    async wait(image, confidence = 0.8, timeout = 5000) {
+        const interval = 1000;
+        const attempts = timeout / interval;
+        for (let i = 0; i < attempts; i++) {
+            if (await this.exists(image, confidence)) {
+                return true;
+            }
+            await this.sleep(interval);
+        }
+        throw new Error(`Timeout waiting for image: ${image}`);
+    }
+    /**
+   * Waits until an image disappears
+   * from the screen.
+   *
+   * @param image Image filename or path.
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   * @param timeout Timeout duration
+   * in milliseconds.
+   *
+   * Default:
+   * 5000ms
+   *
+   * Recommended range:
+   * 1000ms to 30000ms
+   * @throws Error if timeout occurs.
+   *
+   * @example
+   * await visor.waitToVanish("spinner.png");
+   */
+    async waitToVanish(image, confidence = 0.8, timeout = 5000) {
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            if (!(await this.exists(image, confidence))) {
+                return true;
+            }
+            await this.sleep(1000);
+        }
+        throw new Error(`Timeout waiting for image to vanish: ${image}`);
+    }
+    /**
+   * Waits until specific text appears
+   * on screen using OCR.
+   *
+   * Performance Note:
+   * OCR operations are computationally
+   * expensive and may take 1–5 seconds
+   * depending on screen complexity.
+   *
+   * @param text Text to search for.
+   *
+   * @param timeout Timeout duration
+   * in milliseconds.
+   *
+   * Default:
+   * 5000ms
+   *
+   * Recommended range:
+   * 1000ms to 30000ms
+   *
+   * @throws Error if timeout occurs.
+   *
+   * @example
+   * await visor.waitText("Success");
+   */
+    async waitText(text, timeout = 5000) {
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            if (await this.existsText(text)) {
+                return true;
+            }
+            await this.sleep(1000);
+        }
+        throw new Error(`Timeout waiting for text: ${text}`);
+    }
+    /**
+   * Waits until specific text disappears
+   * from screen using OCR.
+   * Performance Note:
+   * OCR operations are computationally
+   * expensive and may take 1–5 seconds
+   * depending on screen complexity.
+   *
+   * @param text Text to search for.
+   * @param timeout Timeout duration
+   * in milliseconds.
+   *
+   * Default:
+   * 5000ms
+   *
+   * Recommended range:
+   * 1000ms to 30000ms
+   *
+   * @throws Error if timeout occurs.
+   *
+   * @example
+   * await visor.waitTextToVanish("Loading");
+   */
+    async waitTextToVanish(text, timeout = 5000) {
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            if (!(await this.existsText(text))) {
+                return true;
+            }
+            await this.sleep(1000);
+        }
+        throw new Error(`Timeout waiting for text to vanish: ${text}`);
+    }
+    /**
+   * Finds text on screen using OCR
+   * and performs a left mouse click
+   * on the matched text region.
+   *
+   * @param text Text to search for.
+   *
+   * @throws Error if text is not found.
+   *
+   * @example
+   * await visor.clickText("Login");
+   */
+    async clickText(text) {
+        const region = await (0, text_1.findText)(text);
+        if (!region) {
+            throw new Error(`Text not found: ${text}`);
+        }
+        await (0, mouse_1.clickRegion)(region);
+    }
+    /**
+   * Finds text on screen or inside
+   * a specific region using OCR.
+   *
+   * @param text Text to search for.
+   * @param region Optional search region.
+   *
+   * @returns Matched text region or null.
+   *
+   * @example
+   * const region =
+   *   await visor.findText("Submit");
+   */
+    async findText(text, region) {
+        return await (0, text_1.findText)(text, region);
+    }
+    /**
+   * Checks whether specific text exists
+   * on screen using OCR.
+   *
+   * @param text Text to search for.
+   * @param region Optional search region.
+   *
+   * @returns True if text exists.
+   *
+   * @example
+   * const exists =
+   *   await visor.existsText("Teams");
+   */
+    async existsText(text, region) {
+        return await (0, text_1.existsText)(text, region);
+    }
+    /**
+   * Performs OCR on a specific
+   * screen region.
+   *
+   * @param region Screen region coordinates.
+   *
+   * @returns OCR result object.
+   *
+   * @example
+   * const result =
+   *   await visor.readRegion({
+   *     x: 100,
+   *     y: 100,
+   *     width: 500,
+   *     height: 300
+   *   });
+   */
+    async readRegion(region) {
+        return await (0, ocr_1.extractTextFromRegion)(region);
+    }
+    /**
+   * Performs OCR on the entire screen
+   * using Tesseract OCR.
+   *
+   * Captures the current screen,
+   * preprocesses the image, and
+   * extracts readable text content.
+   *
+   * Performance Note:
+   * OCR is computationally expensive
+   * and may take 1–5 seconds depending
+   * on:
+   * - screen complexity
+   * - text density
+   * - display resolution
+   * - system performance
+   *
+   * Returns:
+   * - extracted text
+   * - OCR metadata
+   * - TSV layout information
+   * - HOCR data
+   *
+   * @returns OCR result object.
+   *
+   * @example
+   * const result =
+   *   await visor.readScreen();
+   *
+   * console.log(result.text);
+   */
+    async readScreen() {
+        return await (0, ocr_1.extractTextFromRegion)();
+    }
+    /**
+   * Captures a screenshot of the
+   * current screen and saves it
+   * to the specified path.
+   *
+   * Supported formats depend on
+   * the output file extension.
+   *
+   * @param path Output image path.
+   *
+   * @example
+   * await visor.captureScreenshot(
+   *   "./screenshots/home.png"
+   * );
+   */
+    async captureScreenshot(path) {
+        console.log(`[VISOR] Saving screenshot: ${path}`);
+        await (0, screen_1.saveScreenshot)(path);
+        console.log("[VISOR] Screenshot saved");
+    }
+    /**
+   * Opens a desktop application,
+   * executable, file, folder,
+   * or URL using Windows shell.
+   *
+   * Performance Note:
+   * Some Electron-based applications
+   * may require additional startup
+   * stabilization time.
+   *
+   * @param command App name, executable,
+   * file path, or URL.
+   *
+   * @example
+   * await visor.openApp("notepad");
+   *
+   * @example
+   * await visor.openApp("chrome.exe");
+   */
+    async openApp(command) {
+        console.log(`[VISOR] Opening app: ${command}`);
+        await (0, app_1.openApp)(command);
+    }
+    /**
+   * Drags one visual element and
+   * drops it onto another using
+   * image matching.
+   *
+   * @param source Source image.
+   *
+   * @param target Target image.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * @throws Error if source or target
+   * image is not found.
+   *
+   * @example
+   * await visor.dragDrop(
+   *   "file.png",
+   *   "folder.png"
+   * );
+   */
+    async dragDrop(source, target, confidence = 0.8) {
+        const src = await this.find(source, confidence);
+        const dst = await this.find(target, confidence);
+        if (!src || !dst) {
+            throw new Error("Source or target not found");
+        }
+        await (0, mouse_1.moveToRegion)(src);
+        await this.mouse.pressButton(this.Button.LEFT);
+        await (0, mouse_1.moveToRegion)(dst);
+        await this.mouse.releaseButton(this.Button.LEFT);
+        console.log("[MOUSE] Drag and drop completed");
+    }
+    /**
+   * Moves the mouse cursor to the
+   * matched image location without
+   * performing a click.
+   *
+   * @param image Image filename or path.
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * @throws Error if image is not found.
+   *
+   * @example
+   * await visor.hover("menu.png");
+   */
+    async hover(image, confidence = 0.8) {
+        const region = await this.find(image, confidence);
+        if (!region) {
+            throw new Error(`Image not found: ${image}`);
+        }
+        await (0, mouse_1.moveToRegion)(region);
+        console.log("[MOUSE] Hover completed");
+    }
+    /**
+   * Scrolls the mouse wheel downward.
+   *
+   * @param amount Scroll amount.
+   *
+   * Default:
+   * 500
+   *
+   * Recommended range:
+   * 100 to 3000
+   *
+   * @example
+   * await visor.scrollDown(1000);
+   */
+    async scrollDown(amount = 500) {
+        await this.mouse.scrollDown(amount);
+    }
+    /**
+   * Scrolls the mouse wheel upward.
+   *
+   * @param amount Scroll amount.
+   *
+   * Default:
+   * 500
+   *
+   * Recommended range:
+   * 100 to 3000
+   *
+   * @example
+   * await visor.scrollUp(1000);
+   */
+    async scrollUp(amount = 500) {
+        await this.mouse.scrollUp(amount);
+    }
+    /**
+   * Types text using keyboard automation.
+   *
+   * @param text Text to type.
+   *
+   * @example
+   * await visor.type("Hello World");
+   */
+    async type(text) {
+        await this.keyboard.type(text);
+    }
+    /**
+   * Presses one or more keyboard keys.
+   *
+   * Supports both single key presses
+   * and hotkey combinations.
+   *
+   * @param keys Keyboard keys to press.
+   *
+   * @example
+   * await visor.press(visor.Key.Enter);
+   *
+   * @example
+   * await visor.press(
+   *   visor.Key.LeftControl,
+   *   visor.Key.S
+   * );
+   */
+    async press(...keys) {
+        await this.keyboard.pressKey(...keys);
+        await this.keyboard.releaseKey(...keys);
+    }
+    /**
+   * Pauses execution for a specified
+   * duration.
+   *
+   * Useful for:
+   * - UI stabilization
+   * - animation completion
+   * - Electron rendering delays
+   * - OCR synchronization
+   * - desktop transition handling
+   *
+   * Recommended for short stabilization
+   * waits rather than long fixed delays.
+   *
+   * @param ms Delay duration
+   * in milliseconds.
+   *
+   * Recommended range:
+   * 200ms to 5000ms
+   *
+   * Excessive sleep usage may
+   * slow automation execution.
+   *
+   * @example
+   * await visor.sleep(2000);
+   */
+    async sleep(ms) {
+        return new Promise(r => setTimeout(r, ms));
+    }
+    /**
+   * Moves the mouse cursor to the
+   * specified screen coordinates.
+   *
+   * Coordinates should match the
+   * current display scaling setup.
+   *
+   * @param x X coordinate.
+   * @param y Y coordinate.
+   *
+   * @example
+   * await visor.moveMouse(500, 300);
+   */
+    async moveMouse(x, y) {
+        await this.mouse.move((0, nut_js_1.straightTo)(new nut_js_1.Point(x, y)));
+    }
+    /**
+   * Returns the current mouse cursor
+   * position.
+   *
+   * @returns Current mouse coordinates.
+   *
+   * @example
+   * const pos =
+   *   await visor.getMousePosition();
+   */
+    async getMousePosition() {
+        return await this.mouse.getPosition();
+    }
+    /**
+   * Sets the display scaling factor
+   * used for coordinate normalization
+   * and image matching.
+   *
+   * Required for:
+   * - high-DPI displays
+   * - Windows display scaling
+   * - accurate mouse positioning
+   * - reliable template matching
+   *
+   * Common values:
+   * - 1.0 = 100% scaling
+   * - 1.25 = 125% scaling
+   * - 1.5 = 150% scaling
+   * - 2.0 = 200% scaling
+   *
+   * Incorrect scaling values may cause:
+   * - inaccurate clicks
+   * - failed image matching
+   * - incorrect OCR regions
+   * - offset mouse movement
+   *
+   * @param scale Display scaling factor.
+   *
+   * Recommended range:
+   * 1.0 to 2.0
+   *
+   * @example
+   * visor.setScaleFactor(1.5);
+   */
+    setScaleFactor(scale) {
+        config_1.visorConfig.scaleFactor = scale;
+    }
+    /**
+   * Returns the current display
+   * scaling factor.
+   *
+   * @returns Current scale factor.
+   *
+   * @example
+   * const scale =
+   *   visor.getScaleFactor();
+   */
+    getScaleFactor() {
+        return config_1.visorConfig.scaleFactor;
+    }
+    /**
+   * Enables or disables debug logging.
+   *
+   * @param mode Debug mode state.
+   *
+   * @example
+   * visor.setDebug(true);
+   */
+    setDebug(mode) {
+        config_1.visorConfig.debug = mode;
+    }
+    /**
+   * Sets the default image search path
+   * used for visual automation APIs.
+   *
+   * @param path Image directory path.
+   *
+   * @example
+   * visor.setImagePath("./images");
+   */
+    setImagePath(path) {
+        config_1.visorConfig.imagePath = path;
+    }
+    /**
+   * Returns the current default
+   * image search path.
+   *
+   * @returns Image path.
+   *
+   * @example
+   * const path =
+   *   visor.getImagePath();
+   */
+    getImagePath() {
+        return config_1.visorConfig.imagePath;
+    }
+    /**
+   * Closes a desktop application
+   * using Windows taskkill.
+   *
+   * @param processName Process executable name.
+   *
+   * @example
+   * await visor.closeApp("notepad.exe");
+   *
+   * @example
+   * await visor.closeApp("ms-teams.exe");
+   */
+    async closeApp(processName) {
+        await (0, app_1.closeApp)(processName);
+    }
+    /**
+   * Loads multiple framework settings
+   * at once from a configuration object.
+   *
+   * Useful for centralized framework
+   * initialization and project setup.
+   *
+   * Supported settings:
+   * - scaleFactor
+   * - imagePath
+   * - debug
+   *
+   * @param config Framework configuration object.
+   *
+   * @example
+   * visor.loadConfig({
+   *   scaleFactor: 1.5,
+   *   imagePath: "./images",
+   *   debug: true
+   * });
+   */
+    loadConfig(config) {
+        if (config.scaleFactor !== undefined) {
+            this.setScaleFactor(config.scaleFactor);
+        }
+        if (config.imagePath) {
+            this.setImagePath(config.imagePath);
+        }
+        if (config.debug !== undefined) {
+            this.setDebug(config.debug);
+        }
+        console.log("[VISOR] Config loaded");
+    }
+    /**
+   * Finds the first matching image
+   * from a list of possible images.
+   *
+   * Useful for handling:
+   * - light/dark themes
+   * - UI variations
+   * - multiple visual states
+   *
+   * @param images Array of image filenames or paths.
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * @returns Object containing matched image
+   * and region, or null if none matched.
+   *
+   * @example
+   * const result =
+   *   await visor.findAny([
+   *     "chat-light.png",
+   *     "chat-dark.png"
+   *   ]);
+   */
+    async findAny(images, confidence = 0.8) {
+        const screen = await (0, screen_1.captureScreen)();
+        try {
+            for (const image of images) {
+                const template = (0, matcher_1.loadTemplate)((0, path_1.resolveImagePath)(image));
+                try {
+                    const region = (0, matcher_1.matchTemplate)(screen, template, confidence);
+                    if (region) {
+                        return {
+                            image,
+                            region
+                        };
+                    }
+                }
+                finally {
+                    template.delete();
+                }
+            }
+            return null;
+        }
+        finally {
+            screen.delete();
+        }
+    }
+    /**
+   * Checks whether any image from
+   * a list exists on the current screen.
+   *
+   * Useful for handling:
+   * - multiple themes
+   * - alternate UI layouts
+   * - dynamic visual states
+   *
+   * @param images Array of image filenames or paths.
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * @returns True if any image exists.
+   *
+   * @example
+   * const exists =
+   *   await visor.existsAny([
+   *     "save-light.png",
+   *     "save-dark.png"
+   *   ]);
+   */
+    async existsAny(images, confidence = 0.8) {
+        return (await this.findAny(images, confidence)) !== null;
+    }
+    /**
+   * Finds the first matching image
+   * from a list and performs a
+   * left mouse click on it.
+   *
+   * Useful for handling:
+   * - light/dark themes
+   * - UI variations
+   * - dynamic buttons/icons
+   *
+   * @param images Array of image
+   * filenames or paths.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * Lower confidence increases
+   * flexibility but may increase
+   * false positives.
+   *
+   * @throws Error if none of the
+   * images are found.
+   *
+   * @example
+   * await visor.clickAny([
+   *   "send-light.png",
+   *   "send-dark.png"
+   * ]);
+   */
+    async clickAny(images, confidence = 0.8) {
+        const result = await this.findAny(images, confidence);
+        if (!result) {
+            throw new Error(`None of the images were found`);
+        }
+        console.log(`[VISOR] Clicking image: ${result.image}`);
+        await (0, mouse_1.clickRegion)(result.region);
+    }
+    /**
+   * Waits until any image from
+   * a list appears on screen.
+   *
+   * Useful for handling:
+   * - multiple themes
+   * - alternate UI layouts
+   * - dynamic application states
+   *
+   * @param images Array of image
+   * filenames or paths.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * Lower confidence increases
+   * flexibility but may increase
+   * false positives.
+   *
+   * @param timeout Timeout duration
+   * in milliseconds.
+   *
+   * Default:
+   * 5000ms
+   *
+   * Recommended range:
+   * 1000ms to 30000ms
+   *
+   * @returns Object containing matched image
+   * and region.
+   *
+   * @throws Error if timeout occurs.
+   *
+   * @example
+   * await visor.waitAny([
+   *   "home-light.png",
+   *   "home-dark.png"
+   * ]);
+   */
+    async waitAny(images, confidence = 0.8, timeout = 5000) {
+        const interval = 1000;
+        const attempts = timeout / interval;
+        for (let i = 0; i < attempts; i++) {
+            console.log(`[WAITANY] Attempt ${i + 1}`);
+            for (const image of images) {
+                console.log(`[WAITANY] Checking ${image}`);
+                const exists = await this.exists(image, confidence);
+                if (exists) {
+                    console.log(`[WAITANY] Found ${image}`);
+                    return true;
+                }
+            }
+            await this.sleep(interval);
+        }
+        throw new Error("Timeout waiting for images");
+    }
+    /**
+   * Terminates shared OCR worker.
+   *
+   * Useful for framework cleanup
+   * after long automation sessions.
+   *
+   * Recommended for:
+   * - long-running automation
+   * - memory cleanup
+   * - graceful framework shutdown
+   * @example
+   * await visor.terminateOCR();
+   */
+    async terminateOCR() {
+        await (0, ocr_1.terminateOCR)();
+    }
+}
+exports.Visor = Visor;
+exports.visor = new Visor();