@aspiresys/visor 1.2.10 → 1.2.11

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Key, Button, Point } from "@nut-tree-fork/nut-js";
 import { Region } from "./types";
 export declare class Visor {
-    mouse: import("@nut-tree-fork/nut-js").MouseClass;
-    keyboard: import("@nut-tree-fork/nut-js").KeyboardClass;
+    private mouse;
+    private keyboard;
     Key: typeof Key;
     Button: typeof Button;
     private configWarningShown;
@@ -719,11 +719,12 @@ export declare class Visor {
      *
      * @param x X coordinate.
      * @param y Y coordinate.
+     * @param inspectorCoords Boolean to represent if the coords are from visor-inspector
      *
      * @example
      * await visor.moveMouse(500, 300);
      */
-    moveMouse(x: number, y: number): Promise<void>;
+    moveMouse(x: number, y: number, inspectorCoords?: boolean): Promise<void>;
     /**
      * Returns the current mouse cursor
      * position.

package/dist/index.js

@@ -336,8 +336,12 @@ class Visor {
         const start = Date.now();
         const screen = await (0, screen_1.captureScreen)();
         const template = await (0, matcher_1.loadTemplate)((0, path_1.resolveImagePath)(image));
+        const scaleFactor = config_1.visorConfig.scaleFactor;
         try {
             const result = (0, matcher_1.matchTemplate)(screen, template, confidence);
+            if (result) {
+                (0, logger_1.log)(`[FIND] Actual coords: (${Math.floor(result.x * scaleFactor)}, ${Math.floor(result.y * scaleFactor)})`);
+            }
             (0, logger_1.log)(`[FIND] Total: ${Date.now() - start} ms`);
             return result;
         }
@@ -929,13 +933,19 @@ CONF:${m.confidence.toFixed(3)}
      *
      * @param x X coordinate.
      * @param y Y coordinate.
+     * @param inspectorCoords Boolean to represent if the coords are from visor-inspector
      *
      * @example
      * await visor.moveMouse(500, 300);
      */
-    async moveMouse(x, y) {
+    async moveMouse(x, y, inspectorCoords = false) {
         this.checkConfig();
-        await this.mouse.move((0, nut_js_1.straightTo)(new nut_js_1.Point(x, y)));
+        if (inspectorCoords) {
+            await this.mouse.move((0, nut_js_1.straightTo)(new nut_js_1.Point(x, y)));
+            return;
+        }
+        const scaleFactor = config_1.visorConfig.scaleFactor;
+        await this.mouse.move((0, nut_js_1.straightTo)(new nut_js_1.Point(Math.floor(x / scaleFactor), Math.floor(y / scaleFactor))));
     }
     /**
      * Returns the current mouse cursor

package/inspector/index.html

@@ -24,7 +24,8 @@
               <div class="input-wrapper">
                 <span class="input-hint">Confidence</span>
                 <input id="confidenceInput" type="number" min="0" max="1" step="0.01" value="0.8" />
-                <span class="input-hint">(0.0 - 1.0)</span>
+                <span class="input-hint">(0.0 - 1.0)    </span>
+                Current Template: <span id="currentTemplate" class="template-status">None</span>
               </div>
             </div>
           </div>
@@ -36,22 +37,12 @@
           <canvas id="screenCanvas" class="canvas"></canvas>
         </div>
         <div class="result-panel">
+          <h3 class="section-title"> Template </h3>
+          <img id="templatePreview" class="template-preview" alt="No Template Loaded" src="data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs="/>
           <h3 class="section-title"> Match Result </h3>
           <div id="matchResult"> No Match Tested </div>
-        </div>
+         </div>
       </div>
-      <section class="template-section">
-        <h3 class="section-title">Template Management</h3>
-        <div class="template-grid">
-          <div class="template-info">
-            <p>
-              <strong>Current Template: </strong>
-              <span id="currentTemplate" class="template-status">None</span>
-            </p>
-          </div>
-          <img id="templatePreview" class="template-preview" />
-        </div>
-      </section>
     </div>
     <script src="./src/renderer.js"></script>
   </body>

package/inspector/src/renderer.js

@@ -30,6 +30,7 @@ captureBtn.addEventListener("click",
 			const scale = image.width > maxWidth ? maxWidth / image.width : 1;
 			canvas.width = image.width * scale;
 			canvas.height = image.height * scale;
+			matchResult.textContent = " No Match Tested ";
 			ctx.drawImage(
 				image,
 				0,
@@ -125,8 +126,18 @@ saveBtn.addEventListener("click",
 				height: Math.abs(endY - startY),
 				outputPath: filePath
 			});
+		const fileName = filePath.split(/[\\/]/).pop();
 		selectedTemplatePath = filePath;
-		currentTemplate.textContent = filePath;
+		currentTemplate.textContent = fileName;
+		currentTemplate.title = filePath;
+		matchResult.textContent = " No Match Tested ";
+		ctx.drawImage(
+			image,
+			0,
+			0,
+			canvas.width,
+			canvas.height
+		);
 		templatePreview.src = filePath + "?t=" + Date.now();
 		alert("Template Saved");
 	}
@@ -155,8 +166,30 @@ testMatchBtn.addEventListener("click", async () => {
 
   if (!result) {
 	matchResult.textContent = "✗ MATCH NOT FOUND";
+	ctx.drawImage(
+		image,
+		0,
+		0,
+		canvas.width,
+		canvas.height
+	);
     return;
   }
+  ctx.drawImage(
+  	image,
+	0,
+	0,
+	canvas.width,
+	canvas.height
+  );
+  ctx.strokeStyle = "lime";
+  ctx.lineWidth = 3;
+  ctx.strokeRect(
+	result.x / imageScaleX,
+	result.y / imageScaleY,
+	result.width / imageScaleX,
+	result.height / imageScaleY
+  );
   matchResult.textContent = `
 	✓ MATCH FOUND
 
@@ -178,8 +211,18 @@ loadTemplateBtn.addEventListener("click",
 		if (!path) {
 			return;
 		}
+		const fileName = path.split(/[\\/]/).pop();
 		selectedTemplatePath = path;
-		currentTemplate.textContent = path;
+		currentTemplate.textContent = fileName;
+		currentTemplate.title = path;
+		matchResult.textContent = " No Match Tested ";
+		ctx.drawImage(
+			image,
+			0,
+			0,
+			canvas.width,
+			canvas.height
+		);
 		templatePreview.src = path + "?t=" + Date.now();
 	}
 );

package/inspector/styles.css

@@ -238,6 +238,7 @@ input[type="number"]:focus {
   display: block;
   margin-top: 15px;
   box-shadow: 0 0 20px rgba(0, 212, 255, 0.1);
+  width: stretch;
 }
 
 /* TEMPLATE SECTION */
@@ -268,26 +269,23 @@ input[type="number"]:focus {
 }
 
 .template-status {
-  display: inline-block;
-  padding: 4px 7px;
-  background: rgba(76, 175, 80, 0.15);
-  border: 1px solid rgba(76, 175, 80, 0.3);
-  border-radius: 6px;
   color: #4caf50;
-  font-weight: 500;
-  width: fit-content;
+  font-size: small;
 }
 
 .template-preview {
   border: 2px solid #00d4ff;
   border-radius: 8px;
+  width: 130px;
   max-width: 100%;
-  height: auto;
+  height: 130px;
   max-height: 150px;
   object-fit: contain;
   background: #0a0a0a;
   box-shadow: 0 0 20px rgba(0, 212, 255, 0.1);
   display: none;
+  margin-top: 15px;
+  margin-bottom: 15px;
 }
 
 .template-preview[src]:not([src=""]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspiresys/visor",
-  "version": "1.2.10",
+  "version": "1.2.11",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/readme.md

@@ -22,6 +22,8 @@ Visor is designed for automating desktop workflows using visual interactions ins
 * Region OCR support
 * Automatic display scaling detection
 * Mouse automation
+* Region-based mouse automation
+* Target offset support
 * Keyboard automation
 * Drag & drop support
 * Multi-theme image handling
@@ -51,6 +53,23 @@ npm install @aspiresys/visor
 
 ---
 
+# Visor Inspector
+
+Visor includes an optional desktop Inspector tool for:
+
+* Capturing templates
+* Testing image matches
+* Measuring screen coordinates
+* Validating confidence thresholds
+
+Run:
+
+```bash
+npx visor-inspector
+```
+
+---
+
 # Quick Start
 
 ```ts
@@ -167,6 +186,67 @@ const region =
 
 ---
 
+## Region-Based Automation
+
+Regions can be obtained from:
+
+* visor.find()
+* visor.findAll()
+* visor.findText()
+* Visor Inspector
+
+### Move To Region
+
+```ts
+const region =
+  await visor.find(
+    "save.png"
+  );
+
+await visor.moveToRegion(
+  region
+);
+```
+
+### Click Region
+
+```ts
+const region =
+  await visor.find(
+    "save.png"
+  );
+
+await visor.clickRegion(
+    region
+  );
+```
+
+### Double Click Region
+
+```ts
+await visor.doubleClickRegion({
+  x: 100,
+  y: 200,
+  width: 150,
+  height: 50
+});
+```
+
+### Right Click Region
+
+```ts
+await visor.rightClickRegion({
+  x: 100,
+  y: 200,
+  width: 150,
+  height: 50
+});
+```
+
+Display scaling is automatically applied when using region-based APIs.
+
+---
+
 ## Check Image Exists
 
 ```ts
@@ -230,6 +310,47 @@ await visor.hover("menu.png");
 
 ---
 
+## Target Offsets
+
+Target offsets allow mouse actions to be performed relative to the center of a matched image.
+
+Useful for:
+
+* Dropdown arrows
+* Adjacent controls
+* Dynamic layouts
+* Composite UI elements
+
+### Click With Offset
+
+```ts
+await visor.click(
+  "search.png",
+  0.8,
+  {
+    x: 50,
+    y: 0
+  }
+);
+```
+
+### Hover With Offset
+
+```ts
+await visor.hover(
+  "menu.png",
+  0.8,
+  {
+    x: -20,
+    y: 10
+  }
+);
+```
+
+Offsets are applied relative to the center of the matched region before display scaling adjustments are performed.
+
+---
+
 # OCR Automation
 
 Visor includes OCR automation powered by Tesseract.js.
@@ -351,6 +472,21 @@ await visor.moveMouse(
 
 ---
 
+### Move To Inspector Region
+
+```ts
+await visor.moveToRegion({
+  x: 90,
+  y: 61,
+  width: 138,
+  height: 69
+});
+```
+
+Region coordinates can be copied directly from Visor Inspector match results.
+
+---
+
 ## Scroll Down
 
 ```ts
@@ -497,9 +633,9 @@ visor.loadConfig({
 
 # Roadmap
 
-* Template cache
-* OCR cache
-* Scale cache
+* Match visualization overlay
+* Inspector coordinate picker
+* Multi-monitor support improvements
 * Parallel image matching
 * Advanced OCR tuning
 * Electron recorder