@pheem49/mint 1.14.0 → 1.15.0

package/crates/mint-core/src/browser/evidence.rs

@@ -0,0 +1,260 @@
+//! Coordinate input is authorized by target-local screenshot evidence, not a
+//! whole-page hash. Backend node IDs survive reads but not node replacement.
+use super::{cdp::cdp_call_raw, session::evaluate};
+use crate::MintConfig;
+use base64::Engine;
+use image::RgbaImage;
+use serde_json::{Value, json};
+use std::time::{Duration, Instant};
+
+pub(super) struct ScreenshotEvidence {
+    tab: String,
+    captured: Instant,
+    marker: Value,
+    image: RgbaImage,
+    snapshot_before: Value,
+    snapshot_after: Value,
+}
+
+async fn marker(config: &MintConfig) -> Result<Value, String> {
+    evaluate(config,"[location.href,globalThis.__mintScreenshotDocument ||= (crypto.randomUUID?.() || String(performance.timeOrigin)+Math.random()),scrollX,scrollY,innerWidth,innerHeight,devicePixelRatio]".into()).await
+}
+
+async fn snapshot(config: &MintConfig) -> Result<Value, String> {
+    Ok(cdp_call_raw(config,"DOMSnapshot.captureSnapshot",json!({"computedStyles":["pointer-events"],"includePaintOrder":true,"includeDOMRects":true})).await?["result"].clone())
+}
+
+pub(super) async fn capture(
+    config: &MintConfig,
+    tab: &str,
+) -> Result<(String, ScreenshotEvidence), String> {
+    capture_at(config, tab, None).await
+}
+
+/// At initial capture the coordinate is unknown. Retain both layout epochs so
+/// validation can check the eventual target without requiring distant DOM to
+/// remain unchanged. A coordinate-aware recapture retries target movement once.
+async fn capture_at(
+    config: &MintConfig,
+    tab: &str,
+    coordinate: Option<(f64, f64)>,
+) -> Result<(String, ScreenshotEvidence), String> {
+    // Hide only Mint's two cosmetic surfaces, including their shadows. Restore
+    // the stylesheet even if capture fails; never hide website content.
+    let token = format!("mint-evidence-{}", uuid::Uuid::new_v4());
+    evaluate(config,format!("(() => {{const s=document.createElement('style'); s.id={}; s.textContent='#mint-cursor-overlay,#mint-browser-aura{{display:none!important}}';document.documentElement.appendChild(s);return true;}})()",json!(token))).await?;
+    let result = async {
+        for _ in 0..2 {
+            let before_marker = marker(config).await?;
+            let before = snapshot(config).await?;
+            let captured = Instant::now();
+            let data = super::screenshot(config).await?;
+            let after = snapshot(config).await?;
+            if before_marker != marker(config).await? {
+                continue;
+            }
+            let bytes = base64::engine::general_purpose::STANDARD
+                .decode(&data)
+                .map_err(|e| e.to_string())?;
+            let image = image::load_from_memory(&bytes)
+                .map_err(|e| e.to_string())?
+                .to_rgba8();
+            let evidence = ScreenshotEvidence {
+                tab: tab.into(),
+                captured,
+                marker: before_marker,
+                image,
+                snapshot_before: before,
+                snapshot_after: after,
+            };
+            if coordinate.is_some_and(|(x, y)| target(&evidence, x, y).is_err()) {
+                continue;
+            }
+            return Ok((data, evidence));
+        }
+        Err("screenshot_stale: target or viewport changed during capture; capture again".into())
+    }
+    .await;
+    let _ = evaluate(
+        config,
+        format!("document.getElementById({})?.remove()", json!(token)),
+    )
+    .await;
+    result
+}
+
+#[derive(Debug, PartialEq)]
+struct Target {
+    backend: i64,
+    bounds: Value,
+}
+
+fn ancestor(nodes: &Value, ancestor: usize, mut child: usize) -> bool {
+    loop {
+        if ancestor == child {
+            return true;
+        }
+        let Some(parent) = nodes["parentIndex"][child].as_i64().filter(|p| *p >= 0) else {
+            return false;
+        };
+        child = parent as usize;
+    }
+}
+
+fn target(evidence: &ScreenshotEvidence, x: f64, y: f64) -> Result<Target, String> {
+    let before = target_in_snapshot(&evidence.snapshot_before, &evidence.marker, x, y)?;
+    let after = target_in_snapshot(&evidence.snapshot_after, &evidence.marker, x, y)?;
+    if before != after {
+        return Err("screenshot_stale: target changed around image capture".into());
+    }
+    Ok(before)
+}
+
+fn target_in_snapshot(snapshot: &Value, marker: &Value, x: f64, y: f64) -> Result<Target, String> {
+    let stale = || {
+        "screenshot_stale: ambiguous coordinate target; capture again or use an element".to_string()
+    };
+    let document = &snapshot["documents"][0];
+    let nodes = &document["nodes"];
+    let layout = &document["layout"];
+    let indices = layout["nodeIndex"].as_array().ok_or_else(stale)?;
+    let sx = marker[2].as_f64().ok_or_else(stale)?;
+    let sy = marker[3].as_f64().ok_or_else(stale)?;
+    let mut candidates = Vec::new();
+    for (i, index) in indices.iter().enumerate() {
+        let Some(node) = index.as_u64().map(|n| n as usize) else {
+            continue;
+        };
+        if nodes["nodeType"][node] != 1 {
+            continue;
+        }
+        let b = &layout["bounds"][i];
+        let Some(rect) = b.as_array().filter(|r| r.len() == 4) else {
+            continue;
+        };
+        let r: Vec<f64> = rect.iter().filter_map(Value::as_f64).collect();
+        if r.len() != 4
+            || x + sx < r[0]
+            || y + sy < r[1]
+            || x + sx >= r[0] + r[2]
+            || y + sy >= r[1] + r[3]
+        {
+            continue;
+        }
+        let style = layout["styles"][i][0].as_u64().map(|v| v as usize);
+        if style.is_some_and(|v| snapshot["strings"][v] == "none") {
+            continue;
+        }
+        let paint = layout["paintOrders"][i].as_i64().ok_or_else(stale)?;
+        candidates.push((paint, node, i));
+    }
+    let top = candidates.iter().map(|v| v.0).max().ok_or_else(stale)?;
+    let mut chosen: Option<(usize, usize)> = None;
+    for (_, node, i) in candidates.into_iter().filter(|v| v.0 == top) {
+        if let Some((previous, _)) = chosen {
+            if ancestor(nodes, node, previous) {
+                continue;
+            }
+            if !ancestor(nodes, previous, node) {
+                return Err(stale());
+            }
+        }
+        chosen = Some((node, i));
+    }
+    let (node, i) = chosen.ok_or_else(stale)?;
+    Ok(Target {
+        backend: nodes["backendNodeId"][node].as_i64().ok_or_else(stale)?,
+        bounds: layout["bounds"][i].clone(),
+    })
+}
+
+fn pixels_match(old: &ScreenshotEvidence, new: &ScreenshotEvidence, x: f64, y: f64) -> bool {
+    if old.image.dimensions() != new.image.dimensions() {
+        return false;
+    }
+    let scale_x = old.image.width() as f64 / old.marker[4].as_f64().unwrap_or(1.0);
+    let scale_y = old.image.height() as f64 / old.marker[5].as_f64().unwrap_or(1.0);
+    let cx = (x * scale_x).round() as i64;
+    let cy = (y * scale_y).round() as i64;
+    for py in (cy - 32).max(0)..(cy + 32).min(old.image.height() as i64) {
+        for px in (cx - 32).max(0)..(cx + 32).min(old.image.width() as i64) {
+            if old.image.get_pixel(px as u32, py as u32)
+                != new.image.get_pixel(px as u32, py as u32)
+            {
+                return false;
+            }
+        }
+    }
+    true
+}
+
+pub(super) async fn validate(
+    config: &MintConfig,
+    evidence: &ScreenshotEvidence,
+    tab: &str,
+    args: &Value,
+) -> Result<(), String> {
+    if evidence.tab != tab || evidence.captured.elapsed() >= Duration::from_secs(30) {
+        return Err("screenshot_stale: screenshot expired or tab changed".into());
+    }
+    let x = args["x"].as_f64().ok_or("x required")?;
+    let y = args["y"].as_f64().ok_or("y required")?;
+    if !x.is_finite()
+        || !y.is_finite()
+        || x < 0.0
+        || y < 0.0
+        || x >= evidence.marker[4].as_f64().unwrap_or(0.0)
+        || y >= evidence.marker[5].as_f64().unwrap_or(0.0)
+    {
+        return Err("screenshot_stale: coordinate outside viewport".into());
+    }
+    let original = target(evidence, x, y)?;
+    let (_, current) = capture_at(config, tab, Some((x, y))).await?;
+    if evidence.marker != current.marker
+        || original != target(&current, x, y)?
+        || !pixels_match(evidence, &current, x, y)
+    {
+        return Err("screenshot_stale: target identity, geometry, or pixels changed".into());
+    }
+    // DOM location lookup uses main-document coordinates, while screenshots
+    // and Input.dispatchMouseEvent use viewport coordinates.
+    let document_x = x + current.marker[2]
+        .as_f64()
+        .ok_or("screenshot_stale: missing scroll geometry")?;
+    let document_y = y + current.marker[3]
+        .as_f64()
+        .ok_or("screenshot_stale: missing scroll geometry")?;
+    let hit=cdp_call_raw(config,"DOM.getNodeForLocation",json!({"x":document_x.floor() as i64,"y":document_y.floor() as i64,"includeUserAgentShadowDOM":false,"ignorePointerEventsNone":false})).await?;
+    if hit["result"]["backendNodeId"].as_i64() != Some(original.backend) {
+        return Err("screenshot_stale: target is obstructed".into());
+    }
+    Ok(())
+}
+
+pub(super) async fn input(
+    config: &MintConfig,
+    evidence: &ScreenshotEvidence,
+    tab: &str,
+    action: &str,
+    args: &Value,
+) -> Result<String, String> {
+    let x = args["x"].as_f64().ok_or("x required")?;
+    let y = args["y"].as_f64().ok_or("y required")?;
+    super::mouse_move(config, x, y).await?;
+    tokio::time::sleep(Duration::from_millis(60)).await;
+    validate(config, evidence, tab, args).await?;
+    if action == "browser_mouse_move" {
+        return Ok("mouse moved".into());
+    }
+    let button = match args["button"].as_str() {
+        Some("right") => "right",
+        Some("middle") => "middle",
+        _ => "left",
+    };
+    // No second move or cosmetic animation between the final check and press.
+    for kind in ["mousePressed", "mouseReleased"] {
+        cdp_call_raw(config,"Input.dispatchMouseEvent",json!({"type":kind,"x":x,"y":y,"button":button,"buttons":if kind=="mousePressed" {match button {"right"=>2,"middle"=>4,_=>1}} else {0},"clickCount":1})).await?;
+    }
+    super::navigate::wait_for_page_load(config).await;
+    Ok(format!("clicked at ({x:.0},{y:.0}) with {button} button"))
+}

package/crates/mint-core/src/browser/input.rs

@@ -157,7 +157,7 @@ pub async fn mouse_click(
 pub async fn type_text_native(config: &MintConfig, text: &str) -> Result<String, String> {
     log_action(
         "TYPE",
-        &format!("Native typing: '{}'", &text[..text.len().min(60)]),
+        &format!("Native typing: {} characters", text.chars().count()),
     );
     ensure_page_open(config).await?;
 

package/crates/mint-core/src/browser/interact.rs

@@ -5,11 +5,10 @@
 use crate::MintConfig;
 use serde_json::{Value, json};
 
-use super::cdp::{cdp_call, cdp_call_raw, response_error};
+use super::cdp::{cdp_call_raw, response_error};
 use super::input::{mouse_click, type_text_native};
 use super::lifecycle::ensure_page_open;
 use super::logging::log_action;
-use super::navigate::wait_for_page_load;
 use super::overlay::inject_overlay;
 
 /// Click a CSS selector element using native CDP mouse events.
@@ -32,90 +31,8 @@ pub async fn click(config: &MintConfig, selector: &str) -> Result<String, String
     // Ensure overlay exists before doing any visual interaction
     inject_overlay(config).await;
 
-    // Build a JS expression that finds the element using selector or text/xpath
-    let find_expr = selector_to_js_find(selector);
-
-    let expression = format!(
-        r#"(() => {{
-            {find_expr}
-            if (!el) return null;
-            const r = el.getBoundingClientRect();
-            return JSON.stringify({{ x: r.left + r.width / 2, y: r.top + r.height / 2 }});
-        }})()"#
-    );
-
-    let coord_result = cdp_call_raw(
-        config,
-        "Runtime.evaluate",
-        json!({ "expression": expression, "returnByValue": true }),
-    )
-    .await;
-
-    if let Ok(response) = coord_result {
-        let val = &response["result"]["result"];
-        if let Some(val_str) = val["value"].as_str() {
-            if let Ok(parsed) = serde_json::from_str::<Value>(val_str) {
-                if let (Some(x), Some(y)) = (parsed["x"].as_f64(), parsed["y"].as_f64()) {
-                    log_action(
-                        "CLICK",
-                        &format!("Coordinates ({x:.0},{y:.0}) for '{selector}'"),
-                    );
-                    let result = mouse_click(config, x, y, "left").await?;
-                    log_action(
-                        "CLICK_SUCCESS",
-                        &format!("Clicked '{selector}' at ({x:.0},{y:.0})"),
-                    );
-                    return Ok(result);
-                }
-            }
-        }
-    }
-
-    // Fallback: JS .click() directly
-    let click_expr = format!(
-        r#"(() => {{
-            {find_expr}
-            if (!el) return 'not-found';
-            el.scrollIntoView({{behavior:'instant',block:'center'}});
-            el.click();
-            return 'clicked';
-        }})()"#
-    );
-    match cdp_call(
-        config,
-        "Runtime.evaluate",
-        json!({ "expression": click_expr, "returnByValue": true }),
-    )
-    .await
-    {
-        Ok(response) => match response["result"]["result"]["value"].as_str() {
-            Some("clicked") => {
-                log_action(
-                    "CLICK_SUCCESS",
-                    &format!("JS-fallback clicked '{selector}'"),
-                );
-                // The coordinate-based path already waits inside
-                // `mouse_click`; this JS `.click()` fallback bypasses that,
-                // so it needs its own wait — see `wait_for_page_load`'s doc.
-                wait_for_page_load(config).await;
-                Ok("clicked".into())
-            }
-            Some("not-found") => {
-                let err = format!("element not found for selector: {selector}");
-                log_action("CLICK_ERROR", &err);
-                Err(err)
-            }
-            _ => {
-                let err = response_error(&response);
-                log_action("CLICK_ERROR", &err);
-                Err(err)
-            }
-        },
-        Err(e) => {
-            log_action("CLICK_ERROR", &format!("Websocket error: {e}"));
-            Err(e)
-        }
-    }
+    let (x, y) = get_element_coordinates(config, selector).await?;
+    mouse_click(config, x, y, "left").await
 }
 
 /// Type text into a CSS selector element using native CDP keyboard events.
@@ -132,16 +49,61 @@ pub async fn type_text(config: &MintConfig, selector: &str, text: &str) -> Resul
     log_action("TYPE", &format!("Typing into '{selector}'"));
     ensure_page_open(config).await?;
 
-    // Focus the element by clicking it first. Propagate failure instead of
-    // swallowing it: `Input.insertText` types into whatever currently has
-    // focus, so if the click silently failed to find the element, the old
-    // behavior would type into the wrong field (or nowhere) with no error
-    // surfaced back to the agent to recover from.
-    click(config, selector).await?;
-    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+    edit_text(config, selector, text, false).await
+}
 
-    // Native keyboard input
-    type_text_native(config, text).await
+/// Pin one DOM node for the entire edit; never resolve a replacement selector.
+pub(super) async fn edit_text(
+    config: &MintConfig,
+    selector: &str,
+    text: &str,
+    replace: bool,
+) -> Result<String, String> {
+    let token = uuid::Uuid::new_v4().to_string();
+    let find = selector_to_js_find(selector);
+    eval(config, format!("(() => {{ {find} if (!el || !el.isConnected) throw new Error('stale_reference'); if (el.readOnly || !(el.tagName === 'TEXTAREA' || (el.tagName === 'INPUT' && ['text','search','url','tel','password','email','number'].includes(el.type)))) throw new Error('unsupported_edit_target'); (globalThis.__mintEditable ||= new Map()).set({},el); return true; }})()",json!(token))).await?;
+    let pinned = format!("mint-edit={token}");
+    let find = selector_to_js_find(&pinned);
+    let check = format!(
+        "{find} if (!el || !el.isConnected) throw new Error('stale_reference'); if (el.disabled || el.readOnly || el.getAttribute('aria-disabled') === 'true' || !(el.tagName === 'TEXTAREA' || (el.tagName === 'INPUT' && ['text','search','url','tel','password','email','number'].includes(el.type)))) throw new Error('focus_changed: original target is no longer editable'); if (el.getRootNode().activeElement !== el) throw new Error('focus_changed');"
+    );
+    let result = async {
+        click(config, &pinned).await?;
+        let previous = eval(config,format!("(() => {{ {check} {} return el.value; }})()",if replace {""} else {"if (typeof el.selectionStart === 'number') el.setSelectionRange(el.value.length,el.value.length);"})).await?;
+        if replace {
+            let platform = eval(config,"navigator.platform".into()).await?;
+            let modifiers = if platform.as_str().unwrap_or("").contains("Mac") {4} else {2};
+            for kind in ["keyDown", "keyUp"] {
+                cdp_call_raw(config,"Input.dispatchKeyEvent",json!({"type":kind,"key":"a","code":"KeyA","windowsVirtualKeyCode":65,"nativeVirtualKeyCode":65,"modifiers":modifiers})).await?;
+            }
+        } else {
+            super::key_press(config,"End").await?;
+        }
+        // Key handlers may redirect focus or replace the node. Stop before text input.
+        eval(config,format!("(() => {{ {check} return true; }})()")).await?;
+        if replace && text.is_empty() { super::key_press(config,"Backspace").await?; }
+        else { type_text_native(config,text).await?; }
+        let value = eval(config,format!("(() => {{ {find} if (!el?.isConnected) throw new Error('stale_reference'); return el.value; }})()")).await?;
+        let expected = if replace {text.to_owned()} else {format!("{}{text}",previous.as_str().ok_or("unsupported_edit_target")?)};
+        if value.as_str() != Some(expected.as_str()) {return Err("field_value_mismatch".into());}
+        Ok("value_verified".into())
+    }.await;
+    let _ = eval(
+        config,
+        format!("globalThis.__mintEditable?.delete({})", json!(token)),
+    )
+    .await;
+    result
+}
+
+async fn eval(config: &MintConfig, expression: String) -> Result<Value, String> {
+    Ok(cdp_call_raw(
+        config,
+        "Runtime.evaluate",
+        json!({"expression":expression,"returnByValue":true}),
+    )
+    .await?["result"]["result"]["value"]
+        .clone())
 }
 
 /// Get the viewport-relative center (x, y) of an element by CSS selector.
@@ -154,9 +116,16 @@ pub async fn get_element_coordinates(
     let expression = format!(
         r#"(() => {{
             {find_expr}
-            if (!el) return null;
-            const r = el.getBoundingClientRect();
-            return JSON.stringify({{ x: r.left + r.width / 2, y: r.top + r.height / 2 }});
+            if (!el || !el.isConnected) throw new Error('element_not_found_or_stale');
+            el.scrollIntoView({{behavior:'instant',block:'center',inline:'center'}});
+            const r = el.getBoundingClientRect(), style = getComputedStyle(el);
+            if (!r.width || !r.height || style.visibility === 'hidden' || style.display === 'none') throw new Error('element_not_visible');
+            if (el.disabled || el.getAttribute('aria-disabled') === 'true') throw new Error('element_disabled');
+            const x = r.left + r.width / 2, y = r.top + r.height / 2;
+            let hit = document.elementFromPoint(x,y);
+            while (hit && hit.shadowRoot) {{ const deeper = hit.shadowRoot.elementFromPoint(x,y); if (!deeper || deeper === hit) break; hit = deeper; }}
+            if (hit !== el && !el.contains(hit)) throw new Error('element_obstructed');
+            return JSON.stringify({{ x, y }});
         }})()"#
     );
     match cdp_call_raw(
@@ -186,40 +155,45 @@ pub async fn get_element_coordinates(
 
 /// Convert a selector (CSS / text= / contains= / xpath=) into a JS let statement:
 /// `let el = <expression>;`
-fn selector_to_js_find(selector: &str) -> String {
-    if let Some(text) = selector.strip_prefix("text=") {
-        // Exact text match (trimmed)
-        let escaped = text.replace('\\', "\\\\").replace('`', "\\`");
+pub(super) fn selector_to_js_find(selector: &str) -> String {
+    let quoted = |s: &str| serde_json::to_string(s).expect("string serialization");
+    if selector == "mint-focus=" {
+        "let el=document.activeElement; while (el?.shadowRoot?.activeElement) el=el.shadowRoot.activeElement;".into()
+    } else if let Some(point) = selector.strip_prefix("mint-point=") {
+        let (x, y) = point.split_once(',').unwrap_or(("0", "0"));
+        let x = x.parse::<f64>().unwrap_or(0.0);
+        let y = y.parse::<f64>().unwrap_or(0.0);
+        format!(
+            "let el=document.elementFromPoint({x},{y}); while(el?.shadowRoot) {{const hit=el.shadowRoot.elementFromPoint({x},{y});if (!hit || hit===el) break;el=hit;}}"
+        )
+    } else if selector == "mint-attempt=" {
+        "const el = globalThis.__mintAttemptTarget;".into()
+    } else if let Some(token) = selector.strip_prefix("mint-edit=") {
         format!(
-            "const el = Array.from(document.querySelectorAll('*')).find(\
-             e => e.childElementCount === 0 && e.textContent.trim() === `{escaped}`) \
-             || Array.from(document.querySelectorAll('*')).find(\
-             e => e.textContent.trim() === `{escaped}`);"
+            "const el = globalThis.__mintEditable?.get({});",
+            quoted(token)
+        )
+    } else if let Some(reference) = selector.strip_prefix("mint-ref=") {
+        format!(
+            "const el = globalThis.__mintObservation?.elements.get({});",
+            quoted(reference)
+        )
+    } else if let Some(text) = selector.strip_prefix("text=") {
+        format!(
+            "const el = Array.from(document.querySelectorAll('*')).find(e => e.childElementCount === 0 && e.textContent.trim() === {});",
+            quoted(text)
         )
     } else if let Some(text) = selector.strip_prefix("contains=") {
-        // Partial text match
-        let escaped = text.replace('\\', "\\\\").replace('`', "\\`");
         format!(
-            "const el = Array.from(document.querySelectorAll('*')).find(\
-             e => e.childElementCount === 0 && e.textContent.includes(`{escaped}`)) \
-             || Array.from(document.querySelectorAll('*')).find(\
-             e => e.textContent.includes(`{escaped}`));"
+            "const el = Array.from(document.querySelectorAll('*')).find(e => e.childElementCount === 0 && e.textContent.includes({}));",
+            quoted(text)
         )
     } else if let Some(xpath) = selector.strip_prefix("xpath=") {
-        let escaped = xpath.replace('\\', "\\\\").replace('"', "\\\"");
         format!(
-            "const el = document.evaluate(`{escaped}`, document, null, \
-             XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;"
+            "const el = document.evaluate({}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;",
+            quoted(xpath)
         )
     } else {
-        // Standard CSS selector — wrap in try/catch so invalid selectors don't throw
-        let escaped = selector.replace('\\', "\\\\").replace('`', "\\`");
-        format!(
-            "let el; try {{ el = document.querySelector(`{escaped}`); }} \
-             catch(e) {{ \
-               el = Array.from(document.querySelectorAll('*')).find(\
-                 e => e.textContent.trim() === `{escaped}`); \
-             }}"
-        )
+        format!("const el = document.querySelector({});", quoted(selector))
     }
 }

package/crates/mint-core/src/browser/lifecycle.rs

@@ -15,7 +15,38 @@ pub async fn is_browser_running(config: &MintConfig) -> bool {
     fetch_pages_endpoint(endpoint).await.is_ok()
 }
 
-pub async fn spawn_automation_browser(config: &MintConfig) -> Result<(), String> {
+pub(crate) const BROWSER_TOOLS: &[&str] = &[
+    "browser_open",
+    "browser_click",
+    "browser_type",
+    "browser_read",
+    "browser_mouse_move",
+    "browser_mouse_click",
+    "browser_key_press",
+    "browser_screenshot",
+    "browser_tabs",
+    "browser_observe",
+    "browser_fill",
+    "browser_select",
+    "browser_scroll",
+    "browser_wait",
+];
+
+pub fn enable_browser_tools(config: &mut MintConfig) -> bool {
+    let mut changed = false;
+    for tool in BROWSER_TOOLS {
+        if config.disabled_tools.contains(&tool.to_string()) {
+            config.disabled_tools.retain(|x| x != *tool);
+            changed = true;
+        }
+    }
+    changed
+}
+
+pub async fn spawn_automation_browser_with_url(
+    config: &MintConfig,
+    initial_url: Option<&str>,
+) -> Result<(), String> {
     let endpoint = config
         .extra
         .get("browserDebugUrl")
@@ -23,9 +54,23 @@ pub async fn spawn_automation_browser(config: &MintConfig) -> Result<(), String>
         .unwrap_or("http://127.0.0.1:9222/json/list");
 
     if fetch_pages_endpoint(endpoint).await.is_ok() {
+        if let Some(url) = initial_url {
+            let trimmed = url.trim();
+            if !trimmed.is_empty() {
+                ensure_page_open(config).await?;
+                super::navigate::navigate(config, trimmed).await?;
+            }
+        }
         return Ok(());
     }
 
+    let debug_url = reqwest::Url::parse(endpoint).map_err(|e| e.to_string())?;
+    if !matches!(
+        debug_url.host_str(),
+        Some("localhost" | "127.0.0.1" | "[::1]" | "::1")
+    ) {
+        return Err("Configured remote browser is unavailable; start it at the configured endpoint before using Mint Auto".into());
+    }
     let browser_name = config
         .extra
         .get("automationBrowser")
@@ -38,13 +83,26 @@ pub async fn spawn_automation_browser(config: &MintConfig) -> Result<(), String>
         .join("automation-profile");
     let profile_arg = format!("--user-data-dir={}", profile_dir.to_string_lossy());
 
-    let args = [
-        "--remote-debugging-port=9222".to_owned(),
+    let mut args = vec![
+        format!(
+            "--remote-debugging-port={}",
+            reqwest::Url::parse(endpoint)
+                .map_err(|e| e.to_string())?
+                .port_or_known_default()
+                .ok_or("Missing debugging port")?
+        ),
         "--no-first-run".to_owned(),
         "--no-default-browser-check".to_owned(),
         profile_arg,
     ];
 
+    if let Some(url) = initial_url {
+        let trimmed = url.trim();
+        if !trimmed.is_empty() {
+            args.push(trimmed.to_owned());
+        }
+    }
+
     let mut spawned = false;
     let executables: Vec<&str> = if cfg!(target_os = "windows") {
         vec!["chrome.exe", "chromium.exe", "msedge.exe"]
@@ -92,7 +150,13 @@ pub async fn spawn_automation_browser(config: &MintConfig) -> Result<(), String>
         }
     }
 
-    Err("Browser spawned but remote debugging port 9222 did not become available.".to_string())
+    Err(format!(
+        "Browser spawned but debugging endpoint {endpoint} did not become available."
+    ))
+}
+
+pub async fn spawn_automation_browser(config: &MintConfig) -> Result<(), String> {
+    spawn_automation_browser_with_url(config, None).await
 }
 
 pub async fn ensure_page_open(config: &MintConfig) -> Result<(), String> {
@@ -106,6 +170,13 @@ pub async fn ensure_page_open(config: &MintConfig) -> Result<(), String> {
         .unwrap_or("http://127.0.0.1:9222/json/list");
 
     let pages = fetch_pages_endpoint(endpoint).await?;
+    if let Some(id) = super::selected_tab() {
+        return if pages.iter().any(|p| p["type"] == "page" && p["id"] == id) {
+            Ok(())
+        } else {
+            Err("tab_unavailable".into())
+        };
+    }
     let has_page = pages.iter().any(|p| p["type"] == "page");
     if !has_page {
         let base_url = endpoint.replace("/json/list", "/json/new");