@mediar-ai/terminator 0.20.6

package/src/locator.rs

@@ -0,0 +1,172 @@
+use napi_derive::napi;
+use terminator::locator::WaitCondition as TerminatorWaitCondition;
+use terminator::Locator as TerminatorLocator;
+
+use crate::map_error;
+use crate::Element;
+use crate::Selector;
+use napi::bindgen_prelude::Either;
+
+/// Locator for finding UI elements by selector.
+#[napi(js_name = "Locator")]
+pub struct Locator {
+    inner: TerminatorLocator,
+}
+
+impl std::fmt::Display for Locator {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "Locator({})", self.inner.selector_string())
+    }
+}
+
+impl From<TerminatorLocator> for Locator {
+    fn from(l: TerminatorLocator) -> Self {
+        Locator { inner: l }
+    }
+}
+
+#[napi]
+impl Locator {
+    /// (async) Get the first matching element.
+    ///
+    /// @param {number} timeoutMs - Timeout in milliseconds (required).
+    /// @returns {Promise<Element>} The first matching element.
+    #[napi]
+    pub async fn first(&self, timeout_ms: f64) -> napi::Result<Element> {
+        use std::time::Duration;
+        let timeout = Duration::from_millis(timeout_ms as u64);
+        self.inner
+            .first(Some(timeout))
+            .await
+            .map(Element::from)
+            .map_err(map_error)
+    }
+
+    /// (async) Get all matching elements.
+    ///
+    /// @param {number} timeoutMs - Timeout in milliseconds (required).
+    /// @param {number} [depth] - Maximum depth to search.
+    /// @returns {Promise<Array<Element>>} List of matching elements.
+    #[napi]
+    pub async fn all(&self, timeout_ms: f64, depth: Option<u32>) -> napi::Result<Vec<Element>> {
+        use std::time::Duration;
+        let timeout = Duration::from_millis(timeout_ms as u64);
+        let depth = depth.map(|d| d as usize);
+        self.inner
+            .all(Some(timeout), depth)
+            .await
+            .map(|els| els.into_iter().map(Element::from).collect())
+            .map_err(map_error)
+    }
+
+    /// Set a default timeout for this locator.
+    ///
+    /// @param {number} timeoutMs - Timeout in milliseconds.
+    /// @returns {Locator} A new locator with the specified timeout.
+    #[napi]
+    pub fn timeout(&self, timeout_ms: f64) -> Locator {
+        let loc = self
+            .inner
+            .clone()
+            .set_default_timeout(std::time::Duration::from_millis(timeout_ms as u64));
+        Locator::from(loc)
+    }
+
+    /// Set the root element for this locator.
+    ///
+    /// @param {Element} element - The root element.
+    /// @returns {Locator} A new locator with the specified root element.
+    #[napi]
+    pub fn within(&self, element: &Element) -> Locator {
+        let loc = self.inner.clone().within(element.inner.clone());
+        Locator::from(loc)
+    }
+
+    /// Chain another selector.
+    /// Accepts either a selector string or a Selector object.
+    ///
+    /// @param {string | Selector} selector - The selector.
+    /// @returns {Locator} A new locator with the chained selector.
+    #[napi]
+    pub fn locator(
+        &self,
+        #[napi(ts_arg_type = "string | Selector")] selector: Either<String, &Selector>,
+    ) -> napi::Result<Locator> {
+        use napi::bindgen_prelude::Either::*;
+        let sel_rust: terminator::selector::Selector = match selector {
+            A(sel_str) => sel_str.as_str().into(),
+            B(sel_obj) => sel_obj.inner.clone(),
+        };
+        let loc = self.inner.clone().locator(sel_rust);
+        Ok(Locator::from(loc))
+    }
+
+    /// (async) Validate element existence without throwing an error.
+    ///
+    /// @param {number} timeoutMs - Timeout in milliseconds (required).
+    /// @returns {Promise<ValidationResult>} Validation result with exists flag and optional element.
+    #[napi]
+    pub async fn validate(&self, timeout_ms: f64) -> napi::Result<ValidationResult> {
+        use std::time::Duration;
+        let timeout = Duration::from_millis(timeout_ms as u64);
+        match self.inner.validate(Some(timeout)).await {
+            Ok(Some(element)) => Ok(ValidationResult {
+                exists: true,
+                element: Some(Element::from(element)),
+                error: None,
+            }),
+            Ok(None) => Ok(ValidationResult {
+                exists: false,
+                element: None,
+                error: None,
+            }),
+            Err(e) => Ok(ValidationResult {
+                exists: false,
+                element: None,
+                error: Some(e.to_string()),
+            }),
+        }
+    }
+
+    /// (async) Wait for an element to meet a specific condition.
+    ///
+    /// @param {string} condition - Condition to wait for: 'exists', 'visible', 'enabled', 'focused'
+    /// @param {number} timeoutMs - Timeout in milliseconds (required).
+    /// @returns {Promise<Element>} The element when condition is met.
+    #[napi]
+    pub async fn wait_for(&self, condition: String, timeout_ms: f64) -> napi::Result<Element> {
+        use std::time::Duration;
+        let wait_condition = parse_condition(&condition)?;
+        let timeout = Duration::from_millis(timeout_ms as u64);
+
+        self.inner
+            .wait_for(wait_condition, Some(timeout))
+            .await
+            .map(Element::from)
+            .map_err(map_error)
+    }
+}
+
+/// Result of element validation
+#[napi(object)]
+pub struct ValidationResult {
+    /// Whether the element exists
+    pub exists: bool,
+    /// The element if found
+    pub element: Option<Element>,
+    /// Error message if validation failed (not element not found, but actual error)
+    pub error: Option<String>,
+}
+/// Convert string condition to WaitCondition enum
+fn parse_condition(condition: &str) -> napi::Result<TerminatorWaitCondition> {
+    match condition.to_lowercase().as_str() {
+        "exists" => Ok(TerminatorWaitCondition::Exists),
+        "visible" => Ok(TerminatorWaitCondition::Visible),
+        "enabled" => Ok(TerminatorWaitCondition::Enabled),
+        "focused" => Ok(TerminatorWaitCondition::Focused),
+        _ => Err(napi::Error::new(
+            napi::Status::InvalidArg,
+            format!("Invalid condition '{condition}'. Valid: exists, visible, enabled, focused"),
+        )),
+    }
+}

package/src/selector.rs

@@ -0,0 +1,139 @@
+use napi::bindgen_prelude::FromNapiValue;
+use napi_derive::napi;
+use std::collections::BTreeMap;
+use terminator::selector::Selector as TerminatorSelector;
+
+/// Selector for locating UI elements. Provides a typed alternative to the string based selector API.
+#[napi(js_name = "Selector")]
+pub struct Selector {
+    pub(crate) inner: TerminatorSelector,
+}
+
+impl std::fmt::Display for Selector {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{:?}", self.inner)
+    }
+}
+
+impl From<TerminatorSelector> for Selector {
+    fn from(sel: TerminatorSelector) -> Self {
+        Selector { inner: sel }
+    }
+}
+
+impl From<&Selector> for TerminatorSelector {
+    fn from(sel: &Selector) -> Self {
+        sel.inner.clone()
+    }
+}
+
+impl FromNapiValue for Selector {
+    unsafe fn from_napi_value(
+        env: napi::sys::napi_env,
+        napi_val: napi::sys::napi_value,
+    ) -> napi::Result<Self> {
+        let mut result = std::ptr::null_mut();
+        let status = napi::sys::napi_get_value_external(env, napi_val, &mut result);
+        if status != napi::sys::Status::napi_ok {
+            return Err(napi::Error::new(
+                napi::Status::InvalidArg,
+                "Failed to get external value for Selector".to_string(),
+            ));
+        }
+        Ok(std::ptr::read(result as *const Selector))
+    }
+}
+
+#[napi]
+impl Selector {
+    /// Create a selector that matches elements by their accessibility `name`.
+    #[napi(factory)]
+    pub fn name(name: String) -> Self {
+        Selector::from(TerminatorSelector::Name(name))
+    }
+
+    /// Create a selector that matches elements by role (and optionally name).
+    #[napi(factory)]
+    pub fn role(role: String, name: Option<String>) -> Self {
+        Selector::from(TerminatorSelector::Role { role, name })
+    }
+
+    /// Create a selector that matches elements by accessibility `id`.
+    #[napi(factory, js_name = "id")]
+    pub fn id_factory(id: String) -> Self {
+        Selector::from(TerminatorSelector::Id(id))
+    }
+
+    /// Create a selector that matches elements by the text they display.
+    #[napi(factory)]
+    pub fn text(text: String) -> Self {
+        Selector::from(TerminatorSelector::Text(text))
+    }
+
+    /// Create a selector from an XPath-like path string.
+    #[napi(factory)]
+    pub fn path(path: String) -> Self {
+        Selector::from(TerminatorSelector::Path(path))
+    }
+
+    /// Create a selector that matches elements by a native automation id (e.g., AutomationID on Windows).
+    #[napi(factory, js_name = "nativeId")]
+    pub fn native_id(id: String) -> Self {
+        Selector::from(TerminatorSelector::NativeId(id))
+    }
+
+    /// Create a selector that matches elements by their class name.
+    #[napi(factory, js_name = "className")]
+    pub fn class_name(name: String) -> Self {
+        Selector::from(TerminatorSelector::ClassName(name))
+    }
+
+    /// Create a selector from an arbitrary attribute map.
+    #[napi(factory)]
+    pub fn attributes(attributes: std::collections::HashMap<String, String>) -> Self {
+        let map: BTreeMap<String, String> = attributes.into_iter().collect();
+        Selector::from(TerminatorSelector::Attributes(map))
+    }
+
+    /// Chain another selector onto this selector.
+    #[napi]
+    pub fn chain(&self, other: &Selector) -> Selector {
+        Selector::from(TerminatorSelector::Chain(vec![
+            self.inner.clone(),
+            other.inner.clone(),
+        ]))
+    }
+
+    /// Filter by visibility.
+    #[napi]
+    pub fn visible(&self, is_visible: bool) -> Selector {
+        Selector::from(TerminatorSelector::Chain(vec![
+            self.inner.clone(),
+            TerminatorSelector::Visible(is_visible),
+        ]))
+    }
+
+    /// Create a selector that selects the nth element from matches.
+    /// Positive values are 0-based from the start (0 = first, 1 = second).
+    /// Negative values are from the end (-1 = last, -2 = second-to-last).
+    #[napi(factory)]
+    pub fn nth(index: i32) -> Self {
+        Selector::from(TerminatorSelector::Nth(index))
+    }
+
+    /// Create a selector that matches elements having at least one descendant matching the inner selector.
+    /// This is similar to Playwright's :has() pseudo-class.
+    #[napi(factory)]
+    pub fn has(inner_selector: &Selector) -> Self {
+        Selector::from(TerminatorSelector::Has(Box::new(
+            inner_selector.inner.clone(),
+        )))
+    }
+
+    /// Create a selector that navigates to the parent element.
+    /// This is similar to Playwright's .. syntax.
+    #[napi(factory)]
+    pub fn parent() -> Self {
+        Selector::from(TerminatorSelector::Parent)
+    }
+}

package/src/types.rs

@@ -0,0 +1,308 @@
+use napi_derive::napi;
+use std::collections::HashMap;
+
+#[napi(object, js_name = "Bounds")]
+pub struct Bounds {
+    pub x: f64,
+    pub y: f64,
+    pub width: f64,
+    pub height: f64,
+}
+
+#[napi(object, js_name = "Coordinates")]
+pub struct Coordinates {
+    pub x: f64,
+    pub y: f64,
+}
+
+#[napi(object, js_name = "ClickResult")]
+pub struct ClickResult {
+    pub method: String,
+    pub coordinates: Option<Coordinates>,
+    pub details: String,
+}
+
+#[napi(object, js_name = "CommandOutput")]
+pub struct CommandOutput {
+    pub exit_status: Option<i32>,
+    pub stdout: String,
+    pub stderr: String,
+}
+
+#[napi(object)]
+pub struct Monitor {
+    pub id: String,
+    pub name: String,
+    pub is_primary: bool,
+    pub width: u32,
+    pub height: u32,
+    pub x: i32,
+    pub y: i32,
+    pub scale_factor: f64,
+}
+
+#[napi(object)]
+pub struct MonitorScreenshotPair {
+    pub monitor: Monitor,
+    pub screenshot: ScreenshotResult,
+}
+
+#[napi(object)]
+pub struct ScreenshotResult {
+    pub width: u32,
+    pub height: u32,
+    pub image_data: Vec<u8>,
+    pub monitor: Option<Monitor>,
+}
+
+#[napi(object, js_name = "UIElementAttributes")]
+pub struct UIElementAttributes {
+    pub role: String,
+    pub name: Option<String>,
+    pub label: Option<String>,
+    pub value: Option<String>,
+    pub description: Option<String>,
+    pub properties: HashMap<String, Option<String>>,
+    pub is_keyboard_focusable: Option<bool>,
+    pub bounds: Option<Bounds>,
+}
+
+#[napi(object, js_name = "UINode")]
+pub struct UINode {
+    pub id: Option<String>,
+    pub attributes: UIElementAttributes,
+    pub children: Vec<UINode>,
+}
+
+#[napi(string_enum)]
+pub enum PropertyLoadingMode {
+    /// Only load essential properties (role + name) - fastest
+    Fast,
+    /// Load all properties for complete element data - slower but comprehensive
+    Complete,
+    /// Load specific properties based on element type - balanced approach
+    Smart,
+}
+
+#[napi(object, js_name = "TreeBuildConfig")]
+pub struct TreeBuildConfig {
+    /// Property loading strategy
+    pub property_mode: PropertyLoadingMode,
+    /// Optional timeout per operation in milliseconds
+    pub timeout_per_operation_ms: Option<i64>,
+    /// Optional yield frequency for responsiveness
+    pub yield_every_n_elements: Option<i32>,
+    /// Optional batch size for processing elements
+    pub batch_size: Option<i32>,
+}
+
+impl From<(f64, f64, f64, f64)> for Bounds {
+    fn from(t: (f64, f64, f64, f64)) -> Self {
+        Bounds {
+            x: t.0,
+            y: t.1,
+            width: t.2,
+            height: t.3,
+        }
+    }
+}
+
+impl From<(f64, f64)> for Coordinates {
+    fn from(t: (f64, f64)) -> Self {
+        Coordinates { x: t.0, y: t.1 }
+    }
+}
+
+impl From<terminator::ClickResult> for ClickResult {
+    fn from(r: terminator::ClickResult) -> Self {
+        ClickResult {
+            method: r.method,
+            coordinates: r.coordinates.map(Coordinates::from),
+            details: r.details,
+        }
+    }
+}
+
+impl From<terminator::Monitor> for Monitor {
+    fn from(m: terminator::Monitor) -> Self {
+        Monitor {
+            id: m.id,
+            name: m.name,
+            is_primary: m.is_primary,
+            width: m.width,
+            height: m.height,
+            x: m.x,
+            y: m.y,
+            scale_factor: m.scale_factor,
+        }
+    }
+}
+
+impl From<terminator::UINode> for UINode {
+    fn from(node: terminator::UINode) -> Self {
+        UINode {
+            id: node.id,
+            attributes: UIElementAttributes::from(node.attributes),
+            children: node.children.into_iter().map(UINode::from).collect(),
+        }
+    }
+}
+
+impl From<terminator::UIElementAttributes> for UIElementAttributes {
+    fn from(attrs: terminator::UIElementAttributes) -> Self {
+        // Convert HashMap<String, Option<serde_json::Value>> to HashMap<String, Option<String>>
+        let properties = attrs
+            .properties
+            .into_iter()
+            .map(|(k, v)| (k, v.map(|val| val.to_string())))
+            .collect();
+
+        UIElementAttributes {
+            role: attrs.role,
+            name: attrs.name,
+            label: attrs.label,
+            value: attrs.value,
+            description: attrs.description,
+            properties,
+            is_keyboard_focusable: attrs.is_keyboard_focusable,
+            bounds: attrs.bounds.map(|(x, y, width, height)| Bounds {
+                x,
+                y,
+                width,
+                height,
+            }),
+        }
+    }
+}
+
+#[napi(string_enum)]
+pub enum TextPosition {
+    Top,
+    TopRight,
+    Right,
+    BottomRight,
+    Bottom,
+    BottomLeft,
+    Left,
+    TopLeft,
+    Inside,
+}
+
+#[napi(object)]
+pub struct FontStyle {
+    pub size: u32,
+    pub bold: bool,
+    pub color: u32,
+}
+
+#[napi]
+pub struct HighlightHandle {
+    inner: Option<terminator::HighlightHandle>,
+}
+
+#[napi]
+impl HighlightHandle {
+    #[napi]
+    pub fn close(&mut self) {
+        if let Some(handle) = self.inner.take() {
+            handle.close();
+        }
+    }
+}
+
+impl HighlightHandle {
+    pub fn new(handle: terminator::HighlightHandle) -> Self {
+        Self {
+            inner: Some(handle),
+        }
+    }
+
+    pub fn new_dummy() -> Self {
+        Self { inner: None }
+    }
+}
+
+impl From<TextPosition> for terminator::TextPosition {
+    fn from(pos: TextPosition) -> Self {
+        match pos {
+            TextPosition::Top => terminator::TextPosition::Top,
+            TextPosition::TopRight => terminator::TextPosition::TopRight,
+            TextPosition::Right => terminator::TextPosition::Right,
+            TextPosition::BottomRight => terminator::TextPosition::BottomRight,
+            TextPosition::Bottom => terminator::TextPosition::Bottom,
+            TextPosition::BottomLeft => terminator::TextPosition::BottomLeft,
+            TextPosition::Left => terminator::TextPosition::Left,
+            TextPosition::TopLeft => terminator::TextPosition::TopLeft,
+            TextPosition::Inside => terminator::TextPosition::Inside,
+        }
+    }
+}
+
+impl From<FontStyle> for terminator::FontStyle {
+    fn from(style: FontStyle) -> Self {
+        terminator::FontStyle {
+            size: style.size,
+            bold: style.bold,
+            color: style.color,
+        }
+    }
+}
+
+impl Default for FontStyle {
+    fn default() -> Self {
+        Self {
+            size: 12,
+            bold: false,
+            color: 0x000000,
+        }
+    }
+}
+
+impl From<TreeBuildConfig> for terminator::platforms::TreeBuildConfig {
+    fn from(config: TreeBuildConfig) -> Self {
+        terminator::platforms::TreeBuildConfig {
+            property_mode: match config.property_mode {
+                PropertyLoadingMode::Fast => terminator::platforms::PropertyLoadingMode::Fast,
+                PropertyLoadingMode::Complete => {
+                    terminator::platforms::PropertyLoadingMode::Complete
+                }
+                PropertyLoadingMode::Smart => terminator::platforms::PropertyLoadingMode::Smart,
+            },
+            timeout_per_operation_ms: config.timeout_per_operation_ms.map(|x| x as u64),
+            yield_every_n_elements: config.yield_every_n_elements.map(|x| x as usize),
+            batch_size: config.batch_size.map(|x| x as usize),
+            max_depth: None, // Not exposed in nodejs bindings yet
+        }
+    }
+}
+
+/// Convert SerializableUIElement to UINode
+pub(crate) fn serializable_to_ui_node(elem: &terminator::SerializableUIElement) -> UINode {
+    let attrs = UIElementAttributes {
+        role: elem.role.clone(),
+        name: elem.name.clone(),
+        label: elem.label.clone(),
+        value: elem.value.clone(),
+        description: elem.description.clone(),
+        properties: HashMap::new(), // SerializableUIElement doesn't have properties field
+        is_keyboard_focusable: elem.is_keyboard_focusable,
+        bounds: elem.bounds.map(|(x, y, w, h)| Bounds {
+            x,
+            y,
+            width: w,
+            height: h,
+        }),
+    };
+
+    let children = elem
+        .children
+        .as_ref()
+        .map(|children| children.iter().map(serializable_to_ui_node).collect())
+        .unwrap_or_default();
+
+    UINode {
+        id: elem.id.clone(),
+        attributes: attrs,
+        children,
+    }
+}

package/sync-version.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Read the workspace Cargo.toml
+const workspaceCargoPath = path.join(__dirname, '../../Cargo.toml');
+const cargoContent = fs.readFileSync(workspaceCargoPath, 'utf8');
+
+// Extract version from Cargo.toml
+const versionMatch = cargoContent.match(/^version\s*=\s*"([^"]+)"/m);
+if (!versionMatch) {
+    console.error('Could not find version in workspace Cargo.toml');
+    process.exit(1);
+}
+
+const version = versionMatch[1];
+console.log(`Found version: ${version}`);
+
+// Read package.json
+const packagePath = path.join(__dirname, 'package.json');
+const packageContent = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+
+// Update version and optionalDependencies
+packageContent.version = version;
+
+// Update optionalDependencies to use the same version
+if (packageContent.optionalDependencies) {
+    for (const dep in packageContent.optionalDependencies) {
+        if (dep.startsWith('@mediar-ai/terminator-')) {
+            packageContent.optionalDependencies[dep] = version;
+        }
+    }
+}
+
+// Write back to package.json
+fs.writeFileSync(packagePath, JSON.stringify(packageContent, null, 2) + '\n');
+
+console.log(`Updated package.json version to: ${version}`);
+
+// Also update platform packages
+const npmDir = path.join(__dirname, 'npm');
+if (fs.existsSync(npmDir)) {
+    const platforms = fs.readdirSync(npmDir);
+    for (const platform of platforms) {
+        const platformPath = path.join(npmDir, platform);
+        const platformPackagePath = path.join(platformPath, 'package.json');
+        
+        if (fs.existsSync(platformPackagePath) && fs.statSync(platformPath).isDirectory()) {
+            try {
+                const platformPackage = JSON.parse(fs.readFileSync(platformPackagePath, 'utf8'));
+                platformPackage.version = version;
+                fs.writeFileSync(platformPackagePath, JSON.stringify(platformPackage, null, 2) + '\n');
+                console.log(`Updated ${platform} package version to: ${version}`);
+            } catch (error) {
+                console.warn(`Failed to update ${platform} package:`, error.message);
+            }
+        }
+    }
+}