@aspiresys/visor 1.3.4 → 1.4.0

package/dist/types.d.ts

@@ -31,63 +31,79 @@ export declare class Region {
     constructor(x: number, y: number, width: number, height: number, confidence?: number);
     private checkConfig;
     /**
-   * Returns the center point of the region.
-   *
-   * Useful for:
-   * - mouse movement
-   * - coordinate calculations
-   * - custom interactions
-   */
+     * Captures a screenshot of the
+     * region and saves it
+     * to the specified path.
+     *
+     * Supported formats depend on
+     * the output file extension.
+     *
+     * @param path Output image path.
+     *
+     * @example
+     * await region.capture(
+     *   "./screenshots/output.png"
+     * );
+     */
+    capture(path: string): Promise<void>;
+    /**
+     * Returns the center point of the region.
+     *
+     * Useful for:
+     * - mouse movement
+     * - coordinate calculations
+     * - custom interactions
+     */
     center(): {
         x: number;
         y: number;
     };
     /**
-   * Moves the mouse to the center of the region.
-   *
-   * Mouse coordinates are automatically
-   * adjusted for display scaling.
-   */
+     * Moves the mouse to the center of the region.
+     *
+     * Mouse coordinates are automatically
+     * adjusted for display scaling.
+     */
     move(): Promise<void>;
     /**
-   * Performs a left click on the region.
-   *
-   * Clicks the center of the region by default.
-   *
-   * Optional offset can be supplied to click
-   * a specific position relative to the center.
-   */
+     * Performs a left click on the region.
+     *
+     * Clicks the center of the region by default.
+     *
+     * Optional offset can be supplied to click
+     * a specific position relative to the center.
+     */
     click(offset?: Offset): Promise<void>;
     /**
-   * Finds an image in the Region 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 region.clickImg("save.png");
-   *
-   * @example
-   * await region.clickImg("./images/save.png", 0.9);
-   */
+     * Finds an image in the Region 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 region.clickImg("save.png");
+     *
+     * @example
+     * await region.clickImg("./images/save.png", 0.9);
+     */
     clickImg(image?: string, confidence?: number, offset?: Offset): Promise<void>;
     /**
      * Finds the image in the Region and
@@ -144,144 +160,218 @@ export declare class Region {
      */
     doubleClickImg(image?: string, confidence?: number, offset?: Offset): Promise<void>;
     /**
-   * Waits until an image appears
-   * in the Region.
-   *
-   * @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 region.waitImg("loading-done.png");
-   */
+     * Waits until an image appears
+     * in the Region.
+     *
+     * @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 region.waitImg("loading-done.png");
+     */
     waitImg(image: string, { confidence, timeout }?: {
         confidence?: number;
         timeout?: number;
     }): Promise<boolean>;
     /**
-   * Performs a double left click on the region.
-   *
-   * Optional offset can be supplied to click
-   * a specific position relative to the center.
-   */
+     * Waits until any image from
+     * a list appears in the Region.
+     *
+     * 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
+     *
+     * @throws Error if timeout occurs.
+     *
+     * @example
+     * await visor.waitAnyImg([
+     *   "home-light.png",
+     *   "home-dark.png"
+     * ]);
+     */
+    waitAnyImg(images: string[], { confidence, timeout }?: {
+        confidence?: number;
+        timeout?: number;
+    }): Promise<Region>;
+    /**
+     * Finds the first matching image
+     * within the current Region and
+     * performs a click.
+     *
+     * Useful for:
+     * - theme variations
+     * - alternate UI states
+     * - dynamic controls
+     *
+     * @param images Array of image paths.
+     * @param confidence Match confidence.
+     * @param offset Optional click offset.
+     *
+     * @returns Matched Region.
+     *
+     * @example
+     * await region.clickAny([
+     *   "save-light.png",
+     *   "save-dark.png"
+     * ]);
+     */
+    clickAny(images: string[], confidence?: number, offset?: Offset): Promise<Region>;
+    /**
+     * Performs a double left click on the region.
+     *
+     * Optional offset can be supplied to click
+     * a specific position relative to the center.
+     */
     doubleClick(offset?: Offset): Promise<void>;
     /**
-   * Performs a right click on the region.
-   *
-   * Optional offset can be supplied to click
-   * a specific position relative to the center.
-   */
+     * Performs a right click on the region.
+     *
+     * Optional offset can be supplied to click
+     * a specific position relative to the center.
+     */
     rightClick(offset?: Offset): Promise<void>;
     /**
-   * Checks whether the supplied coordinates
-   * are located inside this region.
-   *
-   * Returns:
-   * - true if inside
-   * - false otherwise
-   */
+     * Checks whether the supplied coordinates
+     * are located inside this region.
+     *
+     * Returns:
+     * - true if inside
+     * - false otherwise
+     */
     contains(x: number, y: number): boolean;
     /**
-   * Creates a new Region shifted by the
-   * supplied x and y offsets.
-   *
-   * Original region remains unchanged.
-   */
+     * Creates a new Region shifted by the
+     * supplied x and y offsets.
+     *
+     * Original region remains unchanged.
+     */
     offset(x: number, y: number): Region;
     /**
-   * Checks whether this region overlaps
-   * with another region.
-   *
-   * Returns:
-   * - true if regions intersect
-   * - false otherwise
-   */
+     * Checks whether this region overlaps
+     * with another region.
+     *
+     * Returns:
+     * - true if regions intersect
+     * - false otherwise
+     */
     intersects(region: Region): boolean;
     /**
-   * Returns the total area of the region
-   * in pixels.
-   */
+     * Returns the total area of the region
+     * in pixels.
+     */
     area(): number;
     /**
-   * Extracts OCR text from this region.
-   *
-   * Returns full OCR output including:
-   * - text
-   * - TSV data
-   * - HOCR data
-   * - block information
-   */
+     * Extracts OCR text from this region.
+     *
+     * Returns full OCR output including:
+     * - text
+     * - TSV data
+     * - HOCR data
+     * - block information
+     */
     readText(): Promise<any>;
     /**
-   * Searches for text within this region.
-   *
-   * Returns the matching text region
-   * if found, otherwise null.
-   *
-   * Supports selecting a specific match
-   * using the index parameter.
-   */
+     * Searches for text within this region.
+     *
+     * Returns the matching text region
+     * if found, otherwise null.
+     *
+     * Supports selecting a specific match
+     * using the index parameter.
+     */
     findText(text: string, index?: number): Promise<Region>;
     /**
-   * Checks whether the supplied text
-   * exists within this region.
-   *
-   * Returns:
-   * - true if found
-   * - false otherwise
-   */
+     * Checks whether the supplied text
+     * exists within this region.
+     *
+     * Returns:
+     * - true if found
+     * - false otherwise
+     */
     existsText(text: string): Promise<boolean>;
     /**
-   * Searches for an image within this region.
-   *
-   * Matching is performed only inside
-   * the current region, improving speed
-   * and reducing false positives.
-   *
-   * Returns:
-   * - matching Region if found
-   * - null otherwise
-   */
+     * Searches for an image within this region.
+     *
+     * Matching is performed only inside
+     * the current region, improving speed
+     * and reducing false positives.
+     *
+     * Returns:
+     * - matching Region if found
+     * - null otherwise
+     */
     find(image: string, confidence?: number): Promise<Region>;
+    expand(pixels: number): Region;
     /**
-   * Finds all image matches within this region.
-   *
-   * Matching is performed only inside
-   * the current region.
-   *
-   * Returns an array of matching regions.
-   */
+     * Finds all image matches within this region.
+     *
+     * Matching is performed only inside
+     * the current region.
+     *
+     * Returns an array of matching regions.
+     */
     findAll(image: string, confidence?: number): Promise<Region[]>;
     /**
-   * Checks whether an image exists
-   * within this region.
-   *
-   * Returns:
-   * - true if found
-   * - false otherwise
-   */
+     * Checks whether an image exists
+     * within this region.
+     *
+     * Returns:
+     * - true if found
+     * - false otherwise
+     */
     exists(image: string, confidence?: number): Promise<boolean>;
 }
 /**