cdpilot 0.2.0 → 0.3.0

package/README.md

@@ -282,22 +282,40 @@ Found a vulnerability? Please email the maintainer directly instead of opening a
 
 ## Roadmap
 
-We're building cdpilot into the lightweight alternative to Playwright MCP for AI agents. Here's what's coming:
-
-- [x] 40+ CLI commands (navigate, click, fill, screenshot, PDF, console, network...)
-- [x] MCP server for AI agent integration (Claude Code, etc.)
-- [x] Visual feedback system (green glow, cursor visualization, click ripples, keystroke display)
-- [x] AI control warning toast (appears when user tries to interact during automation)
-- [x] Multi-project browser isolation (each project gets its own port + profile automatically)
+The only browser MCP with built-in test assertions. Here's what we've shipped and what's next:
+
+### Shipped
+
+- [x] 60+ CLI commands (navigate, click, fill, screenshot, PDF, console, network...)
+- [x] MCP server for AI agent integration (Claude Code, Cursor, etc.)
+- [x] **10 built-in test assertions** — assert, assert-url, assert-title, assert-count, assert-value, assert-attr, assert-visible/hidden, wait-for, check (batch), screenshot-diff
+- [x] **Accessibility tree snapshot** (`a11y-snapshot`) — structured data with @ref references, 500x fewer tokens than screenshots
+- [x] **Token-efficient screenshots** — element-level crop (13x smaller), JPEG quality control, format selection
+- [x] **Vision fallback** (`describe`) — a11y + screenshot + text in one call
+- [x] **Annotated screenshots** — @N badge overlays on interactive elements
+- [x] **Auto-wait** — MutationObserver-based, 5s automatic element waiting
+- [x] **Batch commands** — pipe JSON arrays via stdin for multi-step automation
+- [x] Visual feedback system (persistent green glow, cursor, ripples, keystroke display)
+- [x] AI control warning toast (red warning when user interacts during automation)
+- [x] Multi-project browser isolation (each project gets its own port + profile)
+- [x] Pre-flight wizard (auto-installs dependencies on first run)
+- [x] Persistent MCP glow (stays on during entire AI session, like Claude's orange glow)
 - [x] DevExtension system (native JS injection without browser store)
-- [ ] **Accessibility tree snapshot** — structured a11y data for AI agents (like Playwright MCP but 4x lighter)
-- [ ] **Annotated screenshots** — element references (@e1, @e2) overlaid on screenshots for precise AI clicking
-- [ ] **Auto-wait** — automatically wait for elements before interaction (reduce flakiness)
-- [ ] **Batch commands** — pipe JSON arrays via stdin for multi-step automation in one call
+- [x] **Smart commands** — `smart-click`, `smart-fill`, `smart-select` — interact by visible text, no CSS selectors needed, no LLM required
+- [x] **Data extraction** (`extract`) — structured DOM data in text, JSON, or list format
+- [x] **Page observation** (`observe`) — list all interactive elements with available actions
+- [x] **Script runner** (`run`) — execute `.cdp` script files with pass/fail reporting
+
+### Coming Soon
+
 - [ ] **iframe & Shadow DOM** support — interact with elements inside iframes and shadow roots
-- [ ] **Claude Code Skill mode** — run as a `.claude/skills/` skill in addition to MCP
 - [ ] **Session recording & replay** — record browser sessions and replay them deterministically
-- [ ] **Stealth mode** — anti-detection flags for web scraping scenarios
+- [ ] **Stealth mode** *(Pro)* — human-like mouse/typing, anti-fingerprint, CAPTCHA solving
+- [ ] **cdpilot Cloud** — hosted browser sessions API, REST + WebSocket MCP endpoint
+- [ ] **Chrome Extension** — use cdpilot from any browser without CLI
+- [ ] **Performance audit** — Core Web Vitals (LCP, CLS, INP) via CDP Performance domain
+- [ ] **WCAG accessibility audit** — automated a11y compliance reporting
+- [ ] **Claude Code Skill mode** — run as a `.claude/skills/` skill in addition to MCP
 
 Have an idea? [Open an issue](https://github.com/mehmetnadir/cdpilot/issues) or submit a PR!
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdpilot",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Zero-dependency browser automation from your terminal. One command, full control.",
   "bin": {
     "cdpilot": "./bin/cdpilot.js",

package/src/cdpilot.py

@@ -39,6 +39,7 @@ CDPILOT_HOME = os.path.expanduser("~/.cdpilot")
 REGISTRY_FILE = os.path.join(CDPILOT_HOME, "registry.json")
 CDPILOT_PORT_RANGE_START = 9222
 CDPILOT_PORT_RANGE_END = 9322
+IS_MCP_SESSION = os.environ.get("CDPILOT_MCP_SESSION") == "1"
 
 
 def _get_project_id():
@@ -565,10 +566,11 @@ async def _control_start(ws_url):
         pass
 
 async def _control_end(ws_url):
-    """Remove input blocker, set glow/vfx auto-timeout (10s).
+    """Remove input blocker, keep glow alive.
 
-    Persistent script stays active so glow survives page navigations.
-    It gets cleaned up by the 10s timeout in GLOW_TIMEOUT_JS.
+    In MCP session mode (CDPILOT_MCP_SESSION=1): glow stays permanently,
+    no timeout — mimics Claude's persistent orange glow behavior.
+    In CLI mode: glow fades after 10s idle (GLOW_TIMEOUT_JS).
     """
     global _glow_script_id
     try:
@@ -577,11 +579,12 @@ async def _control_end(ws_url):
             # Re-inject glow+vfx on current page (may be new after navigation)
             (906, "Runtime.evaluate", {"expression": GLOW_CSS, "returnByValue": True}),
             (907, "Runtime.evaluate", {"expression": VISUAL_FEEDBACK_JS, "returnByValue": True}),
-            # Then start the 10s auto-cleanup timeout
-            (904, "Runtime.evaluate", {"expression": GLOW_TIMEOUT_JS, "returnByValue": True}),
         ]
-        # Don't remove persistent script here — it auto-cleans via GLOW_TIMEOUT_JS.
-        # Next _control_start will replace it with a fresh one anyway.
+        if not IS_MCP_SESSION:
+            # CLI mode: start 10s auto-cleanup timeout
+            cmds.append((904, "Runtime.evaluate", {"expression": GLOW_TIMEOUT_JS, "returnByValue": True}))
+        # Don't remove persistent script — it auto-cleans via GLOW_TIMEOUT_JS (CLI)
+        # or stays forever (MCP session).
         _glow_script_id = None
         await cdp_send(ws_url, cmds)
     except Exception:
@@ -828,12 +831,12 @@ async def cdp_send(ws_url, commands, timeout=15):
                     continue
         return results
     except ConnectionRefusedError:
-        print(f'Browser is not running. Run \'cdpilot launch\' first.', file=sys.stderr)
+        print("Browser is not running. Run 'cdpilot launch' first.", file=sys.stderr)
         sys.exit(1)
     except Exception as e:
         err = str(e)
         if "websocket" in err.lower() or "connect" in err.lower() or "ws://" in err.lower():
-            print(f'Browser is not running or CDP port {CDP_PORT} is unreachable. Run \'cdpilot launch\' first.', file=sys.stderr)
+            print(f"Browser is not running or CDP port {CDP_PORT} is unreachable. Run 'cdpilot launch' first.", file=sys.stderr)
             sys.exit(1)
         raise
 
@@ -1338,16 +1341,62 @@ async def cmd_html():
         print("[Output truncated at 1MB]")
 
 
-async def cmd_shot(output=None):
+async def cmd_shot(output=None, quality=None, element=None, fmt=None):
+    """Take screenshot. Supports --quality, --element, --format for token savings.
+
+    Args:
+        output: File path (auto-detects format from extension)
+        quality: JPEG quality 1-100 (only for jpeg format, saves ~5-7x tokens)
+        element: CSS selector to capture only that element (crop)
+        fmt: Force format: 'png', 'jpeg', or 'webp'
+    """
     if not output:
         output = f"{SCREENSHOT_DIR}/screenshot.png"
     ws, _ = get_page_ws()
-    r = await cdp_send(ws, [(1, "Page.captureScreenshot", {"format": "png", "captureBeyondViewport": True})])
-    b64 = r.get(1, {}).get("data", "")
+
+    # Auto-detect format from extension
+    if fmt is None:
+        ext = os.path.splitext(output)[1].lower()
+        fmt = {"jpg": "jpeg", ".jpg": "jpeg", ".jpeg": "jpeg", ".webp": "webp"}.get(ext, "png")
+
+    params = {"format": fmt}
+    if fmt == "jpeg" and quality:
+        params["quality"] = max(1, min(100, int(quality)))
+    elif fmt == "jpeg" and quality is None:
+        params["quality"] = 80  # sensible default
+
+    # Element-level crop: get bounding rect, use clip
+    if element:
+        safe_sel = json.dumps(element)
+        js = f"""
+        (function() {{
+          var el = document.querySelector({safe_sel});
+          if (!el) return null;
+          el.scrollIntoView({{block: 'center'}});
+          var r = el.getBoundingClientRect();
+          return JSON.stringify({{x: r.x, y: r.y, width: r.width, height: r.height}});
+        }})()
+        """
+        cr = await cdp_send(ws, [(2, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+        rect_str = cr.get(2, {}).get("result", {}).get("value")
+        if rect_str:
+            rect = json.loads(rect_str)
+            params["clip"] = {
+                "x": rect["x"], "y": rect["y"],
+                "width": rect["width"], "height": rect["height"],
+                "scale": 1
+            }
+        else:
+            print(f"Element not found: {element}, taking full page", file=sys.stderr)
+
+    r = await cdp_send(ws, [(1, "Page.captureScreenshot", params)])
+    b64 = r.get(1, {}).get("result", {}).get("data", "") or r.get(1, {}).get("data", "")
     if b64:
+        data = base64.b64decode(b64)
         with open(output, "wb") as f:
-            f.write(base64.b64decode(b64))
-        print(f"{output}")
+            f.write(data)
+        size_kb = len(data) / 1024
+        print(f"{output} ({size_kb:.1f}KB)")
     else:
         print("Screenshot failed", file=sys.stderr)
 
@@ -2042,7 +2091,8 @@ def cmd_ext_remove(ext_id):
 async def cmd_new_tab(url='about:blank'):
     """Open a new tab."""
     import urllib.parse
-    data = cdp_get(f'/json/new?{urllib.parse.quote(url, safe=":/?#[]@!$&\'()*+,;=")}')
+    safe_chars = ":/?#[]@!$&'()*+,;="
+    data = cdp_get(f'/json/new?{urllib.parse.quote(url, safe=safe_chars)}')
     if data:
         print(f'New tab opened: {data.get("url", url)}')
         print(f'  ID: {data.get("id", "?")}')
@@ -2778,6 +2828,751 @@ async def cmd_describe():
     print(page_text[:2000])
 
 
+# ─── Data Extraction & Observation Commands ───
+
+async def cmd_extract(selector, output_format="text"):
+    """Extract structured data from elements matching selector.
+
+    Returns text content, attributes, or full JSON structure.
+    No LLM required — pure DOM extraction.
+
+    Usage:
+        cdpilot extract "table tr"              → text rows
+        cdpilot extract ".product" --json        → full JSON (tag, text, attrs, children)
+        cdpilot extract "a" --attrs=href,title   → specific attributes
+        cdpilot extract "ul li" --list           → clean list output
+    """
+    ws_url, _ = get_page_ws()
+    safe_sel = json.dumps(selector)
+
+    if output_format == "json":
+        js = f"""
+        (function() {{
+          var els = document.querySelectorAll({safe_sel});
+          if (!els.length) return JSON.stringify([]);
+          return JSON.stringify(Array.from(els).slice(0, 100).map(function(el) {{
+            var attrs = {{}};
+            for (var i = 0; i < el.attributes.length; i++) {{
+              attrs[el.attributes[i].name] = el.attributes[i].value;
+            }}
+            return {{
+              tag: el.tagName.toLowerCase(),
+              text: (el.textContent || '').trim().substring(0, 500),
+              attrs: attrs,
+              value: el.value || null,
+              href: el.href || null,
+              src: el.src || null
+            }};
+          }}));
+        }})()
+        """
+    elif output_format.startswith("attrs="):
+        attr_names = output_format.split("=", 1)[1].split(",")
+        attrs_js = ",".join(f'"{a}": el.getAttribute("{a}")' for a in attr_names)
+        js = f"""
+        (function() {{
+          var els = document.querySelectorAll({safe_sel});
+          if (!els.length) return JSON.stringify([]);
+          return JSON.stringify(Array.from(els).slice(0, 100).map(function(el) {{
+            return {{ {attrs_js} }};
+          }}));
+        }})()
+        """
+    elif output_format == "list":
+        js = f"""
+        (function() {{
+          var els = document.querySelectorAll({safe_sel});
+          if (!els.length) return '';
+          return Array.from(els).slice(0, 200).map(function(el, i) {{
+            return (i + 1) + '. ' + (el.textContent || '').trim().substring(0, 200);
+          }}).join('\\n');
+        }})()
+        """
+    else:
+        # Default: text content, one per line
+        js = f"""
+        (function() {{
+          var els = document.querySelectorAll({safe_sel});
+          if (!els.length) return '';
+          return Array.from(els).slice(0, 200).map(function(el) {{
+            return (el.textContent || '').trim().substring(0, 300);
+          }}).filter(function(t) {{ return t; }}).join('\\n');
+        }})()
+        """
+
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    result = r.get(1, {}).get("result", {}).get("value", "")
+    if not result:
+        print(f"No elements found: {selector}", file=sys.stderr)
+        return
+    if output_format in ("json",) or output_format.startswith("attrs="):
+        # Pretty print JSON
+        try:
+            parsed = json.loads(result)
+            print(json.dumps(parsed, indent=2, ensure_ascii=False))
+        except (json.JSONDecodeError, TypeError):
+            print(result)
+    else:
+        print(result)
+
+
+async def cmd_observe():
+    """List all interactive elements on the page with actions.
+
+    Like Stagehand's observe() but deterministic — no LLM needed.
+    Shows what you CAN DO on the current page.
+    """
+    ws_url, _ = get_page_ws()
+    js = """
+    (function() {
+      var results = [];
+      var els = document.querySelectorAll(
+        'a, button, input, textarea, select, [role=button], [role=link], ' +
+        '[role=tab], [role=menuitem], [role=checkbox], [role=radio], ' +
+        '[onclick], [tabindex]:not([tabindex="-1"])'
+      );
+      var seen = new Set();
+      Array.from(els).forEach(function(el, i) {
+        if (i >= 50) return;
+        var rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return;
+        var style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden') return;
+
+        var tag = el.tagName.toLowerCase();
+        var type = el.type || '';
+        var role = el.getAttribute('role') || '';
+        var text = (el.textContent || el.value || el.placeholder || '').trim().substring(0, 60);
+        var href = el.href || '';
+        var name = el.name || el.id || '';
+
+        // Determine action
+        var action = 'click';
+        if (tag === 'input' || tag === 'textarea') {
+          if (type === 'checkbox' || type === 'radio') action = 'toggle';
+          else if (type === 'submit') action = 'submit';
+          else if (type === 'file') action = 'upload';
+          else action = 'fill';
+        } else if (tag === 'select') {
+          action = 'select';
+        } else if (tag === 'a') {
+          action = 'navigate';
+        }
+
+        // Build selector
+        var sel = '';
+        if (el.id) sel = '#' + el.id;
+        else if (name) sel = tag + '[name=' + JSON.stringify(name) + ']';
+        else if (type) sel = tag + '[type=' + type + ']';
+        else sel = tag;
+
+        var key = action + ':' + sel + ':' + text;
+        if (seen.has(key)) return;
+        seen.add(key);
+
+        var line = action.toUpperCase() + '  ' + sel;
+        if (text) line += '  "' + text + '"';
+        if (href && action === 'navigate') line += '  → ' + href.substring(0, 80);
+        results.push(line);
+      });
+      return results.join('\\n') || 'No interactive elements found';
+    })()
+    """
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    result = r.get(1, {}).get("result", {}).get("value", "No interactive elements found")
+    print(f"=== What you can do on this page ===\n")
+    print(result)
+
+
+# ─── Smart Commands (LLM-free intelligence) ───
+
+async def cmd_smart_click(text):
+    """Click element by visible text — fuzzy matching, no CSS selector needed.
+
+    Like Stagehand's act("Click login") but without LLM.
+    Searches: button text, link text, aria-label, placeholder, title, value.
+
+    Usage:
+        cdpilot smart-click "Login"
+        cdpilot smart-click "Submit Order"
+        cdpilot smart-click "Learn more"
+    """
+    ws_url, _ = get_page_ws()
+    safe_text = json.dumps(text.lower())
+    js = f"""
+    (function() {{
+      var search = {safe_text};
+      var candidates = [];
+
+      // Score: exact > startsWith > includes > partial
+      function score(str) {{
+        if (!str) return 0;
+        var s = str.toLowerCase().trim();
+        if (s === search) return 100;
+        if (s.startsWith(search)) return 80;
+        if (s.includes(search)) return 60;
+        // Partial word match
+        var words = search.split(/\\s+/);
+        var matched = words.filter(function(w) {{ return s.includes(w); }}).length;
+        if (matched > 0) return 20 + (matched / words.length) * 30;
+        return 0;
+      }}
+
+      var els = document.querySelectorAll(
+        'a, button, input[type=submit], input[type=button], ' +
+        '[role=button], [role=link], [role=tab], [role=menuitem], ' +
+        'summary, label, [onclick], [tabindex]'
+      );
+
+      Array.from(els).forEach(function(el) {{
+        var rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return;
+        var style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden') return;
+
+        var texts = [
+          el.textContent || '',
+          el.getAttribute('aria-label') || '',
+          el.getAttribute('title') || '',
+          el.getAttribute('placeholder') || '',
+          el.value || '',
+          el.getAttribute('alt') || ''
+        ];
+
+        var bestScore = 0;
+        var bestMatch = '';
+        texts.forEach(function(t) {{
+          var s = score(t);
+          if (s > bestScore) {{ bestScore = s; bestMatch = t.trim().substring(0, 60); }}
+        }});
+
+        if (bestScore > 0) {{
+          candidates.push({{
+            el: el,
+            score: bestScore,
+            match: bestMatch,
+            tag: el.tagName.toLowerCase(),
+            cx: rect.x + rect.width / 2,
+            cy: rect.y + rect.height / 2
+          }});
+        }}
+      }});
+
+      if (candidates.length === 0) return JSON.stringify({{found: false}});
+
+      candidates.sort(function(a, b) {{ return b.score - a.score; }});
+      var best = candidates[0];
+      best.el.scrollIntoView({{block: 'center'}});
+      var rect = best.el.getBoundingClientRect();
+      best.el.click();
+      return JSON.stringify({{
+        found: true,
+        tag: best.tag,
+        text: best.match,
+        score: best.score,
+        x: rect.x + rect.width / 2,
+        y: rect.y + rect.height / 2,
+        alternatives: candidates.slice(1, 4).map(function(c) {{
+          return c.tag + ' "' + c.match + '" (score:' + c.score + ')';
+        }})
+      }});
+    }})()
+    """
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    raw = r.get(1, {}).get("result", {}).get("value", "")
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        print(f"Error parsing result", file=sys.stderr)
+        return
+
+    if not data.get("found"):
+        print(f'No element found matching: "{text}"', file=sys.stderr)
+        sys.exit(1)
+
+    await _vfx_ripple(ws_url, data["x"], data["y"])
+    print(f'Clicked: {data["tag"].upper()} "{data["text"]}" (score:{data["score"]})')
+    if data.get("alternatives"):
+        print(f'  Also found: {", ".join(data["alternatives"])}')
+
+
+async def cmd_smart_fill(text, value):
+    """Fill input by label/placeholder text — no CSS selector needed.
+
+    Finds input by: associated label, placeholder, aria-label, name, id match.
+
+    Usage:
+        cdpilot smart-fill "Email" "test@example.com"
+        cdpilot smart-fill "Password" "secret123"
+        cdpilot smart-fill "Search" "cdpilot"
+    """
+    ws_url, _ = get_page_ws()
+    safe_text = json.dumps(text.lower())
+    safe_value = json.dumps(value)
+    js = f"""
+    (function() {{
+      var search = {safe_text};
+      var value = {safe_value};
+      var candidates = [];
+
+      function score(str) {{
+        if (!str) return 0;
+        var s = str.toLowerCase().trim();
+        if (s === search) return 100;
+        if (s.startsWith(search)) return 80;
+        if (s.includes(search)) return 60;
+        return 0;
+      }}
+
+      var inputs = document.querySelectorAll('input, textarea, select, [contenteditable=true]');
+      Array.from(inputs).forEach(function(el) {{
+        var rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return;
+
+        var scores = [];
+        // Check placeholder
+        scores.push(score(el.getAttribute('placeholder') || ''));
+        // Check aria-label
+        scores.push(score(el.getAttribute('aria-label') || ''));
+        // Check name/id
+        scores.push(score(el.name || ''));
+        scores.push(score(el.id || ''));
+        // Check associated label
+        if (el.id) {{
+          var label = document.querySelector('label[for="' + el.id + '"]');
+          if (label) scores.push(score(label.textContent || ''));
+        }}
+        // Check parent label
+        var parentLabel = el.closest('label');
+        if (parentLabel) scores.push(score(parentLabel.textContent || ''));
+        // Check preceding text node/label
+        var prev = el.previousElementSibling;
+        if (prev) scores.push(score(prev.textContent || ''));
+
+        var bestScore = Math.max.apply(null, scores);
+        if (bestScore > 0) {{
+          candidates.push({{el: el, score: bestScore, tag: el.tagName.toLowerCase(), type: el.type || ''}});
+        }}
+      }});
+
+      if (candidates.length === 0) return JSON.stringify({{found: false}});
+
+      candidates.sort(function(a, b) {{ return b.score - a.score; }});
+      var best = candidates[0];
+
+      // React-compatible value setting
+      var nativeSetter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype, 'value'
+      ) || Object.getOwnPropertyDescriptor(
+        window.HTMLTextAreaElement.prototype, 'value'
+      );
+      if (nativeSetter && nativeSetter.set) {{
+        nativeSetter.set.call(best.el, value);
+      }} else {{
+        best.el.value = value;
+      }}
+      best.el.dispatchEvent(new Event('input', {{bubbles: true}}));
+      best.el.dispatchEvent(new Event('change', {{bubbles: true}}));
+
+      return JSON.stringify({{
+        found: true,
+        tag: best.tag,
+        type: best.type,
+        score: best.score,
+        placeholder: best.el.getAttribute('placeholder') || '',
+        name: best.el.name || best.el.id || ''
+      }});
+    }})()
+    """
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    raw = r.get(1, {}).get("result", {}).get("value", "")
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        print(f"Error parsing result", file=sys.stderr)
+        return
+
+    if not data.get("found"):
+        print(f'No input found matching: "{text}"', file=sys.stderr)
+        sys.exit(1)
+
+    ident = data.get("placeholder") or data.get("name") or data["tag"]
+    print(f'Filled: {data["tag"].upper()}[{data["type"]}] "{ident}" = {value} (score:{data["score"]})')
+
+
+async def cmd_smart_select(text, option_text):
+    """Select dropdown option by label text — no CSS selector needed.
+
+    Usage:
+        cdpilot smart-select "Country" "Turkey"
+        cdpilot smart-select "Size" "Large"
+    """
+    ws_url, _ = get_page_ws()
+    safe_text = json.dumps(text.lower())
+    safe_option = json.dumps(option_text.lower())
+    js = f"""
+    (function() {{
+      var search = {safe_text};
+      var optSearch = {safe_option};
+      var selects = document.querySelectorAll('select');
+      var best = null;
+      var bestScore = 0;
+
+      Array.from(selects).forEach(function(sel) {{
+        var texts = [
+          sel.getAttribute('aria-label') || '',
+          sel.name || '', sel.id || ''
+        ];
+        if (sel.id) {{
+          var label = document.querySelector('label[for="' + sel.id + '"]');
+          if (label) texts.push(label.textContent || '');
+        }}
+        var parent = sel.closest('label');
+        if (parent) texts.push(parent.textContent || '');
+
+        texts.forEach(function(t) {{
+          var s = t.toLowerCase().trim();
+          var sc = s === search ? 100 : s.includes(search) ? 60 : 0;
+          if (sc > bestScore) {{ bestScore = sc; best = sel; }}
+        }});
+      }});
+
+      if (!best) return JSON.stringify({{found: false}});
+
+      // Find matching option
+      var options = Array.from(best.options);
+      var match = options.find(function(o) {{
+        return o.text.toLowerCase().trim() === optSearch;
+      }}) || options.find(function(o) {{
+        return o.text.toLowerCase().includes(optSearch);
+      }});
+
+      if (!match) return JSON.stringify({{found: true, optionFound: false, available: options.map(function(o) {{ return o.text; }}).slice(0, 10)}});
+
+      best.value = match.value;
+      best.dispatchEvent(new Event('change', {{bubbles: true}}));
+      return JSON.stringify({{found: true, optionFound: true, selected: match.text, value: match.value}});
+    }})()
+    """
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    raw = r.get(1, {}).get("result", {}).get("value", "")
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        print("Error parsing result", file=sys.stderr)
+        return
+
+    if not data.get("found"):
+        print(f'No select found matching: "{text}"', file=sys.stderr)
+        sys.exit(1)
+    if not data.get("optionFound"):
+        print(f'Option "{option_text}" not found. Available: {", ".join(data.get("available", []))}', file=sys.stderr)
+        sys.exit(1)
+    print(f'Selected: "{data["selected"]}" (value={data["value"]})')
+
+
+async def cmd_run_script(script_path):
+    """Run a .cdp script file — sequential commands, one per line.
+
+    Script format (plain text):
+        go https://example.com
+        wait-for h1
+        assert h1 "Example Domain"
+        click a
+        shot /tmp/result.png
+
+    Lines starting with # are comments. Empty lines are skipped.
+    """
+    if not os.path.exists(script_path):
+        print(f"Script not found: {script_path}", file=sys.stderr)
+        sys.exit(1)
+
+    with open(script_path) as f:
+        lines = f.readlines()
+
+    import shlex
+    passed = 0
+    failed = 0
+    for line_num, line in enumerate(lines, 1):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        try:
+            parts = shlex.split(line)
+        except ValueError:
+            parts = line.split()
+        cmd_name = parts[0]
+        cmd_args = parts[1:]
+
+        print(f"[{line_num}] {line}")
+        try:
+            result = subprocess.run(
+                [sys.executable, __file__] + parts,
+                capture_output=True, text=True, timeout=30,
+                env={**os.environ, "CDPILOT_MCP_SESSION": "1"}
+            )
+            output = result.stdout.strip()
+            if output:
+                for out_line in output.split("\n"):
+                    print(f"     {out_line}")
+            if result.returncode != 0:
+                err = result.stderr.strip()
+                if err:
+                    print(f"     ERROR: {err}")
+                failed += 1
+            else:
+                passed += 1
+        except subprocess.TimeoutExpired:
+            print(f"     TIMEOUT")
+            failed += 1
+
+    print(f"\n{'─' * 40}")
+    print(f"Script: {script_path}")
+    print(f"Result: {passed} passed, {failed} failed, {passed + failed} total")
+
+
+# ─── Testing Commands ───
+
+async def cmd_assert(selector, expected_text=None, check_visible=True):
+    """Assert element exists, optionally check text content and visibility."""
+    ws_url, _ = get_page_ws()
+    visible_check = ""
+    if check_visible:
+        visible_check = """
+        var rect = el.getBoundingClientRect();
+        var style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden' ||
+            style.opacity === '0' || (rect.width === 0 && rect.height === 0)) {
+          return 'FAIL: Element found but not visible: ' + sel;
+        }"""
+    text_check = ""
+    if expected_text:
+        safe_text = json.dumps(expected_text)
+        text_check = f"""
+        var actual = el.textContent || el.value || '';
+        if (actual.indexOf({safe_text}) === -1) {{
+          return 'FAIL: Expected text ' + {safe_text} + ' not found in: ' + actual.substring(0, 100);
+        }}"""
+    safe_sel = json.dumps(selector)
+    js = f"""
+    (function() {{
+      var sel = {safe_sel};
+      var el = document.querySelector(sel);
+      if (!el) return 'FAIL: Element not found: ' + sel;
+      {visible_check}
+      {text_check}
+      var tag = el.tagName.toLowerCase();
+      var txt = (el.textContent || '').substring(0, 60).trim();
+      return 'PASS: ' + tag + (txt ? ' "' + txt + '"' : '') + ' (' + sel + ')';
+    }})()
+    """
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+    print(result)
+
+
+async def cmd_wait_for(selector, timeout_ms=5000):
+    """Wait for element to appear in DOM, up to timeout."""
+    ws_url, _ = get_page_ws()
+    safe_sel = json.dumps(selector)
+    js = f"""
+    (function() {{
+      return new Promise(function(resolve) {{
+        var sel = {safe_sel};
+        var el = document.querySelector(sel);
+        if (el) return resolve('FOUND: ' + el.tagName + ' "' + (el.textContent || '').substring(0, 60).trim() + '"');
+        var obs = new MutationObserver(function() {{
+          var el = document.querySelector(sel);
+          if (el) {{ obs.disconnect(); resolve('FOUND: ' + el.tagName + ' "' + (el.textContent || '').substring(0, 60).trim() + '"'); }}
+        }});
+        obs.observe(document.body, {{childList: true, subtree: true}});
+        setTimeout(function() {{ obs.disconnect(); resolve('TIMEOUT: ' + sel + ' not found after {timeout_ms}ms'); }}, {timeout_ms});
+      }});
+    }})()
+    """
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True, "awaitPromise": True})], timeout=max(15, timeout_ms // 1000 + 5))
+    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+    print(result)
+
+
+async def cmd_check(checks_json=None):
+    """Run batch assertions. Input: JSON array of {selector, text?} objects."""
+    ws_url, _ = get_page_ws()
+    if checks_json is None:
+        raw = sys.stdin.read().strip()
+    else:
+        raw = checks_json
+    try:
+        checks = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        print("Error: Invalid JSON. Expected: [{\"selector\": \"...\", \"text\": \"...\"}]")
+        sys.exit(1)
+
+    passed = 0
+    failed = 0
+    results = []
+    for i, check in enumerate(checks, 1):
+        sel = check.get("selector", "")
+        text = check.get("text")
+        safe_sel = json.dumps(sel)
+        text_check = ""
+        if text:
+            safe_text = json.dumps(text)
+            text_check = f"""
+            var actual = el.textContent || el.value || '';
+            if (actual.indexOf({safe_text}) === -1) {{
+              return 'FAIL: Expected ' + {safe_text} + ' in: ' + actual.substring(0, 80);
+            }}"""
+        js = f"""
+        (function() {{
+          var el = document.querySelector({safe_sel});
+          if (!el) return 'FAIL: Not found: ' + {safe_sel};
+          {text_check}
+          return 'PASS: ' + el.tagName + ' (' + {safe_sel} + ')';
+        }})()
+        """
+        r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+        result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+        if result.startswith("PASS"):
+            passed += 1
+        else:
+            failed += 1
+        results.append(f"  {i}. {result}")
+
+    print(f"Test Report: {passed} passed, {failed} failed")
+    print("─" * 40)
+    for line in results:
+        print(line)
+
+
+async def cmd_assert_url(expected_url):
+    """Assert current page URL contains the expected substring."""
+    ws_url, _ = get_page_ws()
+    safe_expected = json.dumps(expected_url)
+    js = f"""(function() {{
+      var href = window.location.href;
+      var expected = {safe_expected};
+      if (href.indexOf(expected) !== -1) return 'PASS: URL ' + href + ' contains \"' + expected + '\"';
+      return 'FAIL: URL ' + href + ' does not contain \"' + expected + '\"';
+    }})()"""
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+    print(result)
+
+
+async def cmd_assert_title(expected_title):
+    """Assert page title contains the expected substring."""
+    ws_url, _ = get_page_ws()
+    safe_expected = json.dumps(expected_title)
+    js = f"""(function() {{
+      var title = document.title;
+      var expected = {safe_expected};
+      if (title.indexOf(expected) !== -1) return 'PASS: Title \"' + title + '\" contains \"' + expected + '\"';
+      return 'FAIL: Title \"' + title + '\" does not contain \"' + expected + '\"';
+    }})()"""
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+    print(result)
+
+
+async def cmd_assert_count(selector, expected_count):
+    """Assert the number of elements matching a CSS selector equals expected_count."""
+    ws_url, _ = get_page_ws()
+    safe_sel = json.dumps(selector)
+    exp = int(expected_count)
+    js = f"""(function() {{
+      var count = document.querySelectorAll({safe_sel}).length;
+      var exp = {exp};
+      if (count === exp) return 'PASS: Found ' + count + ' element(s) matching {safe_sel} (expected ' + exp + ')';
+      return 'FAIL: Expected ' + exp + ' \"{selector}\" but found ' + count;
+    }})()"""
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+    print(result)
+
+
+async def cmd_assert_value(selector, expected_value):
+    """Assert an input/textarea/select element's value equals expected_value."""
+    ws_url, _ = get_page_ws()
+    safe_sel = json.dumps(selector)
+    safe_expected = json.dumps(expected_value)
+    js = f"""(function() {{
+      var el = document.querySelector({safe_sel});
+      if (!el) return 'FAIL: Element not found: ' + {safe_sel};
+      var val = el.value;
+      var expected = {safe_expected};
+      if (val === expected) return 'PASS: Value matches \"' + expected + '\"';
+      return 'FAIL: Expected value \"' + expected + '\" but got \"' + val + '\"';
+    }})()"""
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+    print(result)
+
+
+async def cmd_assert_attr(selector, attr, expected):
+    """Assert element attribute value contains expected substring."""
+    ws_url, _ = get_page_ws()
+    safe_sel = json.dumps(selector)
+    safe_attr = json.dumps(attr)
+    safe_expected = json.dumps(expected)
+    js = f"""(function() {{
+      var el = document.querySelector({safe_sel});
+      if (!el) return 'FAIL: Element not found: ' + {safe_sel};
+      var val = el.getAttribute({safe_attr}) || '';
+      var expected = {safe_expected};
+      if (val.indexOf(expected) !== -1) return 'PASS: ' + {safe_sel} + '[' + {safe_attr} + '] = \"' + val + '\"';
+      return 'FAIL: Expected ' + {safe_sel} + '[' + {safe_attr} + '] to contain \"' + expected + '\" but got \"' + val + '\"';
+    }})()"""
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+    print(result)
+
+
+async def cmd_assert_visible(selector, should_be_visible=True):
+    """Assert element is visible (or hidden). should_be_visible=True checks for visible, False for hidden."""
+    ws_url, _ = get_page_ws()
+    safe_sel = json.dumps(selector)
+    expect_label = "visible" if should_be_visible else "hidden"
+    opposite_label = "hidden" if should_be_visible else "visible"
+    js = f"""(function() {{
+      var el = document.querySelector({safe_sel});
+      if (!el) return 'FAIL: Element not found: ' + {safe_sel};
+      var style = window.getComputedStyle(el);
+      var rect = el.getBoundingClientRect();
+      var isVisible = (
+        style.display !== 'none' &&
+        style.visibility !== 'hidden' &&
+        style.opacity !== '0' &&
+        (rect.width > 0 || rect.height > 0)
+      );
+      var expectVisible = {str(should_be_visible).lower()};
+      if (isVisible === expectVisible) return 'PASS: ' + {safe_sel} + ' is {expect_label}';
+      return 'FAIL: ' + {safe_sel} + ' expected {expect_label} but is {opposite_label}';
+    }})()"""
+    r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+    print(result)
+
+
+async def cmd_screenshot_diff(path1, path2):
+    """Compare two screenshot files byte-by-byte. No CDP required."""
+    for path in (path1, path2):
+        if not os.path.exists(path):
+            print(f"ERROR: File not found: {path}")
+            return
+    size1 = os.path.getsize(path1)
+    size2 = os.path.getsize(path2)
+    with open(path1, "rb") as f1, open(path2, "rb") as f2:
+        data1 = f1.read()
+        data2 = f2.read()
+    if data1 == data2:
+        print("MATCH: Files are identical")
+    else:
+        kb1 = size1 / 1024
+        kb2 = size2 / 1024
+        print(f"DIFF: Files differ ({os.path.basename(path1)}: {kb1:.1f}KB, {os.path.basename(path2)}: {kb2:.1f}KB)")
+
+
 async def cmd_a11y_snapshot():
     """Output a compact accessibility snapshot for AI agent navigation.
 
@@ -3338,36 +4133,68 @@ class MCPServer:
 
     def _register_tools(self):
         return [
-            {"name": "browser_navigate", "description": "Navigate to a URL",
-             "inputSchema": {"type": "object", "properties": {"url": {"type": "string", "description": "URL to navigate to"}}, "required": ["url"]}},
-            {"name": "browser_screenshot", "description": "Take a screenshot of the current page",
-             "inputSchema": {"type": "object", "properties": {"filename": {"type": "string", "description": "Output filename", "default": "screenshot.png"}}}},
-            {"name": "browser_click", "description": "Click an element by CSS selector",
-             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector"}}, "required": ["selector"]}},
-            {"name": "browser_type", "description": "Type text into an input element",
-             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector"}, "text": {"type": "string", "description": "Text to type"}}, "required": ["selector", "text"]}},
-            {"name": "browser_content", "description": "Get text content of the current page",
+            {"name": "browser_navigate", "description": "Navigate the browser to a URL and return the page text content. Use this to open websites, follow links, or load web applications. Waits for page load before returning. Returns first 10000 chars of visible text.",
+             "inputSchema": {"type": "object", "properties": {"url": {"type": "string", "description": "Full URL to navigate to (must include https://)"}}, "required": ["url"]}},
+            {"name": "browser_screenshot", "description": "Capture a screenshot of the current browser viewport. Supports element-level cropping to save tokens (capture only a specific element instead of full page). Use JPEG format with quality parameter for smaller files (~5x smaller than PNG). Prefer element cropping + JPEG for token-efficient AI workflows.",
+             "inputSchema": {"type": "object", "properties": {"filename": {"type": "string", "description": "Output file path (e.g. /tmp/screenshot.png). Extension determines format: .png, .jpg, .webp", "default": "screenshot.png"}, "element": {"type": "string", "description": "CSS selector to capture only that element (crops to bounding box). Saves ~3-7x tokens vs full page."}, "quality": {"type": "number", "description": "JPEG quality 1-100 (only for .jpg files). Lower = smaller file = fewer tokens. Default: 80"}}}},
+            {"name": "browser_click", "description": "Click an element on the page identified by CSS selector. Auto-waits up to 5 seconds for the element to appear (MutationObserver). Scrolls the element into view before clicking. Returns the tag name and text of the clicked element.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the element to click (e.g. '#submit-btn', '.nav a', 'button[type=submit]')"}}, "required": ["selector"]}},
+            {"name": "browser_type", "description": "Type text into an input or textarea element. Uses React-compatible value setting (native setter + input/change events). Auto-waits up to 5 seconds for the element. Use browser_fill as an alias.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the input element"}, "text": {"type": "string", "description": "Text value to type into the element"}}, "required": ["selector", "text"]}},
+            {"name": "browser_content", "description": "Get the visible text content of the current page (document.body.innerText). Returns up to 10000 characters. Use this to read page content without HTML markup. Prefer browser_a11y for structured navigation data.",
+             "inputSchema": {"type": "object", "properties": {}}},
+            {"name": "browser_html", "description": "Get the full HTML source of the current page (document.documentElement.outerHTML). Returns up to 50000 characters. Use sparingly — prefer browser_content or browser_a11y for most tasks as they return smaller, more useful data.",
              "inputSchema": {"type": "object", "properties": {}}},
-            {"name": "browser_html", "description": "Get HTML source of the current page",
+            {"name": "browser_eval", "description": "Execute arbitrary JavaScript code in the browser page context and return the result. Use for custom DOM queries, data extraction, or page manipulation that other tools don't cover. Expression is evaluated via Runtime.evaluate.",
+             "inputSchema": {"type": "object", "properties": {"expression": {"type": "string", "description": "JavaScript expression to evaluate (e.g. 'document.title', 'document.querySelectorAll(\"a\").length')"}}, "required": ["expression"]}},
+            {"name": "browser_tabs", "description": "List all open browser tabs with their IDs, URLs, and titles. Use this to see what pages are open and get tab IDs for switching between them with other navigation commands.",
              "inputSchema": {"type": "object", "properties": {}}},
-            {"name": "browser_eval", "description": "Execute JavaScript in the browser",
-             "inputSchema": {"type": "object", "properties": {"expression": {"type": "string", "description": "JavaScript expression"}}, "required": ["expression"]}},
-            {"name": "browser_tabs", "description": "List all open browser tabs",
+            {"name": "browser_console", "description": "Navigate to a URL and capture all browser console output (log, warn, error, info) and uncaught exceptions. Use for debugging JavaScript errors, monitoring API calls logged to console, or verifying application behavior.",
+             "inputSchema": {"type": "object", "properties": {"url": {"type": "string", "description": "URL to navigate to while capturing console output"}}}},
+            {"name": "browser_network", "description": "Navigate to a URL and monitor all network requests/responses. Returns each request's URL, HTTP status code, and MIME type. Use for debugging API calls, checking resource loading, or verifying network behavior.",
+             "inputSchema": {"type": "object", "properties": {"url": {"type": "string", "description": "URL to navigate to while monitoring network traffic"}}}},
+            {"name": "browser_a11y", "description": "Get the accessibility tree of the current page as structured data. Returns interactive elements with @N references that can be used with browser_click. This is the PREFERRED way to understand page structure — uses ~500 tokens vs ~250K for screenshots. Use 'summary' mode for a compact view.",
+             "inputSchema": {"type": "object", "properties": {"mode": {"type": "string", "enum": ["full", "summary"], "description": "Output detail level: 'full' for complete tree, 'summary' for interactive elements only", "default": "full"}}}},
+            {"name": "browser_fill", "description": "Set an input element's value using React-compatible method (native descriptor setter + input/change events). Auto-waits up to 5 seconds for the element. Works with regular inputs, textareas, and React controlled components.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the input element"}, "value": {"type": "string", "description": "Value to set in the input field"}}, "required": ["selector", "value"]}},
+            {"name": "browser_launch", "description": "Launch an isolated browser instance with Chrome DevTools Protocol enabled. Uses existing Brave/Chrome/Chromium installation — no browser download needed. Creates an isolated profile directory so your personal browser data is never touched.",
              "inputSchema": {"type": "object", "properties": {}}},
-            {"name": "browser_console", "description": "Get console logs from the browser",
-             "inputSchema": {"type": "object", "properties": {"url": {"type": "string", "description": "URL to navigate and capture logs"}}}},
-            {"name": "browser_network", "description": "Monitor network requests",
-             "inputSchema": {"type": "object", "properties": {"url": {"type": "string", "description": "URL to navigate and monitor"}}}},
-            {"name": "browser_a11y", "description": "Get accessibility tree of the current page",
-             "inputSchema": {"type": "object", "properties": {"mode": {"type": "string", "enum": ["full", "summary"], "default": "full"}}}},
-            {"name": "browser_fill", "description": "Set input value (React-compatible)",
-             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector"}, "value": {"type": "string", "description": "Value to set"}}, "required": ["selector", "value"]}},
-            {"name": "browser_launch", "description": "Launch browser with CDP enabled",
+            {"name": "browser_close", "description": "Close the currently active browser tab. Use this to clean up after automation tasks or to close unwanted popups/tabs that were opened during navigation.",
              "inputSchema": {"type": "object", "properties": {}}},
-            {"name": "browser_close", "description": "Close the active tab",
+            {"name": "browser_extract", "description": "Extract structured data from elements matching a CSS selector. No LLM needed — pure DOM extraction. Returns text (default), JSON (with tag, text, attrs, href, src), specific attributes, or clean list. Use for scraping tables, lists, links, form values. Limit: 100 elements for JSON, 200 for text.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector to match elements (e.g. 'table tr', '.product', 'a')"}, "format": {"type": "string", "enum": ["text", "json", "list"], "description": "Output format: 'text' (one per line), 'json' (full structure with attrs), 'list' (numbered)", "default": "text"}}, "required": ["selector"]}},
+            {"name": "browser_observe", "description": "List all interactive elements on the current page with their available actions (CLICK, FILL, NAVIGATE, TOGGLE, SELECT, SUBMIT, UPLOAD). Like Stagehand observe() but deterministic — no LLM needed. Shows what you CAN DO on the page. Use this to understand page structure before acting.",
              "inputSchema": {"type": "object", "properties": {}}},
-            {"name": "browser_describe", "description": "Get full page description with accessibility snapshot, screenshot, and text content. Use when a11y-snapshot alone is insufficient (canvas, WebGL, visual verification).",
+            {"name": "browser_smart_click", "description": "Click an element by its visible text — no CSS selector needed. Uses fuzzy matching across text content, aria-label, title, placeholder, and value. Returns match score and alternatives. Like Stagehand act('Click login') but without LLM cost. Use when you know WHAT to click but not the exact selector.",
+             "inputSchema": {"type": "object", "properties": {"text": {"type": "string", "description": "Visible text of the element to click (e.g. 'Login', 'Submit Order', 'Learn more')"}}, "required": ["text"]}},
+            {"name": "browser_smart_fill", "description": "Fill an input by its label or placeholder text — no CSS selector needed. Finds input by associated label, placeholder, aria-label, name, or id. React-compatible value setting. Use when you know WHAT field to fill but not the exact selector.",
+             "inputSchema": {"type": "object", "properties": {"label": {"type": "string", "description": "Label or placeholder text of the input (e.g. 'Email', 'Password', 'Search')"}, "value": {"type": "string", "description": "Value to fill in the input"}}, "required": ["label", "value"]}},
+            {"name": "browser_smart_select", "description": "Select a dropdown option by label and option text — no CSS selector needed. Finds the select element by label/name, then selects the matching option. Use for dropdown interactions without knowing selectors.",
+             "inputSchema": {"type": "object", "properties": {"label": {"type": "string", "description": "Label text of the select dropdown"}, "option": {"type": "string", "description": "Text of the option to select"}}, "required": ["label", "option"]}},
+            {"name": "browser_describe", "description": "Get a comprehensive page description combining three data sources: (1) accessibility tree with @N references for interactive elements, (2) a PNG screenshot saved to disk, and (3) visible text content. Use this when browser_a11y alone is insufficient — for canvas/WebGL content, visual verification, or complex dynamic UIs. This is the vision fallback tool.",
              "inputSchema": {"type": "object", "properties": {}}},
+            {"name": "browser_assert", "description": "Assert that an element matching the CSS selector exists and optionally contains expected text. Returns PASS or FAIL with details. Use this for automated testing — verify page state after navigation or interaction. Checks visibility by default.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector to check for existence"}, "text": {"type": "string", "description": "Optional: expected text content (substring match)"}, "visible": {"type": "boolean", "description": "Check element is visible (not hidden/zero-size)", "default": True}}, "required": ["selector"]}},
+            {"name": "browser_wait_for", "description": "Wait for an element matching the CSS selector to appear in the DOM, up to the specified timeout. Uses MutationObserver for efficient waiting. Returns the element's tag and text when found, or TIMEOUT if not found. Use before interactions with dynamically loaded content.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector to wait for"}, "timeout": {"type": "number", "description": "Maximum wait time in milliseconds", "default": 5000}}, "required": ["selector"]}},
+            {"name": "browser_check", "description": "Run a batch of assertions on the current page and return a test report. Each check verifies element existence and optional text content. Returns a summary with PASS/FAIL count. Use this for comprehensive page validation after a series of actions.",
+             "inputSchema": {"type": "object", "properties": {"checks": {"type": "array", "description": "Array of checks, each with 'selector' (required) and 'text' (optional)", "items": {"type": "object", "properties": {"selector": {"type": "string"}, "text": {"type": "string"}}, "required": ["selector"]}}}, "required": ["checks"]}},
+            {"name": "browser_assert_url", "description": "Assert the current page URL contains the expected substring. Returns PASS with the full URL or FAIL. Use this after navigation to verify you landed on the correct page.",
+             "inputSchema": {"type": "object", "properties": {"expected_url": {"type": "string", "description": "Expected substring to find in the current URL (e.g. 'example.com', '/dashboard', '?tab=settings')"}}, "required": ["expected_url"]}},
+            {"name": "browser_assert_title", "description": "Assert the current page title contains the expected substring. Returns PASS with full title or FAIL. Useful for verifying page identity without relying on URL.",
+             "inputSchema": {"type": "object", "properties": {"expected_title": {"type": "string", "description": "Expected substring to find in the page title (e.g. 'Dashboard', 'Login')"}}, "required": ["expected_title"]}},
+            {"name": "browser_assert_count", "description": "Assert the number of elements matching a CSS selector equals an expected count. Returns PASS with count or FAIL with actual vs expected. Use this to verify list items, table rows, search results, or repeated components.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector to count matching elements"}, "expected_count": {"type": "integer", "description": "Expected number of matching elements"}}, "required": ["selector", "expected_count"]}},
+            {"name": "browser_assert_value", "description": "Assert an input, textarea, or select element's current value equals the expected string. Returns PASS or FAIL with actual value. Use this to verify form field state after filling or after page load.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the input/textarea/select element"}, "expected_value": {"type": "string", "description": "Expected exact value of the element"}}, "required": ["selector", "expected_value"]}},
+            {"name": "browser_assert_attr", "description": "Assert an element's HTML attribute contains the expected substring. Returns PASS with actual value or FAIL. Use this to verify href, src, data-*, aria-* and other attributes without reading full page HTML.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the element"}, "attr": {"type": "string", "description": "Attribute name (e.g. 'href', 'src', 'data-id', 'aria-label')"}, "expected": {"type": "string", "description": "Expected substring in the attribute value"}}, "required": ["selector", "attr", "expected"]}},
+            {"name": "browser_assert_visible", "description": "Assert an element is visible on the page (not hidden by CSS). Checks display, visibility, opacity and bounding rect. Returns PASS or FAIL. Use this to verify modals opened, elements shown after interaction, or content loaded.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the element to check for visibility"}}, "required": ["selector"]}},
+            {"name": "browser_assert_hidden", "description": "Assert an element exists but is hidden (display:none, visibility:hidden, opacity:0, or zero size). Returns PASS or FAIL. Use this to verify modals closed, tooltips dismissed, or conditional sections hidden.",
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the element expected to be hidden"}}, "required": ["selector"]}},
+            {"name": "browser_screenshot_diff", "description": "Compare two screenshot PNG files byte-by-byte. Returns MATCH if files are identical or DIFF with file sizes if different. Use this for visual regression testing — take a baseline screenshot, perform actions, take another screenshot, then compare.",
+             "inputSchema": {"type": "object", "properties": {"path1": {"type": "string", "description": "Absolute path to the first (baseline) screenshot PNG"}, "path2": {"type": "string", "description": "Absolute path to the second (current) screenshot PNG"}}, "required": ["path1", "path2"]}},
         ]
 
     def _handle_request(self, request):
@@ -3405,7 +4232,7 @@ class MCPServer:
         import io, subprocess
         tool_map = {
             "browser_navigate": lambda a: ["go", a.get("url", "")],
-            "browser_screenshot": lambda a: ["shot"] + ([self._safe_filename(a["filename"])] if a.get("filename") else []),
+            "browser_screenshot": lambda a: ["shot"] + ([self._safe_filename(a["filename"])] if a.get("filename") else []) + ([f"--element={a['element']}"] if a.get("element") else []) + ([f"--quality={a['quality']}"] if a.get("quality") else []),
             "browser_click": lambda a: ["click", a.get("selector", "")],
             "browser_type": lambda a: ["type", a.get("selector", ""), a.get("text", "")],
             "browser_content": lambda a: ["content"],
@@ -3418,16 +4245,34 @@ class MCPServer:
             "browser_fill": lambda a: ["fill", a.get("selector", ""), a.get("value", "")],
             "browser_launch": lambda a: ["launch"],
             "browser_close": lambda a: ["close"],
+            "browser_extract": lambda a: ["extract", a.get("selector", "")] + ([f"--{a['format']}"] if a.get("format") and a["format"] != "text" else []),
+            "browser_observe": lambda a: ["observe"],
+            "browser_smart_click": lambda a: ["smart-click", a.get("text", "")],
+            "browser_smart_fill": lambda a: ["smart-fill", a.get("label", ""), a.get("value", "")],
+            "browser_smart_select": lambda a: ["smart-select", a.get("label", ""), a.get("option", "")],
             "browser_describe": lambda a: ["describe"],
+            "browser_assert": lambda a: ["assert", a.get("selector", "")] + ([a["text"]] if a.get("text") else []),
+            "browser_wait_for": lambda a: ["wait-for", a.get("selector", "")] + ([str(a["timeout"])] if a.get("timeout") else []),
+            "browser_check": lambda a: ["check", json.dumps(a.get("checks", []))],
+            "browser_assert_url": lambda a: ["assert-url", a.get("expected_url", "")],
+            "browser_assert_title": lambda a: ["assert-title", a.get("expected_title", "")],
+            "browser_assert_count": lambda a: ["assert-count", a.get("selector", ""), str(a.get("expected_count", 0))],
+            "browser_assert_value": lambda a: ["assert-value", a.get("selector", ""), a.get("expected_value", "")],
+            "browser_assert_attr": lambda a: ["assert-attr", a.get("selector", ""), a.get("attr", ""), a.get("expected", "")],
+            "browser_assert_visible": lambda a: ["assert-visible", a.get("selector", "")],
+            "browser_assert_hidden": lambda a: ["assert-hidden", a.get("selector", "")],
+            "browser_screenshot_diff": lambda a: ["screenshot-diff", a.get("path1", ""), a.get("path2", "")],
         }
         if tool_name not in tool_map:
             return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32602, "message": f"Unknown tool: {tool_name}"}}
 
         cli_args = [a for a in tool_map[tool_name](args) if a]
         try:
+            env = os.environ.copy()
+            env["CDPILOT_MCP_SESSION"] = "1"
             result = subprocess.run(
                 [sys.executable, __file__] + cli_args,
-                capture_output=True, text=True, timeout=30
+                capture_output=True, text=True, timeout=30, env=env
             )
             output = result.stdout.strip()
             errors = result.stderr.strip()
@@ -3536,7 +4381,12 @@ if __name__ == "__main__":
         "go": lambda: (require_args(1, "go <url>"), cmd_go(args[0]))[1] if not args else cmd_go(args[0]),
         "content": cmd_content,
         "html": cmd_html,
-        "shot": lambda: cmd_shot(args[0] if args else None),
+        "shot": lambda: cmd_shot(
+            output=next((a for a in args if not a.startswith("--")), None),
+            quality=next((a.split("=")[1] for a in args if a.startswith("--quality=")), None),
+            element=next((a.split("=")[1] for a in args if a.startswith("--element=")), None),
+            fmt=next((a.split("=")[1] for a in args if a.startswith("--format=")), None),
+        ),
         "shot-annotated": lambda: cmd_shot_annotated(args[0] if args else None),
         "batch": cmd_batch,
         "eval": lambda: (require_args(1, "eval <js>"), None)[1] if not args else cmd_eval(" ".join(args)),
@@ -3564,6 +4414,23 @@ if __name__ == "__main__":
         'a11y': lambda: cmd_a11y(' '.join(args)),
         'a11y-snapshot': cmd_a11y_snapshot,
         'describe': cmd_describe,
+        'extract': lambda: (require_args(1, 'extract <selector> [--json|--list|--attrs=href,title]'), None)[1] if not args else cmd_extract(args[0], next((a.lstrip('-') for a in args[1:] if a.startswith('--')), "text")),
+        'observe': cmd_observe,
+        'run': lambda: (require_args(1, 'run <script.cdp>'), None)[1] if not args else cmd_run_script(args[0]),
+        'smart-click': lambda: (require_args(1, 'smart-click <text>'), None)[1] if not args else cmd_smart_click(" ".join(args)),
+        'smart-fill': lambda: (require_args(2, 'smart-fill <label> <value>'), None)[1] if len(args) < 2 else cmd_smart_fill(args[0], " ".join(args[1:])),
+        'smart-select': lambda: (require_args(2, 'smart-select <label> <option>'), None)[1] if len(args) < 2 else cmd_smart_select(args[0], " ".join(args[1:])),
+        'assert': lambda: (require_args(1, 'assert <selector> [text]'), None)[1] if not args else cmd_assert(args[0], args[1] if len(args) > 1 else None),
+        'wait-for': lambda: (require_args(1, 'wait-for <selector> [timeout_ms]'), None)[1] if not args else cmd_wait_for(args[0], int(args[1]) if len(args) > 1 else 5000),
+        'check': lambda: cmd_check(args[0] if args else None),
+        'assert-url': lambda: (require_args(1, 'assert-url <expected>'), None)[1] if not args else cmd_assert_url(args[0]),
+        'assert-title': lambda: (require_args(1, 'assert-title <expected>'), None)[1] if not args else cmd_assert_title(args[0]),
+        'assert-count': lambda: (require_args(2, 'assert-count <selector> <n>'), None)[1] if len(args) < 2 else cmd_assert_count(args[0], int(args[1])),
+        'assert-value': lambda: (require_args(2, 'assert-value <selector> <value>'), None)[1] if len(args) < 2 else cmd_assert_value(args[0], args[1]),
+        'assert-attr': lambda: (require_args(3, 'assert-attr <selector> <attr> <expected>'), None)[1] if len(args) < 3 else cmd_assert_attr(args[0], args[1], args[2]),
+        'assert-visible': lambda: (require_args(1, 'assert-visible <selector>'), None)[1] if not args else cmd_assert_visible(args[0], True),
+        'assert-hidden': lambda: (require_args(1, 'assert-hidden <selector>'), None)[1] if not args else cmd_assert_visible(args[0], False),
+        'screenshot-diff': lambda: (require_args(2, 'screenshot-diff <path1> <path2>'), None)[1] if len(args) < 2 else cmd_screenshot_diff(args[0], args[1]),
         'click-ref': lambda: (require_args(1, 'click-ref <@N>'), None)[1] if not args else cmd_click_ref(args[0]),
         'hover': lambda: (require_args(1, 'hover <selector>'), None)[1] if not args else cmd_hover(args[0]),
         'dblclick': lambda: (require_args(1, 'dblclick <selector>'), None)[1] if not args else cmd_dblclick(args[0]),
@@ -3582,7 +4449,7 @@ if __name__ == "__main__":
     # Commands that do not require the visual indicator / input blocker
     NO_CONTROL_CMDS = {'glow', 'stop', 'tabs', 'close', 'close-tab', 'new-tab',
                        'dialog', 'download', 'throttle', 'permission', 'intercept',
-                       'batch'}
+                       'batch', 'screenshot-diff', 'run'}
     # Clean up idle sessions before running any command
     _cleanup_idle_sessions()