cdpilot 0.1.2 → 0.2.1

package/src/cdpilot.py

@@ -25,18 +25,202 @@ import time
 import urllib.request
 import subprocess
 import shutil
+import platform
+import socket
+import difflib
+import hashlib
+import re as _re
 
-# ─── Session Configuration ───
-# cdpilot runs in its own Chrome instance on the configured CDP port.
-# The user's existing Chrome/browser session is not affected.
+# ─── Project-Based Multi-Instance Configuration ───
+# Each project directory (cwd) gets its own browser instance with
+# a unique CDP port and isolated profile directory. Zero-config.
 
-CDP_PORT = int(os.environ.get("CDP_PORT", "9222"))
+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():
+    """Derive a deterministic project ID from the current working directory.
+
+    Prefers CDPILOT_PROJECT_ID env (set by bin/cdpilot.js based on caller's cwd)
+    over os.getcwd() which may differ when invoked via npx or absolute path.
+    """
+    env_id = os.environ.get("CDPILOT_PROJECT_ID")
+    if env_id:
+        return env_id
+    cwd = os.getcwd()
+    dir_name = os.path.basename(cwd)
+    safe_name = _re.sub(r'[^a-zA-Z0-9-]', '', dir_name)[:20]
+    hash_suffix = hashlib.md5(cwd.encode()).hexdigest()[:6]
+    return f"{safe_name}-{hash_suffix}" if safe_name else hash_suffix
+
+
+def _is_port_free(port):
+    """Check if a port is available for binding."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind(("127.0.0.1", port))
+            return True
+        except OSError:
+            return False
+
+
+def _load_registry():
+    """Read the global project registry."""
+    try:
+        with open(REGISTRY_FILE) as f:
+            data = json.load(f)
+            return data.get("projects", {})
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def _save_registry(projects):
+    """Write the global project registry."""
+    os.makedirs(os.path.dirname(REGISTRY_FILE), exist_ok=True)
+    with open(REGISTRY_FILE, 'w') as f:
+        json.dump({"version": 1, "projects": projects}, f, indent=2)
+
+
+def _register_project(project_id, port, profile_dir, pid=None):
+    """Register or update a project in the global registry."""
+    registry = _load_registry()
+    existing = registry.get(project_id, {})
+    registry[project_id] = {
+        "cwd": os.getcwd(),
+        "port": port,
+        "profile_dir": profile_dir,
+        "pid": pid,
+        "created": existing.get("created", time.strftime("%Y-%m-%dT%H:%M:%S")),
+        "last_used": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        "status": "running" if pid else "stopped",
+    }
+    _save_registry(registry)
+
+
+def _cleanup_registry():
+    """Update status for dead processes and return cleaned registry."""
+    registry = _load_registry()
+    changed = False
+    for pid_key, info in registry.items():
+        if info.get("status") == "running":
+            port = info.get("port")
+            if port and _is_port_free(port):
+                info["status"] = "stopped"
+                info["pid"] = None
+                changed = True
+    if changed:
+        _save_registry(registry)
+    return registry
+
+
+def _allocate_port(project_id):
+    """Find a free port for the given project."""
+    registry = _load_registry()
+
+    # Reuse existing port if still free
+    if project_id in registry:
+        existing_port = registry[project_id].get("port")
+        if existing_port and _is_port_free(existing_port):
+            return existing_port
+
+    # Collect ports used by other active projects
+    used_ports = set()
+    for pid, info in registry.items():
+        if pid != project_id and info.get("port"):
+            used_ports.add(info["port"])
+
+    # Find first free port in range
+    for port in range(CDPILOT_PORT_RANGE_START, CDPILOT_PORT_RANGE_END):
+        if port not in used_ports and _is_port_free(port):
+            return port
+
+    raise RuntimeError(
+        f"No free port in range {CDPILOT_PORT_RANGE_START}-{CDPILOT_PORT_RANGE_END}"
+    )
+
+
+def _resolve_project_config():
+    """Determine port, profile dir, and project ID based on cwd + env vars."""
+    env_port = os.environ.get("CDP_PORT")
+    env_profile = os.environ.get("CDPILOT_PROFILE")
+
+    # Treat CDP_PORT=0 as "auto-allocate"
+    has_explicit_port = env_port and env_port != "0"
+
+    # Full manual override (legacy behavior)
+    if has_explicit_port and env_profile:
+        return int(env_port), env_profile, None
+
+    project_id = _get_project_id()
+    registry = _load_registry()
+    default_profile = os.path.join(CDPILOT_HOME, "projects", project_id, "profile")
+
+    if project_id in registry:
+        info = registry[project_id]
+        port = int(env_port) if has_explicit_port else info.get("port", 9222)
+        profile = env_profile or info.get("profile_dir", default_profile)
+        return port, profile, project_id
+
+    # New project: allocate port
+    try:
+        port = int(env_port) if has_explicit_port else _allocate_port(project_id)
+    except RuntimeError:
+        port = 9222  # fallback
+    profile = env_profile or default_profile
+    return port, profile, project_id
+
+
+def _migrate_legacy_profile():
+    """Migrate old single-profile layout to project-based layout."""
+    legacy_profile = os.path.join(CDPILOT_HOME, "profile")
+    if (os.path.isdir(legacy_profile) and not os.path.islink(legacy_profile)
+            and not os.path.exists(REGISTRY_FILE)):
+        project_id = _get_project_id()
+        new_dir = os.path.join(CDPILOT_HOME, "projects", project_id)
+        new_profile = os.path.join(new_dir, "profile")
+        if not os.path.exists(new_profile):
+            os.makedirs(new_dir, exist_ok=True)
+            os.rename(legacy_profile, new_profile)
+            os.symlink(new_profile, legacy_profile)
+
+
+# Resolve project config at module load time
+try:
+    _migrate_legacy_profile()
+except Exception:
+    pass
+CDP_PORT, PROFILE_DIR, PROJECT_ID = _resolve_project_config()
 CDP_BASE = f"http://127.0.0.1:{CDP_PORT}"
 CHROME_BIN = os.environ.get("CHROME_BIN")
-PROFILE_DIR = os.environ.get("CDPILOT_PROFILE", os.path.expanduser("~/.cdpilot/profile"))
-SCREENSHOT_DIR = "/tmp"
+
+if platform.system() == "Windows":
+    SCREENSHOT_DIR = os.path.expandvars(r"%TEMP%")
+else:
+    SCREENSHOT_DIR = "/tmp"
 
 DEV_EXTENSIONS_FILE = os.path.join(PROFILE_DIR, 'dev-extensions.json')
+
+# ─── Auto-Wait JS Helper ───────────────────────────────────────────────────────
+# Tarayıcıya inject edilir; MutationObserver ile element görünene kadar bekler.
+WAIT_AND_QUERY_JS = """
+window.__cdpilot_waitFor = function(selector, timeout) {
+  return new Promise(function(resolve) {
+    var el = document.querySelector(selector);
+    if (el) { resolve(el); return; }
+    var obs = new MutationObserver(function() {
+      var found = document.querySelector(selector);
+      if (found) { obs.disconnect(); resolve(found); }
+    });
+    obs.observe(document.documentElement, {childList: true, subtree: true});
+    setTimeout(function() { obs.disconnect(); resolve(null); }, timeout || 5000);
+  });
+};
+"""
 PROXY_CONFIG_FILE = os.path.join(PROFILE_DIR, 'proxy.json')
 HEADLESS_CONFIG_FILE = os.path.join(PROFILE_DIR, 'headless.json')
 DOWNLOAD_CONFIG_FILE = os.path.join(PROFILE_DIR, 'download-config.json')
@@ -88,41 +272,100 @@ def _cleanup_stale_sessions():
 INTERCEPT_RULES = []  # list of (pattern, action, data) tuples
 DIALOG_MODE = None    # 'accept', 'dismiss', or None
 _current_session_id = None  # lazy init
+_A11Y_REF_MAP = {}  # ref_num -> backendNodeId mapping
+_A11Y_REF_FILE = os.path.join(PROFILE_DIR, 'a11y-refs.json')
+
+
+def _save_a11y_refs(ref_map):
+    """Persist a11y ref map to disk for cross-process access."""
+    os.makedirs(os.path.dirname(_A11Y_REF_FILE), exist_ok=True)
+    with open(_A11Y_REF_FILE, 'w') as f:
+        json.dump(ref_map, f)
+
+
+def _load_a11y_refs():
+    """Load a11y ref map from disk."""
+    try:
+        with open(_A11Y_REF_FILE) as f:
+            data = json.load(f)
+            return {int(k): v for k, v in data.items()}
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
 
 # ─── Visual Indicator Overlay CSS ───
 
 GLOW_CSS = """
 (function() {
-  if (document.getElementById('cdpilot-glow')) return 'already active';
-  const style = document.createElement('style');
-  style.id = 'cdpilot-glow';
+  if (document.getElementById('cdpilot-glow-overlay')) {
+    document.getElementById('cdpilot-glow-overlay').style.opacity = '1';
+    clearTimeout(window.__cdpilot_glow_timeout);
+    return 'glow refreshed';
+  }
+  var style = document.createElement('style');
+  style.id = 'cdpilot-glow-style';
   style.textContent = `
     @keyframes cdpilot-pulse {
-      0%, 100% { box-shadow: inset 0 0 20px 4px rgba(34, 197, 94, 0.25), inset 0 0 60px 8px rgba(34, 197, 94, 0.08); }
-      50% { box-shadow: inset 0 0 30px 6px rgba(34, 197, 94, 0.35), inset 0 0 80px 12px rgba(34, 197, 94, 0.12); }
+      0%, 100% { box-shadow: inset 0 0 20px 4px rgba(34,197,94,0.25), inset 0 0 60px 8px rgba(34,197,94,0.08); }
+      50% { box-shadow: inset 0 0 30px 6px rgba(34,197,94,0.35), inset 0 0 80px 12px rgba(34,197,94,0.12); }
     }
-    body::after {
-      content: '';
-      position: fixed;
-      top: 0; left: 0; right: 0; bottom: 0;
-      pointer-events: none;
-      z-index: 2147483647;
+    #cdpilot-glow-overlay {
+      position: fixed; top: 0; left: 0; right: 0; bottom: 0;
+      pointer-events: none; z-index: 2147483646;
       animation: cdpilot-pulse 2s ease-in-out infinite;
-      border: 2px solid rgba(34, 197, 94, 0.3);
-      border-radius: 0;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.3);
+      border: 2px solid rgba(34,197,94,0.3);
+      transition: opacity 1s ease;
+      opacity: 1;
+    }
+    #cdpilot-ai-toast {
+      position: fixed; bottom: -80px; left: 50%; transform: translateX(-50%);
+      z-index: 2147483647; background: rgba(15,0,0,0.92); color: #ef4444;
+      padding: 14px 28px; border-radius: 12px;
+      font: 600 14px/1.4 system-ui,-apple-system,sans-serif;
+      transition: bottom 0.4s cubic-bezier(0.34,1.56,0.64,1);
+      border: 1px solid rgba(239,68,68,0.4);
+      box-shadow: 0 4px 24px rgba(0,0,0,0.5), 0 0 20px rgba(239,68,68,0.15);
+      pointer-events: none; white-space: nowrap; backdrop-filter: blur(8px);
     }
   `;
   document.head.appendChild(style);
+  var overlay = document.createElement('div');
+  overlay.id = 'cdpilot-glow-overlay';
+  document.body.appendChild(overlay);
+  var toast = document.createElement('div');
+  toast.id = 'cdpilot-ai-toast';
+  toast.textContent = '\\u26A0\\uFE0F  Browser is controlled by AI — please wait';
+  document.body.appendChild(toast);
+  var _tt, _throttle = 0;
+  function _showWarn() {
+    if (!document.getElementById('cdpilot-glow-overlay')) return;
+    var now = Date.now();
+    if (now - _throttle < 2000) return;
+    _throttle = now;
+    toast.style.bottom = '24px';
+    clearTimeout(_tt);
+    _tt = setTimeout(function() { toast.style.bottom = '-80px'; }, 3000);
+  }
+  window.__cdpilot_warn = _showWarn;
+  document.addEventListener('mousemove', _showWarn, true);
+  clearTimeout(window.__cdpilot_glow_timeout);
   return 'glow active';
 })()
 """
 
 GLOW_OFF_CSS = """
 (function() {
-  const el = document.getElementById('cdpilot-glow');
-  if (el) { el.remove(); return 'glow off'; }
-  return 'already off';
+  var overlay = document.getElementById('cdpilot-glow-overlay');
+  var style = document.getElementById('cdpilot-glow-style');
+  var toast = document.getElementById('cdpilot-ai-toast');
+  if (overlay) { overlay.style.opacity = '0'; setTimeout(function() { overlay.remove(); }, 1000); }
+  if (style) setTimeout(function() { style.remove(); }, 1100);
+  if (toast) toast.remove();
+  if (window.__cdpilot_warn) {
+    document.removeEventListener('mousemove', window.__cdpilot_warn, true);
+    delete window.__cdpilot_warn;
+  }
+  clearTimeout(window.__cdpilot_glow_timeout);
+  return overlay ? 'glow fading' : 'already off';
 })()
 """
 
@@ -131,38 +374,36 @@ GLOW_OFF_CSS = """
 INPUT_BLOCKER_ON = """
 (function() {
   if (document.getElementById('cdpilot-input-blocker')) return 'blocker already active';
-  const overlay = document.createElement('div');
+  var overlay = document.createElement('div');
   overlay.id = 'cdpilot-input-blocker';
-  overlay.style.cssText = `
-    position: fixed; top: 0; left: 0; right: 0; bottom: 0;
-    z-index: 2147483646; cursor: not-allowed;
-    background: transparent;
-  `;
-  overlay.addEventListener('mousedown', e => { e.stopPropagation(); e.preventDefault(); }, true);
-  overlay.addEventListener('mouseup', e => { e.stopPropagation(); e.preventDefault(); }, true);
-  overlay.addEventListener('click', e => { e.stopPropagation(); e.preventDefault(); }, true);
-  overlay.addEventListener('dblclick', e => { e.stopPropagation(); e.preventDefault(); }, true);
-  overlay.addEventListener('contextmenu', e => { e.stopPropagation(); e.preventDefault(); }, true);
-  overlay.addEventListener('wheel', e => { e.stopPropagation(); e.preventDefault(); }, {capture: true, passive: false});
+  overlay.style.cssText = 'position:fixed;top:0;left:0;right:0;bottom:0;z-index:2147483646;cursor:not-allowed;background:transparent;';
+  var toast = document.createElement('div');
+  toast.id = 'cdpilot-warning-toast';
+  toast.textContent = '\\u26A0\\uFE0F  Browser is controlled by AI \\u2014 please wait';
+  toast.style.cssText = 'position:fixed;bottom:-80px;left:50%;transform:translateX(-50%);z-index:2147483647;background:rgba(15,0,0,0.92);color:#ef4444;padding:14px 28px;border-radius:12px;font:600 14px/1.4 system-ui,-apple-system,sans-serif;transition:bottom 0.4s cubic-bezier(0.34,1.56,0.64,1);border:1px solid rgba(239,68,68,0.4);box-shadow:0 4px 24px rgba(0,0,0,0.5),0 0 20px rgba(239,68,68,0.15);pointer-events:none;white-space:nowrap;backdrop-filter:blur(8px);';
+  document.body.appendChild(toast);
+  var _tt;
+  function _warn() {
+    toast.style.bottom = '24px';
+    clearTimeout(_tt);
+    _tt = setTimeout(function() { toast.style.bottom = '-80px'; }, 3000);
+  }
+  overlay.addEventListener('mousedown', function(e) { e.stopPropagation(); e.preventDefault(); _warn(); }, true);
+  overlay.addEventListener('mouseup', function(e) { e.stopPropagation(); e.preventDefault(); }, true);
+  overlay.addEventListener('click', function(e) { e.stopPropagation(); e.preventDefault(); _warn(); }, true);
+  overlay.addEventListener('dblclick', function(e) { e.stopPropagation(); e.preventDefault(); }, true);
+  overlay.addEventListener('contextmenu', function(e) { e.stopPropagation(); e.preventDefault(); }, true);
+  overlay.addEventListener('wheel', function(e) { e.stopPropagation(); e.preventDefault(); }, {capture:true, passive:false});
   document.addEventListener('keydown', function _cb(e) {
-    if (!document.getElementById('cdpilot-input-blocker')) {
-      document.removeEventListener('keydown', _cb, true);
-      return;
-    }
-    e.stopPropagation(); e.preventDefault();
+    if (!document.getElementById('cdpilot-input-blocker')) { document.removeEventListener('keydown', _cb, true); return; }
+    e.stopPropagation(); e.preventDefault(); _warn();
   }, true);
   document.addEventListener('keyup', function _cb(e) {
-    if (!document.getElementById('cdpilot-input-blocker')) {
-      document.removeEventListener('keyup', _cb, true);
-      return;
-    }
+    if (!document.getElementById('cdpilot-input-blocker')) { document.removeEventListener('keyup', _cb, true); return; }
     e.stopPropagation(); e.preventDefault();
   }, true);
   document.addEventListener('keypress', function _cb(e) {
-    if (!document.getElementById('cdpilot-input-blocker')) {
-      document.removeEventListener('keypress', _cb, true);
-      return;
-    }
+    if (!document.getElementById('cdpilot-input-blocker')) { document.removeEventListener('keypress', _cb, true); return; }
     e.stopPropagation(); e.preventDefault();
   }, true);
   document.body.appendChild(overlay);
@@ -172,56 +413,207 @@ INPUT_BLOCKER_ON = """
 
 INPUT_BLOCKER_OFF = """
 (function() {
-  const el = document.getElementById('cdpilot-input-blocker');
-  if (el) { el.remove(); return 'input blocker off'; }
-  return 'blocker already off';
+  var el = document.getElementById('cdpilot-input-blocker');
+  if (el) el.remove();
+  var toast = document.getElementById('cdpilot-warning-toast');
+  if (toast) toast.remove();
+  return el ? 'input blocker off' : 'blocker already off';
 })()
 """
 
-# ─── Automation Indicator Wrapper ───
+# ─── Visual Feedback System (cursor, ripple, keystroke) ───
 
-_glow_script_id = None  # addScriptToEvaluateOnNewDocument identifier
+VISUAL_FEEDBACK_JS = """
+(function() {
+  if (window.__cdpilot_vfx) return 'vfx already active';
+  var style = document.createElement('style');
+  style.id = 'cdpilot-vfx-style';
+  style.textContent = `
+    @keyframes cdpilot-ripple-anim {
+      0% { transform: translate(-50%,-50%) scale(0); opacity: 1; }
+      100% { transform: translate(-50%,-50%) scale(1); opacity: 0; }
+    }
+    .cdpilot-ripple {
+      position: fixed; width: 50px; height: 50px;
+      border: 2.5px solid #22c55e; border-radius: 50%;
+      pointer-events: none; z-index: 2147483647;
+      animation: cdpilot-ripple-anim 0.6s ease-out forwards;
+      box-shadow: 0 0 12px rgba(34,197,94,0.4);
+    }
+    .cdpilot-ripple-inner {
+      position: fixed; width: 8px; height: 8px;
+      background: #22c55e; border-radius: 50%;
+      pointer-events: none; z-index: 2147483647;
+      transform: translate(-50%,-50%);
+      opacity: 0.8;
+      animation: cdpilot-ripple-anim 0.4s ease-out 0.1s forwards;
+    }
+    #cdpilot-cursor {
+      position: fixed; pointer-events: none; z-index: 2147483647;
+      transition: left 0.2s cubic-bezier(0.25,0.8,0.25,1), top 0.2s cubic-bezier(0.25,0.8,0.25,1);
+      filter: drop-shadow(0 0 4px rgba(34,197,94,0.6));
+    }
+    #cdpilot-keystroke {
+      position: fixed; bottom: 80px; left: 50%;
+      transform: translateX(-50%);
+      background: rgba(0,0,0,0.88); color: #22c55e;
+      padding: 10px 20px; border-radius: 8px;
+      font: 700 15px/1.4 'SF Mono',Monaco,Menlo,monospace;
+      pointer-events: none; z-index: 2147483647;
+      border: 1px solid rgba(34,197,94,0.4);
+      box-shadow: 0 4px 20px rgba(0,0,0,0.4), 0 0 15px rgba(34,197,94,0.1);
+      opacity: 0; transition: opacity 0.3s ease;
+      backdrop-filter: blur(8px);
+    }
+  `;
+  document.head.appendChild(style);
+  var cursor = document.createElement('div');
+  cursor.id = 'cdpilot-cursor';
+  cursor.style.display = 'none';
+  cursor.innerHTML = '<svg width="24" height="24" viewBox="0 0 24 24" fill="none"><path d="M5.5 3.21V20.8l5.71-5.71h8.3L5.5 3.21z" fill="#22c55e" stroke="#15803d" stroke-width="1.2"/></svg>';
+  document.body.appendChild(cursor);
+  var ks = document.createElement('div');
+  ks.id = 'cdpilot-keystroke';
+  document.body.appendChild(ks);
+  window.__cdpilot_vfx = {
+    ripple: function(x, y) {
+      var el = document.createElement('div');
+      el.className = 'cdpilot-ripple';
+      el.style.left = x + 'px'; el.style.top = y + 'px';
+      document.body.appendChild(el);
+      var inner = document.createElement('div');
+      inner.className = 'cdpilot-ripple-inner';
+      inner.style.left = x + 'px'; inner.style.top = y + 'px';
+      document.body.appendChild(inner);
+      setTimeout(function() { el.remove(); inner.remove(); }, 700);
+    },
+    moveCursor: function(x, y) {
+      cursor.style.display = 'block';
+      cursor.style.left = (x - 3) + 'px';
+      cursor.style.top = (y - 2) + 'px';
+    },
+    hideCursor: function() { cursor.style.display = 'none'; },
+    keystroke: function(text) {
+      ks.textContent = text;
+      ks.style.opacity = '1';
+      clearTimeout(ks.__tid);
+      ks.__tid = setTimeout(function() { ks.style.opacity = '0'; }, 2000);
+    }
+  };
+  return 'vfx active';
+})()
+"""
 
-GLOW_ACTIVATE_JS = "document.documentElement.dataset.cdpilotActive = 'true';"
-GLOW_DEACTIVATE_JS = """
-document.documentElement.removeAttribute('data-cdpilot-active');
-var _go = document.getElementById('cdpilot-glow-overlay');
-var _gs = document.getElementById('cdpilot-glow-style');
-if (_go) _go.remove();
-if (_gs) _gs.remove();
+VISUAL_FEEDBACK_OFF = """
+(function() {
+  delete window.__cdpilot_vfx;
+  ['cdpilot-vfx-style','cdpilot-cursor','cdpilot-keystroke'].forEach(function(id) {
+    var el = document.getElementById(id); if (el) el.remove();
+  });
+  document.querySelectorAll('.cdpilot-ripple,.cdpilot-ripple-inner').forEach(function(el) { el.remove(); });
+  return 'vfx off';
+})()
+"""
+
+# ─── Glow Auto-Timeout (fade out after 10s idle) ───
+
+GLOW_TIMEOUT_JS = """
+clearTimeout(window.__cdpilot_glow_timeout);
+window.__cdpilot_glow_timeout = setTimeout(function() {
+  var o = document.getElementById('cdpilot-glow-overlay');
+  if (o) { o.style.opacity = '0'; setTimeout(function() { o.remove(); }, 1000); }
+  var s = document.getElementById('cdpilot-glow-style');
+  if (s) setTimeout(function() { s.remove(); }, 1100);
+  var t = document.getElementById('cdpilot-ai-toast');
+  if (t) t.remove();
+  if (window.__cdpilot_warn) {
+    document.removeEventListener('mousemove', window.__cdpilot_warn, true);
+    delete window.__cdpilot_warn;
+  }
+  ['cdpilot-vfx-style','cdpilot-cursor','cdpilot-keystroke'].forEach(function(id) {
+    var el = document.getElementById(id); if (el) el.remove();
+  });
+  delete window.__cdpilot_vfx;
+}, 10000);
 """
 
+# ─── Automation Indicator Wrapper ───
+
+_glow_script_id = None  # addScriptToEvaluateOnNewDocument identifier
+
 async def _control_start(ws_url):
-    """Enable visual indicator and input blocker at command start."""
+    """Enable glow, input blocker, and visual feedback at command start."""
     global _glow_script_id
     try:
-        # Inject activation marker on every new page load
-        r = await cdp_send(ws_url, [
-            (901, "Page.addScriptToEvaluateOnNewDocument", {"source": GLOW_ACTIVATE_JS}),
-            (902, "Runtime.evaluate", {"expression": GLOW_ACTIVATE_JS, "returnByValue": True}),
-            (903, "Runtime.evaluate", {"expression": INPUT_BLOCKER_ON, "returnByValue": True}),
+        # Remove previous persistent script if exists (prevent accumulation)
+        cmds = []
+        if _glow_script_id:
+            cmds.append((900, "Page.removeScriptToEvaluateOnNewDocument", {"identifier": _glow_script_id}))
+            _glow_script_id = None
+        persistent_source = GLOW_CSS + "\n" + VISUAL_FEEDBACK_JS
+        cmds.extend([
+            (901, "Page.addScriptToEvaluateOnNewDocument", {"source": persistent_source}),
+            (902, "Runtime.evaluate", {"expression": GLOW_CSS, "returnByValue": True}),
+            (903, "Runtime.evaluate", {"expression": VISUAL_FEEDBACK_JS, "returnByValue": True}),
+            (904, "Runtime.evaluate", {"expression": INPUT_BLOCKER_ON, "returnByValue": True}),
         ])
-        # Save script identifier for cleanup
-        if 901 in r and "identifier" in r.get(901, {}):
-            _glow_script_id = r[901]["identifier"]
+        r = await cdp_send(ws_url, cmds)
+        resp_901 = r.get(901, {})
+        result = resp_901.get("result", {})
+        if isinstance(result, dict) and "identifier" in result:
+            _glow_script_id = result["identifier"]
     except Exception:
-        pass  # Silent fail if no connection
+        pass
 
 async def _control_end(ws_url):
-    """Disable visual indicator and input blocker at command end."""
+    """Remove input blocker, keep glow alive.
+
+    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:
         cmds = [
-            (903, "Runtime.evaluate", {"expression": GLOW_DEACTIVATE_JS, "returnByValue": True}),
-            (904, "Runtime.evaluate", {"expression": INPUT_BLOCKER_OFF, "returnByValue": True}),
+            (903, "Runtime.evaluate", {"expression": INPUT_BLOCKER_OFF, "returnByValue": True}),
+            # 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}),
         ]
-        # Remove the persistent new-document script
-        if _glow_script_id:
-            cmds.append((905, "Page.removeScriptToEvaluateOnNewDocument", {"identifier": _glow_script_id}))
-            _glow_script_id = None
+        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:
-        pass  # Silent fail if no connection
+        pass
+
+async def _vfx_ripple(ws_url, x, y):
+    """Show click ripple + move cursor at (x, y)."""
+    js = f"if(window.__cdpilot_vfx){{window.__cdpilot_vfx.moveCursor({x},{y});window.__cdpilot_vfx.ripple({x},{y});}}"
+    try:
+        await cdp_send(ws_url, [(999, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    except Exception:
+        pass
+
+async def _vfx_keystroke(ws_url, text):
+    """Show keystroke display."""
+    safe = json.dumps(text)
+    js = f"if(window.__cdpilot_vfx){{window.__cdpilot_vfx.keystroke({safe});}}"
+    try:
+        await cdp_send(ws_url, [(999, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    except Exception:
+        pass
+
+async def _vfx_move_cursor(ws_url, x, y):
+    """Move fake cursor to (x, y)."""
+    js = f"if(window.__cdpilot_vfx){{window.__cdpilot_vfx.moveCursor({x},{y});}}"
+    try:
+        await cdp_send(ws_url, [(999, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    except Exception:
+        pass
 
 # ─── Connection Helpers ───
 
@@ -421,22 +813,32 @@ async def cdp_send(ws_url, commands, timeout=15):
     """Send multiple CDP commands and collect results."""
     import websockets
     results = {}
-    async with websockets.connect(ws_url, max_size=100 * 1024 * 1024) as ws:
-        for cmd_id, method, params in commands:
-            await ws.send(json.dumps({"id": cmd_id, "method": method, "params": params or {}}))
+    try:
+        async with websockets.connect(ws_url, max_size=100 * 1024 * 1024) as ws:
+            for cmd_id, method, params in commands:
+                await ws.send(json.dumps({"id": cmd_id, "method": method, "params": params or {}}))
 
-        pending = {c[0] for c in commands}
-        start = time.time()
-        while pending and (time.time() - start) < timeout:
-            try:
-                resp = await asyncio.wait_for(ws.recv(), timeout=2)
-                data = json.loads(resp)
-                if "id" in data and data["id"] in pending:
-                    pending.discard(data["id"])
-                    results[data["id"]] = data.get("result", data.get("error", {}))
-            except asyncio.TimeoutError:
-                continue
-    return results
+            pending = {c[0] for c in commands}
+            start = time.time()
+            while pending and (time.time() - start) < timeout:
+                try:
+                    resp = await asyncio.wait_for(ws.recv(), timeout=2)
+                    data = json.loads(resp)
+                    if "id" in data and data["id"] in pending:
+                        pending.discard(data["id"])
+                        results[data["id"]] = data.get("result", data.get("error", {}))
+                except asyncio.TimeoutError:
+                    continue
+        return results
+    except ConnectionRefusedError:
+        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)
+            sys.exit(1)
+        raise
 
 
 async def navigate_collect(ws_url, url, network=False, console=False, glow=True):
@@ -495,11 +897,16 @@ async def navigate_collect(ws_url, url, network=False, console=False, glow=True)
                 if loaded:
                     break
 
-        # Inject visual indicator (sets data-cdpilot-active attribute)
+        # Inject visual indicator (glow overlay + visual feedback)
         if glow:
             await ws.send(json.dumps({
                 "id": 200, "method": "Runtime.evaluate",
-                "params": {"expression": GLOW_ACTIVATE_JS, "returnByValue": True}
+                "params": {"expression": GLOW_CSS, "returnByValue": True}
+            }))
+            sid += 1
+            await ws.send(json.dumps({
+                "id": sid, "method": "Runtime.evaluate",
+                "params": {"expression": VISUAL_FEEDBACK_JS, "returnByValue": True}
             }))
 
         # Inject dev extension content scripts via the existing WS connection
@@ -556,6 +963,49 @@ async def navigate_collect(ws_url, url, network=False, console=False, glow=True)
 
 # ─── Helper Functions ───
 
+def _find_browser():
+    """İşletim sistemine göre tarayıcı ikili dosyasını otomatik olarak bulur."""
+    for b in ["brave-browser", "google-chrome", "chromium-browser", "chromium"]:
+        found = shutil.which(b)
+        if found:
+            return found
+
+    system = platform.system()
+    if system == "Darwin":
+        paths = [
+            "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        ]
+    elif system == "Linux":
+        paths = [
+            "/usr/bin/brave-browser",
+            "/usr/bin/google-chrome",
+            "/usr/bin/chromium-browser",
+            "/usr/bin/chromium",
+            "/snap/bin/chromium",
+        ]
+    elif system == "Windows":
+        paths = [
+            os.path.expandvars(r"C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"),
+            os.path.expandvars(r"C:\Program Files\Google\Chrome\Application\chrome.exe"),
+            os.path.expandvars(r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe"),
+            os.path.expandvars(r"C:\Program Files\Chromium\Application\chromium.exe"),
+        ]
+    else:
+        return None
+
+    for path in paths:
+        if os.path.exists(path):
+            return path
+    return None
+
+
+def _is_port_in_use(port):
+    """Check if a port is actively in use."""
+    return not _is_port_free(port)
+
+
 def get_dev_extensions():
     """Read registered dev mode extension paths."""
     if os.path.exists(DEV_EXTENSIONS_FILE):
@@ -741,17 +1191,34 @@ def get_headless_config():
 
 def cmd_launch():
     """Launch the browser with CDP enabled (isolated session — does not touch existing browser)."""
+    global CHROME_BIN, CDP_PORT, CDP_BASE
     if cdp_get('/json/version'):
-        print(f'Browser already running on port {CDP_PORT}.')
+        proj_label = f' [{PROJECT_ID}]' if PROJECT_ID else ''
+        print(f'Browser already running on port {CDP_PORT}{proj_label}.')
         return
+    if _is_port_in_use(CDP_PORT):
+        if PROJECT_ID:
+            # Auto-allocate a new port
+            new_port = _allocate_port(PROJECT_ID)
+            print(f'Port {CDP_PORT} busy, using {new_port}.')
+            CDP_PORT = new_port
+            CDP_BASE = f"http://127.0.0.1:{CDP_PORT}"
+        else:
+            print(f'Error: Port {CDP_PORT} is in use. Set CDP_PORT to a different port.', file=sys.stderr)
+            sys.exit(1)
 
     if not CHROME_BIN:
-        print('Error: CHROME_BIN is not set. Export CHROME_BIN=/path/to/browser.', file=sys.stderr)
-        sys.exit(1)
+        bin_path = _find_browser()
+        if not bin_path:
+            print('No supported browser found. Install Brave, Chrome, or Chromium and ensure it is in PATH or set CHROME_BIN.', file=sys.stderr)
+            sys.exit(1)
+        CHROME_BIN = bin_path
+        print(f'Browser found: {bin_path}')
 
     os.makedirs(PROFILE_DIR, exist_ok=True)
 
-    print(f'Launching browser (isolated session, port {CDP_PORT})...')
+    proj_label = f' [{PROJECT_ID}]' if PROJECT_ID else ''
+    print(f'Launching browser (isolated session, port {CDP_PORT}){proj_label}...')
 
     chrome_args = [
         CHROME_BIN,
@@ -816,12 +1283,15 @@ def cmd_launch():
         chrome_args.append('--headless=new')
         print('  Mode: headless')
 
-    subprocess.Popen(chrome_args, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+    proc = subprocess.Popen(chrome_args, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
 
     for _ in range(20):
         time.sleep(0.5)
         if cdp_get('/json/version'):
-            print(f'CDP ready! (port {CDP_PORT})')
+            if PROJECT_ID:
+                _register_project(PROJECT_ID, CDP_PORT, PROFILE_DIR, pid=proc.pid)
+            proj_label = f' [{PROJECT_ID}]' if PROJECT_ID else ''
+            print(f'CDP ready! (port {CDP_PORT}){proj_label}')
             return
     print('Failed to start CDP (timeout).', file=sys.stderr)
     sys.exit(1)
@@ -850,31 +1320,164 @@ async def cmd_go(url):
 async def cmd_content():
     ws, _ = get_page_ws()
     r = await cdp_send(ws, [(1, "Runtime.evaluate", {
-        "expression": "document.body.innerText.substring(0, 10000)",
+        "expression": "document.body.innerText.substring(0, 1048576)",
         "returnByValue": True,
     })])
-    print(r.get(1, {}).get("result", {}).get("value", "(empty)"))
+    content = r.get(1, {}).get("result", {}).get("value", "(empty)")
+    print(content)
+    if len(content) >= 1048576:
+        print("[Output truncated at 1MB]")
 
 
 async def cmd_html():
     ws, _ = get_page_ws()
     r = await cdp_send(ws, [(1, "Runtime.evaluate", {
-        "expression": "document.documentElement.outerHTML.substring(0, 30000)",
+        "expression": "document.documentElement.outerHTML.substring(0, 1048576)",
         "returnByValue": True,
     })])
-    print(r.get(1, {}).get("result", {}).get("value", "(empty)"))
+    html_content = r.get(1, {}).get("result", {}).get("value", "(empty)")
+    print(html_content)
+    if len(html_content) >= 1048576:
+        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(data)
+        size_kb = len(data) / 1024
+        print(f"{output} ({size_kb:.1f}KB)")
+    else:
+        print("Screenshot failed", file=sys.stderr)
+
+
+async def cmd_shot_annotated(output=None):
+    """Etkileşimli elementler üzerine @N badge eklenmiş annotated screenshot al."""
+    if not output:
+        output = f"{SCREENSHOT_DIR}/screenshot-annotated.png"
+    ws_url, _ = get_page_ws()
+
+    # A11y tree'den etkileşimli node'ları topla
+    await cdp_send(ws_url, [
+        (0, "Accessibility.enable", {}),
+        (9, "DOM.enable", {}),
+    ])
+    res = await cdp_send(ws_url, [(1, "Accessibility.getFullAXTree", {})])
+    nodes = res.get(1, {}).get("nodes", [])
+
+    interactive_roles = {
+        "button", "link", "textbox", "textField", "combobox", "comboBox",
+        "checkbox", "radio", "menuitem", "menuItem", "searchbox", "searchBox",
+        "spinbutton", "spinButton", "switch", "tab", "slider",
+    }
+    targets = [
+        n for n in nodes
+        if not n.get("ignored")
+        and n.get("role", {}).get("value", "") in interactive_roles
+        and n.get("backendDOMNodeId")
+    ]
+
+    # Her node için ekran koordinatlarını al
+    badge_count = 0
+    inject_parts = []
+    for idx, node in enumerate(targets, start=1):
+        backend_id = node["backendDOMNodeId"]
+        res_b = await cdp_send(ws_url, [(11, "DOM.getBoxModel", {"backendNodeId": backend_id})])
+        model = res_b.get(11, {}).get("model")
+        if not model:
+            continue
+        content = model.get("content", model.get("border", []))
+        if len(content) < 8:
+            continue
+        left = int(content[0])
+        top = int(content[1])
+        width = int(content[2] - content[0])
+        height = int(content[5] - content[1])
+        if width == 0 or height == 0:
+            continue
+        label = json.dumps(f"@{idx}")
+        inject_parts.append(
+            f"(function(){{"
+            f"var b=document.createElement('span');"
+            f"b.textContent={label};"
+            f"b.setAttribute('data-cdpilot-badge','1');"
+            f"b.style.cssText='position:fixed;left:{left}px;top:{top}px;"
+            f"background:#22c55e;color:#fff;font-size:11px;font-weight:bold;"
+            f"padding:1px 4px;border-radius:3px;z-index:99999;"
+            f"pointer-events:none;line-height:1.4;';"
+            f"document.body.appendChild(b);"
+            f"}})();"
+        )
+        badge_count += 1
+
+    # Badge'leri inject et
+    if inject_parts:
+        inject_js = "\n".join(inject_parts)
+        await cdp_send(ws_url, [(20, "Runtime.evaluate", {"expression": inject_js})])
+
+    # Screenshot al
+    r = await cdp_send(ws_url, [(21, "Page.captureScreenshot", {"format": "png", "captureBeyondViewport": False})])
+    b64 = r.get(21, {}).get("data", "")
+
+    # Badge'leri temizle
+    await cdp_send(ws_url, [(22, "Runtime.evaluate", {
+        "expression": "document.querySelectorAll('[data-cdpilot-badge]').forEach(function(e){e.remove();})"
+    })])
+
     if b64:
         with open(output, "wb") as f:
             f.write(base64.b64decode(b64))
-        print(f"{output}")
+        print(f"{output} ({badge_count} badge)")
     else:
         print("Screenshot failed", file=sys.stderr)
 
@@ -904,35 +1507,54 @@ async def cmd_eval(js_code):
 async def cmd_click(selector):
     ws, _ = get_page_ws()
     safe_sel = json.dumps(selector)
-    js = f"""(function() {{
-        const el = document.querySelector({safe_sel});
-        if (!el) return 'Not found: ' + {safe_sel};
+    js = WAIT_AND_QUERY_JS + f"""
+(function() {{
+    return window.__cdpilot_waitFor({safe_sel}, 5000).then(function(el) {{
+        if (!el) return 'Timeout waiting for: ' + {safe_sel};
         el.scrollIntoView({{behavior:'smooth', block:'center'}});
+        if (window.__cdpilot_vfx) {{
+            var r = el.getBoundingClientRect();
+            var cx = Math.round(r.left + r.width/2), cy = Math.round(r.top + r.height/2);
+            window.__cdpilot_vfx.moveCursor(cx, cy);
+            window.__cdpilot_vfx.ripple(cx, cy);
+        }}
         el.click();
         return 'Clicked: ' + el.tagName + ' ' + (el.textContent || '').substring(0, 60).trim();
-    }})()"""
-    r = await cdp_send(ws, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    }});
+}})()"""
+    r = await cdp_send(ws, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True, "awaitPromise": True})])
     print(r.get(1, {}).get("result", {}).get("value", "?"))
 
 
 async def cmd_fill(selector, value):
-    """Fill an input field (React/Vue compatible)."""
+    """Fill an input field with auto-wait (React/Vue compatible)."""
     ws, _ = get_page_ws()
     safe_sel = json.dumps(selector)
     safe_value = json.dumps(value)
-    js = f"""(function() {{
-        const el = document.querySelector({safe_sel});
-        if (!el) return 'Not found: ' + {safe_sel};
+    js = WAIT_AND_QUERY_JS + f"""
+(function() {{
+    return window.__cdpilot_waitFor({safe_sel}, 5000).then(function(el) {{
+        if (!el) return 'Timeout waiting for: ' + {safe_sel};
         el.focus();
-        const nativeSet = Object.getOwnPropertyDescriptor(
+        if (window.__cdpilot_vfx) {{
+            var r = el.getBoundingClientRect();
+            window.__cdpilot_vfx.moveCursor(Math.round(r.left + r.width/2), Math.round(r.top + r.height/2));
+            window.__cdpilot_vfx.keystroke('\\u2328 ' + {safe_value}.substring(0, 30));
+        }}
+        var nativeSet = Object.getOwnPropertyDescriptor(
             window.HTMLInputElement.prototype, 'value'
-        ).set;
-        nativeSet.call(el, {safe_value});
+        );
+        if (nativeSet && nativeSet.set) {{
+            nativeSet.set.call(el, {safe_value});
+        }} else {{
+            el.value = {safe_value};
+        }}
         el.dispatchEvent(new Event('input', {{bubbles: true}}));
         el.dispatchEvent(new Event('change', {{bubbles: true}}));
         return 'Filled: ' + el.tagName + ' = ' + el.value.substring(0, 50);
-    }})()"""
-    r = await cdp_send(ws, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    }});
+}})()"""
+    r = await cdp_send(ws, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True, "awaitPromise": True})])
     print(r.get(1, {}).get("result", {}).get("value", "?"))
 
 
@@ -968,6 +1590,55 @@ async def cmd_wait(selector, timeout=5):
     print(r.get(1, {}).get("result", {}).get("value", "?"))
 
 
+async def cmd_batch():
+    """stdin'den JSON komut dizisi oku, sırayla çalıştır, sonuçları JSON olarak yaz.
+
+    Kullanım:
+      echo '[{"cmd":"go","args":["https://example.com"]},{"cmd":"shot","args":["/tmp/out.png"]}]' | cdpilot batch
+    """
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw)
+        if not isinstance(data, list):
+            print(json.dumps({"error": "Input must be a JSON array"}), file=sys.stderr)
+            sys.exit(1)
+    except json.JSONDecodeError as exc:
+        print(json.dumps({"error": f"JSON parse error: {exc}"}), file=sys.stderr)
+        sys.exit(1)
+
+    results = []
+    for item in data:
+        cmd_name = item.get("cmd", "")
+        cmd_args = item.get("args", [])
+        try:
+            if cmd_name == "go":
+                await cmd_go(cmd_args[0] if cmd_args else "")
+            elif cmd_name == "click":
+                await cmd_click(cmd_args[0] if cmd_args else "")
+            elif cmd_name in ("fill", "type"):
+                await cmd_fill(cmd_args[0] if cmd_args else "", cmd_args[1] if len(cmd_args) > 1 else "")
+            elif cmd_name == "shot":
+                await cmd_shot(cmd_args[0] if cmd_args else None)
+            elif cmd_name == "shot-annotated":
+                await cmd_shot_annotated(cmd_args[0] if cmd_args else None)
+            elif cmd_name == "wait":
+                await cmd_wait(cmd_args[0] if cmd_args else "body", int(cmd_args[1]) if len(cmd_args) > 1 else 5)
+            elif cmd_name == "eval":
+                await cmd_eval(" ".join(cmd_args) if cmd_args else "")
+            elif cmd_name == "submit":
+                await cmd_submit(cmd_args[0] if cmd_args else "form")
+            else:
+                results.append({"cmd": cmd_name, "status": "error", "error": f"Unsupported command: {cmd_name}"})
+                continue
+            results.append({"cmd": cmd_name, "status": "ok"})
+        except SystemExit:
+            results.append({"cmd": cmd_name, "status": "error", "error": "Command exited with error"})
+        except Exception as exc:
+            results.append({"cmd": cmd_name, "status": "error", "error": str(exc)})
+
+    print(json.dumps(results, indent=2, ensure_ascii=False))
+
+
 async def cmd_network(url=None):
     ws, page = get_page_ws()
     if url is None:
@@ -1080,8 +1751,16 @@ async def cmd_emulate(device):
 
 async def cmd_glow(state="on"):
     ws, page = get_page_ws()
-    js = GLOW_ACTIVATE_JS if state == "on" else GLOW_DEACTIVATE_JS
-    r = await cdp_send(ws, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
+    if state == "on":
+        await cdp_send(ws, [
+            (1, "Runtime.evaluate", {"expression": GLOW_CSS, "returnByValue": True}),
+            (2, "Runtime.evaluate", {"expression": VISUAL_FEEDBACK_JS, "returnByValue": True}),
+        ])
+    else:
+        await cdp_send(ws, [
+            (1, "Runtime.evaluate", {"expression": GLOW_OFF_CSS, "returnByValue": True}),
+            (2, "Runtime.evaluate", {"expression": VISUAL_FEEDBACK_OFF, "returnByValue": True}),
+        ])
     print(f"Visual indicator {'on' if state == 'on' else 'off'}")
 
 
@@ -1412,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", "?")}')
@@ -1617,29 +2297,160 @@ def cmd_headless(state=None):
     print('Restart browser (stop → launch).')
 
 
+def _stop_browser_on_port(port):
+    """Stop the browser process listening on the given port."""
+    import signal
+    try:
+        result = subprocess.run(
+            ["lsof", "-ti", f":{port}"],
+            capture_output=True, text=True
+        )
+        pids = [p.strip() for p in result.stdout.strip().split("\n") if p.strip()]
+        if pids:
+            for pid in pids:
+                os.kill(int(pid), signal.SIGTERM)
+            return True
+        else:
+            subprocess.run(
+                ["pkill", "-f", f"remote-debugging-port={port}"],
+                capture_output=True, text=True
+            )
+            return True
+    except Exception:
+        return False
+
+
 def cmd_stop():
     """Stop the browser instance managed by cdpilot."""
+    if platform.system() == "Windows":
+        browser_procs = ["brave.exe", "chrome.exe", "chromium.exe"]
+        stopped_any = False
+        for proc in browser_procs:
+            try:
+                result = subprocess.run(
+                    ["taskkill", "/F", "/IM", proc],
+                    capture_output=True, text=True
+                )
+                if result.returncode == 0:
+                    print(f"  {proc} terminated")
+                    stopped_any = True
+            except Exception:
+                pass
+        if stopped_any:
+            print(f"Browser stopped (port {CDP_PORT}).")
+        else:
+            print(f"No browser process found (port {CDP_PORT}).", file=sys.stderr)
+        return
+
     import signal
     try:
         result = subprocess.run(
             ["lsof", "-ti", f":{CDP_PORT}"],
             capture_output=True, text=True
         )
-        pids = result.stdout.strip().split("\n")
-        for pid in pids:
-            if pid.strip():
-                os.kill(int(pid.strip()), signal.SIGTERM)
-                print(f"  PID {pid.strip()} terminated")
-        print(f"Browser stopped (port {CDP_PORT}).")
+        pids = [p.strip() for p in result.stdout.strip().split("\n") if p.strip()]
+        if pids:
+            for pid in pids:
+                os.kill(int(pid), signal.SIGTERM)
+                print(f"  PID {pid} terminated")
+            print(f"Browser stopped (port {CDP_PORT}).")
+        else:
+            # lsof bulamazsa pkill ile dene
+            subprocess.run(
+                ["pkill", "-f", f"remote-debugging-port={CDP_PORT}"],
+                capture_output=True, text=True
+            )
+            print(f"Browser stopped (port {CDP_PORT}).")
     except Exception as e:
         print(f"Stop error: {e}", file=sys.stderr)
 
+    # Update registry
+    if PROJECT_ID:
+        registry = _load_registry()
+        if PROJECT_ID in registry:
+            registry[PROJECT_ID]["status"] = "stopped"
+            registry[PROJECT_ID]["pid"] = None
+            _save_registry(registry)
+
 
 def cmd_version():
     """Show cdpilot version."""
     print(f"cdpilot v{__version__}")
 
 
+def cmd_projects():
+    """List all registered cdpilot project instances."""
+    registry = _cleanup_registry()
+    if not registry:
+        print("No registered projects.")
+        return
+
+    current = PROJECT_ID
+    print(f"{'Project':<28} {'Port':<7} {'Status':<10} {'CWD'}")
+    print("\u2500" * 90)
+
+    for pid, info in sorted(registry.items(),
+                            key=lambda x: x[1].get("last_used", ""), reverse=True):
+        port = info.get("port", "?")
+        status = info.get("status", "?")
+        cwd = info.get("cwd", "?")
+        # Live check
+        if status == "running" and _is_port_free(port):
+            status = "stopped"
+        icon = "\U0001f7e2" if status == "running" else "\u26ab"
+        marker = " \u2190 current" if pid == current else ""
+        if len(cwd) > 45:
+            cwd = "..." + cwd[-42:]
+        print(f"  {pid:<26} {port:<7} {icon} {status:<8} {cwd}{marker}")
+
+    print(f"\nTotal: {len(registry)} project(s)")
+
+
+def cmd_project_stop(name):
+    """Stop a specific project's browser instance."""
+    registry = _load_registry()
+    target_id = None
+    for pid, info in registry.items():
+        if name in pid or name in info.get("cwd", ""):
+            target_id = pid
+            break
+
+    if not target_id:
+        print(f"Project not found: {name}", file=sys.stderr)
+        sys.exit(1)
+
+    info = registry[target_id]
+    port = info.get("port")
+    if port and not _is_port_free(port):
+        _stop_browser_on_port(port)
+        print(f"Stopped: {target_id} (port {port})")
+    else:
+        print(f"Project already stopped: {target_id}")
+
+    info["status"] = "stopped"
+    info["pid"] = None
+    _save_registry(registry)
+
+
+def cmd_stop_all():
+    """Stop all active cdpilot browser instances."""
+    registry = _cleanup_registry()
+    stopped = 0
+    for pid, info in registry.items():
+        port = info.get("port")
+        if port and info.get("status") == "running" and not _is_port_free(port):
+            _stop_browser_on_port(port)
+            info["status"] = "stopped"
+            info["pid"] = None
+            stopped += 1
+            print(f"  Stopped: {pid} (port {port})")
+    _save_registry(registry)
+    if stopped:
+        print(f"\n{stopped} instance(s) stopped.")
+    else:
+        print("No active instances.")
+
+
 # ─── New CDP Commands ───
 
 async def _get_element_center(ws_url, selector):
@@ -1858,12 +2669,604 @@ async def cmd_a11y(subcmd=""):
         sys.exit(1)
 
 
+async def cmd_describe():
+    """Full page description for AI agents — structured data + screenshot fallback.
+
+    Outputs URL/title, accessibility snapshot, screenshot path, and text content.
+    AI agents can use the a11y snapshot for cheap navigation; fall back to the
+    screenshot with a vision model when the snapshot is insufficient (canvas, WebGL).
+    """
+    global _A11Y_REF_MAP
+    _A11Y_REF_MAP = {}
+    ws_url, page = get_page_ws()
+
+    print("=== Page Description ===")
+    print(f"URL: {page.get('url', 'N/A')}")
+    print(f"Title: {page.get('title', 'N/A')}")
+    print()
+
+    # ── Accessibility Snapshot ──────────────────────────────────────────────
+    print("=== Accessibility Snapshot ===")
+
+    ROLE_NORMALIZE = {
+        "textField": "textbox",
+        "comboBox": "combobox",
+        "checkBox": "checkbox",
+        "radioButton": "radio",
+    }
+
+    SKIP_ROLES = {
+        "none", "presentation", "generic", "LineBreak", "InlineTextBox",
+        "ignored", "unknown"
+    }
+
+    INTERACTIVE_ROLES = {
+        "button", "link", "textbox", "checkbox", "radio", "combobox", "listbox",
+        "menuitem", "menuitemcheckbox", "menuitemradio", "option", "spinbutton",
+        "slider", "switch", "tab", "treeitem"
+    }
+
+    STRUCTURAL_ROLES = {
+        "heading", "img", "navigation", "menu", "list", "listitem", "table",
+        "grid", "row", "cell", "columnheader", "rowheader", "dialog", "alert",
+        "main", "banner", "contentinfo", "region", "figure", "article", "section"
+    }
+
+    def _get_prop(node, prop_name):
+        for p in node.get("properties", []):
+            if p.get("name") == prop_name:
+                return p.get("value", {}).get("value", "")
+        return ""
+
+    await cdp_send(ws_url, [(0, "Accessibility.enable", {})])
+    res = await cdp_send(ws_url, [(1, "Accessibility.getFullAXTree", {})])
+    nodes = res.get(1, {}).get("nodes", [])
+
+    if not nodes:
+        print("Could not get accessibility tree.", file=sys.stderr)
+
+    ref_count = 0
+    interactive_count = 0
+    output_lines = []
+
+    for node in nodes:
+        backend_node_id = node.get("backendDOMNodeId") or node.get("backendNodeId")
+        role = node.get("role", {}).get("value")
+        name = node.get("name", {}).get("value")
+        description = node.get("description", {}).get("value")
+        ignored = node.get("ignored", False)
+
+        if ignored:
+            continue
+        if not role or role in SKIP_ROLES:
+            continue
+        if not backend_node_id:
+            continue
+        if not name and not description and role in {"staticText", "text", "paragraph"}:
+            continue
+
+        normalized = ROLE_NORMALIZE.get(role, role)
+
+        if normalized == "heading":
+            level = _get_prop(node, "level")
+            if level:
+                normalized = f"heading/{level}"
+
+        base_role = normalized.split("/")[0]
+        is_interactive = base_role in INTERACTIVE_ROLES
+        is_structural = base_role in STRUCTURAL_ROLES
+
+        if not (is_interactive or (is_structural and (name or description))):
+            continue
+
+        ref_count += 1
+        _A11Y_REF_MAP[ref_count] = backend_node_id
+
+        if is_interactive:
+            interactive_count += 1
+
+        display_name = name or description or ""
+        attrs = []
+
+        if base_role == "link":
+            href = _get_prop(node, "url")
+            if href:
+                attrs.append(f"href={href}")
+
+        if _get_prop(node, "disabled") == "true":
+            attrs.append("disabled")
+
+        if _get_prop(node, "required") == "true":
+            attrs.append("required")
+
+        if base_role in {"textbox", "combobox"}:
+            val = _get_prop(node, "value")
+            if val:
+                attrs.append(f"value={val!r}")
+            ph = _get_prop(node, "placeholder")
+            if ph:
+                attrs.append(f"placeholder={ph!r}")
+
+        if base_role in {"checkbox", "radio"}:
+            if _get_prop(node, "checked") == "true":
+                attrs.append("checked")
+
+        if _get_prop(node, "expanded") == "true":
+            attrs.append("expanded")
+
+        attr_str = (" " + " ".join(attrs)) if attrs else ""
+        output_lines.append(f"@{ref_count} [{normalized}] \"{display_name}\"{attr_str}")
+
+    _save_a11y_refs(_A11Y_REF_MAP)
+
+    for line in output_lines:
+        print(line)
+    print(f"\n[{interactive_count} interactive, {ref_count} total shown]")
+    print()
+
+    # ── Screenshot ─────────────────────────────────────────────────────────
+    print("=== Screenshot ===")
+    ts = int(time.time())
+    shot_path = f"{SCREENSHOT_DIR}/cdpilot-describe-{ts}.png"
+    shot_res = await cdp_send(ws_url, [(2, "Page.captureScreenshot", {"format": "png", "captureBeyondViewport": False})])
+    shot_data = shot_res.get(2, {}).get("data")
+    if shot_data:
+        with open(shot_path, "wb") as f:
+            f.write(base64.b64decode(shot_data))
+        print(f"Saved: {shot_path}")
+    else:
+        print("Could not capture screenshot.", file=sys.stderr)
+    print()
+
+    # ── Text Content ────────────────────────────────────────────────────────
+    print("=== Page Content (first 2000 chars) ===")
+    eval_res = await cdp_send(ws_url, [(3, "Runtime.evaluate", {
+        "expression": "document.body ? document.body.innerText : ''",
+        "returnByValue": True
+    })])
+    page_text = eval_res.get(3, {}).get("result", {}).get("value", "")
+    print(page_text[:2000])
+
+
+# ─── 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.
+
+    Each line: @ref [role] "name" attributes...
+    Use 'click-ref @N' to click an element by its reference number.
+    """
+    global _A11Y_REF_MAP
+    _A11Y_REF_MAP = {}
+    ws_url, _ = get_page_ws()
+    await cdp_send(ws_url, [(0, "Accessibility.enable", {})])
+    res = await cdp_send(ws_url, [(1, "Accessibility.getFullAXTree", {})])
+    nodes = res.get(1, {}).get("nodes", [])
+    if not nodes:
+        print("Could not get accessibility tree.", file=sys.stderr)
+        sys.exit(1)
+
+    ROLE_NORMALIZE = {
+        "textField": "textbox",
+        "comboBox": "combobox",
+        "checkBox": "checkbox",
+        "radioButton": "radio",
+    }
+
+    SKIP_ROLES = {
+        "none", "presentation", "generic", "LineBreak", "InlineTextBox",
+        "ignored", "unknown"
+    }
+
+    INTERACTIVE_ROLES = {
+        "button", "link", "textbox", "checkbox", "radio", "combobox", "listbox",
+        "menuitem", "menuitemcheckbox", "menuitemradio", "option", "spinbutton",
+        "slider", "switch", "tab", "treeitem"
+    }
+
+    STRUCTURAL_ROLES = {
+        "heading", "img", "navigation", "menu", "list", "listitem", "table",
+        "grid", "row", "cell", "columnheader", "rowheader", "dialog", "alert",
+        "main", "banner", "contentinfo", "region", "figure", "article", "section"
+    }
+
+    def _get_prop(node, prop_name):
+        for p in node.get("properties", []):
+            if p.get("name") == prop_name:
+                return p.get("value", {}).get("value", "")
+        return ""
+
+    ref_count = 0
+    interactive_count = 0
+    output_lines = []
+
+    for node in nodes:
+        backend_node_id = node.get("backendDOMNodeId") or node.get("backendNodeId")
+        role = node.get("role", {}).get("value")
+        name = node.get("name", {}).get("value")
+        description = node.get("description", {}).get("value")
+        ignored = node.get("ignored", False)
+
+        if ignored:
+            continue
+        if not role or role in SKIP_ROLES:
+            continue
+        if not backend_node_id:
+            continue
+        if not name and not description and role in {"staticText", "text", "paragraph"}:
+            continue
+
+        normalized = ROLE_NORMALIZE.get(role, role)
+
+        # heading/N format
+        if normalized == "heading":
+            level = _get_prop(node, "level")
+            if level:
+                normalized = f"heading/{level}"
+
+        # Determine inclusion
+        base_role = normalized.split("/")[0]
+        is_interactive = base_role in INTERACTIVE_ROLES
+        is_structural = base_role in STRUCTURAL_ROLES
+        if not (is_interactive or (is_structural and (name or description))):
+            continue
+
+        display_name = name or description or ""
+
+        attrs = []
+
+        if base_role == "link":
+            href = _get_prop(node, "url")
+            if href:
+                attrs.append(f"href={href}")
+
+        if _get_prop(node, "disabled") == "true":
+            attrs.append("disabled")
+
+        if _get_prop(node, "required") == "true":
+            attrs.append("required")
+
+        if base_role in {"textbox", "combobox"}:
+            val = _get_prop(node, "value")
+            if val:
+                attrs.append(f"value={val!r}")
+            ph = _get_prop(node, "placeholder")
+            if ph:
+                attrs.append(f"placeholder={ph!r}")
+
+        if base_role in {"checkbox", "radio"}:
+            if _get_prop(node, "checked") == "true":
+                attrs.append("checked")
+
+        if _get_prop(node, "expanded") == "true":
+            attrs.append("expanded")
+
+        ref_count += 1
+        _A11Y_REF_MAP[ref_count] = backend_node_id
+
+        if is_interactive:
+            interactive_count += 1
+
+        attr_str = (" " + " ".join(attrs)) if attrs else ""
+        line = f"@{ref_count} [{normalized}] \"{display_name}\"{attr_str}"
+        output_lines.append(line)
+
+    _save_a11y_refs(_A11Y_REF_MAP)
+
+    for line in output_lines:
+        print(line)
+    print(f"\n[{interactive_count} interactive, {ref_count} total shown]")
+
+
+async def cmd_click_ref(ref_str):
+    """Click an element by its @N reference from the last a11y-snapshot."""
+    ws_url, _ = get_page_ws()
+
+    try:
+        ref_num = int(ref_str.lstrip("@"))
+    except ValueError:
+        print(f"Error: Invalid reference '{ref_str}'. Expected @N (e.g. @3).", file=sys.stderr)
+        sys.exit(1)
+
+    ref_map = _A11Y_REF_MAP or _load_a11y_refs()
+    backend_node_id = ref_map.get(ref_num)
+    if not backend_node_id:
+        print(f"Error: Reference '@{ref_num}' not found. Run 'a11y-snapshot' first.", file=sys.stderr)
+        sys.exit(1)
+
+    # Get element box model via backendNodeId directly
+    await cdp_send(ws_url, [(0, "DOM.enable", {})])
+    res1 = await cdp_send(ws_url, [(1, "DOM.getBoxModel", {"backendNodeId": backend_node_id})])
+    model = res1.get(1, {}).get("model")
+    if not model:
+        # Fallback: resolve to objectId and use JS
+        res_r = await cdp_send(ws_url, [(10, "DOM.resolveNode", {"backendNodeId": backend_node_id})])
+        oid = res_r.get(10, {}).get("object", {}).get("objectId")
+        if oid:
+            res_js = await cdp_send(ws_url, [(11, "Runtime.callFunctionOn", {
+                "functionDeclaration": "function(){var r=this.getBoundingClientRect();return{x:Math.round(r.left+r.width/2),y:Math.round(r.top+r.height/2)};}",
+                "objectId": oid, "returnByValue": True,
+            })])
+            val = res_js.get(11, {}).get("result", {}).get("value")
+            if val and "x" in val:
+                model = None  # skip box model path
+                x, y = val["x"], val["y"]
+    if model:
+        # content quad: [x1,y1, x2,y2, x3,y3, x4,y4]
+        content = model.get("content", model.get("border", []))
+        if len(content) >= 8:
+            x = int((content[0] + content[2] + content[4] + content[6]) / 4)
+            y = int((content[1] + content[3] + content[5] + content[7]) / 4)
+            val = {"x": x, "y": y}
+        else:
+            val = None
+    elif not model and 'x' not in dir():
+        val = None
+
+    if not val or "x" not in val:
+        print(f"Error: Could not get coordinates for @{ref_num}.", file=sys.stderr)
+        sys.exit(1)
+
+    x, y = val["x"], val["y"]
+    await _vfx_ripple(ws_url, x, y)
+    await cdp_send(ws_url, [
+        (3, "Input.dispatchMouseEvent", {
+            "type": "mousePressed", "x": x, "y": y, "button": "left", "clickCount": 1
+        }),
+        (4, "Input.dispatchMouseEvent", {
+            "type": "mouseReleased", "x": x, "y": y, "button": "left", "clickCount": 1
+        }),
+    ])
+    print(f"Clicked @{ref_num} (backendNodeId={backend_node_id}): ({x}, {y})")
+
+
 # ─── 3. Advanced Input Commands ───
 
 async def cmd_hover(selector):
     """Move the mouse cursor to the specified element."""
     ws_url, _ = get_page_ws()
     x, y = await _get_element_center(ws_url, selector)
+    await _vfx_move_cursor(ws_url, x, y)
     await cdp_send(ws_url, [(1, "Input.dispatchMouseEvent",
         {"type": "mouseMoved", "x": x, "y": y, "button": "none", "modifiers": 0})])
     print(f"Hover: {selector} ({x}, {y})")
@@ -1873,6 +3276,7 @@ async def cmd_dblclick(selector):
     """Double-click the specified element."""
     ws_url, _ = get_page_ws()
     x, y = await _get_element_center(ws_url, selector)
+    await _vfx_ripple(ws_url, x, y)
     cmds = [
         (1, "Input.dispatchMouseEvent", {"type": "mousePressed", "x": x, "y": y, "button": "left", "clickCount": 1}),
         (2, "Input.dispatchMouseEvent", {"type": "mouseReleased", "x": x, "y": y, "button": "left", "clickCount": 1}),
@@ -1887,6 +3291,7 @@ async def cmd_rightclick(selector):
     """Right-click the specified element."""
     ws_url, _ = get_page_ws()
     x, y = await _get_element_center(ws_url, selector)
+    await _vfx_ripple(ws_url, x, y)
     cmds = [
         (1, "Input.dispatchMouseEvent", {"type": "mousePressed", "x": x, "y": y, "button": "right", "clickCount": 1}),
         (2, "Input.dispatchMouseEvent", {"type": "mouseReleased", "x": x, "y": y, "button": "right", "clickCount": 1}),
@@ -1900,6 +3305,7 @@ async def cmd_drag(from_selector, to_selector):
     ws_url, _ = get_page_ws()
     fx, fy = await _get_element_center(ws_url, from_selector)
     tx, ty = await _get_element_center(ws_url, to_selector)
+    await _vfx_ripple(ws_url, fx, fy)
 
     import websockets
     async with websockets.connect(ws_url, max_size=100 * 1024 * 1024) as ws:
@@ -1913,6 +3319,7 @@ async def cmd_drag(from_selector, to_selector):
         for i in range(1, steps + 1):
             ix = int(fx + (tx - fx) * i / steps)
             iy = int(fy + (ty - fy) * i / steps)
+            await _vfx_move_cursor(ws_url, ix, iy)
             await send_mouse(10 + i, "mouseMoved", ix, iy)
             await asyncio.sleep(0.05)
         await send_mouse(20, "mouseReleased", tx, ty)
@@ -1957,6 +3364,7 @@ async def cmd_keys(combo):
         print("Error: specify a valid key (e.g. ctrl+a, enter, tab).", file=sys.stderr)
         sys.exit(1)
 
+    await _vfx_keystroke(ws_url, combo.upper())
     cmds = [
         (1, "Input.dispatchKeyEvent", {"type": "keyDown", "modifiers": modifiers,
             "key": key_name, "windowsVirtualKeyCode": key_code, "nativeVirtualKeyCode": key_code}),
@@ -2222,34 +3630,58 @@ 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_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):
@@ -2287,7 +3719,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"],
@@ -2300,15 +3732,29 @@ class MCPServer:
             "browser_fill": lambda a: ["fill", a.get("selector", ""), a.get("value", "")],
             "browser_launch": lambda a: ["launch"],
             "browser_close": lambda a: ["close"],
+            "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()
@@ -2373,6 +3819,9 @@ if __name__ == "__main__":
         'session': cmd_session,
         'sessions': cmd_sessions,
         'session-close': lambda: cmd_session_close(args[0] if args else None),
+        'projects': cmd_projects,
+        'project-stop': lambda: cmd_project_stop(args[0] if args else ''),
+        'stop-all': cmd_stop_all,
     }
 
     if cmd == "mcp":
@@ -2414,7 +3863,14 @@ 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)),
         "click": lambda: (require_args(1, "click <selector>"), None)[1] if not args else cmd_click(args[0]),
         "fill": lambda: (require_args(2, "fill <selector> <value>"), None)[1] if len(args) < 2 else cmd_fill(args[0], " ".join(args[1:])),
@@ -2438,6 +3894,20 @@ if __name__ == "__main__":
         'multi-eval': lambda: (require_args(1, 'multi-eval <js>'), None)[1] if not args else cmd_multi_eval(' '.join(args)),
         'intercept': lambda: (require_args(1, 'intercept [block|mock|headers|clear|list] ...'), None)[1] if not args else cmd_intercept(args[0], *args[1:]),
         'a11y': lambda: cmd_a11y(' '.join(args)),
+        'a11y-snapshot': cmd_a11y_snapshot,
+        'describe': cmd_describe,
+        '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]),
         'rightclick': lambda: (require_args(1, 'rightclick <selector>'), None)[1] if not args else cmd_rightclick(args[0]),
@@ -2454,7 +3924,8 @@ 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'}
+                       'dialog', 'download', 'throttle', 'permission', 'intercept',
+                       'batch', 'screenshot-diff'}
     # Clean up idle sessions before running any command
     _cleanup_idle_sessions()
 
@@ -2483,5 +3954,10 @@ if __name__ == "__main__":
             asyncio.run(_wrapped())
             _update_session_timestamp()
     else:
-        print(f"Unknown command: {cmd}")
-        print(__doc__)
+        print(f"Unknown command: {cmd}", file=sys.stderr)
+        all_cmds = sorted(set(list(sync_cmds.keys()) + list(async_map.keys())))
+        matches = difflib.get_close_matches(cmd, all_cmds, n=1, cutoff=0.6)
+        if matches:
+            print(f"Did you mean: {matches[0]}?", file=sys.stderr)
+        print(f"\nAvailable commands: {', '.join(all_cmds)}", file=sys.stderr)
+        sys.exit(1)