@mediar-ai/terminator 0.23.36 → 0.23.44

package/src/window_manager.rs

@@ -0,0 +1,341 @@
+//! Window manager bindings for Node.js
+
+use napi_derive::napi;
+use std::sync::Arc;
+
+#[cfg(target_os = "windows")]
+use terminator::WindowManager as RustWindowManager;
+
+/// Information about a window
+#[napi(object)]
+pub struct WindowInfo {
+    /// Window handle
+    pub hwnd: i64,
+    /// Process name (e.g., "notepad.exe")
+    pub process_name: String,
+    /// Process ID
+    pub process_id: u32,
+    /// Z-order position (0 = topmost)
+    pub z_order: u32,
+    /// Whether the window is minimized
+    pub is_minimized: bool,
+    /// Whether the window is maximized
+    pub is_maximized: bool,
+    /// Whether the window has WS_EX_TOPMOST style
+    pub is_always_on_top: bool,
+    /// Window title
+    pub title: String,
+}
+
+#[cfg(target_os = "windows")]
+impl From<terminator::WindowInfo> for WindowInfo {
+    fn from(info: terminator::WindowInfo) -> Self {
+        Self {
+            hwnd: info.hwnd as i64,
+            process_name: info.process_name,
+            process_id: info.process_id,
+            z_order: info.z_order,
+            is_minimized: info.is_minimized,
+            is_maximized: info.is_maximized,
+            is_always_on_top: info.is_always_on_top,
+            title: info.title,
+        }
+    }
+}
+
+/// Window manager for controlling window states
+///
+/// Provides functionality for:
+/// - Enumerating windows with Z-order tracking
+/// - Bringing windows to front (bypassing Windows focus-stealing prevention)
+/// - Minimizing/maximizing windows
+/// - Capturing and restoring window states for workflows
+#[napi]
+pub struct WindowManager {
+    #[cfg(target_os = "windows")]
+    inner: Arc<RustWindowManager>,
+}
+
+#[napi]
+impl Default for WindowManager {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[napi]
+impl WindowManager {
+    /// Create a new WindowManager instance
+    #[napi(constructor)]
+    pub fn new() -> Self {
+        Self {
+            #[cfg(target_os = "windows")]
+            inner: Arc::new(RustWindowManager::new()),
+        }
+    }
+
+    /// Update window cache with current window information
+    #[napi]
+    pub async fn update_window_cache(&self) -> napi::Result<()> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner.update_window_cache().await.map_err(|e| {
+                napi::Error::from_reason(format!("Failed to update window cache: {}", e))
+            })
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Get topmost window for a process by name
+    #[napi]
+    pub async fn get_topmost_window_for_process(
+        &self,
+        process: String,
+    ) -> napi::Result<Option<WindowInfo>> {
+        #[cfg(target_os = "windows")]
+        {
+            Ok(self
+                .inner
+                .get_topmost_window_for_process(&process)
+                .await
+                .map(WindowInfo::from))
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Get topmost window for a specific PID
+    #[napi]
+    pub async fn get_topmost_window_for_pid(&self, pid: u32) -> napi::Result<Option<WindowInfo>> {
+        #[cfg(target_os = "windows")]
+        {
+            Ok(self
+                .inner
+                .get_topmost_window_for_pid(pid)
+                .await
+                .map(WindowInfo::from))
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Get all visible always-on-top windows
+    #[napi]
+    pub async fn get_always_on_top_windows(&self) -> napi::Result<Vec<WindowInfo>> {
+        #[cfg(target_os = "windows")]
+        {
+            Ok(self
+                .inner
+                .get_always_on_top_windows()
+                .await
+                .into_iter()
+                .map(WindowInfo::from)
+                .collect())
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Minimize only always-on-top windows (excluding target)
+    /// Returns the number of windows minimized
+    #[napi]
+    pub async fn minimize_always_on_top_windows(&self, target_hwnd: i64) -> napi::Result<u32> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner
+                .minimize_always_on_top_windows(target_hwnd as isize)
+                .await
+                .map_err(|e| {
+                    napi::Error::from_reason(format!(
+                        "Failed to minimize always-on-top windows: {}",
+                        e
+                    ))
+                })
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Minimize all visible windows except the target
+    #[napi]
+    pub async fn minimize_all_except(&self, target_hwnd: i64) -> napi::Result<u32> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner
+                .minimize_all_except(target_hwnd as isize)
+                .await
+                .map_err(|e| napi::Error::from_reason(format!("Failed to minimize windows: {}", e)))
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Maximize window if not already maximized
+    /// Returns true if the window was maximized (wasn't already maximized)
+    #[napi]
+    pub async fn maximize_if_needed(&self, hwnd: i64) -> napi::Result<bool> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner
+                .maximize_if_needed(hwnd as isize)
+                .await
+                .map_err(|e| napi::Error::from_reason(format!("Failed to maximize window: {}", e)))
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Bring window to front using AttachThreadInput trick
+    ///
+    /// This uses AttachThreadInput to bypass Windows' focus-stealing prevention.
+    /// Returns true if the window is now in the foreground.
+    #[napi]
+    pub async fn bring_window_to_front(&self, hwnd: i64) -> napi::Result<bool> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner
+                .bring_window_to_front(hwnd as isize)
+                .await
+                .map_err(|e| {
+                    napi::Error::from_reason(format!("Failed to bring window to front: {}", e))
+                })
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Minimize window if not already minimized
+    /// Returns true if the window was minimized (wasn't already minimized)
+    #[napi]
+    pub async fn minimize_if_needed(&self, hwnd: i64) -> napi::Result<bool> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner
+                .minimize_if_needed(hwnd as isize)
+                .await
+                .map_err(|e| napi::Error::from_reason(format!("Failed to minimize window: {}", e)))
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Capture current state before workflow
+    #[napi]
+    pub async fn capture_initial_state(&self) -> napi::Result<()> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner.capture_initial_state().await.map_err(|e| {
+                napi::Error::from_reason(format!("Failed to capture initial state: {}", e))
+            })
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Restore windows that were minimized and target window to their original state
+    /// Returns the number of windows restored
+    #[napi]
+    pub async fn restore_all_windows(&self) -> napi::Result<u32> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner
+                .restore_all_windows()
+                .await
+                .map_err(|e| napi::Error::from_reason(format!("Failed to restore windows: {}", e)))
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Clear captured state
+    #[napi]
+    pub async fn clear_captured_state(&self) -> napi::Result<()> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner.clear_captured_state().await;
+            Ok(())
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Check if a process is a UWP/Modern app
+    #[napi]
+    pub async fn is_uwp_app(&self, pid: u32) -> napi::Result<bool> {
+        #[cfg(target_os = "windows")]
+        {
+            Ok(self.inner.is_uwp_app(pid).await)
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+
+    /// Track a window as the target for restoration
+    #[napi]
+    pub async fn set_target_window(&self, hwnd: i64) -> napi::Result<()> {
+        #[cfg(target_os = "windows")]
+        {
+            self.inner.set_target_window(hwnd as isize).await;
+            Ok(())
+        }
+        #[cfg(not(target_os = "windows"))]
+        {
+            Err(napi::Error::from_reason(
+                "WindowManager is only supported on Windows",
+            ))
+        }
+    }
+}

package/tests/cross-app-verification.test.js

@@ -0,0 +1,243 @@
+const { Desktop } = require("../index.js");
+
+/**
+ * Cross-Application Verification Test Suite
+ * Tests verification methods across multiple Windows built-in applications
+ * These apps are available on all Windows 10/11 computers
+ */
+
+const desktop = new Desktop();
+
+// Test configuration for each app
+const APP_TESTS = [
+  {
+    name: "Notepad",
+    launch: "notepad.exe",
+    existsSelector: "role:Document || role:Edit",
+    existsDescription: "text editor area",
+    menuBarSelector: "role:MenuBar",
+    notExistsSelector: "role:Window && name:Save As",
+    notExistsDescription: "Save As dialog",
+    required: true,
+  },
+  {
+    name: "Calculator",
+    launch: "calc",
+    existsSelector: "role:Button && name:Zero",
+    existsDescription: "Zero button",
+    menuBarSelector: null, // Calculator has no traditional menu bar
+    notExistsSelector: "role:Button && name:NonExistentCalcButton",
+    notExistsDescription: "non-existent button",
+    required: true,
+  },
+  {
+    name: "Google Chrome",
+    launch: "chrome",
+    existsSelector: "role:Document || role:Pane",
+    existsDescription: "browser content area",
+    menuBarSelector: null, // Chrome uses toolbar, not menu bar
+    notExistsSelector: "role:Window && name:Downloads Complete",
+    notExistsDescription: "Downloads Complete dialog",
+    required: false, // Chrome may not be installed
+  },
+  {
+    name: "Microsoft Edge",
+    launch: "msedge",
+    existsSelector: "role:Document || role:Pane",
+    existsDescription: "browser content area",
+    menuBarSelector: null, // Edge uses toolbar, not menu bar
+    notExistsSelector: "role:Window && name:Downloads Complete",
+    notExistsDescription: "Downloads Complete dialog",
+    required: false, // Edge can fail if already open or slow to launch
+  },
+  {
+    name: "File Explorer",
+    launch: "explorer",
+    existsSelector: "role:Pane",
+    existsDescription: "content pane",
+    menuBarSelector: null, // Modern Explorer uses ribbon
+    notExistsSelector: "role:Window && name:Confirm Delete",
+    notExistsDescription: "Confirm Delete dialog",
+    required: false, // Explorer has complex window structure, can be flaky
+  },
+];
+
+async function closeApp(appElement, appName) {
+  try {
+    await appElement.pressKey("Alt+F4");
+    await new Promise(r => setTimeout(r, 500));
+
+    // Handle save dialogs if they appear
+    try {
+      const dontSave = await appElement.locator("role:Button && name:Don\\'t Save").first(1000);
+      await dontSave.click();
+    } catch {
+      // Try "No" button for some dialogs
+      try {
+        const noBtn = await appElement.locator("role:Button && name:No").first(500);
+        await noBtn.click();
+      } catch {
+        // No dialog, that's fine
+      }
+    }
+  } catch (e) {
+    console.log(`    Note: Could not close ${appName} cleanly: ${e.message.substring(0, 50)}`);
+  }
+}
+
+async function testApp(config) {
+  console.log(`\n  ═══ ${config.name} ═══`);
+
+  let appElement = null;
+  let passed = 0;
+  let failed = 0;
+  let skipped = false;
+
+  try {
+    // Launch app
+    console.log(`  Launching ${config.name}...`);
+    try {
+      appElement = await desktop.openApplication(config.launch);
+      await new Promise(r => setTimeout(r, 1500)); // Wait for app to stabilize
+    } catch (launchError) {
+      if (!config.required) {
+        console.log(`  ⏭️  Skipping ${config.name} (not installed or failed to launch)`);
+        return { passed: 0, failed: 0, skipped: true, name: config.name };
+      }
+      throw launchError;
+    }
+
+    // Test 1: verifyElementExists for known element
+    console.log(`  Test 1: verifyElementExists (${config.existsDescription})`);
+    try {
+      const found = await desktop.verifyElementExists(
+        appElement,
+        config.existsSelector,
+        5000
+      );
+      if (found) {
+        console.log(`    ✅ Found ${config.existsDescription}: role=${found.role()}`);
+        passed++;
+      } else {
+        console.log(`    ❌ Expected to find ${config.existsDescription}`);
+        failed++;
+      }
+    } catch (e) {
+      console.log(`    ❌ Error: ${e.message.substring(0, 80)}`);
+      failed++;
+    }
+
+    // Test 2: verifyElementExists for MenuBar (if applicable)
+    if (config.menuBarSelector) {
+      console.log(`  Test 2: verifyElementExists (MenuBar)`);
+      try {
+        const menuBar = await desktop.verifyElementExists(
+          appElement,
+          config.menuBarSelector,
+          3000
+        );
+        if (menuBar) {
+          console.log(`    ✅ Found MenuBar: role=${menuBar.role()}`);
+          passed++;
+        }
+      } catch (e) {
+        console.log(`    ❌ MenuBar not found: ${e.message.substring(0, 60)}`);
+        failed++;
+      }
+    }
+
+    // Test 3: verifyElementNotExists for non-existent element
+    console.log(`  Test 3: verifyElementNotExists (${config.notExistsDescription})`);
+    try {
+      await desktop.verifyElementNotExists(
+        appElement,
+        config.notExistsSelector,
+        2000
+      );
+      console.log(`    ✅ Correctly confirmed ${config.notExistsDescription} does not exist`);
+      passed++;
+    } catch (e) {
+      if (e.message.includes("VERIFICATION_FAILED")) {
+        console.log(`    ❌ Element unexpectedly exists`);
+      } else {
+        console.log(`    ❌ Error: ${e.message.substring(0, 60)}`);
+      }
+      failed++;
+    }
+
+    // Test 4: Scoped locator search
+    console.log(`  Test 4: Scoped locator within app window`);
+    try {
+      const element = await appElement.locator(config.existsSelector).first(3000);
+      if (element) {
+        console.log(`    ✅ Scoped locator found element: role=${element.role()}`);
+        passed++;
+      }
+    } catch (e) {
+      console.log(`    ❌ Scoped locator failed: ${e.message.substring(0, 60)}`);
+      failed++;
+    }
+
+  } finally {
+    // Cleanup
+    if (appElement) {
+      console.log(`  Closing ${config.name}...`);
+      await closeApp(appElement, config.name);
+    }
+  }
+
+  return { passed, failed, name: config.name };
+}
+
+async function runTests() {
+  console.log("═══════════════════════════════════════════════════════════════════");
+  console.log("Cross-Application Verification Test Suite");
+  console.log("Tests SDK verification methods across Windows built-in applications");
+  console.log("═══════════════════════════════════════════════════════════════════");
+
+  let totalPassed = 0;
+  let totalFailed = 0;
+  const results = [];
+
+  for (const config of APP_TESTS) {
+    try {
+      const result = await testApp(config);
+      totalPassed += result.passed;
+      totalFailed += result.failed;
+      results.push(result);
+    } catch (error) {
+      console.log(`\n  ❌ ${config.name} test suite crashed: ${error.message}`);
+      results.push({ name: config.name, passed: 0, failed: 1, error: error.message });
+      totalFailed++;
+    }
+
+    // Brief pause between apps
+    await new Promise(r => setTimeout(r, 1000));
+  }
+
+  console.log("\n═══════════════════════════════════════════════════════════════════");
+  console.log("Results Summary:");
+  console.log("═══════════════════════════════════════════════════════════════════");
+
+  let totalSkipped = 0;
+  for (const result of results) {
+    if (result.skipped) {
+      console.log(`  ⏭️  ${result.name}: SKIPPED (not installed)`);
+      totalSkipped++;
+    } else {
+      const status = result.failed === 0 ? "✅" : "❌";
+      console.log(`  ${status} ${result.name}: ${result.passed} passed, ${result.failed} failed`);
+    }
+  }
+
+  console.log("───────────────────────────────────────────────────────────────────");
+  console.log(`  TOTAL: ${totalPassed} passed, ${totalFailed} failed, ${totalSkipped} skipped`);
+  console.log("═══════════════════════════════════════════════════════════════════");
+
+  process.exit(totalFailed > 0 ? 1 : 0);
+}
+
+runTests().catch(error => {
+  console.error("Test suite crashed:", error);
+  process.exit(1);
+});