browserclaw 0.1.0

package/dist/index.js

@@ -0,0 +1,2173 @@
+import os from 'os';
+import path from 'path';
+import fs from 'fs';
+import net from 'net';
+import { spawn, execFileSync } from 'child_process';
+import { chromium } from 'playwright-core';
+
+// src/chrome-launcher.ts
+var CHROMIUM_BUNDLE_IDS = /* @__PURE__ */ new Set([
+  "com.google.Chrome",
+  "com.google.Chrome.beta",
+  "com.google.Chrome.canary",
+  "com.google.Chrome.dev",
+  "com.brave.Browser",
+  "com.brave.Browser.beta",
+  "com.brave.Browser.nightly",
+  "com.microsoft.Edge",
+  "com.microsoft.EdgeBeta",
+  "com.microsoft.EdgeDev",
+  "com.microsoft.EdgeCanary",
+  "org.chromium.Chromium",
+  "com.vivaldi.Vivaldi",
+  "com.operasoftware.Opera",
+  "com.operasoftware.OperaGX",
+  "com.yandex.desktop.yandex-browser",
+  "company.thebrowser.Browser"
+]);
+var CHROMIUM_DESKTOP_IDS = /* @__PURE__ */ new Set([
+  "google-chrome.desktop",
+  "google-chrome-beta.desktop",
+  "google-chrome-unstable.desktop",
+  "brave-browser.desktop",
+  "microsoft-edge.desktop",
+  "microsoft-edge-beta.desktop",
+  "microsoft-edge-dev.desktop",
+  "microsoft-edge-canary.desktop",
+  "chromium.desktop",
+  "chromium-browser.desktop",
+  "vivaldi.desktop",
+  "vivaldi-stable.desktop",
+  "opera.desktop",
+  "opera-gx.desktop",
+  "yandex-browser.desktop",
+  "org.chromium.Chromium.desktop"
+]);
+var CHROMIUM_EXE_NAMES = /* @__PURE__ */ new Set([
+  "chrome.exe",
+  "msedge.exe",
+  "brave.exe",
+  "brave-browser.exe",
+  "chromium.exe",
+  "vivaldi.exe",
+  "opera.exe",
+  "launcher.exe",
+  "yandex.exe",
+  "yandexbrowser.exe",
+  "google chrome",
+  "google chrome canary",
+  "brave browser",
+  "microsoft edge",
+  "chromium",
+  "chrome",
+  "brave",
+  "msedge",
+  "brave-browser",
+  "google-chrome",
+  "google-chrome-stable",
+  "google-chrome-beta",
+  "google-chrome-unstable",
+  "microsoft-edge",
+  "microsoft-edge-beta",
+  "microsoft-edge-dev",
+  "microsoft-edge-canary",
+  "chromium-browser",
+  "vivaldi",
+  "vivaldi-stable",
+  "opera",
+  "opera-stable",
+  "opera-gx",
+  "yandex-browser"
+]);
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+function execText(command, args, timeoutMs = 1200) {
+  try {
+    const output = execFileSync(command, args, {
+      timeout: timeoutMs,
+      encoding: "utf8",
+      maxBuffer: 1024 * 1024
+    });
+    return String(output ?? "").trim() || null;
+  } catch {
+    return null;
+  }
+}
+function inferKindFromIdentifier(identifier) {
+  const id = identifier.toLowerCase();
+  if (id.includes("brave")) return "brave";
+  if (id.includes("edge")) return "edge";
+  if (id.includes("chromium")) return "chromium";
+  if (id.includes("canary")) return "canary";
+  if (id.includes("opera") || id.includes("vivaldi") || id.includes("yandex") || id.includes("thebrowser")) return "chromium";
+  return "chrome";
+}
+function inferKindFromExeName(name) {
+  const lower = name.toLowerCase();
+  if (lower.includes("brave")) return "brave";
+  if (lower.includes("edge") || lower.includes("msedge")) return "edge";
+  if (lower.includes("chromium")) return "chromium";
+  if (lower.includes("canary") || lower.includes("sxs")) return "canary";
+  if (lower.includes("opera") || lower.includes("vivaldi") || lower.includes("yandex")) return "chromium";
+  return "chrome";
+}
+function findFirstExe(candidates) {
+  for (const c of candidates) if (fileExists(c.path)) return c;
+  return null;
+}
+function detectDefaultBrowserBundleIdMac() {
+  const plistPath = path.join(os.homedir(), "Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist");
+  if (!fileExists(plistPath)) return null;
+  const handlersRaw = execText("/usr/bin/plutil", ["-extract", "LSHandlers", "json", "-o", "-", "--", plistPath], 2e3);
+  if (!handlersRaw) return null;
+  let handlers;
+  try {
+    handlers = JSON.parse(handlersRaw);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(handlers)) return null;
+  const resolveScheme = (scheme) => {
+    let candidate = null;
+    for (const entry of handlers) {
+      if (!entry || typeof entry !== "object") continue;
+      if (entry.LSHandlerURLScheme !== scheme) continue;
+      const role = typeof entry.LSHandlerRoleAll === "string" && entry.LSHandlerRoleAll || typeof entry.LSHandlerRoleViewer === "string" && entry.LSHandlerRoleViewer || null;
+      if (role) candidate = role;
+    }
+    return candidate;
+  };
+  return resolveScheme("http") ?? resolveScheme("https");
+}
+function detectDefaultChromiumMac() {
+  const bundleId = detectDefaultBrowserBundleIdMac();
+  if (!bundleId || !CHROMIUM_BUNDLE_IDS.has(bundleId)) return null;
+  const appPathRaw = execText("/usr/bin/osascript", ["-e", `POSIX path of (path to application id "${bundleId}")`]);
+  if (!appPathRaw) return null;
+  const appPath = appPathRaw.trim().replace(/\/$/, "");
+  const exeName = execText("/usr/bin/defaults", ["read", path.join(appPath, "Contents", "Info"), "CFBundleExecutable"]);
+  if (!exeName) return null;
+  const exePath = path.join(appPath, "Contents", "MacOS", exeName.trim());
+  if (!fileExists(exePath)) return null;
+  return { kind: inferKindFromIdentifier(bundleId), path: exePath };
+}
+function findChromeMac() {
+  return findFirstExe([
+    { kind: "chrome", path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" },
+    { kind: "chrome", path: path.join(os.homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome") },
+    { kind: "brave", path: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" },
+    { kind: "brave", path: path.join(os.homedir(), "Applications/Brave Browser.app/Contents/MacOS/Brave Browser") },
+    { kind: "edge", path: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" },
+    { kind: "edge", path: path.join(os.homedir(), "Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge") },
+    { kind: "chromium", path: "/Applications/Chromium.app/Contents/MacOS/Chromium" },
+    { kind: "chromium", path: path.join(os.homedir(), "Applications/Chromium.app/Contents/MacOS/Chromium") },
+    { kind: "canary", path: "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary" },
+    { kind: "canary", path: path.join(os.homedir(), "Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary") }
+  ]);
+}
+function detectDefaultChromiumLinux() {
+  const desktopId = execText("xdg-settings", ["get", "default-web-browser"]) || execText("xdg-mime", ["query", "default", "x-scheme-handler/http"]);
+  if (!desktopId) return null;
+  const trimmed = desktopId.trim();
+  if (!CHROMIUM_DESKTOP_IDS.has(trimmed)) return null;
+  const searchDirs = [
+    path.join(os.homedir(), ".local", "share", "applications"),
+    "/usr/local/share/applications",
+    "/usr/share/applications",
+    "/var/lib/snapd/desktop/applications"
+  ];
+  let desktopPath = null;
+  for (const dir of searchDirs) {
+    const candidate = path.join(dir, trimmed);
+    if (fileExists(candidate)) {
+      desktopPath = candidate;
+      break;
+    }
+  }
+  if (!desktopPath) return null;
+  let execLine = null;
+  try {
+    const lines = fs.readFileSync(desktopPath, "utf8").split(/\r?\n/);
+    for (const line of lines) if (line.startsWith("Exec=")) {
+      execLine = line.slice(5).trim();
+      break;
+    }
+  } catch {
+  }
+  if (!execLine) return null;
+  const tokens = execLine.split(/\s+/);
+  let command = null;
+  for (const token of tokens) {
+    if (!token || token === "env" || token.includes("=") && !token.startsWith("/")) continue;
+    command = token.replace(/^["']|["']$/g, "");
+    break;
+  }
+  if (!command) return null;
+  const resolved = command.startsWith("/") ? command : execText("which", [command], 800)?.trim() ?? null;
+  if (!resolved) return null;
+  const exeName = path.posix.basename(resolved).toLowerCase();
+  if (!CHROMIUM_EXE_NAMES.has(exeName)) return null;
+  return { kind: inferKindFromExeName(exeName), path: resolved };
+}
+function findChromeLinux() {
+  return findFirstExe([
+    { kind: "chrome", path: "/usr/bin/google-chrome" },
+    { kind: "chrome", path: "/usr/bin/google-chrome-stable" },
+    { kind: "chrome", path: "/usr/bin/chrome" },
+    { kind: "brave", path: "/usr/bin/brave-browser" },
+    { kind: "brave", path: "/usr/bin/brave-browser-stable" },
+    { kind: "brave", path: "/usr/bin/brave" },
+    { kind: "brave", path: "/snap/bin/brave" },
+    { kind: "edge", path: "/usr/bin/microsoft-edge" },
+    { kind: "edge", path: "/usr/bin/microsoft-edge-stable" },
+    { kind: "chromium", path: "/usr/bin/chromium" },
+    { kind: "chromium", path: "/usr/bin/chromium-browser" },
+    { kind: "chromium", path: "/snap/bin/chromium" }
+  ]);
+}
+function findChromeWindows() {
+  const localAppData = process.env.LOCALAPPDATA ?? "";
+  const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
+  const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+  const j = path.win32.join;
+  const candidates = [];
+  if (localAppData) {
+    candidates.push({ kind: "chrome", path: j(localAppData, "Google", "Chrome", "Application", "chrome.exe") });
+    candidates.push({ kind: "brave", path: j(localAppData, "BraveSoftware", "Brave-Browser", "Application", "brave.exe") });
+    candidates.push({ kind: "edge", path: j(localAppData, "Microsoft", "Edge", "Application", "msedge.exe") });
+    candidates.push({ kind: "chromium", path: j(localAppData, "Chromium", "Application", "chrome.exe") });
+    candidates.push({ kind: "canary", path: j(localAppData, "Google", "Chrome SxS", "Application", "chrome.exe") });
+  }
+  candidates.push({ kind: "chrome", path: j(programFiles, "Google", "Chrome", "Application", "chrome.exe") });
+  candidates.push({ kind: "chrome", path: j(programFilesX86, "Google", "Chrome", "Application", "chrome.exe") });
+  candidates.push({ kind: "brave", path: j(programFiles, "BraveSoftware", "Brave-Browser", "Application", "brave.exe") });
+  candidates.push({ kind: "brave", path: j(programFilesX86, "BraveSoftware", "Brave-Browser", "Application", "brave.exe") });
+  candidates.push({ kind: "edge", path: j(programFiles, "Microsoft", "Edge", "Application", "msedge.exe") });
+  candidates.push({ kind: "edge", path: j(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe") });
+  return findFirstExe(candidates);
+}
+function resolveBrowserExecutable(opts) {
+  if (opts?.executablePath) {
+    if (!fileExists(opts.executablePath)) throw new Error(`executablePath not found: ${opts.executablePath}`);
+    return { kind: "custom", path: opts.executablePath };
+  }
+  const platform = process.platform;
+  if (platform === "darwin") return detectDefaultChromiumMac() ?? findChromeMac();
+  if (platform === "linux") return detectDefaultChromiumLinux() ?? findChromeLinux();
+  if (platform === "win32") return findChromeWindows();
+  return null;
+}
+async function ensurePortAvailable(port) {
+  await new Promise((resolve, reject) => {
+    const tester = net.createServer().once("error", (err) => {
+      if (err.code === "EADDRINUSE") reject(new Error(`Port ${port} is already in use`));
+      else reject(err);
+    }).once("listening", () => {
+      tester.close(() => resolve());
+    }).listen(port);
+  });
+}
+function safeReadJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function safeWriteJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+function setDeep(obj, keys, value) {
+  let node = obj;
+  for (const key of keys.slice(0, -1)) {
+    const next = node[key];
+    if (typeof next !== "object" || next === null || Array.isArray(next)) node[key] = {};
+    node = node[key];
+  }
+  node[keys[keys.length - 1]] = value;
+}
+function parseHexRgbToSignedArgbInt(hex) {
+  const cleaned = hex.trim().replace(/^#/, "");
+  if (!/^[0-9a-fA-F]{6}$/.test(cleaned)) return null;
+  const argbUnsigned = 255 << 24 | Number.parseInt(cleaned, 16);
+  return argbUnsigned > 2147483647 ? argbUnsigned - 4294967296 : argbUnsigned;
+}
+function decorateProfile(userDataDir, name, color) {
+  const colorInt = parseHexRgbToSignedArgbInt(color);
+  const localStatePath = path.join(userDataDir, "Local State");
+  const preferencesPath = path.join(userDataDir, "Default", "Preferences");
+  const localState = safeReadJson(localStatePath) ?? {};
+  setDeep(localState, ["profile", "info_cache", "Default", "name"], name);
+  setDeep(localState, ["profile", "info_cache", "Default", "shortcut_name"], name);
+  setDeep(localState, ["profile", "info_cache", "Default", "user_name"], name);
+  setDeep(localState, ["profile", "info_cache", "Default", "profile_color"], color);
+  if (colorInt != null) {
+    setDeep(localState, ["profile", "info_cache", "Default", "profile_color_seed"], colorInt);
+    setDeep(localState, ["profile", "info_cache", "Default", "profile_highlight_color"], colorInt);
+  }
+  safeWriteJson(localStatePath, localState);
+  const prefs = safeReadJson(preferencesPath) ?? {};
+  setDeep(prefs, ["profile", "name"], name);
+  setDeep(prefs, ["profile", "profile_color"], color);
+  if (colorInt != null) {
+    setDeep(prefs, ["autogenerated", "theme", "color"], colorInt);
+    setDeep(prefs, ["browser", "theme", "user_color2"], colorInt);
+  }
+  safeWriteJson(preferencesPath, prefs);
+}
+function ensureCleanExit(userDataDir) {
+  const preferencesPath = path.join(userDataDir, "Default", "Preferences");
+  const prefs = safeReadJson(preferencesPath) ?? {};
+  setDeep(prefs, ["exit_type"], "Normal");
+  setDeep(prefs, ["exited_cleanly"], true);
+  safeWriteJson(preferencesPath, prefs);
+}
+var DEFAULT_CDP_PORT = 9222;
+var DEFAULT_PROFILE_NAME = "browserclaw";
+var DEFAULT_PROFILE_COLOR = "#FF4500";
+function resolveUserDataDir(profileName) {
+  const configDir = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+  return path.join(configDir, "browserclaw", "profiles", profileName, "user-data");
+}
+async function isChromeReachable(cdpUrl, timeoutMs = 500) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(t);
+  }
+}
+async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${cdpUrl.replace(/\/+$/, "")}/json/version`, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return String(data?.webSocketDebuggerUrl ?? "").trim() || null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+async function launchChrome(opts = {}) {
+  const cdpPort = opts.cdpPort ?? DEFAULT_CDP_PORT;
+  await ensurePortAvailable(cdpPort);
+  const exe = resolveBrowserExecutable({ executablePath: opts.executablePath });
+  if (!exe) throw new Error("No supported browser found (Chrome/Brave/Edge/Chromium). Install one or provide executablePath.");
+  const profileName = opts.profileName ?? DEFAULT_PROFILE_NAME;
+  const userDataDir = opts.userDataDir ?? resolveUserDataDir(profileName);
+  fs.mkdirSync(userDataDir, { recursive: true });
+  const spawnChrome = () => {
+    const args = [
+      `--remote-debugging-port=${cdpPort}`,
+      `--user-data-dir=${userDataDir}`,
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--disable-sync",
+      "--disable-background-networking",
+      "--disable-component-update",
+      "--disable-features=Translate,MediaRouter",
+      "--disable-session-crashed-bubble",
+      "--hide-crash-restore-bubble",
+      "--password-store=basic"
+    ];
+    if (opts.headless) {
+      args.push("--headless=new", "--disable-gpu");
+    }
+    if (opts.noSandbox) {
+      args.push("--no-sandbox", "--disable-setuid-sandbox");
+    }
+    if (process.platform === "linux") args.push("--disable-dev-shm-usage");
+    if (opts.chromeArgs?.length) args.push(...opts.chromeArgs);
+    args.push("about:blank");
+    return spawn(exe.path, args, {
+      stdio: "pipe",
+      env: { ...process.env, HOME: os.homedir() }
+    });
+  };
+  const startedAt = Date.now();
+  const localStatePath = path.join(userDataDir, "Local State");
+  const preferencesPath = path.join(userDataDir, "Default", "Preferences");
+  if (!fileExists(localStatePath) || !fileExists(preferencesPath)) {
+    const bootstrap = spawnChrome();
+    const deadline = Date.now() + 1e4;
+    while (Date.now() < deadline) {
+      if (fileExists(localStatePath) && fileExists(preferencesPath)) break;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    try {
+      bootstrap.kill("SIGTERM");
+    } catch {
+    }
+    const exitDeadline = Date.now() + 5e3;
+    while (Date.now() < exitDeadline) {
+      if (bootstrap.exitCode != null) break;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+  try {
+    decorateProfile(userDataDir, profileName, opts.profileColor ?? DEFAULT_PROFILE_COLOR);
+  } catch {
+  }
+  try {
+    ensureCleanExit(userDataDir);
+  } catch {
+  }
+  const proc = spawnChrome();
+  const cdpUrl = `http://127.0.0.1:${cdpPort}`;
+  const readyDeadline = Date.now() + 15e3;
+  while (Date.now() < readyDeadline) {
+    if (await isChromeReachable(cdpUrl, 500)) break;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  if (!await isChromeReachable(cdpUrl, 500)) {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+    }
+    throw new Error(`Failed to start Chrome CDP on port ${cdpPort}. Chrome may not have started correctly.`);
+  }
+  return {
+    pid: proc.pid ?? -1,
+    exe,
+    userDataDir,
+    cdpPort,
+    startedAt,
+    proc
+  };
+}
+async function stopChrome(running, timeoutMs = 2500) {
+  const proc = running.proc;
+  if (proc.killed) return;
+  try {
+    proc.kill("SIGTERM");
+  } catch {
+  }
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (proc.exitCode != null || proc.killed) return;
+    if (!await isChromeReachable(`http://127.0.0.1:${running.cdpPort}`, 200)) return;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  try {
+    proc.kill("SIGKILL");
+  } catch {
+  }
+}
+var cached = null;
+var connecting = null;
+var pageStates = /* @__PURE__ */ new WeakMap();
+var contextStates = /* @__PURE__ */ new WeakMap();
+var observedContexts = /* @__PURE__ */ new WeakSet();
+var observedPages = /* @__PURE__ */ new WeakSet();
+var roleRefsByTarget = /* @__PURE__ */ new Map();
+var MAX_ROLE_REFS_CACHE = 50;
+var MAX_CONSOLE_MESSAGES = 500;
+var MAX_PAGE_ERRORS = 200;
+var MAX_NETWORK_REQUESTS = 500;
+function normalizeCdpUrl(raw) {
+  return raw.replace(/\/$/, "");
+}
+function roleRefsKey(cdpUrl, targetId) {
+  return `${normalizeCdpUrl(cdpUrl)}::${targetId}`;
+}
+function ensurePageState(page) {
+  const existing = pageStates.get(page);
+  if (existing) return existing;
+  const state = {
+    console: [],
+    errors: [],
+    requests: [],
+    requestIds: /* @__PURE__ */ new WeakMap(),
+    nextRequestId: 0,
+    armIdUpload: 0,
+    armIdDialog: 0,
+    armIdDownload: 0
+  };
+  pageStates.set(page, state);
+  if (!observedPages.has(page)) {
+    observedPages.add(page);
+    page.on("console", (msg) => {
+      state.console.push({
+        type: msg.type(),
+        text: msg.text(),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        location: msg.location()
+      });
+      if (state.console.length > MAX_CONSOLE_MESSAGES) state.console.shift();
+    });
+    page.on("pageerror", (err) => {
+      state.errors.push({
+        message: err?.message ? String(err.message) : String(err),
+        name: err?.name ? String(err.name) : void 0,
+        stack: err?.stack ? String(err.stack) : void 0,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (state.errors.length > MAX_PAGE_ERRORS) state.errors.shift();
+    });
+    page.on("request", (req) => {
+      state.nextRequestId += 1;
+      const id = `r${state.nextRequestId}`;
+      state.requestIds.set(req, id);
+      state.requests.push({
+        id,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        method: req.method(),
+        url: req.url(),
+        resourceType: req.resourceType()
+      });
+      if (state.requests.length > MAX_NETWORK_REQUESTS) state.requests.shift();
+    });
+    page.on("response", (resp) => {
+      const req = resp.request();
+      const id = state.requestIds.get(req);
+      if (!id) return;
+      for (let i = state.requests.length - 1; i >= 0; i--) {
+        const rec = state.requests[i];
+        if (rec && rec.id === id) {
+          rec.status = resp.status();
+          rec.ok = resp.ok();
+          break;
+        }
+      }
+    });
+    page.on("requestfailed", (req) => {
+      const id = state.requestIds.get(req);
+      if (!id) return;
+      for (let i = state.requests.length - 1; i >= 0; i--) {
+        const rec = state.requests[i];
+        if (rec && rec.id === id) {
+          rec.failureText = req.failure()?.errorText;
+          rec.ok = false;
+          break;
+        }
+      }
+    });
+    page.on("close", () => {
+      pageStates.delete(page);
+      observedPages.delete(page);
+    });
+  }
+  return state;
+}
+function ensureContextState(context) {
+  const existing = contextStates.get(context);
+  if (existing) return existing;
+  const state = { traceActive: false };
+  contextStates.set(context, state);
+  return state;
+}
+function observeContext(context) {
+  if (observedContexts.has(context)) return;
+  observedContexts.add(context);
+  ensureContextState(context);
+  for (const page of context.pages()) ensurePageState(page);
+  context.on("page", (page) => ensurePageState(page));
+}
+function observeBrowser(browser) {
+  for (const context of browser.contexts()) observeContext(context);
+}
+function storeRoleRefsForTarget(opts) {
+  const state = ensurePageState(opts.page);
+  state.roleRefs = opts.refs;
+  state.roleRefsFrameSelector = opts.frameSelector;
+  state.roleRefsMode = opts.mode;
+  const targetId = opts.targetId?.trim();
+  if (!targetId) return;
+  roleRefsByTarget.set(roleRefsKey(opts.cdpUrl, targetId), {
+    refs: opts.refs,
+    ...opts.frameSelector ? { frameSelector: opts.frameSelector } : {},
+    ...opts.mode ? { mode: opts.mode } : {}
+  });
+  while (roleRefsByTarget.size > MAX_ROLE_REFS_CACHE) {
+    const first = roleRefsByTarget.keys().next();
+    if (first.done) break;
+    roleRefsByTarget.delete(first.value);
+  }
+}
+function restoreRoleRefsForTarget(opts) {
+  const targetId = opts.targetId?.trim() || "";
+  if (!targetId) return;
+  const cached2 = roleRefsByTarget.get(roleRefsKey(opts.cdpUrl, targetId));
+  if (!cached2) return;
+  const state = ensurePageState(opts.page);
+  if (state.roleRefs) return;
+  state.roleRefs = cached2.refs;
+  state.roleRefsFrameSelector = cached2.frameSelector;
+  state.roleRefsMode = cached2.mode;
+}
+async function connectBrowser(cdpUrl) {
+  const normalized = normalizeCdpUrl(cdpUrl);
+  if (cached?.cdpUrl === normalized) return cached;
+  if (connecting) return await connecting;
+  const connectWithRetry = async () => {
+    let lastErr;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        const timeout = 5e3 + attempt * 2e3;
+        const endpoint = await getChromeWebSocketUrl(normalized, timeout).catch(() => null) ?? normalized;
+        const browser = await chromium.connectOverCDP(endpoint, { timeout });
+        const connected = { browser, cdpUrl: normalized };
+        cached = connected;
+        observeBrowser(browser);
+        browser.on("disconnected", () => {
+          if (cached?.browser === browser) cached = null;
+        });
+        return connected;
+      } catch (err) {
+        lastErr = err;
+        await new Promise((r) => setTimeout(r, 250 + attempt * 250));
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error("CDP connect failed");
+  };
+  connecting = connectWithRetry().finally(() => {
+    connecting = null;
+  });
+  return await connecting;
+}
+async function disconnectBrowser() {
+  const cur = cached;
+  cached = null;
+  if (cur) await cur.browser.close().catch(() => {
+  });
+}
+async function getAllPages(browser) {
+  return browser.contexts().flatMap((c) => c.pages());
+}
+async function pageTargetId(page) {
+  const session = await page.context().newCDPSession(page);
+  try {
+    const info = await session.send("Target.getTargetInfo");
+    return String(info?.targetInfo?.targetId ?? "").trim() || null;
+  } finally {
+    await session.detach().catch(() => {
+    });
+  }
+}
+async function findPageByTargetId(browser, targetId, cdpUrl) {
+  const pages = await getAllPages(browser);
+  for (const page of pages) {
+    const tid = await pageTargetId(page).catch(() => null);
+    if (tid && tid === targetId) return page;
+  }
+  if (cdpUrl) {
+    try {
+      const listUrl = `${cdpUrl.replace(/\/+$/, "").replace(/^ws:/, "http:").replace(/\/cdp$/, "")}/json/list`;
+      const response = await fetch(listUrl);
+      if (response.ok) {
+        const targets = await response.json();
+        const target = targets.find((t) => t.id === targetId);
+        if (target) {
+          const urlMatch = pages.filter((p) => p.url() === target.url);
+          if (urlMatch.length === 1) return urlMatch[0];
+        }
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+async function getPageForTargetId(opts) {
+  const { browser } = await connectBrowser(opts.cdpUrl);
+  const pages = await getAllPages(browser);
+  if (!pages.length) throw new Error("No pages available in the connected browser.");
+  const first = pages[0];
+  if (!opts.targetId) return first;
+  const found = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
+  if (!found) {
+    if (pages.length === 1) return first;
+    throw new Error(`Tab not found (targetId: ${opts.targetId}). Use browser.tabs() to list open tabs.`);
+  }
+  return found;
+}
+function refLocator(page, ref) {
+  const normalized = ref.startsWith("@") ? ref.slice(1) : ref.startsWith("ref=") ? ref.slice(4) : ref;
+  if (/^e\d+$/.test(normalized)) {
+    const state = pageStates.get(page);
+    if (state?.roleRefsMode === "aria") {
+      return (state.roleRefsFrameSelector ? page.frameLocator(state.roleRefsFrameSelector) : page).locator(`aria-ref=${normalized}`);
+    }
+    const info = state?.roleRefs?.[normalized];
+    if (!info) throw new Error(`Unknown ref "${normalized}". Run a new snapshot and use a ref from that snapshot.`);
+    const locAny = state?.roleRefsFrameSelector ? page.frameLocator(state.roleRefsFrameSelector) : page;
+    const locator = info.name ? locAny.getByRole(info.role, { name: info.name, exact: true }) : locAny.getByRole(info.role);
+    return info.nth !== void 0 ? locator.nth(info.nth) : locator;
+  }
+  return page.locator(`aria-ref=${normalized}`);
+}
+function toAIFriendlyError(error, selector) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("strict mode violation")) {
+    const countMatch = message.match(/resolved to (\d+) elements/);
+    const count = countMatch ? countMatch[1] : "multiple";
+    return new Error(`Selector "${selector}" matched ${count} elements. Run a new snapshot to get updated refs, or use a different ref.`);
+  }
+  if ((message.includes("Timeout") || message.includes("waiting for")) && (message.includes("to be visible") || message.includes("not visible"))) {
+    return new Error(`Element "${selector}" not found or not visible. Run a new snapshot to see current page elements.`);
+  }
+  if (message.includes("intercepts pointer events") || message.includes("not visible") || message.includes("not receive pointer events")) {
+    return new Error(`Element "${selector}" is not interactable (hidden or covered). Try scrolling it into view, closing overlays, or re-snapshotting.`);
+  }
+  return error instanceof Error ? error : new Error(message);
+}
+function normalizeTimeoutMs(timeoutMs, fallback) {
+  return Math.max(500, Math.min(12e4, timeoutMs ?? fallback));
+}
+
+// src/snapshot/ref-map.ts
+var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "treeitem"
+]);
+var CONTENT_ROLES = /* @__PURE__ */ new Set([
+  "heading",
+  "cell",
+  "gridcell",
+  "columnheader",
+  "rowheader",
+  "listitem",
+  "article",
+  "region",
+  "main",
+  "navigation"
+]);
+var STRUCTURAL_ROLES = /* @__PURE__ */ new Set([
+  "generic",
+  "group",
+  "list",
+  "table",
+  "row",
+  "rowgroup",
+  "grid",
+  "treegrid",
+  "menu",
+  "menubar",
+  "toolbar",
+  "tablist",
+  "tree",
+  "directory",
+  "document",
+  "application",
+  "presentation",
+  "none"
+]);
+function getIndentLevel(line) {
+  const match = line.match(/^(\s*)/);
+  return match ? Math.floor(match[1].length / 2) : 0;
+}
+function createRoleNameTracker() {
+  const counts = /* @__PURE__ */ new Map();
+  const refsByKey = /* @__PURE__ */ new Map();
+  return {
+    counts,
+    refsByKey,
+    getKey(role, name) {
+      return `${role}:${name ?? ""}`;
+    },
+    getNextIndex(role, name) {
+      const key = this.getKey(role, name);
+      const current = counts.get(key) ?? 0;
+      counts.set(key, current + 1);
+      return current;
+    },
+    trackRef(role, name, ref) {
+      const key = this.getKey(role, name);
+      const list = refsByKey.get(key) ?? [];
+      list.push(ref);
+      refsByKey.set(key, list);
+    },
+    getDuplicateKeys() {
+      const out = /* @__PURE__ */ new Set();
+      for (const [key, refs] of refsByKey) if (refs.length > 1) out.add(key);
+      return out;
+    }
+  };
+}
+function removeNthFromNonDuplicates(refs, tracker) {
+  const duplicates = tracker.getDuplicateKeys();
+  for (const [ref, data] of Object.entries(refs)) {
+    const key = tracker.getKey(data.role, data.name);
+    if (!duplicates.has(key)) delete refs[ref]?.nth;
+  }
+}
+function compactTree(tree) {
+  const lines = tree.split("\n");
+  const result = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.includes("[ref=")) {
+      result.push(line);
+      continue;
+    }
+    if (line.includes(":") && !line.trimEnd().endsWith(":")) {
+      result.push(line);
+      continue;
+    }
+    const currentIndent = getIndentLevel(line);
+    let hasRelevantChildren = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (getIndentLevel(lines[j]) <= currentIndent) break;
+      if (lines[j]?.includes("[ref=")) {
+        hasRelevantChildren = true;
+        break;
+      }
+    }
+    if (hasRelevantChildren) result.push(line);
+  }
+  return result.join("\n");
+}
+function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
+  const lines = ariaSnapshot.split("\n");
+  const refs = {};
+  const tracker = createRoleNameTracker();
+  let counter = 0;
+  const nextRef = () => {
+    counter++;
+    return `e${counter}`;
+  };
+  if (options.interactive) {
+    const result2 = [];
+    for (const line of lines) {
+      const depth = getIndentLevel(line);
+      if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
+      const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+      if (!match) continue;
+      const [, , roleRaw, name, suffix] = match;
+      if (roleRaw.startsWith("/")) continue;
+      const role = roleRaw.toLowerCase();
+      if (!INTERACTIVE_ROLES.has(role)) continue;
+      const ref = nextRef();
+      const nth = tracker.getNextIndex(role, name);
+      tracker.trackRef(role, name, ref);
+      refs[ref] = { role, name, nth };
+      let enhanced = `- ${roleRaw}`;
+      if (name) enhanced += ` "${name}"`;
+      enhanced += ` [ref=${ref}]`;
+      if (nth > 0) enhanced += ` [nth=${nth}]`;
+      if (suffix.includes("[")) enhanced += suffix;
+      result2.push(enhanced);
+    }
+    removeNthFromNonDuplicates(refs, tracker);
+    return { snapshot: result2.join("\n") || "(no interactive elements)", refs };
+  }
+  const result = [];
+  for (const line of lines) {
+    const depth = getIndentLevel(line);
+    if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
+    const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+    if (!match) {
+      if (!options.interactive) result.push(line);
+      continue;
+    }
+    const [, prefix, roleRaw, name, suffix] = match;
+    if (roleRaw.startsWith("/")) {
+      result.push(line);
+      continue;
+    }
+    const role = roleRaw.toLowerCase();
+    const isInteractive = INTERACTIVE_ROLES.has(role);
+    const isContent = CONTENT_ROLES.has(role);
+    const isStructural = STRUCTURAL_ROLES.has(role);
+    if (options.compact && isStructural && !name) continue;
+    if (!(isInteractive || isContent && name)) {
+      result.push(line);
+      continue;
+    }
+    const ref = nextRef();
+    const nth = tracker.getNextIndex(role, name);
+    tracker.trackRef(role, name, ref);
+    refs[ref] = { role, name, nth };
+    let enhanced = `${prefix}${roleRaw}`;
+    if (name) enhanced += ` "${name}"`;
+    enhanced += ` [ref=${ref}]`;
+    if (nth > 0) enhanced += ` [nth=${nth}]`;
+    if (suffix) enhanced += suffix;
+    result.push(enhanced);
+  }
+  removeNthFromNonDuplicates(refs, tracker);
+  const tree = result.join("\n") || "(empty)";
+  return { snapshot: options.compact ? compactTree(tree) : tree, refs };
+}
+function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
+  const lines = String(aiSnapshot ?? "").split("\n");
+  const refs = {};
+  function parseAiSnapshotRef(suffix) {
+    const match = suffix.match(/\[ref=(e\d+)\]/i);
+    return match ? match[1] : null;
+  }
+  if (options.interactive) {
+    const out2 = [];
+    for (const line of lines) {
+      const depth = getIndentLevel(line);
+      if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
+      const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+      if (!match) continue;
+      const [, , roleRaw, name, suffix] = match;
+      if (roleRaw.startsWith("/")) continue;
+      const role = roleRaw.toLowerCase();
+      if (!INTERACTIVE_ROLES.has(role)) continue;
+      const ref = parseAiSnapshotRef(suffix);
+      if (!ref) continue;
+      refs[ref] = { role, ...name ? { name } : {} };
+      out2.push(`- ${roleRaw}${name ? ` "${name}"` : ""}${suffix}`);
+    }
+    return { snapshot: out2.join("\n") || "(no interactive elements)", refs };
+  }
+  const out = [];
+  for (const line of lines) {
+    const depth = getIndentLevel(line);
+    if (options.maxDepth !== void 0 && depth > options.maxDepth) continue;
+    const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+    if (!match) {
+      out.push(line);
+      continue;
+    }
+    const [, , roleRaw, name, suffix] = match;
+    if (roleRaw.startsWith("/")) {
+      out.push(line);
+      continue;
+    }
+    const role = roleRaw.toLowerCase();
+    const isStructural = STRUCTURAL_ROLES.has(role);
+    if (options.compact && isStructural && !name) continue;
+    const ref = parseAiSnapshotRef(suffix);
+    if (ref) refs[ref] = { role, ...name ? { name } : {} };
+    out.push(line);
+  }
+  const tree = out.join("\n") || "(empty)";
+  return { snapshot: options.compact ? compactTree(tree) : tree, refs };
+}
+function getRoleSnapshotStats(snapshot, refs) {
+  const interactive = Object.values(refs).filter((r) => INTERACTIVE_ROLES.has(r.role)).length;
+  return {
+    lines: snapshot.split("\n").length,
+    chars: snapshot.length,
+    refs: Object.keys(refs).length,
+    interactive
+  };
+}
+
+// src/snapshot/ai-snapshot.ts
+async function snapshotAi(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const maybe = page;
+  if (!maybe._snapshotForAI) {
+    throw new Error("Playwright _snapshotForAI is not available. Upgrade playwright-core to >= 1.50.");
+  }
+  const result = await maybe._snapshotForAI({
+    timeout: Math.max(500, Math.min(6e4, Math.floor(opts.timeoutMs ?? 5e3))),
+    track: "response"
+  });
+  let snapshot = String(result?.full ?? "");
+  const maxChars = opts.maxChars;
+  const limit = typeof maxChars === "number" && Number.isFinite(maxChars) && maxChars > 0 ? Math.floor(maxChars) : void 0;
+  if (limit && snapshot.length > limit) {
+    snapshot = `${snapshot.slice(0, limit)}
+
+[...TRUNCATED - page too large]`;
+  }
+  const built = buildRoleSnapshotFromAiSnapshot(snapshot, opts.options);
+  storeRoleRefsForTarget({
+    page,
+    cdpUrl: opts.cdpUrl,
+    targetId: opts.targetId,
+    refs: built.refs,
+    mode: "aria"
+  });
+  return {
+    snapshot: built.snapshot,
+    refs: built.refs,
+    stats: getRoleSnapshotStats(built.snapshot, built.refs)
+  };
+}
+
+// src/snapshot/aria-snapshot.ts
+async function snapshotRole(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const frameSelector = opts.frameSelector?.trim() || "";
+  const selector = opts.selector?.trim() || "";
+  const locator = frameSelector ? selector ? page.frameLocator(frameSelector).locator(selector) : page.frameLocator(frameSelector).locator(":root") : selector ? page.locator(selector) : page.locator(":root");
+  const ariaSnapshot = await locator.ariaSnapshot();
+  const built = buildRoleSnapshotFromAriaSnapshot(String(ariaSnapshot ?? ""), opts.options);
+  storeRoleRefsForTarget({
+    page,
+    cdpUrl: opts.cdpUrl,
+    targetId: opts.targetId,
+    refs: built.refs,
+    frameSelector: frameSelector || void 0,
+    mode: "role"
+  });
+  return {
+    snapshot: built.snapshot,
+    refs: built.refs,
+    stats: getRoleSnapshotStats(built.snapshot, built.refs)
+  };
+}
+async function snapshotAria(opts) {
+  const limit = Math.max(1, Math.min(2e3, Math.floor(opts.limit ?? 500)));
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const session = await page.context().newCDPSession(page);
+  try {
+    await session.send("Accessibility.enable").catch(() => {
+    });
+    const res = await session.send("Accessibility.getFullAXTree");
+    return { nodes: formatAriaNodes(Array.isArray(res?.nodes) ? res.nodes : [], limit) };
+  } finally {
+    await session.detach().catch(() => {
+    });
+  }
+}
+function axValue(v) {
+  if (!v || typeof v !== "object") return "";
+  const value = v.value;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return "";
+}
+function formatAriaNodes(nodes, limit) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const n of nodes) if (n.nodeId) byId.set(n.nodeId, n);
+  const referenced = /* @__PURE__ */ new Set();
+  for (const n of nodes) for (const c of n.childIds ?? []) referenced.add(c);
+  const root = nodes.find((n) => n.nodeId && !referenced.has(n.nodeId)) ?? nodes[0];
+  if (!root?.nodeId) return [];
+  const out = [];
+  const stack = [{ id: root.nodeId, depth: 0 }];
+  while (stack.length && out.length < limit) {
+    const popped = stack.pop();
+    if (!popped) break;
+    const { id, depth } = popped;
+    const n = byId.get(id);
+    if (!n) continue;
+    const role = axValue(n.role);
+    const name = axValue(n.name);
+    const value = axValue(n.value);
+    const description = axValue(n.description);
+    const ref = `ax${out.length + 1}`;
+    out.push({
+      ref,
+      role: role || "unknown",
+      name: name || "",
+      ...value ? { value } : {},
+      ...description ? { description } : {},
+      ...typeof n.backendDOMNodeId === "number" ? { backendDOMNodeId: n.backendDOMNodeId } : {},
+      depth
+    });
+    const children = (n.childIds ?? []).filter((c) => byId.has(c));
+    for (let i = children.length - 1; i >= 0; i--) {
+      if (children[i]) stack.push({ id: children[i], depth: depth + 1 });
+    }
+  }
+  return out;
+}
+
+// src/actions/interaction.ts
+async function clickViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const locator = refLocator(page, opts.ref);
+  const timeout = Math.max(500, Math.min(6e4, Math.floor(opts.timeoutMs ?? 8e3)));
+  try {
+    if (opts.doubleClick) {
+      await locator.dblclick({ timeout, button: opts.button, modifiers: opts.modifiers });
+    } else {
+      await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
+    }
+  } catch (err) {
+    throw toAIFriendlyError(err, opts.ref);
+  }
+}
+async function hoverViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  try {
+    await refLocator(page, opts.ref).hover({
+      timeout: Math.max(500, Math.min(6e4, opts.timeoutMs ?? 8e3))
+    });
+  } catch (err) {
+    throw toAIFriendlyError(err, opts.ref);
+  }
+}
+async function typeViaPlaywright(opts) {
+  const text = String(opts.text ?? "");
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const locator = refLocator(page, opts.ref);
+  const timeout = Math.max(500, Math.min(6e4, opts.timeoutMs ?? 8e3));
+  try {
+    if (opts.slowly) {
+      await locator.click({ timeout });
+      await locator.type(text, { timeout, delay: 75 });
+    } else {
+      await locator.fill(text, { timeout });
+    }
+    if (opts.submit) await locator.press("Enter", { timeout });
+  } catch (err) {
+    throw toAIFriendlyError(err, opts.ref);
+  }
+}
+async function selectOptionViaPlaywright(opts) {
+  if (!opts.values?.length) throw new Error("values are required");
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  try {
+    await refLocator(page, opts.ref).selectOption(opts.values, {
+      timeout: Math.max(500, Math.min(6e4, opts.timeoutMs ?? 8e3))
+    });
+  } catch (err) {
+    throw toAIFriendlyError(err, opts.ref);
+  }
+}
+async function dragViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  try {
+    await refLocator(page, opts.startRef).dragTo(refLocator(page, opts.endRef), {
+      timeout: Math.max(500, Math.min(6e4, opts.timeoutMs ?? 8e3))
+    });
+  } catch (err) {
+    throw toAIFriendlyError(err, `${opts.startRef} -> ${opts.endRef}`);
+  }
+}
+async function fillFormViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const timeout = Math.max(500, Math.min(6e4, opts.timeoutMs ?? 8e3));
+  for (const field of opts.fields) {
+    const ref = field.ref.trim();
+    const type = field.type.trim();
+    const rawValue = field.value;
+    const value = typeof rawValue === "string" ? rawValue : typeof rawValue === "number" || typeof rawValue === "boolean" ? String(rawValue) : "";
+    if (!ref || !type) continue;
+    const locator = refLocator(page, ref);
+    if (type === "checkbox" || type === "radio") {
+      const checked = rawValue === true || rawValue === 1 || rawValue === "1" || rawValue === "true";
+      try {
+        await locator.setChecked(checked, { timeout });
+      } catch (err) {
+        throw toAIFriendlyError(err, ref);
+      }
+      continue;
+    }
+    try {
+      await locator.fill(value, { timeout });
+    } catch (err) {
+      throw toAIFriendlyError(err, ref);
+    }
+  }
+}
+async function scrollIntoViewViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  try {
+    await refLocator(page, opts.ref).scrollIntoViewIfNeeded({
+      timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4)
+    });
+  } catch (err) {
+    throw toAIFriendlyError(err, opts.ref);
+  }
+}
+
+// src/actions/keyboard.ts
+async function pressKeyViaPlaywright(opts) {
+  const key = String(opts.key ?? "").trim();
+  if (!key) throw new Error("key is required");
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  await page.keyboard.press(key, { delay: Math.max(0, Math.floor(opts.delayMs ?? 0)) });
+}
+
+// src/actions/navigation.ts
+async function navigateViaPlaywright(opts) {
+  const url = String(opts.url ?? "").trim();
+  if (!url) throw new Error("url is required");
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  await page.goto(url, { timeout: Math.max(1e3, Math.min(12e4, opts.timeoutMs ?? 2e4)) });
+  return { url: page.url() };
+}
+async function listPagesViaPlaywright(opts) {
+  const { browser } = await connectBrowser(opts.cdpUrl);
+  const pages = await getAllPages(browser);
+  const results = [];
+  for (const page of pages) {
+    const tid = await pageTargetId(page).catch(() => null);
+    if (tid) results.push({
+      targetId: tid,
+      title: await page.title().catch(() => ""),
+      url: page.url(),
+      type: "page"
+    });
+  }
+  return results;
+}
+async function createPageViaPlaywright(opts) {
+  const { browser } = await connectBrowser(opts.cdpUrl);
+  const context = browser.contexts()[0] ?? await browser.newContext();
+  ensureContextState(context);
+  const page = await context.newPage();
+  ensurePageState(page);
+  const targetUrl = (opts.url ?? "").trim() || "about:blank";
+  if (targetUrl !== "about:blank") {
+    await page.goto(targetUrl, { timeout: 3e4 }).catch(() => {
+    });
+  }
+  const tid = await pageTargetId(page).catch(() => null);
+  if (!tid) throw new Error("Failed to get targetId for new page");
+  return {
+    targetId: tid,
+    title: await page.title().catch(() => ""),
+    url: page.url(),
+    type: "page"
+  };
+}
+async function closePageByTargetIdViaPlaywright(opts) {
+  const { browser } = await connectBrowser(opts.cdpUrl);
+  const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
+  if (!page) throw new Error(`Tab not found (targetId: ${opts.targetId}). Use browser.tabs() to list open tabs.`);
+  await page.close();
+}
+async function focusPageByTargetIdViaPlaywright(opts) {
+  const { browser } = await connectBrowser(opts.cdpUrl);
+  const page = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
+  if (!page) throw new Error(`Tab not found (targetId: ${opts.targetId}). Use browser.tabs() to list open tabs.`);
+  try {
+    await page.bringToFront();
+  } catch (err) {
+    const session = await page.context().newCDPSession(page);
+    try {
+      await session.send("Page.bringToFront");
+    } catch {
+      throw err;
+    } finally {
+      await session.detach().catch(() => {
+      });
+    }
+  }
+}
+async function resizeViewportViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  await page.setViewportSize({
+    width: Math.max(1, Math.floor(opts.width)),
+    height: Math.max(1, Math.floor(opts.height))
+  });
+}
+
+// src/actions/wait.ts
+async function waitForViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 2e4);
+  if (typeof opts.timeMs === "number" && Number.isFinite(opts.timeMs)) {
+    await page.waitForTimeout(Math.max(0, opts.timeMs));
+  }
+  if (opts.text) {
+    await page.getByText(opts.text).first().waitFor({ state: "visible", timeout });
+  }
+  if (opts.textGone) {
+    await page.getByText(opts.textGone).first().waitFor({ state: "hidden", timeout });
+  }
+  if (opts.selector) {
+    const selector = String(opts.selector).trim();
+    if (selector) await page.locator(selector).first().waitFor({ state: "visible", timeout });
+  }
+  if (opts.url) {
+    const url = String(opts.url).trim();
+    if (url) await page.waitForURL(url, { timeout });
+  }
+  if (opts.loadState) {
+    await page.waitForLoadState(opts.loadState, { timeout });
+  }
+  if (opts.fn) {
+    const fn = String(opts.fn).trim();
+    if (fn) await page.waitForFunction(fn, { timeout });
+  }
+}
+
+// src/actions/evaluate.ts
+async function evaluateInAllFramesViaPlaywright(opts) {
+  const fnText = String(opts.fn ?? "").trim();
+  if (!fnText) throw new Error("function is required");
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  const frames = page.frames();
+  const results = [];
+  for (const frame of frames) {
+    try {
+      const result = await frame.evaluate(
+        // eslint-disable-next-line no-eval
+        (fnBody) => {
+          "use strict";
+          try {
+            const candidate = (0, eval)("(" + fnBody + ")");
+            return typeof candidate === "function" ? candidate() : candidate;
+          } catch (err) {
+            throw new Error("Invalid evaluate function: " + (err?.message ?? String(err)));
+          }
+        },
+        fnText
+      );
+      results.push({
+        frameUrl: frame.url(),
+        frameName: frame.name(),
+        result
+      });
+    } catch {
+    }
+  }
+  return results;
+}
+async function evaluateViaPlaywright(opts) {
+  const fnText = String(opts.fn ?? "").trim();
+  if (!fnText) throw new Error("function is required");
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  if (opts.ref) {
+    const locator = refLocator(page, opts.ref);
+    return await locator.evaluate(
+      // eslint-disable-next-line no-eval
+      (el, fnBody) => {
+        try {
+          const candidate = (0, eval)("(" + fnBody + ")");
+          return typeof candidate === "function" ? candidate(el) : candidate;
+        } catch (err) {
+          throw new Error("Invalid evaluate function: " + (err?.message ?? String(err)));
+        }
+      },
+      fnText
+    );
+  }
+  return await page.evaluate(
+    // eslint-disable-next-line no-eval
+    (fnBody) => {
+      try {
+        const candidate = (0, eval)("(" + fnBody + ")");
+        return typeof candidate === "function" ? candidate() : candidate;
+      } catch (err) {
+        throw new Error("Invalid evaluate function: " + (err?.message ?? String(err)));
+      }
+    },
+    fnText
+  );
+}
+
+// src/capture/screenshot.ts
+async function takeScreenshotViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const type = opts.type ?? "png";
+  if (opts.ref) {
+    if (opts.fullPage) throw new Error("fullPage is not supported for element screenshots");
+    return { buffer: await refLocator(page, opts.ref).screenshot({ type }) };
+  }
+  if (opts.element) {
+    if (opts.fullPage) throw new Error("fullPage is not supported for element screenshots");
+    return { buffer: await page.locator(opts.element).first().screenshot({ type }) };
+  }
+  return { buffer: await page.screenshot({ type, fullPage: Boolean(opts.fullPage) }) };
+}
+
+// src/capture/pdf.ts
+async function pdfViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  return { buffer: await page.pdf({ printBackground: true }) };
+}
+
+// src/capture/activity.ts
+function consolePriority(level) {
+  switch (level) {
+    case "error":
+      return 3;
+    case "warning":
+      return 2;
+    case "info":
+    case "log":
+      return 1;
+    case "debug":
+      return 0;
+    default:
+      return 1;
+  }
+}
+async function getConsoleMessagesViaPlaywright(opts) {
+  const state = ensurePageState(await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId }));
+  if (!opts.level) return [...state.console];
+  const min = consolePriority(opts.level);
+  return state.console.filter((msg) => consolePriority(msg.type) >= min);
+}
+async function getPageErrorsViaPlaywright(opts) {
+  const state = ensurePageState(await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId }));
+  const errors = [...state.errors];
+  if (opts.clear) state.errors = [];
+  return { errors };
+}
+async function getNetworkRequestsViaPlaywright(opts) {
+  const state = ensurePageState(await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId }));
+  const raw = [...state.requests];
+  const filter = typeof opts.filter === "string" ? opts.filter.trim() : "";
+  const requests = filter ? raw.filter((r) => r.url.includes(filter)) : raw;
+  if (opts.clear) {
+    state.requests = [];
+    state.requestIds = /* @__PURE__ */ new WeakMap();
+  }
+  return { requests };
+}
+
+// src/storage/index.ts
+async function cookiesGetViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  return { cookies: await page.context().cookies() };
+}
+async function cookiesSetViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  const cookie = opts.cookie;
+  if (!cookie.name || cookie.value === void 0) throw new Error("cookie name and value are required");
+  const hasUrl = typeof cookie.url === "string" && cookie.url.trim();
+  const hasDomainPath = typeof cookie.domain === "string" && cookie.domain.trim() && typeof cookie.path === "string" && cookie.path.trim();
+  if (!hasUrl && !hasDomainPath) throw new Error("cookie requires url, or domain+path");
+  await page.context().addCookies([cookie]);
+}
+async function cookiesClearViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  await page.context().clearCookies();
+}
+async function storageGetViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  return {
+    values: await page.evaluate(
+      ({ kind, key }) => {
+        const store = kind === "session" ? window.sessionStorage : window.localStorage;
+        if (key) {
+          const value = store.getItem(key);
+          return value === null ? {} : { [key]: value };
+        }
+        const out = {};
+        for (let i = 0; i < store.length; i++) {
+          const k = store.key(i);
+          if (!k) continue;
+          const v = store.getItem(k);
+          if (v !== null) out[k] = v;
+        }
+        return out;
+      },
+      { kind: opts.kind, key: opts.key }
+    ) ?? {}
+  };
+}
+async function storageSetViaPlaywright(opts) {
+  const key = String(opts.key ?? "");
+  if (!key) throw new Error("key is required");
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  await page.evaluate(
+    ({ kind, key: k, value }) => {
+      (kind === "session" ? window.sessionStorage : window.localStorage).setItem(k, value);
+    },
+    { kind: opts.kind, key, value: String(opts.value ?? "") }
+  );
+}
+async function storageClearViaPlaywright(opts) {
+  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  ensurePageState(page);
+  await page.evaluate(
+    ({ kind }) => {
+      (kind === "session" ? window.sessionStorage : window.localStorage).clear();
+    },
+    { kind: opts.kind }
+  );
+}
+
+// src/browser.ts
+var CrawlPage = class {
+  cdpUrl;
+  targetId;
+  /** @internal */
+  constructor(cdpUrl, targetId) {
+    this.cdpUrl = cdpUrl;
+    this.targetId = targetId;
+  }
+  /** The CDP target ID for this page. Use this to identify the page in multi-tab scenarios. */
+  get id() {
+    return this.targetId;
+  }
+  // ── Snapshot ──────────────────────────────────────────────────
+  /**
+   * Take an AI-readable snapshot of the page.
+   *
+   * Returns a text tree with numbered refs (`e1`, `e2`, ...) that map to
+   * interactive elements. Use these refs with actions like `click()` and `type()`.
+   *
+   * @param opts - Snapshot options (mode, filtering, depth limits)
+   * @returns Snapshot text, ref map, and statistics
+   *
+   * @example
+   * ```ts
+   * // Default snapshot (aria mode)
+   * const { snapshot, refs } = await page.snapshot();
+   *
+   * // Interactive elements only, compact
+   * const result = await page.snapshot({ interactive: true, compact: true });
+   *
+   * // Role-based mode (uses getByRole resolution)
+   * const result = await page.snapshot({ mode: 'role' });
+   * ```
+   */
+  async snapshot(opts) {
+    if (opts?.mode === "role") {
+      return snapshotRole({
+        cdpUrl: this.cdpUrl,
+        targetId: this.targetId,
+        selector: opts?.selector,
+        frameSelector: opts?.frameSelector,
+        options: {
+          interactive: opts?.interactive,
+          compact: opts?.compact,
+          maxDepth: opts?.maxDepth
+        }
+      });
+    }
+    return snapshotAi({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      maxChars: opts?.maxChars,
+      options: {
+        interactive: opts?.interactive,
+        compact: opts?.compact,
+        maxDepth: opts?.maxDepth
+      }
+    });
+  }
+  /**
+   * Take a raw ARIA accessibility tree snapshot via CDP.
+   *
+   * Unlike `snapshot()`, this returns structured node data rather than
+   * an AI-readable text tree. Useful for programmatic accessibility analysis.
+   *
+   * @param opts - Options (limit: max nodes to return, default 500)
+   * @returns Array of accessibility tree nodes
+   */
+  async ariaSnapshot(opts) {
+    return snapshotAria({ cdpUrl: this.cdpUrl, targetId: this.targetId, limit: opts?.limit });
+  }
+  // ── Interactions ─────────────────────────────────────────────
+  /**
+   * Click an element by ref.
+   *
+   * @param ref - Ref ID from a snapshot (e.g. `'e1'`)
+   * @param opts - Click options (double-click, button, modifiers)
+   *
+   * @example
+   * ```ts
+   * await page.click('e1');
+   * await page.click('e2', { doubleClick: true });
+   * await page.click('e3', { button: 'right' });
+   * await page.click('e4', { modifiers: ['Control'] });
+   * ```
+   */
+  async click(ref, opts) {
+    return clickViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      ref,
+      doubleClick: opts?.doubleClick,
+      button: opts?.button,
+      modifiers: opts?.modifiers,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
+  /**
+   * Type text into an input element by ref.
+   *
+   * By default, uses Playwright's `fill()` for instant input. Use `slowly: true`
+   * to simulate real keystroke typing with a 75ms delay per character.
+   *
+   * @param ref - Ref ID of the input element (e.g. `'e3'`)
+   * @param text - Text to type
+   * @param opts - Type options (submit, slowly)
+   *
+   * @example
+   * ```ts
+   * await page.type('e3', 'hello world');
+   * await page.type('e3', 'slow typing', { slowly: true });
+   * await page.type('e3', 'search query', { submit: true }); // press Enter after
+   * ```
+   */
+  async type(ref, text, opts) {
+    return typeViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      ref,
+      text,
+      submit: opts?.submit,
+      slowly: opts?.slowly,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
+  /**
+   * Hover over an element by ref.
+   *
+   * @param ref - Ref ID from a snapshot
+   * @param opts - Timeout options
+   */
+  async hover(ref, opts) {
+    return hoverViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      ref,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
+  /**
+   * Select option(s) in a `<select>` dropdown by ref.
+   *
+   * @param ref - Ref ID of the select element
+   * @param values - One or more option labels/values to select
+   *
+   * @example
+   * ```ts
+   * await page.select('e5', 'Option A');
+   * await page.select('e5', 'Option A', 'Option B'); // multi-select
+   * ```
+   */
+  async select(ref, ...values) {
+    return selectOptionViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      ref,
+      values
+    });
+  }
+  /**
+   * Drag one element to another.
+   *
+   * @param startRef - Ref ID of the element to drag
+   * @param endRef - Ref ID of the drop target
+   * @param opts - Timeout options
+   */
+  async drag(startRef, endRef, opts) {
+    return dragViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      startRef,
+      endRef,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
+  /**
+   * Fill multiple form fields at once.
+   *
+   * Supports text inputs, checkboxes, and radio buttons.
+   *
+   * @param fields - Array of form fields to fill
+   *
+   * @example
+   * ```ts
+   * await page.fill([
+   *   { ref: 'e2', type: 'text', value: 'Jane Doe' },
+   *   { ref: 'e4', type: 'text', value: 'jane@example.com' },
+   *   { ref: 'e6', type: 'checkbox', value: true },
+   * ]);
+   * ```
+   */
+  async fill(fields) {
+    return fillFormViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      fields
+    });
+  }
+  /**
+   * Scroll an element into the visible viewport.
+   *
+   * @param ref - Ref ID of the element to scroll to
+   * @param opts - Timeout options
+   */
+  async scrollIntoView(ref, opts) {
+    return scrollIntoViewViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      ref,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
+  // ── Keyboard ─────────────────────────────────────────────────
+  /**
+   * Press a keyboard key or key combination.
+   *
+   * Uses Playwright's key names. Supports combinations with `+`.
+   *
+   * @param key - Key to press (e.g. `'Enter'`, `'Tab'`, `'Control+a'`, `'Meta+c'`)
+   * @param opts - Options (delayMs: hold time between keydown and keyup)
+   *
+   * @example
+   * ```ts
+   * await page.press('Enter');
+   * await page.press('Control+a');
+   * await page.press('Meta+Shift+p');
+   * ```
+   */
+  async press(key, opts) {
+    return pressKeyViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      key,
+      delayMs: opts?.delayMs
+    });
+  }
+  // ── Navigation ───────────────────────────────────────────────
+  /**
+   * Navigate to a URL.
+   *
+   * @param url - The URL to navigate to
+   * @param opts - Timeout options
+   * @returns The final URL after navigation (may differ due to redirects)
+   */
+  async goto(url, opts) {
+    return navigateViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      url,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
+  // ── Wait ─────────────────────────────────────────────────────
+  /**
+   * Wait for various conditions on the page.
+   *
+   * Multiple conditions can be specified — they are checked in order.
+   *
+   * @param opts - Wait conditions (text, URL, load state, selector, etc.)
+   *
+   * @example
+   * ```ts
+   * await page.waitFor({ loadState: 'networkidle' });
+   * await page.waitFor({ text: 'Welcome back' });
+   * await page.waitFor({ url: '**\/dashboard' });
+   * await page.waitFor({ timeMs: 1000 }); // sleep
+   * ```
+   */
+  async waitFor(opts) {
+    return waitForViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      ...opts
+    });
+  }
+  // ── Evaluate ─────────────────────────────────────────────────
+  /**
+   * Run JavaScript in the browser page context.
+   *
+   * The function string is evaluated in the browser's sandbox, not in Node.js.
+   * Pass a `ref` to receive the element as the first argument.
+   *
+   * @param fn - JavaScript function body as a string
+   * @param opts - Options (ref: scope evaluation to a specific element)
+   * @returns The return value of the evaluated function
+   *
+   * @example
+   * ```ts
+   * const title = await page.evaluate('() => document.title');
+   * const text = await page.evaluate('(el) => el.textContent', { ref: 'e1' });
+   * const count = await page.evaluate('() => document.querySelectorAll("img").length');
+   * ```
+   */
+  async evaluate(fn, opts) {
+    return evaluateViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      fn,
+      ref: opts?.ref
+    });
+  }
+  /**
+   * Run JavaScript in ALL frames on the page (including cross-origin iframes).
+   *
+   * Playwright can access cross-origin frames via CDP, bypassing the same-origin policy.
+   * This is essential for filling payment iframes (Stripe, etc.).
+   *
+   * @param fn - JavaScript function body as a string
+   * @returns Array of results from each frame where evaluation succeeded
+   *
+   * @example
+   * ```ts
+   * const results = await page.evaluateInAllFrames(`() => {
+   *   const el = document.querySelector('input[name="cardnumber"]');
+   *   return el ? 'found' : null;
+   * }`);
+   * ```
+   */
+  async evaluateInAllFrames(fn) {
+    return evaluateInAllFramesViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      fn
+    });
+  }
+  // ── Capture ──────────────────────────────────────────────────
+  /**
+   * Take a screenshot of the page or a specific element.
+   *
+   * @param opts - Screenshot options (fullPage, ref, element, type)
+   * @returns PNG or JPEG image as a Buffer
+   *
+   * @example
+   * ```ts
+   * const screenshot = await page.screenshot();
+   * const fullPage = await page.screenshot({ fullPage: true });
+   * const element = await page.screenshot({ ref: 'e1' });
+   * ```
+   */
+  async screenshot(opts) {
+    const result = await takeScreenshotViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      fullPage: opts?.fullPage,
+      ref: opts?.ref,
+      element: opts?.element,
+      type: opts?.type
+    });
+    return result.buffer;
+  }
+  /**
+   * Export the page as a PDF.
+   *
+   * Only works in headless mode.
+   *
+   * @returns PDF document as a Buffer
+   */
+  async pdf() {
+    const result = await pdfViaPlaywright({ cdpUrl: this.cdpUrl, targetId: this.targetId });
+    return result.buffer;
+  }
+  /**
+   * Get console messages captured from the page.
+   *
+   * Messages are buffered automatically. Use `level` to filter by minimum severity.
+   *
+   * @param opts - Filter options (level: `'debug'` | `'log'` | `'info'` | `'warning'` | `'error'`)
+   * @returns Array of captured console messages
+   */
+  async consoleLogs(opts) {
+    return getConsoleMessagesViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      level: opts?.level
+    });
+  }
+  /**
+   * Get uncaught errors from the page.
+   *
+   * @param opts - Options (clear: reset the error buffer after reading)
+   * @returns Array of captured page errors
+   */
+  async pageErrors(opts) {
+    const result = await getPageErrorsViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      clear: opts?.clear
+    });
+    return result.errors;
+  }
+  /**
+   * Get network requests captured from the page.
+   *
+   * @param opts - Options (filter: URL substring match, clear: reset the buffer)
+   * @returns Array of captured network requests
+   *
+   * @example
+   * ```ts
+   * const all = await page.networkRequests();
+   * const apiCalls = await page.networkRequests({ filter: '/api/' });
+   * const fresh = await page.networkRequests({ clear: true }); // read and clear
+   * ```
+   */
+  async networkRequests(opts) {
+    const result = await getNetworkRequestsViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      filter: opts?.filter,
+      clear: opts?.clear
+    });
+    return result.requests;
+  }
+  // ── Viewport ─────────────────────────────────────────────────
+  /**
+   * Resize the browser viewport.
+   *
+   * @param width - Viewport width in pixels
+   * @param height - Viewport height in pixels
+   */
+  async resize(width, height) {
+    return resizeViewportViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      width,
+      height
+    });
+  }
+  // ── Storage ──────────────────────────────────────────────────
+  /**
+   * Get all cookies for the current browser context.
+   *
+   * @returns Array of cookie objects
+   */
+  async cookies() {
+    const result = await cookiesGetViaPlaywright({ cdpUrl: this.cdpUrl, targetId: this.targetId });
+    return result.cookies;
+  }
+  /**
+   * Set a cookie in the browser context.
+   *
+   * @param cookie - Cookie data (must include `name`, `value`, and either `url` or `domain`+`path`)
+   *
+   * @example
+   * ```ts
+   * await page.setCookie({
+   *   name: 'token',
+   *   value: 'abc123',
+   *   url: 'https://example.com',
+   * });
+   * ```
+   */
+  async setCookie(cookie) {
+    return cookiesSetViaPlaywright({ cdpUrl: this.cdpUrl, targetId: this.targetId, cookie });
+  }
+  /** Clear all cookies in the browser context. */
+  async clearCookies() {
+    return cookiesClearViaPlaywright({ cdpUrl: this.cdpUrl, targetId: this.targetId });
+  }
+  /**
+   * Get values from localStorage or sessionStorage.
+   *
+   * @param kind - `'local'` for localStorage, `'session'` for sessionStorage
+   * @param key - Optional specific key to retrieve (returns all if omitted)
+   * @returns Key-value map of storage entries
+   */
+  async storageGet(kind, key) {
+    const result = await storageGetViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      kind,
+      key
+    });
+    return result.values;
+  }
+  /**
+   * Set a value in localStorage or sessionStorage.
+   *
+   * @param kind - `'local'` for localStorage, `'session'` for sessionStorage
+   * @param key - Storage key
+   * @param value - Storage value
+   */
+  async storageSet(kind, key, value) {
+    return storageSetViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      kind,
+      key,
+      value
+    });
+  }
+  /**
+   * Clear all entries in localStorage or sessionStorage.
+   *
+   * @param kind - `'local'` for localStorage, `'session'` for sessionStorage
+   */
+  async storageClear(kind) {
+    return storageClearViaPlaywright({
+      cdpUrl: this.cdpUrl,
+      targetId: this.targetId,
+      kind
+    });
+  }
+};
+var BrowserClaw = class _BrowserClaw {
+  cdpUrl;
+  chrome;
+  constructor(cdpUrl, chrome) {
+    this.cdpUrl = cdpUrl;
+    this.chrome = chrome;
+  }
+  /**
+   * Launch a new Chrome instance and connect to it.
+   *
+   * Automatically detects Chrome, Brave, Edge, or Chromium on the system.
+   * Creates a dedicated browser profile to avoid conflicts with your daily browser.
+   *
+   * @param opts - Launch options (headless, executablePath, cdpPort, etc.)
+   * @returns A connected BrowserClaw instance
+   *
+   * @example
+   * ```ts
+   * // Default: visible Chrome window
+   * const browser = await BrowserClaw.launch();
+   *
+   * // Headless mode
+   * const browser = await BrowserClaw.launch({ headless: true });
+   *
+   * // Specific browser
+   * const browser = await BrowserClaw.launch({
+   *   executablePath: '/usr/bin/google-chrome',
+   * });
+   * ```
+   */
+  static async launch(opts = {}) {
+    const chrome = await launchChrome(opts);
+    const cdpUrl = `http://127.0.0.1:${chrome.cdpPort}`;
+    return new _BrowserClaw(cdpUrl, chrome);
+  }
+  /**
+   * Connect to an already-running Chrome instance via its CDP endpoint.
+   *
+   * The Chrome instance must have been started with `--remote-debugging-port`.
+   *
+   * @param cdpUrl - CDP endpoint URL (e.g. `'http://localhost:9222'`)
+   * @returns A connected BrowserClaw instance
+   *
+   * @example
+   * ```ts
+   * // Chrome started with: chrome --remote-debugging-port=9222
+   * const browser = await BrowserClaw.connect('http://localhost:9222');
+   * ```
+   */
+  static async connect(cdpUrl) {
+    if (!await isChromeReachable(cdpUrl, 3e3)) {
+      throw new Error(`Cannot connect to Chrome at ${cdpUrl}. Is Chrome running with --remote-debugging-port?`);
+    }
+    await connectBrowser(cdpUrl);
+    return new _BrowserClaw(cdpUrl, null);
+  }
+  /**
+   * Open a URL in a new tab and return the page handle.
+   *
+   * @param url - URL to navigate to
+   * @returns A CrawlPage for the new tab
+   *
+   * @example
+   * ```ts
+   * const page = await browser.open('https://example.com');
+   * const { snapshot, refs } = await page.snapshot();
+   * ```
+   */
+  async open(url) {
+    const tab = await createPageViaPlaywright({ cdpUrl: this.cdpUrl, url });
+    return new CrawlPage(this.cdpUrl, tab.targetId);
+  }
+  /**
+   * Get a CrawlPage handle for the currently active tab.
+   *
+   * @returns CrawlPage for the first/active page
+   */
+  async currentPage() {
+    const { browser } = await connectBrowser(this.cdpUrl);
+    const pages = await getAllPages(browser);
+    if (!pages.length) throw new Error("No pages available");
+    const tid = await pageTargetId(pages[0]).catch(() => null);
+    return new CrawlPage(this.cdpUrl, tid ?? "");
+  }
+  /**
+   * List all open tabs.
+   *
+   * @returns Array of tab information objects
+   */
+  async tabs() {
+    return listPagesViaPlaywright({ cdpUrl: this.cdpUrl });
+  }
+  /**
+   * Bring a tab to the foreground.
+   *
+   * @param targetId - CDP target ID of the tab (from `tabs()` or `page.id`)
+   */
+  async focus(targetId) {
+    return focusPageByTargetIdViaPlaywright({ cdpUrl: this.cdpUrl, targetId });
+  }
+  /**
+   * Close a tab.
+   *
+   * @param targetId - CDP target ID of the tab to close
+   */
+  async close(targetId) {
+    return closePageByTargetIdViaPlaywright({ cdpUrl: this.cdpUrl, targetId });
+  }
+  /**
+   * Get a CrawlPage handle for a specific tab by its target ID.
+   *
+   * Unlike `open()`, this doesn't create a new tab — it wraps an existing one.
+   *
+   * @param targetId - CDP target ID of the tab
+   * @returns CrawlPage for the specified tab
+   */
+  page(targetId) {
+    return new CrawlPage(this.cdpUrl, targetId);
+  }
+  /** The CDP endpoint URL for this browser connection. */
+  get url() {
+    return this.cdpUrl;
+  }
+  /**
+   * Stop the browser and clean up all resources.
+   *
+   * If the browser was launched by `BrowserClaw.launch()`, the Chrome process
+   * will be terminated. If connected via `BrowserClaw.connect()`, only the
+   * Playwright connection is closed.
+   */
+  async stop() {
+    await disconnectBrowser();
+    if (this.chrome) {
+      await stopChrome(this.chrome);
+      this.chrome = null;
+    }
+  }
+};
+
+export { BrowserClaw, CrawlPage };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map