@aspiresys/visor 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,875 @@
+import { Key, Button, Point } from "@nut-tree-fork/nut-js";
+export declare class Visor {
+    mouse: import("@nut-tree-fork/nut-js").MouseClass;
+    keyboard: import("@nut-tree-fork/nut-js").KeyboardClass;
+    Key: typeof Key;
+    Button: typeof 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);
+   */
+    click(image?: string, confidence?: number): Promise<void>;
+    /**
+   * 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();
+   */
+    rightClick(image?: string, confidence?: number): Promise<void>;
+    /**
+   * 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();
+   */
+    doubleClick(image?: string, confidence?: number): Promise<void>;
+    /**
+   * 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");
+   */
+    find(image: string, confidence?: number): Promise<import("./types").Region>;
+    /**
+   * 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");
+   */
+    exists(image: string, confidence?: number): Promise<boolean>;
+    /**
+   * 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");
+   */
+    findAll(image: string, confidence?: number): Promise<import("./types").Region[]>;
+    /**
+   * 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");
+   */
+    previewMatches(image: string, confidence?: number): Promise<import("./types").Region[]>;
+    /**
+   * 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");
+   */
+    wait(image: string, confidence?: number, timeout?: number): Promise<boolean>;
+    /**
+   * 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");
+   */
+    waitToVanish(image: string, confidence?: number, timeout?: number): Promise<boolean>;
+    /**
+   * 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");
+   */
+    waitText(text: string, timeout?: number): Promise<boolean>;
+    /**
+   * 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");
+   */
+    waitTextToVanish(text: string, timeout?: number): Promise<boolean>;
+    /**
+   * 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");
+   */
+    clickText(text: string): Promise<void>;
+    /**
+   * 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");
+   */
+    findText(text: string, region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<import("./types").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");
+   */
+    existsText(text: string, region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<boolean>;
+    /**
+   * 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
+   *   });
+   */
+    readRegion(region: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<any>;
+    /**
+   * 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);
+   */
+    readScreen(): Promise<any>;
+    /**
+   * 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"
+   * );
+   */
+    captureScreenshot(path: string): Promise<void>;
+    /**
+   * 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");
+   */
+    openApp(command: string): Promise<void>;
+    /**
+   * 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"
+   * );
+   */
+    dragDrop(source: string, target: string, confidence?: number): Promise<void>;
+    /**
+   * 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");
+   */
+    hover(image: string, confidence?: number): Promise<void>;
+    /**
+   * Scrolls the mouse wheel downward.
+   *
+   * @param amount Scroll amount.
+   *
+   * Default:
+   * 500
+   *
+   * Recommended range:
+   * 100 to 3000
+   *
+   * @example
+   * await visor.scrollDown(1000);
+   */
+    scrollDown(amount?: number): Promise<void>;
+    /**
+   * Scrolls the mouse wheel upward.
+   *
+   * @param amount Scroll amount.
+   *
+   * Default:
+   * 500
+   *
+   * Recommended range:
+   * 100 to 3000
+   *
+   * @example
+   * await visor.scrollUp(1000);
+   */
+    scrollUp(amount?: number): Promise<void>;
+    /**
+   * Types text using keyboard automation.
+   *
+   * @param text Text to type.
+   *
+   * @example
+   * await visor.type("Hello World");
+   */
+    type(text: string): Promise<void>;
+    /**
+   * 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
+   * );
+   */
+    press(...keys: any[]): Promise<void>;
+    /**
+   * 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);
+   */
+    sleep(ms: number): Promise<unknown>;
+    /**
+   * 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);
+   */
+    moveMouse(x: number, y: number): Promise<void>;
+    /**
+   * Returns the current mouse cursor
+   * position.
+   *
+   * @returns Current mouse coordinates.
+   *
+   * @example
+   * const pos =
+   *   await visor.getMousePosition();
+   */
+    getMousePosition(): Promise<Point>;
+    /**
+   * 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: number): void;
+    /**
+   * Returns the current display
+   * scaling factor.
+   *
+   * @returns Current scale factor.
+   *
+   * @example
+   * const scale =
+   *   visor.getScaleFactor();
+   */
+    getScaleFactor(): number;
+    /**
+   * Enables or disables debug logging.
+   *
+   * @param mode Debug mode state.
+   *
+   * @example
+   * visor.setDebug(true);
+   */
+    setDebug(mode: boolean): void;
+    /**
+   * Sets the default image search path
+   * used for visual automation APIs.
+   *
+   * @param path Image directory path.
+   *
+   * @example
+   * visor.setImagePath("./images");
+   */
+    setImagePath(path: string): void;
+    /**
+   * Returns the current default
+   * image search path.
+   *
+   * @returns Image path.
+   *
+   * @example
+   * const path =
+   *   visor.getImagePath();
+   */
+    getImagePath(): string;
+    /**
+   * 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");
+   */
+    closeApp(processName: string): Promise<void>;
+    /**
+   * 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: {
+        scaleFactor?: number;
+        imagePath?: string;
+        debug?: boolean;
+    }): void;
+    /**
+   * 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"
+   *   ]);
+   */
+    findAny(images: string[], confidence?: number): Promise<{
+        image: string;
+        region: import("./types").Region;
+    }>;
+    /**
+   * 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"
+   *   ]);
+   */
+    existsAny(images: string[], confidence?: number): Promise<boolean>;
+    /**
+   * 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"
+   * ]);
+   */
+    clickAny(images: string[], confidence?: number): Promise<void>;
+    /**
+   * 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"
+   * ]);
+   */
+    waitAny(images: string[], confidence?: number, timeout?: number): Promise<boolean>;
+    /**
+   * 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();
+   */
+    terminateOCR(): Promise<void>;
+}
+export declare const visor: Visor;