browserclaw 0.4.3 → 0.5.1

package/dist/index.cjs

@@ -7,14 +7,36 @@ var net = require('net');
 var child_process = require('child_process');
 var playwrightCore = require('playwright-core');
 var promises = require('dns/promises');
+var dns = require('dns');
 var promises$1 = require('fs/promises');
+var crypto = require('crypto');
+var ipaddr = require('ipaddr.js');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
 var os__default = /*#__PURE__*/_interopDefault(os);
 var path__default = /*#__PURE__*/_interopDefault(path);
 var fs__default = /*#__PURE__*/_interopDefault(fs);
 var net__default = /*#__PURE__*/_interopDefault(net);
+var ipaddr__namespace = /*#__PURE__*/_interopNamespace(ipaddr);
 
 // src/chrome-launcher.ts
 var CHROMIUM_BUNDLE_IDS = /* @__PURE__ */ new Set([
@@ -624,8 +646,31 @@ async function stopChrome(running, timeoutMs = 2500) {
 var cached = null;
 var connectingByUrl = /* @__PURE__ */ new Map();
 var pageStates = /* @__PURE__ */ new WeakMap();
+var contextStates = /* @__PURE__ */ new WeakMap();
 var observedContexts = /* @__PURE__ */ new WeakSet();
 var observedPages = /* @__PURE__ */ new WeakSet();
+var nextUploadArmId = 0;
+var nextDialogArmId = 0;
+var nextDownloadArmId = 0;
+function bumpUploadArmId() {
+  nextUploadArmId += 1;
+  return nextUploadArmId;
+}
+function bumpDialogArmId() {
+  nextDialogArmId += 1;
+  return nextDialogArmId;
+}
+function bumpDownloadArmId() {
+  nextDownloadArmId += 1;
+  return nextDownloadArmId;
+}
+function ensureContextState(context) {
+  const existing = contextStates.get(context);
+  if (existing) return existing;
+  const state = { traceActive: false };
+  contextStates.set(context, state);
+  return state;
+}
 var roleRefsByTarget = /* @__PURE__ */ new Map();
 var MAX_ROLE_REFS_CACHE = 50;
 var MAX_CONSOLE_MESSAGES = 500;
@@ -645,7 +690,10 @@ function ensurePageState(page) {
     errors: [],
     requests: [],
     requestIds: /* @__PURE__ */ new WeakMap(),
-    nextRequestId: 0
+    nextRequestId: 0,
+    armIdUpload: 0,
+    armIdDialog: 0,
+    armIdDownload: 0
   };
   pageStates.set(page, state);
   if (!observedPages.has(page)) {
@@ -722,6 +770,7 @@ function applyStealthToPage(page) {
 function observeContext(context) {
   if (observedContexts.has(context)) return;
   observedContexts.add(context);
+  ensureContextState(context);
   context.addInitScript(STEALTH_SCRIPT).catch((e) => {
     if (process.env.DEBUG) console.warn("[browserclaw] stealth initScript failed:", e.message);
   });
@@ -817,6 +866,35 @@ async function disconnectBrowser() {
   if (cur) await cur.browser.close().catch(() => {
   });
 }
+async function forceDisconnectPlaywrightForTarget(opts) {
+  const normalized = normalizeCdpUrl(opts.cdpUrl);
+  const cur = cached;
+  if (!cur || cur.cdpUrl !== normalized) return;
+  cached = null;
+  connectingByUrl.delete(normalized);
+  const targetId = opts.targetId?.trim() || "";
+  if (targetId) {
+    try {
+      const pages = await getAllPages(cur.browser);
+      for (const page of pages) {
+        const tid = await pageTargetId(page).catch(() => null);
+        if (tid === targetId) {
+          const session = await page.context().newCDPSession(page);
+          try {
+            await session.send("Runtime.terminateExecution");
+          } finally {
+            await session.detach().catch(() => {
+            });
+          }
+          break;
+        }
+      }
+    } catch {
+    }
+  }
+  cur.browser.close().catch(() => {
+  });
+}
 async function getAllPages(browser) {
   return browser.contexts().flatMap((c) => c.pages());
 }
@@ -1338,6 +1416,11 @@ function withBrowserNavigationPolicy(ssrfPolicy) {
 var NETWORK_NAVIGATION_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
 var SAFE_NON_NETWORK_URLS = /* @__PURE__ */ new Set(["about:blank"]);
 var PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"];
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
+  "localhost",
+  "localhost.localdomain",
+  "metadata.google.internal"
+]);
 function isAllowedNonNetworkNavigationUrl(parsed) {
   return SAFE_NON_NETWORK_URLS.has(parsed.href);
 }
@@ -1351,6 +1434,261 @@ function hasProxyEnvConfigured(env = process.env) {
   }
   return false;
 }
+function normalizeHostname(hostname) {
+  let h = String(hostname ?? "").trim().toLowerCase();
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  if (h.endsWith(".")) h = h.slice(0, -1);
+  return h;
+}
+function isBlockedHostnameNormalized(normalized) {
+  if (BLOCKED_HOSTNAMES.has(normalized)) return true;
+  return normalized.endsWith(".localhost") || normalized.endsWith(".local") || normalized.endsWith(".internal");
+}
+function isStrictDecimalOctet(part) {
+  if (!/^[0-9]+$/.test(part)) return false;
+  const n = parseInt(part, 10);
+  if (n < 0 || n > 255) return false;
+  if (String(n) !== part) return false;
+  return true;
+}
+function isUnsupportedIPv4Literal(ip) {
+  if (/^[0-9]+$/.test(ip)) return true;
+  const parts = ip.split(".");
+  if (parts.length !== 4) return true;
+  if (!parts.every(isStrictDecimalOctet)) return true;
+  return false;
+}
+var BLOCKED_IPV4_RANGES = /* @__PURE__ */ new Set([
+  "unspecified",
+  "broadcast",
+  "multicast",
+  "linkLocal",
+  "loopback",
+  "carrierGradeNat",
+  "private",
+  "reserved"
+]);
+var BLOCKED_IPV6_RANGES = /* @__PURE__ */ new Set([
+  "unspecified",
+  "loopback",
+  "linkLocal",
+  "uniqueLocal",
+  "multicast"
+]);
+var RFC2544_BENCHMARK_PREFIX = [ipaddr__namespace.IPv4.parse("198.18.0.0"), 15];
+function isBlockedSpecialUseIpv4Address(address, opts) {
+  const inRfc2544 = address.match(RFC2544_BENCHMARK_PREFIX);
+  if (inRfc2544 && opts?.allowRfc2544BenchmarkRange === true) return false;
+  return BLOCKED_IPV4_RANGES.has(address.range()) || inRfc2544;
+}
+function isBlockedSpecialUseIpv6Address(address) {
+  if (BLOCKED_IPV6_RANGES.has(address.range())) return true;
+  return (address.parts[0] & 65472) === 65216;
+}
+function extractEmbeddedIpv4FromIpv6(v6, opts) {
+  if (v6.isIPv4MappedAddress()) {
+    return isBlockedSpecialUseIpv4Address(v6.toIPv4Address(), opts);
+  }
+  const parts = v6.parts;
+  if (parts[0] === 100 && parts[1] === 65435 && parts[2] === 0 && parts[3] === 0 && parts[4] === 0 && parts[5] === 0) {
+    const ip4str = `${parts[6] >> 8 & 255}.${parts[6] & 255}.${parts[7] >> 8 & 255}.${parts[7] & 255}`;
+    try {
+      return isBlockedSpecialUseIpv4Address(ipaddr__namespace.IPv4.parse(ip4str), opts);
+    } catch {
+      return true;
+    }
+  }
+  if (parts[0] === 100 && parts[1] === 65435 && parts[2] === 1) {
+    const ip4str = `${parts[6] >> 8 & 255}.${parts[6] & 255}.${parts[7] >> 8 & 255}.${parts[7] & 255}`;
+    try {
+      return isBlockedSpecialUseIpv4Address(ipaddr__namespace.IPv4.parse(ip4str), opts);
+    } catch {
+      return true;
+    }
+  }
+  if (parts[0] === 8194) {
+    const ip4str = `${parts[1] >> 8 & 255}.${parts[1] & 255}.${parts[2] >> 8 & 255}.${parts[2] & 255}`;
+    try {
+      return isBlockedSpecialUseIpv4Address(ipaddr__namespace.IPv4.parse(ip4str), opts);
+    } catch {
+      return true;
+    }
+  }
+  if (parts[0] === 8193 && parts[1] === 0) {
+    const hiXored = parts[6] ^ 65535;
+    const loXored = parts[7] ^ 65535;
+    const ip4str = `${hiXored >> 8 & 255}.${hiXored & 255}.${loXored >> 8 & 255}.${loXored & 255}`;
+    try {
+      return isBlockedSpecialUseIpv4Address(ipaddr__namespace.IPv4.parse(ip4str), opts);
+    } catch {
+      return true;
+    }
+  }
+  if (parts[0] === 0 && parts[1] === 0 && parts[2] === 0 && parts[3] === 0 && parts[4] === 0 && parts[5] === 0) {
+    const ip4str = `${parts[6] >> 8 & 255}.${parts[6] & 255}.${parts[7] >> 8 & 255}.${parts[7] & 255}`;
+    try {
+      return isBlockedSpecialUseIpv4Address(ipaddr__namespace.IPv4.parse(ip4str), opts);
+    } catch {
+      return true;
+    }
+  }
+  if ((parts[4] & 65023) === 0 && parts[5] === 24318) {
+    const ip4str = `${parts[6] >> 8 & 255}.${parts[6] & 255}.${parts[7] >> 8 & 255}.${parts[7] & 255}`;
+    try {
+      return isBlockedSpecialUseIpv4Address(ipaddr__namespace.IPv4.parse(ip4str), opts);
+    } catch {
+      return true;
+    }
+  }
+  return null;
+}
+function isPrivateIpAddress(address, opts) {
+  let normalized = address.trim().toLowerCase();
+  if (normalized.startsWith("[") && normalized.endsWith("]")) normalized = normalized.slice(1, -1);
+  if (!normalized) return false;
+  try {
+    const parsed = ipaddr__namespace.parse(normalized);
+    if (parsed.kind() === "ipv4") {
+      return isBlockedSpecialUseIpv4Address(parsed, opts);
+    }
+    const v6 = parsed;
+    if (isBlockedSpecialUseIpv6Address(v6)) return true;
+    const embeddedV4 = extractEmbeddedIpv4FromIpv6(v6, opts);
+    if (embeddedV4 !== null) return embeddedV4;
+    return false;
+  } catch {
+  }
+  if (!normalized.includes(":") && isUnsupportedIPv4Literal(normalized)) return true;
+  if (normalized.includes(":")) return true;
+  return false;
+}
+function normalizeHostnameSet(values) {
+  if (!values || values.length === 0) return /* @__PURE__ */ new Set();
+  return new Set(values.map((v) => normalizeHostname(v)).filter(Boolean));
+}
+function normalizeHostnameAllowlist(values) {
+  if (!values || values.length === 0) return [];
+  return Array.from(
+    new Set(
+      values.map((v) => normalizeHostname(v)).filter((v) => v !== "*" && v !== "*." && v.length > 0)
+    )
+  );
+}
+function isHostnameAllowedByPattern(hostname, pattern) {
+  if (pattern.startsWith("*.")) {
+    const suffix = pattern.slice(2);
+    if (!suffix || hostname === suffix) return false;
+    return hostname.endsWith(`.${suffix}`);
+  }
+  return hostname === pattern;
+}
+function matchesHostnameAllowlist(hostname, allowlist) {
+  if (allowlist.length === 0) return true;
+  return allowlist.some((pattern) => isHostnameAllowedByPattern(hostname, pattern));
+}
+function dedupeAndPreferIpv4(results) {
+  const seen = /* @__PURE__ */ new Set();
+  const ipv4 = [];
+  const ipv6 = [];
+  for (const r of results) {
+    if (seen.has(r.address)) continue;
+    seen.add(r.address);
+    if (r.family === 4) ipv4.push(r.address);
+    else ipv6.push(r.address);
+  }
+  return [...ipv4, ...ipv6];
+}
+function createPinnedLookup(params) {
+  const normalizedHost = normalizeHostname(params.hostname);
+  const fallback = params.fallback ?? dns.lookup;
+  const records = params.addresses.map((address) => ({
+    address,
+    family: address.includes(":") ? 6 : 4
+  }));
+  let index = 0;
+  return ((host, options, callback) => {
+    const cb = typeof options === "function" ? options : callback;
+    if (!cb) return;
+    const normalized = normalizeHostname(host);
+    if (!normalized || normalized !== normalizedHost) {
+      if (typeof options === "function" || options === void 0) return fallback(host, cb);
+      return fallback(host, options, cb);
+    }
+    const opts = typeof options === "object" && options !== null ? options : {};
+    const requestedFamily = typeof options === "number" ? options : typeof opts.family === "number" ? opts.family : 0;
+    const candidates = requestedFamily === 4 || requestedFamily === 6 ? records.filter((entry) => entry.family === requestedFamily) : records;
+    const usable = candidates.length > 0 ? candidates : records;
+    if (opts.all) {
+      cb(null, usable);
+      return;
+    }
+    const chosen = usable[index % usable.length];
+    index += 1;
+    cb(null, chosen.address, chosen.family);
+  });
+}
+async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
+  const normalized = normalizeHostname(hostname);
+  if (!normalized) throw new InvalidBrowserNavigationUrlError(`Invalid hostname: "${hostname}"`);
+  const allowPrivateNetwork = isPrivateNetworkAllowedByPolicy(params.policy);
+  const allowedHostnames = normalizeHostnameSet(params.policy?.allowedHostnames);
+  const hostnameAllowlist = normalizeHostnameAllowlist(params.policy?.hostnameAllowlist);
+  const isExplicitlyAllowed = allowedHostnames.has(normalized);
+  const skipPrivateNetworkChecks = allowPrivateNetwork || isExplicitlyAllowed;
+  if (!matchesHostnameAllowlist(normalized, hostnameAllowlist)) {
+    throw new InvalidBrowserNavigationUrlError(
+      `Navigation blocked: hostname "${hostname}" is not in the allowlist.`
+    );
+  }
+  if (!skipPrivateNetworkChecks) {
+    if (isBlockedHostnameNormalized(normalized)) {
+      throw new InvalidBrowserNavigationUrlError(
+        `Navigation to internal/loopback address blocked: "${hostname}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
+      );
+    }
+    const ipOpts = { allowRfc2544BenchmarkRange: params.policy?.allowRfc2544BenchmarkRange };
+    if (isPrivateIpAddress(normalized, ipOpts)) {
+      throw new InvalidBrowserNavigationUrlError(
+        `Navigation to internal/loopback address blocked: "${hostname}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
+      );
+    }
+  }
+  const lookupFn = params.lookupFn ?? promises.lookup;
+  let results;
+  try {
+    results = await lookupFn(normalized, { all: true });
+  } catch {
+    throw new InvalidBrowserNavigationUrlError(
+      `Navigation to internal/loopback address blocked: unable to resolve "${hostname}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
+    );
+  }
+  if (!results || results.length === 0) {
+    throw new InvalidBrowserNavigationUrlError(
+      `Navigation to internal/loopback address blocked: unable to resolve "${hostname}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
+    );
+  }
+  if (!skipPrivateNetworkChecks) {
+    const ipOpts = { allowRfc2544BenchmarkRange: params.policy?.allowRfc2544BenchmarkRange };
+    for (const r of results) {
+      if (isPrivateIpAddress(r.address, ipOpts)) {
+        throw new InvalidBrowserNavigationUrlError(
+          `Navigation to internal/loopback address blocked: "${hostname}" resolves to "${r.address}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
+        );
+      }
+    }
+  }
+  const addresses = dedupeAndPreferIpv4(results);
+  if (addresses.length === 0) {
+    throw new InvalidBrowserNavigationUrlError(
+      `Navigation to internal/loopback address blocked: unable to resolve "${hostname}".`
+    );
+  }
+  return {
+    hostname: normalized,
+    addresses,
+    lookup: createPinnedLookup({ hostname: normalized, addresses })
+  };
+}
 async function assertBrowserNavigationAllowed(opts) {
   const rawUrl = String(opts.url ?? "").trim();
   let parsed;
@@ -1368,22 +1706,10 @@ async function assertBrowserNavigationAllowed(opts) {
       "Navigation blocked: strict browser SSRF policy cannot be enforced while env proxy variables are set"
     );
   }
-  const policy = opts.ssrfPolicy;
-  if (policy?.dangerouslyAllowPrivateNetwork ?? policy?.allowPrivateNetwork ?? true) return;
-  const allowedHostnames = [
-    ...policy?.allowedHostnames ?? [],
-    ...policy?.hostnameAllowlist ?? []
-  ];
-  if (allowedHostnames.length) {
-    const hostname = parsed.hostname.toLowerCase();
-    if (allowedHostnames.some((h) => h.toLowerCase() === hostname)) return;
-  }
-  const ipOpts = { allowRfc2544BenchmarkRange: policy?.allowRfc2544BenchmarkRange };
-  if (await isInternalUrlResolved(rawUrl, opts.lookupFn, ipOpts)) {
-    throw new InvalidBrowserNavigationUrlError(
-      `Navigation to internal/loopback address blocked: "${rawUrl}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
-    );
-  }
+  await resolvePinnedHostnameWithPolicy(parsed.hostname, {
+    lookupFn: opts.lookupFn,
+    policy: opts.ssrfPolicy
+  });
 }
 async function assertSafeOutputPath(path2, allowedRoots) {
   if (!path2 || typeof path2 !== "string") {
@@ -1426,111 +1752,6 @@ async function assertSafeOutputPath(path2, allowedRoots) {
     }
   }
 }
-function expandIPv6(ip) {
-  let normalized = ip;
-  const v4Match = normalized.match(/^(.+:)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
-  if (v4Match) {
-    const octets = v4Match[2].split(".").map(Number);
-    if (octets.some((o) => o > 255)) return null;
-    const hexHi = (octets[0] << 8 | octets[1]).toString(16).padStart(4, "0");
-    const hexLo = (octets[2] << 8 | octets[3]).toString(16).padStart(4, "0");
-    normalized = v4Match[1] + hexHi + ":" + hexLo;
-  }
-  const halves = normalized.split("::");
-  if (halves.length > 2) return null;
-  if (halves.length === 2) {
-    const left = halves[0] !== "" ? halves[0].split(":") : [];
-    const right = halves[1] !== "" ? halves[1].split(":") : [];
-    const needed = 8 - left.length - right.length;
-    if (needed < 0) return null;
-    const groups2 = [...left, ...Array(needed).fill("0"), ...right];
-    if (groups2.length !== 8) return null;
-    return groups2.map((g) => g.padStart(4, "0")).join(":");
-  }
-  const groups = normalized.split(":");
-  if (groups.length !== 8) return null;
-  return groups.map((g) => g.padStart(4, "0")).join(":");
-}
-function hexToIPv4(hiHex, loHex) {
-  const hi = parseInt(hiHex, 16);
-  const lo = parseInt(loHex, 16);
-  return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
-}
-function extractEmbeddedIPv4(lower) {
-  if (lower.startsWith("::ffff:")) {
-    return lower.slice(7);
-  }
-  const expanded = expandIPv6(lower);
-  if (expanded === null) return "";
-  const groups = expanded.split(":");
-  if (groups.length !== 8) return "";
-  if (groups[0] === "0064" && groups[1] === "ff9b" && groups[2] === "0000" && groups[3] === "0000" && groups[4] === "0000" && groups[5] === "0000") {
-    return hexToIPv4(groups[6], groups[7]);
-  }
-  if (groups[0] === "0064" && groups[1] === "ff9b" && groups[2] === "0001") {
-    return hexToIPv4(groups[6], groups[7]);
-  }
-  if (groups[0] === "2002") {
-    return hexToIPv4(groups[1], groups[2]);
-  }
-  if (groups[0] === "2001" && groups[1] === "0000") {
-    const hiXored = (parseInt(groups[6], 16) ^ 65535).toString(16).padStart(4, "0");
-    const loXored = (parseInt(groups[7], 16) ^ 65535).toString(16).padStart(4, "0");
-    return hexToIPv4(hiXored, loXored);
-  }
-  return null;
-}
-function isStrictDecimalOctet(part) {
-  if (!/^[0-9]+$/.test(part)) return false;
-  const n = parseInt(part, 10);
-  if (n < 0 || n > 255) return false;
-  if (String(n) !== part) return false;
-  return true;
-}
-function isUnsupportedIPv4Literal(ip) {
-  if (/^[0-9]+$/.test(ip)) return true;
-  const parts = ip.split(".");
-  if (parts.length !== 4) return true;
-  if (!parts.every(isStrictDecimalOctet)) return true;
-  return false;
-}
-function isInternalIP(ip, opts) {
-  if (!ip.includes(":") && isUnsupportedIPv4Literal(ip)) return true;
-  if (/^127\./.test(ip)) return true;
-  if (/^10\./.test(ip)) return true;
-  if (/^172\.(1[6-9]|2\d|3[01])\./.test(ip)) return true;
-  if (/^192\.168\./.test(ip)) return true;
-  if (/^169\.254\./.test(ip)) return true;
-  if (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(ip)) return true;
-  if (ip === "0.0.0.0") return true;
-  if (!opts?.allowRfc2544BenchmarkRange && /^198\.1[89]\./.test(ip)) return true;
-  const lower = ip.toLowerCase();
-  if (lower === "::1") return true;
-  if (lower.startsWith("fe80:")) return true;
-  if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
-  if (lower.startsWith("ff")) return true;
-  const embedded = extractEmbeddedIPv4(lower);
-  if (embedded !== null) {
-    if (embedded === "") return true;
-    return isInternalIP(embedded, opts);
-  }
-  return false;
-}
-function isInternalUrl(url, opts) {
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return true;
-  }
-  const hostname = parsed.hostname.toLowerCase();
-  if (hostname === "localhost") return true;
-  if (isInternalIP(hostname, opts)) return true;
-  if (hostname.endsWith(".local") || hostname.endsWith(".internal") || hostname.endsWith(".localhost")) {
-    return true;
-  }
-  return false;
-}
 async function assertSafeUploadPaths(paths) {
   for (const filePath of paths) {
     let stat;
@@ -1547,21 +1768,48 @@ async function assertSafeUploadPaths(paths) {
     }
   }
 }
-async function isInternalUrlResolved(url, lookupFn = promises.lookup, opts) {
-  if (isInternalUrl(url, opts)) return true;
-  let parsed;
+function sanitizeUntrustedFileName(fileName, fallbackName) {
+  const trimmed = String(fileName ?? "").trim();
+  if (!trimmed) return fallbackName;
+  let base = path.posix.basename(trimmed);
+  base = path.win32.basename(base);
+  let cleaned = "";
+  for (let i = 0; i < base.length; i++) {
+    const code = base.charCodeAt(i);
+    if (code < 32 || code === 127) continue;
+    cleaned += base[i];
+  }
+  base = cleaned.trim();
+  if (!base || base === "." || base === "..") return fallbackName;
+  if (base.length > 200) base = base.slice(0, 200);
+  return base;
+}
+function buildSiblingTempPath(targetPath) {
+  const id = crypto.randomUUID();
+  const safeTail = sanitizeUntrustedFileName(path.basename(targetPath), "output.bin");
+  return path.join(path.dirname(targetPath), `.browserclaw-output-${id}-${safeTail}.part`);
+}
+async function writeViaSiblingTempPath(params) {
+  const rootDir = await promises$1.realpath(path.resolve(params.rootDir)).catch(() => path.resolve(params.rootDir));
+  const requestedTargetPath = path.resolve(params.targetPath);
+  const targetPath = await promises$1.realpath(path.dirname(requestedTargetPath)).then((realDir) => path.join(realDir, path.basename(requestedTargetPath))).catch(() => requestedTargetPath);
+  const relativeTargetPath = path.relative(rootDir, targetPath);
+  if (!relativeTargetPath || relativeTargetPath === ".." || relativeTargetPath.startsWith(`..${path.sep}`) || isAbsolute(relativeTargetPath)) {
+    throw new Error("Target path is outside the allowed root");
+  }
+  const tempPath = buildSiblingTempPath(targetPath);
+  let renameSucceeded = false;
   try {
-    parsed = new URL(url);
-  } catch {
-    return true;
-  }
-  try {
-    const { address } = await lookupFn(parsed.hostname);
-    if (isInternalIP(address, opts)) return true;
-  } catch {
-    return true;
+    await params.writeTemp(tempPath);
+    await promises$1.rename(tempPath, targetPath);
+    renameSucceeded = true;
+  } finally {
+    if (!renameSucceeded) await promises$1.rm(tempPath, { force: true }).catch(() => {
+    });
   }
-  return false;
+}
+function isAbsolute(p) {
+  return p.startsWith("/") || /^[a-zA-Z]:/.test(p);
 }
 async function assertBrowserNavigationResultAllowed(opts) {
   const rawUrl = String(opts.url ?? "").trim();
@@ -1669,13 +1917,12 @@ async function fillFormViaPlaywright(opts) {
   ensurePageState(page);
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 8e3, 6e4);
-  for (let i = 0; i < opts.fields.length; i++) {
-    const field = opts.fields[i];
+  for (const field of opts.fields) {
     const ref = field.ref.trim();
     const type = (typeof field.type === "string" ? field.type.trim() : "") || "text";
     const rawValue = field.value;
-    const value = rawValue == null ? "" : String(rawValue);
-    if (!ref) throw new Error(`fill(): field at index ${i} has empty ref`);
+    const value = typeof rawValue === "string" ? rawValue : typeof rawValue === "number" || typeof rawValue === "boolean" ? String(rawValue) : "";
+    if (!ref) continue;
     const locator = refLocator(page, ref);
     if (type === "checkbox" || type === "radio") {
       const checked = rawValue === true || rawValue === 1 || rawValue === "1" || rawValue === "true";
@@ -1719,61 +1966,78 @@ async function setInputFilesViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
-  const locator = opts.ref ? refLocator(page, opts.ref) : opts.element ? page.locator(opts.element).first() : null;
-  if (!locator) throw new Error("Either ref or element is required for setInputFiles");
+  if (!opts.paths.length) throw new Error("paths are required");
+  const inputRef = typeof opts.ref === "string" ? opts.ref.trim() : "";
+  const element = typeof opts.element === "string" ? opts.element.trim() : "";
+  if (inputRef && element) throw new Error("ref and element are mutually exclusive");
+  if (!inputRef && !element) throw new Error("Either ref or element is required for setInputFiles");
+  const locator = inputRef ? refLocator(page, inputRef) : page.locator(element).first();
   await assertSafeUploadPaths(opts.paths);
   try {
     await locator.setInputFiles(opts.paths);
   } catch (err) {
-    throw toAIFriendlyError(err, opts.ref ?? opts.element ?? "unknown");
+    throw toAIFriendlyError(err, inputRef || element);
+  }
+  try {
+    const handle = await locator.elementHandle();
+    if (handle) {
+      await handle.evaluate((el) => {
+        el.dispatchEvent(new Event("input", { bubbles: true }));
+        el.dispatchEvent(new Event("change", { bubbles: true }));
+      });
+    }
+  } catch {
   }
 }
 async function armDialogViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
-  return new Promise((resolve2, reject) => {
-    const timer = setTimeout(() => {
-      page.removeListener("dialog", handler);
-      reject(new Error(`No dialog appeared within ${timeout}ms`));
-    }, timeout);
-    const handler = async (dialog) => {
-      clearTimeout(timer);
-      try {
-        if (opts.accept) {
-          await dialog.accept(opts.promptText);
-        } else {
-          await dialog.dismiss();
-        }
-        resolve2();
-      } catch (err) {
-        reject(err);
-      }
-    };
-    page.once("dialog", handler);
+  const state = ensurePageState(page);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
+  state.armIdDialog = bumpDialogArmId();
+  const armId = state.armIdDialog;
+  page.waitForEvent("dialog", { timeout }).then(async (dialog) => {
+    if (state.armIdDialog !== armId) return;
+    if (opts.accept) await dialog.accept(opts.promptText);
+    else await dialog.dismiss();
+  }).catch(() => {
   });
 }
 async function armFileUploadViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
-  return new Promise((resolve2, reject) => {
-    const timer = setTimeout(() => {
-      page.removeListener("filechooser", handler);
-      reject(new Error(`No file chooser appeared within ${timeout}ms`));
-    }, timeout);
-    const handler = async (fc) => {
-      clearTimeout(timer);
+  const state = ensurePageState(page);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
+  state.armIdUpload = bumpUploadArmId();
+  const armId = state.armIdUpload;
+  page.waitForEvent("filechooser", { timeout }).then(async (fileChooser) => {
+    if (state.armIdUpload !== armId) return;
+    if (!opts.paths?.length) {
       try {
-        const paths = opts.paths ?? [];
-        if (paths.length > 0) await assertSafeUploadPaths(paths);
-        await fc.setFiles(paths);
-        resolve2();
-      } catch (err) {
-        reject(err);
+        await page.keyboard.press("Escape");
+      } catch {
       }
-    };
-    page.once("filechooser", handler);
+      return;
+    }
+    try {
+      await assertSafeUploadPaths(opts.paths);
+    } catch {
+      try {
+        await page.keyboard.press("Escape");
+      } catch {
+      }
+      return;
+    }
+    await fileChooser.setFiles(opts.paths);
+    try {
+      const input = typeof fileChooser.element === "function" ? await Promise.resolve(fileChooser.element()) : null;
+      if (input) {
+        await input.evaluate((el) => {
+          el.dispatchEvent(new Event("input", { bubbles: true }));
+          el.dispatchEvent(new Event("change", { bubbles: true }));
+        });
+      }
+    } catch {
+    }
+  }).catch(() => {
   });
 }
 
@@ -1787,17 +2051,35 @@ async function pressKeyViaPlaywright(opts) {
 }
 
 // src/actions/navigation.ts
+function isRetryableNavigateError(err) {
+  const msg = typeof err === "string" ? err.toLowerCase() : err instanceof Error ? err.message.toLowerCase() : "";
+  return msg.includes("frame has been detached") || msg.includes("target page, context or browser has been closed");
+}
 async function navigateViaPlaywright(opts) {
   const url = String(opts.url ?? "").trim();
   if (!url) throw new Error("url is required");
   const policy = opts.allowInternal ? { ...opts.ssrfPolicy, dangerouslyAllowPrivateNetwork: true } : opts.ssrfPolicy;
-  await assertBrowserNavigationAllowed({ url, ssrfPolicy: policy });
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+  await assertBrowserNavigationAllowed({ url, ...withBrowserNavigationPolicy(policy) });
+  const timeout = Math.max(1e3, Math.min(12e4, opts.timeoutMs ?? 2e4));
+  let page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  const response = await page.goto(url, { timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4) });
+  const navigate = async () => await page.goto(url, { timeout });
+  let response;
+  try {
+    response = await navigate();
+  } catch (err) {
+    if (!isRetryableNavigateError(err)) throw err;
+    await forceDisconnectPlaywrightForTarget({
+      cdpUrl: opts.cdpUrl,
+      targetId: opts.targetId}).catch(() => {
+    });
+    page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
+    ensurePageState(page);
+    response = await navigate();
+  }
   await assertBrowserNavigationRedirectChainAllowed({ request: response?.request(), ...withBrowserNavigationPolicy(policy) });
   const finalUrl = page.url();
-  await assertBrowserNavigationResultAllowed({ url: finalUrl, ssrfPolicy: policy });
+  await assertBrowserNavigationResultAllowed({ url: finalUrl, ...withBrowserNavigationPolicy(policy) });
   return { url: finalUrl };
 }
 async function listPagesViaPlaywright(opts) {
@@ -1823,11 +2105,12 @@ 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);
   if (targetUrl !== "about:blank") {
     const navigationPolicy = withBrowserNavigationPolicy(policy);
-    const response = await page.goto(targetUrl, { timeout: normalizeTimeoutMs(void 0, 2e4) }).catch(() => null);
+    const response = await page.goto(targetUrl, { timeout: 3e4 }).catch(() => null);
     await assertBrowserNavigationRedirectChainAllowed({ request: response?.request(), ...navigationPolicy });
     await assertBrowserNavigationResultAllowed({ url: page.url(), ssrfPolicy: policy });
   }
@@ -1936,68 +2219,136 @@ async function evaluateInAllFramesViaPlaywright(opts) {
   }
   return results;
 }
+async function awaitEvalWithAbort(evalPromise, abortPromise) {
+  if (!abortPromise) return await evalPromise;
+  try {
+    return await Promise.race([evalPromise, abortPromise]);
+  } catch (err) {
+    evalPromise.catch(() => {
+    });
+    throw err;
+  }
+}
+var BROWSER_EVALUATOR = new Function("args", `
+  "use strict";
+  var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
+  try {
+    var candidate = eval("(" + fnBody + ")");
+    var result = typeof candidate === "function" ? candidate() : candidate;
+    if (result && typeof result.then === "function") {
+      return Promise.race([
+        result,
+        new Promise(function(_, reject) {
+          setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
+        })
+      ]);
+    }
+    return result;
+  } catch (err) {
+    throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
+  }
+`);
+var ELEMENT_EVALUATOR = new Function("el", "args", `
+  "use strict";
+  var fnBody = args.fnBody, timeoutMs = args.timeoutMs;
+  try {
+    var candidate = eval("(" + fnBody + ")");
+    var result = typeof candidate === "function" ? candidate(el) : candidate;
+    if (result && typeof result.then === "function") {
+      return Promise.race([
+        result,
+        new Promise(function(_, reject) {
+          setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
+        })
+      ]);
+    }
+    return result;
+  } catch (err) {
+    throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
+  }
+`);
 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 });
-  const timeout = opts.timeoutMs != null ? opts.timeoutMs : void 0;
-  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 instanceof Error ? err.message : String(err)));
-        }
-      },
-      fnText,
-      { timeout }
+  const outerTimeout = normalizeTimeoutMs(opts.timeoutMs, 2e4);
+  let evaluateTimeout = Math.max(1e3, Math.min(12e4, outerTimeout - 500));
+  evaluateTimeout = Math.min(evaluateTimeout, outerTimeout);
+  const signal = opts.signal;
+  let abortListener;
+  let abortReject;
+  let abortPromise;
+  if (signal) {
+    abortPromise = new Promise((_, reject) => {
+      abortReject = reject;
+    });
+    abortPromise.catch(() => {
+    });
+  }
+  if (signal) {
+    const disconnect = () => {
+      forceDisconnectPlaywrightForTarget({
+        cdpUrl: opts.cdpUrl,
+        targetId: opts.targetId}).catch(() => {
+      });
+    };
+    if (signal.aborted) {
+      disconnect();
+      throw signal.reason ?? new Error("aborted");
+    }
+    abortListener = () => {
+      disconnect();
+      abortReject?.(signal.reason ?? new Error("aborted"));
+    };
+    signal.addEventListener("abort", abortListener, { once: true });
+    if (signal.aborted) {
+      abortListener();
+      throw signal.reason ?? new Error("aborted");
+    }
+  }
+  try {
+    if (opts.ref) {
+      const locator = refLocator(page, opts.ref);
+      return await awaitEvalWithAbort(
+        locator.evaluate(ELEMENT_EVALUATOR, { fnBody: fnText, timeoutMs: evaluateTimeout }),
+        abortPromise
+      );
+    }
+    return await awaitEvalWithAbort(
+      page.evaluate(BROWSER_EVALUATOR, { fnBody: fnText, timeoutMs: evaluateTimeout }),
+      abortPromise
     );
+  } finally {
+    if (signal && abortListener) signal.removeEventListener("abort", abortListener);
   }
-  const evalPromise = 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 instanceof Error ? err.message : String(err)));
-      }
-    },
-    fnText
-  );
-  if (!opts.signal) return evalPromise;
-  return Promise.race([
-    evalPromise,
-    new Promise((_, reject) => {
-      opts.signal.addEventListener("abort", () => reject(new Error("Evaluate aborted")), { once: true });
-    })
-  ]);
 }
-
-// src/actions/download.ts
 async function downloadViaPlaywright(opts) {
   await assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
+  const state = ensurePageState(page);
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
-  const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
   const locator = refLocator(page, opts.ref);
+  state.armIdDownload = bumpDownloadArmId();
   try {
     const [download] = await Promise.all([
       page.waitForEvent("download", { timeout }),
       locator.click({ timeout })
     ]);
-    await download.saveAs(opts.path);
+    const outPath = opts.path;
+    await writeViaSiblingTempPath({
+      rootDir: path.dirname(outPath),
+      targetPath: outPath,
+      writeTemp: async (tempPath) => {
+        await download.saveAs(tempPath);
+      }
+    });
     return {
       url: download.url(),
       suggestedFilename: download.suggestedFilename(),
-      path: opts.path
+      path: outPath
     };
   } catch (err) {
     throw toAIFriendlyError(err, opts.ref);
@@ -2006,11 +2357,17 @@ async function downloadViaPlaywright(opts) {
 async function waitForDownloadViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  const timeout = normalizeTimeoutMs(opts.timeoutMs, 3e4, 12e4);
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
   const download = await page.waitForEvent("download", { timeout });
   const savePath = opts.path ?? download.suggestedFilename();
   await assertSafeOutputPath(savePath, opts.allowedOutputRoots);
-  await download.saveAs(savePath);
+  await writeViaSiblingTempPath({
+    rootDir: path.dirname(savePath),
+    targetPath: savePath,
+    writeTemp: async (tempPath) => {
+      await download.saveAs(tempPath);
+    }
+  });
   return {
     url: download.url(),
     suggestedFilename: download.suggestedFilename(),
@@ -2023,33 +2380,51 @@ async function emulateMediaViaPlaywright(opts) {
   await page.emulateMedia({ colorScheme: opts.colorScheme });
 }
 async function setDeviceViaPlaywright(opts) {
-  const device = playwrightCore.devices[opts.name];
+  const name = String(opts.name ?? "").trim();
+  if (!name) throw new Error("device name is required");
+  const device = playwrightCore.devices[name];
   if (!device) {
-    const available = Object.keys(playwrightCore.devices).slice(0, 10).join(", ");
-    throw new Error(`Unknown device "${opts.name}". Some available devices: ${available}...`);
+    throw new Error(`Unknown device "${name}".`);
   }
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   if (device.viewport) {
-    await page.setViewportSize(device.viewport);
+    await page.setViewportSize({
+      width: device.viewport.width,
+      height: device.viewport.height
+    });
   }
-  if (device.userAgent) {
-    const context = page.context();
-    const session = await context.newCDPSession(page);
-    try {
+  const session = await page.context().newCDPSession(page);
+  try {
+    const locale = device.locale;
+    if (device.userAgent || locale) {
       await session.send("Emulation.setUserAgentOverride", {
-        userAgent: device.userAgent
+        userAgent: device.userAgent ?? "",
+        acceptLanguage: locale ?? void 0
       });
-    } finally {
-      await session.detach().catch(() => {
+    }
+    if (device.viewport) {
+      await session.send("Emulation.setDeviceMetricsOverride", {
+        mobile: Boolean(device.isMobile),
+        width: device.viewport.width,
+        height: device.viewport.height,
+        deviceScaleFactor: device.deviceScaleFactor ?? 1,
+        screenWidth: device.viewport.width,
+        screenHeight: device.viewport.height
       });
     }
+    if (device.hasTouch) {
+      await session.send("Emulation.setTouchEmulationEnabled", { enabled: true });
+    }
+  } finally {
+    await session.detach().catch(() => {
+    });
   }
 }
 async function setExtraHTTPHeadersViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  await page.setExtraHTTPHeaders(opts.headers);
+  await page.context().setExtraHTTPHeaders(opts.headers);
 }
 async function setGeolocationViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
@@ -2057,38 +2432,53 @@ async function setGeolocationViaPlaywright(opts) {
   const context = page.context();
   if (opts.clear) {
     await context.setGeolocation(null);
-    await context.clearPermissions();
+    await context.clearPermissions().catch(() => {
+    });
     return;
   }
-  if (opts.latitude === void 0 || opts.longitude === void 0) {
+  if (typeof opts.latitude !== "number" || typeof opts.longitude !== "number") {
     throw new Error("latitude and longitude are required (or set clear=true)");
   }
-  await context.grantPermissions(["geolocation"], opts.origin ? { origin: opts.origin } : void 0);
   await context.setGeolocation({
     latitude: opts.latitude,
     longitude: opts.longitude,
-    accuracy: opts.accuracy
+    accuracy: typeof opts.accuracy === "number" ? opts.accuracy : void 0
+  });
+  const origin = opts.origin?.trim() || (() => {
+    try {
+      return new URL(page.url()).origin;
+    } catch {
+      return "";
+    }
+  })();
+  if (origin) await context.grantPermissions(["geolocation"], { origin }).catch(() => {
   });
 }
 async function setHttpCredentialsViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  const context = page.context();
   if (opts.clear) {
-    await context.setHTTPCredentials({ username: "", password: "" });
+    await page.context().setHTTPCredentials(null);
     return;
   }
-  await context.setHTTPCredentials({
-    username: opts.username ?? "",
-    password: opts.password ?? ""
-  });
+  const username = String(opts.username ?? "");
+  const password = String(opts.password ?? "");
+  if (!username) throw new Error("username is required (or set clear=true)");
+  await page.context().setHTTPCredentials({ username, password });
 }
 async function setLocaleViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
+  const locale = String(opts.locale ?? "").trim();
+  if (!locale) throw new Error("locale is required");
   const session = await page.context().newCDPSession(page);
   try {
-    await session.send("Emulation.setLocaleOverride", { locale: opts.locale });
+    try {
+      await session.send("Emulation.setLocaleOverride", { locale });
+    } catch (err) {
+      if (String(err).includes("Another locale override is already in effect")) return;
+      throw err;
+    }
   } finally {
     await session.detach().catch(() => {
     });
@@ -2102,9 +2492,18 @@ async function setOfflineViaPlaywright(opts) {
 async function setTimezoneViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
+  const timezoneId = String(opts.timezoneId ?? "").trim();
+  if (!timezoneId) throw new Error("timezoneId is required");
   const session = await page.context().newCDPSession(page);
   try {
-    await session.send("Emulation.setTimezoneOverride", { timezoneId: opts.timezoneId });
+    try {
+      await session.send("Emulation.setTimezoneOverride", { timezoneId });
+    } catch (err) {
+      const msg = String(err);
+      if (msg.includes("Timezone override is already in effect")) return;
+      if (msg.includes("Invalid timezone")) throw new Error(`Invalid timezone ID: ${timezoneId}`, { cause: err });
+      throw err;
+    }
   } finally {
     await session.detach().catch(() => {
     });
@@ -2180,24 +2579,38 @@ async function pdfViaPlaywright(opts) {
   ensurePageState(page);
   return { buffer: await page.pdf({ printBackground: true }) };
 }
-
-// src/capture/trace.ts
 async function traceStartViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const context = page.context();
+  const ctxState = ensureContextState(context);
+  if (ctxState.traceActive) {
+    throw new Error("Trace already running. Stop the current trace before starting a new one.");
+  }
   await context.tracing.start({
     screenshots: opts.screenshots ?? true,
     snapshots: opts.snapshots ?? true,
-    sources: opts.sources
+    sources: opts.sources ?? false
   });
+  ctxState.traceActive = true;
 }
 async function traceStopViaPlaywright(opts) {
   await assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
   const context = page.context();
-  await context.tracing.stop({ path: opts.path });
+  const ctxState = ensureContextState(context);
+  if (!ctxState.traceActive) {
+    throw new Error("No active trace. Start a trace before stopping it.");
+  }
+  await writeViaSiblingTempPath({
+    rootDir: path.dirname(opts.path),
+    targetPath: opts.path,
+    writeTemp: async (tempPath) => {
+      await context.tracing.stop({ path: tempPath });
+    }
+  });
+  ctxState.traceActive = false;
 }
 
 // src/capture/response.ts
@@ -2280,8 +2693,8 @@ async function cookiesSetViaPlaywright(opts) {
   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 hasDomain = typeof cookie.domain === "string" && cookie.domain.trim();
-  if (!hasUrl && !hasDomain) throw new Error("cookie requires url or domain");
+  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) {
@@ -3360,11 +3773,17 @@ exports.InvalidBrowserNavigationUrlError = InvalidBrowserNavigationUrlError;
 exports.assertBrowserNavigationAllowed = assertBrowserNavigationAllowed;
 exports.assertBrowserNavigationRedirectChainAllowed = assertBrowserNavigationRedirectChainAllowed;
 exports.assertBrowserNavigationResultAllowed = assertBrowserNavigationResultAllowed;
+exports.createPinnedLookup = createPinnedLookup;
+exports.ensureContextState = ensureContextState;
+exports.forceDisconnectPlaywrightForTarget = forceDisconnectPlaywrightForTarget;
 exports.getChromeWebSocketUrl = getChromeWebSocketUrl;
 exports.isChromeCdpReady = isChromeCdpReady;
 exports.isChromeReachable = isChromeReachable;
 exports.normalizeCdpHttpBaseForJsonEndpoints = normalizeCdpHttpBaseForJsonEndpoints;
 exports.requiresInspectableBrowserNavigationRedirects = requiresInspectableBrowserNavigationRedirects;
+exports.resolvePinnedHostnameWithPolicy = resolvePinnedHostnameWithPolicy;
+exports.sanitizeUntrustedFileName = sanitizeUntrustedFileName;
 exports.withBrowserNavigationPolicy = withBrowserNavigationPolicy;
+exports.writeViaSiblingTempPath = writeViaSiblingTempPath;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map