@mediar-ai/terminator 0.23.44 → 0.23.45

package/Cargo.toml

@@ -16,6 +16,7 @@ napi = { version = "2.12.2", default-features = false, features = [
 ] }
 napi-derive = "2.12.2"
 terminator = { workspace = true }
+tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"

package/index.d.ts

@@ -32,6 +32,11 @@ export interface ActionOptions {
   clickType?: ClickType
   /** Whether to restore cursor to original position after click. Defaults to false. */
   restoreCursor?: boolean
+  /**
+   * Whether to restore the original focus and caret position after the action. Defaults to false.
+   * When true, saves the currently focused element and caret position before the action, then restores them after.
+   */
+  restoreFocus?: boolean
 }
 /** Options for typeText method */
 export interface TypeTextOptions {
@@ -52,6 +57,11 @@ export interface TypeTextOptions {
   tryFocusBefore?: boolean
   /** Whether to try clicking the element if focus fails. Defaults to true. */
   tryClickBefore?: boolean
+  /**
+   * Whether to restore the original focus and caret position after typing. Defaults to false.
+   * When true, saves the currently focused element and caret position before typing, then restores them after.
+   */
+  restoreFocus?: boolean
   /** Whether to capture UI tree before/after action and compute diff. Defaults to false. */
   uiDiffBeforeAfter?: boolean
   /** Max depth for tree capture when doing UI diff. */

package/package.json

@@ -41,11 +41,11 @@
     }
   },
   "optionalDependencies": {
-    "@mediar-ai/terminator-darwin-arm64": "0.23.44",
-    "@mediar-ai/terminator-darwin-x64": "0.23.44",
-    "@mediar-ai/terminator-linux-x64-gnu": "0.23.44",
-    "@mediar-ai/terminator-win32-arm64-msvc": "0.23.44",
-    "@mediar-ai/terminator-win32-x64-msvc": "0.23.44"
+    "@mediar-ai/terminator-darwin-arm64": "0.23.45",
+    "@mediar-ai/terminator-darwin-x64": "0.23.45",
+    "@mediar-ai/terminator-linux-x64-gnu": "0.23.45",
+    "@mediar-ai/terminator-win32-arm64-msvc": "0.23.45",
+    "@mediar-ai/terminator-win32-x64-msvc": "0.23.45"
   },
   "repository": {
     "type": "git",
@@ -63,5 +63,5 @@
     "test-hook": "powershell.exe -ExecutionPolicy Bypass -File \"../../.git/hooks/pre-push.ps1\""
   },
   "types": "wrapper.d.ts",
-  "version": "0.23.44"
+  "version": "0.23.45"
 }

package/src/element.rs

@@ -47,6 +47,9 @@ pub struct ActionOptions {
     pub click_type: Option<ClickType>,
     /// Whether to restore cursor to original position after click. Defaults to false.
     pub restore_cursor: Option<bool>,
+    /// Whether to restore the original focus and caret position after the action. Defaults to false.
+    /// When true, saves the currently focused element and caret position before the action, then restores them after.
+    pub restore_focus: Option<bool>,
 }
 
 /// Options for typeText method
@@ -68,6 +71,9 @@ pub struct TypeTextOptions {
     pub try_focus_before: Option<bool>,
     /// Whether to try clicking the element if focus fails. Defaults to true.
     pub try_click_before: Option<bool>,
+    /// Whether to restore the original focus and caret position after typing. Defaults to false.
+    /// When true, saves the currently focused element and caret position before typing, then restores them after.
+    pub restore_focus: Option<bool>,
     /// Whether to capture UI tree before/after action and compute diff. Defaults to false.
     pub ui_diff_before_after: Option<bool>,
     /// Max depth for tree capture when doing UI diff.
@@ -253,6 +259,17 @@ 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);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] click: saving focus state BEFORE activate_window");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("click");
         }
@@ -353,6 +370,13 @@ impl Element {
         result.window_screenshot_path = screenshots.window_path;
         result.monitor_screenshot_paths = screenshots.monitor_paths;
 
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] click: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
         Ok(result)
     }
 
@@ -363,6 +387,17 @@ 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);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] double_click: saving focus state BEFORE activate_window");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("double_click");
         }
@@ -383,6 +418,13 @@ impl Element {
         result.window_screenshot_path = screenshots.window_path;
         result.monitor_screenshot_paths = screenshots.monitor_paths;
 
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] double_click: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
         Ok(result)
     }
 
@@ -392,11 +434,31 @@ 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);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] right_click: saving focus state BEFORE activate_window");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("right_click");
         }
         let _ = self.inner.activate_window();
-        self.inner.right_click().map_err(map_error)
+        let result = self.inner.right_click().map_err(map_error);
+
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] right_click: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
+        result
     }
 
     /// Hover over this element.
@@ -405,11 +467,31 @@ 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);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] hover: saving focus state BEFORE activate_window");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("hover");
         }
         let _ = self.inner.activate_window();
-        self.inner.hover().map_err(map_error)
+        let result = self.inner.hover().map_err(map_error);
+
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] hover: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
+        result
     }
 
     /// Check if element is visible.
@@ -457,6 +539,18 @@ impl Element {
         options: Option<TypeTextOptions>,
     ) -> napi::Result<ActionResult> {
         let opts = options.unwrap_or_default();
+        let restore_focus = opts.restore_focus.unwrap_or(true);
+
+        // CRITICAL: Save focus state BEFORE activate_window() if restore is requested
+        // activate_window() steals focus, so we must save first
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] type_text: saving focus state BEFORE activate_window");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("type");
         }
@@ -469,15 +563,24 @@ impl Element {
 
         let try_focus_before = opts.try_focus_before.unwrap_or(true);
         let try_click_before = opts.try_click_before.unwrap_or(true);
+        // Pass restore_focus=false to platform layer since we handle it ourselves
         self.inner
-            .type_text_with_state_and_focus(
+            .type_text_with_state_and_focus_restore(
                 &text,
                 opts.use_clipboard.unwrap_or(false),
                 try_focus_before,
                 try_click_before,
+                false, // We handle focus restore ourselves since we saved BEFORE activate_window
             )
             .map_err(map_error)?;
 
+        // Restore focus state if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] type_text: restoring focus state after typing");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
         // Capture screenshots if requested
         let screenshots = capture_element_screenshots(
             &self.inner,
@@ -506,6 +609,17 @@ impl Element {
         options: Option<ActionOptions>,
     ) -> napi::Result<ActionResult> {
         let opts = options.unwrap_or_default();
+        let restore_focus = opts.restore_focus.unwrap_or(true);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] press_key: saving focus state BEFORE activate_window");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("key");
         }
@@ -524,6 +638,13 @@ impl Element {
             "pressKey",
         );
 
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] press_key: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
         Ok(ActionResult {
             success: true,
             window_screenshot_path: screenshots.window_path,
@@ -544,6 +665,17 @@ impl Element {
         options: Option<ActionOptions>,
     ) -> napi::Result<ActionResult> {
         let opts = options.unwrap_or_default();
+        let restore_focus = opts.restore_focus.unwrap_or(true);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] set_value: saving focus state BEFORE action");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("set_value");
         }
@@ -557,6 +689,13 @@ impl Element {
             "setValue",
         );
 
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] set_value: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
         Ok(ActionResult {
             success: true,
             window_screenshot_path: screenshots.window_path,
@@ -581,6 +720,17 @@ 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);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] invoke: saving focus state BEFORE action");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("invoke");
         }
@@ -594,6 +744,13 @@ impl Element {
             "invoke",
         );
 
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] invoke: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
         Ok(ActionResult {
             success: true,
             window_screenshot_path: screenshots.window_path,
@@ -616,6 +773,17 @@ impl Element {
         options: Option<ActionOptions>,
     ) -> napi::Result<ActionResult> {
         let opts = options.unwrap_or_default();
+        let restore_focus = opts.restore_focus.unwrap_or(true);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] scroll: saving focus state BEFORE action");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("scroll");
         }
@@ -629,6 +797,13 @@ impl Element {
             "scroll",
         );
 
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] scroll: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
         Ok(ActionResult {
             success: true,
             window_screenshot_path: screenshots.window_path,
@@ -893,10 +1068,30 @@ impl Element {
         options: Option<ActionOptions>,
     ) -> napi::Result<()> {
         let opts = options.unwrap_or_default();
+        let restore_focus = opts.restore_focus.unwrap_or(true);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] select_option: saving focus state BEFORE action");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("select_option");
         }
-        self.inner.select_option(&option_name).map_err(map_error)
+        let result = self.inner.select_option(&option_name).map_err(map_error);
+
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] select_option: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
+        result
     }
 
     /// Lists all available option strings from a dropdown or list box.
@@ -942,10 +1137,30 @@ impl Element {
     #[napi]
     pub fn set_selected(&self, state: bool, options: Option<ActionOptions>) -> napi::Result<()> {
         let opts = options.unwrap_or_default();
+        let restore_focus = opts.restore_focus.unwrap_or(true);
+
+        // FOCUS RESTORATION: Save focus state BEFORE any window operations
+        #[cfg(target_os = "windows")]
+        let saved_focus = if restore_focus {
+            tracing::debug!("[TS SDK] set_selected: saving focus state BEFORE action");
+            terminator::platforms::windows::save_focus_state()
+        } else {
+            None
+        };
+
         if opts.highlight_before_action.unwrap_or(false) {
             let _ = self.inner.highlight_before_action("set_selected");
         }
-        self.inner.set_selected(state).map_err(map_error)
+        let result = self.inner.set_selected(state).map_err(map_error);
+
+        // FOCUS RESTORATION: Restore focus state after action if we saved it
+        #[cfg(target_os = "windows")]
+        if let Some(state) = saved_focus {
+            tracing::debug!("[TS SDK] set_selected: restoring focus state after action");
+            terminator::platforms::windows::restore_focus_state(state);
+        }
+
+        result
     }
 
     /// Gets the current value from a range-based control like a slider or progress bar.

package/wrapper.js

@@ -255,7 +255,7 @@ async function enhancedExecuteBrowserScript(scriptOrFunction, processOrEnv, time
           }
           return String(result);
         }
-        return null;
+        return "undefined";
       })()
     `;
   } else if (typeof scriptOrFunction === "object" && scriptOrFunction.file) {

package/wrapper.ts

@@ -271,7 +271,7 @@ async function enhancedExecuteBrowserScript(
           }
           return String(result);
         }
-        return null;
+        return "undefined";
       })()
     `;
   } else if (