browserclaw 0.5.2 → 0.5.5

package/dist/index.cjs

@@ -829,15 +829,16 @@ async function connectBrowser(cdpUrl, authToken) {
         const headers = {};
         if (authToken) headers["Authorization"] = `Bearer ${authToken}`;
         const browser = await playwrightCore.chromium.connectOverCDP(endpoint, { timeout, headers });
-        const connected = { browser, cdpUrl: normalized, authToken };
-        cached = connected;
-        observeBrowser(browser);
-        browser.on("disconnected", () => {
+        const onDisconnected = () => {
           if (cached?.browser === browser) cached = null;
           for (const key of roleRefsByTarget.keys()) {
             if (key.startsWith(normalized + "::")) roleRefsByTarget.delete(key);
           }
-        });
+        };
+        const connected = { browser, cdpUrl: normalized, authToken, onDisconnected };
+        cached = connected;
+        observeBrowser(browser);
+        browser.on("disconnected", onDisconnected);
         return connected;
       } catch (err) {
         lastErr = err;
@@ -867,6 +868,14 @@ async function disconnectBrowser() {
   if (cur) await cur.browser.close().catch(() => {
   });
 }
+function cdpSocketNeedsAttach(wsUrl) {
+  try {
+    const pathname = new URL(wsUrl).pathname;
+    return pathname === "/cdp" || pathname.endsWith("/cdp") || pathname.includes("/devtools/browser/") || pathname === "/";
+  } catch {
+    return false;
+  }
+}
 async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
   const httpBase = normalizeCdpHttpBaseForJsonEndpoints(cdpUrl);
   const ctrl = new AbortController();
@@ -883,8 +892,10 @@ async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
   }
   if (!Array.isArray(targets)) return;
   const target = targets.find((entry) => String(entry?.id ?? "").trim() === targetId);
-  const wsUrl = String(target?.webSocketDebuggerUrl ?? "").trim();
-  if (!wsUrl) return;
+  const wsUrlRaw = String(target?.webSocketDebuggerUrl ?? "").trim();
+  if (!wsUrlRaw) return;
+  const wsUrl = normalizeCdpWsUrl(wsUrlRaw, httpBase);
+  const needsAttach = cdpSocketNeedsAttach(wsUrl);
   await new Promise((resolve2) => {
     let done = false;
     const finish = () => {
@@ -897,8 +908,9 @@ async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
       }
       resolve2();
     };
-    const timer = setTimeout(finish, 2e3);
+    const timer = setTimeout(finish, 3e3);
     let ws;
+    let nextId = 1;
     try {
       ws = new WebSocket(wsUrl);
     } catch {
@@ -906,11 +918,27 @@ async function tryTerminateExecutionViaCdp(cdpUrl, targetId) {
       return;
     }
     ws.onopen = () => {
+      if (needsAttach) {
+        ws.send(JSON.stringify({ id: nextId++, method: "Target.attachToTarget", params: { targetId, flatten: true } }));
+      } else {
+        ws.send(JSON.stringify({ id: nextId++, method: "Runtime.terminateExecution" }));
+        setTimeout(finish, 300);
+      }
+    };
+    ws.onmessage = (event) => {
+      if (!needsAttach) return;
       try {
-        ws.send(JSON.stringify({ id: 1, method: "Runtime.terminateExecution" }));
+        const msg = JSON.parse(String(event.data));
+        if (msg.id && msg.result?.sessionId) {
+          ws.send(JSON.stringify({ id: nextId++, sessionId: msg.result.sessionId, method: "Runtime.terminateExecution" }));
+          try {
+            ws.send(JSON.stringify({ id: nextId++, method: "Target.detachFromTarget", params: { sessionId: msg.result.sessionId } }));
+          } catch {
+          }
+          setTimeout(finish, 300);
+        }
       } catch {
       }
-      setTimeout(finish, 300);
     };
     ws.onerror = () => finish();
     ws.onclose = () => finish();
@@ -922,6 +950,9 @@ async function forceDisconnectPlaywrightForTarget(opts) {
   if (!cur || cur.cdpUrl !== normalized) return;
   cached = null;
   connectingByUrl.delete(normalized);
+  if (cur.onDisconnected && typeof cur.browser.off === "function") {
+    cur.browser.off("disconnected", cur.onDisconnected);
+  }
   const targetId = opts.targetId?.trim() || "";
   if (targetId) {
     await tryTerminateExecutionViaCdp(normalized, targetId).catch(() => {
@@ -957,33 +988,37 @@ async function findPageByTargetId(browser, targetId, cdpUrl) {
     }
     if (tid && tid === targetId) return page;
   }
-  if (!resolvedViaCdp && pages.length === 1) {
-    return pages[0];
-  }
   if (cdpUrl) {
     try {
       const listUrl = `${normalizeCdpHttpBaseForJsonEndpoints(cdpUrl)}/json/list`;
       const headers = {};
       if (cached?.authToken) headers["Authorization"] = `Bearer ${cached.authToken}`;
-      const response = await fetch(listUrl, { headers });
-      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];
-          if (urlMatch.length > 1) {
-            const sameUrlTargets = targets.filter((t) => t.url === target.url);
-            if (sameUrlTargets.length === urlMatch.length) {
-              const idx = sameUrlTargets.findIndex((t) => t.id === targetId);
-              if (idx >= 0 && idx < urlMatch.length) return urlMatch[idx];
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), 2e3);
+      try {
+        const response = await fetch(listUrl, { headers, signal: ctrl.signal });
+        if (response.ok) {
+          const targets = await response.json();
+          const target = targets.find((entry) => entry.id === targetId);
+          if (target) {
+            const urlMatch = pages.filter((p) => p.url() === target.url);
+            if (urlMatch.length === 1) return urlMatch[0];
+            if (urlMatch.length > 1) {
+              const sameUrlTargets = targets.filter((entry) => entry.url === target.url);
+              if (sameUrlTargets.length === urlMatch.length) {
+                const idx = sameUrlTargets.findIndex((entry) => entry.id === targetId);
+                if (idx >= 0 && idx < urlMatch.length) return urlMatch[idx];
+              }
             }
           }
         }
+      } finally {
+        clearTimeout(t);
       }
     } catch {
     }
   }
+  if (!resolvedViaCdp && pages.length === 1) return pages[0];
   return null;
 }
 async function getPageForTargetId(opts) {
@@ -1508,20 +1543,6 @@ 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",
@@ -1540,6 +1561,97 @@ var BLOCKED_IPV6_RANGES = /* @__PURE__ */ new Set([
   "multicast"
 ]);
 var RFC2544_BENCHMARK_PREFIX = [ipaddr__namespace.IPv4.parse("198.18.0.0"), 15];
+var EMBEDDED_IPV4_SENTINEL_RULES = [
+  // IPv4-compatible (::a.b.c.d)
+  {
+    matches: (parts) => parts[0] === 0 && parts[1] === 0 && parts[2] === 0 && parts[3] === 0 && parts[4] === 0 && parts[5] === 0,
+    toHextets: (parts) => [parts[6], parts[7]]
+  },
+  // NAT64 local-use (64:ff9b:1::/48)
+  {
+    matches: (parts) => parts[0] === 100 && parts[1] === 65435 && parts[2] === 1 && parts[3] === 0 && parts[4] === 0 && parts[5] === 0,
+    toHextets: (parts) => [parts[6], parts[7]]
+  },
+  // 6to4 (2002::/16)
+  {
+    matches: (parts) => parts[0] === 8194,
+    toHextets: (parts) => [parts[1], parts[2]]
+  },
+  // Teredo (2001:0000::/32) — IPv4 XOR'd
+  {
+    matches: (parts) => parts[0] === 8193 && parts[1] === 0,
+    toHextets: (parts) => [parts[6] ^ 65535, parts[7] ^ 65535]
+  },
+  // ISATAP — sentinel in parts[4-5]: 0x0000:0x5efe or 0x0200:0x5efe
+  {
+    matches: (parts) => (parts[4] & 64767) === 0 && parts[5] === 24318,
+    toHextets: (parts) => [parts[6], parts[7]]
+  }
+];
+function stripIpv6Brackets(value) {
+  if (value.startsWith("[") && value.endsWith("]")) return value.slice(1, -1);
+  return value;
+}
+function isNumericIpv4LiteralPart(value) {
+  return /^[0-9]+$/.test(value) || /^0x[0-9a-f]+$/i.test(value);
+}
+function parseIpv6WithEmbeddedIpv4(raw) {
+  if (!raw.includes(":") || !raw.includes(".")) return;
+  const match = /^(.*:)([^:%]+(?:\.[^:%]+){3})(%[0-9A-Za-z]+)?$/i.exec(raw);
+  if (!match) return;
+  const [, prefix, embeddedIpv4, zoneSuffix = ""] = match;
+  if (!ipaddr__namespace.IPv4.isValidFourPartDecimal(embeddedIpv4)) return;
+  const octets = embeddedIpv4.split(".").map((part) => Number.parseInt(part, 10));
+  const normalizedIpv6 = `${prefix}${(octets[0] << 8 | octets[1]).toString(16)}:${(octets[2] << 8 | octets[3]).toString(16)}${zoneSuffix}`;
+  if (!ipaddr__namespace.IPv6.isValid(normalizedIpv6)) return;
+  return ipaddr__namespace.IPv6.parse(normalizedIpv6);
+}
+function normalizeIpParseInput(raw) {
+  const trimmed = raw?.trim();
+  if (!trimmed) return;
+  return stripIpv6Brackets(trimmed);
+}
+function parseCanonicalIpAddress(raw) {
+  const normalized = normalizeIpParseInput(raw);
+  if (!normalized) return;
+  if (ipaddr__namespace.IPv4.isValid(normalized)) {
+    if (!ipaddr__namespace.IPv4.isValidFourPartDecimal(normalized)) return;
+    return ipaddr__namespace.IPv4.parse(normalized);
+  }
+  if (ipaddr__namespace.IPv6.isValid(normalized)) return ipaddr__namespace.IPv6.parse(normalized);
+  return parseIpv6WithEmbeddedIpv4(normalized);
+}
+function parseLooseIpAddress(raw) {
+  const normalized = normalizeIpParseInput(raw);
+  if (!normalized) return;
+  if (ipaddr__namespace.isValid(normalized)) return ipaddr__namespace.parse(normalized);
+  return parseIpv6WithEmbeddedIpv4(normalized);
+}
+function isCanonicalDottedDecimalIPv4(raw) {
+  const trimmed = raw?.trim();
+  if (!trimmed) return false;
+  const normalized = stripIpv6Brackets(trimmed);
+  if (!normalized) return false;
+  return ipaddr__namespace.IPv4.isValidFourPartDecimal(normalized);
+}
+function isLegacyIpv4Literal(raw) {
+  const trimmed = raw?.trim();
+  if (!trimmed) return false;
+  const normalized = stripIpv6Brackets(trimmed);
+  if (!normalized || normalized.includes(":")) return false;
+  if (isCanonicalDottedDecimalIPv4(normalized)) return false;
+  const parts = normalized.split(".");
+  if (parts.length === 0 || parts.length > 4) return false;
+  if (parts.some((part) => part.length === 0)) return false;
+  if (!parts.every((part) => isNumericIpv4LiteralPart(part))) return false;
+  return true;
+}
+function looksLikeUnsupportedIpv4Literal(address) {
+  const parts = address.split(".");
+  if (parts.length === 0 || parts.length > 4) return false;
+  if (parts.some((part) => part.length === 0)) return true;
+  return parts.every((part) => /^[0-9]+$/.test(part) || /^0x/i.test(part));
+}
 function isBlockedSpecialUseIpv4Address(address, opts) {
   const inRfc2544 = address.match(RFC2544_BENCHMARK_PREFIX);
   if (inRfc2544 && opts?.allowRfc2544BenchmarkRange === true) return false;
@@ -1549,89 +1661,50 @@ 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] === 65535 && 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] === 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;
-    }
+function decodeIpv4FromHextets(high, low) {
+  const octets = [
+    high >>> 8 & 255,
+    high & 255,
+    low >>> 8 & 255,
+    low & 255
+  ];
+  return ipaddr__namespace.IPv4.parse(octets.join("."));
+}
+function extractEmbeddedIpv4FromIpv6(address) {
+  if (address.isIPv4MappedAddress()) return address.toIPv4Address();
+  if (address.range() === "rfc6145") return decodeIpv4FromHextets(address.parts[6], address.parts[7]);
+  if (address.range() === "rfc6052") return decodeIpv4FromHextets(address.parts[6], address.parts[7]);
+  for (const rule of EMBEDDED_IPV4_SENTINEL_RULES) {
+    if (!rule.matches(address.parts)) continue;
+    const [high, low] = rule.toHextets(address.parts);
+    return decodeIpv4FromHextets(high, low);
   }
-  return null;
 }
-function isPrivateIpAddress(address, opts) {
+function resolveIpv4SpecialUseBlockOptions(policy) {
+  return { allowRfc2544BenchmarkRange: policy?.allowRfc2544BenchmarkRange === true };
+}
+function isBlockedHostnameOrIp(hostname, policy) {
+  const normalized = normalizeHostname(hostname);
+  if (!normalized) return false;
+  return isBlockedHostnameNormalized(normalized) || isPrivateIpAddress(normalized, policy);
+}
+function isPrivateIpAddress(address, policy) {
   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;
+  const blockOptions = resolveIpv4SpecialUseBlockOptions(policy);
+  const strictIp = parseCanonicalIpAddress(normalized);
+  if (strictIp) {
+    if (strictIp.kind() === "ipv4") return isBlockedSpecialUseIpv4Address(strictIp, blockOptions);
+    const v6 = strictIp;
     if (isBlockedSpecialUseIpv6Address(v6)) return true;
-    const embeddedV4 = extractEmbeddedIpv4FromIpv6(v6, opts);
-    if (embeddedV4 !== null) return embeddedV4;
+    const embeddedIpv4 = extractEmbeddedIpv4FromIpv6(v6);
+    if (embeddedIpv4) return isBlockedSpecialUseIpv4Address(embeddedIpv4, blockOptions);
     return false;
-  } catch {
   }
-  if (!normalized.includes(":") && isUnsupportedIPv4Literal(normalized)) return true;
-  if (normalized.includes(":")) return true;
+  if (normalized.includes(":") && !parseLooseIpAddress(normalized)) return true;
+  if (!isCanonicalDottedDecimalIPv4(normalized) && isLegacyIpv4Literal(normalized)) return true;
+  if (looksLikeUnsupportedIpv4Literal(normalized)) return true;
   return false;
 }
 function normalizeHostnameSet(values) {
@@ -1713,13 +1786,7 @@ async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
     );
   }
   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)) {
+    if (isBlockedHostnameOrIp(normalized, params.policy)) {
       throw new InvalidBrowserNavigationUrlError(
         `Navigation to internal/loopback address blocked: "${hostname}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
       );
@@ -1740,9 +1807,8 @@ async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
     );
   }
   if (!skipPrivateNetworkChecks) {
-    const ipOpts = { allowRfc2544BenchmarkRange: params.policy?.allowRfc2544BenchmarkRange };
     for (const r of results) {
-      if (isPrivateIpAddress(r.address, ipOpts)) {
+      if (isBlockedHostnameOrIp(r.address, params.policy)) {
         throw new InvalidBrowserNavigationUrlError(
           `Navigation to internal/loopback address blocked: "${hostname}" resolves to "${r.address}". ssrfPolicy.dangerouslyAllowPrivateNetwork is false (strict mode).`
         );
@@ -1763,6 +1829,7 @@ async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
 }
 async function assertBrowserNavigationAllowed(opts) {
   const rawUrl = String(opts.url ?? "").trim();
+  if (!rawUrl) throw new InvalidBrowserNavigationUrlError("url is required");
   let parsed;
   try {
     parsed = new URL(rawUrl);
@@ -1919,12 +1986,30 @@ function resolveBoundedDelayMs(value, label, maxMs) {
   if (normalized > maxMs) throw new Error(`${label} exceeds maximum of ${maxMs}ms`);
   return normalized;
 }
-async function clickViaPlaywright(opts) {
+function resolveInteractionTimeoutMs(timeoutMs) {
+  return Math.max(500, Math.min(6e4, Math.floor(timeoutMs ?? 8e3)));
+}
+function requireRefOrSelector(ref, selector) {
+  const trimmedRef = typeof ref === "string" ? ref.trim() : "";
+  const trimmedSelector = typeof selector === "string" ? selector.trim() : "";
+  if (!trimmedRef && !trimmedSelector) throw new Error("ref or selector is required");
+  return { ref: trimmedRef || void 0, selector: trimmedSelector || void 0 };
+}
+function resolveLocator(page, resolved) {
+  return resolved.ref ? refLocator(page, resolved.ref) : page.locator(resolved.selector);
+}
+async function getRestoredPageForTarget(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 = normalizeTimeoutMs(opts.timeoutMs, 8e3, 6e4);
+  return page;
+}
+async function clickViaPlaywright(opts) {
+  const resolved = requireRefOrSelector(opts.ref, opts.selector);
+  const page = await getRestoredPageForTarget(opts);
+  const label = resolved.ref ?? resolved.selector;
+  const locator = resolveLocator(page, resolved);
+  const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
   try {
     const delayMs = resolveBoundedDelayMs(opts.delayMs, "click delayMs", MAX_CLICK_DELAY_MS);
     if (delayMs > 0) {
@@ -1937,28 +2022,27 @@ async function clickViaPlaywright(opts) {
       await locator.click({ timeout, button: opts.button, modifiers: opts.modifiers });
     }
   } catch (err) {
-    throw toAIFriendlyError(err, opts.ref);
+    throw toAIFriendlyError(err, label);
   }
 }
 async function hoverViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const resolved = requireRefOrSelector(opts.ref, opts.selector);
+  const page = await getRestoredPageForTarget(opts);
+  const label = resolved.ref ?? resolved.selector;
+  const locator = resolveLocator(page, resolved);
   try {
-    await refLocator(page, opts.ref).hover({
-      timeout: normalizeTimeoutMs(opts.timeoutMs, 8e3, 6e4)
-    });
+    await locator.hover({ timeout: resolveInteractionTimeoutMs(opts.timeoutMs) });
   } catch (err) {
-    throw toAIFriendlyError(err, opts.ref);
+    throw toAIFriendlyError(err, label);
   }
 }
 async function typeViaPlaywright(opts) {
+  const resolved = requireRefOrSelector(opts.ref, opts.selector);
   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 = normalizeTimeoutMs(opts.timeoutMs, 8e3, 6e4);
+  const page = await getRestoredPageForTarget(opts);
+  const label = resolved.ref ?? resolved.selector;
+  const locator = resolveLocator(page, resolved);
+  const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
   try {
     if (opts.slowly) {
       await locator.click({ timeout });
@@ -1968,39 +2052,38 @@ async function typeViaPlaywright(opts) {
     }
     if (opts.submit) await locator.press("Enter", { timeout });
   } catch (err) {
-    throw toAIFriendlyError(err, opts.ref);
+    throw toAIFriendlyError(err, label);
   }
 }
 async function selectOptionViaPlaywright(opts) {
+  const resolved = requireRefOrSelector(opts.ref, opts.selector);
   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 });
+  const page = await getRestoredPageForTarget(opts);
+  const label = resolved.ref ?? resolved.selector;
+  const locator = resolveLocator(page, resolved);
   try {
-    await refLocator(page, opts.ref).selectOption(opts.values, {
-      timeout: normalizeTimeoutMs(opts.timeoutMs, 8e3, 6e4)
-    });
+    await locator.selectOption(opts.values, { timeout: resolveInteractionTimeoutMs(opts.timeoutMs) });
   } catch (err) {
-    throw toAIFriendlyError(err, opts.ref);
+    throw toAIFriendlyError(err, label);
   }
 }
 async function dragViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const resolvedStart = requireRefOrSelector(opts.startRef, opts.startSelector);
+  const resolvedEnd = requireRefOrSelector(opts.endRef, opts.endSelector);
+  const page = await getRestoredPageForTarget(opts);
+  const startLocator = resolveLocator(page, resolvedStart);
+  const endLocator = resolveLocator(page, resolvedEnd);
+  const startLabel = resolvedStart.ref ?? resolvedStart.selector;
+  const endLabel = resolvedEnd.ref ?? resolvedEnd.selector;
   try {
-    await refLocator(page, opts.startRef).dragTo(refLocator(page, opts.endRef), {
-      timeout: normalizeTimeoutMs(opts.timeoutMs, 8e3, 6e4)
-    });
+    await startLocator.dragTo(endLocator, { timeout: resolveInteractionTimeoutMs(opts.timeoutMs) });
   } catch (err) {
-    throw toAIFriendlyError(err, `${opts.startRef} -> ${opts.endRef}`);
+    throw toAIFriendlyError(err, `${startLabel} -> ${endLabel}`);
   }
 }
 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 = normalizeTimeoutMs(opts.timeoutMs, 8e3, 6e4);
+  const page = await getRestoredPageForTarget(opts);
+  const timeout = resolveInteractionTimeoutMs(opts.timeoutMs);
   for (const field of opts.fields) {
     const ref = field.ref.trim();
     const type = (typeof field.type === "string" ? field.type.trim() : "") || "text";
@@ -2025,21 +2108,18 @@ async function fillFormViaPlaywright(opts) {
   }
 }
 async function scrollIntoViewViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const resolved = requireRefOrSelector(opts.ref, opts.selector);
+  const page = await getRestoredPageForTarget(opts);
+  const label = resolved.ref ?? resolved.selector;
+  const locator = resolveLocator(page, resolved);
   try {
-    await refLocator(page, opts.ref).scrollIntoViewIfNeeded({
-      timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4)
-    });
+    await locator.scrollIntoViewIfNeeded({ timeout: normalizeTimeoutMs(opts.timeoutMs, 2e4) });
   } catch (err) {
-    throw toAIFriendlyError(err, opts.ref);
+    throw toAIFriendlyError(err, label);
   }
 }
 async function highlightViaPlaywright(opts) {
-  const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
-  restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
+  const page = await getRestoredPageForTarget(opts);
   try {
     await refLocator(page, opts.ref).highlight();
   } catch (err) {
@@ -2047,9 +2127,7 @@ async function highlightViaPlaywright(opts) {
   }
 }
 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 page = await getRestoredPageForTarget(opts);
   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() : "";
@@ -2242,13 +2320,18 @@ async function resizeViewportViaPlaywright(opts) {
 
 // src/actions/wait.ts
 var MAX_WAIT_TIME_MS = 3e4;
+function resolveBoundedDelayMs2(value, label, maxMs) {
+  const normalized = Math.floor(value ?? 0);
+  if (!Number.isFinite(normalized) || normalized < 0) throw new Error(`${label} must be >= 0`);
+  if (normalized > maxMs) throw new Error(`${label} exceeds maximum of ${maxMs}ms`);
+  return normalized;
+}
 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)) {
-    const bounded = Math.max(0, Math.min(MAX_WAIT_TIME_MS, Math.floor(opts.timeMs)));
-    await page.waitForTimeout(bounded);
+    await page.waitForTimeout(resolveBoundedDelayMs2(opts.timeMs, "wait timeMs", MAX_WAIT_TIME_MS));
   }
   if (opts.text) {
     await page.getByText(opts.text).first().waitFor({ state: "visible", timeout });
@@ -2410,55 +2493,106 @@ async function evaluateViaPlaywright(opts) {
     if (signal && abortListener) signal.removeEventListener("abort", abortListener);
   }
 }
+function createPageDownloadWaiter(page, timeoutMs) {
+  let done = false;
+  let timer;
+  let handler;
+  const cleanup = () => {
+    if (timer) clearTimeout(timer);
+    timer = void 0;
+    if (handler) {
+      page.off("download", handler);
+      handler = void 0;
+    }
+  };
+  return {
+    promise: new Promise((resolve2, reject) => {
+      handler = (download) => {
+        if (done) return;
+        done = true;
+        cleanup();
+        resolve2(download);
+      };
+      page.on("download", handler);
+      timer = setTimeout(() => {
+        if (done) return;
+        done = true;
+        cleanup();
+        reject(new Error("Timeout waiting for download"));
+      }, timeoutMs);
+    }),
+    cancel: () => {
+      if (done) return;
+      done = true;
+      cleanup();
+    }
+  };
+}
+async function saveDownloadPayload(download, outPath) {
+  await writeViaSiblingTempPath({
+    rootDir: path.dirname(outPath),
+    targetPath: outPath,
+    writeTemp: async (tempPath) => {
+      await download.saveAs(tempPath);
+    }
+  });
+  return {
+    url: download.url(),
+    suggestedFilename: download.suggestedFilename(),
+    path: outPath
+  };
+}
+async function awaitDownloadPayload(params) {
+  try {
+    const download = await params.waiter.promise;
+    if (params.state.armIdDownload !== params.armId) throw new Error("Download was superseded by another waiter");
+    return await saveDownloadPayload(download, params.outPath);
+  } catch (err) {
+    params.waiter.cancel();
+    throw err;
+  }
+}
 async function downloadViaPlaywright(opts) {
   await assertSafeOutputPath(opts.path, opts.allowedOutputRoots);
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   const state = ensurePageState(page);
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
   const timeout = normalizeTimeoutMs(opts.timeoutMs, 12e4);
-  const locator = refLocator(page, opts.ref);
+  const outPath = String(opts.path ?? "").trim();
+  if (!outPath) throw new Error("path is required");
   state.armIdDownload = bumpDownloadArmId();
+  const armId = state.armIdDownload;
+  const waiter = createPageDownloadWaiter(page, timeout);
   try {
-    const [download] = await Promise.all([
-      page.waitForEvent("download", { timeout }),
-      locator.click({ timeout })
-    ]);
-    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: outPath
-    };
+    const locator = refLocator(page, opts.ref);
+    try {
+      await locator.click({ timeout });
+    } catch (err) {
+      throw toAIFriendlyError(err, opts.ref);
+    }
+    return await awaitDownloadPayload({ waiter, state, armId, outPath });
   } catch (err) {
-    throw toAIFriendlyError(err, opts.ref);
+    waiter.cancel();
+    throw err;
   }
 }
 async function waitForDownloadViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
-  ensurePageState(page);
+  const state = ensurePageState(page);
   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 writeViaSiblingTempPath({
-    rootDir: path.dirname(savePath),
-    targetPath: savePath,
-    writeTemp: async (tempPath) => {
-      await download.saveAs(tempPath);
-    }
-  });
-  return {
-    url: download.url(),
-    suggestedFilename: download.suggestedFilename(),
-    path: savePath
-  };
+  state.armIdDownload = bumpDownloadArmId();
+  const armId = state.armIdDownload;
+  const waiter = createPageDownloadWaiter(page, timeout);
+  try {
+    const download = await waiter.promise;
+    if (state.armIdDownload !== armId) throw new Error("Download was superseded by another waiter");
+    const savePath = opts.path ?? download.suggestedFilename();
+    await assertSafeOutputPath(savePath, opts.allowedOutputRoots);
+    return await saveDownloadPayload(download, savePath);
+  } catch (err) {
+    waiter.cancel();
+    throw err;
+  }
 }
 async function emulateMediaViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
@@ -2573,7 +2707,7 @@ async function setLocaleViaPlaywright(opts) {
 async function setOfflineViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });
   ensurePageState(page);
-  await page.context().setOffline(opts.offline);
+  await page.context().setOffline(Boolean(opts.offline));
 }
 async function setTimezoneViaPlaywright(opts) {
   const page = await getPageForTargetId({ cdpUrl: opts.cdpUrl, targetId: opts.targetId });