commands.rs

use base64::{engine::general_purpose::STANDARD, Engine};
use serde_json::{json, Value};
use std::io::{self, BufRead};

use crate::color;
use crate::flags::Flags;
use crate::validation::{is_valid_session_name, session_name_error};

/// Error type for command parsing with contextual information
#[derive(Debug)]
pub enum ParseError {
    /// Command does not exist
    UnknownCommand { command: String },
    /// Command exists but subcommand is invalid
    UnknownSubcommand {
        subcommand: String,
        valid_options: &'static [&'static str],
    },
    /// Command/subcommand exists but required arguments are missing
    MissingArguments {
        context: String,
        usage: &'static str,
    },
    /// Argument exists but has an invalid value
    InvalidValue {
        message: String,
        usage: &'static str,
    },
    /// Invalid session name (path traversal or invalid characters)
    InvalidSessionName { name: String },
}

impl ParseError {
    pub fn format(&self) -> String {
        match self {
            ParseError::UnknownCommand { command } => {
                format!("Unknown command: {}", command)
            }
            ParseError::UnknownSubcommand {
                subcommand,
                valid_options,
            } => {
                format!(
                    "Unknown subcommand: {}\nValid options: {}",
                    subcommand,
                    valid_options.join(", ")
                )
            }
            ParseError::MissingArguments { context, usage } => {
                format!(
                    "Missing arguments for: {}\nUsage: agent-browser {}",
                    context, usage
                )
            }
            ParseError::InvalidValue { message, usage } => {
                format!("{}\nUsage: agent-browser {}", message, usage)
            }
            ParseError::InvalidSessionName { name } => session_name_error(name),
        }
    }
}

pub fn gen_id() -> String {
    format!(
        "r{}",
        std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_micros()
            % 1000000
    )
}

/// Normalize browser navigation inputs while preserving schemes Chrome can
/// open directly. Bare hostnames use HTTPS, matching the `open` command.
fn normalize_navigation_url(url: &str) -> String {
    let url_lower = url.to_lowercase();
    if url_lower.starts_with("http://")
        || url_lower.starts_with("https://")
        || url_lower.starts_with("about:")
        || url_lower.starts_with("data:")
        || url_lower.starts_with("file:")
        || url_lower.starts_with("chrome-extension://")
        || url_lower.starts_with("chrome://")
    {
        url.to_string()
    } else {
        format!("https://{}", url)
    }
}

pub fn is_top_level_command(value: &str) -> bool {
    matches!(
        value,
        "open"
            | "goto"
            | "navigate"
            | "back"
            | "forward"
            | "reload"
            | "read"
            | "click"
            | "dblclick"
            | "fill"
            | "type"
            | "hover"
            | "focus"
            | "check"
            | "uncheck"
            | "select"
            | "drag"
            | "upload"
            | "download"
            | "press"
            | "key"
            | "keydown"
            | "keyup"
            | "keyboard"
            | "scroll"
            | "scrollintoview"
            | "scrollinto"
            | "wait"
            | "screenshot"
            | "pdf"
            | "snapshot"
            | "eval"
            | "close"
            | "quit"
            | "exit"
            | "inspect"
            | "auth"
            | "confirm"
            | "deny"
            | "connect"
            | "stream"
            | "get"
            | "is"
            | "find"
            | "mouse"
            | "set"
            | "network"
            | "storage"
            | "cookies"
            | "tab"
            | "window"
            | "frame"
            | "dialog"
            | "trace"
            | "profiler"
            | "record"
            | "console"
            | "errors"
            | "highlight"
            | "clipboard"
            | "state"
            | "tap"
            | "swipe"
            | "device"
            | "diff"
            | "batch"
            | "react"
            | "vitals"
            | "web-vitals"
            | "a11y"
            | "pushstate"
            | "removeinitscript"
            | "session"
            | "mcp"
            | "doctor"
            | "install"
            | "upgrade"
            | "profiles"
            | "skills"
            | "dashboard"
            | "plugin"
            | "plugins"
            | "chat"
            | "webmcp"
    )
}

/// Parse a cookies file in one of three auto-detected formats:
///
/// 1. JSON array — `[{"name":"x","value":"y"}, ...]`
/// 2. cURL dump  — the output of DevTools → Network → Copy → Copy as cURL
///    (the Cookie header is extracted from `-H 'cookie: ...'` or
///    `-b '...'`/`--cookie '...'`)
/// 3. Bare cookie header — `name=value; name2=value2`
///
/// Returns a JSON array of cookie objects (each `{ name, value }`) suitable
/// for the `cookies_set` daemon action. Error text never echoes the secret
/// value.
pub fn parse_curl_cookies(raw: &str) -> Result<Vec<Value>, String> {
    let trimmed = raw.trim();
    if trimmed.is_empty() {
        return Err("cookies file is empty".to_string());
    }

    if trimmed.starts_with('[') {
        let arr: Vec<Value> = serde_json::from_str(trimmed)
            .map_err(|e| format!("cookies JSON parse error: {}", e))?;
        let mut out = Vec::with_capacity(arr.len());
        for (i, c) in arr.into_iter().enumerate() {
            let name = c
                .get("name")
                .and_then(|v| v.as_str())
                .ok_or_else(|| format!("cookies[{}] missing string name", i))?;
            let value = c
                .get("value")
                .and_then(|v| v.as_str())
                .ok_or_else(|| format!("cookies[{}] missing string value", i))?;
            out.push(json!({ "name": name, "value": value }));
        }
        return Ok(out);
    }

    // Heuristic: cURL commands start with `curl` followed by space/quote.
    let looks_like_curl = {
        let head: String = trimmed.chars().take(5).collect::<String>().to_lowercase();
        head.starts_with("curl") && head.len() > 4 && {
            let c = head.chars().nth(4).unwrap();
            c.is_whitespace() || c == '\'' || c == '"'
        }
    };

    let header = if looks_like_curl {
        extract_cookie_header_from_curl(trimmed).ok_or_else(|| {
            "no Cookie header found in this cURL - right-click an authenticated request in DevTools → Network → Copy → Copy as cURL".to_string()
        })?
    } else {
        trimmed.to_string()
    };

    parse_cookie_header(&header)
}

fn extract_cookie_header_from_curl(curl: &str) -> Option<String> {
    // Strip bash (`\`) and cmd (`^`) line continuations so -H is on one line.
    let joined = curl
        .replace("\\\r\n", " ")
        .replace("\\\n", " ")
        .replace("^\r\n", " ")
        .replace("^\n", " ");
    if let Some(v) = match_quoted_arg(&joined, "-H", Some("cookie")) {
        return Some(v);
    }
    if let Some(v) = match_quoted_arg(&joined, "-b", None) {
        return Some(v);
    }
    if let Some(v) = match_quoted_arg(&joined, "--cookie", None) {
        return Some(v);
    }
    None
}

/// Find `flag <quote>[header:]value<quote>` in haystack and return the value.
/// When `expect_header` is set, the quoted value must start with that header
/// name followed by a colon (case-insensitive) and the prefix is stripped.
fn match_quoted_arg(haystack: &str, flag: &str, expect_header: Option<&str>) -> Option<String> {
    let bytes = haystack.as_bytes();
    let flag_b = flag.as_bytes();
    let mut i = 0;
    while i + flag_b.len() < bytes.len() {
        if &bytes[i..i + flag_b.len()] != flag_b {
            i += 1;
            continue;
        }
        // Must be at a word boundary on the left (start of string or whitespace).
        if i > 0 && !bytes[i - 1].is_ascii_whitespace() {
            i += 1;
            continue;
        }
        let mut j = i + flag_b.len();
        // Require a whitespace separator after the flag.
        if j >= bytes.len() || !bytes[j].is_ascii_whitespace() {
            i += 1;
            continue;
        }
        while j < bytes.len() && bytes[j].is_ascii_whitespace() {
            j += 1;
        }
        if j >= bytes.len() {
            return None;
        }
        let quote = bytes[j];
        if quote != b'\'' && quote != b'"' {
            i = j;
            continue;
        }
        let start = j + 1;
        let mut k = start;
        while k < bytes.len() && bytes[k] != quote {
            k += 1;
        }
        if k >= bytes.len() {
            return None;
        }
        let value = String::from_utf8_lossy(&bytes[start..k]).into_owned();
        if let Some(header) = expect_header {
            let lower = value.to_lowercase();
            let prefix = format!("{}:", header.to_lowercase());
            if let Some(stripped) = lower.strip_prefix(&prefix) {
                let _ = stripped;
                return Some(value[prefix.len()..].trim().to_string());
            }
            i = k + 1;
            continue;
        }
        return Some(value);
    }
    None
}

fn parse_cookie_header(header: &str) -> Result<Vec<Value>, String> {
    let mut out = Vec::new();
    for piece in header.split(';') {
        let piece = piece.trim();
        let Some(eq) = piece.find('=') else { continue };
        let name = piece[..eq].trim();
        let value = piece[eq + 1..].trim();
        if !name.is_empty() {
            out.push(json!({ "name": name, "value": value }));
        }
    }
    if out.is_empty() {
        return Err("no cookies found in input".to_string());
    }
    Ok(out)
}

/// Parses `--cdp-headers`: a JSON object of string values sent on the CDP
/// WebSocket handshake (distinct from page-level `--headers`).
pub fn parse_cdp_headers(raw: &str) -> Result<Value, String> {
    let headers = serde_json::from_str::<Value>(raw)
        .map_err(|e| format!("Invalid JSON for --cdp-headers at column {}", e.column()))?;
    let valid = headers
        .as_object()
        .is_some_and(|map| map.values().all(Value::is_string));
    if !valid {
        return Err("--cdp-headers must be a JSON object with string values".to_string());
    }
    Ok(headers)
}

/// Parses command arguments, including literal fill/type text after `--`.
/// Wait selector `--state` values are accepted only for selector waits.
pub fn parse_command(args: &[String], flags: &Flags) -> Result<Value, ParseError> {
    let mut result = parse_command_inner(args, flags)?;

    // Inject AGENT_BROWSER_DEFAULT_TIMEOUT into any wait-family command that
    // doesn't already carry an explicit timeout. Centralised here so that new
    // wait variants automatically inherit the default without per-variant wiring.
    if let Some(action) = result.get("action").and_then(|a| a.as_str()) {
        if action.starts_with("wait") && result.get("timeout").is_none() {
            if let Some(t) = flags.default_timeout {
                result["timeout"] = json!(t);
            }
        }
    }
    attach_ca_cert_to_launch_command(&mut result, flags);

    Ok(result)
}

pub fn attach_ca_cert_to_launch_command(cmd: &mut Value, flags: &Flags) {
    if cmd.get("action").and_then(Value::as_str) != Some("launch") {
        return;
    }
    if let Some(ref ca) = flags.ca_cert {
        cmd["caCert"] = json!(ca);
    }
    if flags.clear_ca_cert {
        cmd["clearCaCert"] = json!(true);
    }
}

fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseError> {
    if args.is_empty() {
        return Err(ParseError::MissingArguments {
            context: "".to_string(),
            usage: "<command> [args...]",
        });
    }

    let cmd = args[0].as_str();
    let rest: Vec<&str> = args[1..].iter().map(|s| s.as_str()).collect();
    let id = gen_id();

    if flags.cli_annotate && cmd != "screenshot" {
        eprintln!(
            "{} --annotate only applies to the screenshot command",
            color::warning_indicator()
        );
    }

    match cmd {
        // === Navigation ===
        // Maps to "navigate" action in protocol; reflected in ACTION_CATEGORIES in action-policy.ts
        "open" | "goto" | "navigate" => {
            // `open` without a URL launches the browser but stays on
            // about:blank. Lets agents set up routes, cookies, or init
            // scripts before the first real navigation (see `batch`).
            // `goto` and `navigate` still require a URL since those verbs
            // imply the navigation itself.
            let first_url = rest.iter().find(|a| !a.starts_with("--"));
            let url = match first_url {
                Some(u) => *u,
                None if cmd == "open" => {
                    return Ok(json!({ "id": id, "action": "launch", "headless": !flags.headed }));
                }
                None => {
                    return Err(ParseError::MissingArguments {
                        context: cmd.to_string(),
                        usage: "goto <url>",
                    });
                }
            };
            let url = normalize_navigation_url(url);
            let mut nav_cmd = json!({ "id": id, "action": "navigate", "url": url });
            if flags.provider.is_some() {
                nav_cmd["waitUntil"] = json!("none");
            }
            if let Some(ref headers_json) = flags.headers {
                let headers =
                    serde_json::from_str::<serde_json::Value>(headers_json).map_err(|_| {
                        ParseError::InvalidValue {
                            message: format!("Invalid JSON for --headers: {}", headers_json),
                            usage: "open <url> --headers '{\"Key\": \"Value\"}'",
                        }
                    })?;
                nav_cmd["headers"] = headers;
            }
            // Include iOS device info if specified (needed for auto-launch with existing daemon)
            if flags.provider.as_deref() == Some("ios") {
                if let Some(ref device) = flags.device {
                    nav_cmd["iosDevice"] = json!(device);
                }
            }
            Ok(nav_cmd)
        }
        "back" => Ok(json!({ "id": id, "action": "back" })),
        "forward" => Ok(json!({ "id": id, "action": "forward" })),
        "reload" => Ok(json!({ "id": id, "action": "reload" })),
        "read" => parse_read(&rest, &id, flags),
        "webmcp" => parse_webmcp(&rest, &id),

        // === Core Actions ===
        "click" => {
            let new_tab = rest.contains(&"--new-tab");
            let human = rest.contains(&"--human");
            let sel = rest
                .iter()
                .find(|arg| **arg != "--new-tab" && **arg != "--human")
                .ok_or_else(|| ParseError::MissingArguments {
                    context: "click".to_string(),
                    usage: "click <selector> [--new-tab] [--human]",
                })?;
            let mut cmd = json!({ "id": id, "action": "click", "selector": sel });
            if new_tab {
                cmd["newTab"] = json!(true);
            }
            if human {
                cmd["inputMode"] = json!("human");
            }
            Ok(cmd)
        }
        "dblclick" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "dblclick".to_string(),
                usage: "dblclick <selector>",
            })?;
            Ok(json!({ "id": id, "action": "dblclick", "selector": sel }))
        }
        "fill" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "fill".to_string(),
                usage: "fill <selector> <text>",
            })?;
            let text = if rest.get(1) == Some(&"--") {
                &rest[2..]
            } else {
                &rest[1..]
            };
            Ok(json!({ "id": id, "action": "fill", "selector": sel, "value": text.join(" ") }))
        }
        "type" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "type".to_string(),
                usage: "type <selector> <text> [--clear] [--delay <ms>]",
            })?;
            // The daemon has always supported clear/delay, but the CLI used
            // to join every remaining arg into the text, so `--clear` was
            // literally typed into the field with a success response.
            let mut clear = false;
            let mut delay: Option<u64> = None;
            let mut text_parts: Vec<&str> = Vec::new();
            let mut i = 1;
            while i < rest.len() {
                match rest[i] {
                    "--" => {
                        text_parts.extend_from_slice(&rest[i + 1..]);
                        break;
                    }
                    "--clear" => clear = true,
                    "--delay" => {
                        // Error rather than silently drop a malformed value;
                        // a dropped flag would type its argument into the field.
                        let raw = rest
                            .get(i + 1)
                            .ok_or_else(|| ParseError::MissingArguments {
                                context: "type --delay".to_string(),
                                usage: "type <selector> <text> [--clear] [--delay <ms>]",
                            })?;
                        delay = Some(raw.parse::<u64>().map_err(|_| ParseError::InvalidValue {
                            message: format!("--delay expects a number in ms, got '{}'", raw),
                            usage: "type <selector> <text> [--clear] [--delay <ms>]",
                        })?);
                        i += 1;
                    }
                    other => text_parts.push(other),
                }
                i += 1;
            }
            let mut cmd = json!({ "id": id, "action": "type", "selector": sel, "text": text_parts.join(" ") });
            if clear {
                cmd["clear"] = json!(true);
            }
            if let Some(ms) = delay {
                cmd["delay"] = json!(ms);
            }
            Ok(cmd)
        }
        "hover" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "hover".to_string(),
                usage: "hover <selector>",
            })?;
            Ok(json!({ "id": id, "action": "hover", "selector": sel }))
        }
        "focus" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "focus".to_string(),
                usage: "focus <selector>",
            })?;
            Ok(json!({ "id": id, "action": "focus", "selector": sel }))
        }
        "check" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "check".to_string(),
                usage: "check <selector>",
            })?;
            Ok(json!({ "id": id, "action": "check", "selector": sel }))
        }
        "uncheck" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "uncheck".to_string(),
                usage: "uncheck <selector>",
            })?;
            Ok(json!({ "id": id, "action": "uncheck", "selector": sel }))
        }
        "select" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "select".to_string(),
                usage: "select <selector> <value...>",
            })?;
            let _val = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "select".to_string(),
                usage: "select <selector> <value...>",
            })?;
            let values = &rest[1..];
            if values.len() == 1 {
                Ok(json!({ "id": id, "action": "select", "selector": sel, "values": values[0] }))
            } else {
                Ok(json!({ "id": id, "action": "select", "selector": sel, "values": values }))
            }
        }
        "drag" => {
            let src = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "drag".to_string(),
                usage: "drag <source> <target>",
            })?;
            let tgt = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "drag".to_string(),
                usage: "drag <source> <target>",
            })?;
            let mut cmd = json!({ "id": id, "action": "drag", "source": src, "target": tgt });
            if rest.contains(&"--human") {
                cmd["inputMode"] = json!("human");
            }
            Ok(cmd)
        }
        "upload" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "upload".to_string(),
                usage: "upload <selector> <files...>",
            })?;
            Ok(json!({ "id": id, "action": "upload", "selector": sel, "files": &rest[1..] }))
        }
        "download" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "download".to_string(),
                usage: "download <selector> <path>",
            })?;
            let path = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "download".to_string(),
                usage: "download <selector> <path>",
            })?;
            Ok(json!({ "id": id, "action": "download", "selector": sel, "path": path }))
        }

        // === Keyboard ===
        "press" | "key" => {
            let key = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "press".to_string(),
                usage: "press <key>",
            })?;
            Ok(json!({ "id": id, "action": "press", "key": key }))
        }
        "keydown" => {
            let key = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "keydown".to_string(),
                usage: "keydown <key>",
            })?;
            Ok(json!({ "id": id, "action": "keydown", "key": key }))
        }
        "keyup" => {
            let key = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "keyup".to_string(),
                usage: "keyup <key>",
            })?;
            Ok(json!({ "id": id, "action": "keyup", "key": key }))
        }
        "keyboard" => {
            let sub = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "keyboard".to_string(),
                usage: "keyboard <type|inserttext> <text>",
            })?;
            match *sub {
                "type" => {
                    let text: String = rest[1..].join(" ");
                    if text.is_empty() {
                        return Err(ParseError::MissingArguments {
                            context: "keyboard type".to_string(),
                            usage: "keyboard type <text>",
                        });
                    }
                    Ok(json!({ "id": id, "action": "keyboard", "subaction": "type", "text": text }))
                }
                "inserttext" | "insertText" => {
                    let text: String = rest[1..].join(" ");
                    if text.is_empty() {
                        return Err(ParseError::MissingArguments {
                            context: "keyboard inserttext".to_string(),
                            usage: "keyboard inserttext <text>",
                        });
                    }
                    Ok(
                        json!({ "id": id, "action": "keyboard", "subaction": "insertText", "text": text }),
                    )
                }
                _ => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.to_string(),
                    valid_options: &["type", "inserttext"],
                }),
            }
        }

        // === Scroll ===
        "scroll" => {
            let mut cmd = json!({ "id": id, "action": "scroll" });
            let obj = cmd.as_object_mut().unwrap();
            let mut positional_index = 0;
            let mut i = 0;
            while i < rest.len() {
                match rest[i] {
                    "-s" | "--selector" => {
                        if let Some(s) = rest.get(i + 1) {
                            obj.insert("selector".to_string(), json!(s));
                            i += 1;
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "scroll --selector".to_string(),
                                usage: "scroll [direction] [amount] [--selector <sel>]",
                            });
                        }
                    }
                    arg if arg.starts_with('-') => {}
                    _ => {
                        match positional_index {
                            0 => {
                                obj.insert("direction".to_string(), json!(rest[i]));
                            }
                            1 => {
                                if let Ok(n) = rest[i].parse::<i32>() {
                                    obj.insert("amount".to_string(), json!(n));
                                }
                            }
                            _ => {}
                        }
                        positional_index += 1;
                    }
                }
                i += 1;
            }
            if !obj.contains_key("direction") {
                obj.insert("direction".to_string(), json!("down"));
            }
            if !obj.contains_key("amount") {
                obj.insert("amount".to_string(), json!(300));
            }
            Ok(cmd)
        }
        "scrollintoview" | "scrollinto" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "scrollintoview".to_string(),
                usage: "scrollintoview <selector>",
            })?;
            Ok(json!({ "id": id, "action": "scrollintoview", "selector": sel }))
        }

        // === Wait ===
        "wait" => {
            // --timeout applies to EVERY wait variant (the docs advertise
            // e.g. `wait --url "**/dashboard" --timeout 120000`); it used to
            // be parsed only for --text/--download and silently ignored
            // elsewhere. Extract it first so variants parse independently.
            let mut rest = rest.clone();
            let mut timeout_ms: Option<u64> = None;
            if let Some(idx) = rest.iter().position(|&s| s == "--timeout") {
                // Error rather than silently drop a malformed value; a dropped
                // flag would leave its argument to be misread as a selector.
                let raw = rest
                    .get(idx + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: "wait --timeout".to_string(),
                        usage: "wait <selector|ms|--url|--load|--fn|--text> [--timeout <ms>]",
                    })?;
                timeout_ms = Some(raw.parse::<u64>().map_err(|_| ParseError::InvalidValue {
                    message: format!("--timeout expects a number in ms, got '{}'", raw),
                    usage: "wait <selector|ms|--url|--load|--fn|--text> [--timeout <ms>]",
                })?);
                rest.drain(idx..=idx + 1);
            }
            let mut element_state: Option<&str> = None;
            if let Some(idx) = rest.iter().position(|&s| s == "--state") {
                let raw = rest
                    .get(idx + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: "wait --state".to_string(),
                        usage: "wait <selector> --state <visible|hidden|attached|detached>",
                    })?;
                if !matches!(*raw, "visible" | "hidden" | "attached" | "detached") {
                    return Err(ParseError::InvalidValue {
                        message: format!(
                            "--state expects visible, hidden, attached, or detached, got '{}'. To load a state file, put --state <path> before wait.",
                            raw
                        ),
                        usage: "wait <selector> --state <visible|hidden|attached|detached>",
                    });
                }
                element_state = Some(*raw);
                rest.drain(idx..=idx + 1);
            }
            let uses_non_selector_wait =
                rest.iter().any(|arg| {
                    matches!(
                        *arg,
                        "--url"
                            | "-u"
                            | "--load"
                            | "-l"
                            | "--fn"
                            | "-f"
                            | "--text"
                            | "-t"
                            | "--download"
                            | "-d"
                    )
                }) || rest.first().is_some_and(|arg| arg.parse::<u64>().is_ok());
            if element_state.is_some() && uses_non_selector_wait {
                return Err(ParseError::InvalidValue {
                    message: "--state can only be used with a selector wait".to_string(),
                    usage: "wait <selector> --state <visible|hidden|attached|detached>",
                });
            }
            let with_timeout = |mut cmd: Value| {
                if let Some(ms) = timeout_ms {
                    cmd["timeout"] = json!(ms);
                }
                cmd
            };

            // Check for --url flag: wait --url "**/dashboard"
            if let Some(idx) = rest.iter().position(|&s| s == "--url" || s == "-u") {
                let url = rest
                    .get(idx + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: "wait --url".to_string(),
                        usage: "wait --url <pattern>",
                    })?;
                return Ok(with_timeout(
                    json!({ "id": id, "action": "waitforurl", "url": url }),
                ));
            }

            // Check for --load flag: wait --load networkidle
            if let Some(idx) = rest.iter().position(|&s| s == "--load" || s == "-l") {
                let state = rest
                    .get(idx + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: "wait --load".to_string(),
                        usage: "wait --load <state>",
                    })?;
                return Ok(with_timeout(
                    json!({ "id": id, "action": "waitforloadstate", "state": state }),
                ));
            }

            // Check for --fn flag: wait --fn "window.ready === true"
            if let Some(idx) = rest.iter().position(|&s| s == "--fn" || s == "-f") {
                let expr = rest
                    .get(idx + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: "wait --fn".to_string(),
                        usage: "wait --fn <expression>",
                    })?;
                return Ok(with_timeout(
                    json!({ "id": id, "action": "waitforfunction", "expression": expr }),
                ));
            }

            // Check for --text flag: wait --text "Welcome"
            if let Some(idx) = rest.iter().position(|&s| s == "--text" || s == "-t") {
                let text = rest
                    .get(idx + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: "wait --text".to_string(),
                        usage: "wait --text <text>",
                    })?;
                return Ok(with_timeout(
                    json!({ "id": id, "action": "wait", "text": text }),
                ));
            }

            // Check for --download flag: wait --download [path]
            if rest.iter().any(|&s| s == "--download" || s == "-d") {
                let mut cmd = json!({ "id": id, "action": "waitfordownload" });
                // Check for optional path (first non-flag argument after --download)
                let download_idx = rest
                    .iter()
                    .position(|&s| s == "--download" || s == "-d")
                    .unwrap();
                if let Some(path) = rest.get(download_idx + 1) {
                    if !path.starts_with("--") {
                        cmd["path"] = json!(path);
                    }
                }
                return Ok(with_timeout(cmd));
            }

            // Default: selector or timeout
            if let Some(arg) = rest.first() {
                if let Ok(timeout) = arg.parse::<u64>() {
                    Ok(json!({ "id": id, "action": "wait", "timeout": timeout }))
                } else {
                    let mut cmd = json!({ "id": id, "action": "wait", "selector": arg });
                    if let Some(state) = element_state {
                        cmd["state"] = json!(state);
                    }
                    Ok(with_timeout(cmd))
                }
            } else {
                Err(ParseError::MissingArguments {
                    context: "wait".to_string(),
                    usage: "wait <selector|ms|--url|--load|--fn|--text>",
                })
            }
        }

        // === Screenshot/PDF ===
        "screenshot" => {
            // screenshot [selector] [path] [--full/-f]
            // selector: @ref or CSS selector
            // path: file path (contains / or . or ends with known extension)
            let mut full_page = false;
            let mut if_changed = false;
            let mut threshold = None;
            let mut positional = Vec::new();
            let mut i = 0;
            while i < rest.len() {
                match rest[i] {
                    "--full" | "-f" => full_page = true,
                    "--if-changed" => if_changed = true,
                    "--threshold" => {
                        let raw = rest.get(i + 1).ok_or_else(|| ParseError::MissingArguments {
                            context: "screenshot --threshold".to_string(),
                            usage: "screenshot [selector] [path] [--if-changed] [--threshold <0-1>]",
                        })?;
                        let value = raw.parse::<f64>().map_err(|_| ParseError::InvalidValue {
                            message: format!(
                                "--threshold expects a number from 0 to 1, got '{}'",
                                raw
                            ),
                            usage:
                                "screenshot [selector] [path] [--if-changed] [--threshold <0-1>]",
                        })?;
                        if !(0.0..=1.0).contains(&value) {
                            return Err(ParseError::InvalidValue {
                                message: format!("--threshold must be from 0 to 1, got '{}'", raw),
                                usage: "screenshot [selector] [path] [--if-changed] [--threshold <0-1>]",
                            });
                        }
                        threshold = Some(value);
                        if_changed = true;
                        i += 1;
                    }
                    arg => positional.push(arg),
                }
                i += 1;
            }
            let (selector, path) = match (positional.first(), positional.get(1)) {
                (Some(first), Some(second)) => {
                    // Two args: first is selector, second is path
                    (Some(*first), Some(*second))
                }
                (Some(first), None) => {
                    // One arg: determine if it's a selector or a path
                    let is_relative_path = first.starts_with("./") || first.starts_with("../");
                    let is_selector = !is_relative_path
                        && (first.starts_with('.')
                            || first.starts_with('#')
                            || first.starts_with('@'));
                    let has_path_extension = first.ends_with(".png")
                        || first.ends_with(".jpg")
                        || first.ends_with(".jpeg")
                        || first.ends_with(".webp");
                    let is_path = is_relative_path || first.contains('/') || has_path_extension;
                    if is_selector || !is_path {
                        (Some(*first), None)
                    } else {
                        (None, Some(*first))
                    }
                }
                _ => (None, None),
            };
            let mut cmd = json!({
                "id": id, "action": "screenshot",
                "path": path, "selector": selector,
                "fullPage": full_page, "annotate": flags.annotate
            });
            if let Some(ref fmt) = flags.screenshot_format {
                cmd["format"] = json!(fmt);
            }
            if let Some(q) = flags.screenshot_quality {
                cmd["quality"] = json!(q);
                if flags.screenshot_format.as_deref() != Some("jpeg") {
                    eprintln!(
                        "{} --screenshot-quality is ignored for PNG; use --screenshot-format jpeg",
                        color::warning_indicator()
                    );
                }
            }
            if let Some(ref dir) = flags.screenshot_dir {
                cmd["screenshotDir"] = json!(dir);
            }
            if if_changed {
                cmd["ifChanged"] = json!(true);
            }
            if let Some(value) = threshold {
                cmd["threshold"] = json!(value);
            }
            Ok(cmd)
        }
        "pdf" => {
            let path = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "pdf".to_string(),
                usage: "pdf <path>",
            })?;
            Ok(json!({ "id": id, "action": "pdf", "path": path }))
        }

        // === Snapshot ===
        "snapshot" => {
            let mut cmd = json!({ "id": id, "action": "snapshot" });
            let obj = cmd.as_object_mut().unwrap();
            let mut i = 0;
            while i < rest.len() {
                match rest[i] {
                    "-i" | "--interactive" => {
                        obj.insert("interactive".to_string(), json!(true));
                    }
                    "-c" | "--compact" => {
                        obj.insert("compact".to_string(), json!(true));
                    }
                    "-C" | "--cursor" => {
                        obj.insert("cursor".to_string(), json!(true));
                    }
                    "-u" | "--urls" => {
                        obj.insert("urls".to_string(), json!(true));
                    }
                    "-d" | "--depth" => {
                        if let Some(d) = rest.get(i + 1) {
                            if let Ok(n) = d.parse::<i32>() {
                                obj.insert("maxDepth".to_string(), json!(n));
                                i += 1;
                            }
                        }
                    }
                    "-s" | "--selector" => {
                        if let Some(s) = rest.get(i + 1) {
                            obj.insert("selector".to_string(), json!(s));
                            i += 1;
                        }
                    }
                    "--delta" => {
                        obj.insert("delta".to_string(), json!(true));
                    }
                    "--full" => {
                        obj.insert("full".to_string(), json!(true));
                        obj.insert("delta".to_string(), json!(true));
                    }
                    _ => {}
                }
                i += 1;
            }
            Ok(cmd)
        }

        // === Eval ===
        "eval" => {
            // Check for flags: -b/--base64 or --stdin
            let (is_base64, is_stdin, script_parts): (bool, bool, &[&str]) =
                if rest.first() == Some(&"-b") || rest.first() == Some(&"--base64") {
                    (true, false, &rest[1..])
                } else if rest.first() == Some(&"--stdin") {
                    (false, true, &rest[1..])
                } else {
                    (false, false, rest.as_slice())
                };

            let script = if is_stdin {
                // Read script from stdin
                let stdin = io::stdin();
                let lines: Vec<String> = stdin
                    .lock()
                    .lines()
                    .map(|l| l.unwrap_or_default())
                    .collect();
                lines.join("\n")
            } else {
                let raw_script = script_parts.join(" ");
                if is_base64 {
                    let decoded =
                        STANDARD
                            .decode(&raw_script)
                            .map_err(|_| ParseError::InvalidValue {
                                message: "Invalid base64 encoding".to_string(),
                                usage: "eval -b <base64-encoded-script>",
                            })?;
                    String::from_utf8(decoded).map_err(|_| ParseError::InvalidValue {
                        message: "Base64 decoded to invalid UTF-8".to_string(),
                        usage: "eval -b <base64-encoded-script>",
                    })?
                } else {
                    raw_script
                }
            };
            Ok(json!({ "id": id, "action": "evaluate", "script": script }))
        }

        // === Close ===
        "close" | "quit" | "exit" => Ok(json!({ "id": id, "action": "close" })),

        // === Inspect ===
        "inspect" => Ok(json!({ "id": id, "action": "inspect" })),

        // === Authentication Vault ===
        "auth" => {
            let sub = rest.first().map(|s| s.as_ref());
            match sub {
                Some("save") => {
                    let name = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                        context: "auth save".to_string(),
                        usage: "agent-browser auth save <name> --url <url> --username <user> --password <pass>",
                    })?;

                    let mut url = None;
                    let mut username = None;
                    let mut password = None;
                    let mut password_stdin = false;
                    let mut username_selector = None;
                    let mut password_selector = None;
                    let mut submit_selector = None;

                    let mut j = 2;
                    while j < rest.len() {
                        match rest[j] {
                            "--url" => {
                                url = rest.get(j + 1).cloned();
                                j += 1;
                            }
                            "--username" => {
                                username = rest.get(j + 1).cloned();
                                j += 1;
                            }
                            "--password" => {
                                password = rest.get(j + 1).cloned();
                                j += 1;
                            }
                            "--password-stdin" => {
                                password_stdin = true;
                            }
                            "--username-selector" => {
                                username_selector = rest.get(j + 1).cloned();
                                j += 1;
                            }
                            "--password-selector" => {
                                password_selector = rest.get(j + 1).cloned();
                                j += 1;
                            }
                            "--submit-selector" => {
                                submit_selector = rest.get(j + 1).cloned();
                                j += 1;
                            }
                            other => {
                                if other.starts_with("--") {
                                    return Err(ParseError::InvalidValue {
                                        message: format!("unknown flag '{}' for auth save", other),
                                        usage: "agent-browser auth save <name> --url <url> --username <user> --password <pass>",
                                    });
                                }
                            }
                        }
                        j += 1;
                    }

                    let url_val = url.ok_or_else(|| ParseError::MissingArguments {
                        context: "auth save".to_string(),
                        usage: "agent-browser auth save <name> --url <url> --username <user> --password <pass> [--password-stdin]",
                    })?;
                    let user_val = username.ok_or_else(|| ParseError::MissingArguments {
                        context: "auth save".to_string(),
                        usage: "agent-browser auth save <name> --url <url> --username <user> --password <pass> [--password-stdin]",
                    })?;

                    if !password_stdin && password.is_none() {
                        return Err(ParseError::MissingArguments {
                            context: "auth save".to_string(),
                            usage: "agent-browser auth save <name> --url <url> --username <user> --password <pass> [--password-stdin]",
                        });
                    }

                    let mut cmd = json!({
                        "id": id,
                        "action": "auth_save",
                        "name": name,
                        "url": url_val,
                        "username": user_val,
                    });
                    if password_stdin {
                        cmd["passwordStdin"] = json!(true);
                    }
                    if let Some(pass_val) = password {
                        cmd["password"] = json!(pass_val);
                    }
                    if let Some(us) = username_selector {
                        cmd["usernameSelector"] = json!(us);
                    }
                    if let Some(ps) = password_selector {
                        cmd["passwordSelector"] = json!(ps);
                    }
                    if let Some(ss) = submit_selector {
                        cmd["submitSelector"] = json!(ss);
                    }
                    Ok(cmd)
                }
                Some("login") => {
                    const AUTH_LOGIN_USAGE: &str = "agent-browser auth login <name> [--no-navigate] [--credential-provider <plugin>] [--item <ref>] [--url <url>] [--username-selector <s>] [--password-selector <s>] [--submit-selector <s>]";
                    let name = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                        context: "auth login".to_string(),
                        usage: AUTH_LOGIN_USAGE,
                    })?;
                    let mut credential_provider: Option<String> = None;
                    let mut credential_item: Option<String> = None;
                    let mut url: Option<String> = None;
                    let mut username_selector: Option<String> = None;
                    let mut password_selector: Option<String> = None;
                    let mut submit_selector: Option<String> = None;
                    let mut no_navigate = false;

                    let mut j = 2;
                    while j < rest.len() {
                        match rest[j] {
                            "--no-navigate" => {
                                if rest
                                    .get(j + 1)
                                    .is_some_and(|value| !value.starts_with("--"))
                                {
                                    return Err(ParseError::InvalidValue {
                                        message: "--no-navigate does not accept a value"
                                            .to_string(),
                                        usage: AUTH_LOGIN_USAGE,
                                    });
                                }
                                no_navigate = true;
                            }
                            "--credential-provider" => {
                                let Some(value) = rest.get(j + 1).filter(|v| !v.starts_with("--"))
                                else {
                                    return Err(ParseError::MissingArguments {
                                        context: "auth login --credential-provider".to_string(),
                                        usage: AUTH_LOGIN_USAGE,
                                    });
                                };
                                credential_provider = Some((*value).to_string());
                                j += 1;
                            }
                            "--item" => {
                                let Some(value) = rest.get(j + 1).filter(|v| !v.starts_with("--"))
                                else {
                                    return Err(ParseError::MissingArguments {
                                        context: "auth login --item".to_string(),
                                        usage: AUTH_LOGIN_USAGE,
                                    });
                                };
                                credential_item = Some((*value).to_string());
                                j += 1;
                            }
                            "--url" => {
                                let Some(value) = rest.get(j + 1).filter(|v| !v.starts_with("--"))
                                else {
                                    return Err(ParseError::MissingArguments {
                                        context: "auth login --url".to_string(),
                                        usage: AUTH_LOGIN_USAGE,
                                    });
                                };
                                url = Some((*value).to_string());
                                j += 1;
                            }
                            "--username-selector" => {
                                let Some(value) = rest.get(j + 1).filter(|v| !v.starts_with("--"))
                                else {
                                    return Err(ParseError::MissingArguments {
                                        context: "auth login --username-selector".to_string(),
                                        usage: AUTH_LOGIN_USAGE,
                                    });
                                };
                                username_selector = Some((*value).to_string());
                                j += 1;
                            }
                            "--password-selector" => {
                                let Some(value) = rest.get(j + 1).filter(|v| !v.starts_with("--"))
                                else {
                                    return Err(ParseError::MissingArguments {
                                        context: "auth login --password-selector".to_string(),
                                        usage: AUTH_LOGIN_USAGE,
                                    });
                                };
                                password_selector = Some((*value).to_string());
                                j += 1;
                            }
                            "--submit-selector" => {
                                let Some(value) = rest.get(j + 1).filter(|v| !v.starts_with("--"))
                                else {
                                    return Err(ParseError::MissingArguments {
                                        context: "auth login --submit-selector".to_string(),
                                        usage: AUTH_LOGIN_USAGE,
                                    });
                                };
                                submit_selector = Some((*value).to_string());
                                j += 1;
                            }
                            other => {
                                if other.starts_with("--") {
                                    return Err(ParseError::InvalidValue {
                                        message: format!("unknown flag '{}' for auth login", other),
                                        usage: AUTH_LOGIN_USAGE,
                                    });
                                }
                            }
                        }
                        j += 1;
                    }

                    let mut cmd = json!({ "id": id, "action": "auth_login", "name": name });
                    if let Some(provider) = credential_provider {
                        cmd["credentialProvider"] = json!(provider);
                    }
                    if let Some(item) = credential_item {
                        cmd["credentialItem"] = json!(item);
                    }
                    if let Some(url) = url {
                        cmd["url"] = json!(url);
                    }
                    if let Some(us) = username_selector {
                        cmd["usernameSelector"] = json!(us);
                    }
                    if let Some(ps) = password_selector {
                        cmd["passwordSelector"] = json!(ps);
                    }
                    if let Some(ss) = submit_selector {
                        cmd["submitSelector"] = json!(ss);
                    }
                    if no_navigate {
                        // Invocation-only behavior. This is intentionally not
                        // stored in AuthProfile or credential provider data.
                        cmd["noNavigate"] = json!(true);
                    }
                    Ok(cmd)
                }
                Some("list") => Ok(json!({ "id": id, "action": "auth_list" })),
                Some("delete") | Some("remove") => {
                    let name = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                        context: "auth delete".to_string(),
                        usage: "agent-browser auth delete <name>",
                    })?;
                    Ok(json!({ "id": id, "action": "auth_delete", "name": name }))
                }
                Some("show") => {
                    let name = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                        context: "auth show".to_string(),
                        usage: "agent-browser auth show <name>",
                    })?;
                    Ok(json!({ "id": id, "action": "auth_show", "name": name }))
                }
                _ => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.unwrap_or("(none)").to_string(),
                    valid_options: &["save", "login", "list", "delete", "show"],
                }),
            }
        }

        // === Action Confirmation ===
        "confirm" => {
            let cid = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "confirm".to_string(),
                usage: "agent-browser confirm <confirmation-id>",
            })?;
            Ok(json!({ "id": id, "action": "confirm", "confirmationId": cid }))
        }
        "deny" => {
            let cid = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "deny".to_string(),
                usage: "agent-browser deny <confirmation-id>",
            })?;
            Ok(json!({ "id": id, "action": "deny", "confirmationId": cid }))
        }

        // === Connect (CDP) ===
        "connect" => {
            let endpoint = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "connect".to_string(),
                usage: "connect <port|url>",
            })?;
            // Check if it's a URL (ws://, wss://, http://, https://)
            if endpoint.starts_with("ws://")
                || endpoint.starts_with("wss://")
                || endpoint.starts_with("http://")
                || endpoint.starts_with("https://")
            {
                let mut cmd = json!({ "id": id, "action": "launch", "cdpUrl": endpoint });
                if let Some(ref raw) = flags.cdp_headers {
                    cmd["cdpHeaders"] =
                        parse_cdp_headers(raw).map_err(|message| ParseError::InvalidValue {
                            message,
                            usage: r#"connect <url> --cdp-headers '{"Authorization":"Bearer <token>"}'"#,
                        })?;
                }
                Ok(cmd)
            } else {
                // It's a port number - validate and use cdpPort field
                let port: u16 = match endpoint.parse::<u32>() {
                    Ok(0) => {
                        return Err(ParseError::InvalidValue {
                            message: "Invalid port: port must be greater than 0".to_string(),
                            usage: "connect <port|url>",
                        });
                    }
                    Ok(p) if p > 65535 => {
                        return Err(ParseError::InvalidValue {
                            message: format!(
                                "Invalid port: {} is out of range (valid range: 1-65535)",
                                p
                            ),
                            usage: "connect <port|url>",
                        });
                    }
                    Ok(p) => p as u16,
                    Err(_) => {
                        return Err(ParseError::InvalidValue {
                            message: format!(
                                "Invalid value: '{}' is not a valid port number or URL",
                                endpoint
                            ),
                            usage: "connect <port|url>",
                        });
                    }
                };
                let mut cmd = json!({ "id": id, "action": "launch", "cdpPort": port });
                if let Some(ref raw) = flags.cdp_headers {
                    cmd["cdpHeaders"] =
                        parse_cdp_headers(raw).map_err(|message| ParseError::InvalidValue {
                            message,
                            usage: r#"connect <port> --cdp-headers '{"Authorization":"Bearer <token>"}'"#,
                        })?;
                }
                Ok(cmd)
            }
        }

        // === Runtime stream control ===
        "stream" => match rest.first().copied() {
            Some("enable") => {
                let mut cmd = json!({ "id": id, "action": "stream_enable" });
                let mut i = 1;
                while i < rest.len() {
                    match rest[i] {
                        "--port" => {
                            let value =
                                rest.get(i + 1)
                                    .ok_or_else(|| ParseError::MissingArguments {
                                        context: "stream enable --port".to_string(),
                                        usage: "stream enable [--port <port>]",
                                    })?;
                            let port =
                                value.parse::<u32>().map_err(|_| ParseError::InvalidValue {
                                    message: format!(
                                        "Invalid port: '{}' is not a valid integer",
                                        value
                                    ),
                                    usage: "stream enable [--port <port>]",
                                })?;
                            if port > u16::MAX as u32 {
                                return Err(ParseError::InvalidValue {
                                    message: format!(
                                        "Invalid port: {} is out of range (valid range: 0-65535)",
                                        port
                                    ),
                                    usage: "stream enable [--port <port>]",
                                });
                            }
                            cmd["port"] = json!(port);
                            i += 2;
                        }
                        flag => {
                            return Err(ParseError::InvalidValue {
                                message: format!("Unknown flag for stream enable: {}", flag),
                                usage: "stream enable [--port <port>]",
                            });
                        }
                    }
                }
                Ok(cmd)
            }
            Some("disable") => Ok(json!({ "id": id, "action": "stream_disable" })),
            Some("status") => Ok(json!({ "id": id, "action": "stream_status" })),
            Some(sub) => Err(ParseError::UnknownSubcommand {
                subcommand: sub.to_string(),
                valid_options: &["enable", "disable", "status"],
            }),
            None => Err(ParseError::MissingArguments {
                context: "stream".to_string(),
                usage: "stream <enable|disable|status>",
            }),
        },

        // === Get ===
        "get" => parse_get(&rest, &id),

        // === Is (state checks) ===
        "is" => parse_is(&rest, &id),

        // === Find (locators) ===
        "find" => parse_find(&rest, &id),

        // === Mouse ===
        "mouse" => parse_mouse(&rest, &id),

        // === Set (browser settings) ===
        "set" => parse_set(&rest, &id),

        // === Network ===
        "network" => parse_network(&rest, &id),

        // === Storage ===
        "storage" => parse_storage(&rest, &id),

        // === Cookies ===
        "cookies" => {
            const COOKIES_SET_USAGE: &str = "cookies set <name> <value> [--url <url>] [--domain <domain>] [--path <path>] [--http-only] [--secure] [--same-site <Strict|Lax|None>] [--expires <timestamp>]\n  or:  cookies set --curl <file> [--domain <domain>] [--url <url>]";
            let op = rest.first().unwrap_or(&"get");
            match *op {
                "set" => {
                    // --curl <file> mode: import cookies from a JSON array,
                    // raw cURL dump, or bare Cookie header. Scoped to the
                    // host of --domain if provided; otherwise the cookies
                    // have no scope (daemon falls back to current origin).
                    if let Some(curl_idx) = rest.iter().position(|a| *a == "--curl") {
                        let path =
                            rest.get(curl_idx + 1)
                                .ok_or_else(|| {
                                    ParseError::MissingArguments {
                            context: "cookies set --curl".to_string(),
                            usage: "cookies set --curl <file> [--domain <domain>] [--url <url>]",
                        }
                                })?;
                        let raw = std::fs::read_to_string(path).map_err(|e| {
                            ParseError::InvalidValue {
                                message: format!("cookies --curl: cannot read '{}': {}", path, e),
                                usage: "cookies set --curl <file>",
                            }
                        })?;
                        let mut cookies =
                            parse_curl_cookies(&raw).map_err(|e| ParseError::InvalidValue {
                                message: format!("cookies --curl: {}", e),
                                usage: "cookies set --curl <file>",
                            })?;

                        let domain_idx = rest.iter().position(|a| *a == "--domain");
                        let domain = domain_idx.and_then(|i| rest.get(i + 1).copied());
                        let url_idx = rest.iter().position(|a| *a == "--url");
                        let url = url_idx.and_then(|i| rest.get(i + 1).copied());

                        for cookie in cookies.iter_mut() {
                            if let Some(d) = domain {
                                cookie["domain"] = json!(d);
                                cookie["path"] = cookie.get("path").cloned().unwrap_or(json!("/"));
                            }
                            if let Some(u) = url {
                                cookie["url"] = json!(u);
                            }
                        }

                        return Ok(json!({
                            "id": id,
                            "action": "cookies_set",
                            "cookies": cookies,
                        }));
                    }

                    let name = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                        context: "cookies set".to_string(),
                        usage: COOKIES_SET_USAGE,
                    })?;
                    let value = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
                        context: "cookies set".to_string(),
                        usage: COOKIES_SET_USAGE,
                    })?;

                    let mut cookie = json!({ "name": name, "value": value });

                    // Parse optional flags
                    let mut i = 3;
                    while i < rest.len() {
                        match rest[i] {
                            "--url" => {
                                if let Some(url) = rest.get(i + 1) {
                                    cookie["url"] = json!(url);
                                    i += 2;
                                } else {
                                    return Err(ParseError::MissingArguments {
                                        context: "cookies set --url".to_string(),
                                        usage: "--url <url>",
                                    });
                                }
                            }
                            "--domain" => {
                                if let Some(domain) = rest.get(i + 1) {
                                    cookie["domain"] = json!(domain);
                                    i += 2;
                                } else {
                                    return Err(ParseError::MissingArguments {
                                        context: "cookies set --domain".to_string(),
                                        usage: "--domain <domain>",
                                    });
                                }
                            }
                            "--path" => {
                                if let Some(path) = rest.get(i + 1) {
                                    cookie["path"] = json!(path);
                                    i += 2;
                                } else {
                                    return Err(ParseError::MissingArguments {
                                        context: "cookies set --path".to_string(),
                                        usage: "--path <path>",
                                    });
                                }
                            }
                            "--http-only" | "--httpOnly" => {
                                cookie["httpOnly"] = json!(true);
                                i += 1;
                            }
                            "--secure" => {
                                cookie["secure"] = json!(true);
                                i += 1;
                            }
                            "--same-site" | "--sameSite" => {
                                if let Some(same_site) = rest.get(i + 1) {
                                    // Validate sameSite value
                                    if *same_site == "Strict"
                                        || *same_site == "Lax"
                                        || *same_site == "None"
                                    {
                                        cookie["sameSite"] = json!(same_site);
                                        i += 2;
                                    } else {
                                        return Err(ParseError::MissingArguments {
                                            context: "cookies set --same-site".to_string(),
                                            usage: "--same-site <Strict|Lax|None>",
                                        });
                                    }
                                } else {
                                    return Err(ParseError::MissingArguments {
                                        context: "cookies set --same-site".to_string(),
                                        usage: "--same-site <Strict|Lax|None>",
                                    });
                                }
                            }
                            "--expires" => {
                                if let Some(expires_str) = rest.get(i + 1) {
                                    if let Ok(expires) = expires_str.parse::<i64>() {
                                        cookie["expires"] = json!(expires);
                                        i += 2;
                                    } else {
                                        return Err(ParseError::MissingArguments {
                                            context: "cookies set --expires".to_string(),
                                            usage: "--expires <timestamp>",
                                        });
                                    }
                                } else {
                                    return Err(ParseError::MissingArguments {
                                        context: "cookies set --expires".to_string(),
                                        usage: "--expires <timestamp>",
                                    });
                                }
                            }
                            other => {
                                let message = if other.starts_with("--") {
                                    format!("cookies set: unknown flag '{}'", other)
                                } else {
                                    "cookies set: unexpected argument".to_string()
                                };
                                return Err(ParseError::InvalidValue {
                                    message,
                                    usage: COOKIES_SET_USAGE,
                                });
                            }
                        }
                    }

                    Ok(json!({ "id": id, "action": "cookies_set", "cookies": [cookie] }))
                }
                "clear" => Ok(json!({ "id": id, "action": "cookies_clear" })),
                _ => Ok(json!({ "id": id, "action": "cookies_get" })),
            }
        }

        // === Tabs ===
        "tab" => {
            match rest.first().copied() {
                Some("new") => {
                    // Accepted forms:
                    //   tab new [url]
                    //   tab new --label <name> [url]
                    //   tab new [url] --label <name>
                    let mut cmd = json!({ "id": id, "action": "tab_new" });
                    let mut i = 1;
                    while i < rest.len() {
                        match rest[i] {
                            "--label" => {
                                let name = rest.get(i + 1).ok_or(ParseError::MissingArguments {
                                    context: "tab new --label".to_string(),
                                    usage: "tab new --label <name> [url]",
                                })?;
                                cmd["label"] = json!(name);
                                i += 2;
                            }
                            other if !other.starts_with("--") && cmd.get("url").is_none() => {
                                cmd["url"] = json!(other);
                                i += 1;
                            }
                            other => {
                                return Err(ParseError::UnknownSubcommand {
                                    subcommand: other.to_string(),
                                    valid_options: &["--label", "<url>"],
                                });
                            }
                        }
                    }
                    Ok(cmd)
                }
                Some("list") => Ok(json!({ "id": id, "action": "tab_list" })),
                Some("close") => {
                    let mut cmd = json!({ "id": id, "action": "tab_close" });
                    if let Some(tab_ref) = rest.get(1) {
                        cmd["tabId"] = json!(tab_ref);
                    }
                    Ok(cmd)
                }
                Some(tab_ref) => Ok(json!({
                    "id": id,
                    "action": "tab_switch",
                    "tabId": tab_ref,
                })),
                None => Ok(json!({ "id": id, "action": "tab_list" })),
            }
        }

        // === Window ===
        "window" => {
            const VALID: &[&str] = &["new"];
            match rest.first().copied() {
                Some("new") => Ok(json!({ "id": id, "action": "window_new" })),
                Some(sub) => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.to_string(),
                    valid_options: VALID,
                }),
                None => Err(ParseError::MissingArguments {
                    context: "window".to_string(),
                    usage: "window <new>",
                }),
            }
        }

        // === Frame ===
        "frame" => {
            if rest.first().copied() == Some("main") {
                Ok(json!({ "id": id, "action": "mainframe" }))
            } else {
                let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                    context: "frame".to_string(),
                    usage: "frame <selector|main>",
                })?;
                Ok(json!({ "id": id, "action": "frame", "selector": sel }))
            }
        }

        // === Dialog ===
        "dialog" => {
            const VALID: &[&str] = &["accept", "dismiss", "status"];
            match rest.first().copied() {
                Some("accept") => {
                    let mut cmd = json!({ "id": id, "action": "dialog", "response": "accept" });
                    if let Some(prompt_text) = rest.get(1) {
                        cmd["promptText"] = json!(prompt_text);
                    }
                    Ok(cmd)
                }
                Some("dismiss") => {
                    let mut cmd = json!({ "id": id, "action": "dialog", "response": "dismiss" });
                    if let Some(prompt_text) = rest.get(1) {
                        cmd["promptText"] = json!(prompt_text);
                    }
                    Ok(cmd)
                }
                Some("status") => Ok(json!({ "id": id, "action": "dialog", "response": "status" })),
                Some(sub) => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.to_string(),
                    valid_options: VALID,
                }),
                None => Err(ParseError::MissingArguments {
                    context: "dialog".to_string(),
                    usage: "dialog <accept|dismiss|status> [text]",
                }),
            }
        }

        // === Debug ===
        "trace" => {
            const VALID: &[&str] = &["start", "stop"];
            match rest.first().copied() {
                Some("start") => Ok(json!({ "id": id, "action": "trace_start" })),
                Some("stop") => {
                    let mut cmd = json!({ "id": id, "action": "trace_stop" });
                    if let Some(path) = rest.get(1) {
                        cmd["path"] = json!(path);
                    }
                    Ok(cmd)
                }
                Some(sub) => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.to_string(),
                    valid_options: VALID,
                }),
                None => Err(ParseError::MissingArguments {
                    context: "trace".to_string(),
                    usage: "trace <start|stop> [path]",
                }),
            }
        }

        // === Profiler (CDP Tracing / Chromium profiling) ===
        "profiler" => {
            const VALID: &[&str] = &["start", "stop"];
            match rest.first().copied() {
                Some("start") => {
                    let mut cmd = json!({ "id": id, "action": "profiler_start" });
                    if let Some(idx) = rest.iter().position(|s| *s == "--categories") {
                        if let Some(cats) = rest.get(idx + 1) {
                            let categories: Vec<&str> = cats.split(',').collect();
                            cmd["categories"] = json!(categories);
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "profiler start --categories".to_string(),
                                usage: "--categories <list>",
                            });
                        }
                    }
                    Ok(cmd)
                }
                Some("stop") => {
                    let mut cmd = json!({ "id": id, "action": "profiler_stop" });
                    if let Some(path) = rest.get(1) {
                        cmd["path"] = json!(path);
                    }
                    Ok(cmd)
                }
                Some(sub) => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.to_string(),
                    valid_options: VALID,
                }),
                None => Err(ParseError::MissingArguments {
                    context: "profiler".to_string(),
                    usage: "profiler <start|stop> [options]",
                }),
            }
        }

        // === Recording (browser video recording) ===
        "record" => {
            const VALID: &[&str] = &["start", "stop", "restart"];
            match rest.first().copied() {
                Some("start") => parse_record_take(
                    &id,
                    "recording_start",
                    &rest[1..],
                    "record start",
                    "record start <output.webm|output.mp4> [url] [--fps <n>] [--cursor] [--contact-sheet] [--contact-sheet-threshold <0-1>]",
                ),
                Some("stop") => Ok(json!({ "id": id, "action": "recording_stop" })),
                Some("restart") => parse_record_take(
                    &id,
                    "recording_restart",
                    &rest[1..],
                    "record restart",
                    "record restart <output.webm|output.mp4> [url] [--fps <n>] [--cursor] [--contact-sheet] [--contact-sheet-threshold <0-1>]",
                ),
                Some(sub) => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.to_string(),
                    valid_options: VALID,
                }),
                None => Err(ParseError::MissingArguments {
                    context: "record".to_string(),
                    usage: "record <start|stop|restart> [path] [url] [--fps <n>]",
                }),
            }
        }
        "console" => {
            let clear = rest.contains(&"--clear");
            Ok(json!({ "id": id, "action": "console", "clear": clear }))
        }
        "errors" => {
            let clear = rest.contains(&"--clear");
            Ok(json!({ "id": id, "action": "errors", "clear": clear }))
        }
        "highlight" => {
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "highlight".to_string(),
                usage: "highlight <selector>",
            })?;
            Ok(json!({ "id": id, "action": "highlight", "selector": sel }))
        }

        // === Clipboard ===
        "clipboard" => match rest.first().copied() {
            Some("read") | None => {
                Ok(json!({ "id": id, "action": "clipboard", "operation": "read" }))
            }
            Some("write") => {
                rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                    context: "clipboard write".to_string(),
                    usage: "clipboard write <text>",
                })?;
                let text = rest[1..].join(" ");
                Ok(json!({ "id": id, "action": "clipboard", "operation": "write", "text": text }))
            }
            Some("copy") => Ok(json!({ "id": id, "action": "clipboard", "operation": "copy" })),
            Some("paste") => Ok(json!({ "id": id, "action": "clipboard", "operation": "paste" })),
            Some(sub) => Err(ParseError::UnknownSubcommand {
                subcommand: sub.to_string(),
                valid_options: &["read", "write", "copy", "paste"],
            }),
        },

        // === State ===
        "state" => {
            const VALID: &[&str] = &["save", "load", "list", "clear", "show", "clean", "rename"];
            match rest.first().copied() {
                Some("save") => {
                    let path = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                        context: "state save".to_string(),
                        usage: "state save <path>",
                    })?;
                    Ok(json!({ "id": id, "action": "state_save", "path": path }))
                }
                Some("load") => {
                    let path = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                        context: "state load".to_string(),
                        usage: "state load <path>",
                    })?;
                    Ok(json!({ "id": id, "action": "state_load", "path": path }))
                }
                Some("list") => Ok(json!({ "id": id, "action": "state_list" })),
                Some("clear") => {
                    let mut session_name: Option<&str> = None;
                    let mut all = false;

                    let mut i = 1;
                    while i < rest.len() {
                        match rest[i] {
                            "--all" | "-a" => {
                                all = true;
                            }
                            arg if !arg.starts_with('-') => {
                                session_name = Some(arg);
                            }
                            _ => {}
                        }
                        i += 1;
                    }

                    if let Some(name) = session_name {
                        if !is_valid_session_name(name) {
                            return Err(ParseError::InvalidSessionName {
                                name: name.to_string(),
                            });
                        }
                    }

                    let mut cmd = json!({ "id": id, "action": "state_clear" });
                    if all {
                        cmd["all"] = json!(true);
                    }
                    if let Some(name) = session_name {
                        cmd["sessionName"] = json!(name);
                    }
                    Ok(cmd)
                }
                Some("show") => {
                    let filename = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                        context: "state show".to_string(),
                        usage: "state show <filename>",
                    })?;
                    Ok(json!({ "id": id, "action": "state_show", "path": filename }))
                }
                Some("clean") => {
                    let mut days: Option<i64> = None;

                    let mut i = 1;
                    while i < rest.len() {
                        if rest[i] == "--older-than" {
                            if let Some(d) = rest.get(i + 1) {
                                days = d.parse().ok();
                                i += 1;
                            }
                        }
                        i += 1;
                    }

                    let days = days.ok_or_else(|| ParseError::MissingArguments {
                        context: "state clean".to_string(),
                        usage: "state clean --older-than <days>",
                    })?;

                    Ok(json!({ "id": id, "action": "state_clean", "days": days }))
                }
                Some("rename") => {
                    let old_name = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                        context: "state rename".to_string(),
                        usage: "state rename <old-name> <new-name>",
                    })?;
                    let new_name = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
                        context: "state rename".to_string(),
                        usage: "state rename <old-name> <new-name>",
                    })?;
                    let old_name = old_name.trim_end_matches(".json");
                    let new_name = new_name.trim_end_matches(".json");

                    if !is_valid_session_name(old_name) {
                        return Err(ParseError::InvalidSessionName {
                            name: old_name.to_string(),
                        });
                    }
                    if !is_valid_session_name(new_name) {
                        return Err(ParseError::InvalidSessionName {
                            name: new_name.to_string(),
                        });
                    }

                    Ok(
                        json!({ "id": id, "action": "state_rename", "oldName": old_name, "newName": new_name }),
                    )
                }
                Some(sub) => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.to_string(),
                    valid_options: VALID,
                }),
                None => Err(ParseError::MissingArguments {
                    context: "state".to_string(),
                    usage: "state <save|load|list|clear|show|clean|rename> ...",
                }),
            }
        }

        // === iOS-specific commands ===
        "tap" => {
            // Alias for click (semantic clarity for touch interfaces)
            let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "tap".to_string(),
                usage: "tap <selector>",
            })?;
            Ok(json!({ "id": id, "action": "tap", "selector": sel }))
        }
        "swipe" => {
            let direction = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "swipe".to_string(),
                usage: "swipe <up|down|left|right> [distance]",
            })?;
            let valid_directions = ["up", "down", "left", "right"];
            if !valid_directions.contains(direction) {
                return Err(ParseError::InvalidValue {
                    message: format!("Invalid swipe direction: {}", direction),
                    usage: "swipe <up|down|left|right> [distance]",
                });
            }
            let mut cmd = json!({ "id": id, "action": "swipe", "direction": direction });
            if let Some(distance) = rest.get(1) {
                if let Ok(d) = distance.parse::<u32>() {
                    cmd.as_object_mut()
                        .unwrap()
                        .insert("distance".to_string(), json!(d));
                }
            }
            Ok(cmd)
        }
        "device" => {
            match rest.first().copied() {
                Some("list") | None => {
                    // List available iOS simulators
                    Ok(json!({ "id": id, "action": "device_list" }))
                }
                Some(sub) => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.to_string(),
                    valid_options: &["list"],
                }),
            }
        }

        "diff" => parse_diff(&rest, &id),

        // === Batch ===
        "batch" => {
            let bail = rest.contains(&"--bail");
            let omit_command = rest.contains(&"--omit-command");
            let commands: Vec<&str> = rest
                .iter()
                .filter(|a| **a != "--bail" && **a != "--omit-command")
                .copied()
                .collect();
            let mut cmd =
                json!({ "id": id, "action": "batch", "bail": bail, "omitCommand": omit_command });
            if !commands.is_empty() {
                cmd["commands"] = json!(commands);
            }
            Ok(cmd)
        }

        // === React (requires `open --enable react-devtools`) ===
        "react" => parse_react(&rest, &id),

        // === Core Web Vitals + hydration ===
        "vitals" | "web-vitals" => {
            let mut cmd = json!({ "id": id, "action": "vitals" });
            let json_out = rest.contains(&"--json");
            if json_out {
                cmd["json"] = json!(true);
            }
            if let Some(url) = rest.iter().find(|a| !a.starts_with("--")) {
                cmd["url"] = json!(url);
            }
            Ok(cmd)
        }

        // === Accessibility audit (axe-core) ===
        "a11y" => {
            const A11Y_USAGE: &str = "a11y [url] [--tags <tag1,tag2>] [--selector <css>] [--json]";
            let mut cmd = json!({ "id": id, "action": "a11y" });
            let mut i = 0;
            while i < rest.len() {
                match rest[i] {
                    "--tags" => {
                        i += 1;
                        let value = rest
                            .get(i)
                            .copied()
                            .filter(|value| {
                                !matches!(*value, "--tags" | "--selector" | "-s" | "--json")
                            })
                            .ok_or(ParseError::MissingArguments {
                                context: "a11y --tags".to_string(),
                                usage: A11Y_USAGE,
                            })?;
                        cmd["tags"] = json!(value);
                    }
                    "--selector" | "-s" => {
                        i += 1;
                        let value = rest
                            .get(i)
                            .copied()
                            .filter(|value| {
                                !matches!(*value, "--tags" | "--selector" | "-s" | "--json")
                            })
                            .ok_or(ParseError::MissingArguments {
                                context: "a11y --selector".to_string(),
                                usage: A11Y_USAGE,
                            })?;
                        cmd["selector"] = json!(value);
                    }
                    "--json" => {
                        cmd["json"] = json!(true);
                    }
                    other if !other.starts_with('-') => {
                        if cmd.get("url").is_some() {
                            return Err(ParseError::InvalidValue {
                                message: format!("Unexpected argument: {}", other),
                                usage: A11Y_USAGE,
                            });
                        }
                        cmd["url"] = json!(normalize_navigation_url(other));
                    }
                    other => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unknown flag: {}", other),
                            usage: A11Y_USAGE,
                        });
                    }
                }
                i += 1;
            }
            Ok(cmd)
        }

        // === SPA client-side navigation ===
        "pushstate" => {
            let url = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "pushstate".to_string(),
                usage: "pushstate <url>",
            })?;
            Ok(json!({ "id": id, "action": "pushstate", "url": url }))
        }

        // === Remove init script ===
        "removeinitscript" => {
            let identifier = rest.first().ok_or_else(|| ParseError::MissingArguments {
                context: "removeinitscript".to_string(),
                usage: "removeinitscript <identifier>",
            })?;
            Ok(json!({ "id": id, "action": "removeinitscript", "identifier": identifier }))
        }

        _ => Err(ParseError::UnknownCommand {
            command: cmd.to_string(),
        }),
    }
}

fn parse_webmcp(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    let subcommand = rest.first().ok_or_else(|| ParseError::MissingArguments {
        context: "webmcp".to_string(),
        usage: "webmcp <list|invoke|result|cancel>",
    })?;
    match *subcommand {
        "list" => {
            let mut command = json!({"id": id, "action": "webmcp_list"});
            let mut i = 1;
            while i < rest.len() {
                match rest[i] {
                    "--frame" if rest.get(i + 1).is_some_and(|v| !v.starts_with("--")) => {
                        command["frameId"] = json!(rest[i + 1]);
                        i += 2;
                    }
                    name if !name.starts_with("--") && command.get("tool").is_none() => {
                        command["tool"] = json!(name);
                        i += 1;
                    }
                    argument => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unexpected argument for webmcp list: {}", argument),
                            usage: "webmcp list [tool] [--frame <frame-id>]",
                        })
                    }
                }
            }
            Ok(command)
        }
        "invoke" => {
            let tool = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "webmcp invoke".to_string(),
                usage: "webmcp invoke <tool> [--params <json|@file>] [--frame <frame-id>] [--detach] [--timeout <ms>]",
            })?;
            let mut command = json!({
                "id": id,
                "action": "webmcp_invoke",
                "tool": tool,
                "params": {},
            });
            let mut index = 2;
            while index < rest.len() {
                match rest[index] {
                    "--params" => {
                        let raw = rest.get(index + 1).ok_or_else(|| {
                            ParseError::MissingArguments {
                                context: "webmcp invoke --params".to_string(),
                                usage: "webmcp invoke <tool> [--params <json|@file>] [--frame <frame-id>] [--detach] [--timeout <ms>]",
                            }
                        })?;
                        let payload = if let Some(path) = raw.strip_prefix('@') {
                            let metadata =
                                std::fs::metadata(path).map_err(|error| ParseError::InvalidValue {
                                    message: format!(
                                        "Unable to read WebMCP params file '{}': {}",
                                        path, error
                                    ),
                                    usage: "webmcp invoke <tool> --params @input.json",
                                })?;
                            if metadata.len() as usize > crate::native::webmcp::MAX_INPUT_BYTES {
                                return Err(ParseError::InvalidValue {
                                    message: format!(
                                        "WebMCP params file is {} bytes; maximum is {} bytes",
                                        metadata.len(),
                                        crate::native::webmcp::MAX_INPUT_BYTES
                                    ),
                                    usage: "webmcp invoke <tool> --params @input.json",
                                });
                            }
                            std::fs::read_to_string(path).map_err(|error| {
                                ParseError::InvalidValue {
                                    message: format!(
                                        "Unable to read WebMCP params file '{}': {}",
                                        path, error
                                    ),
                                    usage: "webmcp invoke <tool> --params @input.json",
                                }
                            })?
                        } else {
                            raw.to_string()
                        };
                        let params: Value = serde_json::from_str(&payload).map_err(|error| {
                            ParseError::InvalidValue {
                                message: format!("Invalid JSON for --params: {}", error),
                                usage: "webmcp invoke <tool> --params '{\"key\":\"value\"}'",
                            }
                        })?;
                        crate::native::webmcp::validate_input(&params).map_err(|message| {
                            ParseError::InvalidValue {
                                message,
                                usage: "webmcp invoke <tool> --params <json|@file>",
                            }
                        })?;
                        command["params"] = params;
                        index += 1;
                    }
                    "--frame" => {
                        let frame = rest.get(index + 1).ok_or_else(|| {
                            ParseError::MissingArguments {
                                context: "webmcp invoke --frame".to_string(),
                                usage: "webmcp invoke <tool> --frame <frame-id>",
                            }
                        })?;
                        command["frameId"] = json!(frame);
                        index += 1;
                    }
                    "--detach" => command["detach"] = json!(true),
                    "--timeout" => {
                        let raw = rest.get(index + 1).ok_or_else(|| {
                            ParseError::MissingArguments {
                                context: "webmcp invoke --timeout".to_string(),
                                usage: "webmcp invoke <tool> --timeout <ms>",
                            }
                        })?;
                        let timeout =
                            raw.parse::<u64>().map_err(|_| ParseError::InvalidValue {
                                message: format!(
                                    "--timeout expects a number in ms, got '{}'",
                                    raw
                                ),
                                usage: "webmcp invoke <tool> --timeout <ms>",
                            })?;
                        command["timeout"] = json!(timeout);
                        index += 1;
                    }
                    other => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unknown webmcp invoke option: {}", other),
                            usage: "webmcp invoke <tool> [--params <json|@file>] [--frame <frame-id>] [--detach] [--timeout <ms>]",
                        })
                    }
                }
                index += 1;
            }
            Ok(command)
        }
        "result" => {
            let invocation_id = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "webmcp result".to_string(),
                usage: "webmcp result <invocation-id> [--timeout <ms>]",
            })?;
            let mut command = json!({
                "id": id,
                "action": "webmcp_result",
                "invocationId": invocation_id,
            });
            let mut index = 2;
            while index < rest.len() {
                match rest[index] {
                    "--timeout" => {
                        let raw =
                            rest.get(index + 1)
                                .ok_or_else(|| ParseError::MissingArguments {
                                    context: "webmcp result --timeout".to_string(),
                                    usage: "webmcp result <invocation-id> --timeout <ms>",
                                })?;
                        command["timeout"] =
                            json!(raw.parse::<u64>().map_err(|_| ParseError::InvalidValue {
                                message: format!("--timeout expects a number in ms, got '{}'", raw),
                                usage: "webmcp result <invocation-id> --timeout <ms>",
                            })?);
                        index += 1;
                    }
                    other => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unknown webmcp result option: {}", other),
                            usage: "webmcp result <invocation-id> [--timeout <ms>]",
                        });
                    }
                }
                index += 1;
            }
            Ok(command)
        }
        "cancel" => {
            let invocation_id = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "webmcp cancel".to_string(),
                usage: "webmcp cancel <invocation-id>",
            })?;
            if let Some(argument) = rest.get(2) {
                return Err(ParseError::InvalidValue {
                    message: format!("Unexpected argument for webmcp cancel: {}", argument),
                    usage: "webmcp cancel <invocation-id>",
                });
            }
            Ok(json!({
                "id": id,
                "action": "webmcp_cancel",
                "invocationId": invocation_id,
            }))
        }
        _ => Err(ParseError::UnknownSubcommand {
            subcommand: subcommand.to_string(),
            valid_options: &["list", "invoke", "result", "cancel"],
        }),
    }
}

fn parse_read(rest: &[&str], id: &str, flags: &Flags) -> Result<Value, ParseError> {
    const READ_USAGE: &str =
        "read [url] [--raw] [--require-md] [--llms <index|full>] [--outline] [--filter <text>] [--timeout <ms>]";
    let mut cmd = json!({
        "id": id,
        "action": "read",
        "timeout": crate::read::default_timeout_ms(),
    });
    let mut url: Option<&str> = None;
    let mut i = 0;
    while i < rest.len() {
        match rest[i] {
            "--raw" => {
                cmd["raw"] = json!(true);
            }
            "--require-md" => {
                cmd["requireMd"] = json!(true);
            }
            "--llms" => {
                let value = rest
                    .get(i + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: "read --llms".to_string(),
                        usage: READ_USAGE,
                    })?;
                crate::read::parse_llms_mode(value).map_err(|message| {
                    ParseError::InvalidValue {
                        message,
                        usage: READ_USAGE,
                    }
                })?;
                cmd["llms"] = json!(value);
                i += 1;
            }
            "--outline" => {
                cmd["outline"] = json!(true);
            }
            "--filter" => {
                let value = rest
                    .get(i + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: "read --filter".to_string(),
                        usage: READ_USAGE,
                    })?;
                cmd["filter"] = json!(value);
                i += 1;
            }
            "--timeout" => {
                let value = rest
                    .get(i + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: "read --timeout".to_string(),
                        usage: READ_USAGE,
                    })?;
                let timeout = crate::read::parse_timeout_ms(value).map_err(|message| {
                    ParseError::InvalidValue {
                        message,
                        usage: READ_USAGE,
                    }
                })?;
                cmd["timeout"] = json!(timeout);
                i += 1;
            }
            "--json" => {
                cmd["json"] = json!(true);
            }
            arg if arg.starts_with("--") => {
                return Err(ParseError::UnknownSubcommand {
                    subcommand: arg.to_string(),
                    valid_options: &[
                        "--raw",
                        "--require-md",
                        "--llms",
                        "--outline",
                        "--filter",
                        "--timeout",
                        "--json",
                    ],
                });
            }
            arg => {
                if url.is_some() {
                    return Err(ParseError::InvalidValue {
                        message: format!("Unexpected read argument: {}", arg),
                        usage: READ_USAGE,
                    });
                }
                url = Some(arg);
            }
        }
        i += 1;
    }
    if cmd.get("llms").is_some()
        && cmd
            .get("outline")
            .and_then(|v| v.as_bool())
            .unwrap_or(false)
    {
        return Err(ParseError::InvalidValue {
            message: "read --llms and --outline cannot be used together".to_string(),
            usage: READ_USAGE,
        });
    }
    if let Some(url) = url {
        cmd["url"] = json!(url);
    }
    if let Some(ref headers_json) = flags.headers {
        let headers = serde_json::from_str::<serde_json::Value>(headers_json).map_err(|_| {
            ParseError::InvalidValue {
                message: format!("Invalid JSON for --headers: {}", headers_json),
                usage: READ_USAGE,
            }
        })?;
        if !headers.is_object() {
            return Err(ParseError::InvalidValue {
                message: format!("Invalid JSON object for --headers: {}", headers_json),
                usage: READ_USAGE,
            });
        }
        cmd["headers"] = headers;
    }
    if let Some(ref allowed_domains) = flags.allowed_domains {
        cmd["allowedDomains"] = json!(allowed_domains);
    }
    Ok(cmd)
}

/// Parse the arguments shared by `record start` and `record restart`:
/// `<path> [url] [--fps <n>] [--cursor] [--contact-sheet]` plus an optional
/// contact-sheet pixel-difference threshold.
///
/// `rest` excludes the subcommand. `path` needs an extension so ffmpeg can
/// pick a container (`.webm` and `.mp4` are the tuned ones). Recording
/// defaults to
/// `recording::DEFAULT_FPS`; `--fps` accepts anything up to
/// `recording::MAX_FPS`, with 60 reserved for motion-heavy takes.
fn parse_record_take(
    id: &str,
    action: &str,
    rest: &[&str],
    context: &str,
    usage: &'static str,
) -> Result<Value, ParseError> {
    let max_fps = crate::native::recording::MAX_FPS;
    let mut path: Option<&str> = None;
    let mut url: Option<&str> = None;
    let mut fps: Option<u32> = None;
    let mut cursor = false;
    let mut contact_sheet = false;
    let mut contact_sheet_threshold: Option<f64> = None;

    let mut i = 0;
    while i < rest.len() {
        match rest[i] {
            "--fps" => {
                let value = rest
                    .get(i + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: format!("{} --fps", context),
                        usage,
                    })?;
                let parsed = value.parse::<u32>().map_err(|_| ParseError::InvalidValue {
                    message: format!("Invalid fps: '{}' is not a valid integer", value),
                    usage,
                })?;
                if parsed == 0 || parsed > max_fps {
                    return Err(ParseError::InvalidValue {
                        message: format!(
                            "Invalid fps: {} is out of range (valid range: 1-{})",
                            parsed, max_fps
                        ),
                        usage,
                    });
                }
                fps = Some(parsed);
                i += 2;
            }
            "--cursor" => {
                cursor = true;
                i += 1;
            }
            "--contact-sheet" => {
                contact_sheet = true;
                i += 1;
            }
            "--contact-sheet-threshold" => {
                let value = rest
                    .get(i + 1)
                    .ok_or_else(|| ParseError::MissingArguments {
                        context: format!("{} --contact-sheet-threshold", context),
                        usage,
                    })?;
                let parsed = value.parse::<f64>().map_err(|_| ParseError::InvalidValue {
                    message: format!(
                        "Invalid contact sheet threshold: '{}' is not a number",
                        value
                    ),
                    usage,
                })?;
                if !parsed.is_finite() || !(0.0..=1.0).contains(&parsed) {
                    return Err(ParseError::InvalidValue {
                        message: format!(
                            "Invalid contact sheet threshold: {} is out of range (valid range: 0-1)",
                            parsed
                        ),
                        usage,
                    });
                }
                contact_sheet = true;
                contact_sheet_threshold = Some(parsed);
                i += 2;
            }
            flag if flag.starts_with("--") => {
                return Err(ParseError::InvalidValue {
                    message: format!("Unknown flag for {}: {}", context, flag),
                    usage,
                });
            }
            positional => {
                if path.is_none() {
                    path = Some(positional);
                } else if url.is_none() {
                    url = Some(positional);
                } else {
                    return Err(ParseError::InvalidValue {
                        message: format!("Unexpected argument for {}: {}", context, positional),
                        usage,
                    });
                }
                i += 1;
            }
        }
    }

    let path = path.ok_or_else(|| ParseError::MissingArguments {
        context: context.to_string(),
        usage,
    })?;

    // ffmpeg picks the container from the extension and only fails at
    // `record stop`, so reject extensionless paths before the daemon is asked.
    crate::native::recording::validate_output_path(path)
        .map_err(|message| ParseError::InvalidValue { message, usage })?;

    let mut cmd = json!({ "id": id, "action": action, "path": path });
    if let Some(u) = url {
        let url_str = normalize_navigation_url(u);
        cmd["url"] = json!(url_str);
    }
    if let Some(rate) = fps {
        cmd["fps"] = json!(rate);
    }
    if cursor {
        cmd["cursor"] = json!(true);
    }
    if contact_sheet {
        cmd["contactSheet"] = json!(true);
    }
    if let Some(threshold) = contact_sheet_threshold {
        cmd["contactSheetThreshold"] = json!(threshold);
    }
    Ok(cmd)
}

fn parse_react(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    const VALID: &[&str] = &["tree", "inspect", "renders", "suspense"];
    let sub = rest.first().copied().ok_or(ParseError::MissingArguments {
        context: "react".to_string(),
        usage: "react <tree|inspect|renders|suspense>",
    })?;
    // MCP runs child commands with global `--json` for transport. That global
    // flag is stripped before command parsing, so `--raw-json` preserves the
    // React command's raw payload toggle for MCP without changing public docs.
    let json_out = rest.contains(&"--json") || rest.contains(&"--raw-json");
    let flag = |key: &str| -> Value {
        if json_out {
            json!({ "id": id, "action": key, "json": true })
        } else {
            json!({ "id": id, "action": key })
        }
    };
    match sub {
        "tree" => Ok(flag("react_tree")),
        "inspect" => {
            let id_arg = rest
                .iter()
                .skip(1)
                .find(|a| !a.starts_with("--"))
                .copied()
                .ok_or(ParseError::MissingArguments {
                    context: "react inspect".to_string(),
                    usage: "react inspect <id>",
                })?;
            let numeric: i64 = id_arg.parse().map_err(|_| ParseError::InvalidValue {
                message: format!("react inspect id must be a number, got '{}'", id_arg),
                usage: "react inspect <id>",
            })?;
            let mut cmd = json!({ "id": id, "action": "react_inspect", "fiberId": numeric });
            if json_out {
                cmd["json"] = json!(true);
            }
            Ok(cmd)
        }
        "renders" => {
            let op = rest.get(1).copied().unwrap_or("start");
            match op {
                "start" => Ok(flag("react_renders_start")),
                "stop" => Ok(flag("react_renders_stop")),
                other => Err(ParseError::UnknownSubcommand {
                    subcommand: other.to_string(),
                    valid_options: &["start", "stop"],
                }),
            }
        }
        "suspense" => {
            let only_dynamic = rest.contains(&"--only-dynamic");
            let mut cmd = json!({ "id": id, "action": "react_suspense" });
            if json_out {
                cmd["json"] = json!(true);
            }
            if only_dynamic {
                cmd["onlyDynamic"] = json!(true);
            }
            Ok(cmd)
        }
        other => Err(ParseError::UnknownSubcommand {
            subcommand: other.to_string(),
            valid_options: VALID,
        }),
    }
}

fn parse_diff(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    const VALID: &[&str] = &["snapshot", "screenshot", "url"];

    match rest.first().copied() {
        Some("snapshot") => {
            let mut cmd = json!({ "id": id, "action": "diff_snapshot" });
            let obj = cmd.as_object_mut().unwrap();
            let mut i = 1;
            while i < rest.len() {
                match rest[i] {
                    "-b" | "--baseline" => {
                        if let Some(path) = rest.get(i + 1) {
                            obj.insert("baseline".to_string(), json!(path));
                            i += 1;
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff snapshot --baseline".to_string(),
                                usage: "diff snapshot --baseline <file>",
                            });
                        }
                    }
                    "-s" | "--selector" => {
                        if let Some(s) = rest.get(i + 1) {
                            obj.insert("selector".to_string(), json!(s));
                            i += 1;
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff snapshot --selector".to_string(),
                                usage: "diff snapshot --selector <sel>",
                            });
                        }
                    }
                    "-c" | "--compact" => {
                        obj.insert("compact".to_string(), json!(true));
                    }
                    "-d" | "--depth" => {
                        if let Some(d) = rest.get(i + 1) {
                            match d.parse::<u32>() {
                                Ok(n) => {
                                    obj.insert("maxDepth".to_string(), json!(n));
                                    i += 1;
                                }
                                Err(_) => {
                                    return Err(ParseError::InvalidValue {
                                        message: format!(
                                            "Depth must be a non-negative integer, got: {}",
                                            d
                                        ),
                                        usage: "diff snapshot --depth <n>",
                                    });
                                }
                            }
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff snapshot --depth".to_string(),
                                usage: "diff snapshot --depth <n>",
                            });
                        }
                    }
                    other if other.starts_with('-') => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unknown flag: {}", other),
                            usage: "diff snapshot [--baseline <file>] [--selector <sel>] [--compact] [--depth <n>]",
                        });
                    }
                    other => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unexpected argument: {}", other),
                            usage: "diff snapshot [--baseline <file>] [--selector <sel>] [--compact] [--depth <n>]",
                        });
                    }
                }
                i += 1;
            }
            Ok(cmd)
        }
        Some("screenshot") => {
            let mut cmd = json!({ "id": id, "action": "diff_screenshot" });
            let obj = cmd.as_object_mut().unwrap();
            let mut i = 1;
            while i < rest.len() {
                match rest[i] {
                    "-b" | "--baseline" => {
                        if let Some(path) = rest.get(i + 1) {
                            obj.insert("baseline".to_string(), json!(path));
                            i += 1;
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff screenshot --baseline".to_string(),
                                usage: "diff screenshot --baseline <file>",
                            });
                        }
                    }
                    "-o" | "--output" => {
                        if let Some(path) = rest.get(i + 1) {
                            obj.insert("output".to_string(), json!(path));
                            i += 1;
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff screenshot --output".to_string(),
                                usage: "diff screenshot --output <file>",
                            });
                        }
                    }
                    "-t" | "--threshold" => {
                        if let Some(t) = rest.get(i + 1) {
                            match t.parse::<f64>() {
                                Ok(n) if (0.0..=1.0).contains(&n) => {
                                    obj.insert("threshold".to_string(), json!(n));
                                    i += 1;
                                }
                                Ok(n) => {
                                    return Err(ParseError::InvalidValue {
                                        message: format!(
                                            "Threshold must be between 0 and 1, got {}",
                                            n
                                        ),
                                        usage: "diff screenshot --threshold <0-1>",
                                    });
                                }
                                Err(_) => {
                                    return Err(ParseError::InvalidValue {
                                        message: format!("Invalid threshold value: {}", t),
                                        usage: "diff screenshot --threshold <0-1>",
                                    });
                                }
                            }
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff screenshot --threshold".to_string(),
                                usage: "diff screenshot --threshold <0-1>",
                            });
                        }
                    }
                    "-s" | "--selector" => {
                        if let Some(s) = rest.get(i + 1) {
                            obj.insert("selector".to_string(), json!(s));
                            i += 1;
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff screenshot --selector".to_string(),
                                usage: "diff screenshot --selector <sel>",
                            });
                        }
                    }
                    "--full" | "-f" => {
                        obj.insert("fullPage".to_string(), json!(true));
                    }
                    other if other.starts_with('-') => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unknown flag: {}", other),
                            usage: "diff screenshot --baseline <file> [--output <file>] [--threshold <0-1>] [--selector <sel>] [--full/-f]",
                        });
                    }
                    other => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unexpected argument: {}", other),
                            usage: "diff screenshot --baseline <file> [--output <file>] [--threshold <0-1>] [--selector <sel>] [--full/-f]",
                        });
                    }
                }
                i += 1;
            }
            if !obj.contains_key("baseline") {
                return Err(ParseError::MissingArguments {
                    context: "diff screenshot".to_string(),
                    usage: "diff screenshot --baseline <file>",
                });
            }
            Ok(cmd)
        }
        Some("url") => {
            let url1 = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "diff url".to_string(),
                usage: "diff url <url1> <url2>",
            })?;
            let url2 = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
                context: "diff url".to_string(),
                usage: "diff url <url1> <url2>",
            })?;
            let mut cmd = json!({
                "id": id,
                "action": "diff_url",
                "url1": url1,
                "url2": url2,
            });
            let obj = cmd.as_object_mut().unwrap();
            let mut i = 3;
            while i < rest.len() {
                match rest[i] {
                    "--screenshot" => {
                        obj.insert("screenshot".to_string(), json!(true));
                    }
                    "--full" | "-f" => {
                        obj.insert("fullPage".to_string(), json!(true));
                    }
                    "--wait-until" => {
                        if let Some(val) = rest.get(i + 1) {
                            obj.insert("waitUntil".to_string(), json!(val));
                            i += 1;
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff url --wait-until".to_string(),
                                usage: "diff url <url1> <url2> --wait-until <load|domcontentloaded|networkidle>",
                            });
                        }
                    }
                    "-s" | "--selector" => {
                        if let Some(s) = rest.get(i + 1) {
                            obj.insert("selector".to_string(), json!(s));
                            i += 1;
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff url --selector".to_string(),
                                usage: "diff url <url1> <url2> --selector <sel>",
                            });
                        }
                    }
                    "-c" | "--compact" => {
                        obj.insert("compact".to_string(), json!(true));
                    }
                    "-d" | "--depth" => {
                        if let Some(d) = rest.get(i + 1) {
                            match d.parse::<u32>() {
                                Ok(n) => {
                                    obj.insert("maxDepth".to_string(), json!(n));
                                    i += 1;
                                }
                                Err(_) => {
                                    return Err(ParseError::InvalidValue {
                                        message: format!(
                                            "Depth must be a non-negative integer, got: {}",
                                            d
                                        ),
                                        usage: "diff url <url1> <url2> --depth <n>",
                                    });
                                }
                            }
                        } else {
                            return Err(ParseError::MissingArguments {
                                context: "diff url --depth".to_string(),
                                usage: "diff url <url1> <url2> --depth <n>",
                            });
                        }
                    }
                    other if other.starts_with('-') => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unknown flag: {}", other),
                            usage: "diff url <url1> <url2> [--screenshot] [--full/-f] [--wait-until <strategy>] [--selector <sel>] [--compact] [--depth <n>]",
                        });
                    }
                    other => {
                        return Err(ParseError::InvalidValue {
                            message: format!("Unexpected argument: {}", other),
                            usage: "diff url <url1> <url2> [--screenshot] [--full/-f] [--wait-until <strategy>] [--selector <sel>] [--compact] [--depth <n>]",
                        });
                    }
                }
                i += 1;
            }
            Ok(cmd)
        }
        Some(sub) => Err(ParseError::UnknownSubcommand {
            subcommand: sub.to_string(),
            valid_options: VALID,
        }),
        None => Err(ParseError::MissingArguments {
            context: "diff".to_string(),
            usage: "diff <snapshot|screenshot|url>",
        }),
    }
}

fn parse_get(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    const VALID: &[&str] = &[
        "text", "html", "value", "attr", "url", "title", "count", "box", "styles", "cdp-url",
    ];

    match rest.first().copied() {
        Some("text") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "get text".to_string(),
                usage: "get text <selector>",
            })?;
            Ok(json!({ "id": id, "action": "gettext", "selector": sel }))
        }
        Some("html") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "get html".to_string(),
                usage: "get html <selector>",
            })?;
            Ok(json!({ "id": id, "action": "innerhtml", "selector": sel }))
        }
        Some("value") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "get value".to_string(),
                usage: "get value <selector>",
            })?;
            Ok(json!({ "id": id, "action": "inputvalue", "selector": sel }))
        }
        Some("attr") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "get attr".to_string(),
                usage: "get attr <selector> <attribute>",
            })?;
            let attr = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
                context: "get attr".to_string(),
                usage: "get attr <selector> <attribute>",
            })?;
            Ok(json!({ "id": id, "action": "getattribute", "selector": sel, "attribute": attr }))
        }
        Some("url") => Ok(json!({ "id": id, "action": "url" })),
        Some("cdp-url") => Ok(json!({ "id": id, "action": "cdp_url" })),
        Some("title") => Ok(json!({ "id": id, "action": "title" })),
        Some("count") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "get count".to_string(),
                usage: "get count <selector>",
            })?;
            Ok(json!({ "id": id, "action": "count", "selector": sel }))
        }
        Some("box") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "get box".to_string(),
                usage: "get box <selector>",
            })?;
            Ok(json!({ "id": id, "action": "boundingbox", "selector": sel }))
        }
        Some("styles") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "get styles".to_string(),
                usage: "get styles <selector>",
            })?;
            Ok(json!({ "id": id, "action": "styles", "selector": sel }))
        }
        Some(sub) => Err(ParseError::UnknownSubcommand {
            subcommand: sub.to_string(),
            valid_options: VALID,
        }),
        None => Err(ParseError::MissingArguments {
            context: "get".to_string(),
            usage: "get <text|html|value|attr|url|title|count|box|styles|cdp-url> [args...]",
        }),
    }
}

fn parse_is(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    const VALID: &[&str] = &["visible", "enabled", "checked"];

    match rest.first().copied() {
        Some("visible") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "is visible".to_string(),
                usage: "is visible <selector>",
            })?;
            Ok(json!({ "id": id, "action": "isvisible", "selector": sel }))
        }
        Some("enabled") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "is enabled".to_string(),
                usage: "is enabled <selector>",
            })?;
            Ok(json!({ "id": id, "action": "isenabled", "selector": sel }))
        }
        Some("checked") => {
            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "is checked".to_string(),
                usage: "is checked <selector>",
            })?;
            Ok(json!({ "id": id, "action": "ischecked", "selector": sel }))
        }
        Some(sub) => Err(ParseError::UnknownSubcommand {
            subcommand: sub.to_string(),
            valid_options: VALID,
        }),
        None => Err(ParseError::MissingArguments {
            context: "is".to_string(),
            usage: "is <visible|enabled|checked> <selector>",
        }),
    }
}

fn parse_find(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    const VALID: &[&str] = &[
        "role",
        "text",
        "label",
        "placeholder",
        "alt",
        "title",
        "testid",
        "first",
        "last",
        "nth",
    ];

    let locator = rest.first().ok_or_else(|| ParseError::MissingArguments {
        context: "find".to_string(),
        usage: "find <locator> <value> [action] [text]",
    })?;

    match *locator {
        "role" | "text" | "label" | "placeholder" | "alt" | "title" | "testid" | "first"
        | "last" => {
            let value = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: format!("find {}", locator),
                usage: match *locator {
                    "role" => "find role <role> [action] [--name <name>] [--exact]",
                    "text" => "find text <text> [action] [value] [--exact]",
                    "label" => "find label <label> [action] [text] [--exact]",
                    "placeholder" => "find placeholder <text> [action] [text] [--exact]",
                    "alt" => "find alt <text> [action] [value] [--exact]",
                    "title" => "find title <text> [action] [value] [--exact]",
                    "testid" => "find testid <id> [action] [text]",
                    "first" => "find first <selector> [action] [text]",
                    "last" => "find last <selector> [action] [text]",
                    _ => "find <locator> <value> [action] [text]",
                },
            })?;
            let subaction = rest.get(2).unwrap_or(&"click");
            let mut name: Option<&str> = None;
            let mut exact = false;
            let mut fill_parts: Vec<&str> = Vec::new();

            if rest.len() > 3 {
                let mut i = 3;
                while i < rest.len() {
                    match rest[i] {
                        "--exact" => {
                            exact = true;
                            i += 1;
                        }
                        "--name" => {
                            let n =
                                rest.get(i + 1)
                                    .ok_or_else(|| ParseError::MissingArguments {
                                        context: format!("find {}", locator),
                                        usage:
                                            "find role <role> [action] [--name <name>] [--exact]",
                                    })?;
                            name = Some(*n);
                            i += 2;
                        }
                        token => {
                            fill_parts.push(token);
                            i += 1;
                        }
                    }
                }
            }

            let fill_value = if fill_parts.is_empty() {
                None
            } else {
                Some(fill_parts.join(" "))
            };

            match *locator {
                "role" => {
                    let mut cmd = json!({ "id": id, "action": "getbyrole", "role": value, "subaction": subaction, "name": name, "exact": exact });
                    if let Some(v) = fill_value {
                        cmd["value"] = json!(v);
                    }
                    Ok(cmd)
                }
                "text" => {
                    let mut cmd = json!({ "id": id, "action": "getbytext", "text": value, "subaction": subaction, "exact": exact });
                    if let Some(v) = fill_value {
                        cmd["value"] = json!(v);
                    }
                    Ok(cmd)
                }
                "label" => {
                    let mut cmd = json!({ "id": id, "action": "getbylabel", "label": value, "subaction": subaction, "exact": exact });
                    if let Some(v) = fill_value {
                        cmd["value"] = json!(v);
                    }
                    Ok(cmd)
                }
                "placeholder" => {
                    let mut cmd = json!({ "id": id, "action": "getbyplaceholder", "placeholder": value, "subaction": subaction, "exact": exact });
                    if let Some(v) = fill_value {
                        cmd["value"] = json!(v);
                    }
                    Ok(cmd)
                }
                "alt" => {
                    let mut cmd = json!({ "id": id, "action": "getbyalttext", "text": value, "subaction": subaction, "exact": exact });
                    if let Some(v) = fill_value {
                        cmd["value"] = json!(v);
                    }
                    Ok(cmd)
                }
                "title" => {
                    let mut cmd = json!({ "id": id, "action": "getbytitle", "text": value, "subaction": subaction, "exact": exact });
                    if let Some(v) = fill_value {
                        cmd["value"] = json!(v);
                    }
                    Ok(cmd)
                }
                "testid" => {
                    let mut cmd = json!({ "id": id, "action": "getbytestid", "testId": value, "subaction": subaction });
                    if let Some(v) = fill_value {
                        cmd["value"] = json!(v);
                    }
                    Ok(cmd)
                }
                "first" => {
                    let mut cmd = json!({ "id": id, "action": "nth", "selector": value, "index": 0, "subaction": subaction });
                    if let Some(v) = fill_value {
                        cmd["value"] = json!(v);
                    }
                    Ok(cmd)
                }
                "last" => {
                    let mut cmd = json!({ "id": id, "action": "nth", "selector": value, "index": -1, "subaction": subaction });
                    if let Some(v) = fill_value {
                        cmd["value"] = json!(v);
                    }
                    Ok(cmd)
                }
                _ => unreachable!(),
            }
        }
        "nth" => {
            let idx_str = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "find nth".to_string(),
                usage: "find nth <index> <selector> [action] [text]",
            })?;
            let idx = idx_str
                .parse::<i32>()
                .map_err(|_| ParseError::MissingArguments {
                    context: "find nth".to_string(),
                    usage: "find nth <index> <selector> [action] [text]",
                })?;
            let sel = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
                context: "find nth".to_string(),
                usage: "find nth <index> <selector> [action] [text]",
            })?;
            let sub = rest.get(3).unwrap_or(&"click");
            let fv = if rest.len() > 4 {
                Some(rest[4..].join(" "))
            } else {
                None
            };
            let mut cmd = json!({ "id": id, "action": "nth", "selector": sel, "index": idx, "subaction": sub });
            if let Some(v) = fv {
                cmd["value"] = json!(v);
            }
            Ok(cmd)
        }
        _ => Err(ParseError::UnknownSubcommand {
            subcommand: locator.to_string(),
            valid_options: VALID,
        }),
    }
}

fn parse_mouse(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    const VALID: &[&str] = &["move", "down", "up", "wheel"];

    match rest.first().copied() {
        Some("move") => {
            let x_str = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "mouse move".to_string(),
                usage: "mouse move <x> <y>",
            })?;
            let y_str = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
                context: "mouse move".to_string(),
                usage: "mouse move <x> <y>",
            })?;
            let x = x_str
                .parse::<i32>()
                .map_err(|_| ParseError::MissingArguments {
                    context: "mouse move".to_string(),
                    usage: "mouse move <x> <y>",
                })?;
            let y = y_str
                .parse::<i32>()
                .map_err(|_| ParseError::MissingArguments {
                    context: "mouse move".to_string(),
                    usage: "mouse move <x> <y>",
                })?;
            let mut cmd = json!({ "id": id, "action": "mousemove", "x": x, "y": y });
            let mut i = 3;
            while i < rest.len() {
                match rest[i] {
                    "--duration" | "--steps" | "--seed" => {
                        let flag = rest[i];
                        let raw = rest.get(i + 1).ok_or_else(|| ParseError::MissingArguments {
                            context: format!("mouse move {}", flag),
                            usage: "mouse move <x> <y> [--duration <ms>] [--steps <n>] [--seed <n>]",
                        })?;
                        let value = raw.parse::<u64>().map_err(|_| ParseError::InvalidValue {
                            message: format!("{} expects a non-negative integer, got '{}'", flag, raw),
                            usage: "mouse move <x> <y> [--duration <ms>] [--steps <n>] [--seed <n>]",
                        })?;
                        let key = match flag { "--duration" => "duration", "--steps" => "steps", _ => "seed" };
                        cmd[key] = json!(value);
                        i += 2;
                    }
                    "--human" => { cmd["inputMode"] = json!("human"); i += 1; }
                    other => return Err(ParseError::InvalidValue {
                        message: format!("unexpected argument '{}'", other),
                        usage: "mouse move <x> <y> [--duration <ms>] [--steps <n>] [--seed <n>] [--human]",
                    }),
                }
            }
            Ok(cmd)
        }
        Some("down") => {
            Ok(json!({ "id": id, "action": "mousedown", "button": rest.get(1).unwrap_or(&"left") }))
        }
        Some("up") => {
            Ok(json!({ "id": id, "action": "mouseup", "button": rest.get(1).unwrap_or(&"left") }))
        }
        Some("wheel") => {
            let dy = rest
                .get(1)
                .and_then(|s| s.parse::<i32>().ok())
                .unwrap_or(100);
            let dx = rest.get(2).and_then(|s| s.parse::<i32>().ok()).unwrap_or(0);
            Ok(json!({ "id": id, "action": "wheel", "deltaX": dx, "deltaY": dy }))
        }
        Some(sub) => Err(ParseError::UnknownSubcommand {
            subcommand: sub.to_string(),
            valid_options: VALID,
        }),
        None => Err(ParseError::MissingArguments {
            context: "mouse".to_string(),
            usage: "mouse <move|down|up|wheel> [args...]",
        }),
    }
}

/// Parse a finite floating-point argument for JSON serialization.
fn parse_finite_f64(raw: &str, what: &str, usage: &'static str) -> Result<f64, ParseError> {
    raw.parse::<f64>()
        .ok()
        .filter(|value| value.is_finite())
        .ok_or_else(|| ParseError::InvalidValue {
            message: format!("{} expects a finite number, got '{}'", what, raw),
            usage,
        })
}

fn parse_set(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    const VALID: &[&str] = &[
        "viewport",
        "device",
        "geo",
        "geolocation",
        "offline",
        "headers",
        "credentials",
        "auth",
        "media",
    ];

    match rest.first().copied() {
        Some("viewport") => {
            let w_str = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "set viewport".to_string(),
                usage: "set viewport <width> <height> [scale]",
            })?;
            let h_str = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
                context: "set viewport".to_string(),
                usage: "set viewport <width> <height> [scale]",
            })?;
            let w = w_str
                .parse::<i32>()
                .map_err(|_| ParseError::MissingArguments {
                    context: "set viewport".to_string(),
                    usage: "set viewport <width> <height> [scale]",
                })?;
            let h = h_str
                .parse::<i32>()
                .map_err(|_| ParseError::MissingArguments {
                    context: "set viewport".to_string(),
                    usage: "set viewport <width> <height> [scale]",
                })?;
            let mut cmd = json!({ "id": id, "action": "viewport", "width": w, "height": h });
            if let Some(scale_str) = rest.get(3) {
                let scale = parse_finite_f64(
                    scale_str,
                    "set viewport scale",
                    "set viewport <width> <height> [scale]",
                )?;
                cmd["deviceScaleFactor"] = json!(scale);
            }
            Ok(cmd)
        }
        Some("device") => {
            let dev = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "set device".to_string(),
                usage: "set device <name>",
            })?;
            Ok(json!({ "id": id, "action": "device", "device": dev }))
        }
        Some("geo") | Some("geolocation") => {
            let lat_str = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "set geo".to_string(),
                usage: "set geo <latitude> <longitude>",
            })?;
            let lng_str = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
                context: "set geo".to_string(),
                usage: "set geo <latitude> <longitude>",
            })?;
            let lat = parse_finite_f64(
                lat_str,
                "set geo latitude",
                "set geo <latitude> <longitude>",
            )?;
            let lng = parse_finite_f64(
                lng_str,
                "set geo longitude",
                "set geo <latitude> <longitude>",
            )?;
            Ok(json!({ "id": id, "action": "geolocation", "latitude": lat, "longitude": lng }))
        }
        Some("offline") => {
            let off = rest
                .get(1)
                .map(|s| *s != "off" && *s != "false")
                .unwrap_or(true);
            Ok(json!({ "id": id, "action": "offline", "offline": off }))
        }
        Some("headers") => {
            let headers_json = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "set headers".to_string(),
                usage: "set headers <json>",
            })?;
            // Parse the JSON string into an object
            let headers: serde_json::Value =
                serde_json::from_str(headers_json).map_err(|_| ParseError::MissingArguments {
                    context: "set headers".to_string(),
                    usage: "set headers <json> (must be valid JSON object)",
                })?;
            Ok(json!({ "id": id, "action": "headers", "headers": headers }))
        }
        Some("credentials") | Some("auth") => {
            let user = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "set credentials".to_string(),
                usage: "set credentials <username> <password>",
            })?;
            let pass = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
                context: "set credentials".to_string(),
                usage: "set credentials <username> <password>",
            })?;
            Ok(json!({ "id": id, "action": "credentials", "username": user, "password": pass }))
        }
        Some("media") => {
            let color = if rest.contains(&"dark") {
                "dark"
            } else if rest.contains(&"light") {
                "light"
            } else {
                "no-preference"
            };
            let reduced = if rest.contains(&"reduced-motion") {
                "reduce"
            } else {
                "no-preference"
            };
            Ok(
                json!({ "id": id, "action": "emulatemedia", "colorScheme": color, "reducedMotion": reduced }),
            )
        }
        Some(sub) => Err(ParseError::UnknownSubcommand {
            subcommand: sub.to_string(),
            valid_options: VALID,
        }),
        None => Err(ParseError::MissingArguments {
            context: "set".to_string(),
            usage: "set <viewport|device|geo|offline|headers|credentials|media> [args...]",
        }),
    }
}

/// Parse network interception, request inspection, and HAR recording commands.
fn parse_network(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    const VALID: &[&str] = &["route", "unroute", "requests", "request", "har"];

    match rest.first().copied() {
        Some("route") => {
            let url = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "network route".to_string(),
                usage: "network route <url> [--abort|--body <json> [--allow-origin <origin>]] [--resource-type <csv>]",
            })?;
            let abort = rest.contains(&"--abort");
            let body_idx = rest.iter().position(|&s| s == "--body");
            let body = body_idx.and_then(|i| rest.get(i + 1).copied());
            let rt_idx = rest
                .iter()
                .position(|&s| s == "--resource-type" || s == "--resource-types");
            let resource_type = rt_idx.and_then(|i| rest.get(i + 1).copied());
            let allow_origin = rest
                .iter()
                .position(|&s| s == "--allow-origin")
                .and_then(|i| rest.get(i + 1).copied());
            if allow_origin.is_some() && body.is_none() {
                return Err(ParseError::MissingArguments {
                    context: "network route --allow-origin".to_string(),
                    usage: "network route <url> --body <json> --allow-origin <origin>",
                });
            }
            let mut cmd = json!({ "id": id, "action": "route", "url": url, "abort": abort });
            if let Some(body) = body {
                cmd["response"] = json!({ "body": body });
                if let Some(origin) = allow_origin {
                    cmd["response"]["allowOrigin"] = json!(origin);
                }
            }
            if let Some(rt) = resource_type {
                cmd["resourceType"] = json!(rt);
            }
            Ok(cmd)
        }
        Some("unroute") => {
            let mut cmd = json!({ "id": id, "action": "unroute" });
            if let Some(url) = rest.get(1) {
                cmd["url"] = json!(url);
            }
            Ok(cmd)
        }
        Some("requests") => {
            let clear = rest.contains(&"--clear");
            let filter_idx = rest.iter().position(|&s| s == "--filter");
            let filter = filter_idx.and_then(|i| rest.get(i + 1).copied());
            let type_idx = rest.iter().position(|&s| s == "--type");
            let rtype = type_idx.and_then(|i| rest.get(i + 1).copied());
            let method_idx = rest.iter().position(|&s| s == "--method");
            let method = method_idx.and_then(|i| rest.get(i + 1).copied());
            let status_idx = rest.iter().position(|&s| s == "--status");
            let status = status_idx.and_then(|i| rest.get(i + 1).copied());
            let mut cmd = json!({ "id": id, "action": "requests", "clear": clear });
            if let Some(f) = filter {
                cmd["filter"] = json!(f);
            }
            if let Some(t) = rtype {
                cmd["type"] = json!(t);
            }
            if let Some(m) = method {
                cmd["method"] = json!(m);
            }
            if let Some(s) = status {
                cmd["status"] = json!(s);
            }
            Ok(cmd)
        }
        Some("request") => {
            let request_id = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
                context: "network request".to_string(),
                usage: "network request <requestId>",
            })?;
            Ok(json!({ "id": id, "action": "request_detail", "requestId": request_id }))
        }
        Some("har") => {
            const HAR_VALID: &[&str] = &["start", "stop"];
            match rest.get(1).copied() {
                Some("start") => {
                    let mut cmd = json!({ "id": id, "action": "har_start" });
                    if let Some(content_idx) = rest.iter().position(|&s| s == "--content") {
                        let mode = rest.get(content_idx + 1).ok_or_else(|| {
                            ParseError::MissingArguments {
                                context: "network har start --content".to_string(),
                                usage: "network har start [--content <all|text|none>]",
                            }
                        })?;
                        if !["all", "text", "none"].contains(mode) {
                            return Err(ParseError::InvalidValue {
                                message: format!("Invalid --content mode '{}'", mode),
                                usage: "network har start [--content <all|text|none>]",
                            });
                        }
                        cmd["content"] = json!(mode);
                    }
                    Ok(cmd)
                }
                Some("stop") => {
                    let mut cmd = json!({ "id": id, "action": "har_stop" });
                    if let Some(path) = rest.get(2) {
                        cmd["path"] = json!(path);
                    }
                    Ok(cmd)
                }
                Some(sub) => Err(ParseError::UnknownSubcommand {
                    subcommand: sub.to_string(),
                    valid_options: HAR_VALID,
                }),
                None => Err(ParseError::MissingArguments {
                    context: "network har".to_string(),
                    usage: "network har <start|stop> [path]",
                }),
            }
        }
        Some(sub) => Err(ParseError::UnknownSubcommand {
            subcommand: sub.to_string(),
            valid_options: VALID,
        }),
        None => Err(ParseError::MissingArguments {
            context: "network".to_string(),
            usage: "network <route|unroute|requests|request|har> [args...]",
        }),
    }
}

/// Parses storage operations with exact operand counts and one-key read shorthand.
fn parse_storage(rest: &[&str], id: &str) -> Result<Value, ParseError> {
    const VALID: &[&str] = &["local", "session"];

    match rest.first().copied() {
        Some("local") | Some("session") => {
            let storage_type = rest.first().unwrap();
            let (op, key, value, max_rest_len) = match rest.get(1) {
                Some(&"get") => ("get", rest.get(2), None, 3),
                Some(&"set") => ("set", rest.get(2), rest.get(3), 4),
                Some(&"clear") => ("clear", None, None, 2),
                Some(_) => ("get", rest.get(1), None, 2),
                None => ("get", None, None, 2),
            };
            if let Some(extra) = rest.get(max_rest_len) {
                return Err(ParseError::InvalidValue {
                    message: format!("Unexpected argument: {}", extra),
                    usage:
                        "storage <local|session> [get [key] | set <key> <value> | clear | <key>]",
                });
            }
            match op {
                "set" => {
                    let k = key.ok_or_else(|| ParseError::MissingArguments {
                        context: format!("storage {} set", storage_type),
                        usage: "storage <local|session> set <key> <value>",
                    })?;
                    let v = value.ok_or_else(|| ParseError::MissingArguments {
                        context: format!("storage {} set", storage_type),
                        usage: "storage <local|session> set <key> <value>",
                    })?;
                    Ok(
                        json!({ "id": id, "action": "storage_set", "type": storage_type, "key": k, "value": v }),
                    )
                }
                "clear" => Ok(json!({ "id": id, "action": "storage_clear", "type": storage_type })),
                _ => {
                    let mut cmd =
                        json!({ "id": id, "action": "storage_get", "type": storage_type });
                    if let Some(k) = key {
                        cmd.as_object_mut()
                            .unwrap()
                            .insert("key".to_string(), json!(k));
                    }
                    Ok(cmd)
                }
            }
        }
        Some(sub) => Err(ParseError::UnknownSubcommand {
            subcommand: sub.to_string(),
            valid_options: VALID,
        }),
        None => Err(ParseError::MissingArguments {
            context: "storage".to_string(),
            usage: "storage <local|session> [get [key] | set <key> <value> | clear | <key>]",
        }),
    }
}

/// Split a string into arguments respecting shell quoting (double/single quotes, backslash escapes).
pub fn shell_words_split(s: &str) -> Vec<String> {
    let mut args = Vec::new();
    let mut current = String::new();
    let mut in_double = false;
    let mut in_single = false;
    let mut chars = s.chars().peekable();

    while let Some(c) = chars.next() {
        match c {
            '\\' if !in_single => {
                if let Some(&next) = chars.peek() {
                    chars.next();
                    current.push(next);
                }
            }
            '"' if !in_single => in_double = !in_double,
            '\'' if !in_double => in_single = !in_single,
            ' ' if !in_double && !in_single => {
                if !current.is_empty() {
                    args.push(std::mem::take(&mut current));
                }
            }
            _ => current.push(c),
        }
    }
    if !current.is_empty() {
        args.push(current);
    }
    args
}

#[cfg(test)]
mod tests {
    use super::*;

    fn default_flags() -> Flags {
        Flags {
            session: "test".to_string(),
            session_source: "--session",
            json: false,
            headed: false,
            debug: false,
            headers: None,
            executable_path: None,
            extensions: Vec::new(),
            init_scripts: Vec::new(),
            enable: Vec::new(),
            cdp: None,
            cdp_headers: None,
            profile: None,
            state: None,
            proxy: None,
            proxy_bypass: None,
            args: None,
            user_agent: None,
            provider: None,
            ignore_https_errors: false,
            ca_cert: None,
            clear_ca_cert: false,
            use_system_ca: false,
            allow_file_access: false,
            hide_scrollbars: true,
            webgpu: false,
            no_webmcp: false,
            no_xvfb: false,
            device: None,
            auto_connect: false,
            pin_tab: false,
            session_name: None,
            restore: None,
            restore_save: None,
            restore_check_url: None,
            restore_check_text: None,
            restore_check_fn: None,
            namespace: None,
            restore_uses_session: false,
            cli_executable_path: false,
            cli_extensions: false,
            cli_init_scripts: false,
            cli_enable: false,
            cli_profile: false,
            cli_state: false,
            cli_args: false,
            cli_user_agent: false,
            cli_proxy: false,
            cli_proxy_bypass: false,
            cli_ca_cert: false,
            cli_use_system_ca: false,
            cli_allow_file_access: false,
            cli_hide_scrollbars: false,
            cli_annotate: false,
            cli_download_path: false,
            cli_headed: false,
            cli_webgpu: false,
            cli_no_webmcp: false,
            cli_restore: false,
            cli_pin_tab: false,
            cli_input_mode: false,
            annotate: false,
            color_scheme: None,
            download_path: None,
            content_boundaries: false,
            max_output: None,
            allowed_domains: None,
            action_policy: None,
            confirm_actions: None,
            confirm_interactive: false,
            engine: None,
            screenshot_dir: None,
            screenshot_quality: None,
            screenshot_format: None,
            idle_timeout: None,
            default_timeout: None,
            no_auto_dialog: false,
            model: None,
            plugins: Vec::new(),
            verbose: false,
            quiet: false,
            input_mode: "instant".to_string(),
        }
    }

    fn args(s: &str) -> Vec<String> {
        s.split_whitespace().map(String::from).collect()
    }

    // === Cookies Tests ===

    #[test]
    fn test_cookies_get() {
        let cmd = parse_command(&args("cookies"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "cookies_get");
    }

    #[test]
    fn test_cookies_get_explicit() {
        let cmd = parse_command(&args("cookies get"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "cookies_get");
    }

    #[test]
    fn test_cookies_set() {
        let cmd = parse_command(&args("cookies set mycookie myvalue"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
    }

    #[test]
    fn test_cookies_set_missing_value() {
        let result = parse_command(&args("cookies set mycookie"), &default_flags());
        assert!(result.is_err());
    }

    #[test]
    fn test_cookies_clear() {
        let cmd = parse_command(&args("cookies clear"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "cookies_clear");
    }

    #[test]
    fn test_parse_curl_cookies_json_array() {
        let input = r#"[{"name":"a","value":"1"},{"name":"b","value":"2"}]"#;
        let out = parse_curl_cookies(input).unwrap();
        assert_eq!(out.len(), 2);
        assert_eq!(out[0]["name"], "a");
        assert_eq!(out[0]["value"], "1");
        assert_eq!(out[1]["name"], "b");
        assert_eq!(out[1]["value"], "2");
    }

    #[test]
    fn test_parse_curl_cookies_bare_header() {
        let input = "sid=abc; token=xyz; other=";
        let out = parse_curl_cookies(input).unwrap();
        assert_eq!(out.len(), 3);
        assert_eq!(out[0]["name"], "sid");
        assert_eq!(out[0]["value"], "abc");
        assert_eq!(out[2]["name"], "other");
        assert_eq!(out[2]["value"], "");
    }

    #[test]
    fn test_parse_curl_cookies_from_curl_bash() {
        let input = "curl 'https://example.com/api' \\\n  -H 'accept: application/json' \\\n  -H 'cookie: sid=abc; token=xyz'";
        let out = parse_curl_cookies(input).unwrap();
        assert_eq!(out.len(), 2);
        assert_eq!(out[0]["name"], "sid");
        assert_eq!(out[1]["name"], "token");
    }

    #[test]
    fn test_parse_curl_cookies_from_curl_b_flag() {
        let input = "curl 'https://example.com/api' -b 'sid=abc; token=xyz'";
        let out = parse_curl_cookies(input).unwrap();
        assert_eq!(out.len(), 2);
        assert_eq!(out[0]["name"], "sid");
    }

    #[test]
    fn test_parse_curl_cookies_empty_error() {
        assert!(parse_curl_cookies("").is_err());
        assert!(parse_curl_cookies("   ").is_err());
    }

    #[test]
    fn test_parse_curl_cookies_never_echoes_values_in_errors() {
        // Error messages must never echo cookie values or any bytes from the
        // input that could be a secret. Use a distinct recognizable token per
        // case so a regression surfaces the leaking code path clearly.

        // JSON array with a missing `name` field.
        let name_secret = "LEAK_VIA_MISSING_NAME_xY9zQ";
        let input = format!(r#"[{{"value":"{}"}}]"#, name_secret);
        let err = parse_curl_cookies(&input).unwrap_err();
        assert!(
            !err.contains(name_secret),
            "missing-name error leaked secret value: {}",
            err
        );

        // Truncated / malformed JSON containing a secret. Depends on
        // serde_json's Display impl to report position only, not payload.
        let parse_secret = "LEAK_VIA_JSON_PARSE_aA1bB2";
        let input = format!(r#"[{{"name":"sid","value":"{}"#, parse_secret);
        let err = parse_curl_cookies(&input).unwrap_err();
        assert!(
            !err.contains(parse_secret),
            "malformed-JSON error leaked secret value: {}",
            err
        );

        // Valid cURL dump with no Cookie header but a secret in another
        // header. Should error on "no Cookie header found" without echoing.
        let curl_secret = "LEAK_VIA_CURL_NO_COOKIE_pP7qQ";
        let input = format!("curl 'https://example.com/' -H 'x-token: {}'", curl_secret);
        let err = parse_curl_cookies(&input).unwrap_err();
        assert!(
            !err.contains(curl_secret),
            "cURL-without-cookie error leaked secret value: {}",
            err
        );
    }

    #[test]
    fn test_react_tree_command() {
        let cmd = parse_command(&args("react tree"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "react_tree");
    }

    #[test]
    fn test_react_tree_json() {
        let cmd = parse_command(&args("react tree --json"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "react_tree");
        assert_eq!(cmd["json"], true);
    }

    #[test]
    fn test_react_tree_raw_json_internal_flag() {
        let cmd = parse_command(&args("react tree --raw-json"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "react_tree");
        assert_eq!(cmd["json"], true);
    }

    #[test]
    fn test_react_inspect_command() {
        let cmd = parse_command(&args("react inspect 12345"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "react_inspect");
        assert_eq!(cmd["fiberId"], 12345);
    }

    #[test]
    fn test_react_inspect_requires_numeric_id() {
        let err = parse_command(&args("react inspect not-a-number"), &default_flags());
        assert!(err.is_err());
    }

    #[test]
    fn test_react_renders_start_stop() {
        let start = parse_command(&args("react renders start"), &default_flags()).unwrap();
        assert_eq!(start["action"], "react_renders_start");
        let stop = parse_command(&args("react renders stop"), &default_flags()).unwrap();
        assert_eq!(stop["action"], "react_renders_stop");
        let stop_json =
            parse_command(&args("react renders stop --json"), &default_flags()).unwrap();
        assert_eq!(stop_json["json"], true);
    }

    #[test]
    fn test_react_suspense() {
        let cmd = parse_command(&args("react suspense"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "react_suspense");
        // onlyDynamic defaults to unset; absence means the full report
        assert!(cmd.get("onlyDynamic").is_none());
    }

    #[test]
    fn test_react_suspense_only_dynamic() {
        let cmd = parse_command(&args("react suspense --only-dynamic"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "react_suspense");
        assert_eq!(cmd["onlyDynamic"], true);
    }

    #[test]
    fn test_react_suspense_only_dynamic_with_json() {
        let cmd = parse_command(
            &args("react suspense --only-dynamic --json"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "react_suspense");
        assert_eq!(cmd["onlyDynamic"], true);
        assert_eq!(cmd["json"], true);
    }

    #[test]
    fn test_vitals_command() {
        let cmd = parse_command(&args("vitals"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "vitals");
        let cmd = parse_command(
            &args("vitals http://localhost:3000/dashboard"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["url"], "http://localhost:3000/dashboard");
    }

    #[test]
    fn test_a11y_command() {
        let cmd = parse_command(&args("a11y"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "a11y");
        assert!(cmd.get("url").is_none());

        let cmd = parse_command(
            &args("a11y http://localhost:3000 --tags wcag2a,wcag2aa --selector #main --json"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "a11y");
        assert_eq!(cmd["url"], "http://localhost:3000");
        assert_eq!(cmd["tags"], "wcag2a,wcag2aa");
        assert_eq!(cmd["selector"], "#main");
        assert_eq!(cmd["json"], true);

        let cmd = parse_command(&args("a11y example.com"), &default_flags()).unwrap();
        assert_eq!(cmd["url"], "https://example.com");

        let cmd = parse_command(&args("a11y about:blank"), &default_flags()).unwrap();
        assert_eq!(cmd["url"], "about:blank");

        assert!(parse_command(&args("a11y --tags"), &default_flags()).is_err());
        assert!(matches!(
            parse_command(
                &args("a11y --tags --selector #main"),
                &default_flags()
            ),
            Err(ParseError::MissingArguments { context, .. }) if context == "a11y --tags"
        ));
        assert!(matches!(
            parse_command(
                &args("a11y --selector --tags wcag2a"),
                &default_flags()
            ),
            Err(ParseError::MissingArguments { context, .. }) if context == "a11y --selector"
        ));
        assert!(parse_command(&args("a11y --bogus"), &default_flags()).is_err());
        assert!(parse_command(
            &args("a11y https://first.example https://second.example"),
            &default_flags()
        )
        .is_err());
    }

    #[test]
    fn test_pushstate_command() {
        let cmd = parse_command(&args("pushstate /foo"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "pushstate");
        assert_eq!(cmd["url"], "/foo");
    }

    #[test]
    fn test_removeinitscript_command() {
        let cmd = parse_command(&args("removeinitscript abc123"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "removeinitscript");
        assert_eq!(cmd["identifier"], "abc123");
    }

    #[test]
    fn test_network_route_resource_type() {
        let cmd = parse_command(
            &args("network route * --abort --resource-type script"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "route");
        assert_eq!(cmd["resourceType"], "script");
        assert_eq!(cmd["abort"], true);
    }

    #[test]
    fn test_network_route_body_builds_response() {
        let cmd = parse_command(
            &args("network route **/api/users --body {\"users\":[]}"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "route");
        assert_eq!(cmd["url"], "**/api/users");
        assert_eq!(cmd["response"]["body"], "{\"users\":[]}");
        assert!(cmd.get("body").is_none());
    }

    #[test]
    fn test_network_route_allow_origin_needs_body() {
        let cmd = parse_command(
            &args("network route https://api.example.com/* --body {} --allow-origin https://www.example.com"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["response"]["allowOrigin"], "https://www.example.com");
        assert!(parse_command(
            &args("network route https://api.example.com/* --allow-origin https://www.example.com"),
            &default_flags(),
        )
        .is_err());
    }

    #[test]
    fn test_cookies_set_with_url() {
        let cmd = parse_command(
            &args("cookies set mycookie myvalue --url https://example.com"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
        assert_eq!(cmd["cookies"][0]["url"], "https://example.com");
    }

    #[test]
    fn test_cookies_set_with_domain() {
        let cmd = parse_command(
            &args("cookies set mycookie myvalue --domain example.com"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
        assert_eq!(cmd["cookies"][0]["domain"], "example.com");
    }

    #[test]
    fn test_cookies_set_with_path() {
        let cmd = parse_command(
            &args("cookies set mycookie myvalue --path /api"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
        assert_eq!(cmd["cookies"][0]["path"], "/api");
    }

    #[test]
    fn test_cookies_set_with_httponly() {
        let cmd = parse_command(
            &args("cookies set mycookie myvalue --httpOnly"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
        assert_eq!(cmd["cookies"][0]["httpOnly"], true);
    }

    #[test]
    fn test_cookies_set_with_secure() {
        let cmd = parse_command(
            &args("cookies set mycookie myvalue --secure"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
        assert_eq!(cmd["cookies"][0]["secure"], true);
    }

    #[test]
    fn test_cookies_set_with_samesite() {
        let cmd = parse_command(
            &args("cookies set mycookie myvalue --sameSite Strict"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
        assert_eq!(cmd["cookies"][0]["sameSite"], "Strict");
    }

    #[test]
    fn test_cookies_set_with_expires() {
        let cmd = parse_command(
            &args("cookies set mycookie myvalue --expires 1234567890"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
        assert_eq!(cmd["cookies"][0]["expires"], 1234567890);
    }

    #[test]
    fn test_cookies_set_with_multiple_flags() {
        let cmd = parse_command(&args("cookies set mycookie myvalue --url https://example.com --httpOnly --secure --sameSite Lax"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
        assert_eq!(cmd["cookies"][0]["url"], "https://example.com");
        assert_eq!(cmd["cookies"][0]["httpOnly"], true);
        assert_eq!(cmd["cookies"][0]["secure"], true);
        assert_eq!(cmd["cookies"][0]["sameSite"], "Lax");
    }

    #[test]
    fn test_cookies_set_with_all_flags() {
        let cmd = parse_command(&args("cookies set mycookie myvalue --url https://example.com --domain example.com --path /api --httpOnly --secure --sameSite None --expires 9999999999"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "cookies_set");
        assert_eq!(cmd["cookies"][0]["name"], "mycookie");
        assert_eq!(cmd["cookies"][0]["value"], "myvalue");
        assert_eq!(cmd["cookies"][0]["url"], "https://example.com");
        assert_eq!(cmd["cookies"][0]["domain"], "example.com");
        assert_eq!(cmd["cookies"][0]["path"], "/api");
        assert_eq!(cmd["cookies"][0]["httpOnly"], true);
        assert_eq!(cmd["cookies"][0]["secure"], true);
        assert_eq!(cmd["cookies"][0]["sameSite"], "None");
        assert_eq!(cmd["cookies"][0]["expires"], 9999999999i64);
    }

    #[test]
    fn test_cookies_set_invalid_samesite() {
        let result = parse_command(
            &args("cookies set mycookie myvalue --sameSite Invalid"),
            &default_flags(),
        );
        assert!(result.is_err());
    }

    #[test]
    fn test_cookies_set_aliases_and_rejects_unknown_arguments() {
        let kebab = parse_command(
            &args("cookies set session value --http-only --same-site Strict"),
            &default_flags(),
        )
        .unwrap();
        let camel = parse_command(
            &args("cookies set session value --httpOnly --sameSite Strict"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(kebab["cookies"], camel["cookies"]);
        assert_eq!(kebab["cookies"][0]["httpOnly"], true);
        assert_eq!(kebab["cookies"][0]["sameSite"], "Strict");

        let unknown_flag = parse_command(
            &args("cookies set session value --unknown-cookie-flag"),
            &default_flags(),
        )
        .unwrap_err()
        .format();
        assert!(unknown_flag.contains("--unknown-cookie-flag"));

        let unexpected = parse_command(
            &args("cookies set session value private-cookie-value"),
            &default_flags(),
        )
        .unwrap_err()
        .format();
        assert!(unexpected.contains("unexpected argument"));
        assert!(!unexpected.contains("private-cookie-value"));
    }

    // === Storage Tests ===

    #[test]
    fn test_storage_local_get() {
        let cmd = parse_command(&args("storage local"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "storage_get");
        assert_eq!(cmd["type"], "local");
        assert!(cmd.get("key").is_none());
    }

    #[test]
    fn test_storage_local_get_key() {
        let cmd = parse_command(&args("storage local get mykey"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "storage_get");
        assert_eq!(cmd["type"], "local");
        assert_eq!(cmd["key"], "mykey");
    }

    #[test]
    fn test_storage_local_get_implicit_key() {
        let cmd = parse_command(&args("storage local mykey"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "storage_get");
        assert_eq!(cmd["type"], "local");
        assert_eq!(cmd["key"], "mykey");
    }

    #[test]
    fn test_storage_implicit_get_rejects_extra_operands_and_preserves_keys() {
        for storage_type in ["local", "session"] {
            for key in ["delete", "remove"] {
                let bare = parse_command(
                    &args(&format!("storage {storage_type} {key}")),
                    &default_flags(),
                )
                .unwrap();
                assert_eq!(bare["action"], "storage_get");
                assert_eq!(bare["type"], storage_type);
                assert_eq!(bare["key"], key);

                let err = parse_command(
                    &args(&format!("storage {storage_type} {key} extra")),
                    &default_flags(),
                )
                .unwrap_err();
                match err {
                    ParseError::InvalidValue { message, usage } => {
                        assert!(message.contains("Unexpected argument: extra"));
                        assert!(usage.contains("<key>"));
                    }
                    other => panic!("expected InvalidValue, got {:?}", other),
                }
            }
        }
    }

    #[test]
    fn test_storage_operations_reject_extra_operands() {
        for (command, extra) in [
            ("storage local get greeting extra", "extra"),
            ("storage local set greeting hello world", "world"),
            ("storage local clear greeting", "greeting"),
        ] {
            let error = parse_command(&args(command), &default_flags()).unwrap_err();
            match error {
                ParseError::InvalidValue { message, .. } => {
                    assert_eq!(message, format!("Unexpected argument: {}", extra));
                }
                other => panic!("expected InvalidValue, got {:?}", other),
            }
        }
    }

    #[test]
    fn test_storage_session_get() {
        let cmd = parse_command(&args("storage session"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "storage_get");
        assert_eq!(cmd["type"], "session");
    }

    #[test]
    fn test_storage_session_get_implicit_key() {
        let cmd = parse_command(&args("storage session mykey"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "storage_get");
        assert_eq!(cmd["type"], "session");
        assert_eq!(cmd["key"], "mykey");
    }

    #[test]
    fn test_storage_local_set() {
        let cmd =
            parse_command(&args("storage local set mykey myvalue"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "storage_set");
        assert_eq!(cmd["type"], "local");
        assert_eq!(cmd["key"], "mykey");
        assert_eq!(cmd["value"], "myvalue");
    }

    #[test]
    fn test_storage_session_set() {
        let cmd =
            parse_command(&args("storage session set skey svalue"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "storage_set");
        assert_eq!(cmd["type"], "session");
        assert_eq!(cmd["key"], "skey");
        assert_eq!(cmd["value"], "svalue");
    }

    #[test]
    fn test_storage_set_missing_value() {
        let result = parse_command(&args("storage local set mykey"), &default_flags());
        assert!(result.is_err());
    }

    #[test]
    fn test_storage_local_clear() {
        let cmd = parse_command(&args("storage local clear"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "storage_clear");
        assert_eq!(cmd["type"], "local");
    }

    #[test]
    fn test_storage_session_clear() {
        let cmd = parse_command(&args("storage session clear"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "storage_clear");
        assert_eq!(cmd["type"], "session");
    }

    #[test]
    fn test_storage_invalid_type() {
        let result = parse_command(&args("storage invalid"), &default_flags());
        assert!(result.is_err());
    }

    // === Navigation Tests ===

    #[test]
    fn test_open_without_url_launches() {
        let cmd = parse_command(&args("open"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "launch");
        assert_eq!(cmd["headless"], true);
    }

    #[test]
    fn test_open_without_url_headed() {
        let mut flags = default_flags();
        flags.headed = true;
        let cmd = parse_command(&args("open"), &flags).unwrap();
        assert_eq!(cmd["action"], "launch");
        assert_eq!(cmd["headless"], false);
    }

    #[test]
    fn test_goto_still_requires_url() {
        assert!(parse_command(&args("goto"), &default_flags()).is_err());
        assert!(parse_command(&args("navigate"), &default_flags()).is_err());
    }

    #[test]
    fn test_navigate_with_https() {
        let cmd = parse_command(&args("open https://example.com"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "navigate");
        assert_eq!(cmd["url"], "https://example.com");
    }

    #[test]
    fn test_navigate_without_protocol() {
        let cmd = parse_command(&args("open example.com"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "navigate");
        assert_eq!(cmd["url"], "https://example.com");
    }

    #[test]
    fn test_read_command() {
        let cmd = parse_command(&args("read example.com/docs"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "read");
        assert_eq!(cmd["url"], "example.com/docs");
        assert_eq!(cmd["timeout"], crate::read::default_timeout_ms());
    }

    #[test]
    fn test_read_without_url_uses_active_tab() {
        let cmd = parse_command(&args("read"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "read");
        assert!(cmd.get("url").is_none());
    }

    #[test]
    fn test_read_flags() {
        let cmd = parse_command(
            &args("read https://example.com --raw --require-md --timeout 2500"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "read");
        assert_eq!(cmd["url"], "https://example.com");
        assert_eq!(cmd["raw"], true);
        assert_eq!(cmd["requireMd"], true);
        assert_eq!(cmd["timeout"], 2500);
    }

    #[test]
    fn test_read_includes_global_headers_and_allowed_domains() {
        let mut flags = default_flags();
        flags.headers = Some(r#"{"Authorization":"Bearer token","X-Trace":"abc"}"#.to_string());
        flags.allowed_domains = Some(vec!["example.com".to_string(), "*.example.org".to_string()]);

        let cmd = parse_command(&args("read https://example.com/docs"), &flags).unwrap();

        assert_eq!(cmd["action"], "read");
        assert_eq!(cmd["headers"]["Authorization"], "Bearer token");
        assert_eq!(cmd["headers"]["X-Trace"], "abc");
        assert_eq!(
            cmd["allowedDomains"],
            json!(["example.com", "*.example.org"])
        );
    }

    #[test]
    fn test_read_rejects_invalid_headers_json() {
        let mut flags = default_flags();
        flags.headers = Some("not json".to_string());

        let result = parse_command(&args("read https://example.com/docs"), &flags);

        assert!(matches!(result, Err(ParseError::InvalidValue { .. })));
    }

    #[test]
    fn test_read_llms_index_filter_flags() {
        let cmd = parse_command(
            &args("read https://example.com/docs --llms index --filter auth"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "read");
        assert_eq!(cmd["url"], "https://example.com/docs");
        assert_eq!(cmd["llms"], "index");
        assert_eq!(cmd["filter"], "auth");
    }

    #[test]
    fn test_read_llms_full_filter_flags() {
        let cmd = parse_command(
            &args("read https://example.com/docs --llms full --filter auth"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "read");
        assert_eq!(cmd["url"], "https://example.com/docs");
        assert_eq!(cmd["llms"], "full");
        assert_eq!(cmd["filter"], "auth");
    }

    #[test]
    fn test_read_outline_filter_flags() {
        let cmd = parse_command(
            &args("read https://example.com/docs --outline --filter auth"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "read");
        assert_eq!(cmd["url"], "https://example.com/docs");
        assert_eq!(cmd["outline"], true);
        assert_eq!(cmd["filter"], "auth");
    }

    #[test]
    fn test_read_rejects_llms_with_outline() {
        let result = parse_command(
            &args("read https://example.com --llms index --outline"),
            &default_flags(),
        );
        assert!(matches!(result, Err(ParseError::InvalidValue { .. })));
    }

    #[test]
    fn test_read_rejects_invalid_llms_mode() {
        let result = parse_command(
            &args("read https://example.com --llms toc"),
            &default_flags(),
        );
        assert!(matches!(result, Err(ParseError::InvalidValue { .. })));
    }

    #[test]
    fn test_read_filter_without_llms_or_outline_filters_page_sections() {
        let cmd = parse_command(
            &args("read https://example.com --filter auth"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "read");
        assert_eq!(cmd["url"], "https://example.com");
        assert_eq!(cmd["filter"], "auth");
    }

    #[test]
    fn test_read_rejects_invalid_timeout() {
        let result = parse_command(&args("read example.com --timeout nope"), &default_flags());
        assert!(matches!(result, Err(ParseError::InvalidValue { .. })));
    }

    #[test]
    fn test_navigate_with_headers() {
        let mut flags = default_flags();
        flags.headers = Some(r#"{"Authorization": "Bearer token"}"#.to_string());
        let cmd = parse_command(&args("open api.example.com"), &flags).unwrap();
        assert_eq!(cmd["action"], "navigate");
        assert_eq!(cmd["url"], "https://api.example.com");
        assert_eq!(cmd["headers"]["Authorization"], "Bearer token");
    }

    #[test]
    fn test_navigate_with_multiple_headers() {
        let mut flags = default_flags();
        flags.headers =
            Some(r#"{"Authorization": "Bearer token", "X-Custom": "value"}"#.to_string());
        let cmd = parse_command(&args("open api.example.com"), &flags).unwrap();
        assert_eq!(cmd["headers"]["Authorization"], "Bearer token");
        assert_eq!(cmd["headers"]["X-Custom"], "value");
    }

    #[test]
    fn test_navigate_without_headers_flag() {
        let cmd = parse_command(&args("open example.com"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "navigate");
        // headers should not be present when flag is not set
        assert!(cmd.get("headers").is_none());
    }

    #[test]
    fn test_navigate_with_invalid_headers_json() {
        let mut flags = default_flags();
        flags.headers = Some("not valid json".to_string());
        let result = parse_command(&args("open api.example.com"), &flags);
        // Invalid JSON should return a ParseError, not silently drop headers
        assert!(result.is_err());
        let err = result.unwrap_err();
        let msg = err.format();
        assert!(msg.contains("Invalid JSON for --headers"));
    }

    #[test]
    fn test_navigate_chrome_extension_url() {
        let cmd = parse_command(
            &args("open chrome-extension://abcdefghijklmnop/popup.html"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "navigate");
        assert_eq!(cmd["url"], "chrome-extension://abcdefghijklmnop/popup.html");
    }

    #[test]
    fn test_navigate_chrome_url() {
        let cmd = parse_command(&args("open chrome://extensions"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "navigate");
        assert_eq!(cmd["url"], "chrome://extensions");
    }

    // === Set Headers Tests ===

    #[test]
    fn test_set_headers_parses_json() {
        let input: Vec<String> = vec![
            "set".to_string(),
            "headers".to_string(),
            r#"{"Authorization":"Bearer token"}"#.to_string(),
        ];
        let cmd = parse_command(&input, &default_flags()).unwrap();
        assert_eq!(cmd["action"], "headers");
        // Headers should be an object, not a string
        assert!(cmd["headers"].is_object());
        assert_eq!(cmd["headers"]["Authorization"], "Bearer token");
    }

    #[test]
    fn test_set_headers_with_multiple_values() {
        let input: Vec<String> = vec![
            "set".to_string(),
            "headers".to_string(),
            r#"{"Authorization": "Bearer token", "X-Custom": "value"}"#.to_string(),
        ];
        let cmd = parse_command(&input, &default_flags()).unwrap();
        assert_eq!(cmd["headers"]["Authorization"], "Bearer token");
        assert_eq!(cmd["headers"]["X-Custom"], "value");
    }

    #[test]
    fn test_set_headers_invalid_json_error() {
        let input: Vec<String> = vec![
            "set".to_string(),
            "headers".to_string(),
            "not-valid-json".to_string(),
        ];
        let result = parse_command(&input, &default_flags());
        assert!(result.is_err());
    }

    #[test]
    fn test_back() {
        let cmd = parse_command(&args("back"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "back");
    }

    #[test]
    fn test_forward() {
        let cmd = parse_command(&args("forward"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "forward");
    }

    #[test]
    fn test_reload() {
        let cmd = parse_command(&args("reload"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "reload");
    }

    // === Core Actions ===

    #[test]
    fn test_click() {
        let cmd = parse_command(&args("click #button"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "click");
        assert_eq!(cmd["selector"], "#button");
    }

    #[test]
    fn test_click_human() {
        let cmd = parse_command(&args("click @e1 --human"), &default_flags()).unwrap();
        assert_eq!(cmd["selector"], "@e1");
        assert_eq!(cmd["inputMode"], "human");
    }

    #[test]
    fn test_mouse_move_interpolation_options() {
        let cmd = parse_command(
            &args("mouse move 600 400 --duration 250 --steps 24 --seed 42 --human"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["duration"], 250);
        assert_eq!(cmd["steps"], 24);
        assert_eq!(cmd["seed"], 42);
        assert_eq!(cmd["inputMode"], "human");
    }

    #[test]
    fn test_fill() {
        let cmd = parse_command(&args("fill #input hello world"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "fill");
        assert_eq!(cmd["selector"], "#input");
        assert_eq!(cmd["value"], "hello world");
    }

    #[test]
    fn test_fill_and_type_preserve_text_after_end_of_options() {
        let fill_args = args("fill #input -- --config /missing --json café 世界");
        let fill = parse_command(&crate::flags::clean_args(&fill_args), &default_flags()).unwrap();
        assert_eq!(fill["value"], "--config /missing --json café 世界");

        let empty_fill = parse_command(&args("fill #input --"), &default_flags()).unwrap();
        assert_eq!(empty_fill["value"], "");

        let type_args =
            args("type #input --clear --delay 7 -- --clear --delay 99 café 世界 -- --help");
        let typed = parse_command(&crate::flags::clean_args(&type_args), &default_flags()).unwrap();
        assert_eq!(typed["clear"], true);
        assert_eq!(typed["delay"], 7);
        assert_eq!(typed["text"], "--clear --delay 99 café 世界 -- --help");

        let empty_type =
            parse_command(&args("type #input --clear --delay 7 --"), &default_flags()).unwrap();
        assert_eq!(empty_type["clear"], true);
        assert_eq!(empty_type["delay"], 7);
        assert_eq!(empty_type["text"], "");
    }

    #[test]
    fn test_type_command() {
        let cmd = parse_command(&args("type #input some text"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "type");
        assert_eq!(cmd["selector"], "#input");
        assert_eq!(cmd["text"], "some text");
    }

    #[test]
    fn test_find_fill_value_survives_for_all_locators() {
        // fill is advertised for these locators, so the value must reach dispatch.
        // Force-red: drop the value block from the text/alt/title arms and these
        // assertions fail (value missing).
        for (loc, action) in [
            ("text", "getbytext"),
            ("alt", "getbyalttext"),
            ("title", "getbytitle"),
        ] {
            let cmd = parse_command(
                &args(&format!("find {loc} Label fill hello")),
                &default_flags(),
            )
            .unwrap();
            assert_eq!(cmd["action"], action, "{loc}");
            assert_eq!(cmd["value"], "hello", "{loc} dropped the fill value");
        }
    }

    #[test]
    fn test_select() {
        let cmd = parse_command(&args("select #menu option1"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "select");
        assert_eq!(cmd["selector"], "#menu");
        assert_eq!(cmd["values"], "option1");
    }

    #[test]
    fn test_select_multiple_values() {
        let cmd = parse_command(&args("select #menu opt1 opt2 opt3"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "select");
        assert_eq!(cmd["selector"], "#menu");
        assert_eq!(cmd["values"], json!(["opt1", "opt2", "opt3"]));
    }

    #[test]
    fn test_frame_main() {
        let cmd = parse_command(&args("frame main"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "mainframe");
    }

    // === Tabs ===

    #[test]
    fn test_tab_new() {
        let cmd = parse_command(&args("tab new"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_new");
        assert!(
            cmd.get("url").is_none(),
            "url should not be present when not provided"
        );
    }

    #[test]
    fn test_tab_new_with_url() {
        let cmd = parse_command(&args("tab new https://example.com"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_new");
        assert_eq!(cmd["url"], "https://example.com");
    }

    #[test]
    fn test_tab_list() {
        let cmd = parse_command(&args("tab list"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_list");
    }

    #[test]
    fn test_tab_switch_by_id() {
        let cmd = parse_command(&args("tab t2"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_switch");
        assert_eq!(cmd["tabId"], "t2");
    }

    #[test]
    fn test_tab_switch_by_label() {
        let cmd = parse_command(&args("tab docs"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_switch");
        assert_eq!(cmd["tabId"], "docs");
    }

    #[test]
    fn test_tab_close() {
        let cmd = parse_command(&args("tab close"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_close");
    }

    #[test]
    fn test_tab_close_with_id() {
        let cmd = parse_command(&args("tab close t2"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_close");
        assert_eq!(cmd["tabId"], "t2");
    }

    #[test]
    fn test_tab_close_with_label() {
        let cmd = parse_command(&args("tab close docs"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_close");
        assert_eq!(cmd["tabId"], "docs");
    }

    #[test]
    fn test_tab_sends_string_tab_id() {
        let cmd = parse_command(&args("tab t2"), &default_flags()).unwrap();
        assert!(
            cmd["tabId"].is_string(),
            "tabId must be a string, got: {:?}",
            cmd["tabId"]
        );
        assert!(cmd.get("index").is_none());
    }

    #[test]
    fn test_tab_new_with_label() {
        let cmd = parse_command(&args("tab new --label docs"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_new");
        assert_eq!(cmd["label"], "docs");
    }

    #[test]
    fn test_tab_new_with_label_and_url() {
        let cmd = parse_command(
            &args("tab new --label docs https://docs.example.com"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "tab_new");
        assert_eq!(cmd["label"], "docs");
        assert_eq!(cmd["url"], "https://docs.example.com");
    }

    #[test]
    fn test_tab_new_with_url_then_label() {
        let cmd = parse_command(
            &args("tab new https://docs.example.com --label docs"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["url"], "https://docs.example.com");
        assert_eq!(cmd["label"], "docs");
    }

    #[test]
    fn test_tab_no_args_defaults_to_list() {
        let cmd = parse_command(&args("tab"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_list");
    }

    #[test]
    fn test_tab_unknown_flag_errors() {
        // Unknown flags on `tab new` must error instead of being silently
        // dropped. This protects against typos like `--labl` or `--new-tab`.
        let result = parse_command(
            &args("tab new --unknown-flag https://example.com"),
            &default_flags(),
        );
        assert!(
            result.is_err(),
            "tab new with an unknown flag must error, got: {:?}",
            result
        );
    }

    #[test]
    fn test_tab_non_keyword_treated_as_ref() {
        // After the shift to `t<N>`/label ids, non-keyword tokens (`select`,
        // `docs`, etc.) are valid label refs; `tab <something>` routes to
        // tab_switch and the runtime decides whether the label exists.
        let cmd = parse_command(&args("tab select"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "tab_switch");
        assert_eq!(cmd["tabId"], "select");
    }

    // === Network ===

    #[test]
    fn test_network_har_start() {
        let cmd = parse_command(&args("network har start"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "har_start");
        assert!(cmd.get("content").is_none());
    }

    #[test]
    fn test_network_har_start_with_content_mode() {
        let cmd =
            parse_command(&args("network har start --content all"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "har_start");
        assert_eq!(cmd["content"], "all");
    }

    #[test]
    fn test_network_har_start_rejects_invalid_content_mode() {
        let result = parse_command(&args("network har start --content huge"), &default_flags());
        assert!(matches!(result, Err(ParseError::InvalidValue { .. })));
    }

    #[test]
    fn test_network_har_start_content_requires_value() {
        let result = parse_command(&args("network har start --content"), &default_flags());
        assert!(matches!(result, Err(ParseError::MissingArguments { .. })));
    }

    #[test]
    fn test_network_har_stop_with_path() {
        let cmd = parse_command(&args("network har stop ./capture.har"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "har_stop");
        assert_eq!(cmd["path"], "./capture.har");
    }

    #[test]
    fn test_network_har_stop_without_path() {
        let cmd = parse_command(&args("network har stop"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "har_stop");
        assert!(cmd.get("path").is_none());
    }

    #[test]
    fn test_network_har_requires_subcommand() {
        let result = parse_command(&args("network har"), &default_flags());
        assert!(matches!(result, Err(ParseError::MissingArguments { .. })));
    }

    #[test]
    fn test_network_requests_type_filter() {
        let cmd =
            parse_command(&args("network requests --type xhr,fetch"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "requests");
        assert_eq!(cmd["type"], "xhr,fetch");
    }

    #[test]
    fn test_network_requests_method_filter() {
        let cmd = parse_command(&args("network requests --method POST"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "requests");
        assert_eq!(cmd["method"], "POST");
    }

    #[test]
    fn test_network_requests_status_filter() {
        let cmd = parse_command(&args("network requests --status 2xx"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "requests");
        assert_eq!(cmd["status"], "2xx");
    }

    #[test]
    fn test_network_requests_combined_filters() {
        let cmd = parse_command(
            &args("network requests --filter api --type xhr --method GET --status 200"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["filter"], "api");
        assert_eq!(cmd["type"], "xhr");
        assert_eq!(cmd["method"], "GET");
        assert_eq!(cmd["status"], "200");
    }

    #[test]
    fn test_network_request_detail() {
        let cmd = parse_command(&args("network request 1234.5"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "request_detail");
        assert_eq!(cmd["requestId"], "1234.5");
    }

    #[test]
    fn test_network_request_detail_requires_id() {
        let result = parse_command(&args("network request"), &default_flags());
        assert!(matches!(result, Err(ParseError::MissingArguments { .. })));
    }

    // === Screenshot ===

    #[test]
    fn test_screenshot() {
        let cmd = parse_command(&args("screenshot"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "screenshot");
        assert_eq!(cmd["path"], serde_json::Value::Null);
        assert_eq!(cmd["selector"], serde_json::Value::Null);
    }

    #[test]
    fn test_screenshot_path() {
        let cmd = parse_command(&args("screenshot out.png"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "screenshot");
        assert_eq!(cmd["path"], "out.png");
    }

    #[test]
    fn test_screenshot_full_page() {
        let cmd = parse_command(&args("screenshot --full"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "screenshot");
        assert_eq!(cmd["fullPage"], true);
    }

    #[test]
    fn test_screenshot_full_page_shorthand() {
        let cmd = parse_command(&args("screenshot -f"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "screenshot");
        assert_eq!(cmd["fullPage"], true);
    }

    #[test]
    fn test_screenshot_with_ref() {
        let cmd = parse_command(&args("screenshot @e1"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "screenshot");
        assert_eq!(cmd["selector"], "@e1");
        assert_eq!(cmd["path"], serde_json::Value::Null);
    }

    #[test]
    fn test_screenshot_with_css_class() {
        let cmd = parse_command(&args("screenshot .my-button"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "screenshot");
        assert_eq!(cmd["selector"], ".my-button");
        assert_eq!(cmd["path"], serde_json::Value::Null);
    }

    #[test]
    fn test_screenshot_with_css_id() {
        let cmd = parse_command(&args("screenshot #header"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "screenshot");
        assert_eq!(cmd["selector"], "#header");
        assert_eq!(cmd["path"], serde_json::Value::Null);
    }

    #[test]
    fn test_screenshot_with_path() {
        let cmd = parse_command(&args("screenshot ./output.png"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "screenshot");
        assert_eq!(cmd["selector"], serde_json::Value::Null);
        assert_eq!(cmd["path"], "./output.png");
    }

    #[test]
    fn test_screenshot_with_selector_and_path() {
        let cmd = parse_command(&args("screenshot .btn ./button.png"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "screenshot");
        assert_eq!(cmd["selector"], ".btn");
        assert_eq!(cmd["path"], "./button.png");
    }

    #[test]
    fn test_screenshot_if_changed() {
        let cmd = parse_command(&args("screenshot --if-changed"), &default_flags()).unwrap();
        assert_eq!(cmd["ifChanged"], true);
        assert!(cmd.get("threshold").is_none());
    }

    #[test]
    fn test_screenshot_threshold_implies_if_changed() {
        let cmd = parse_command(
            &args("screenshot .btn ./button.png --threshold 0.025"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["selector"], ".btn");
        assert_eq!(cmd["path"], "./button.png");
        assert_eq!(cmd["ifChanged"], true);
        assert_eq!(cmd["threshold"], 0.025);
    }

    #[test]
    fn test_screenshot_threshold_rejects_out_of_range_value() {
        let result = parse_command(&args("screenshot --threshold 1.1"), &default_flags());
        assert!(matches!(result, Err(ParseError::InvalidValue { .. })));
    }

    #[test]
    fn test_screenshot_threshold_requires_value() {
        let result = parse_command(&args("screenshot --threshold"), &default_flags());
        assert!(matches!(result, Err(ParseError::MissingArguments { .. })));
    }

    // === Snapshot ===

    #[test]
    fn test_snapshot() {
        let cmd = parse_command(&args("snapshot"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "snapshot");
    }

    #[test]
    fn test_snapshot_delta_and_full_flags() {
        let cmd = parse_command(&args("snapshot --delta --full"), &default_flags()).unwrap();
        assert_eq!(cmd["delta"], true);
        assert_eq!(cmd["full"], true);
    }

    #[test]
    fn test_snapshot_interactive() {
        let cmd = parse_command(&args("snapshot -i"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "snapshot");
        assert_eq!(cmd["interactive"], true);
    }

    #[test]
    fn test_snapshot_cursor() {
        let cmd = parse_command(&args("snapshot -C"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "snapshot");
        assert_eq!(cmd["cursor"], true);
    }

    #[test]
    fn test_snapshot_interactive_cursor() {
        let cmd = parse_command(&args("snapshot -i -C"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "snapshot");
        assert_eq!(cmd["interactive"], true);
        assert_eq!(cmd["cursor"], true);
    }

    #[test]
    fn test_snapshot_compact() {
        let cmd = parse_command(&args("snapshot --compact"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "snapshot");
        assert_eq!(cmd["compact"], true);
    }

    #[test]
    fn test_snapshot_depth() {
        let cmd = parse_command(&args("snapshot -d 3"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "snapshot");
        assert_eq!(cmd["maxDepth"], 3);
    }

    #[test]
    fn test_snapshot_urls() {
        let cmd = parse_command(&args("snapshot -i --urls"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "snapshot");
        assert_eq!(cmd["interactive"], true);
        assert_eq!(cmd["urls"], true);
    }

    #[test]
    fn test_snapshot_urls_short() {
        let cmd = parse_command(&args("snapshot -i -u"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "snapshot");
        assert_eq!(cmd["urls"], true);
    }

    // === Wait ===

    #[test]
    fn test_wait_selector() {
        let cmd = parse_command(&args("wait #element"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "wait");
        assert_eq!(cmd["selector"], "#element");
    }

    #[test]
    fn test_wait_selector_state_in_either_order() {
        for (command, state) in [
            ("wait #spinner --state visible", "visible"),
            ("wait --state hidden #spinner", "hidden"),
            ("wait #spinner --state attached", "attached"),
            ("wait --state detached #spinner", "detached"),
        ] {
            let cmd = parse_command(&args(command), &default_flags()).unwrap();
            assert_eq!(cmd["selector"], "#spinner");
            assert_eq!(cmd["state"], state);
        }
    }

    #[test]
    fn test_wait_selector_state_with_timeout() {
        let cmd = parse_command(
            &args("wait --state hidden #spinner --timeout 9000"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["state"], "hidden");
        assert_eq!(cmd["timeout"], 9000);
    }

    #[test]
    fn test_wait_selector_state_rejects_unknown_value() {
        for state in ["gone", "/tmp/auth.json"] {
            let error = parse_command(
                &args(&format!("wait #spinner --state {state}")),
                &default_flags(),
            )
            .unwrap_err();
            assert!(matches!(error, ParseError::InvalidValue { .. }));
            assert!(error.format().contains("put --state <path> before wait"));
        }
    }

    #[test]
    fn test_wait_selector_state_rejects_non_selector_waits() {
        for command in [
            "wait --url **/dashboard --state hidden",
            "wait --load networkidle --state hidden",
            "wait --fn true --state hidden",
            "wait --text Ready --state hidden",
            "wait --download --state hidden",
            "wait 1000 --state hidden",
        ] {
            assert!(matches!(
                parse_command(&args(command), &default_flags()),
                Err(ParseError::InvalidValue { .. })
            ));
        }
    }

    #[test]
    fn test_wait_timeout() {
        let cmd = parse_command(&args("wait 5000"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "wait");
        assert_eq!(cmd["timeout"], 5000);
    }

    #[test]
    fn test_wait_url() {
        let cmd = parse_command(&args("wait --url **/dashboard"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "waitforurl");
        assert_eq!(cmd["url"], "**/dashboard");
    }

    #[test]
    fn test_wait_load() {
        let cmd = parse_command(&args("wait --load networkidle"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "waitforloadstate");
        assert_eq!(cmd["state"], "networkidle");
    }

    #[test]
    fn test_wait_load_missing_state() {
        let result = parse_command(&args("wait --load"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_wait_fn() {
        let cmd = parse_command(&args("wait --fn window.ready"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "waitforfunction");
        assert_eq!(cmd["expression"], "window.ready");
    }

    #[test]
    fn test_wait_text() {
        let cmd = parse_command(&args("wait --text Welcome"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "wait");
        assert_eq!(cmd["text"], "Welcome");
        assert!(cmd.get("timeout").is_none());
    }

    #[test]
    fn test_wait_text_with_timeout() {
        let cmd = parse_command(
            &args("wait --text Welcome --timeout 5000"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "wait");
        assert_eq!(cmd["text"], "Welcome");
        assert_eq!(cmd["timeout"], 5000);
    }

    // === Clipboard Tests ===

    #[test]
    fn test_clipboard_read_default() {
        let cmd = parse_command(&args("clipboard"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "clipboard");
        assert_eq!(cmd["operation"], "read");
    }

    #[test]
    fn test_clipboard_read_explicit() {
        let cmd = parse_command(&args("clipboard read"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "clipboard");
        assert_eq!(cmd["operation"], "read");
    }

    #[test]
    fn test_clipboard_write() {
        let cmd = parse_command(&args("clipboard write hello"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "clipboard");
        assert_eq!(cmd["operation"], "write");
        assert_eq!(cmd["text"], "hello");
    }

    #[test]
    fn test_clipboard_write_multi_word() {
        let cmd = parse_command(&args("clipboard write hello world"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "clipboard");
        assert_eq!(cmd["operation"], "write");
        assert_eq!(cmd["text"], "hello world");
    }

    #[test]
    fn test_clipboard_copy() {
        let cmd = parse_command(&args("clipboard copy"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "clipboard");
        assert_eq!(cmd["operation"], "copy");
    }

    #[test]
    fn test_clipboard_paste() {
        let cmd = parse_command(&args("clipboard paste"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "clipboard");
        assert_eq!(cmd["operation"], "paste");
    }

    #[test]
    fn test_clipboard_write_missing_text() {
        let result = parse_command(&args("clipboard write"), &default_flags());
        assert!(result.is_err());
    }

    #[test]
    fn test_clipboard_unknown_subcommand() {
        let result = parse_command(&args("clipboard clear"), &default_flags());
        assert!(result.is_err());
    }

    // === Unknown command ===

    // === Record Tests ===

    #[test]
    fn test_record_start() {
        let cmd = parse_command(&args("record start output.webm"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "recording_start");
        assert_eq!(cmd["path"], "output.webm");
        assert!(cmd.get("url").is_none());
        // Omitting --fps lets the daemon apply its 30 fps default.
        assert!(cmd.get("fps").is_none());
    }

    #[test]
    fn test_record_start_with_fps() {
        let cmd =
            parse_command(&args("record start output.webm --fps 60"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "recording_start");
        assert_eq!(cmd["path"], "output.webm");
        assert_eq!(cmd["fps"], 60);
    }

    #[test]
    fn test_record_start_with_cursor() {
        let cmd =
            parse_command(&args("record start output.webm --cursor"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "recording_start");
        assert_eq!(cmd["cursor"], true);
    }

    #[test]
    fn test_record_start_with_contact_sheet() {
        let cmd = parse_command(
            &args("record start output.webm --contact-sheet --contact-sheet-threshold 0.12"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["contactSheet"], true);
        assert_eq!(cmd["contactSheetThreshold"], 0.12);
    }

    #[test]
    fn test_record_start_threshold_implies_contact_sheet() {
        let cmd = parse_command(
            &args("record start output.webm --contact-sheet-threshold 0.01"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["contactSheet"], true);
        assert_eq!(cmd["contactSheetThreshold"], 0.01);
    }

    #[test]
    fn test_record_start_rejects_invalid_contact_sheet_threshold() {
        for value in ["-0.1", "1.1", "many"] {
            let result = parse_command(
                &args(&format!(
                    "record start output.webm --contact-sheet-threshold {}",
                    value
                )),
                &default_flags(),
            );
            assert!(result.is_err(), "threshold {value} should fail");
        }
    }

    #[test]
    fn test_record_start_with_url_and_fps() {
        let cmd = parse_command(
            &args("record start demo.webm example.com --fps 24"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["path"], "demo.webm");
        assert_eq!(cmd["url"], "https://example.com");
        assert_eq!(cmd["fps"], 24);
    }

    #[test]
    fn test_record_start_with_fps_before_url() {
        let cmd = parse_command(
            &args("record start demo.webm --fps 60 https://example.com"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["path"], "demo.webm");
        assert_eq!(cmd["url"], "https://example.com");
        assert_eq!(cmd["fps"], 60);
    }

    #[test]
    fn test_record_start_rejects_fps_above_max() {
        let result = parse_command(&args("record start demo.webm --fps 120"), &default_flags());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_record_start_rejects_zero_fps() {
        let result = parse_command(&args("record start demo.webm --fps 0"), &default_flags());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_record_start_accepts_any_extension() {
        // .webm and .mp4 are the documented formats; other containers
        // worked before validation existed and are still passed through.
        for path in [
            "demo.mp4",
            "./out/DEMO.WEBM",
            "Take.Mp4",
            "take.mkv",
            "take.mov",
            "dir.v2/take.MP4",
        ] {
            let cmd = parse_command(&args(&format!("record start {}", path)), &default_flags())
                .unwrap_or_else(|e| panic!("{} should parse: {:?}", path, e));
            assert_eq!(cmd["action"], "recording_start");
            assert_eq!(cmd["path"], path);
        }
    }

    #[test]
    fn test_record_start_rejects_extensionless_path() {
        for path in ["take", "dir.v2/take", ".hidden"] {
            let err = parse_command(&args(&format!("record start {}", path)), &default_flags())
                .unwrap_err();
            match err {
                ParseError::InvalidValue { message, usage } => {
                    assert!(message.contains(path), "should name the path: {}", message);
                    assert!(message.contains("no extension"), "message was: {}", message);
                    assert!(
                        message.contains(".webm"),
                        "should suggest .webm: {}",
                        message
                    );
                    assert!(message.contains(".mp4"), "should suggest .mp4: {}", message);
                    assert!(usage.starts_with("record start"), "usage was: {}", usage);
                }
                other => panic!("expected InvalidValue for {}, got {:?}", path, other),
            }
        }
    }

    #[test]
    fn test_record_start_rejects_extensionless_path_with_valid_fps() {
        // The path is validated once all flags are parsed, so a bad path
        // is reported even when --fps is fine.
        let err = parse_command(&args("record start take --fps 60"), &default_flags()).unwrap_err();
        assert!(
            matches!(err, ParseError::InvalidValue { ref message, .. } if message.contains("output path"))
        );
    }

    #[test]
    fn test_record_restart_rejects_extensionless_path() {
        let err = parse_command(&args("record restart take2"), &default_flags()).unwrap_err();
        match err {
            ParseError::InvalidValue { message, usage } => {
                assert!(message.contains("take2"), "message was: {}", message);
                assert!(usage.starts_with("record restart"), "usage was: {}", usage);
            }
            other => panic!("expected InvalidValue, got {:?}", other),
        }
    }

    #[test]
    fn test_record_start_rejects_non_numeric_fps() {
        let result = parse_command(&args("record start demo.webm --fps fast"), &default_flags());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_record_start_rejects_fps_without_value() {
        let result = parse_command(&args("record start demo.webm --fps"), &default_flags());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_record_start_rejects_unknown_flag() {
        let result = parse_command(&args("record start demo.webm --smooth"), &default_flags());
        match result.unwrap_err() {
            ParseError::InvalidValue { message, .. } => {
                assert!(message.contains("--smooth"), "got: {message}");
            }
            other => panic!("expected InvalidValue, got {other:?}"),
        }
    }

    #[test]
    fn test_record_start_rejects_extra_positional() {
        let result = parse_command(
            &args("record start demo.webm example.com extra"),
            &default_flags(),
        );
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_record_restart_with_fps() {
        let cmd = parse_command(
            &args("record restart take2.webm --fps 60"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "recording_restart");
        assert_eq!(cmd["path"], "take2.webm");
        assert_eq!(cmd["fps"], 60);
    }

    #[test]
    fn test_record_start_with_url() {
        let cmd = parse_command(
            &args("record start demo.webm https://example.com"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "recording_start");
        assert_eq!(cmd["path"], "demo.webm");
        assert_eq!(cmd["url"], "https://example.com");
    }

    #[test]
    fn test_record_start_with_url_no_protocol() {
        let cmd = parse_command(
            &args("record start demo.webm example.com"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "recording_start");
        assert_eq!(cmd["path"], "demo.webm");
        assert_eq!(cmd["url"], "https://example.com");
    }

    #[test]
    fn test_record_start_with_chrome_extension_url() {
        let cmd = parse_command(
            &args("record start demo.webm chrome-extension://abcdef/popup.html"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "recording_start");
        assert_eq!(cmd["path"], "demo.webm");
        assert_eq!(cmd["url"], "chrome-extension://abcdef/popup.html");
    }

    #[test]
    fn test_record_start_missing_path() {
        let result = parse_command(&args("record start"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_record_stop() {
        let cmd = parse_command(&args("record stop"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "recording_stop");
    }

    #[test]
    fn test_record_restart() {
        let cmd = parse_command(&args("record restart output.webm"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "recording_restart");
        assert_eq!(cmd["path"], "output.webm");
        assert!(cmd.get("url").is_none());
    }

    #[test]
    fn test_record_restart_with_url() {
        let cmd = parse_command(
            &args("record restart demo.webm https://example.com"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "recording_restart");
        assert_eq!(cmd["path"], "demo.webm");
        assert_eq!(cmd["url"], "https://example.com");
    }

    #[test]
    fn test_record_restart_missing_path() {
        let result = parse_command(&args("record restart"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_record_invalid_subcommand() {
        let result = parse_command(&args("record foo"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::UnknownSubcommand { .. }
        ));
    }

    #[test]
    fn test_record_missing_subcommand() {
        let result = parse_command(&args("record"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    // === Profile (CDP Tracing) Tests ===

    #[test]
    fn test_profiler_start() {
        let cmd = parse_command(&args("profiler start"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "profiler_start");
        assert!(cmd.get("categories").is_none());
    }

    #[test]
    fn test_profiler_start_with_categories() {
        let cmd = parse_command(
            &args("profiler start --categories devtools.timeline,v8.execute"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "profiler_start");
        let categories = cmd["categories"].as_array().unwrap();
        assert_eq!(categories.len(), 2);
        assert_eq!(categories[0], "devtools.timeline");
        assert_eq!(categories[1], "v8.execute");
    }

    #[test]
    fn test_profiler_start_categories_missing_value() {
        let result = parse_command(&args("profiler start --categories"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_profiler_stop_with_path() {
        let cmd = parse_command(&args("profiler stop trace.json"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "profiler_stop");
        assert_eq!(cmd["path"], "trace.json");
    }

    #[test]
    fn test_profiler_stop_no_path() {
        let cmd = parse_command(&args("profiler stop"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "profiler_stop");
        assert!(cmd.get("path").is_none());
    }

    #[test]
    fn test_profiler_invalid_subcommand() {
        let result = parse_command(&args("profiler foo"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::UnknownSubcommand { .. }
        ));
    }

    #[test]
    fn test_profiler_missing_subcommand() {
        let result = parse_command(&args("profiler"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    // === Eval Tests ===

    #[test]
    fn test_eval_basic() {
        let cmd = parse_command(&args("eval document.title"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "evaluate");
        assert_eq!(cmd["script"], "document.title");
    }

    #[test]
    fn test_eval_base64_short_flag() {
        // "document.title" in base64
        let cmd = parse_command(&args("eval -b ZG9jdW1lbnQudGl0bGU="), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "evaluate");
        assert_eq!(cmd["script"], "document.title");
    }

    #[test]
    fn test_eval_base64_long_flag() {
        // "document.title" in base64
        let cmd = parse_command(
            &args("eval --base64 ZG9jdW1lbnQudGl0bGU="),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "evaluate");
        assert_eq!(cmd["script"], "document.title");
    }

    #[test]
    fn test_eval_base64_with_special_chars() {
        // "document.querySelector('[src*=\"_next\"]')" in base64
        let cmd = parse_command(
            &args("eval -b ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ=="),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "evaluate");
        assert_eq!(cmd["script"], "document.querySelector('[src*=\"_next\"]')");
    }

    #[test]
    fn test_eval_base64_invalid() {
        let result = parse_command(&args("eval -b !!!invalid!!!"), &default_flags());
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ParseError::InvalidValue { .. }));
        assert!(err.format().contains("Invalid base64"));
    }

    #[test]
    fn test_unknown_command() {
        let result = parse_command(&args("unknowncommand"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::UnknownCommand { .. }
        ));
    }

    #[test]
    fn test_empty_args() {
        let result = parse_command(&[], &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    // === Error message tests ===

    #[test]
    fn test_get_missing_subcommand() {
        let result = parse_command(&args("get"), &default_flags());
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ParseError::MissingArguments { .. }));
        assert!(err.format().contains("get"));
    }

    #[test]
    fn test_get_unknown_subcommand() {
        let result = parse_command(&args("get foo"), &default_flags());
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ParseError::UnknownSubcommand { .. }));
        assert!(err.format().contains("foo"));
        assert!(err.format().contains("text"));
    }

    #[test]
    fn test_get_text_missing_selector() {
        let result = parse_command(&args("get text"), &default_flags());
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ParseError::MissingArguments { .. }));
        assert!(err.format().contains("get text"));
    }

    // === Protocol alignment tests ===

    #[test]
    fn test_mouse_wheel() {
        let cmd = parse_command(&args("mouse wheel 100 50"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "wheel");
        assert_eq!(cmd["deltaY"], 100);
        assert_eq!(cmd["deltaX"], 50);
    }

    #[test]
    fn test_set_media() {
        let cmd = parse_command(&args("set media dark"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "emulatemedia");
        assert_eq!(cmd["colorScheme"], "dark");
        assert_eq!(cmd["reducedMotion"], "no-preference");
    }

    #[test]
    fn test_set_media_reduced_motion() {
        let cmd = parse_command(&args("set media light reduced-motion"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "emulatemedia");
        assert_eq!(cmd["colorScheme"], "light");
        assert_eq!(cmd["reducedMotion"], "reduce");
    }

    #[test]
    fn test_set_viewport() {
        let cmd = parse_command(&args("set viewport 1920 1080"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "viewport");
        assert_eq!(cmd["width"], 1920);
        assert_eq!(cmd["height"], 1080);
        assert!(cmd.get("deviceScaleFactor").is_none());
    }

    #[test]
    fn test_set_viewport_with_scale() {
        let cmd = parse_command(&args("set viewport 1920 1080 2"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "viewport");
        assert_eq!(cmd["width"], 1920);
        assert_eq!(cmd["height"], 1080);
        assert_eq!(cmd["deviceScaleFactor"], 2.0);
    }

    #[test]
    fn test_set_viewport_with_fractional_scale() {
        let cmd = parse_command(&args("set viewport 375 812 3"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "viewport");
        assert_eq!(cmd["width"], 375);
        assert_eq!(cmd["height"], 812);
        assert_eq!(cmd["deviceScaleFactor"], 3.0);
    }

    #[test]
    fn test_set_viewport_missing_height() {
        let result = parse_command(&args("set viewport 1920"), &default_flags());
        assert!(result.is_err());
    }

    #[test]
    fn test_set_viewport_invalid_scale() {
        let result = parse_command(&args("set viewport 1920 1080 abc"), &default_flags());
        assert!(result.is_err());
    }

    #[test]
    fn test_set_rejects_non_finite_float_arguments() {
        for command in [
            "set viewport 800 600 nan",
            "set viewport 800 600 inf",
            "set geo nan 10",
            "set geo 10 inf",
        ] {
            let error = parse_command(&args(command), &default_flags())
                .unwrap_err()
                .format();
            assert!(
                error.contains("finite number"),
                "command should reject non-finite value: {}",
                command
            );
        }
    }

    #[test]
    fn test_find_first_no_value() {
        let cmd = parse_command(&args("find first a click"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "nth");
        assert_eq!(cmd["index"], 0);
        assert!(cmd.get("value").is_none());
    }

    #[test]
    fn test_find_first_with_value() {
        let cmd = parse_command(&args("find first input fill hello"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "nth");
        assert_eq!(cmd["index"], 0);
        assert_eq!(cmd["value"], "hello");
    }

    #[test]
    fn test_find_nth_no_value() {
        let cmd = parse_command(&args("find nth 2 a click"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "nth");
        assert_eq!(cmd["index"], 2);
        assert!(cmd.get("value").is_none());
    }

    #[test]
    fn test_find_role_fill_does_not_include_flags_in_value() {
        let cmd = parse_command(
            &args("find role textbox fill hello --name username --exact"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "getbyrole");
        assert_eq!(cmd["role"], "textbox");
        assert_eq!(cmd["subaction"], "fill");
        assert_eq!(cmd["name"], "username");
        assert_eq!(cmd["exact"], true);
        assert_eq!(cmd["value"], "hello");
    }

    // === Download Tests ===

    #[test]
    fn test_download() {
        let cmd = parse_command(&args("download #btn ./file.pdf"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "download");
        assert_eq!(cmd["selector"], "#btn");
        assert_eq!(cmd["path"], "./file.pdf");
    }

    #[test]
    fn test_download_with_ref() {
        let cmd = parse_command(&args("download @e5 ./report.xlsx"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "download");
        assert_eq!(cmd["selector"], "@e5");
        assert_eq!(cmd["path"], "./report.xlsx");
    }

    #[test]
    fn test_download_missing_path() {
        let result = parse_command(&args("download #btn"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_download_missing_selector() {
        let result = parse_command(&args("download"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    // === Wait for Download Tests ===

    #[test]
    fn test_wait_download() {
        let cmd = parse_command(&args("wait --download"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "waitfordownload");
        assert!(cmd.get("path").is_none());
    }

    #[test]
    fn test_wait_download_with_path() {
        let cmd = parse_command(&args("wait --download ./file.pdf"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "waitfordownload");
        assert_eq!(cmd["path"], "./file.pdf");
    }

    #[test]
    fn test_wait_download_with_timeout() {
        let cmd =
            parse_command(&args("wait --download --timeout 30000"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "waitfordownload");
        assert_eq!(cmd["timeout"], 30000);
    }

    #[test]
    fn test_wait_download_with_path_and_timeout() {
        let cmd = parse_command(
            &args("wait --download ./file.pdf --timeout 30000"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "waitfordownload");
        assert_eq!(cmd["path"], "./file.pdf");
        assert_eq!(cmd["timeout"], 30000);
    }

    #[test]
    fn test_wait_download_short_flag() {
        let cmd = parse_command(&args("wait -d ./file.pdf"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "waitfordownload");
        assert_eq!(cmd["path"], "./file.pdf");
    }

    // === Default timeout (AGENT_BROWSER_DEFAULT_TIMEOUT) tests ===

    fn flags_with_default_timeout(ms: u64) -> Flags {
        let mut f = default_flags();
        f.default_timeout = Some(ms);
        f
    }

    #[test]
    fn test_wait_selector_inherits_default_timeout() {
        let flags = flags_with_default_timeout(3000);
        let cmd = parse_command(&args("wait #element"), &flags).unwrap();
        assert_eq!(cmd["action"], "wait");
        assert_eq!(cmd["selector"], "#element");
        assert_eq!(cmd["timeout"], 3000);
    }

    #[test]
    fn test_wait_url_inherits_default_timeout() {
        let flags = flags_with_default_timeout(4000);
        let cmd = parse_command(&args("wait --url **/dashboard"), &flags).unwrap();
        assert_eq!(cmd["action"], "waitforurl");
        assert_eq!(cmd["timeout"], 4000);
    }

    #[test]
    fn test_wait_load_inherits_default_timeout() {
        let flags = flags_with_default_timeout(4000);
        let cmd = parse_command(&args("wait --load networkidle"), &flags).unwrap();
        assert_eq!(cmd["action"], "waitforloadstate");
        assert_eq!(cmd["timeout"], 4000);
    }

    #[test]
    fn test_wait_fn_inherits_default_timeout() {
        let flags = flags_with_default_timeout(4000);
        let cmd = parse_command(&args("wait --fn window.ready"), &flags).unwrap();
        assert_eq!(cmd["action"], "waitforfunction");
        assert_eq!(cmd["timeout"], 4000);
    }

    #[test]
    fn test_wait_text_inherits_default_timeout() {
        let flags = flags_with_default_timeout(2000);
        let cmd = parse_command(&args("wait --text Welcome"), &flags).unwrap();
        assert_eq!(cmd["action"], "wait");
        assert_eq!(cmd["text"], "Welcome");
        assert_eq!(cmd["timeout"], 2000);
    }

    #[test]
    fn test_wait_download_inherits_default_timeout() {
        let flags = flags_with_default_timeout(5000);
        let cmd = parse_command(&args("wait --download"), &flags).unwrap();
        assert_eq!(cmd["action"], "waitfordownload");
        assert_eq!(cmd["timeout"], 5000);
    }

    #[test]
    fn test_wait_explicit_timeout_overrides_default() {
        let flags = flags_with_default_timeout(5000);
        let cmd = parse_command(&args("wait --text Welcome --timeout 1000"), &flags).unwrap();
        assert_eq!(cmd["timeout"], 1000);
    }

    #[test]
    fn test_wait_no_default_timeout_omits_field() {
        let cmd = parse_command(&args("wait #element"), &default_flags()).unwrap();
        assert!(cmd.get("timeout").is_none());
    }

    // === Connect (CDP) tests ===

    #[test]
    fn test_connect_with_port() {
        let cmd = parse_command(&args("connect 9222"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "launch");
        assert_eq!(cmd["cdpPort"], 9222);
        assert!(cmd.get("cdpUrl").is_none());
    }

    #[test]
    fn test_connect_with_cdp_headers() {
        let mut flags = default_flags();
        flags.cdp_headers = Some(r#"{"Authorization":"Bearer t"}"#.to_string());
        let cmd = parse_command(&args("connect wss://example.com/cdp"), &flags).unwrap();
        assert_eq!(cmd["action"], "launch");
        assert_eq!(cmd["cdpUrl"], "wss://example.com/cdp");
        assert_eq!(cmd["cdpHeaders"]["Authorization"], "Bearer t");
    }

    #[test]
    fn test_connect_port_with_cdp_headers() {
        let mut flags = default_flags();
        flags.cdp_headers = Some(r#"{"Authorization":"Bearer t"}"#.to_string());
        let cmd = parse_command(&args("connect 9222"), &flags).unwrap();
        assert_eq!(cmd["cdpPort"], 9222);
        assert_eq!(cmd["cdpHeaders"]["Authorization"], "Bearer t");
    }

    #[test]
    fn test_parse_cdp_headers_rejects_invalid_shapes() {
        assert!(parse_cdp_headers(r#"{"Authorization":"Bearer t"}"#).is_ok());
        assert!(parse_cdp_headers("{bad").is_err());
        assert!(parse_cdp_headers(r#"["x"]"#).is_err());
        assert!(parse_cdp_headers(r#"{"Authorization":123}"#).is_err());
    }

    #[test]
    fn test_parse_cdp_headers_errors_never_echo_values() {
        for raw in [
            r#"{"Authorization":"Bearer SECRET",}"#,
            r#"{"Authorization":"Bearer SECRET","n":1}"#,
            r#"["Bearer SECRET"]"#,
        ] {
            let err = parse_cdp_headers(raw).unwrap_err();
            assert!(!err.contains("SECRET"), "{err}");
        }
    }

    #[test]
    fn test_connect_with_ws_url() {
        let input: Vec<String> = vec![
            "connect".to_string(),
            "ws://localhost:9222/devtools/browser/abc123".to_string(),
        ];
        let cmd = parse_command(&input, &default_flags()).unwrap();
        assert_eq!(cmd["action"], "launch");
        assert_eq!(cmd["cdpUrl"], "ws://localhost:9222/devtools/browser/abc123");
        assert!(cmd.get("cdpPort").is_none());
    }

    #[test]
    fn test_connect_with_wss_url() {
        let input: Vec<String> = vec![
            "connect".to_string(),
            "wss://remote-browser.example.com/cdp?token=xyz".to_string(),
        ];
        let cmd = parse_command(&input, &default_flags()).unwrap();
        assert_eq!(cmd["action"], "launch");
        assert_eq!(
            cmd["cdpUrl"],
            "wss://remote-browser.example.com/cdp?token=xyz"
        );
        assert!(cmd.get("cdpPort").is_none());
    }

    #[test]
    fn test_connect_with_http_url() {
        let input: Vec<String> = vec!["connect".to_string(), "http://localhost:9222".to_string()];
        let cmd = parse_command(&input, &default_flags()).unwrap();
        assert_eq!(cmd["action"], "launch");
        assert_eq!(cmd["cdpUrl"], "http://localhost:9222");
        assert!(cmd.get("cdpPort").is_none());
    }

    #[test]
    fn test_connect_missing_argument() {
        let result = parse_command(&args("connect"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_connect_invalid_port() {
        let result = parse_command(&args("connect notanumber"), &default_flags());
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ParseError::InvalidValue { .. }));
        assert!(err.format().contains("not a valid port number or URL"));
    }

    #[test]
    fn test_connect_port_zero() {
        let result = parse_command(&args("connect 0"), &default_flags());
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ParseError::InvalidValue { .. }));
        assert!(err.format().contains("port must be greater than 0"));
    }

    #[test]
    fn test_connect_port_out_of_range() {
        let result = parse_command(&args("connect 65536"), &default_flags());
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ParseError::InvalidValue { .. }));
        assert!(err.format().contains("out of range"));
        assert!(err.format().contains("1-65535"));
    }

    #[test]
    fn test_connect_port_max_valid() {
        let cmd = parse_command(&args("connect 65535"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "launch");
        assert_eq!(cmd["cdpPort"], 65535);
    }

    #[test]
    fn test_connect_port_min_valid() {
        let cmd = parse_command(&args("connect 1"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "launch");
        assert_eq!(cmd["cdpPort"], 1);
    }

    // === Runtime stream control tests ===

    #[test]
    fn test_stream_enable_auto_port() {
        let cmd = parse_command(&args("stream enable"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "stream_enable");
        assert!(cmd.get("port").is_none());
    }

    #[test]
    fn test_stream_enable_with_port() {
        let cmd = parse_command(&args("stream enable --port 9223"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "stream_enable");
        assert_eq!(cmd["port"], 9223);
    }

    #[test]
    fn test_stream_status() {
        let cmd = parse_command(&args("stream status"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "stream_status");
    }

    #[test]
    fn test_webmcp_commands() {
        let list = parse_command(&args("webmcp list"), &default_flags()).unwrap();
        assert_eq!(list["action"], "webmcp_list");

        let invoke = parse_command(
            &args(r#"webmcp invoke search --params {"query":"agents"} --frame frame-1 --detach --timeout 5000"#),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(invoke["action"], "webmcp_invoke");
        assert_eq!(invoke["tool"], "search");
        assert_eq!(invoke["params"]["query"], "agents");
        assert_eq!(invoke["frameId"], "frame-1");
        assert_eq!(invoke["detach"], true);
        assert_eq!(invoke["timeout"], 5000);

        let result = parse_command(
            &args("webmcp result invocation-1 --timeout 200"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(result["action"], "webmcp_result");
        assert_eq!(result["timeout"], 200);

        let cancel = parse_command(&args("webmcp cancel invocation-1"), &default_flags()).unwrap();
        assert_eq!(cancel["action"], "webmcp_cancel");
    }

    #[test]
    fn test_webmcp_rejects_malformed_params() {
        let result = parse_command(
            &args("webmcp invoke search --params not-json"),
            &default_flags(),
        );
        assert!(matches!(result, Err(ParseError::InvalidValue { .. })));
    }

    #[test]
    fn test_webmcp_reads_params_file() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("input.json");
        std::fs::write(&path, r#"{"from":"EZE","to":"LIM"}"#).unwrap();
        let command = parse_command(
            &[
                "webmcp".to_string(),
                "invoke".to_string(),
                "search_flights".to_string(),
                "--params".to_string(),
                format!("@{}", path.display()),
            ],
            &default_flags(),
        )
        .unwrap();
        assert_eq!(command["params"]["from"], "EZE");
        assert_eq!(command["params"]["to"], "LIM");
    }

    #[test]
    fn test_webmcp_rejects_non_object_params() {
        let result = parse_command(
            &args(r#"webmcp invoke search --params ["agents"]"#),
            &default_flags(),
        );
        assert!(matches!(result, Err(ParseError::InvalidValue { .. })));
    }

    #[test]
    fn test_webmcp_rejects_unexpected_arguments() {
        for command in [
            "webmcp list search extra",
            "webmcp list --frame",
            "webmcp result invocation-1 extra",
            "webmcp cancel invocation-1 extra",
        ] {
            assert!(
                matches!(
                    parse_command(&args(command), &default_flags()),
                    Err(ParseError::InvalidValue { .. })
                ),
                "{command} should reject trailing arguments"
            );
        }
    }

    #[test]
    fn test_stream_disable() {
        let cmd = parse_command(&args("stream disable"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "stream_disable");
    }

    #[test]
    fn test_stream_enable_invalid_port() {
        let result = parse_command(&args("stream enable --port abc"), &default_flags());
        assert!(matches!(result, Err(ParseError::InvalidValue { .. })));
    }

    #[test]
    fn test_stream_missing_subcommand() {
        let result = parse_command(&args("stream"), &default_flags());
        assert!(matches!(result, Err(ParseError::MissingArguments { .. })));
    }

    // === Trace Tests ===

    #[test]
    fn test_trace_start() {
        let cmd = parse_command(&args("trace start"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "trace_start");
    }

    #[test]
    fn test_trace_stop_with_path() {
        let cmd = parse_command(&args("trace stop ./trace.zip"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "trace_stop");
        assert_eq!(cmd["path"], "./trace.zip");
    }

    #[test]
    fn test_trace_stop_without_path() {
        let cmd = parse_command(&args("trace stop"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "trace_stop");
        assert!(cmd.get("path").is_none() || cmd["path"].is_null());
    }

    // === Diff Tests ===

    #[test]
    fn test_diff_snapshot_basic() {
        let cmd = parse_command(&args("diff snapshot"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "diff_snapshot");
    }

    #[test]
    fn test_diff_snapshot_baseline() {
        let cmd = parse_command(
            &args("diff snapshot --baseline before.txt"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_snapshot");
        assert_eq!(cmd["baseline"], "before.txt");
    }

    #[test]
    fn test_diff_snapshot_selector_compact_depth() {
        let cmd = parse_command(
            &args("diff snapshot --selector #main --compact --depth 3"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_snapshot");
        assert_eq!(cmd["selector"], "#main");
        assert_eq!(cmd["compact"], true);
        assert_eq!(cmd["maxDepth"], 3);
    }

    #[test]
    fn test_diff_snapshot_short_flags() {
        let cmd = parse_command(
            &args("diff snapshot -b snap.txt -s .content -c -d 2"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_snapshot");
        assert_eq!(cmd["baseline"], "snap.txt");
        assert_eq!(cmd["selector"], ".content");
        assert_eq!(cmd["compact"], true);
        assert_eq!(cmd["maxDepth"], 2);
    }

    #[test]
    fn test_diff_screenshot_baseline() {
        let cmd = parse_command(
            &args("diff screenshot --baseline before.png"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_screenshot");
        assert_eq!(cmd["baseline"], "before.png");
    }

    #[test]
    fn test_diff_screenshot_all_options() {
        let cmd = parse_command(
            &args("diff screenshot --baseline b.png --output d.png --threshold 0.2 --selector #hero --full"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_screenshot");
        assert_eq!(cmd["baseline"], "b.png");
        assert_eq!(cmd["output"], "d.png");
        assert_eq!(cmd["threshold"], 0.2);
        assert_eq!(cmd["selector"], "#hero");
        assert_eq!(cmd["fullPage"], true);
    }

    #[test]
    fn test_diff_screenshot_missing_baseline() {
        let result = parse_command(&args("diff screenshot"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_screenshot_command_full_flag() {
        let cmd = parse_command(
            &args("diff screenshot --baseline b.png --full"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_screenshot");
        assert_eq!(cmd["fullPage"], true);
    }

    #[test]
    fn test_diff_screenshot_command_full_flag_shorthand() {
        let cmd = parse_command(
            &args("diff screenshot --baseline b.png -f"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_screenshot");
        assert_eq!(cmd["fullPage"], true);
    }

    #[test]
    fn test_diff_url_basic() {
        let cmd = parse_command(
            &args("diff url https://a.com https://b.com"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_url");
        assert_eq!(cmd["url1"], "https://a.com");
        assert_eq!(cmd["url2"], "https://b.com");
    }

    #[test]
    fn test_diff_url_with_screenshot_full() {
        let cmd = parse_command(
            &args("diff url https://a.com https://b.com --screenshot --full"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_url");
        assert_eq!(cmd["screenshot"], true);
        assert_eq!(cmd["fullPage"], true);
    }

    #[test]
    fn test_diff_url_with_wait_until() {
        let cmd = parse_command(
            &args("diff url https://a.com https://b.com --wait-until networkidle"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_url");
        assert_eq!(cmd["waitUntil"], "networkidle");
    }

    #[test]
    fn test_diff_url_command_full_flag() {
        let cmd = parse_command(
            &args("diff url https://a.com https://b.com --full"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["fullPage"], true);
    }

    #[test]
    fn test_diff_missing_subcommand() {
        let result = parse_command(&args("diff"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_unknown_subcommand() {
        let result = parse_command(&args("diff invalid"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::UnknownSubcommand { .. }
        ));
    }

    #[test]
    fn test_diff_snapshot_baseline_missing_value() {
        let result = parse_command(&args("diff snapshot --baseline"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_snapshot_selector_missing_value() {
        let result = parse_command(&args("diff snapshot --selector"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_snapshot_depth_missing_value() {
        let result = parse_command(&args("diff snapshot --depth"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_screenshot_threshold_missing_value() {
        let result = parse_command(
            &args("diff screenshot --baseline b.png --threshold"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_screenshot_output_missing_value() {
        let result = parse_command(
            &args("diff screenshot --baseline b.png --output"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_url_wait_until_missing_value() {
        let result = parse_command(
            &args("diff url https://a.com https://b.com --wait-until"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_snapshot_unexpected_arg() {
        let result = parse_command(&args("diff snapshot foo"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_screenshot_unexpected_arg() {
        let result = parse_command(
            &args("diff screenshot --baseline b.png unexpected"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_url_unexpected_arg() {
        let result = parse_command(
            &args("diff url https://a.com https://b.com extra"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_snapshot_unknown_flag() {
        let result = parse_command(&args("diff snapshot --invalid"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_url_missing_urls() {
        let result = parse_command(&args("diff url"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_url_missing_second_url() {
        let result = parse_command(&args("diff url https://a.com"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    #[test]
    fn test_diff_snapshot_depth_invalid_value() {
        let result = parse_command(&args("diff snapshot --depth abc"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_screenshot_threshold_invalid_value() {
        let result = parse_command(
            &args("diff screenshot --baseline b.png --threshold abc"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_screenshot_threshold_out_of_range() {
        let result = parse_command(
            &args("diff screenshot --baseline b.png --threshold 1.5"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_screenshot_threshold_negative() {
        let result = parse_command(
            &args("diff screenshot --baseline b.png --threshold -0.5"),
            &default_flags(),
        );
        assert!(result.is_err());
    }

    #[test]
    fn test_diff_url_with_selector() {
        let cmd = parse_command(
            &args("diff url https://a.com https://b.com --selector #main"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_url");
        assert_eq!(cmd["selector"], "#main");
    }

    #[test]
    fn test_diff_url_with_compact_depth() {
        let cmd = parse_command(
            &args("diff url https://a.com https://b.com --compact --depth 3"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_url");
        assert_eq!(cmd["compact"], true);
        assert_eq!(cmd["maxDepth"], 3);
    }

    #[test]
    fn test_diff_url_with_short_snapshot_flags() {
        let cmd = parse_command(
            &args("diff url https://a.com https://b.com -s .content -c -d 2"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "diff_url");
        assert_eq!(cmd["selector"], ".content");
        assert_eq!(cmd["compact"], true);
        assert_eq!(cmd["maxDepth"], 2);
    }

    #[test]
    fn test_diff_url_depth_invalid_value() {
        let result = parse_command(
            &args("diff url https://a.com https://b.com --depth abc"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_snapshot_depth_negative_value() {
        let result = parse_command(&args("diff snapshot --depth -1"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_url_depth_negative_value() {
        let result = parse_command(
            &args("diff url https://a.com https://b.com --depth -1"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::InvalidValue { .. }
        ));
    }

    #[test]
    fn test_diff_url_selector_missing_value() {
        let result = parse_command(
            &args("diff url https://a.com https://b.com --selector"),
            &default_flags(),
        );
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    // === Scroll Tests ===

    #[test]
    fn test_scroll_defaults() {
        let cmd = parse_command(&args("scroll"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "scroll");
        assert_eq!(cmd["direction"], "down");
        assert_eq!(cmd["amount"], 300);
        assert!(cmd.get("selector").is_none());
    }

    #[test]
    fn test_scroll_direction_and_amount() {
        let cmd = parse_command(&args("scroll up 200"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "scroll");
        assert_eq!(cmd["direction"], "up");
        assert_eq!(cmd["amount"], 200);
    }

    #[test]
    fn test_scroll_with_selector() {
        let cmd = parse_command(
            &args("scroll down 500 --selector div.scroll-container"),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "scroll");
        assert_eq!(cmd["direction"], "down");
        assert_eq!(cmd["amount"], 500);
        assert_eq!(cmd["selector"], "div.scroll-container");
    }

    #[test]
    fn test_scroll_with_selector_short_flag() {
        let cmd = parse_command(&args("scroll left 100 -s .sidebar"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "scroll");
        assert_eq!(cmd["direction"], "left");
        assert_eq!(cmd["amount"], 100);
        assert_eq!(cmd["selector"], ".sidebar");
    }

    #[test]
    fn test_scroll_selector_before_positional() {
        let cmd =
            parse_command(&args("scroll --selector .panel down 400"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "scroll");
        assert_eq!(cmd["direction"], "down");
        assert_eq!(cmd["amount"], 400);
        assert_eq!(cmd["selector"], ".panel");
    }

    #[test]
    fn test_scroll_selector_only() {
        let cmd = parse_command(&args("scroll --selector .content"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "scroll");
        assert_eq!(cmd["direction"], "down");
        assert_eq!(cmd["amount"], 300);
        assert_eq!(cmd["selector"], ".content");
    }

    #[test]
    fn test_scroll_selector_missing_value() {
        let result = parse_command(&args("scroll down 500 --selector"), &default_flags());
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ParseError::MissingArguments { .. }
        ));
    }

    // === Inspect / CDP URL ===

    #[test]
    fn test_inspect() {
        let cmd = parse_command(&args("inspect"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "inspect");
    }

    #[test]
    fn test_get_cdp_url() {
        let cmd = parse_command(&args("get cdp-url"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "cdp_url");
    }

    // === Batch Tests ===

    #[test]
    fn test_batch_default() {
        let cmd = parse_command(&args("batch"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "batch");
        assert_eq!(cmd["bail"], false);
    }

    #[test]
    fn test_batch_with_bail() {
        let cmd = parse_command(&args("batch --bail"), &default_flags()).unwrap();
        assert_eq!(cmd["action"], "batch");
        assert_eq!(cmd["bail"], true);
    }

    #[test]
    fn test_batch_with_args() {
        let cmd_args = vec![
            "batch".to_string(),
            "open https://example.com".to_string(),
            "screenshot".to_string(),
        ];
        let cmd = parse_command(&cmd_args, &default_flags()).unwrap();
        assert_eq!(cmd["action"], "batch");
        assert_eq!(cmd["bail"], false);
        let commands = cmd["commands"].as_array().unwrap();
        assert_eq!(commands.len(), 2);
        assert_eq!(commands[0], "open https://example.com");
        assert_eq!(commands[1], "screenshot");
    }

    #[test]
    fn test_batch_with_args_and_bail() {
        let cmd_args = vec![
            "batch".to_string(),
            "--bail".to_string(),
            "open https://example.com".to_string(),
            "screenshot".to_string(),
        ];
        let cmd = parse_command(&cmd_args, &default_flags()).unwrap();
        assert_eq!(cmd["action"], "batch");
        assert_eq!(cmd["bail"], true);
        let commands = cmd["commands"].as_array().unwrap();
        assert_eq!(commands.len(), 2);
    }

    #[test]
    fn test_batch_no_args_no_commands_field() {
        let cmd = parse_command(&args("batch"), &default_flags()).unwrap();
        assert!(cmd.get("commands").is_none());
    }

    #[test]
    fn test_auth_login_credential_provider_flags() {
        let cmd = parse_command(
            &args(
                "auth login github --credential-provider onepassword --item GitHub --url https://github.com/login --username-selector #login_field --password-selector #password --submit-selector input[type=submit]",
            ),
            &default_flags(),
        )
        .unwrap();
        assert_eq!(cmd["action"], "auth_login");
        assert_eq!(cmd["name"], "github");
        assert_eq!(cmd["credentialProvider"], "onepassword");
        assert_eq!(cmd["credentialItem"], "GitHub");
        assert_eq!(cmd["url"], "https://github.com/login");
        assert_eq!(cmd["usernameSelector"], "#login_field");
        assert_eq!(cmd["passwordSelector"], "#password");
        assert_eq!(cmd["submitSelector"], "input[type=submit]");
        assert!(cmd.get("noNavigate").is_none());
    }

    #[test]
    fn test_auth_login_no_navigate() {
        let cmd =
            parse_command(&args("auth login github --no-navigate"), &default_flags()).unwrap();

        assert_eq!(cmd["action"], "auth_login");
        assert_eq!(cmd["name"], "github");
        assert_eq!(cmd["noNavigate"], true);
        assert!(cmd.get("url").is_none());
    }

    #[test]
    fn test_auth_login_no_navigate_with_url() {
        let cmd = parse_command(
            &args("auth login github --no-navigate --url https://github.com/login"),
            &default_flags(),
        )
        .unwrap();

        assert_eq!(cmd["action"], "auth_login");
        assert_eq!(cmd["name"], "github");
        assert_eq!(cmd["noNavigate"], true);
        assert_eq!(cmd["url"], "https://github.com/login");
    }

    #[test]
    fn test_auth_login_no_navigate_combines_with_provider_and_selectors() {
        let cmd = parse_command(
            &args(
                "auth login work --credential-provider vault --item Work --no-navigate --username-selector #email --password-selector #pass --submit-selector #submit",
            ),
            &default_flags(),
        )
        .unwrap();

        assert_eq!(cmd["credentialProvider"], "vault");
        assert_eq!(cmd["credentialItem"], "Work");
        assert_eq!(cmd["noNavigate"], true);
        assert_eq!(cmd["usernameSelector"], "#email");
        assert_eq!(cmd["passwordSelector"], "#pass");
        assert_eq!(cmd["submitSelector"], "#submit");
    }

    #[test]
    fn test_auth_login_no_navigate_rejects_value() {
        let err = parse_command(
            &args("auth login github --no-navigate true"),
            &default_flags(),
        )
        .unwrap_err();

        assert!(matches!(err, ParseError::InvalidValue { .. }));
    }

    #[test]
    fn test_auth_login_credential_provider_requires_value() {
        let err = parse_command(
            &args("auth login github --credential-provider"),
            &default_flags(),
        )
        .unwrap_err();

        assert!(matches!(err, ParseError::MissingArguments { .. }));
    }

    #[test]
    fn test_auth_login_item_does_not_consume_next_flag_as_value() {
        let err = parse_command(
            &args("auth login github --credential-provider vault --item --url https://github.com/login"),
            &default_flags(),
        )
        .unwrap_err();

        assert!(matches!(err, ParseError::MissingArguments { .. }));
    }
}