@hasna/browser 0.0.2 → 0.0.3

package/dist/cli/index.js

@@ -2525,6 +2525,336 @@ var init_selector = __esm(() => {
   };
 });
 
+// src/db/network-log.ts
+import { randomUUID as randomUUID2 } from "crypto";
+function logRequest(data) {
+  const db = getDatabase();
+  const id = randomUUID2();
+  db.prepare(`INSERT INTO network_log (id, session_id, method, url, status_code, request_headers,
+     response_headers, request_body, body_size, duration_ms, resource_type)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, data.session_id, data.method, data.url, data.status_code ?? null, data.request_headers ?? null, data.response_headers ?? null, data.request_body ?? null, data.body_size ?? null, data.duration_ms ?? null, data.resource_type ?? null);
+  return getNetworkRequest(id);
+}
+function getNetworkRequest(id) {
+  const db = getDatabase();
+  return db.query("SELECT * FROM network_log WHERE id = ?").get(id) ?? null;
+}
+function getNetworkLog(sessionId) {
+  const db = getDatabase();
+  return db.query("SELECT * FROM network_log WHERE session_id = ? ORDER BY timestamp ASC").all(sessionId);
+}
+function clearNetworkLog(sessionId) {
+  const db = getDatabase();
+  db.prepare("DELETE FROM network_log WHERE session_id = ?").run(sessionId);
+}
+var init_network_log = __esm(() => {
+  init_schema();
+});
+
+// src/lib/network.ts
+function enableNetworkLogging(page, sessionId) {
+  const requestStart = new Map;
+  const onRequest = (req) => {
+    requestStart.set(req.url(), Date.now());
+  };
+  const onResponse = (res) => {
+    const start = requestStart.get(res.url()) ?? Date.now();
+    const duration = Date.now() - start;
+    const req = res.request();
+    try {
+      logRequest({
+        session_id: sessionId,
+        method: req.method(),
+        url: res.url(),
+        status_code: res.status(),
+        request_headers: JSON.stringify(req.headers()),
+        response_headers: JSON.stringify(res.headers()),
+        body_size: res.headers()["content-length"] != null ? parseInt(res.headers()["content-length"]) : undefined,
+        duration_ms: duration,
+        resource_type: req.resourceType()
+      });
+    } catch {}
+  };
+  page.on("request", onRequest);
+  page.on("response", onResponse);
+  return () => {
+    page.off("request", onRequest);
+    page.off("response", onResponse);
+  };
+}
+async function addInterceptRule(page, rule) {
+  await page.route(rule.pattern, async (route) => {
+    if (rule.action === "block") {
+      await route.abort();
+    } else if (rule.action === "modify" && rule.response) {
+      await route.fulfill({
+        status: rule.response.status,
+        body: rule.response.body,
+        headers: rule.response.headers
+      });
+    } else {
+      await route.continue();
+    }
+  });
+}
+function startHAR(page) {
+  const entries = [];
+  const requestStart = new Map;
+  const onRequest = (req) => {
+    requestStart.set(req.url() + req.method(), {
+      time: Date.now(),
+      method: req.method(),
+      headers: req.headers(),
+      postData: req.postData() ?? undefined
+    });
+  };
+  const onResponse = async (res) => {
+    const key = res.url() + res.request().method();
+    const start = requestStart.get(key);
+    if (!start)
+      return;
+    const duration = Date.now() - start.time;
+    const entry = {
+      startedDateTime: new Date(start.time).toISOString(),
+      time: duration,
+      request: {
+        method: start.method,
+        url: res.url(),
+        headers: Object.entries(start.headers).map(([name, value]) => ({ name, value })),
+        postData: start.postData ? { text: start.postData } : undefined
+      },
+      response: {
+        status: res.status(),
+        statusText: res.statusText(),
+        headers: Object.entries(res.headers()).map(([name, value]) => ({ name, value })),
+        content: {
+          size: parseInt(res.headers()["content-length"] ?? "0") || 0,
+          mimeType: res.headers()["content-type"] ?? "application/octet-stream"
+        }
+      },
+      timings: { send: 0, wait: duration, receive: 0 }
+    };
+    entries.push(entry);
+    requestStart.delete(key);
+  };
+  page.on("request", onRequest);
+  page.on("response", onResponse);
+  return {
+    entries,
+    stop: () => {
+      page.off("request", onRequest);
+      page.off("response", onResponse);
+      return {
+        log: {
+          version: "1.2",
+          creator: { name: "@hasna/browser", version: "0.0.1" },
+          entries
+        }
+      };
+    }
+  };
+}
+var init_network = __esm(() => {
+  init_network_log();
+});
+
+// src/db/console-log.ts
+var exports_console_log = {};
+__export(exports_console_log, {
+  logConsoleMessage: () => logConsoleMessage,
+  getConsoleMessage: () => getConsoleMessage,
+  getConsoleLog: () => getConsoleLog,
+  clearConsoleLog: () => clearConsoleLog
+});
+import { randomUUID as randomUUID3 } from "crypto";
+function logConsoleMessage(data) {
+  const db = getDatabase();
+  const id = randomUUID3();
+  db.prepare("INSERT INTO console_log (id, session_id, level, message, source, line_number) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.session_id, data.level, data.message, data.source ?? null, data.line_number ?? null);
+  return getConsoleMessage(id);
+}
+function getConsoleMessage(id) {
+  const db = getDatabase();
+  return db.query("SELECT * FROM console_log WHERE id = ?").get(id) ?? null;
+}
+function getConsoleLog(sessionId, level) {
+  const db = getDatabase();
+  if (level) {
+    return db.query("SELECT * FROM console_log WHERE session_id = ? AND level = ? ORDER BY timestamp ASC").all(sessionId, level);
+  }
+  return db.query("SELECT * FROM console_log WHERE session_id = ? ORDER BY timestamp ASC").all(sessionId);
+}
+function clearConsoleLog(sessionId) {
+  const db = getDatabase();
+  db.prepare("DELETE FROM console_log WHERE session_id = ?").run(sessionId);
+}
+var init_console_log = __esm(() => {
+  init_schema();
+});
+
+// src/lib/console.ts
+function enableConsoleCapture(page, sessionId) {
+  const onConsole = (msg) => {
+    const levelMap = {
+      log: "log",
+      warn: "warn",
+      error: "error",
+      debug: "debug",
+      info: "info",
+      warning: "warn"
+    };
+    const level = levelMap[msg.type()] ?? "log";
+    const location = msg.location();
+    try {
+      logConsoleMessage({
+        session_id: sessionId,
+        level,
+        message: msg.text(),
+        source: location.url || undefined,
+        line_number: location.lineNumber || undefined
+      });
+    } catch {}
+  };
+  page.on("console", onConsole);
+  return () => page.off("console", onConsole);
+}
+var init_console = __esm(() => {
+  init_console_log();
+});
+
+// src/lib/stealth.ts
+async function applyStealthPatches(page) {
+  await page.context().addInitScript(STEALTH_SCRIPT);
+  await page.context().setExtraHTTPHeaders({
+    "User-Agent": REALISTIC_USER_AGENT
+  });
+}
+var REALISTIC_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36", STEALTH_SCRIPT = `
+// \u2500\u2500 1. Remove navigator.webdriver flag \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+Object.defineProperty(navigator, 'webdriver', {
+  get: () => false,
+  configurable: true,
+});
+
+// \u2500\u2500 2. Override navigator.plugins to show typical Chrome plugins \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+Object.defineProperty(navigator, 'plugins', {
+  get: () => {
+    const plugins = [
+      { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer', description: 'Portable Document Format', length: 1 },
+      { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai', description: '', length: 1 },
+      { name: 'Native Client', filename: 'internal-nacl-plugin', description: '', length: 2 },
+    ];
+    // Mimic PluginArray interface
+    const pluginArray = Object.create(PluginArray.prototype);
+    plugins.forEach((p, i) => {
+      const plugin = Object.create(Plugin.prototype);
+      Object.defineProperties(plugin, {
+        name: { value: p.name, enumerable: true },
+        filename: { value: p.filename, enumerable: true },
+        description: { value: p.description, enumerable: true },
+        length: { value: p.length, enumerable: true },
+      });
+      pluginArray[i] = plugin;
+    });
+    Object.defineProperty(pluginArray, 'length', { value: plugins.length });
+    pluginArray.item = (i) => pluginArray[i] || null;
+    pluginArray.namedItem = (name) => plugins.find(p => p.name === name) ? pluginArray[plugins.findIndex(p => p.name === name)] : null;
+    pluginArray.refresh = () => {};
+    return pluginArray;
+  },
+  configurable: true,
+});
+
+// \u2500\u2500 3. Override navigator.languages \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+Object.defineProperty(navigator, 'languages', {
+  get: () => ['en-US', 'en'],
+  configurable: true,
+});
+
+// \u2500\u2500 4. Override chrome.runtime to appear like real Chrome \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+if (!window.chrome) {
+  window.chrome = {};
+}
+if (!window.chrome.runtime) {
+  window.chrome.runtime = {
+    connect: function() { return { onMessage: { addListener: function() {} }, postMessage: function() {} }; },
+    sendMessage: function() {},
+    onMessage: { addListener: function() {}, removeListener: function() {} },
+    id: undefined,
+  };
+}
+`;
+var init_stealth = () => {};
+
+// src/lib/dialogs.ts
+function setupDialogHandler(page, sessionId) {
+  const onDialog = (dialog) => {
+    const info = {
+      type: dialog.type(),
+      message: dialog.message(),
+      default_value: dialog.defaultValue(),
+      timestamp: new Date().toISOString()
+    };
+    const autoTimer = setTimeout(() => {
+      try {
+        dialog.dismiss().catch(() => {});
+      } catch {}
+      const list = pendingDialogs.get(sessionId);
+      if (list) {
+        const idx = list.findIndex((p) => p.dialog === dialog);
+        if (idx >= 0)
+          list.splice(idx, 1);
+        if (list.length === 0)
+          pendingDialogs.delete(sessionId);
+      }
+    }, AUTO_DISMISS_MS);
+    const pending = { dialog, info, autoTimer };
+    if (!pendingDialogs.has(sessionId)) {
+      pendingDialogs.set(sessionId, []);
+    }
+    pendingDialogs.get(sessionId).push(pending);
+  };
+  page.on("dialog", onDialog);
+  return () => {
+    page.off("dialog", onDialog);
+    const list = pendingDialogs.get(sessionId);
+    if (list) {
+      for (const p of list)
+        clearTimeout(p.autoTimer);
+      pendingDialogs.delete(sessionId);
+    }
+  };
+}
+function getDialogs(sessionId) {
+  const list = pendingDialogs.get(sessionId);
+  if (!list)
+    return [];
+  return list.map((p) => p.info);
+}
+async function handleDialog(sessionId, action, promptText) {
+  const list = pendingDialogs.get(sessionId);
+  if (!list || list.length === 0) {
+    return { handled: false };
+  }
+  const pending = list.shift();
+  clearTimeout(pending.autoTimer);
+  if (list.length === 0) {
+    pendingDialogs.delete(sessionId);
+  }
+  try {
+    if (action === "accept") {
+      await pending.dialog.accept(promptText);
+    } else {
+      await pending.dialog.dismiss();
+    }
+  } catch {}
+  return { handled: true, dialog: pending.info };
+}
+var pendingDialogs, AUTO_DISMISS_MS = 5000;
+var init_dialogs = __esm(() => {
+  pendingDialogs = new Map;
+});
+
 // src/lib/session.ts
 async function createSession2(opts = {}) {
   const engine = opts.engine === "auto" || !opts.engine ? selectEngine(opts.useCase ?? "spa_navigate" /* SPA_NAVIGATE */, opts.engine) : opts.engine;
@@ -2550,13 +2880,33 @@ async function createSession2(opts = {}) {
     engine: resolvedEngine,
     projectId: opts.projectId,
     agentId: opts.agentId,
-    startUrl: opts.startUrl
+    startUrl: opts.startUrl,
+    name: opts.name ?? (opts.startUrl ? new URL(opts.startUrl).hostname : undefined)
   });
-  handles.set(session.id, { browser, page, engine: resolvedEngine });
+  if (opts.stealth) {
+    try {
+      await applyStealthPatches(page);
+    } catch {}
+  }
+  const cleanups = [];
+  if (opts.captureNetwork !== false) {
+    try {
+      cleanups.push(enableNetworkLogging(page, session.id));
+    } catch {}
+  }
+  if (opts.captureConsole !== false) {
+    try {
+      cleanups.push(enableConsoleCapture(page, session.id));
+    } catch {}
+  }
+  try {
+    cleanups.push(setupDialogHandler(page, session.id));
+  } catch {}
+  handles.set(session.id, { browser, page, engine: resolvedEngine, cleanups, tokenBudget: { total: 0, used: 0 } });
   if (opts.startUrl) {
     try {
       await page.goto(opts.startUrl, { waitUntil: "domcontentloaded" });
-    } catch (err) {}
+    } catch {}
   }
   return { session, page };
 }
@@ -2564,11 +2914,28 @@ function getSessionPage(sessionId) {
   const handle = handles.get(sessionId);
   if (!handle)
     throw new SessionNotFoundError(sessionId);
+  try {
+    handle.page.url();
+  } catch {
+    handles.delete(sessionId);
+    throw new SessionNotFoundError(sessionId);
+  }
   return handle.page;
 }
+function setSessionPage(sessionId, page) {
+  const handle = handles.get(sessionId);
+  if (!handle)
+    throw new SessionNotFoundError(sessionId);
+  handle.page = page;
+}
 async function closeSession2(sessionId) {
   const handle = handles.get(sessionId);
   if (handle) {
+    for (const cleanup of handle.cleanups) {
+      try {
+        cleanup();
+      } catch {}
+    }
     try {
       await handle.page.context().close();
     } catch {}
@@ -2579,6 +2946,9 @@ async function closeSession2(sessionId) {
   }
   return closeSession(sessionId);
 }
+function getSession2(sessionId) {
+  return getSession(sessionId);
+}
 function listSessions2(filter) {
   return listSessions(filter);
 }
@@ -2588,6 +2958,10 @@ function getSessionByName2(name) {
 function renameSession2(id, name) {
   return renameSession(id, name);
 }
+function getTokenBudget(sessionId) {
+  const handle = handles.get(sessionId);
+  return handle ? handle.tokenBudget : null;
+}
 var handles;
 var init_session = __esm(() => {
   init_types();
@@ -2596,9 +2970,186 @@ var init_session = __esm(() => {
   init_playwright();
   init_lightpanda();
   init_selector();
+  init_network();
+  init_console();
+  init_stealth();
+  init_dialogs();
   handles = new Map;
 });
 
+// src/lib/snapshot.ts
+function getLastSnapshot(sessionId) {
+  return lastSnapshots.get(sessionId) ?? null;
+}
+function setLastSnapshot(sessionId, snapshot) {
+  lastSnapshots.set(sessionId, snapshot);
+}
+async function takeSnapshot(page, sessionId) {
+  let ariaTree;
+  try {
+    ariaTree = await page.locator("body").ariaSnapshot();
+  } catch {
+    ariaTree = "";
+  }
+  const refs = {};
+  const refMap = new Map;
+  let refCounter = 0;
+  for (const role of INTERACTIVE_ROLES) {
+    const locators = page.getByRole(role);
+    const count = await locators.count();
+    for (let i = 0;i < count; i++) {
+      const el = locators.nth(i);
+      let name = "";
+      let visible = false;
+      let enabled = true;
+      let value;
+      let checked;
+      try {
+        visible = await el.isVisible();
+        if (!visible)
+          continue;
+      } catch {
+        continue;
+      }
+      try {
+        name = await el.evaluate((e) => {
+          const el2 = e;
+          return el2.getAttribute("aria-label") ?? el2.textContent?.trim().slice(0, 80) ?? el2.getAttribute("title") ?? el2.getAttribute("placeholder") ?? "";
+        });
+      } catch {
+        continue;
+      }
+      if (!name)
+        continue;
+      try {
+        enabled = await el.isEnabled();
+      } catch {}
+      try {
+        if (role === "checkbox" || role === "radio" || role === "switch") {
+          checked = await el.isChecked();
+        }
+      } catch {}
+      try {
+        if (role === "textbox" || role === "searchbox" || role === "spinbutton" || role === "combobox") {
+          value = await el.inputValue();
+        }
+      } catch {}
+      const ref = `@e${refCounter}`;
+      refCounter++;
+      refs[ref] = { role, name, visible, enabled, value, checked };
+      const escapedName = name.replace(/"/g, "\\\"");
+      refMap.set(ref, { role, name, locatorSelector: `role=${role}[name="${escapedName}"]` });
+    }
+  }
+  let annotatedTree = ariaTree;
+  for (const [ref, info] of Object.entries(refs)) {
+    const escapedName = info.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`(${info.role}\\s+"${escapedName.slice(0, 40)}[^"]*")`, "m");
+    const match = annotatedTree.match(pattern);
+    if (match) {
+      annotatedTree = annotatedTree.replace(match[0], `${match[0]} [${ref}]`);
+    }
+  }
+  const unmatchedRefs = Object.entries(refs).filter(([ref]) => !annotatedTree.includes(`[${ref}]`));
+  if (unmatchedRefs.length > 0) {
+    annotatedTree += `
+
+--- Interactive elements ---`;
+    for (const [ref, info] of unmatchedRefs) {
+      const extras = [];
+      if (info.checked !== undefined)
+        extras.push(`checked=${info.checked}`);
+      if (!info.enabled)
+        extras.push("disabled");
+      if (info.value)
+        extras.push(`value="${info.value}"`);
+      const extrasStr = extras.length ? ` (${extras.join(", ")})` : "";
+      annotatedTree += `
+${info.role} "${info.name}" [${ref}]${extrasStr}`;
+    }
+  }
+  if (sessionId) {
+    sessionRefMaps.set(sessionId, refMap);
+  }
+  return {
+    tree: annotatedTree,
+    refs,
+    interactive_count: refCounter
+  };
+}
+function getRefLocator(page, sessionId, ref) {
+  const refMap = sessionRefMaps.get(sessionId);
+  if (!refMap)
+    throw new Error(`No snapshot taken for session ${sessionId}. Call browser_snapshot first.`);
+  const entry = refMap.get(ref);
+  if (!entry)
+    throw new Error(`Ref ${ref} not found. Available refs: ${[...refMap.keys()].slice(0, 20).join(", ")}`);
+  return page.getByRole(entry.role, { name: entry.name }).first();
+}
+function refKey(info) {
+  return `${info.role}::${info.name}`;
+}
+function diffSnapshots(before, after) {
+  const beforeMap = new Map;
+  for (const [ref, info] of Object.entries(before.refs)) {
+    beforeMap.set(refKey(info), { ref, info });
+  }
+  const afterMap = new Map;
+  for (const [ref, info] of Object.entries(after.refs)) {
+    afterMap.set(refKey(info), { ref, info });
+  }
+  const added = [];
+  const removed = [];
+  const modified = [];
+  for (const [key, afterEntry] of afterMap) {
+    const beforeEntry = beforeMap.get(key);
+    if (!beforeEntry) {
+      added.push({ ref: afterEntry.ref, info: afterEntry.info });
+    } else {
+      const b = beforeEntry.info;
+      const a = afterEntry.info;
+      if (b.visible !== a.visible || b.enabled !== a.enabled || b.value !== a.value || b.checked !== a.checked || b.description !== a.description) {
+        modified.push({ ref: afterEntry.ref, before: b, after: a });
+      }
+    }
+  }
+  for (const [key, beforeEntry] of beforeMap) {
+    if (!afterMap.has(key)) {
+      removed.push({ ref: beforeEntry.ref, info: beforeEntry.info });
+    }
+  }
+  const url_changed = before.tree.split(`
+`)[0] !== after.tree.split(`
+`)[0];
+  const title_changed = before.tree !== after.tree && (added.length > 0 || removed.length > 0 || modified.length > 0);
+  return { added, removed, modified, url_changed, title_changed };
+}
+var lastSnapshots, sessionRefMaps, INTERACTIVE_ROLES;
+var init_snapshot = __esm(() => {
+  lastSnapshots = new Map;
+  sessionRefMaps = new Map;
+  INTERACTIVE_ROLES = [
+    "button",
+    "link",
+    "textbox",
+    "checkbox",
+    "radio",
+    "combobox",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "searchbox",
+    "slider",
+    "spinbutton",
+    "switch",
+    "tab",
+    "treeitem",
+    "listbox",
+    "menu"
+  ];
+});
+
 // src/lib/actions.ts
 async function click(page, selector, opts) {
   try {
@@ -2818,9 +3369,67 @@ function stopWatch(watchId) {
     activeWatches.delete(watchId);
   }
 }
+async function clickRef(page, sessionId, ref, opts) {
+  try {
+    const locator = getRefLocator(page, sessionId, ref);
+    await locator.click({ timeout: opts?.timeout ?? 1e4 });
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("Ref "))
+      throw new ElementNotFoundError(ref);
+    if (err instanceof Error && err.message.includes("No snapshot"))
+      throw new BrowserError(err.message, "NO_SNAPSHOT");
+    throw new BrowserError(`clickRef ${ref} failed: ${err instanceof Error ? err.message : String(err)}`, "CLICK_REF_FAILED");
+  }
+}
+async function typeRef(page, sessionId, ref, text, opts) {
+  try {
+    const locator = getRefLocator(page, sessionId, ref);
+    if (opts?.clear)
+      await locator.fill("", { timeout: opts.timeout ?? 1e4 });
+    await locator.pressSequentially(text, { delay: opts?.delay, timeout: opts?.timeout ?? 1e4 });
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("Ref "))
+      throw new ElementNotFoundError(ref);
+    throw new BrowserError(`typeRef ${ref} failed: ${err instanceof Error ? err.message : String(err)}`, "TYPE_REF_FAILED");
+  }
+}
+async function selectRef(page, sessionId, ref, value, timeout = 1e4) {
+  try {
+    const locator = getRefLocator(page, sessionId, ref);
+    return await locator.selectOption(value, { timeout });
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("Ref "))
+      throw new ElementNotFoundError(ref);
+    throw new BrowserError(`selectRef ${ref} failed: ${err instanceof Error ? err.message : String(err)}`, "SELECT_REF_FAILED");
+  }
+}
+async function checkRef(page, sessionId, ref, checked, timeout = 1e4) {
+  try {
+    const locator = getRefLocator(page, sessionId, ref);
+    if (checked)
+      await locator.check({ timeout });
+    else
+      await locator.uncheck({ timeout });
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("Ref "))
+      throw new ElementNotFoundError(ref);
+    throw new BrowserError(`checkRef ${ref} failed: ${err instanceof Error ? err.message : String(err)}`, "CHECK_REF_FAILED");
+  }
+}
+async function hoverRef(page, sessionId, ref, timeout = 1e4) {
+  try {
+    const locator = getRefLocator(page, sessionId, ref);
+    await locator.hover({ timeout });
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("Ref "))
+      throw new ElementNotFoundError(ref);
+    throw new BrowserError(`hoverRef ${ref} failed: ${err instanceof Error ? err.message : String(err)}`, "HOVER_REF_FAILED");
+  }
+}
 var RETRYABLE_ERRORS, activeWatches;
 var init_actions = __esm(() => {
   init_types();
+  init_snapshot();
   RETRYABLE_ERRORS = ["Timeout", "timeout", "navigation", "net::ERR", "Target closed"];
   activeWatches = new Map;
 });
@@ -2890,24 +3499,6 @@ async function extractTable(page, selector) {
     return rows.map((row) => Array.from(row.querySelectorAll("th, td")).map((cell) => cell.textContent?.trim() ?? ""));
   }, selector);
 }
-async function getAriaSnapshot(page) {
-  try {
-    return await page.ariaSnapshot?.() ?? page.evaluate(() => {
-      function walk(el, indent = 0) {
-        const role = el.getAttribute("role") ?? el.tagName.toLowerCase();
-        const label = el.getAttribute("aria-label") ?? el.getAttribute("aria-labelledby") ?? el.textContent?.trim().slice(0, 50) ?? "";
-        const line = "  ".repeat(indent) + `[${role}] ${label}`;
-        const children = Array.from(el.children).map((c) => walk(c, indent + 1)).join(`
-`);
-        return children ? `${line}
-${children}` : line;
-      }
-      return walk(document.body);
-    });
-  } catch {
-    return page.evaluate(() => document.body.innerText?.slice(0, 2000) ?? "");
-  }
-}
 async function extract(page, opts = {}) {
   const result = {};
   const format = opts.format ?? "text";
@@ -9377,7 +9968,7 @@ __export(exports_gallery, {
   deleteEntry: () => deleteEntry,
   createEntry: () => createEntry
 });
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 function deserialize(row) {
   return {
     id: row.id,
@@ -9401,7 +9992,7 @@ function deserialize(row) {
 }
 function createEntry(data) {
   const db = getDatabase();
-  const id = randomUUID2();
+  const id = randomUUID4();
   db.prepare(`
     INSERT INTO gallery_entries
       (id, session_id, project_id, url, title, path, thumbnail_path, format,
@@ -9674,7 +10265,7 @@ var init_screenshot = __esm(() => {
 });
 
 // src/db/crawl-results.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 function deserialize2(row) {
   const pages = JSON.parse(row.pages);
   return {
@@ -9690,7 +10281,7 @@ function deserialize2(row) {
 }
 function createCrawlResult(data) {
   const db = getDatabase();
-  const id = randomUUID3();
+  const id = randomUUID5();
   db.prepare("INSERT INTO crawl_results (id, project_id, start_url, depth, pages, links, errors) VALUES (?, ?, ?, ?, ?, ?, ?)").run(id, data.project_id ?? null, data.start_url, data.depth, JSON.stringify(data.pages), JSON.stringify(data.pages.flatMap((p) => p.links)), JSON.stringify(data.errors));
   return getCrawlResult(id);
 }
@@ -9783,7 +10374,7 @@ __export(exports_agents, {
   deleteAgent: () => deleteAgent,
   cleanStaleAgents: () => cleanStaleAgents
 });
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 function registerAgent(name, opts = {}) {
   const db = getDatabase();
   const existing = db.query("SELECT * FROM agents WHERE name = ?").get(name);
@@ -9791,7 +10382,7 @@ function registerAgent(name, opts = {}) {
     db.prepare("UPDATE agents SET last_seen = datetime('now'), session_id = ?, project_id = ?, working_dir = ? WHERE name = ?").run(opts.sessionId ?? existing.session_id ?? null, opts.projectId ?? existing.project_id ?? null, opts.workingDir ?? existing.working_dir ?? null, name);
     return getAgentByName(name);
   }
-  const id = randomUUID4();
+  const id = randomUUID6();
   db.prepare("INSERT INTO agents (id, name, description, session_id, project_id, working_dir) VALUES (?, ?, ?, ?, ?, ?)").run(id, name, opts.description ?? null, opts.sessionId ?? null, opts.projectId ?? null, opts.workingDir ?? null);
   return getAgent(id);
 }
@@ -9801,7 +10392,7 @@ function heartbeat(agentId) {
   if (!agent)
     throw new AgentNotFoundError(agentId);
   db.prepare("UPDATE agents SET last_seen = datetime('now') WHERE id = ?").run(agentId);
-  db.prepare("INSERT INTO heartbeats (id, agent_id, session_id) VALUES (?, ?, ?)").run(randomUUID4(), agentId, agent.session_id ?? null);
+  db.prepare("INSERT INTO heartbeats (id, agent_id, session_id) VALUES (?, ?, ?)").run(randomUUID6(), agentId, agent.session_id ?? null);
 }
 function getAgent(id) {
   const db = getDatabase();
@@ -9878,10 +10469,10 @@ var init_agents2 = __esm(() => {
 });
 
 // src/db/projects.ts
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID7 } from "crypto";
 function createProject(data) {
   const db = getDatabase();
-  const id = randomUUID5();
+  const id = randomUUID7();
   db.prepare("INSERT INTO projects (id, name, path, description) VALUES (?, ?, ?, ?)").run(id, data.name, data.path, data.description ?? null);
   return getProject(id);
 }
@@ -9917,7 +10508,7 @@ __export(exports_recordings, {
   deleteRecording: () => deleteRecording,
   createRecording: () => createRecording
 });
-import { randomUUID as randomUUID6 } from "crypto";
+import { randomUUID as randomUUID8 } from "crypto";
 function deserialize3(row) {
   return {
     ...row,
@@ -9928,7 +10519,7 @@ function deserialize3(row) {
 }
 function createRecording(data) {
   const db = getDatabase();
-  const id = randomUUID6();
+  const id = randomUUID8();
   db.prepare("INSERT INTO recordings (id, name, project_id, start_url, steps) VALUES (?, ?, ?, ?, ?)").run(id, data.name, data.project_id ?? null, data.start_url ?? null, JSON.stringify(data.steps ?? []));
   return getRecording(id);
 }
@@ -14031,139 +14622,6 @@ var init_zod = __esm(() => {
   init_external();
 });
 
-// src/db/network-log.ts
-import { randomUUID as randomUUID7 } from "crypto";
-function logRequest(data) {
-  const db = getDatabase();
-  const id = randomUUID7();
-  db.prepare(`INSERT INTO network_log (id, session_id, method, url, status_code, request_headers,
-     response_headers, request_body, body_size, duration_ms, resource_type)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, data.session_id, data.method, data.url, data.status_code ?? null, data.request_headers ?? null, data.response_headers ?? null, data.request_body ?? null, data.body_size ?? null, data.duration_ms ?? null, data.resource_type ?? null);
-  return getNetworkRequest(id);
-}
-function getNetworkRequest(id) {
-  const db = getDatabase();
-  return db.query("SELECT * FROM network_log WHERE id = ?").get(id) ?? null;
-}
-function getNetworkLog(sessionId) {
-  const db = getDatabase();
-  return db.query("SELECT * FROM network_log WHERE session_id = ? ORDER BY timestamp ASC").all(sessionId);
-}
-function clearNetworkLog(sessionId) {
-  const db = getDatabase();
-  db.prepare("DELETE FROM network_log WHERE session_id = ?").run(sessionId);
-}
-var init_network_log = __esm(() => {
-  init_schema();
-});
-
-// src/lib/network.ts
-function enableNetworkLogging(page, sessionId) {
-  const requestStart = new Map;
-  const onRequest = (req) => {
-    requestStart.set(req.url(), Date.now());
-  };
-  const onResponse = (res) => {
-    const start = requestStart.get(res.url()) ?? Date.now();
-    const duration = Date.now() - start;
-    const req = res.request();
-    try {
-      logRequest({
-        session_id: sessionId,
-        method: req.method(),
-        url: res.url(),
-        status_code: res.status(),
-        request_headers: JSON.stringify(req.headers()),
-        response_headers: JSON.stringify(res.headers()),
-        body_size: res.headers()["content-length"] != null ? parseInt(res.headers()["content-length"]) : undefined,
-        duration_ms: duration,
-        resource_type: req.resourceType()
-      });
-    } catch {}
-  };
-  page.on("request", onRequest);
-  page.on("response", onResponse);
-  return () => {
-    page.off("request", onRequest);
-    page.off("response", onResponse);
-  };
-}
-async function addInterceptRule(page, rule) {
-  await page.route(rule.pattern, async (route) => {
-    if (rule.action === "block") {
-      await route.abort();
-    } else if (rule.action === "modify" && rule.response) {
-      await route.fulfill({
-        status: rule.response.status,
-        body: rule.response.body,
-        headers: rule.response.headers
-      });
-    } else {
-      await route.continue();
-    }
-  });
-}
-function startHAR(page) {
-  const entries = [];
-  const requestStart = new Map;
-  const onRequest = (req) => {
-    requestStart.set(req.url() + req.method(), {
-      time: Date.now(),
-      method: req.method(),
-      headers: req.headers(),
-      postData: req.postData() ?? undefined
-    });
-  };
-  const onResponse = async (res) => {
-    const key = res.url() + res.request().method();
-    const start = requestStart.get(key);
-    if (!start)
-      return;
-    const duration = Date.now() - start.time;
-    const entry = {
-      startedDateTime: new Date(start.time).toISOString(),
-      time: duration,
-      request: {
-        method: start.method,
-        url: res.url(),
-        headers: Object.entries(start.headers).map(([name, value]) => ({ name, value })),
-        postData: start.postData ? { text: start.postData } : undefined
-      },
-      response: {
-        status: res.status(),
-        statusText: res.statusText(),
-        headers: Object.entries(res.headers()).map(([name, value]) => ({ name, value })),
-        content: {
-          size: parseInt(res.headers()["content-length"] ?? "0") || 0,
-          mimeType: res.headers()["content-type"] ?? "application/octet-stream"
-        }
-      },
-      timings: { send: 0, wait: duration, receive: 0 }
-    };
-    entries.push(entry);
-    requestStart.delete(key);
-  };
-  page.on("request", onRequest);
-  page.on("response", onResponse);
-  return {
-    entries,
-    stop: () => {
-      page.off("request", onRequest);
-      page.off("response", onResponse);
-      return {
-        log: {
-          version: "1.2",
-          creator: { name: "@hasna/browser", version: "0.0.1" },
-          entries
-        }
-      };
-    }
-  };
-}
-var init_network = __esm(() => {
-  init_network_log();
-});
-
 // src/engines/cdp.ts
 class CDPClient {
   session;
@@ -14263,120 +14721,56 @@ class CDPClient {
     this.on("Network.responseReceived", onResponse);
     return () => {
       this.off("Network.requestWillBeSent", onRequest);
-      this.off("Network.responseReceived", onResponse);
-    };
-  }
-  async detach() {
-    try {
-      await this.session.detach();
-    } catch {}
-  }
-}
-var init_cdp = __esm(() => {
-  init_types();
-});
-
-// src/lib/performance.ts
-async function getPerformanceMetrics(page) {
-  const navTiming = await page.evaluate(() => {
-    const t = performance.timing;
-    const nav = performance.getEntriesByType("navigation")[0];
-    return {
-      ttfb: nav ? nav.responseStart - nav.requestStart : t.responseStart - t.requestStart,
-      domInteractive: nav ? nav.domInteractive : t.domInteractive - t.navigationStart,
-      domComplete: nav ? nav.domComplete : t.domComplete - t.navigationStart,
-      loadEvent: nav ? nav.loadEventEnd : t.loadEventEnd - t.navigationStart
-    };
-  });
-  const paintEntries = await page.evaluate(() => {
-    const entries = performance.getEntriesByType("paint");
-    const fcp = entries.find((e) => e.name === "first-contentful-paint");
-    return { fcp: fcp?.startTime };
-  });
-  let heapMetrics = {};
-  try {
-    const cdp = await CDPClient.fromPage(page);
-    const cdpMetrics = await cdp.getPerformanceMetrics();
-    heapMetrics = {
-      js_heap_size_used: cdpMetrics.js_heap_size_used,
-      js_heap_size_total: cdpMetrics.js_heap_size_total
-    };
-  } catch {}
-  return {
-    fcp: paintEntries.fcp,
-    ttfb: navTiming.ttfb,
-    dom_interactive: navTiming.domInteractive,
-    dom_complete: navTiming.domComplete,
-    load_event: navTiming.loadEvent,
-    ...heapMetrics
-  };
-}
-var init_performance = __esm(() => {
-  init_cdp();
-});
-
-// src/db/console-log.ts
-var exports_console_log = {};
-__export(exports_console_log, {
-  logConsoleMessage: () => logConsoleMessage,
-  getConsoleMessage: () => getConsoleMessage,
-  getConsoleLog: () => getConsoleLog,
-  clearConsoleLog: () => clearConsoleLog
-});
-import { randomUUID as randomUUID8 } from "crypto";
-function logConsoleMessage(data) {
-  const db = getDatabase();
-  const id = randomUUID8();
-  db.prepare("INSERT INTO console_log (id, session_id, level, message, source, line_number) VALUES (?, ?, ?, ?, ?, ?)").run(id, data.session_id, data.level, data.message, data.source ?? null, data.line_number ?? null);
-  return getConsoleMessage(id);
-}
-function getConsoleMessage(id) {
-  const db = getDatabase();
-  return db.query("SELECT * FROM console_log WHERE id = ?").get(id) ?? null;
-}
-function getConsoleLog(sessionId, level) {
-  const db = getDatabase();
-  if (level) {
-    return db.query("SELECT * FROM console_log WHERE session_id = ? AND level = ? ORDER BY timestamp ASC").all(sessionId, level);
-  }
-  return db.query("SELECT * FROM console_log WHERE session_id = ? ORDER BY timestamp ASC").all(sessionId);
-}
-function clearConsoleLog(sessionId) {
-  const db = getDatabase();
-  db.prepare("DELETE FROM console_log WHERE session_id = ?").run(sessionId);
-}
-var init_console_log = __esm(() => {
-  init_schema();
-});
-
-// src/lib/console.ts
-function enableConsoleCapture(page, sessionId) {
-  const onConsole = (msg) => {
-    const levelMap = {
-      log: "log",
-      warn: "warn",
-      error: "error",
-      debug: "debug",
-      info: "info",
-      warning: "warn"
+      this.off("Network.responseReceived", onResponse);
     };
-    const level = levelMap[msg.type()] ?? "log";
-    const location = msg.location();
+  }
+  async detach() {
     try {
-      logConsoleMessage({
-        session_id: sessionId,
-        level,
-        message: msg.text(),
-        source: location.url || undefined,
-        line_number: location.lineNumber || undefined
-      });
+      await this.session.detach();
     } catch {}
+  }
+}
+var init_cdp = __esm(() => {
+  init_types();
+});
+
+// src/lib/performance.ts
+async function getPerformanceMetrics(page) {
+  const navTiming = await page.evaluate(() => {
+    const t = performance.timing;
+    const nav = performance.getEntriesByType("navigation")[0];
+    return {
+      ttfb: nav ? nav.responseStart - nav.requestStart : t.responseStart - t.requestStart,
+      domInteractive: nav ? nav.domInteractive : t.domInteractive - t.navigationStart,
+      domComplete: nav ? nav.domComplete : t.domComplete - t.navigationStart,
+      loadEvent: nav ? nav.loadEventEnd : t.loadEventEnd - t.navigationStart
+    };
+  });
+  const paintEntries = await page.evaluate(() => {
+    const entries = performance.getEntriesByType("paint");
+    const fcp = entries.find((e) => e.name === "first-contentful-paint");
+    return { fcp: fcp?.startTime };
+  });
+  let heapMetrics = {};
+  try {
+    const cdp = await CDPClient.fromPage(page);
+    const cdpMetrics = await cdp.getPerformanceMetrics();
+    heapMetrics = {
+      js_heap_size_used: cdpMetrics.js_heap_size_used,
+      js_heap_size_total: cdpMetrics.js_heap_size_total
+    };
+  } catch {}
+  return {
+    fcp: paintEntries.fcp,
+    ttfb: navTiming.ttfb,
+    dom_interactive: navTiming.domInteractive,
+    dom_complete: navTiming.domComplete,
+    load_event: navTiming.loadEvent,
+    ...heapMetrics
   };
-  page.on("console", onConsole);
-  return () => page.off("console", onConsole);
 }
-var init_console = __esm(() => {
-  init_console_log();
+var init_performance = __esm(() => {
+  init_cdp();
 });
 
 // src/lib/storage.ts
@@ -14673,6 +15067,282 @@ async function persistFile(localPath, opts) {
 }
 var init_files_integration = () => {};
 
+// src/lib/tabs.ts
+async function newTab(page, url) {
+  const context = page.context();
+  const newPage = await context.newPage();
+  if (url) {
+    await newPage.goto(url, { waitUntil: "domcontentloaded" });
+  }
+  const pages = context.pages();
+  const index = pages.indexOf(newPage);
+  return {
+    index,
+    url: newPage.url(),
+    title: await newPage.title(),
+    is_active: true
+  };
+}
+async function listTabs(page) {
+  const context = page.context();
+  const pages = context.pages();
+  const activePage = page;
+  const tabs = [];
+  for (let i = 0;i < pages.length; i++) {
+    let url = "";
+    let title = "";
+    try {
+      url = pages[i].url();
+      title = await pages[i].title();
+    } catch {}
+    tabs.push({
+      index: i,
+      url,
+      title,
+      is_active: pages[i] === activePage
+    });
+  }
+  return tabs;
+}
+async function switchTab(page, index) {
+  const context = page.context();
+  const pages = context.pages();
+  if (index < 0 || index >= pages.length) {
+    throw new Error(`Tab index ${index} out of range (0-${pages.length - 1})`);
+  }
+  const targetPage = pages[index];
+  await targetPage.bringToFront();
+  return {
+    page: targetPage,
+    tab: {
+      index,
+      url: targetPage.url(),
+      title: await targetPage.title(),
+      is_active: true
+    }
+  };
+}
+async function closeTab(page, index) {
+  const context = page.context();
+  const pages = context.pages();
+  if (index < 0 || index >= pages.length) {
+    throw new Error(`Tab index ${index} out of range (0-${pages.length - 1})`);
+  }
+  if (pages.length <= 1) {
+    throw new Error("Cannot close the last tab");
+  }
+  const targetPage = pages[index];
+  const isActivePage = targetPage === page;
+  await targetPage.close();
+  const remainingPages = context.pages();
+  const activeIndex = isActivePage ? Math.min(index, remainingPages.length - 1) : remainingPages.indexOf(page);
+  const activePage = remainingPages[activeIndex >= 0 ? activeIndex : 0];
+  return {
+    closed_index: index,
+    active_tab: {
+      index: activeIndex >= 0 ? activeIndex : 0,
+      url: activePage.url(),
+      title: await activePage.title(),
+      is_active: true
+    }
+  };
+}
+
+// src/lib/profiles.ts
+import { mkdirSync as mkdirSync6, existsSync as existsSync3, readdirSync as readdirSync2, rmSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join6 } from "path";
+import { homedir as homedir6 } from "os";
+function getProfilesDir() {
+  const dataDir = process.env["BROWSER_DATA_DIR"] ?? join6(homedir6(), ".browser");
+  const dir = join6(dataDir, "profiles");
+  mkdirSync6(dir, { recursive: true });
+  return dir;
+}
+function getProfileDir(name) {
+  return join6(getProfilesDir(), name);
+}
+async function saveProfile(page, name) {
+  const dir = getProfileDir(name);
+  mkdirSync6(dir, { recursive: true });
+  const cookies = await page.context().cookies();
+  writeFileSync2(join6(dir, "cookies.json"), JSON.stringify(cookies, null, 2));
+  let localStorage2 = {};
+  try {
+    localStorage2 = await page.evaluate(() => {
+      const result = {};
+      for (let i = 0;i < window.localStorage.length; i++) {
+        const key = window.localStorage.key(i);
+        result[key] = window.localStorage.getItem(key);
+      }
+      return result;
+    });
+  } catch {}
+  writeFileSync2(join6(dir, "storage.json"), JSON.stringify(localStorage2, null, 2));
+  const savedAt = new Date().toISOString();
+  const url = page.url();
+  const meta = { saved_at: savedAt, url };
+  writeFileSync2(join6(dir, "meta.json"), JSON.stringify(meta, null, 2));
+  return {
+    name,
+    saved_at: savedAt,
+    url,
+    cookie_count: cookies.length,
+    storage_key_count: Object.keys(localStorage2).length
+  };
+}
+function loadProfile(name) {
+  const dir = getProfileDir(name);
+  if (!existsSync3(dir)) {
+    throw new Error(`Profile not found: ${name}`);
+  }
+  const cookiesPath = join6(dir, "cookies.json");
+  const storagePath = join6(dir, "storage.json");
+  const metaPath2 = join6(dir, "meta.json");
+  const cookies = existsSync3(cookiesPath) ? JSON.parse(readFileSync2(cookiesPath, "utf8")) : [];
+  const localStorage2 = existsSync3(storagePath) ? JSON.parse(readFileSync2(storagePath, "utf8")) : {};
+  let savedAt = new Date().toISOString();
+  let url;
+  if (existsSync3(metaPath2)) {
+    const meta = JSON.parse(readFileSync2(metaPath2, "utf8"));
+    savedAt = meta.saved_at ?? savedAt;
+    url = meta.url;
+  }
+  return { cookies, localStorage: localStorage2, saved_at: savedAt, url };
+}
+async function applyProfile(page, profileData) {
+  if (profileData.cookies.length > 0) {
+    await page.context().addCookies(profileData.cookies);
+  }
+  const storageKeys = Object.keys(profileData.localStorage);
+  if (storageKeys.length > 0) {
+    try {
+      await page.evaluate((storage) => {
+        for (const [key, value] of Object.entries(storage)) {
+          window.localStorage.setItem(key, value);
+        }
+      }, profileData.localStorage);
+    } catch {}
+  }
+  return {
+    cookies_applied: profileData.cookies.length,
+    storage_keys_applied: storageKeys.length
+  };
+}
+function listProfiles() {
+  const dir = getProfilesDir();
+  if (!existsSync3(dir))
+    return [];
+  const entries = readdirSync2(dir, { withFileTypes: true });
+  const profiles = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory())
+      continue;
+    const name = entry.name;
+    const profileDir = join6(dir, name);
+    let savedAt = "";
+    let url;
+    let cookieCount = 0;
+    let storageKeyCount = 0;
+    try {
+      const metaPath2 = join6(profileDir, "meta.json");
+      if (existsSync3(metaPath2)) {
+        const meta = JSON.parse(readFileSync2(metaPath2, "utf8"));
+        savedAt = meta.saved_at ?? "";
+        url = meta.url;
+      }
+      const cookiesPath = join6(profileDir, "cookies.json");
+      if (existsSync3(cookiesPath)) {
+        const cookies = JSON.parse(readFileSync2(cookiesPath, "utf8"));
+        cookieCount = Array.isArray(cookies) ? cookies.length : 0;
+      }
+      const storagePath = join6(profileDir, "storage.json");
+      if (existsSync3(storagePath)) {
+        const storage = JSON.parse(readFileSync2(storagePath, "utf8"));
+        storageKeyCount = Object.keys(storage).length;
+      }
+    } catch {}
+    profiles.push({
+      name,
+      saved_at: savedAt,
+      url,
+      cookie_count: cookieCount,
+      storage_key_count: storageKeyCount
+    });
+  }
+  return profiles.sort((a, b) => b.saved_at.localeCompare(a.saved_at));
+}
+function deleteProfile(name) {
+  const dir = getProfileDir(name);
+  if (!existsSync3(dir))
+    return false;
+  try {
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+var init_profiles = () => {};
+
+// src/lib/annotate.ts
+var exports_annotate = {};
+__export(exports_annotate, {
+  annotateScreenshot: () => annotateScreenshot
+});
+async function annotateScreenshot(page, sessionId) {
+  const snapshot = await takeSnapshot(page, sessionId);
+  const rawBuffer = await page.screenshot({ type: "png" });
+  const meta = await import_sharp3.default(rawBuffer).metadata();
+  const imgWidth = meta.width ?? 1280;
+  const imgHeight = meta.height ?? 720;
+  const annotations = [];
+  const labelToRef = {};
+  let labelCounter = 1;
+  for (const [ref, info] of Object.entries(snapshot.refs)) {
+    try {
+      const locator = page.getByRole(info.role, { name: info.name }).first();
+      const box = await locator.boundingBox();
+      if (!box)
+        continue;
+      const annotation = {
+        ref,
+        label: labelCounter,
+        x: Math.round(box.x),
+        y: Math.round(box.y),
+        width: Math.round(box.width),
+        height: Math.round(box.height),
+        role: info.role,
+        name: info.name
+      };
+      annotations.push(annotation);
+      labelToRef[labelCounter] = ref;
+      labelCounter++;
+    } catch {}
+  }
+  const circleR = 10;
+  const fontSize = 12;
+  const svgParts = [];
+  for (const ann of annotations) {
+    const cx = Math.min(Math.max(ann.x + circleR, circleR), imgWidth - circleR);
+    const cy = Math.min(Math.max(ann.y - circleR - 2, circleR), imgHeight - circleR);
+    svgParts.push(`
+      <circle cx="${cx}" cy="${cy}" r="${circleR}" fill="#e11d48" stroke="white" stroke-width="1.5"/>
+      <text x="${cx}" y="${cy + 4}" text-anchor="middle" fill="white" font-size="${fontSize}" font-family="Arial,sans-serif" font-weight="bold">${ann.label}</text>
+    `);
+    svgParts.push(`
+      <rect x="${ann.x}" y="${ann.y}" width="${ann.width}" height="${ann.height}" fill="none" stroke="#e11d48" stroke-width="1.5" stroke-opacity="0.6" rx="2"/>
+    `);
+  }
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${imgWidth}" height="${imgHeight}">${svgParts.join("")}</svg>`;
+  const annotatedBuffer = await import_sharp3.default(rawBuffer).composite([{ input: Buffer.from(svg), top: 0, left: 0 }]).webp({ quality: 85 }).toBuffer();
+  return { buffer: annotatedBuffer, annotations, labelToRef };
+}
+var import_sharp3;
+var init_annotate = __esm(() => {
+  init_snapshot();
+  import_sharp3 = __toESM(require_lib(), 1);
+});
+
 // src/mcp/index.ts
 var exports_mcp = {};
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -14706,8 +15376,11 @@ var init_mcp = __esm(async () => {
   init_gallery();
   init_downloads();
   init_gallery_diff();
+  init_snapshot();
   init_files_integration();
   init_recordings();
+  init_dialogs();
+  init_profiles();
   init_types();
   networkLogCleanup = new Map;
   consoleCaptureCleanup = new Map;
@@ -14724,8 +15397,9 @@ var init_mcp = __esm(async () => {
     start_url: exports_external.string().optional(),
     headless: exports_external.boolean().optional().default(true),
     viewport_width: exports_external.number().optional().default(1280),
-    viewport_height: exports_external.number().optional().default(720)
-  }, async ({ engine, use_case, project_id, agent_id, start_url, headless, viewport_width, viewport_height }) => {
+    viewport_height: exports_external.number().optional().default(720),
+    stealth: exports_external.boolean().optional().default(false)
+  }, async ({ engine, use_case, project_id, agent_id, start_url, headless, viewport_width, viewport_height, stealth }) => {
     try {
       const { session } = await createSession2({
         engine,
@@ -14734,7 +15408,8 @@ var init_mcp = __esm(async () => {
         agentId: agent_id,
         startUrl: start_url,
         headless,
-        viewport: { width: viewport_width, height: viewport_height }
+        viewport: { width: viewport_width, height: viewport_height },
+        stealth
       });
       return json({ session });
     } catch (e) {
@@ -14761,11 +15436,28 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_navigate", "Navigate to a URL in the session", { session_id: exports_external.string(), url: exports_external.string(), timeout: exports_external.number().optional().default(30000) }, async ({ session_id, url, timeout }) => {
+  server.tool("browser_navigate", "Navigate to a URL. Returns title + thumbnail + accessibility snapshot preview with refs.", { session_id: exports_external.string(), url: exports_external.string(), timeout: exports_external.number().optional().default(30000), auto_snapshot: exports_external.boolean().optional().default(true), auto_thumbnail: exports_external.boolean().optional().default(true) }, async ({ session_id, url, timeout, auto_snapshot, auto_thumbnail }) => {
     try {
       const page = getSessionPage(session_id);
       await navigate(page, url, timeout);
-      return json({ url, title: await getTitle(page), current_url: await getUrl(page) });
+      const title = await getTitle(page);
+      const current_url = await getUrl(page);
+      const result = { url, title, current_url };
+      if (auto_thumbnail) {
+        try {
+          const ss = await takeScreenshot(page, { maxWidth: 400, quality: 60, track: false, thumbnail: false });
+          result.thumbnail_base64 = ss.base64.length > 50000 ? "" : ss.base64;
+        } catch {}
+      }
+      if (auto_snapshot) {
+        try {
+          const snap = await takeSnapshot(page, session_id);
+          result.snapshot_preview = snap.tree.slice(0, 3000);
+          result.interactive_count = snap.interactive_count;
+          result.has_errors = getConsoleLog(session_id, "error").length > 0;
+        } catch {}
+      }
+      return json(result);
     } catch (e) {
       return err(e);
     }
@@ -14797,29 +15489,47 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_click", "Click an element matching the selector", { session_id: exports_external.string(), selector: exports_external.string(), button: exports_external.enum(["left", "right", "middle"]).optional(), timeout: exports_external.number().optional() }, async ({ session_id, selector, button, timeout }) => {
+  server.tool("browser_click", "Click an element by ref (from snapshot) or CSS selector. Prefer ref for reliability.", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), button: exports_external.enum(["left", "right", "middle"]).optional(), timeout: exports_external.number().optional() }, async ({ session_id, selector, ref, button, timeout }) => {
     try {
       const page = getSessionPage(session_id);
+      if (ref) {
+        await clickRef(page, session_id, ref, { timeout });
+        return json({ clicked: ref, method: "ref" });
+      }
+      if (!selector)
+        return err(new Error("Either ref or selector is required"));
       await click(page, selector, { button, timeout });
-      return json({ clicked: selector });
+      return json({ clicked: selector, method: "selector" });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_type", "Type text into an element", { session_id: exports_external.string(), selector: exports_external.string(), text: exports_external.string(), clear: exports_external.boolean().optional().default(false), delay: exports_external.number().optional() }, async ({ session_id, selector, text, clear, delay }) => {
+  server.tool("browser_type", "Type text into an element by ref or selector. Prefer ref.", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), text: exports_external.string(), clear: exports_external.boolean().optional().default(false), delay: exports_external.number().optional() }, async ({ session_id, selector, ref, text, clear, delay }) => {
     try {
       const page = getSessionPage(session_id);
+      if (ref) {
+        await typeRef(page, session_id, ref, text, { clear, delay });
+        return json({ typed: text, ref, method: "ref" });
+      }
+      if (!selector)
+        return err(new Error("Either ref or selector is required"));
       await type(page, selector, text, { clear, delay });
-      return json({ typed: text, selector });
+      return json({ typed: text, selector, method: "selector" });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_hover", "Hover over an element", { session_id: exports_external.string(), selector: exports_external.string() }, async ({ session_id, selector }) => {
+  server.tool("browser_hover", "Hover over an element by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional() }, async ({ session_id, selector, ref }) => {
     try {
       const page = getSessionPage(session_id);
+      if (ref) {
+        await hoverRef(page, session_id, ref);
+        return json({ hovered: ref, method: "ref" });
+      }
+      if (!selector)
+        return err(new Error("Either ref or selector is required"));
       await hover(page, selector);
-      return json({ hovered: selector });
+      return json({ hovered: selector, method: "selector" });
     } catch (e) {
       return err(e);
     }
@@ -14833,20 +15543,32 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_select", "Select a dropdown option", { session_id: exports_external.string(), selector: exports_external.string(), value: exports_external.string() }, async ({ session_id, selector, value }) => {
+  server.tool("browser_select", "Select a dropdown option by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), value: exports_external.string() }, async ({ session_id, selector, ref, value }) => {
     try {
       const page = getSessionPage(session_id);
+      if (ref) {
+        const selected2 = await selectRef(page, session_id, ref, value);
+        return json({ selected: selected2, method: "ref" });
+      }
+      if (!selector)
+        return err(new Error("Either ref or selector is required"));
       const selected = await selectOption(page, selector, value);
-      return json({ selected });
+      return json({ selected, method: "selector" });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_check", "Check or uncheck a checkbox", { session_id: exports_external.string(), selector: exports_external.string(), checked: exports_external.boolean() }, async ({ session_id, selector, checked }) => {
+  server.tool("browser_check", "Check or uncheck a checkbox by ref or selector", { session_id: exports_external.string(), selector: exports_external.string().optional(), ref: exports_external.string().optional(), checked: exports_external.boolean() }, async ({ session_id, selector, ref, checked }) => {
     try {
       const page = getSessionPage(session_id);
+      if (ref) {
+        await checkRef(page, session_id, ref, checked);
+        return json({ checked, ref, method: "ref" });
+      }
+      if (!selector)
+        return err(new Error("Either ref or selector is required"));
       await checkBox(page, selector, checked);
-      return json({ checked, selector });
+      return json({ checked, selector, method: "selector" });
     } catch (e) {
       return err(e);
     }
@@ -14927,15 +15649,17 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
-  server.tool("browser_snapshot", "Get an accessibility (ARIA) snapshot of the page", { session_id: exports_external.string() }, async ({ session_id }) => {
+  server.tool("browser_snapshot", "Get a structured accessibility snapshot with element refs (@e0, @e1...). Use refs in browser_click, browser_type, etc.", { session_id: exports_external.string() }, async ({ session_id }) => {
     try {
       const page = getSessionPage(session_id);
-      return json({ snapshot: await getAriaSnapshot(page) });
+      const result = await takeSnapshot(page, session_id);
+      setLastSnapshot(session_id, result);
+      return json({ snapshot: result.tree, refs: result.refs, interactive_count: result.interactive_count });
     } catch (e) {
       return err(e);
     }
   });
-  server.tool("browser_screenshot", "Take a screenshot of the page or an element", {
+  server.tool("browser_screenshot", "Take a screenshot. Use annotate=true to overlay numbered labels on interactive elements for visual+ref workflows.", {
     session_id: exports_external.string(),
     selector: exports_external.string().optional(),
     full_page: exports_external.boolean().optional().default(false),
@@ -14943,17 +15667,37 @@ var init_mcp = __esm(async () => {
     quality: exports_external.number().optional(),
     max_width: exports_external.number().optional().default(1280),
     compress: exports_external.boolean().optional().default(true),
-    thumbnail: exports_external.boolean().optional().default(true)
-  }, async ({ session_id, selector, full_page, format, quality, max_width, compress, thumbnail }) => {
+    thumbnail: exports_external.boolean().optional().default(true),
+    annotate: exports_external.boolean().optional().default(false)
+  }, async ({ session_id, selector, full_page, format, quality, max_width, compress, thumbnail, annotate }) => {
     try {
       const page = getSessionPage(session_id);
+      if (annotate && !selector && !full_page) {
+        const { annotateScreenshot: annotateScreenshot2 } = await Promise.resolve().then(() => (init_annotate(), exports_annotate));
+        const annotated = await annotateScreenshot2(page, session_id);
+        const base64 = annotated.buffer.toString("base64");
+        return json({
+          base64: base64.length > 50000 ? undefined : base64,
+          base64_truncated: base64.length > 50000,
+          size_bytes: annotated.buffer.length,
+          annotations: annotated.annotations,
+          label_to_ref: annotated.labelToRef,
+          annotation_count: annotated.annotations.length
+        });
+      }
       const result = await takeScreenshot(page, { selector, fullPage: full_page, format, quality, maxWidth: max_width, compress, thumbnail });
+      result.url = page.url();
       try {
         const buf = Buffer.from(result.base64, "base64");
         const filename = result.path.split("/").pop() ?? `screenshot.${format ?? "webp"}`;
         const dl = saveToDownloads(buf, filename, { sessionId: session_id, type: "screenshot", sourceUrl: page.url() });
         result.download_id = dl.id;
       } catch {}
+      if (result.base64.length > 50000) {
+        result.base64_truncated = true;
+        result.full_image_path = result.path;
+        result.base64 = result.thumbnail_base64 ?? "";
+      }
       return json(result);
     } catch (e) {
       return err(e);
@@ -15248,6 +15992,37 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
+  server.tool("browser_scroll_and_screenshot", "Scroll the page and take a screenshot in one call. Saves 3 separate tool calls.", { session_id: exports_external.string(), direction: exports_external.enum(["up", "down", "left", "right"]).optional().default("down"), amount: exports_external.number().optional().default(500), wait_ms: exports_external.number().optional().default(300) }, async ({ session_id, direction, amount, wait_ms }) => {
+    try {
+      const page = getSessionPage(session_id);
+      await scroll(page, direction, amount);
+      await new Promise((r) => setTimeout(r, wait_ms));
+      const result = await takeScreenshot(page, { maxWidth: 1280, track: true });
+      result.url = page.url();
+      if (result.base64.length > 50000) {
+        result.base64_truncated = true;
+        result.full_image_path = result.path;
+        result.base64 = result.thumbnail_base64 ?? "";
+      }
+      return json({ scrolled: { direction, amount }, screenshot: result });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_wait_for_navigation", "Wait for URL change after a click or action. Returns the new URL and title.", { session_id: exports_external.string(), timeout: exports_external.number().optional().default(30000), url_pattern: exports_external.string().optional() }, async ({ session_id, timeout, url_pattern }) => {
+    try {
+      const page = getSessionPage(session_id);
+      const start = Date.now();
+      if (url_pattern) {
+        await page.waitForURL(url_pattern, { timeout });
+      } else {
+        await page.waitForLoadState("domcontentloaded", { timeout });
+      }
+      return json({ url: page.url(), title: await getTitle(page), elapsed_ms: Date.now() - start });
+    } catch (e) {
+      return err(e);
+    }
+  });
   server.tool("browser_session_get_by_name", "Get a session by its name", { name: exports_external.string() }, async ({ name }) => {
     try {
       const session = getSessionByName2(name);
@@ -15361,6 +16136,40 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
+  server.tool("browser_page_check", "One-call page summary: page info + console errors + performance metrics + thumbnail + accessibility snapshot preview. Replaces 4-5 separate tool calls.", { session_id: exports_external.string() }, async ({ session_id }) => {
+    try {
+      const page = getSessionPage(session_id);
+      const info = await getPageInfo(page);
+      const errors2 = getConsoleLog(session_id, "error");
+      info.has_console_errors = errors2.length > 0;
+      let perf = {};
+      try {
+        perf = await getPerformanceMetrics(page);
+      } catch {}
+      let thumbnail_base64 = "";
+      try {
+        const ss = await takeScreenshot(page, { maxWidth: 400, quality: 60, track: false, thumbnail: false });
+        thumbnail_base64 = ss.base64;
+      } catch {}
+      let snapshot_preview = "";
+      let interactive_count = 0;
+      try {
+        const snap = await takeSnapshot(page, session_id);
+        snapshot_preview = snap.tree.slice(0, 2000);
+        interactive_count = snap.interactive_count;
+      } catch {}
+      return json({
+        ...info,
+        error_count: errors2.length,
+        performance: perf,
+        thumbnail_base64: thumbnail_base64.length > 50000 ? "" : thumbnail_base64,
+        snapshot_preview,
+        interactive_count
+      });
+    } catch (e) {
+      return err(e);
+    }
+  });
   server.tool("browser_gallery_list", "List screenshot gallery entries with optional filters", {
     project_id: exports_external.string().optional(),
     session_id: exports_external.string().optional(),
@@ -15509,6 +16318,297 @@ var init_mcp = __esm(async () => {
       return err(e);
     }
   });
+  server.tool("browser_snapshot_diff", "Take a new accessibility snapshot and diff it against the last snapshot for this session. Shows added/removed/modified interactive elements.", { session_id: exports_external.string() }, async ({ session_id }) => {
+    try {
+      const page = getSessionPage(session_id);
+      const before = getLastSnapshot(session_id);
+      const after = await takeSnapshot(page, session_id);
+      setLastSnapshot(session_id, after);
+      if (!before) {
+        return json({
+          message: "No previous snapshot \u2014 returning current snapshot only.",
+          snapshot: after.tree,
+          refs: after.refs,
+          interactive_count: after.interactive_count
+        });
+      }
+      const diff = diffSnapshots(before, after);
+      return json({
+        diff,
+        added_count: diff.added.length,
+        removed_count: diff.removed.length,
+        modified_count: diff.modified.length,
+        url_changed: diff.url_changed,
+        title_changed: diff.title_changed,
+        current_interactive_count: after.interactive_count
+      });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_session_stats", "Get session info and estimated token usage (based on network log, console log, and gallery entry sizes).", { session_id: exports_external.string() }, async ({ session_id }) => {
+    try {
+      const session = getSession2(session_id);
+      const networkLog = getNetworkLog(session_id);
+      const consoleLog = getConsoleLog(session_id);
+      const galleryEntries = listEntries({ sessionId: session_id, limit: 1000 });
+      let totalChars = 0;
+      for (const req of networkLog) {
+        totalChars += (req.url?.length ?? 0) + (req.request_headers?.length ?? 0) + (req.response_headers?.length ?? 0) + (req.request_body?.length ?? 0);
+      }
+      for (const msg of consoleLog) {
+        totalChars += (msg.message?.length ?? 0) + (msg.source?.length ?? 0);
+      }
+      for (const entry of galleryEntries) {
+        totalChars += (entry.url?.length ?? 0) + (entry.title?.length ?? 0) + (entry.notes?.length ?? 0) + (entry.tags?.join(",").length ?? 0);
+      }
+      const estimatedTokens = Math.ceil(totalChars / 4);
+      const tokenBudget = getTokenBudget(session_id);
+      return json({
+        session,
+        network_request_count: networkLog.length,
+        console_message_count: consoleLog.length,
+        gallery_entry_count: galleryEntries.length,
+        estimated_tokens_used: estimatedTokens,
+        token_budget: tokenBudget,
+        data_size_chars: totalChars
+      });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_tab_new", "Open a new tab in the session's browser context, optionally navigating to a URL", { session_id: exports_external.string(), url: exports_external.string().optional() }, async ({ session_id, url }) => {
+    try {
+      const page = getSessionPage(session_id);
+      const tab = await newTab(page, url);
+      return json(tab);
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_tab_list", "List all open tabs in the session's browser context", { session_id: exports_external.string() }, async ({ session_id }) => {
+    try {
+      const page = getSessionPage(session_id);
+      const tabs = await listTabs(page);
+      return json({ tabs, count: tabs.length });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_tab_switch", "Switch to a different tab by index. Updates the session's active page.", { session_id: exports_external.string(), tab_id: exports_external.number() }, async ({ session_id, tab_id }) => {
+    try {
+      const page = getSessionPage(session_id);
+      const result = await switchTab(page, tab_id);
+      setSessionPage(session_id, result.page);
+      return json(result.tab);
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_tab_close", "Close a tab by index. Cannot close the last tab.", { session_id: exports_external.string(), tab_id: exports_external.number() }, async ({ session_id, tab_id }) => {
+    try {
+      const page = getSessionPage(session_id);
+      const context = page.context();
+      const result = await closeTab(page, tab_id);
+      const remainingPages = context.pages();
+      const newActivePage = remainingPages[result.active_tab.index];
+      if (newActivePage) {
+        setSessionPage(session_id, newActivePage);
+      }
+      return json(result);
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_handle_dialog", "Accept or dismiss a pending dialog (alert, confirm, prompt). Handles the oldest pending dialog.", { session_id: exports_external.string(), action: exports_external.enum(["accept", "dismiss"]), prompt_text: exports_external.string().optional() }, async ({ session_id, action, prompt_text }) => {
+    try {
+      const result = await handleDialog(session_id, action, prompt_text);
+      if (!result.handled)
+        return err(new Error("No pending dialogs for this session"));
+      return json(result);
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_get_dialogs", "Get all pending dialogs for a session", { session_id: exports_external.string() }, async ({ session_id }) => {
+    try {
+      const dialogs = getDialogs(session_id);
+      return json({ dialogs, count: dialogs.length });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_profile_save", "Save cookies + localStorage from the current session as a named profile", { session_id: exports_external.string(), name: exports_external.string() }, async ({ session_id, name }) => {
+    try {
+      const page = getSessionPage(session_id);
+      const info = await saveProfile(page, name);
+      return json(info);
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_profile_load", "Load a saved profile and apply cookies + localStorage to the current session", { session_id: exports_external.string().optional(), name: exports_external.string() }, async ({ session_id, name }) => {
+    try {
+      const profileData = loadProfile(name);
+      if (session_id) {
+        const page = getSessionPage(session_id);
+        const applied = await applyProfile(page, profileData);
+        return json({ ...applied, profile: name });
+      }
+      return json({ profile: name, cookies: profileData.cookies.length, storage_keys: Object.keys(profileData.localStorage).length });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_profile_list", "List all saved browser profiles", {}, async () => {
+    try {
+      return json({ profiles: listProfiles() });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_profile_delete", "Delete a saved browser profile", { name: exports_external.string() }, async ({ name }) => {
+    try {
+      const deleted = deleteProfile(name);
+      if (!deleted)
+        return err(new Error(`Profile not found: ${name}`));
+      return json({ deleted: name });
+    } catch (e) {
+      return err(e);
+    }
+  });
+  server.tool("browser_help", "Show all available browser tools grouped by category with one-line descriptions", {}, async () => {
+    try {
+      const groups = {
+        Navigation: [
+          { tool: "browser_navigate", description: "Navigate to a URL" },
+          { tool: "browser_back", description: "Navigate back in history" },
+          { tool: "browser_forward", description: "Navigate forward in history" },
+          { tool: "browser_reload", description: "Reload the current page" },
+          { tool: "browser_wait_for_navigation", description: "Wait for URL change after action" }
+        ],
+        Interaction: [
+          { tool: "browser_click", description: "Click element by ref or selector" },
+          { tool: "browser_click_text", description: "Click element by visible text" },
+          { tool: "browser_type", description: "Type text into an element" },
+          { tool: "browser_hover", description: "Hover over an element" },
+          { tool: "browser_scroll", description: "Scroll the page" },
+          { tool: "browser_select", description: "Select a dropdown option" },
+          { tool: "browser_check", description: "Check/uncheck a checkbox" },
+          { tool: "browser_upload", description: "Upload a file to an input" },
+          { tool: "browser_press_key", description: "Press a keyboard key" },
+          { tool: "browser_wait", description: "Wait for a selector to appear" },
+          { tool: "browser_wait_for_text", description: "Wait for text to appear" },
+          { tool: "browser_fill_form", description: "Fill multiple form fields at once" },
+          { tool: "browser_handle_dialog", description: "Accept or dismiss a dialog" }
+        ],
+        Extraction: [
+          { tool: "browser_get_text", description: "Get text content from page/selector" },
+          { tool: "browser_get_html", description: "Get HTML content from page/selector" },
+          { tool: "browser_get_links", description: "Get all links on the page" },
+          { tool: "browser_get_page_info", description: "Full page summary in one call" },
+          { tool: "browser_extract", description: "Extract content in various formats" },
+          { tool: "browser_find", description: "Find elements by selector" },
+          { tool: "browser_element_exists", description: "Check if a selector exists" },
+          { tool: "browser_snapshot", description: "Get accessibility snapshot with refs" },
+          { tool: "browser_evaluate", description: "Execute JavaScript in page context" }
+        ],
+        Capture: [
+          { tool: "browser_screenshot", description: "Take a screenshot (PNG/JPEG/WebP)" },
+          { tool: "browser_pdf", description: "Generate a PDF of the page" },
+          { tool: "browser_scroll_and_screenshot", description: "Scroll then screenshot in one call" }
+        ],
+        Storage: [
+          { tool: "browser_cookies_get", description: "Get cookies" },
+          { tool: "browser_cookies_set", description: "Set a cookie" },
+          { tool: "browser_cookies_clear", description: "Clear cookies" },
+          { tool: "browser_storage_get", description: "Get localStorage/sessionStorage" },
+          { tool: "browser_storage_set", description: "Set localStorage/sessionStorage" },
+          { tool: "browser_profile_save", description: "Save cookies + localStorage as profile" },
+          { tool: "browser_profile_load", description: "Load and apply a saved profile" },
+          { tool: "browser_profile_list", description: "List saved profiles" },
+          { tool: "browser_profile_delete", description: "Delete a saved profile" }
+        ],
+        Network: [
+          { tool: "browser_network_log", description: "Get captured network requests" },
+          { tool: "browser_network_intercept", description: "Add a network interception rule" },
+          { tool: "browser_har_start", description: "Start HAR capture" },
+          { tool: "browser_har_stop", description: "Stop HAR capture and get data" }
+        ],
+        Performance: [
+          { tool: "browser_performance", description: "Get performance metrics" }
+        ],
+        Console: [
+          { tool: "browser_console_log", description: "Get console messages" },
+          { tool: "browser_has_errors", description: "Check for console errors" },
+          { tool: "browser_clear_errors", description: "Clear console error log" },
+          { tool: "browser_get_dialogs", description: "Get pending dialogs" }
+        ],
+        Recording: [
+          { tool: "browser_record_start", description: "Start recording actions" },
+          { tool: "browser_record_step", description: "Add a step to recording" },
+          { tool: "browser_record_stop", description: "Stop and save recording" },
+          { tool: "browser_record_replay", description: "Replay a recorded sequence" },
+          { tool: "browser_recordings_list", description: "List all recordings" }
+        ],
+        Crawl: [
+          { tool: "browser_crawl", description: "Crawl a URL recursively" }
+        ],
+        Agent: [
+          { tool: "browser_register_agent", description: "Register an agent" },
+          { tool: "browser_heartbeat", description: "Send agent heartbeat" },
+          { tool: "browser_agent_list", description: "List registered agents" }
+        ],
+        Project: [
+          { tool: "browser_project_create", description: "Create or ensure a project" },
+          { tool: "browser_project_list", description: "List all projects" }
+        ],
+        Gallery: [
+          { tool: "browser_gallery_list", description: "List screenshot gallery entries" },
+          { tool: "browser_gallery_get", description: "Get a gallery entry by id" },
+          { tool: "browser_gallery_tag", description: "Add a tag to gallery entry" },
+          { tool: "browser_gallery_untag", description: "Remove a tag from gallery entry" },
+          { tool: "browser_gallery_favorite", description: "Mark/unmark as favorite" },
+          { tool: "browser_gallery_delete", description: "Delete a gallery entry" },
+          { tool: "browser_gallery_search", description: "Search gallery entries" },
+          { tool: "browser_gallery_stats", description: "Get gallery statistics" },
+          { tool: "browser_gallery_diff", description: "Pixel-diff two screenshots" }
+        ],
+        Downloads: [
+          { tool: "browser_downloads_list", description: "List downloaded files" },
+          { tool: "browser_downloads_get", description: "Get a download by id" },
+          { tool: "browser_downloads_delete", description: "Delete a download" },
+          { tool: "browser_downloads_clean", description: "Clean old downloads" },
+          { tool: "browser_downloads_export", description: "Copy download to a path" },
+          { tool: "browser_persist_file", description: "Persist file permanently" }
+        ],
+        Session: [
+          { tool: "browser_session_create", description: "Create a new browser session" },
+          { tool: "browser_session_list", description: "List all sessions" },
+          { tool: "browser_session_close", description: "Close a session" },
+          { tool: "browser_session_get_by_name", description: "Get session by name" },
+          { tool: "browser_session_rename", description: "Rename a session" },
+          { tool: "browser_session_stats", description: "Get session stats and token usage" },
+          { tool: "browser_tab_new", description: "Open a new tab" },
+          { tool: "browser_tab_list", description: "List all open tabs" },
+          { tool: "browser_tab_switch", description: "Switch to a tab by index" },
+          { tool: "browser_tab_close", description: "Close a tab by index" }
+        ],
+        Meta: [
+          { tool: "browser_page_check", description: "One-call page summary with diagnostics" },
+          { tool: "browser_help", description: "Show this help (all tools)" },
+          { tool: "browser_snapshot_diff", description: "Diff current snapshot vs previous" },
+          { tool: "browser_watch_start", description: "Watch page for DOM changes" },
+          { tool: "browser_watch_get_changes", description: "Get captured DOM changes" },
+          { tool: "browser_watch_stop", description: "Stop DOM watcher" }
+        ]
+      };
+      const totalTools = Object.values(groups).reduce((sum, g) => sum + g.length, 0);
+      return json({ groups, total_tools: totalTools });
+    } catch (e) {
+      return err(e);
+    }
+  });
   transport = new StdioServerTransport;
   await server.connect(transport);
 });
@@ -15551,8 +16651,8 @@ var init_snapshots = __esm(() => {
 
 // src/server/index.ts
 var exports_server = {};
-import { join as join6 } from "path";
-import { existsSync as existsSync3 } from "fs";
+import { join as join7 } from "path";
+import { existsSync as existsSync4 } from "fs";
 function ok(data, status = 200) {
   return new Response(JSON.stringify(data), {
     status,
@@ -15802,14 +16902,14 @@ var init_server = __esm(() => {
         if (path.match(/^\/api\/gallery\/([^/]+)\/thumbnail$/) && method === "GET") {
           const id = path.split("/")[3];
           const entry = getEntry(id);
-          if (!entry?.thumbnail_path || !existsSync3(entry.thumbnail_path))
+          if (!entry?.thumbnail_path || !existsSync4(entry.thumbnail_path))
             return notFound("Thumbnail not found");
           return new Response(Bun.file(entry.thumbnail_path), { headers: { ...CORS_HEADERS } });
         }
         if (path.match(/^\/api\/gallery\/([^/]+)\/image$/) && method === "GET") {
           const id = path.split("/")[3];
           const entry = getEntry(id);
-          if (!entry?.path || !existsSync3(entry.path))
+          if (!entry?.path || !existsSync4(entry.path))
             return notFound("Image not found");
           return new Response(Bun.file(entry.path), { headers: { ...CORS_HEADERS } });
         }
@@ -15837,7 +16937,7 @@ var init_server = __esm(() => {
         if (path.match(/^\/api\/downloads\/([^/]+)\/raw$/) && method === "GET") {
           const id = path.split("/")[3];
           const file = getDownload(id);
-          if (!file || !existsSync3(file.path))
+          if (!file || !existsSync4(file.path))
             return notFound("Download not found");
           return new Response(Bun.file(file.path), { headers: { ...CORS_HEADERS } });
         }
@@ -15845,13 +16945,13 @@ var init_server = __esm(() => {
           const id = path.split("/")[3];
           return ok({ deleted: deleteDownload(id) });
         }
-        const dashboardDist = join6(import.meta.dir, "../../dashboard/dist");
-        if (existsSync3(dashboardDist)) {
-          const filePath = path === "/" ? join6(dashboardDist, "index.html") : join6(dashboardDist, path);
-          if (existsSync3(filePath)) {
+        const dashboardDist = join7(import.meta.dir, "../../dashboard/dist");
+        if (existsSync4(dashboardDist)) {
+          const filePath = path === "/" ? join7(dashboardDist, "index.html") : join7(dashboardDist, path);
+          if (existsSync4(filePath)) {
             return new Response(Bun.file(filePath), { headers: CORS_HEADERS });
           }
-          return new Response(Bun.file(join6(dashboardDist, "index.html")), { headers: CORS_HEADERS });
+          return new Response(Bun.file(join7(dashboardDist, "index.html")), { headers: CORS_HEADERS });
         }
         if (path === "/" || path === "") {
           return new Response("@hasna/browser REST API running. Dashboard not built.", {
@@ -15893,9 +16993,12 @@ init_projects();
 init_recorder();
 init_recordings();
 init_lightpanda();
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join8 } from "path";
 import chalk from "chalk";
+var pkg = JSON.parse(readFileSync3(join8(import.meta.dir, "../../package.json"), "utf8"));
 var program2 = new Command;
-program2.name("browser").description("@hasna/browser \u2014 general-purpose browser agent CLI").version("0.0.1");
+program2.name("browser").description("@hasna/browser \u2014 general-purpose browser agent CLI").version(pkg.version);
 program2.command("navigate <url>").description("Navigate to a URL and optionally take a screenshot").option("--engine <engine>", "Browser engine: playwright|cdp|lightpanda|auto", "auto").option("--screenshot", "Take a screenshot after navigation").option("--extract", "Extract page text after navigation").option("--headless", "Run in headless mode (default: true)", true).action(async (url, opts) => {
   const { session, page } = await createSession2({ engine: opts.engine, headless: true });
   console.log(chalk.gray(`Session: ${session.id} (${session.engine})`));
@@ -16136,11 +17239,11 @@ galleryCmd.command("stats").description("Show gallery statistics").option("--pro
 });
 galleryCmd.command("clean").description("Delete gallery entries with missing files").action(async () => {
   const { listEntries: listEntries2, deleteEntry: deleteEntry2 } = await Promise.resolve().then(() => (init_gallery(), exports_gallery));
-  const { existsSync: existsSync4 } = await import("fs");
+  const { existsSync: existsSync5 } = await import("fs");
   const entries = listEntries2({ limit: 9999 });
   let removed = 0;
   for (const e of entries) {
-    if (!existsSync4(e.path)) {
+    if (!existsSync5(e.path)) {
       deleteEntry2(e.id);
       removed++;
     }