@mediar-ai/terminator 0.24.7 → 0.24.9

package/index.d.ts

@@ -604,9 +604,12 @@ export declare class Desktop {
    * @param {number} [yPercentage=50] - Y position within bounds as percentage (0-100). Defaults to 50 (center).
    * @param {ClickType} [clickType='left'] - Type of click: 'left', 'double', or 'right'.
    * @param {boolean} [restoreCursor=true] - If true, restore cursor to original position after clicking.
+   * @param {string} [process] - Process name for window screenshot capture. If provided, enables window screenshots.
+   * @param {boolean} [includeWindowScreenshot=true] - Whether to capture window screenshot (requires process).
+   * @param {boolean} [includeMonitorScreenshots=false] - Whether to capture monitor screenshots after clicking.
    * @returns {ClickResult} Result with clicked coordinates and method details.
    */
-  clickAtBounds(x: number, y: number, width: number, height: number, xPercentage?: number | undefined | null, yPercentage?: number | undefined | null, clickType?: ClickType | undefined | null, restoreCursor?: boolean | undefined | null): ClickResult
+  clickAtBounds(x: number, y: number, width: number, height: number, xPercentage?: number | undefined | null, yPercentage?: number | undefined | null, clickType?: ClickType | undefined | null, restoreCursor?: boolean | undefined | null, process?: string | undefined | null, includeWindowScreenshot?: boolean | undefined | null, includeMonitorScreenshots?: boolean | undefined | null): ClickResult
   /**
    * Click on an element by its index from the last tree/vision query.
    *
@@ -619,9 +622,12 @@ export declare class Desktop {
    * @param {number} [yPercentage=50] - Y position within bounds as percentage (0-100).
    * @param {ClickType} [clickType='Left'] - Type of click: 'Left', 'Double', or 'Right'.
    * @param {boolean} [restoreCursor=true] - If true, restore cursor to original position after clicking.
+   * @param {string} [process] - Process name for window screenshot capture. If provided, enables window screenshots.
+   * @param {boolean} [includeWindowScreenshot=true] - Whether to capture window screenshot (requires process).
+   * @param {boolean} [includeMonitorScreenshots=false] - Whether to capture monitor screenshots after clicking.
    * @returns {ClickResult} Result with clicked coordinates, element info, and method details.
    */
-  clickByIndex(index: number, visionType?: VisionType | undefined | null, xPercentage?: number | undefined | null, yPercentage?: number | undefined | null, clickType?: ClickType | undefined | null, restoreCursor?: boolean | undefined | null): ClickResult
+  clickByIndex(index: number, visionType?: VisionType | undefined | null, xPercentage?: number | undefined | null, yPercentage?: number | undefined | null, clickType?: ClickType | undefined | null, restoreCursor?: boolean | undefined | null, process?: string | undefined | null, includeWindowScreenshot?: boolean | undefined | null, includeMonitorScreenshots?: boolean | undefined | null): ClickResult
   /**
    * (async) Run a shell command.
    *
@@ -770,8 +776,11 @@ export declare class Desktop {
    * Open a file with its default application.
    *
    * @param {string} filePath - Path to the file to open.
+   * @param {string} [process] - Process name for window screenshot capture. If provided, enables window screenshots.
+   * @param {boolean} [includeWindowScreenshot=true] - Whether to capture window screenshot (requires process).
+   * @param {boolean} [includeMonitorScreenshots=false] - Whether to capture monitor screenshots after opening.
    */
-  openFile(filePath: string): void
+  openFile(filePath: string, process?: string | undefined | null, includeWindowScreenshot?: boolean | undefined | null, includeMonitorScreenshots?: boolean | undefined | null): void
   /**
    * Activate a browser window by title.
    *
@@ -949,8 +958,11 @@ export declare class Desktop {
    * (async) Press a key globally.
    *
    * @param {string} key - The key to press (e.g., "Enter", "Ctrl+C", "F1").
+   * @param {string} [process] - Process name for window screenshot capture. If provided, enables window screenshots.
+   * @param {boolean} [includeWindowScreenshot=true] - Whether to capture window screenshot (requires process).
+   * @param {boolean} [includeMonitorScreenshots=false] - Whether to capture monitor screenshots after key press.
    */
-  pressKey(key: string): Promise<void>
+  pressKey(key: string, process?: string | undefined | null, includeWindowScreenshot?: boolean | undefined | null, includeMonitorScreenshots?: boolean | undefined | null): Promise<void>
   /**
    * (async) Execute JavaScript in a browser tab.
    * Finds the browser window by process name and executes the script.
@@ -1236,8 +1248,9 @@ export declare class Element {
    * @param {number} startY - Starting Y coordinate.
    * @param {number} endX - Ending X coordinate.
    * @param {number} endY - Ending Y coordinate.
+   * @param {ActionOptions} [options] - Optional action options.
    */
-  mouseDrag(startX: number, startY: number, endX: number, endY: number): void
+  mouseDrag(startX: number, startY: number, endX: number, endY: number, options?: ActionOptions | undefined | null): void
   /**
    * Press and hold mouse at coordinates.
    *
@@ -1252,8 +1265,12 @@ export declare class Element {
    * @param {number} y - Y coordinate.
    */
   mouseMove(x: number, y: number): void
-  /** Release mouse button. */
-  mouseRelease(): void
+  /**
+   * Release mouse button.
+   *
+   * @param {ActionOptions} [options] - Optional action options.
+   */
+  mouseRelease(options?: ActionOptions | undefined | null): void
   /**
    * Create a locator from this element.
    * Accepts either a selector string or a Selector object.
@@ -1356,9 +1373,10 @@ export declare class Element {
    * It only performs an action if the control is not already in the desired state.
    *
    * @param {boolean} state - The desired toggle state.
+   * @param {ActionOptions} [options] - Optional action options.
    * @returns {void}
    */
-  setToggled(state: boolean): void
+  setToggled(state: boolean, options?: ActionOptions | undefined | null): void
   /**
    * Checks if an element is selected (e.g., list item, tree node, tab).
    *
@@ -1384,9 +1402,10 @@ export declare class Element {
    * Sets the value of a range-based control like a slider.
    *
    * @param {number} value - The value to set.
+   * @param {ActionOptions} [options] - Optional action options.
    * @returns {void}
    */
-  setRangeValue(value: number): void
+  setRangeValue(value: number, options?: ActionOptions | undefined | null): void
   /**
    * Gets the value attribute of an element (text inputs, combo boxes, etc.).
    *

package/package.json

@@ -38,8 +38,8 @@
     }
   },
   "optionalDependencies": {
-    "@mediar-ai/terminator-win32-arm64-msvc": "0.24.7",
-    "@mediar-ai/terminator-win32-x64-msvc": "0.24.7"
+    "@mediar-ai/terminator-win32-arm64-msvc": "0.24.9",
+    "@mediar-ai/terminator-win32-x64-msvc": "0.24.9"
   },
   "repository": {
     "type": "git",
@@ -57,5 +57,5 @@
     "test-hook": "powershell.exe -ExecutionPolicy Bypass -File \"../../.git/hooks/pre-push.ps1\""
   },
   "types": "wrapper.d.ts",
-  "version": "0.24.7"
+  "version": "0.24.9"
 }

package/src/desktop.rs

@@ -201,6 +201,9 @@ impl Desktop {
     /// @param {number} [yPercentage=50] - Y position within bounds as percentage (0-100). Defaults to 50 (center).
     /// @param {ClickType} [clickType='left'] - Type of click: 'left', 'double', or 'right'.
     /// @param {boolean} [restoreCursor=true] - If true, restore cursor to original position after clicking.
+    /// @param {string} [process] - Process name for window screenshot capture. If provided, enables window screenshots.
+    /// @param {boolean} [includeWindowScreenshot=true] - Whether to capture window screenshot (requires process).
+    /// @param {boolean} [includeMonitorScreenshots=false] - Whether to capture monitor screenshots after clicking.
     /// @returns {ClickResult} Result with clicked coordinates and method details.
     #[napi]
     #[allow(clippy::too_many_arguments)]
@@ -214,6 +217,9 @@ impl Desktop {
         y_percentage: Option<u8>,
         click_type: Option<ClickType>,
         restore_cursor: Option<bool>,
+        process: Option<String>,
+        include_window_screenshot: Option<bool>,
+        include_monitor_screenshots: Option<bool>,
     ) -> napi::Result<ClickResult> {
         let bounds = (x, y, width, height);
         let click_position = match (x_percentage, y_percentage) {
@@ -225,10 +231,27 @@ impl Desktop {
         let click_type = click_type.unwrap_or(ClickType::Left);
         let restore_cursor = restore_cursor.unwrap_or(true);
 
-        self.inner
+        let result = self
+            .inner
             .click_at_bounds(bounds, click_position, click_type.into(), restore_cursor)
             .map(ClickResult::from)
-            .map_err(map_error)
+            .map_err(map_error);
+
+        // Get PID from process name if provided
+        let pid = process
+            .as_ref()
+            .and_then(|p| find_pid_for_process(&self.inner, p).ok());
+
+        // Capture screenshots if requested
+        let _screenshots = capture_screenshots(
+            &self.inner,
+            pid,
+            include_window_screenshot.unwrap_or(true) && pid.is_some(),
+            include_monitor_screenshots.unwrap_or(false),
+            "clickAtBounds",
+        );
+
+        result
     }
 
     /// Click on an element by its index from the last tree/vision query.
@@ -242,8 +265,12 @@ impl Desktop {
     /// @param {number} [yPercentage=50] - Y position within bounds as percentage (0-100).
     /// @param {ClickType} [clickType='Left'] - Type of click: 'Left', 'Double', or 'Right'.
     /// @param {boolean} [restoreCursor=true] - If true, restore cursor to original position after clicking.
+    /// @param {string} [process] - Process name for window screenshot capture. If provided, enables window screenshots.
+    /// @param {boolean} [includeWindowScreenshot=true] - Whether to capture window screenshot (requires process).
+    /// @param {boolean} [includeMonitorScreenshots=false] - Whether to capture monitor screenshots after clicking.
     /// @returns {ClickResult} Result with clicked coordinates, element info, and method details.
     #[napi]
+    #[allow(clippy::too_many_arguments)]
     pub fn click_by_index(
         &self,
         index: u32,
@@ -252,6 +279,9 @@ impl Desktop {
         y_percentage: Option<u8>,
         click_type: Option<ClickType>,
         restore_cursor: Option<bool>,
+        process: Option<String>,
+        include_window_screenshot: Option<bool>,
+        include_monitor_screenshots: Option<bool>,
     ) -> napi::Result<ClickResult> {
         let vision_type = vision_type.unwrap_or(VisionType::UiTree);
         let click_position = match (x_percentage, y_percentage) {
@@ -263,7 +293,8 @@ impl Desktop {
         let click_type = click_type.unwrap_or(ClickType::Left);
         let restore_cursor = restore_cursor.unwrap_or(true);
 
-        self.inner
+        let result = self
+            .inner
             .click_by_index(
                 index,
                 vision_type.into(),
@@ -272,7 +303,23 @@ impl Desktop {
                 restore_cursor,
             )
             .map(ClickResult::from)
-            .map_err(map_error)
+            .map_err(map_error);
+
+        // Get PID from process name if provided
+        let pid = process
+            .as_ref()
+            .and_then(|p| find_pid_for_process(&self.inner, p).ok());
+
+        // Capture screenshots if requested
+        let _screenshots = capture_screenshots(
+            &self.inner,
+            pid,
+            include_window_screenshot.unwrap_or(true) && pid.is_some(),
+            include_monitor_screenshots.unwrap_or(false),
+            "clickByIndex",
+        );
+
+        result
     }
 
     /// (async) Run a shell command.
@@ -1631,9 +1678,34 @@ impl Desktop {
     /// Open a file with its default application.
     ///
     /// @param {string} filePath - Path to the file to open.
+    /// @param {string} [process] - Process name for window screenshot capture. If provided, enables window screenshots.
+    /// @param {boolean} [includeWindowScreenshot=true] - Whether to capture window screenshot (requires process).
+    /// @param {boolean} [includeMonitorScreenshots=false] - Whether to capture monitor screenshots after opening.
     #[napi]
-    pub fn open_file(&self, file_path: String) -> napi::Result<()> {
-        self.inner.open_file(&file_path).map_err(map_error)
+    pub fn open_file(
+        &self,
+        file_path: String,
+        process: Option<String>,
+        include_window_screenshot: Option<bool>,
+        include_monitor_screenshots: Option<bool>,
+    ) -> napi::Result<()> {
+        let result = self.inner.open_file(&file_path).map_err(map_error);
+
+        // Get PID from process name if provided
+        let pid = process
+            .as_ref()
+            .and_then(|p| find_pid_for_process(&self.inner, p).ok());
+
+        // Capture screenshots if requested
+        let _screenshots = capture_screenshots(
+            &self.inner,
+            pid,
+            include_window_screenshot.unwrap_or(true) && pid.is_some(),
+            include_monitor_screenshots.unwrap_or(false),
+            "openFile",
+        );
+
+        result
     }
 
     /// Activate a browser window by title.
@@ -2315,9 +2387,34 @@ impl Desktop {
     /// (async) Press a key globally.
     ///
     /// @param {string} key - The key to press (e.g., "Enter", "Ctrl+C", "F1").
+    /// @param {string} [process] - Process name for window screenshot capture. If provided, enables window screenshots.
+    /// @param {boolean} [includeWindowScreenshot=true] - Whether to capture window screenshot (requires process).
+    /// @param {boolean} [includeMonitorScreenshots=false] - Whether to capture monitor screenshots after key press.
     #[napi]
-    pub async fn press_key(&self, key: String) -> napi::Result<()> {
-        self.inner.press_key(&key).await.map_err(map_error)
+    pub async fn press_key(
+        &self,
+        key: String,
+        process: Option<String>,
+        include_window_screenshot: Option<bool>,
+        include_monitor_screenshots: Option<bool>,
+    ) -> napi::Result<()> {
+        let result = self.inner.press_key(&key).await.map_err(map_error);
+
+        // Get PID from process name if provided
+        let pid = process
+            .as_ref()
+            .and_then(|p| find_pid_for_process(&self.inner, p).ok());
+
+        // Capture screenshots if requested
+        let _screenshots = capture_screenshots(
+            &self.inner,
+            pid,
+            include_window_screenshot.unwrap_or(true) && pid.is_some(),
+            include_monitor_screenshots.unwrap_or(false),
+            "pressKey",
+        );
+
+        result
     }
 
     /// (async) Execute JavaScript in a browser tab.

package/src/element.rs

@@ -259,7 +259,8 @@ impl Element {
     #[napi]
     pub async fn click(&self, options: Option<ActionOptions>) -> napi::Result<ClickResult> {
         let opts = options.unwrap_or_default();
-        let restore_focus = opts.restore_focus.unwrap_or(true);
+        // Default false: clicking means user wants focus on clicked element
+        let restore_focus = opts.restore_focus.unwrap_or(false);
 
         // FOCUS RESTORATION: Save focus state BEFORE any window operations
         #[cfg(target_os = "windows")]
@@ -387,7 +388,8 @@ impl Element {
     #[napi]
     pub fn double_click(&self, options: Option<ActionOptions>) -> napi::Result<ClickResult> {
         let opts = options.unwrap_or_default();
-        let restore_focus = opts.restore_focus.unwrap_or(true);
+        // Default false: clicking means user wants focus on clicked element
+        let restore_focus = opts.restore_focus.unwrap_or(false);
 
         // FOCUS RESTORATION: Save focus state BEFORE any window operations
         #[cfg(target_os = "windows")]
@@ -434,7 +436,8 @@ impl Element {
     #[napi]
     pub fn right_click(&self, options: Option<ActionOptions>) -> napi::Result<()> {
         let opts = options.unwrap_or_default();
-        let restore_focus = opts.restore_focus.unwrap_or(true);
+        // Default false: clicking means user wants focus on clicked element
+        let restore_focus = opts.restore_focus.unwrap_or(false);
 
         // FOCUS RESTORATION: Save focus state BEFORE any window operations
         #[cfg(target_os = "windows")]
@@ -451,6 +454,14 @@ impl Element {
         let _ = self.inner.activate_window();
         let result = self.inner.right_click().map_err(map_error);
 
+        // Capture screenshots if requested
+        let _screenshots = capture_element_screenshots(
+            &self.inner,
+            opts.include_window_screenshot.unwrap_or(true),
+            opts.include_monitor_screenshots.unwrap_or(false),
+            "rightClick",
+        );
+
         // FOCUS RESTORATION: Restore focus state after action if we saved it
         #[cfg(target_os = "windows")]
         if let Some(state) = saved_focus {
@@ -467,7 +478,8 @@ impl Element {
     #[napi]
     pub fn hover(&self, options: Option<ActionOptions>) -> napi::Result<()> {
         let opts = options.unwrap_or_default();
-        let restore_focus = opts.restore_focus.unwrap_or(true);
+        // Default false: hover shouldn't steal focus
+        let restore_focus = opts.restore_focus.unwrap_or(false);
 
         // FOCUS RESTORATION: Save focus state BEFORE any window operations
         #[cfg(target_os = "windows")]
@@ -484,6 +496,14 @@ impl Element {
         let _ = self.inner.activate_window();
         let result = self.inner.hover().map_err(map_error);
 
+        // Capture screenshots if requested
+        let _screenshots = capture_element_screenshots(
+            &self.inner,
+            opts.include_window_screenshot.unwrap_or(true),
+            opts.include_monitor_screenshots.unwrap_or(false),
+            "hover",
+        );
+
         // FOCUS RESTORATION: Restore focus state after action if we saved it
         #[cfg(target_os = "windows")]
         if let Some(state) = saved_focus {
@@ -720,7 +740,8 @@ impl Element {
     #[napi]
     pub fn invoke(&self, options: Option<ActionOptions>) -> napi::Result<ActionResult> {
         let opts = options.unwrap_or_default();
-        let restore_focus = opts.restore_focus.unwrap_or(true);
+        // Default false: invoking is like clicking
+        let restore_focus = opts.restore_focus.unwrap_or(false);
 
         // FOCUS RESTORATION: Save focus state BEFORE any window operations
         #[cfg(target_os = "windows")]
@@ -852,6 +873,7 @@ impl Element {
     /// @param {number} startY - Starting Y coordinate.
     /// @param {number} endX - Ending X coordinate.
     /// @param {number} endY - Ending Y coordinate.
+    /// @param {ActionOptions} [options] - Optional action options.
     #[napi]
     pub fn mouse_drag(
         &self,
@@ -859,10 +881,28 @@ impl Element {
         start_y: f64,
         end_x: f64,
         end_y: f64,
+        options: Option<ActionOptions>,
     ) -> napi::Result<()> {
-        self.inner
+        let opts = options.unwrap_or_default();
+
+        if opts.highlight_before_action.unwrap_or(false) {
+            let _ = self.inner.highlight_before_action("mouse_drag");
+        }
+
+        let result = self
+            .inner
             .mouse_drag(start_x, start_y, end_x, end_y)
-            .map_err(map_error)
+            .map_err(map_error);
+
+        // Capture screenshots if requested
+        let _screenshots = capture_element_screenshots(
+            &self.inner,
+            opts.include_window_screenshot.unwrap_or(true),
+            opts.include_monitor_screenshots.unwrap_or(false),
+            "mouseDrag",
+        );
+
+        result
     }
 
     /// Press and hold mouse at coordinates.
@@ -884,9 +924,27 @@ impl Element {
     }
 
     /// Release mouse button.
+    ///
+    /// @param {ActionOptions} [options] - Optional action options.
     #[napi]
-    pub fn mouse_release(&self) -> napi::Result<()> {
-        self.inner.mouse_release().map_err(map_error)
+    pub fn mouse_release(&self, options: Option<ActionOptions>) -> napi::Result<()> {
+        let opts = options.unwrap_or_default();
+
+        if opts.highlight_before_action.unwrap_or(false) {
+            let _ = self.inner.highlight_before_action("mouse_release");
+        }
+
+        let result = self.inner.mouse_release().map_err(map_error);
+
+        // Capture screenshots if requested
+        let _screenshots = capture_element_screenshots(
+            &self.inner,
+            opts.include_window_screenshot.unwrap_or(true),
+            opts.include_monitor_screenshots.unwrap_or(false),
+            "mouseRelease",
+        );
+
+        result
     }
 
     /// Create a locator from this element.
@@ -1084,6 +1142,14 @@ impl Element {
         }
         let result = self.inner.select_option(&option_name).map_err(map_error);
 
+        // Capture screenshots if requested
+        let _screenshots = capture_element_screenshots(
+            &self.inner,
+            opts.include_window_screenshot.unwrap_or(true),
+            opts.include_monitor_screenshots.unwrap_or(false),
+            "selectOption",
+        );
+
         // FOCUS RESTORATION: Restore focus state after action if we saved it
         #[cfg(target_os = "windows")]
         if let Some(state) = saved_focus {
@@ -1114,10 +1180,27 @@ impl Element {
     /// It only performs an action if the control is not already in the desired state.
     ///
     /// @param {boolean} state - The desired toggle state.
+    /// @param {ActionOptions} [options] - Optional action options.
     /// @returns {void}
     #[napi]
-    pub fn set_toggled(&self, state: bool) -> napi::Result<()> {
-        self.inner.set_toggled(state).map_err(map_error)
+    pub fn set_toggled(&self, state: bool, options: Option<ActionOptions>) -> napi::Result<()> {
+        let opts = options.unwrap_or_default();
+
+        if opts.highlight_before_action.unwrap_or(false) {
+            let _ = self.inner.highlight_before_action("set_toggled");
+        }
+
+        let result = self.inner.set_toggled(state).map_err(map_error);
+
+        // Capture screenshots if requested
+        let _screenshots = capture_element_screenshots(
+            &self.inner,
+            opts.include_window_screenshot.unwrap_or(true),
+            opts.include_monitor_screenshots.unwrap_or(false),
+            "setToggled",
+        );
+
+        result
     }
 
     /// Checks if an element is selected (e.g., list item, tree node, tab).
@@ -1153,6 +1236,14 @@ impl Element {
         }
         let result = self.inner.set_selected(state).map_err(map_error);
 
+        // Capture screenshots if requested
+        let _screenshots = capture_element_screenshots(
+            &self.inner,
+            opts.include_window_screenshot.unwrap_or(true),
+            opts.include_monitor_screenshots.unwrap_or(false),
+            "setSelected",
+        );
+
         // FOCUS RESTORATION: Restore focus state after action if we saved it
         #[cfg(target_os = "windows")]
         if let Some(state) = saved_focus {
@@ -1174,10 +1265,27 @@ impl Element {
     /// Sets the value of a range-based control like a slider.
     ///
     /// @param {number} value - The value to set.
+    /// @param {ActionOptions} [options] - Optional action options.
     /// @returns {void}
     #[napi]
-    pub fn set_range_value(&self, value: f64) -> napi::Result<()> {
-        self.inner.set_range_value(value).map_err(map_error)
+    pub fn set_range_value(&self, value: f64, options: Option<ActionOptions>) -> napi::Result<()> {
+        let opts = options.unwrap_or_default();
+
+        if opts.highlight_before_action.unwrap_or(false) {
+            let _ = self.inner.highlight_before_action("set_range_value");
+        }
+
+        let result = self.inner.set_range_value(value).map_err(map_error);
+
+        // Capture screenshots if requested
+        let _screenshots = capture_element_screenshots(
+            &self.inner,
+            opts.include_window_screenshot.unwrap_or(true),
+            opts.include_monitor_screenshots.unwrap_or(false),
+            "setRangeValue",
+        );
+
+        result
     }
 
     /// Gets the value attribute of an element (text inputs, combo boxes, etc.).