release: v0.3.29 — extension loading, composable JS helpers, cloakserve origin guard

Expose userDataDir support via launchPersistentContext() for
cloakbrowser/puppeteer, matching the existing Playwright API.
Includes proxy auth, geoip, and humanize support.

.github/workflows/attest-release.yml

@@ -16,9 +16,10 @@ jobs:
       contents: write      # Download release assets
     steps:
       - name: Download release binaries
-        run: gh release download ${{ github.event.inputs.tag }} --repo CloakHQ/cloakbrowser --pattern "cloakbrowser-*.tar.gz" --pattern "cloakbrowser-*.zip"
+        run: gh release download "$RELEASE_TAG" --repo CloakHQ/cloakbrowser --pattern "cloakbrowser-*.tar.gz" --pattern "cloakbrowser-*.zip"
         env:
           GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.inputs.tag }}
 
       - name: Attest build provenance
         uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32  # v4.1.0

.gitignore

@@ -46,6 +46,7 @@ js/dist/
 *.whl
 AGENTS.md
 .beads
+result
 
 # Private docs (launch posts, strategy)
 docs/

CHANGELOG.md

@@ -8,6 +8,19 @@ Changes are tagged: **[wrapper]** for Python/JS wrapper, **[binary]** for Chromi
 
 ## [Unreleased]
 
+## [0.3.29] — 2026-05-20
+
+- **[wrapper]** **Security**: `cloakserve` — guard WebSocket origins to prevent browser-origin CSRF via CDP proxy (thanks [@0xlally](https://github.com/0xlally) for the report, [@honor2030](https://github.com/honor2030) for the fix, #239, #240)
+- **[wrapper]** **Security**: Lambda example — add URL scheme validation, SSRF protection, post-navigation re-validation, remove unsafe caller-controlled options (#233)
+- **[wrapper]** **Security**: CI — isolate `workflow_dispatch` input to avoid shell injection in attest-release (thanks [@aaronjmars](https://github.com/aaronjmars), #223)
+- **[wrapper]** **Security**: JS — bump tar + transitive deps via npm audit fix (thanks [@aaronjmars](https://github.com/aaronjmars), #222)
+- **[wrapper]** Add `extension_paths` parameter for loading Chrome extensions in all launch functions (thanks [@zackycodes](https://github.com/zackycodes), #210)
+- **[wrapper]** Humanize: add Playwright-style actionability checks — auto-wait for visible, enabled, stable elements before humanized actions (#228)
+- **[wrapper]** JS: export composable launch helpers — `buildLaunchOptions()` and `humanizeBrowser()` for custom Playwright integrations (thanks [@honor2030](https://github.com/honor2030), #244)
+- **[wrapper]** JS: add `launchPersistentContext()` to Puppeteer wrapper (#261)
+- **[wrapper]** Add `flake.nix` for Nix/NixOS (thanks [@Seryiza](https://github.com/Seryiza), #220)
+- **[meta]** JS: sync package-lock metadata (thanks [@245678000000](https://github.com/245678000000), #219)
+
 ## [0.3.28] — 2026-05-11
 
 - **[wrapper]** **Security**: `cloakserve` — sanitize fingerprint seed to prevent path traversal, bind to `127.0.0.1` on bare metal, detect Podman containers (#217)

README.md

@@ -128,7 +128,7 @@ Open [http://localhost:8080](http://localhost:8080). Create a profile. Click **L
 
 ---
 
-## Latest: v0.3.26 (Chromium 146.0.7680.177.4)
+## Latest: v0.3.29 (Chromium 146.0.7680.177.4)
 
 - **`launch_context_async()`** — async counterpart to `launch_context()`. Forwards kwargs to `browser.new_context()` for `storage_state`, `permissions`, `extra_http_headers` without a persistent profile folder.
 - **JS `contextOptions` escape hatch** — forward arbitrary options (including `storageState`) to Playwright's `newContext()` from `launchContext()` / `launchPersistentContext()`.
@@ -371,9 +371,16 @@ ctx.close()  # profile saved
 
 # Next run — cookies, localStorage restored automatically
 ctx = launch_persistent_context("./my-profile", headless=False)
+
+# Load Chrome extensions
+ctx = launch_persistent_context(
+    "./my-profile",
+    headless=False,
+    extension_paths=["./my-extension"],
+)
 ```
 
-Supports all the same options as `launch_context()`: `proxy`, `user_agent`, `viewport`, `locale`, `timezone`, `color_scheme`, `geoip`.
+Supports all the same options as `launch_context()`: `proxy`, `user_agent`, `viewport`, `locale`, `timezone`, `color_scheme`, `geoip`, `extension_paths`.
 
 Async version: `launch_persistent_context_async()`.
 
@@ -1196,4 +1203,11 @@ Issues and PRs welcome. If something isn't working, [open an issue](https://gith
 - [@eofreternal](https://github.com/eofreternal) — humanConfig type fix, humanized method option types
 - [@manaskarra](https://github.com/manaskarra) — iframe scope fix for humanized frame actions, GeoIP timeout guard
 - [@Youhai020616](https://github.com/Youhai020616) — SOCKS5 credential encoding logging
-- [@AlexTech314](https://github.com/AlexTech314) — AWS Lambda integration
+- [@AlexTech314](https://github.com/AlexTech314) — AWS Lambda integration, cold-start hardening
+- [@dgtlmoon](https://github.com/dgtlmoon) — graceful pw.stop() cleanup
+- [@zackycodes](https://github.com/zackycodes) — Chrome extension loading
+- [@aaronjmars](https://github.com/aaronjmars) — security fixes (shell injection, dep bumps)
+- [@Seryiza](https://github.com/Seryiza) — Nix/NixOS flake
+- [@245678000000](https://github.com/245678000000) — package-lock sync
+- [@honor2030](https://github.com/honor2030) — cloakserve WebSocket origin guard, composable JS launch helpers
+- [@0xlally](https://github.com/0xlally) — security reports (cloakserve path traversal, WebSocket origin bypass)

bin/cloakserve

@@ -18,6 +18,7 @@ Client:
 from __future__ import annotations
 
 import asyncio
+import ipaddress
 import json
 import logging
 import os
@@ -29,7 +30,7 @@ import subprocess
 import sys
 import time
 from dataclasses import dataclass
-from urllib.parse import parse_qs
+from urllib.parse import parse_qs, urlparse
 
 from pathlib import Path
 
@@ -64,6 +65,91 @@ BASE_CDP_PORT = 5100
 
 SAFE_SEED_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
 RESERVED_SEEDS = {"__default__"}
+TRUSTED_WS_ORIGINS = {"devtools://devtools", "chrome-devtools://devtools"}
+
+
+def _host_port_from_netloc(netloc: str, default_port: int) -> tuple[str, int] | None:
+    """Return a normalized (host, port) pair for an Origin/Host netloc."""
+    if "," in netloc:
+        return None
+    try:
+        parsed = urlparse(f"//{netloc.strip()}")
+        authority = parsed.netloc.rsplit("@", 1)[-1]
+        if (
+            not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or authority.endswith(":")
+            or parsed.path
+            or parsed.params
+            or parsed.query
+            or parsed.fragment
+        ):
+            return None
+        return (parsed.hostname.lower(), parsed.port if parsed.port is not None else default_port)
+    except ValueError:
+        return None
+
+
+def _is_loopback_host(hostname: str) -> bool:
+    """Return True for localhost and loopback IP literals."""
+    hostname = hostname.strip("[]").rstrip(".").lower()
+    if hostname == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(hostname).is_loopback
+    except ValueError:
+        return False
+
+
+def _origin_is_allowed(
+    origin: str | None,
+    host: str | None,
+    request_scheme: str = "http",
+) -> bool:
+    """Return True when a WebSocket Origin is safe to proxy to local CDP."""
+    if origin is None:
+        # Playwright/Puppeteer and other non-browser CDP clients commonly omit
+        # Origin. Keep those clients working while rejecting browser-origin CSRF.
+        return True
+
+    origin = origin.strip()
+    if not origin or origin.lower() == "null":
+        return False
+    if origin in TRUSTED_WS_ORIGINS:
+        return True
+
+    try:
+        parsed = urlparse(origin)
+    except ValueError:
+        return False
+
+    if parsed.scheme not in ("http", "https"):
+        return False
+    if parsed.path or parsed.params or parsed.query or parsed.fragment:
+        return False
+
+    origin_default_port = 443 if parsed.scheme == "https" else 80
+    request_scheme = request_scheme.split(",", 1)[0].strip().lower()
+    request_default_port = 443 if request_scheme in ("https", "wss") else 80
+    origin_host = _host_port_from_netloc(parsed.netloc, origin_default_port)
+    request_host = _host_port_from_netloc(host or "", request_default_port)
+    if origin_host is None or request_host is None:
+        return False
+    if not _is_loopback_host(request_host[0]):
+        return False
+    return origin_host == request_host
+
+
+def _reject_untrusted_origin(request: web.Request) -> web.Response | None:
+    """Reject browser-origin WebSocket upgrades that would expose local CDP."""
+    origin = request.headers.get("Origin")
+    host = request.headers.get("Host")
+    scheme = request.headers.get("X-Forwarded-Proto", getattr(request, "scheme", "http"))
+    if _origin_is_allowed(origin, host, request_scheme=scheme):
+        return None
+    logger.warning("Rejected CDP WebSocket from untrusted Origin %r for Host %r", origin, host)
+    return web.Response(status=403, text="Forbidden: untrusted WebSocket origin\n")
 
 
 # ---------------------------------------------------------------------------
@@ -527,8 +613,12 @@ async def proxy_cdp_websocket(
         logger.error("%s error: %s", label, exc)
 
 
-async def handle_ws_default(request: web.Request) -> web.WebSocketResponse:
+async def handle_ws_default(request: web.Request) -> web.StreamResponse:
     """WebSocket proxy for default (no-seed) Chrome: /devtools/{type}/{guid}"""
+    rejected = _reject_untrusted_origin(request)
+    if rejected is not None:
+        return rejected
+
     pool: ChromePool = request.app["pool"]
     path = request.match_info.get("path", "")
 
@@ -546,8 +636,12 @@ async def handle_ws_default(request: web.Request) -> web.WebSocketResponse:
     return ws
 
 
-async def handle_ws_seed(request: web.Request) -> web.WebSocketResponse:
+async def handle_ws_seed(request: web.Request) -> web.StreamResponse:
     """WebSocket proxy for seed-specific Chrome: /fingerprint/{seed}/devtools/{type}/{guid}"""
+    rejected = _reject_untrusted_origin(request)
+    if rejected is not None:
+        return rejected
+
     pool: ChromePool = request.app["pool"]
     seed = request.match_info["seed"]
     path = request.match_info.get("path", "")

cloakbrowser/_version.py

@@ -1 +1 @@
-__version__ = "0.3.28"
+__version__ = "0.3.29"

cloakbrowser/browser.py

@@ -64,6 +64,7 @@ def launch(
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    extension_paths: list[str] | None = None,
     **kwargs: Any,
 ) -> Any:
     """Launch stealth Chromium browser. Returns a Playwright Browser object.
@@ -75,6 +76,7 @@ def launch(
             Dict: {"server": "http://proxy:8080", "bypass": ".google.com", ...}
             — passed directly to Playwright.
         args: Additional Chromium CLI arguments to pass.
+        extension_paths: List of Chrome extension paths to load.
         stealth_args: Include default stealth fingerprint args (default True).
             Set to False if you want to pass your own --fingerprint flags.
         timezone: IANA timezone (e.g. 'America/New_York'). Sets --fingerprint-timezone binary flag.
@@ -112,7 +114,8 @@ def launch(
     if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
         args = list(args or [])
         args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless)
+        
+    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless, extension_paths=extension_paths)
 
     logger.debug("Launching stealth Chromium (headless=%s, args=%d)", headless, len(chrome_args))
 
@@ -159,6 +162,7 @@ async def launch_async(  # noqa: C901
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    extension_paths: list[str] | None = None,
     **kwargs: Any,
 ) -> Any:
     """Async version of launch(). Returns a Playwright Browser object.
@@ -167,6 +171,7 @@ async def launch_async(  # noqa: C901
         headless: Run in headless mode (default True).
         proxy: Proxy URL string or Playwright proxy dict (see launch() for details).
         args: Additional Chromium CLI arguments to pass.
+        extension_paths: List of Chrome extension paths to load.
         stealth_args: Include default stealth fingerprint args (default True).
         timezone: IANA timezone (e.g. 'America/New_York'). Sets --fingerprint-timezone binary flag.
         locale: BCP 47 locale (e.g. 'en-US'). Sets --lang binary flag.
@@ -202,7 +207,7 @@ async def launch_async(  # noqa: C901
     if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
         args = list(args or [])
         args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless)
+    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless, extension_paths=extension_paths)
 
     logger.debug("Launching stealth Chromium async (headless=%s, args=%d)", headless, len(chrome_args))
 
@@ -253,6 +258,7 @@ def launch_persistent_context(
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    extension_paths: list[str] | None = None,
     **kwargs: Any,
 ) -> Any:
     """Launch stealth browser with a persistent profile and return a BrowserContext.
@@ -268,6 +274,7 @@ def launch_persistent_context(
         headless: Run in headless mode (default True).
         proxy: Proxy URL string or Playwright proxy dict (see launch() for details).
         args: Additional Chromium CLI arguments.
+        extension_paths: List of Chrome extension paths to load.
         stealth_args: Include default stealth fingerprint args (default True).
         user_agent: Custom user agent string.
         viewport: Viewport size dict, e.g. {"width": 1920, "height": 1080}.
@@ -306,7 +313,7 @@ def launch_persistent_context(
     if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
         args = list(args or [])
         args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless)
+    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless, extension_paths=extension_paths)
 
     logger.debug(
         "Launching persistent stealth Chromium (headless=%s, user_data_dir=%s)",
@@ -377,6 +384,7 @@ async def launch_persistent_context_async(
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    extension_paths: list[str] | None = None,
     **kwargs: Any,
 ) -> Any:
     """Async version of launch_persistent_context().
@@ -391,6 +399,7 @@ async def launch_persistent_context_async(
         headless: Run in headless mode (default True).
         proxy: Proxy URL string or Playwright proxy dict (see launch() for details).
         args: Additional Chromium CLI arguments.
+        extension_paths: List of Chrome extension paths to load.
         stealth_args: Include default stealth fingerprint args (default True).
         user_agent: Custom user agent string.
         viewport: Viewport size dict, e.g. {"width": 1920, "height": 1080}.
@@ -432,7 +441,7 @@ async def launch_persistent_context_async(
     if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
         args = list(args or [])
         args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless)
+    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless, extension_paths=extension_paths)
 
     logger.debug(
         "Launching persistent stealth Chromium async (headless=%s, user_data_dir=%s)",
@@ -502,6 +511,7 @@ def launch_context(
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    extension_paths: list[str] | None = None,
     **kwargs: Any,
 ) -> Any:
     """Launch stealth browser and return a BrowserContext with common options pre-set.
@@ -513,6 +523,7 @@ def launch_context(
         headless: Run in headless mode (default True).
         proxy: Proxy URL string or Playwright proxy dict (see launch() for details).
         args: Additional Chromium CLI arguments.
+        extension_paths: List of Chrome extension paths to load.
         stealth_args: Include default stealth fingerprint args (default True).
         user_agent: Custom user agent string.
         viewport: Viewport size dict, e.g. {"width": 1920, "height": 1080}.
@@ -544,7 +555,7 @@ def launch_context(
     # so it applies to ALL contexts, not just the default one.
     # locale and timezone are set via binary flags only — no CDP emulation.
     browser = launch(headless=headless, proxy=proxy, args=args, stealth_args=stealth_args,
-                     timezone=timezone, locale=locale, backend=backend)
+                     timezone=timezone, locale=locale, backend=backend, extension_paths=extension_paths)
 
     context_kwargs: dict[str, Any] = {}
     if user_agent:
@@ -601,6 +612,7 @@ async def launch_context_async(
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    extension_paths: list[str] | None = None,
     **kwargs: Any,
 ) -> Any:
     """Async version of launch_context().
@@ -614,6 +626,7 @@ async def launch_context_async(
         headless: Run in headless mode (default True).
         proxy: Proxy URL string or Playwright proxy dict (see launch() for details).
         args: Additional Chromium CLI arguments.
+        extension_paths: List of Chrome extension paths to load.
         stealth_args: Include default stealth fingerprint args (default True).
         user_agent: Custom user agent string.
         viewport: Viewport size dict, e.g. {"width": 1920, "height": 1080}.
@@ -662,7 +675,7 @@ async def launch_context_async(
     # so it applies to ALL contexts, not just the default one.
     # locale and timezone are set via binary flags only — no CDP emulation.
     browser = await launch_async(headless=headless, proxy=proxy, args=args, stealth_args=stealth_args,
-                                 timezone=timezone, locale=locale, backend=backend)
+                                 timezone=timezone, locale=locale, backend=backend, extension_paths=extension_paths)
 
     context_kwargs: dict[str, Any] = {}
     if user_agent:
@@ -957,6 +970,7 @@ def build_args(
     timezone: str | None = None,
     locale: str | None = None,
     headless: bool = True,
+    extension_paths: list[str] | None = None,
 ) -> list[str]:
     """Combine stealth args with user-provided args and locale flags.
 
@@ -1000,6 +1014,15 @@ def build_args(
                 logger.debug("Arg override: %s -> %s", seen[key], flag)
             seen[key] = flag
 
+    if extension_paths:
+        abs_paths = [os.path.abspath(p) for p in extension_paths]
+        ext_val = ",".join(abs_paths)
+    
+        seen["--load-extension"] = f"--load-extension={ext_val}"
+        seen["--disable-extensions-except"] = (
+            f"--disable-extensions-except={ext_val}"
+        )
+
     return list(seen.values())
 
 

cloakbrowser/human/actionability.py

@@ -0,0 +1,342 @@
+"""Playwright-style actionability checks for the humanize layer (sync).
+
+Checks: attached, visible, stable, enabled, editable, receives pointer events.
+Retry loop with backoff matching Playwright internals: [100, 250, 500, 1000]ms.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, FrozenSet, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Error hierarchy — all subclass RuntimeError for backward compat
+# ---------------------------------------------------------------------------
+
+class ActionabilityError(RuntimeError):
+    """Base for all actionability failures."""
+
+    def __init__(self, selector: str, check: str, message: str):
+        self.selector = selector
+        self.check = check
+        super().__init__(f"Element {selector!r} failed {check} check: {message}")
+
+
+class ElementNotAttachedError(ActionabilityError):
+    def __init__(self, selector: str):
+        super().__init__(selector, "attached", "element not found in DOM")
+
+
+class ElementNotVisibleError(ActionabilityError):
+    def __init__(self, selector: str):
+        super().__init__(selector, "visible", "element is not visible")
+
+
+class ElementNotStableError(ActionabilityError):
+    def __init__(self, selector: str):
+        super().__init__(selector, "stable", "element position is still changing")
+
+
+class ElementNotEnabledError(ActionabilityError):
+    def __init__(self, selector: str):
+        super().__init__(selector, "enabled", "element is disabled")
+
+
+class ElementNotEditableError(ActionabilityError):
+    def __init__(self, selector: str):
+        super().__init__(selector, "editable", "element is not editable")
+
+
+class ElementNotReceivingEventsError(ActionabilityError):
+    def __init__(self, selector: str, covering_tag: str = "unknown"):
+        super().__init__(
+            selector,
+            "pointer_events",
+            f"element is covered by <{covering_tag}>",
+        )
+
+
+# ---------------------------------------------------------------------------
+# Check-set constants
+# ---------------------------------------------------------------------------
+
+CHECKS_CLICK: FrozenSet[str] = frozenset({"attached", "visible", "enabled", "pointer_events"})
+CHECKS_HOVER: FrozenSet[str] = frozenset({"attached", "visible", "pointer_events"})
+CHECKS_INPUT: FrozenSet[str] = frozenset({"attached", "visible", "enabled", "editable", "pointer_events"})
+CHECKS_FOCUS: FrozenSet[str] = frozenset({"attached", "visible", "enabled"})
+CHECKS_CHECK: FrozenSet[str] = frozenset({"attached", "visible", "enabled", "pointer_events"})
+
+_BACKOFF_MS = [100, 250, 500, 1000]
+
+
+def _backoff_sleep(attempt: int) -> None:
+    idx = min(attempt, len(_BACKOFF_MS) - 1)
+    time.sleep(_BACKOFF_MS[idx] / 1000.0)
+
+
+# ---------------------------------------------------------------------------
+# Pre-scroll actionability: attached, visible, enabled, editable
+# ---------------------------------------------------------------------------
+
+def ensure_actionable(
+    page: Any,
+    selector: str,
+    checks: FrozenSet[str],
+    timeout: float = 30000,
+    force: bool = False,
+) -> None:
+    """Wait for element to pass actionability checks (pre-scroll).
+
+    Retries with backoff until *timeout* ms elapsed.
+    Raises a specific ``ActionabilityError`` subclass on failure.
+    If *force* is True, returns immediately.
+    """
+    if force:
+        return
+
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+    last_error: Optional[ActionabilityError] = None
+
+    while True:
+        remaining_ms = max(0, (deadline - time.monotonic()) * 1000)
+        if remaining_ms <= 0:
+            if last_error is not None:
+                raise last_error
+            raise ActionabilityError(selector, "timeout", "timeout expired before first check")
+
+        try:
+            loc = page.locator(selector).first
+
+            if "attached" in checks:
+                try:
+                    loc.wait_for(state="attached", timeout=max(1, min(remaining_ms, 2000)))
+                except Exception:
+                    raise ElementNotAttachedError(selector)
+
+            if "visible" in checks:
+                if not loc.is_visible():
+                    raise ElementNotVisibleError(selector)
+
+            if "enabled" in checks:
+                if not loc.is_enabled():
+                    raise ElementNotEnabledError(selector)
+
+            if "editable" in checks:
+                if not loc.is_editable():
+                    raise ElementNotEditableError(selector)
+
+            return
+
+        except ActionabilityError as e:
+            last_error = e
+            if time.monotonic() >= deadline:
+                raise last_error
+            _backoff_sleep(attempt)
+            attempt += 1
+
+
+# ---------------------------------------------------------------------------
+# Post-scroll stability check
+# ---------------------------------------------------------------------------
+
+def _boxes_differ(a: dict, b: dict) -> bool:
+    return (
+        abs(a["x"] - b["x"]) > 1
+        or abs(a["y"] - b["y"]) > 1
+        or abs(a["width"] - b["width"]) > 1
+        or abs(a["height"] - b["height"]) > 1
+    )
+
+
+def ensure_stable(
+    page: Any,
+    selector: str,
+    timeout: float = 5000,
+) -> None:
+    """Wait for element position to stabilize (two samples 100ms apart).
+
+    Only call after scroll — skip if element was already in viewport.
+    """
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+
+    while True:
+        remaining_ms = max(0, (deadline - time.monotonic()) * 1000)
+        if remaining_ms <= 0:
+            raise ElementNotStableError(selector)
+
+        loc = page.locator(selector).first
+        box1 = loc.bounding_box(timeout=max(1, min(remaining_ms, 1000)))
+        if box1 is None:
+            raise ElementNotAttachedError(selector)
+
+        time.sleep(0.1)
+
+        box2 = loc.bounding_box(timeout=max(1, min(remaining_ms, 1000)))
+        if box2 is None:
+            raise ElementNotAttachedError(selector)
+
+        if not _boxes_differ(box1, box2):
+            return
+
+        if time.monotonic() >= deadline:
+            raise ElementNotStableError(selector)
+
+        _backoff_sleep(attempt)
+        attempt += 1
+
+
+# ---------------------------------------------------------------------------
+# Pointer-events check (post-scroll, at actual click coordinates)
+# ---------------------------------------------------------------------------
+
+_POINTER_EVENTS_LOCATOR_JS = """(expected, coords) => {
+    const target = document.elementFromPoint(coords.x, coords.y);
+    if (!target) return { hit: false, reason: 'no_element_at_point', covering: 'none' };
+    let node = target;
+    while (node) { if (node === expected) return { hit: true }; node = node.parentNode; }
+    if (expected.contains(target)) return { hit: true };
+    return { hit: false, reason: 'covered', covering: target.tagName || 'unknown' };
+}"""
+
+_POINTER_EVENTS_HANDLE_JS = """(expected, coords) => {
+    const target = document.elementFromPoint(coords.x, coords.y);
+    if (!target) return { hit: false, reason: 'no_element_at_point', covering: 'none' };
+    let node = target;
+    while (node) { if (node === expected) return { hit: true }; node = node.parentNode; }
+    if (expected.contains(target)) return { hit: true };
+    return { hit: false, reason: 'covered', covering: target.tagName || 'unknown' };
+}"""
+
+
+def check_pointer_events(
+    page: Any,
+    selector: str,
+    x: float,
+    y: float,
+    stealth: Any = None,
+    timeout: float = 5000,
+) -> None:
+    """Check that elementFromPoint(x, y) hits the expected element.
+
+    Uses locator.evaluate() so all Playwright selector types work
+    (text=, role=, XPath, CSS, etc.). Retries with backoff for transient overlays.
+    """
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+    coords = {"x": x, "y": y}
+
+    while True:
+        try:
+            loc = page.locator(selector).first
+            result = loc.evaluate(_POINTER_EVENTS_LOCATOR_JS, coords)
+        except Exception as exc:
+            logger.debug("pointer_events check failed for %r: %s", selector, exc)
+            result = None
+
+        if result and result.get("hit", False):
+            return
+
+        covering = (result or {}).get("covering", "unknown")
+
+        if time.monotonic() >= deadline:
+            raise ElementNotReceivingEventsError(selector, covering)
+
+        _backoff_sleep(attempt)
+        attempt += 1
+
+
+# ---------------------------------------------------------------------------
+# ElementHandle variant
+# ---------------------------------------------------------------------------
+
+def ensure_actionable_handle(
+    page: Any,
+    el: Any,
+    checks: FrozenSet[str],
+    timeout: float = 30000,
+    force: bool = False,
+) -> None:
+    """Actionability checks for ElementHandle (no selector needed).
+
+    Uses Playwright's wait_for_element_state where available.
+    """
+    if force:
+        return
+
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+    last_error: Optional[ActionabilityError] = None
+    label = "<ElementHandle>"
+
+    while True:
+        remaining_ms = max(0, (deadline - time.monotonic()) * 1000)
+        if remaining_ms <= 0:
+            if last_error is not None:
+                raise last_error
+            raise ActionabilityError(label, "timeout", "timeout expired before first check")
+
+        try:
+            if "visible" in checks:
+                try:
+                    el.wait_for_element_state("visible", timeout=max(1, min(remaining_ms, 2000)))
+                except Exception:
+                    raise ElementNotVisibleError(label)
+
+            if "enabled" in checks:
+                try:
+                    el.wait_for_element_state("enabled", timeout=max(1, min(remaining_ms, 2000)))
+                except Exception:
+                    raise ElementNotEnabledError(label)
+
+            if "editable" in checks:
+                try:
+                    el.wait_for_element_state("editable", timeout=max(1, min(remaining_ms, 2000)))
+                except Exception:
+                    raise ElementNotEditableError(label)
+
+            return
+
+        except ActionabilityError as e:
+            last_error = e
+            if time.monotonic() >= deadline:
+                raise last_error
+            _backoff_sleep(attempt)
+            attempt += 1
+
+
+def check_pointer_events_handle(
+    page: Any,
+    el: Any,
+    x: float,
+    y: float,
+    timeout: float = 5000,
+) -> None:
+    """Pointer-events check for ElementHandle."""
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+
+    coords = {"x": x, "y": y}
+
+    while True:
+        try:
+            result = el.evaluate(_POINTER_EVENTS_HANDLE_JS, coords)
+        except Exception:
+            result = None
+
+        if result and result.get("hit", False):
+            return
+
+        covering = (result or {}).get("covering", "unknown")
+
+        if time.monotonic() >= deadline:
+            raise ElementNotReceivingEventsError("<ElementHandle>", covering)
+
+        _backoff_sleep(attempt)
+        attempt += 1

cloakbrowser/human/actionability_async.py

@@ -0,0 +1,247 @@
+"""Playwright-style actionability checks for the humanize layer (async).
+
+Async mirror of actionability.py — same logic, uses asyncio.sleep and await.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any, FrozenSet, Optional
+
+logger = logging.getLogger(__name__)
+
+from .actionability import (
+    ActionabilityError,
+    ElementNotAttachedError,
+    ElementNotVisibleError,
+    ElementNotStableError,
+    ElementNotEnabledError,
+    ElementNotEditableError,
+    ElementNotReceivingEventsError,
+    _BACKOFF_MS,
+    _boxes_differ,
+    _POINTER_EVENTS_LOCATOR_JS,
+    _POINTER_EVENTS_HANDLE_JS,
+)
+
+
+async def _async_backoff_sleep(attempt: int) -> None:
+    idx = min(attempt, len(_BACKOFF_MS) - 1)
+    await asyncio.sleep(_BACKOFF_MS[idx] / 1000.0)
+
+
+# ---------------------------------------------------------------------------
+# Pre-scroll actionability
+# ---------------------------------------------------------------------------
+
+async def async_ensure_actionable(
+    page: Any,
+    selector: str,
+    checks: FrozenSet[str],
+    timeout: float = 30000,
+    force: bool = False,
+) -> None:
+    if force:
+        return
+
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+    last_error: Optional[ActionabilityError] = None
+
+    while True:
+        remaining_ms = max(0, (deadline - time.monotonic()) * 1000)
+        if remaining_ms <= 0:
+            if last_error is not None:
+                raise last_error
+            raise ActionabilityError(selector, "timeout", "timeout expired before first check")
+
+        try:
+            loc = page.locator(selector).first
+
+            if "attached" in checks:
+                try:
+                    await loc.wait_for(state="attached", timeout=max(1, min(remaining_ms, 2000)))
+                except Exception:
+                    raise ElementNotAttachedError(selector)
+
+            if "visible" in checks:
+                if not await loc.is_visible():
+                    raise ElementNotVisibleError(selector)
+
+            if "enabled" in checks:
+                if not await loc.is_enabled():
+                    raise ElementNotEnabledError(selector)
+
+            if "editable" in checks:
+                if not await loc.is_editable():
+                    raise ElementNotEditableError(selector)
+
+            return
+
+        except ActionabilityError as e:
+            last_error = e
+            if time.monotonic() >= deadline:
+                raise last_error
+            await _async_backoff_sleep(attempt)
+            attempt += 1
+
+
+# ---------------------------------------------------------------------------
+# Post-scroll stability check
+# ---------------------------------------------------------------------------
+
+async def async_ensure_stable(
+    page: Any,
+    selector: str,
+    timeout: float = 5000,
+) -> None:
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+
+    while True:
+        remaining_ms = max(0, (deadline - time.monotonic()) * 1000)
+        if remaining_ms <= 0:
+            raise ElementNotStableError(selector)
+
+        loc = page.locator(selector).first
+        box1 = await loc.bounding_box(timeout=max(1, min(remaining_ms, 1000)))
+        if box1 is None:
+            raise ElementNotAttachedError(selector)
+
+        await asyncio.sleep(0.1)
+
+        box2 = await loc.bounding_box(timeout=max(1, min(remaining_ms, 1000)))
+        if box2 is None:
+            raise ElementNotAttachedError(selector)
+
+        if not _boxes_differ(box1, box2):
+            return
+
+        if time.monotonic() >= deadline:
+            raise ElementNotStableError(selector)
+
+        await _async_backoff_sleep(attempt)
+        attempt += 1
+
+
+# ---------------------------------------------------------------------------
+# Pointer-events check
+# ---------------------------------------------------------------------------
+
+async def async_check_pointer_events(
+    page: Any,
+    selector: str,
+    x: float,
+    y: float,
+    stealth: Any = None,
+    timeout: float = 5000,
+) -> None:
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+    coords = {"x": x, "y": y}
+
+    while True:
+        try:
+            loc = page.locator(selector).first
+            result = await loc.evaluate(_POINTER_EVENTS_LOCATOR_JS, coords)
+        except Exception as exc:
+            logger.debug("pointer_events check failed for %r: %s", selector, exc)
+            result = None
+
+        if result and result.get("hit", False):
+            return
+
+        covering = (result or {}).get("covering", "unknown")
+
+        if time.monotonic() >= deadline:
+            raise ElementNotReceivingEventsError(selector, covering)
+
+        await _async_backoff_sleep(attempt)
+        attempt += 1
+
+
+# ---------------------------------------------------------------------------
+# ElementHandle variant
+# ---------------------------------------------------------------------------
+
+async def async_ensure_actionable_handle(
+    page: Any,
+    el: Any,
+    checks: FrozenSet[str],
+    timeout: float = 30000,
+    force: bool = False,
+) -> None:
+    if force:
+        return
+
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+    last_error: Optional[ActionabilityError] = None
+    label = "<ElementHandle>"
+
+    while True:
+        remaining_ms = max(0, (deadline - time.monotonic()) * 1000)
+        if remaining_ms <= 0:
+            if last_error is not None:
+                raise last_error
+            raise ActionabilityError(label, "timeout", "timeout expired before first check")
+
+        try:
+            if "visible" in checks:
+                try:
+                    await el.wait_for_element_state("visible", timeout=max(1, min(remaining_ms, 2000)))
+                except Exception:
+                    raise ElementNotVisibleError(label)
+
+            if "enabled" in checks:
+                try:
+                    await el.wait_for_element_state("enabled", timeout=max(1, min(remaining_ms, 2000)))
+                except Exception:
+                    raise ElementNotEnabledError(label)
+
+            if "editable" in checks:
+                try:
+                    await el.wait_for_element_state("editable", timeout=max(1, min(remaining_ms, 2000)))
+                except Exception:
+                    raise ElementNotEditableError(label)
+
+            return
+
+        except ActionabilityError as e:
+            last_error = e
+            if time.monotonic() >= deadline:
+                raise last_error
+            await _async_backoff_sleep(attempt)
+            attempt += 1
+
+
+async def async_check_pointer_events_handle(
+    page: Any,
+    el: Any,
+    x: float,
+    y: float,
+    timeout: float = 5000,
+) -> None:
+    deadline = time.monotonic() + timeout / 1000.0
+    attempt = 0
+
+    coords = {"x": x, "y": y}
+
+    while True:
+        try:
+            result = await el.evaluate(_POINTER_EVENTS_HANDLE_JS, coords)
+        except Exception:
+            result = None
+
+        if result and result.get("hit", False):
+            return
+
+        covering = (result or {}).get("covering", "unknown")
+
+        if time.monotonic() >= deadline:
+            raise ElementNotReceivingEventsError("<ElementHandle>", covering)
+
+        await _async_backoff_sleep(attempt)
+        attempt += 1

cloakbrowser/human/scroll.py

@@ -26,7 +26,7 @@ def _get_element_box(page: Any, selector: str, timeout: float = 30000) -> Option
     """
     try:
         el = page.locator(selector).first
-        return el.bounding_box(timeout=timeout)
+        return el.bounding_box(timeout=max(1, timeout))
     except Exception:
         return None
 
@@ -50,7 +50,7 @@ def human_scroll_into_view(
     get_box: Callable[[], Optional[dict]],
     cursor_x: float, cursor_y: float,
     cfg: HumanConfig,
-) -> Tuple[dict, float, float]:
+) -> Tuple[dict, float, float, bool]:
     """Humanized scrolling that uses an arbitrary ``get_box`` callable
     instead of a CSS selector.
 
@@ -58,6 +58,9 @@ def human_scroll_into_view(
     ``ElementHandle.scroll_into_view_if_needed`` / ``Locator.scroll_into_view_if_needed``
     (handle-based) so the same accelerate \u2192 cruise \u2192 decelerate \u2192 overshoot
     behavior runs everywhere.
+
+    Returns ``(box, cursor_x, cursor_y, did_scroll)`` \u2014 *did_scroll* is False
+    when the element was already in the viewport.
     """
     viewport = page.viewport_size
     if not viewport:
@@ -71,7 +74,7 @@ def human_scroll_into_view(
         raise RuntimeError("Element not found while scrolling into view")
 
     if _is_in_viewport(box, viewport_height, cfg):
-        return box, cursor_x, cursor_y
+        return box, cursor_x, cursor_y, False
 
     # Move cursor into scroll area
     scroll_area_x = round(viewport_width * rand(0.3, 0.7))
@@ -139,7 +142,7 @@ def human_scroll_into_view(
     if box is None:
         raise RuntimeError("Element lost after scrolling into view")
 
-    return box, cursor_x, cursor_y
+    return box, cursor_x, cursor_y, True
 
 
 def scroll_to_element(
@@ -149,12 +152,14 @@ def scroll_to_element(
     cursor_x: float, cursor_y: float,
     cfg: HumanConfig,
     timeout: float = 30000,
-) -> Tuple[dict, float, float]:
+) -> Tuple[dict, float, float, bool]:
     """Selector-based humanized scroll.
 
     ``timeout`` is forwarded to ``locator.bounding_box(timeout=...)`` so callers
     such as ``page.click('#x', timeout=5000)`` can wait longer for slow elements
     (#172). Default matches Playwright's 30000ms when not specified.
+
+    Returns ``(box, cursor_x, cursor_y, did_scroll)``.
     """
     return human_scroll_into_view(
         page, raw,

cloakbrowser/human/scroll_async.py

@@ -23,7 +23,7 @@ async def _get_element_box_async(
     elements (#172)."""
     try:
         el = page.locator(selector).first
-        return await el.bounding_box(timeout=timeout)
+        return await el.bounding_box(timeout=max(1, timeout))
     except Exception:
         return None
 
@@ -47,13 +47,16 @@ async def async_human_scroll_into_view(
     get_box: Callable[[], Awaitable[Optional[dict]]],
     cursor_x: float, cursor_y: float,
     cfg: HumanConfig,
-) -> Tuple[dict, float, float]:
+) -> Tuple[dict, float, float, bool]:
     """Humanized scrolling using an arbitrary async ``get_box`` callable.
 
     Used by both ``async_scroll_to_element`` (selector-based) and the
     ElementHandle / Locator ``scroll_into_view_if_needed`` patches so all
     scrolling paths share the same accelerate \u2192 cruise \u2192 decelerate
     \u2192 overshoot behavior.
+
+    Returns ``(box, cursor_x, cursor_y, did_scroll)`` \u2014 *did_scroll* is False
+    when the element was already in the viewport.
     """
     viewport = page.viewport_size
     if not viewport:
@@ -67,7 +70,7 @@ async def async_human_scroll_into_view(
         raise RuntimeError("Element not found while scrolling into view")
 
     if _is_in_viewport(box, viewport_height, cfg):
-        return box, cursor_x, cursor_y
+        return box, cursor_x, cursor_y, False
 
     # Move cursor into scroll area
     scroll_area_x = round(viewport_width * rand(0.3, 0.7))
@@ -135,7 +138,7 @@ async def async_human_scroll_into_view(
     if box is None:
         raise RuntimeError("Element lost after scrolling into view")
 
-    return box, cursor_x, cursor_y
+    return box, cursor_x, cursor_y, True
 
 
 async def async_scroll_to_element(
@@ -145,12 +148,14 @@ async def async_scroll_to_element(
     cursor_x: float, cursor_y: float,
     cfg: HumanConfig,
     timeout: float = 30000,
-) -> Tuple[dict, float, float]:
+) -> Tuple[dict, float, float, bool]:
     """Selector-based humanized scroll (async).
 
     ``timeout`` is forwarded to ``locator.bounding_box(timeout=...)`` so callers
     such as ``page.click('#x', timeout=5000)`` can wait longer for slow elements
     (#172). Default matches Playwright's 30000ms when not specified.
+
+    Returns ``(box, cursor_x, cursor_y, did_scroll)``.
     """
     async def _get():
         return await _get_element_box_async(page, selector, timeout)

examples/integrations/aws_lambda/INSTRUCTIONS.md

@@ -70,7 +70,7 @@ Only `url` is required. Everything else is optional.
 
 | Field | Type | Default |
 |---|---|---|
-| `url` | str | required |
+| `url` | str | required — `http://` and `https://` only |
 | `proxy` | str / dict | none — `http://user:pass@host:port` or a Playwright proxy dict |
 | `humanize` | bool | `false` — enable human-like mouse / keyboard / scroll |
 | `human_preset` | str | `"default"` or `"careful"` |
@@ -79,7 +79,6 @@ Only `url` is required. Everything else is optional.
 | `locale` | str | none — BCP-47, e.g. `"en-US"` |
 | `viewport` | `{width,height}` | `1920x947` (cloakbrowser default) |
 | `user_agent` | str | none |
-| `extra_args` | `list[str]` | `[]` — extra Chromium CLI flags |
 
 ### Navigation
 
@@ -102,8 +101,6 @@ Only `url` is required. Everything else is optional.
 | `wait_for_selector` | str | none — CSS or XPath |
 | `wait_for_selector_state` | str | `"visible"` — also `attached` / `detached` / `hidden` |
 | `wait_for_selector_timeout_ms` | int | `30000` |
-| `wait_for_function` | str | none — JS expression returning truthy when ready |
-| `wait_for_function_timeout_ms` | int | `30000` |
 | `wait_ms` | int | none — fixed pause |
 
 ### Capture
@@ -118,7 +115,7 @@ Only `url` is required. Everything else is optional.
 The handler retries transient navigation failures inline within the same Lambda invocation. Two layers, both built-in:
 
 - **Launch retries** — 3 attempts with 0.3 s + 0.6 s backoff. Recovers Xvfb / Chromium spawn races at cold start. Fast and cheap; not configurable.
-- **Strategy retries** — default 1 attempt, configurable via the `retries` event field. Recovers specific post-launch error classes by relaunching with adjusted Chromium args / page-load budgets.
+- **Strategy retries** — default 1 attempt, configurable via the `retries` event field. Recovers specific post-launch error classes by relaunching with adjusted internal Chromium args / page-load budgets.
 
 | Field | Type | Default |
 |---|---|---|
@@ -176,6 +173,22 @@ For latency-sensitive use cases: provision concurrency, schedule a CloudWatch/Ev
 
 If you see empty/missing dynamic content on cold-start invocations, raise `max_settle_ms` in the event payload (e.g. `25000`) — the default `15000` is tuned for warm runs.
 
+## Security
+
+The handler validates all incoming URLs before navigation:
+
+- **Scheme restriction** — only `http://` and `https://` are accepted. `file://`, `data:`, `javascript:`, and other schemes are rejected.
+- **SSRF protection** — hostnames are resolved before navigation and checked against private, loopback, link-local, reserved, and multicast IP ranges. This blocks access to cloud metadata endpoints (e.g. `169.254.169.254`), localhost services, and internal networks.
+- **Post-navigation re-validation** — the final URL is re-checked after page load and after post-navigation waits to catch server-side redirects to blocked destinations.
+- **No caller-controlled Chromium flags** — the handler does not accept arbitrary CLI flags from the event. Internal retry strategies add flags as needed (e.g. `--ignore-certificate-errors` for cert errors).
+- **No arbitrary JS execution** — `wait_for_function` is not exposed. Use `wait_for_selector` or `smart_wait` instead.
+
+**Limitations**:
+- Post-navigation re-validation prevents response *exfiltration*, but does not prevent the browser from *making* the request. If an internal endpoint has side effects on GET, the request will still reach it before validation rejects the response. Use network-level controls (security groups, VPC) to protect side-effect-bearing internal endpoints.
+- DNS rebinding attacks can bypass pre-navigation IP checks in theory, though the post-navigation re-validation provides a second layer of defense.
+
+**Trust boundary**: if this handler is exposed to untrusted callers (Lambda Function URL, API Gateway without auth, public ALB), add an authentication layer (API Gateway authorizer, IAM auth, etc.). The URL validation above is defense-in-depth, not a substitute for access control.
+
 ## License
 
 The patched Chromium binary inside the upstream `cloakhq/cloakbrowser` image is governed by the **CloakBrowser Binary License** (published at https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md). Internal organizational use (private ECR, your own scraping pipelines, your own business) is free. Exposing this Lambda as a paid API to third-party customers — i.e. browser-as-a-service — requires an OEM/SaaS license from CloakHQ (`cloakhq@pm.me`). Do not push the resulting image to a public registry; that would be redistribution and is prohibited.

examples/integrations/aws_lambda/lambda_handler.py

@@ -5,7 +5,7 @@ Always runs **headed** via the Xvfb display started by `lambda-entrypoint.sh`.
 Event schema (all fields except `url` are optional):
 
     Launch options (passed to cloakbrowser.launch_context_async):
-        url                 str              required, the page to scrape
+        url                 str              required, the page to scrape (http/https only)
         proxy               str|dict         http://user:pass@host:port  or  Playwright proxy dict
         humanize            bool             False — enable human-like mouse/keyboard/scroll
         human_preset        str              "default" | "careful"
@@ -14,7 +14,6 @@ Event schema (all fields except `url` are optional):
         locale              str              BCP-47, e.g. "en-US"
         viewport            {width,height}   defaults to 1920x947 (cloakbrowser DEFAULT_VIEWPORT)
         user_agent          str              custom UA (rare — cloakbrowser sets one already)
-        extra_args          list[str]        additional Chromium CLI flags
 
     Navigation options (passed to page.goto):
         wait_until          str              "load"|"domcontentloaded"|"networkidle"|"commit"
@@ -35,8 +34,6 @@ Event schema (all fields except `url` are optional):
         wait_for_selector                str  CSS or XPath selector
         wait_for_selector_state          str  "attached"|"detached"|"visible"|"hidden", default "visible"
         wait_for_selector_timeout_ms     int  30000
-        wait_for_function                str  JS expression that returns truthy when ready
-        wait_for_function_timeout_ms     int  30000
         wait_ms                          int  fixed pause in ms (page.wait_for_timeout)
 
     Capture options:
@@ -64,11 +61,14 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import ipaddress
 import json
 import logging
+import socket
 import subprocess
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlparse
 
 from cloakbrowser import launch_context_async
 
@@ -76,6 +76,26 @@ logger = logging.getLogger("cloakbrowser.lambda")
 logger.setLevel(logging.INFO)
 
 
+def _validate_url(url: str) -> None:
+    """Reject non-HTTP schemes and URLs that resolve to private/internal IPs."""
+    parsed = urlparse(url)
+    if parsed.scheme.lower() not in ("http", "https"):
+        raise ValueError(
+            f"Only http:// and https:// URLs are supported, got: {parsed.scheme!r}"
+        )
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError("URL has no hostname")
+    try:
+        infos = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
+    except socket.gaierror:
+        raise ValueError(f"Cannot resolve hostname: {hostname}")
+    for info in infos:
+        addr = ipaddress.ip_address(info[4][0])
+        if not addr.is_global:
+            raise ValueError("URLs targeting private/internal networks are blocked")
+
+
 def _diag_snapshot() -> str:
     """Capture Xvfb status, Xvfb log, X11 socket state, and env for error reports."""
     import os
@@ -118,7 +138,7 @@ def _build_launch_kwargs(event: dict) -> dict:
             # Lambda's restricted process model can't fork from Chromium's zygote
             # — without this, child renderer processes fail to spawn.
             "--no-zygote",
-            *event.get("extra_args", []),
+            *event.get("_strategy_args", []),
         ],
     }
     for key in ("proxy", "humanize", "human_preset", "geoip",
@@ -159,7 +179,7 @@ async def _smart_wait(page, dom_stable_ms: int = 1500, max_settle_ms: int = 1500
 
 
 _EXPLICIT_WAIT_KEYS = (
-    "wait_for_load_state", "wait_for_selector", "wait_for_function", "wait_ms",
+    "wait_for_load_state", "wait_for_selector", "wait_ms",
 )
 
 
@@ -184,11 +204,6 @@ async def _post_nav_waits(page, event: dict) -> None:
             state=event.get("wait_for_selector_state", "visible"),
             timeout=event.get("wait_for_selector_timeout_ms", 30000),
         )
-    if "wait_for_function" in event:
-        await page.wait_for_function(
-            event["wait_for_function"],
-            timeout=event.get("wait_for_function_timeout_ms", 30000),
-        )
     if "wait_ms" in event:
         await page.wait_for_timeout(event["wait_ms"])
 
@@ -235,7 +250,7 @@ def _classify_error(err: Exception) -> dict | None:
     msg = str(err)
     if "ERR_CERT" in msg:
         return {
-            "extra_args": ["--ignore-certificate-errors"],
+            "_strategy_args": ["--ignore-certificate-errors"],
             "goto_timeout_ms": 60000,
         }
     if ("Timeout" in msg and "exceeded" in msg) or "ERR_CONNECTION_TIMED_OUT" in msg:
@@ -263,8 +278,10 @@ async def _attempt_scrape(url: str, event: dict) -> dict:
             wait_until=event.get("wait_until", "domcontentloaded"),
             timeout=event.get("goto_timeout_ms", 30000),
         )
+        _validate_url(page.url)
 
         await _post_nav_waits(page, event)
+        _validate_url(page.url)
 
         result: dict = {
             "title": await page.title(),
@@ -306,6 +323,8 @@ async def _run(event: dict) -> dict:
     set to 0 to disable retry entirely).
     """
     url = event["url"]
+    _validate_url(url)
+    event = {k: v for k, v in event.items() if k not in ("extra_args", "_strategy_args")}
     retries_left = max(0, int(event.get("retries", 1)))
     history: list[dict] = []
     current_event = event
@@ -326,8 +345,8 @@ async def _run(event: dict) -> dict:
             })
             logger.warning("attempt %d failed (%s); retrying with strategy=%s",
                            len(history), str(e)[:120], strategy)
-            merged_args = list(current_event.get("extra_args", [])) + list(strategy.get("extra_args", []))
-            current_event = {**current_event, **strategy, "extra_args": merged_args}
+            merged_args = list(current_event.get("_strategy_args", [])) + list(strategy.get("_strategy_args", []))
+            current_event = {**current_event, **strategy, "_strategy_args": merged_args}
             retries_left -= 1
             # No backoff: strategy overrides change goto budget directly;
             # the prior failure was either fast (cert reject) or already

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1777954456,
+        "narHash": "sha256-hGdgeU2Nk87RAuZyYjyDjFL6LK7dAZN5RE9+hrDTkDU=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "549bd84d6279f9852cae6225e372cc67fb91a4c1",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,237 @@
+{
+  description = "CloakBrowser development shell with Nix-packaged Chromium binaries";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = { self, nixpkgs }:
+    let
+      inherit (nixpkgs) lib;
+
+      supportedSystems = [
+        "x86_64-linux"
+        "aarch64-linux"
+      ];
+
+      forAllSystems = lib.genAttrs supportedSystems;
+
+      packageInfo = {
+        x86_64-linux = {
+          platformTag = "linux-x64";
+          version = "146.0.7680.177.3";
+          hash = "sha256-WvAn+q+x/vmTPreEwJS3ZHBt4io3KizuhLwRf8SrU38=";
+        };
+        aarch64-linux = {
+          platformTag = "linux-arm64";
+          version = "146.0.7680.177.3";
+          hash = "sha256-i3HOU7T9ExMnMxox+6ODXXGILRm/qr3njdD1OQvRb0U=";
+        };
+      };
+
+      cloakbrowserBinaryLicense = {
+        shortName = "cloakbrowser-binary";
+        fullName = "CloakBrowser Binary License";
+        url = "https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md";
+        free = false;
+        redistributable = false;
+      };
+
+      mkPkgs = system: import nixpkgs {
+        inherit system;
+        config.allowUnfree = true;
+      };
+
+      runtimeLibraries = pkgs: with pkgs; [
+        alsa-lib
+        at-spi2-atk
+        at-spi2-core
+        atk
+        cairo
+        cups
+        dbus
+        expat
+        fontconfig
+        freetype
+        gdk-pixbuf
+        glib
+        gtk3
+        libdrm
+        libgbm
+        libGL
+        libpulseaudio
+        libxkbcommon
+        mesa
+        nspr
+        nss
+        pango
+        systemd
+        wayland
+        libx11
+        libxcb
+        libxcomposite
+        libxcursor
+        libxdamage
+        libxext
+        libxfixes
+        libxi
+        libxrandr
+        libxrender
+        libxscrnsaver
+        libxshmfence
+        libxtst
+      ];
+
+      fontPackages = pkgs: with pkgs; [
+        freefont_ttf
+        ipafont
+        liberation_ttf
+        noto-fonts
+        noto-fonts-cjk-sans
+        noto-fonts-color-emoji
+        tlwg
+        unifont
+        wqy_zenhei
+      ];
+
+      desktopPackages = pkgs: with pkgs; [
+        adwaita-icon-theme
+        gsettings-desktop-schemas
+        xdg-utils
+      ];
+
+      mkCloakBrowserChromium = pkgs: system:
+        let
+          info = packageInfo.${system} or (throw "CloakBrowser flake package currently supports only x86_64-linux and aarch64-linux.");
+          archiveName = "cloakbrowser-${info.platformTag}.tar.gz";
+          chromiumVersion = info.version;
+          libs = runtimeLibraries pkgs;
+          desktopDeps = desktopPackages pkgs;
+          fonts = fontPackages pkgs;
+          fontsConf = pkgs.makeFontsConf {
+            fontDirectories = fonts;
+          };
+        in
+        pkgs.stdenvNoCC.mkDerivation {
+          pname = "cloakbrowser-chromium";
+          version = chromiumVersion;
+
+          src = pkgs.fetchurl {
+            url = "https://cloakbrowser.dev/chromium-v${chromiumVersion}/${archiveName}";
+            inherit (info) hash;
+          };
+
+          dontUnpack = true;
+
+          nativeBuildInputs = with pkgs; [
+            autoPatchelfHook
+            makeWrapper
+          ];
+
+          buildInputs = libs ++ desktopDeps;
+          runtimeDependencies = libs;
+
+          installPhase = ''
+            runHook preInstall
+
+            mkdir -p "$out/lib/cloakbrowser" "$out/bin"
+            tar -xzf "$src" -C "$out/lib/cloakbrowser"
+            chmod +x "$out/lib/cloakbrowser/chrome"
+            chmod +x "$out/lib/cloakbrowser/chromedriver"
+
+            runHook postInstall
+          '';
+
+          postFixup = ''
+            makeWrapper "$out/lib/cloakbrowser/chrome" "$out/bin/cloakbrowser-chrome" \
+              --prefix LD_LIBRARY_PATH : "${lib.makeLibraryPath libs}" \
+              --prefix XDG_DATA_DIRS : "$GSETTINGS_SCHEMAS_PATH:$XDG_ICON_DIRS" \
+              --suffix PATH : "${lib.makeBinPath [ pkgs.xdg-utils ]}" \
+              --set FONTCONFIG_FILE "${fontsConf}" \
+              --set CHROME_WRAPPER "cloakbrowser-chrome"
+
+            makeWrapper "$out/lib/cloakbrowser/chromedriver" "$out/bin/cloakbrowser-chromedriver" \
+              --prefix LD_LIBRARY_PATH : "${lib.makeLibraryPath libs}"
+          '';
+
+          meta = {
+            description = "Official CloakBrowser patched Chromium binary";
+            homepage = "https://github.com/CloakHQ/CloakBrowser";
+            license = cloakbrowserBinaryLicense;
+            mainProgram = "cloakbrowser-chrome";
+            platforms = supportedSystems;
+            sourceProvenance = [ lib.sourceTypes.binaryNativeCode ];
+          };
+        };
+    in
+    {
+      packages = forAllSystems (system:
+        let
+          pkgs = mkPkgs system;
+          cloakbrowserChromium = mkCloakBrowserChromium pkgs system;
+        in
+        {
+          inherit cloakbrowserChromium;
+          default = cloakbrowserChromium;
+        });
+
+      apps = forAllSystems (system:
+        let
+          cloakbrowserChromium = self.packages.${system}.cloakbrowserChromium;
+        in
+        {
+          default = {
+            type = "app";
+            program = "${cloakbrowserChromium}/bin/cloakbrowser-chrome";
+            meta.description = "Run CloakBrowser Chromium";
+          };
+          cloakbrowser-chrome = {
+            type = "app";
+            program = "${cloakbrowserChromium}/bin/cloakbrowser-chrome";
+            meta.description = "Run CloakBrowser Chromium";
+          };
+          cloakbrowser-chromedriver = {
+            type = "app";
+            program = "${cloakbrowserChromium}/bin/cloakbrowser-chromedriver";
+            meta.description = "Run the CloakBrowser Chromedriver binary";
+          };
+        });
+
+      devShells = forAllSystems (system:
+        let
+          pkgs = mkPkgs system;
+          cloakbrowserChromium = self.packages.${system}.cloakbrowserChromium;
+          python = pkgs.python312.withPackages (ps: with ps; [
+            aiohttp
+            geoip2
+            hatchling
+            httpx
+            playwright
+            pytest
+            pytest-asyncio
+            socksio
+            websockets
+          ]);
+        in
+        {
+          default = pkgs.mkShell {
+            packages = [
+              cloakbrowserChromium
+              python
+              pkgs.cacert
+              pkgs.curl
+              pkgs.git
+              pkgs.jq
+              pkgs.nodejs_20
+              pkgs.which
+              pkgs.xdotool
+              pkgs.xvfb-run
+            ]
+            ++ runtimeLibraries pkgs
+            ++ fontPackages pkgs;
+
+            CLOAKBROWSER_BINARY_PATH = "${cloakbrowserChromium}/bin/cloakbrowser-chrome";
+          };
+        });
+    };
+}

js/README.md

@@ -230,6 +230,13 @@ const ctx = await launchPersistentContext({
   userDataDir: './my-profile',
   headless: false,
 });
+
+// Load Chrome extensions
+const ctx = await launchPersistentContext({
+  userDataDir: './my-profile',
+  headless: false,
+  extensionPaths: ['./my-extension'],
+});
 ```
 
 This also gives you cookie and localStorage persistence across sessions.

js/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "cloakbrowser",
-  "version": "0.3.23",
+  "version": "0.3.29",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "cloakbrowser",
-      "version": "0.3.23",
+      "version": "0.3.29",
       "license": "MIT",
       "dependencies": {
         "tar": "^7.0.0"
@@ -17,7 +17,7 @@
       "devDependencies": {
         "@types/node": "^20.10.0",
         "mmdb-lib": "^3.0.2",
-        "playwright-core": "^1.40.0",
+        "playwright-core": "^1.53.0",
         "puppeteer-core": "^21.0.0",
         "socks-proxy-agent": "^10.0.0",
         "typescript": "^5.3.0",
@@ -28,9 +28,9 @@
       },
       "peerDependencies": {
         "mmdb-lib": ">=2.0.0",
-        "playwright-core": ">=1.40.0",
+        "playwright-core": ">=1.53.0",
         "puppeteer-core": ">=21.0.0",
-        "socks-proxy-agent": ">=8.0.0"
+        "socks-proxy-agent": ">=10.0.0"
       },
       "peerDependenciesMeta": {
         "mmdb-lib": {
@@ -1092,9 +1092,9 @@
       "license": "MIT"
     },
     "node_modules/basic-ftp": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.2.0.tgz",
-      "integrity": "sha512-VoMINM2rqJwJgfdHq6RiUudKt2BV+FY5ZFezP/ypmwayk68+NzzAQy4XXLlqsGD4MCzq3DrmNFD/uUmBJuGoXw==",
+      "version": "5.3.1",
+      "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.3.1.tgz",
+      "integrity": "sha512-bopVNp6ugyA150DDuZfPFdt1KZ5a94ZDiwX4hMgZDzF+GttD80lEy8kj98kbyhLXnPvhtIo93mdnLIjpCAeeOw==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -1684,9 +1684,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/ip-address": {
-      "version": "10.1.0",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
-      "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
+      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -2114,9 +2114,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.6",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz",
-      "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==",
+      "version": "8.5.14",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
+      "integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
       "dev": true,
       "funding": [
         {
@@ -2496,9 +2496,9 @@
       }
     },
     "node_modules/tar": {
-      "version": "7.5.9",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.9.tgz",
-      "integrity": "sha512-BTLcK0xsDh2+PUe9F6c2TlRp4zOOBMTkoQHQIWSIzI0R7KG46uEwq4OPk2W7bZcprBMsuaeFsqwYr7pjh6CuHg==",
+      "version": "7.5.15",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.15.tgz",
+      "integrity": "sha512-dzGK0boVlC4W5QFuQN1EFSl3bIDYsk7Tj40U6eIBnK2k/8ml7TZ5agbI5j5+qnoVcAA+rNtBml8SEiLxZpNqRQ==",
       "license": "BlueOak-1.0.0",
       "dependencies": {
         "@isaacs/fs-minipass": "^4.0.0",

js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloakbrowser",
-  "version": "0.3.28",
+  "version": "0.3.29",
   "description": "Stealth Chromium that passes every bot detection test. Drop-in Playwright/Puppeteer replacement with source-level fingerprint patches.",
   "type": "module",
   "main": "dist/index.js",

js/src/args.ts

@@ -1,7 +1,7 @@
 /**
  * Shared argument builder for Playwright and Puppeteer wrappers.
  */
-
+import path from "path";
 import type { LaunchOptions } from "./types.js";
 import { getDefaultStealthArgs } from "./config.js";
 
@@ -55,5 +55,16 @@ export function buildArgs(options: LaunchOptions): string[] {
       seen.set(k, flag);
     }
   }
+
+  if (options.extensionPaths?.length) {
+    const absPaths = options.extensionPaths.map(p => path.resolve(p));
+    const joined = absPaths.join(",");
+
+    seen.set("--load-extension", `--load-extension=${joined}`);
+    seen.set(
+      "--disable-extensions-except",
+      `--disable-extensions-except=${joined}`
+    );
+  }
   return [...seen.values()];
 }

js/src/human/actionability.ts

@@ -0,0 +1,338 @@
+/**
+ * Playwright-style actionability checks for the humanize layer.
+ *
+ * Checks: attached, visible, stable, enabled, editable, receives pointer events.
+ * Retry loop with backoff matching Playwright internals: [100, 250, 500, 1000]ms.
+ */
+
+import type { Page, Frame, ElementHandle } from 'playwright-core';
+
+// ---------------------------------------------------------------------------
+// Error hierarchy
+// ---------------------------------------------------------------------------
+
+export class ActionabilityError extends Error {
+  selector: string;
+  check: string;
+
+  constructor(selector: string, check: string, message: string) {
+    super(`Element ${JSON.stringify(selector)} failed ${check} check: ${message}`);
+    this.name = 'ActionabilityError';
+    this.selector = selector;
+    this.check = check;
+  }
+}
+
+export class ElementNotAttachedError extends ActionabilityError {
+  constructor(selector: string) {
+    super(selector, 'attached', 'element not found in DOM');
+    this.name = 'ElementNotAttachedError';
+  }
+}
+
+export class ElementNotVisibleError extends ActionabilityError {
+  constructor(selector: string) {
+    super(selector, 'visible', 'element is not visible');
+    this.name = 'ElementNotVisibleError';
+  }
+}
+
+export class ElementNotStableError extends ActionabilityError {
+  constructor(selector: string) {
+    super(selector, 'stable', 'element position is still changing');
+    this.name = 'ElementNotStableError';
+  }
+}
+
+export class ElementNotEnabledError extends ActionabilityError {
+  constructor(selector: string) {
+    super(selector, 'enabled', 'element is disabled');
+    this.name = 'ElementNotEnabledError';
+  }
+}
+
+export class ElementNotEditableError extends ActionabilityError {
+  constructor(selector: string) {
+    super(selector, 'editable', 'element is not editable');
+    this.name = 'ElementNotEditableError';
+  }
+}
+
+export class ElementNotReceivingEventsError extends ActionabilityError {
+  coveringTag: string;
+  constructor(selector: string, coveringTag: string = 'unknown') {
+    super(selector, 'pointer_events', `element is covered by <${coveringTag}>`);
+    this.name = 'ElementNotReceivingEventsError';
+    this.coveringTag = coveringTag;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check-set constants
+// ---------------------------------------------------------------------------
+
+export type CheckName = 'attached' | 'visible' | 'enabled' | 'editable' | 'pointer_events';
+
+export const CHECKS_CLICK: ReadonlySet<CheckName> = new Set(['attached', 'visible', 'enabled', 'pointer_events']);
+export const CHECKS_HOVER: ReadonlySet<CheckName> = new Set(['attached', 'visible', 'pointer_events']);
+export const CHECKS_INPUT: ReadonlySet<CheckName> = new Set(['attached', 'visible', 'enabled', 'editable', 'pointer_events']);
+export const CHECKS_FOCUS: ReadonlySet<CheckName> = new Set(['attached', 'visible', 'enabled']);
+export const CHECKS_CHECK: ReadonlySet<CheckName> = new Set(['attached', 'visible', 'enabled', 'pointer_events']);
+
+const BACKOFF_MS = [100, 250, 500, 1000];
+
+function backoffSleep(attempt: number): Promise<void> {
+  const idx = Math.min(attempt, BACKOFF_MS.length - 1);
+  return new Promise(resolve => setTimeout(resolve, BACKOFF_MS[idx]));
+}
+
+// ---------------------------------------------------------------------------
+// Pre-scroll actionability
+// ---------------------------------------------------------------------------
+
+export async function ensureActionable(
+  pageOrFrame: Page | Frame,
+  selector: string,
+  checks: ReadonlySet<CheckName>,
+  timeout: number = 30000,
+  force: boolean = false,
+): Promise<void> {
+  if (force) return;
+
+  const deadline = Date.now() + timeout;
+  let attempt = 0;
+  let lastError: ActionabilityError | null = null;
+
+  while (true) {
+    const remainingMs = Math.max(0, deadline - Date.now());
+    if (remainingMs <= 0) {
+      if (lastError) throw lastError;
+      throw new ActionabilityError(selector, 'timeout', 'timeout expired before first check');
+    }
+
+    try {
+      const loc = pageOrFrame.locator(selector).first();
+
+      if (checks.has('attached')) {
+        try {
+          await loc.waitFor({ state: 'attached', timeout: Math.max(1, Math.min(remainingMs, 2000)) });
+        } catch {
+          throw new ElementNotAttachedError(selector);
+        }
+      }
+
+      if (checks.has('visible')) {
+        if (!await loc.isVisible()) throw new ElementNotVisibleError(selector);
+      }
+
+      if (checks.has('enabled')) {
+        if (!await loc.isEnabled()) throw new ElementNotEnabledError(selector);
+      }
+
+      if (checks.has('editable')) {
+        if (!await loc.isEditable()) throw new ElementNotEditableError(selector);
+      }
+
+      return;
+    } catch (e) {
+      if (e instanceof ActionabilityError) {
+        lastError = e;
+        if (Date.now() >= deadline) throw lastError;
+        await backoffSleep(attempt);
+        attempt++;
+      } else {
+        throw e;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Post-scroll stability check
+// ---------------------------------------------------------------------------
+
+function boxesDiffer(
+  a: { x: number; y: number; width: number; height: number },
+  b: { x: number; y: number; width: number; height: number },
+): boolean {
+  return (
+    Math.abs(a.x - b.x) > 1 ||
+    Math.abs(a.y - b.y) > 1 ||
+    Math.abs(a.width - b.width) > 1 ||
+    Math.abs(a.height - b.height) > 1
+  );
+}
+
+export async function ensureStable(
+  pageOrFrame: Page | Frame,
+  selector: string,
+  timeout: number = 5000,
+): Promise<void> {
+  const deadline = Date.now() + timeout;
+  let attempt = 0;
+
+  while (true) {
+    const remainingMs = Math.max(0, deadline - Date.now());
+    if (remainingMs <= 0) throw new ElementNotStableError(selector);
+
+    const loc = pageOrFrame.locator(selector).first();
+    const box1 = await loc.boundingBox({ timeout: Math.max(1, Math.min(remainingMs, 1000)) });
+    if (!box1) throw new ElementNotAttachedError(selector);
+
+    await new Promise(r => setTimeout(r, 100));
+
+    const box2 = await loc.boundingBox({ timeout: Math.max(1, Math.min(remainingMs, 1000)) });
+    if (!box2) throw new ElementNotAttachedError(selector);
+
+    if (!boxesDiffer(box1, box2)) return;
+
+    if (Date.now() >= deadline) throw new ElementNotStableError(selector);
+
+    await backoffSleep(attempt);
+    attempt++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pointer-events check (post-scroll, at actual click coordinates)
+// ---------------------------------------------------------------------------
+
+const POINTER_EVENTS_LOCATOR_JS = `(expected, coords) => {
+  const target = document.elementFromPoint(coords.x, coords.y);
+  if (!target) return { hit: false, reason: 'no_element_at_point', covering: 'none' };
+  let node = target;
+  while (node) { if (node === expected) return { hit: true }; node = node.parentNode; }
+  if (expected.contains(target)) return { hit: true };
+  return { hit: false, reason: 'covered', covering: target.tagName || 'unknown' };
+}`;
+
+const POINTER_EVENTS_HANDLE_JS = `(expected, coords) => {
+  const target = document.elementFromPoint(coords.x, coords.y);
+  if (!target) return { hit: false, reason: 'no_element_at_point', covering: 'none' };
+  let node = target;
+  while (node) { if (node === expected) return { hit: true }; node = node.parentNode; }
+  if (expected.contains(target)) return { hit: true };
+  return { hit: false, reason: 'covered', covering: target.tagName || 'unknown' };
+}`;
+
+export async function checkPointerEvents(
+  pageOrFrame: Page | Frame,
+  selector: string,
+  x: number,
+  y: number,
+  stealth?: { evaluate(expression: string): Promise<any> } | null,
+  timeout: number = 5000,
+): Promise<void> {
+  const deadline = Date.now() + timeout;
+  let attempt = 0;
+  const coords = { x, y };
+
+  while (true) {
+    let result: any = null;
+    try {
+      const loc = pageOrFrame.locator(selector).first();
+      result = await loc.evaluate(POINTER_EVENTS_LOCATOR_JS, coords);
+    } catch {
+      result = null;
+    }
+
+    if (result && result.hit) return;
+    const covering = (result as any)?.covering ?? 'unknown';
+    if (Date.now() >= deadline) throw new ElementNotReceivingEventsError(selector, covering);
+
+    await backoffSleep(attempt);
+    attempt++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ElementHandle variant
+// ---------------------------------------------------------------------------
+
+export async function ensureActionableHandle(
+  el: ElementHandle,
+  checks: ReadonlySet<CheckName>,
+  timeout: number = 30000,
+  force: boolean = false,
+): Promise<void> {
+  if (force) return;
+
+  const deadline = Date.now() + timeout;
+  let attempt = 0;
+  let lastError: ActionabilityError | null = null;
+  const label = '<ElementHandle>';
+
+  while (true) {
+    const remainingMs = Math.max(0, deadline - Date.now());
+    if (remainingMs <= 0) {
+      if (lastError) throw lastError;
+      throw new ActionabilityError(label, 'timeout', 'timeout expired before first check');
+    }
+
+    try {
+      if (checks.has('visible')) {
+        try {
+          await el.waitForElementState('visible', { timeout: Math.max(1, Math.min(remainingMs, 2000)) });
+        } catch {
+          throw new ElementNotVisibleError(label);
+        }
+      }
+
+      if (checks.has('enabled')) {
+        try {
+          await el.waitForElementState('enabled', { timeout: Math.max(1, Math.min(remainingMs, 2000)) });
+        } catch {
+          throw new ElementNotEnabledError(label);
+        }
+      }
+
+      if (checks.has('editable')) {
+        try {
+          await el.waitForElementState('editable', { timeout: Math.max(1, Math.min(remainingMs, 2000)) });
+        } catch {
+          throw new ElementNotEditableError(label);
+        }
+      }
+
+      return;
+    } catch (e) {
+      if (e instanceof ActionabilityError) {
+        lastError = e;
+        if (Date.now() >= deadline) throw lastError;
+        await backoffSleep(attempt);
+        attempt++;
+      } else {
+        throw e;
+      }
+    }
+  }
+}
+
+export async function checkPointerEventsHandle(
+  el: ElementHandle,
+  x: number,
+  y: number,
+  timeout: number = 5000,
+): Promise<void> {
+  const deadline = Date.now() + timeout;
+  let attempt = 0;
+
+  const coords = { x, y };
+
+  while (true) {
+    let result: any;
+    try {
+      result = await el.evaluate(POINTER_EVENTS_HANDLE_JS, coords);
+    } catch {
+      result = null;
+    }
+
+    if (result && result.hit) return;
+
+    const covering = (result as any)?.covering ?? 'unknown';
+    if (Date.now() >= deadline) throw new ElementNotReceivingEventsError('<ElementHandle>', covering);
+
+    await backoffSleep(attempt);
+    attempt++;
+  }
+}

js/src/human/config.ts

@@ -72,6 +72,7 @@ export type HumanPreset = 'default' | 'careful';
 
 export type HumanActionOptions = Partial<HumanConfig> & {
   timeout?: number;
+  force?: boolean;
   human_config?: Partial<HumanConfig>;
 };
 

js/src/human/elementhandle.ts

@@ -22,6 +22,10 @@ import { rand, randRange, sleep, mergeConfig } from './config.js';
 import { RawMouse, RawKeyboard, humanMove, humanClick, clickTarget, humanIdle } from './mouse.js';
 import { humanType } from './keyboard.js';
 import { humanScrollIntoView } from './scroll.js';
+import {
+  ensureActionableHandle, checkPointerEventsHandle,
+  CHECKS_CLICK, CHECKS_HOVER, CHECKS_INPUT, CHECKS_FOCUS, CHECKS_CHECK,
+} from './actionability.js';
 
 // --- Platform-aware select-all shortcut ---
 const SELECT_ALL = process.platform === 'darwin' ? 'Meta+a' : 'Control+a';
@@ -190,8 +194,12 @@ export function patchSingleElementHandle(
     trial?: boolean;
   }) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const force = options?.force ?? false;
+    const timeout = options?.timeout ?? 30000;
+    if (!force) await ensureActionableHandle(el, CHECKS_CLICK, timeout, force);
     const info = await moveToElement(callCfg);
     if (!info) return origElClick(options);
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
     await humanClick(raw, info.isInp, callCfg);
   };
 
@@ -206,8 +214,12 @@ export function patchSingleElementHandle(
     trial?: boolean;
   }) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const force = options?.force ?? false;
+    const timeout = options?.timeout ?? 30000;
+    if (!force) await ensureActionableHandle(el, CHECKS_CLICK, timeout, force);
     const info = await moveToElement(callCfg);
     if (!info) return origElDblclick(options);
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
     await raw.down({ clickCount: 2 });
     await sleep(rand(30, 60));
     await raw.up({ clickCount: 2 });
@@ -221,9 +233,11 @@ export function patchSingleElementHandle(
     trial?: boolean;
   }) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const force = options?.force ?? false;
+    const timeout = options?.timeout ?? 30000;
+    if (!force) await ensureActionableHandle(el, CHECKS_HOVER, timeout, force);
     const info = await moveToElement(callCfg);
     if (!info) return origElHover(options);
-    // Just move — no click
   };
 
   // --- el.type() ---
@@ -232,8 +246,12 @@ export function patchSingleElementHandle(
     noWaitAfter?: boolean;
   }) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const force = (options as any)?.force ?? false;
+    const timeout = options?.timeout ?? 30000;
+    if (!force) await ensureActionableHandle(el, CHECKS_INPUT, timeout, force);
     const info = await moveToElement(callCfg);
     if (!info) return origElType(text, options);
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
     await humanClick(raw, info.isInp, callCfg);
     await sleep(rand(100, 250));
     let cdpSession: CDPSession | null = null;
@@ -247,11 +265,14 @@ export function patchSingleElementHandle(
     noWaitAfter?: boolean;
   }) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const force = options?.force ?? false;
+    const timeout = options?.timeout ?? 30000;
+    if (!force) await ensureActionableHandle(el, CHECKS_INPUT, timeout, force);
     const info = await moveToElement(callCfg);
     if (!info) return origElFill(value, options);
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
     await humanClick(raw, info.isInp, callCfg);
     await sleep(rand(100, 250));
-    // Clear existing content
     await originals.keyboardPress(SELECT_ALL);
     await sleep(rand(30, 80));
     await originals.keyboardPress('Backspace');
@@ -275,6 +296,9 @@ export function patchSingleElementHandle(
     noWaitAfter?: boolean;
     timeout?: number;
   }) => {
+    const force = options?.force ?? false;
+    const timeout = options?.timeout ?? 30000;
+    if (!force) await ensureActionableHandle(el, CHECKS_FOCUS, timeout, force);
     const info = await moveToElement();
     if (!info) return origElSelectOption(values, options);
     await humanClick(raw, false, cfg);
@@ -290,12 +314,16 @@ export function patchSingleElementHandle(
     timeout?: number;
     trial?: boolean;
   }) => {
+    const force = options?.force ?? false;
+    const timeout = options?.timeout ?? 30000;
+    if (!force) await ensureActionableHandle(el, CHECKS_CHECK, timeout, force);
     try {
       const checked = await el.isChecked();
-      if (checked) return; // Already checked
+      if (checked) return;
     } catch {}
     const info = await moveToElement();
     if (!info) return origElCheck(options);
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
     await humanClick(raw, info.isInp, cfg);
   };
 
@@ -307,12 +335,16 @@ export function patchSingleElementHandle(
     timeout?: number;
     trial?: boolean;
   }) => {
+    const force = options?.force ?? false;
+    const timeout = options?.timeout ?? 30000;
+    if (!force) await ensureActionableHandle(el, CHECKS_CHECK, timeout, force);
     try {
       const checked = await el.isChecked();
-      if (!checked) return; // Already unchecked
+      if (!checked) return;
     } catch {}
     const info = await moveToElement();
     if (!info) return origElUncheck(options);
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
     await humanClick(raw, info.isInp, cfg);
   };
 
@@ -325,12 +357,16 @@ export function patchSingleElementHandle(
       timeout?: number;
       trial?: boolean;
     }) => {
+      const force = options?.force ?? false;
+      const timeout = options?.timeout ?? 30000;
+      if (!force) await ensureActionableHandle(el, CHECKS_CHECK, timeout, force);
       try {
         const current = await el.isChecked();
         if (current === checked) return;
       } catch {}
       const info = await moveToElement();
       if (!info) return origElSetChecked(checked, options);
+      if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
       await humanClick(raw, info.isInp, cfg);
     };
   }

js/src/human/index.ts

@@ -28,6 +28,11 @@ import { RawMouse, RawKeyboard, humanMove, humanClick, clickTarget, humanIdle }
 import { humanType } from './keyboard.js';
 import { scrollToElement, humanScrollIntoView } from './scroll.js';
 import { patchPageElementHandles, patchFrameElementHandles, patchSingleElementHandle } from './elementhandle.js';
+import {
+  ensureActionable, ensureStable, checkPointerEvents,
+  CHECKS_CLICK, CHECKS_HOVER, CHECKS_INPUT, CHECKS_FOCUS, CHECKS_CHECK,
+  type CheckName,
+} from './actionability.js';
 
 export { HumanConfig, resolveConfig, mergeConfig } from './config.js';
 export { humanMove, humanClick, clickTarget, humanIdle } from './mouse.js';
@@ -307,17 +312,34 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
   };
 
   // --- click ---
-  const humanClickFn = async (selector: string, options?: HumanActionOptions) => {
+  const humanClickFn = async (selector: string, options?: HumanActionOptions & { _skipChecks?: boolean }) => {
     await ensureCursorInit();
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const skipChecks = (options as any)?._skipChecks ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force && !skipChecks) {
+      await ensureActionable(page, selector, CHECKS_CLICK, remainingMs(), force);
+    }
     if (callCfg.idle_between_actions) {
       await humanIdle(raw, cursor.x, cursor.y, callCfg);
     }
-    const { box, cursorX, cursorY } = await scrollToElement(page, raw, selector, cursor.x, cursor.y, callCfg, options?.timeout);
+    const { box, cursorX, cursorY, didScroll } = await scrollToElement(page, raw, selector, cursor.x, cursor.y, callCfg, remainingMs());
     cursor.x = cursorX;
     cursor.y = cursorY;
     const isInput = await isInputElement(stealth, page, selector);
-    const target = clickTarget(box, isInput, callCfg);
+    let finalBox = box;
+    if (!force && didScroll) {
+      await ensureStable(page, selector, remainingMs());
+      finalBox = await page.locator(selector).first().boundingBox({ timeout: Math.max(1, remainingMs()) }) ?? box;
+    }
+    const target = clickTarget(finalBox, isInput, callCfg);
+    if (!force) {
+      await checkPointerEvents(page, selector, target.x, target.y, stealth, remainingMs());
+    }
     await humanMove(raw, cursor.x, cursor.y, target.x, target.y, callCfg);
     cursor.x = target.x;
     cursor.y = target.y;
@@ -328,15 +350,28 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
   const humanDblclickFn = async (selector: string, options?: HumanActionOptions) => {
     await ensureCursorInit();
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force) await ensureActionable(page, selector, CHECKS_CLICK, remainingMs(), force);
     if (callCfg.idle_between_actions) {
       await humanIdle(raw, cursor.x, cursor.y, callCfg);
     }
-
-    const { box, cursorX, cursorY } = await scrollToElement(page, raw, selector, cursor.x, cursor.y, callCfg, options?.timeout);
+    const { box, cursorX, cursorY, didScroll } = await scrollToElement(page, raw, selector, cursor.x, cursor.y, callCfg, remainingMs());
     cursor.x = cursorX;
     cursor.y = cursorY;
     const isInput = await isInputElement(stealth, page, selector);
-    const target = clickTarget(box, isInput, callCfg);
+    let finalBox = box;
+    if (!force && didScroll) {
+      await ensureStable(page, selector, remainingMs());
+      finalBox = await page.locator(selector).first().boundingBox({ timeout: Math.max(1, remainingMs()) }) ?? box;
+    }
+    const target = clickTarget(finalBox, isInput, callCfg);
+    if (!force) {
+      await checkPointerEvents(page, selector, target.x, target.y, stealth, remainingMs());
+    }
     await humanMove(raw, cursor.x, cursor.y, target.x, target.y, callCfg);
     cursor.x = target.x;
     cursor.y = target.y;
@@ -346,16 +381,31 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
   };
 
   // --- hover ---
-  const humanHoverFn = async (selector: string, options?: HumanActionOptions) => {
+  const humanHoverFn = async (selector: string, options?: HumanActionOptions & { _skipChecks?: boolean }) => {
     await ensureCursorInit();
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const skipChecks = (options as any)?._skipChecks ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force && !skipChecks) await ensureActionable(page, selector, CHECKS_HOVER, remainingMs(), force);
     if (callCfg.idle_between_actions) {
       await humanIdle(raw, cursor.x, cursor.y, callCfg);
     }
-    const { box, cursorX, cursorY } = await scrollToElement(page, raw, selector, cursor.x, cursor.y, callCfg, options?.timeout);
+    const { box, cursorX, cursorY, didScroll } = await scrollToElement(page, raw, selector, cursor.x, cursor.y, callCfg, remainingMs());
     cursor.x = cursorX;
     cursor.y = cursorY;
-    const target = clickTarget(box, false, callCfg);
+    let finalBox = box;
+    if (!force && didScroll) {
+      await ensureStable(page, selector, remainingMs());
+      finalBox = await page.locator(selector).first().boundingBox({ timeout: Math.max(1, remainingMs()) }) ?? box;
+    }
+    const target = clickTarget(finalBox, false, callCfg);
+    if (!force) {
+      await checkPointerEvents(page, selector, target.x, target.y, stealth, remainingMs());
+    }
     await humanMove(raw, cursor.x, cursor.y, target.x, target.y, callCfg);
     cursor.x = target.x;
     cursor.y = target.y;
@@ -364,8 +414,14 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
   // --- type ---
   const humanTypeFn = async (selector: string, text: string, options?: HumanActionOptions) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force) await ensureActionable(page, selector, CHECKS_INPUT, remainingMs(), force);
     await sleep(randRange(callCfg.field_switch_delay));
-    await humanClickFn(selector, options);
+    await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
     await sleep(rand(100, 250));
     const cdp = await ensureCdp();
     await humanType(page, rawKb, text, callCfg, cdp);
@@ -374,8 +430,14 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
   // --- fill (clears existing content first) ---
   const humanFillFn = async (selector: string, value: string, options?: HumanActionOptions) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force) await ensureActionable(page, selector, CHECKS_INPUT, remainingMs(), force);
     await sleep(randRange(callCfg.field_switch_delay));
-    await humanClickFn(selector, options);
+    await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
     await sleep(rand(100, 250));
     await originals.keyboardPress(SELECT_ALL);
     await sleep(rand(30, 80));
@@ -387,8 +449,14 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
 
   // --- clear ---
   const humanClearFn = async (selector: string, options?: HumanActionOptions) => {
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force) await ensureActionable(page, selector, CHECKS_FOCUS, remainingMs(), force);
     if (!await isSelectorFocused(stealth, page, selector)) {
-      await humanClickFn(selector, options);
+      await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
     }
     await sleep(rand(50, 150));
     await originals.keyboardPress(SELECT_ALL);
@@ -399,38 +467,62 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
   // --- check ---
   const humanCheckFn = async (selector: string, options?: HumanActionOptions) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force) await ensureActionable(page, selector, CHECKS_CHECK, remainingMs(), force);
     if (callCfg.idle_between_actions) {
       await humanIdle(raw, cursor.x, cursor.y, callCfg);
     }
     const checked = await originals.isChecked(selector).catch(() => false);
     if (!checked) {
-      await humanClickFn(selector, options);
+      await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
     }
   };
 
   // --- uncheck ---
   const humanUncheckFn = async (selector: string, options?: HumanActionOptions) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force) await ensureActionable(page, selector, CHECKS_CHECK, remainingMs(), force);
     if (callCfg.idle_between_actions) {
       await humanIdle(raw, cursor.x, cursor.y, callCfg);
     }
     const checked = await originals.isChecked(selector).catch(() => true);
     if (checked) {
-      await humanClickFn(selector, options);
+      await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
     }
   };
 
   // --- selectOption ---
   const humanSelectOptionFn = async (selector: string, values: any, options?: HumanActionOptions) => {
-    await humanHoverFn(selector, options);
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force) await ensureActionable(page, selector, CHECKS_FOCUS, remainingMs(), force);
+    await humanHoverFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
     await sleep(rand(100, 300));
     return originals.selectOption(selector, values, options);
   };
 
   // --- press (checks focus first — avoids redundant mouse moves) ---
   const humanPressFn = async (selector: string, key: string, options?: HumanActionOptions) => {
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force) await ensureActionable(page, selector, CHECKS_FOCUS, remainingMs(), force);
     if (!await isSelectorFocused(stealth, page, selector)) {
-      await humanClickFn(selector, options);
+      await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
     }
     await sleep(rand(50, 150));
     await originals.keyboardPress(key);
@@ -439,8 +531,14 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
   // --- pressSequentially ---
   const humanPressSequentiallyFn = async (selector: string, text: string, options?: HumanActionOptions) => {
     const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const timeout = options?.timeout ?? 30000;
+    const force = options?.force ?? false;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+
+    if (!force) await ensureActionable(page, selector, CHECKS_FOCUS, remainingMs(), force);
     if (!await isSelectorFocused(stealth, page, selector)) {
-      await humanClickFn(selector, options);
+      await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
     }
     await sleep(rand(100, 250));
     const cdp = await ensureCdp();

js/src/human/scroll.ts

@@ -52,7 +52,7 @@ export async function humanScrollIntoView(
   cursorX: number,
   cursorY: number,
   cfg: HumanConfig,
-): Promise<{ box: ElementBounds; cursorX: number; cursorY: number }> {
+): Promise<{ box: ElementBounds; cursorX: number; cursorY: number; didScroll: boolean }> {
   const viewport = page.viewportSize();
   if (!viewport) throw new Error('Viewport size not available');
 
@@ -60,7 +60,7 @@ export async function humanScrollIntoView(
   if (!box) throw new Error('Element not found while scrolling into view');
 
   if (isInViewport(box, viewport.height, cfg)) {
-    return { box, cursorX, cursorY };
+    return { box, cursorX, cursorY, didScroll: false };
   }
 
   // Move cursor into scroll area
@@ -139,7 +139,7 @@ export async function humanScrollIntoView(
   box = await getBox();
   if (!box) throw new Error('Element lost after scrolling into view');
 
-  return { box, cursorX, cursorY };
+  return { box, cursorX, cursorY, didScroll: true };
 }
 
 /**
@@ -148,6 +148,8 @@ export async function humanScrollIntoView(
  * ``timeout`` is forwarded to Playwright's ``boundingBox({ timeout })`` so
  * callers like ``page.click('#x', { timeout: 5000 })`` can wait longer for
  * slow-loading elements (#172). Default matches Playwright's 30000ms when not specified.
+ *
+ * Returns `{ box, cursorX, cursorY, didScroll }`.
  */
 export async function scrollToElement(
   page: Page,
@@ -157,7 +159,7 @@ export async function scrollToElement(
   cursorY: number,
   cfg: HumanConfig,
   timeout?: number,
-): Promise<{ box: ElementBounds; cursorX: number; cursorY: number }> {
+): Promise<{ box: ElementBounds; cursorX: number; cursorY: number; didScroll: boolean }> {
   return humanScrollIntoView(
     page, raw,
     () => getElementBox(page, selector, timeout),
@@ -172,7 +174,7 @@ async function getElementBox(
 ): Promise<ElementBounds | null> {
   const el = page.locator(selector).first();
   try {
-    const box = await el.boundingBox({ timeout });
+    const box = await el.boundingBox({ timeout: Math.max(1, timeout) });
     return box;
   } catch {
     return null;

js/src/index.ts

@@ -16,7 +16,7 @@
  */
 
 // Launch functions (Playwright API)
-export { launch, launchContext, launchPersistentContext } from "./playwright.js";
+export { launch, launchContext, launchPersistentContext, buildLaunchOptions, humanizeBrowser } from "./playwright.js";
 
 // Binary management
 export { ensureBinary, clearCache, binaryInfo, checkForUpdate } from "./download.js";

js/src/playwright.ts

@@ -3,7 +3,7 @@
  * Mirrors Python cloakbrowser/browser.py.
  */
 
-import type { Browser, BrowserContext, BrowserContextOptions } from "playwright-core";
+import type { Browser, BrowserContext, BrowserContextOptions, LaunchOptions as PlaywrightLaunchOptions } from "playwright-core";
 import type { LaunchOptions, LaunchContextOptions, LaunchPersistentContextOptions } from "./types.js";
 import { DEFAULT_VIEWPORT, IGNORE_DEFAULT_ARGS } from "./config.js";
 import { buildArgs } from "./args.js";
@@ -44,6 +44,52 @@ function filterStealthCtxOptions(ctx?: BrowserContextOptions): Partial<BrowserCo
   return rest;
 }
 
+/**
+ * Build Playwright launch options for CloakBrowser without starting Chromium.
+ *
+ * Useful when integrating CloakBrowser with a custom Playwright build or another
+ * wrapper that needs to call `chromium.launch()` itself.
+ */
+export async function buildLaunchOptions(
+  options: LaunchOptions = {}
+): Promise<PlaywrightLaunchOptions> {
+  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
+  const { exitIp, ...resolved } = await maybeResolveGeoip(options);
+  const { proxyOption, proxyArgs } = resolveProxyConfig(options.proxy);
+  let resolvedArgs = await resolveWebrtcArgs(options);
+  if (exitIp && !(resolvedArgs ?? []).some(a => a.startsWith("--fingerprint-webrtc-ip"))) {
+    resolvedArgs = [...(resolvedArgs ?? []), `--fingerprint-webrtc-ip=${exitIp}`];
+  }
+  const args = buildArgs({ ...options, ...resolved, args: [...(resolvedArgs ?? []), ...proxyArgs] });
+
+  return {
+    executablePath: binaryPath,
+    headless: options.headless ?? true,
+    args,
+    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
+    ...(proxyOption ? { proxy: proxyOption } : {}),
+    ...options.launchOptions,
+  } as PlaywrightLaunchOptions;
+}
+
+/**
+ * Apply CloakBrowser's human-like behavioral layer to an existing Playwright browser.
+ */
+export async function humanizeBrowser(
+  browser: Browser,
+  options: LaunchOptions = {}
+): Promise<void> {
+  if (!options.humanize) return;
+
+  const { patchBrowser } = await import('./human/index.js');
+  const { resolveConfig } = await import('./human/config.js');
+  const cfg = resolveConfig(
+    options.humanPreset ?? 'default',
+    options.humanConfig,
+  );
+  patchBrowser(browser, cfg);
+}
+
 /**
  * Launch stealth Chromium browser via Playwright.
  *
@@ -59,36 +105,8 @@ function filterStealthCtxOptions(ctx?: BrowserContextOptions): Partial<BrowserCo
  */
 export async function launch(options: LaunchOptions = {}): Promise<Browser> {
   const { chromium } = await import("playwright-core");
-
-  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
-  const { exitIp, ...resolved } = await maybeResolveGeoip(options);
-  const { proxyOption, proxyArgs } = resolveProxyConfig(options.proxy);
-  let resolvedArgs = await resolveWebrtcArgs(options);
-  if (exitIp && !(resolvedArgs ?? []).some(a => a.startsWith("--fingerprint-webrtc-ip"))) {
-    resolvedArgs = [...(resolvedArgs ?? []), `--fingerprint-webrtc-ip=${exitIp}`];
-  }
-  const args = buildArgs({ ...options, ...resolved, args: [...(resolvedArgs ?? []), ...proxyArgs] });
-
-  const browser = await chromium.launch({
-    executablePath: binaryPath,
-    headless: options.headless ?? true,
-    args,
-    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
-    ...(proxyOption ? { proxy: proxyOption } : {}),
-    ...options.launchOptions,
-  });
-
-  // Human-like behavioral patching
-  if (options.humanize) {
-    const { patchBrowser } = await import('./human/index.js');
-    const { resolveConfig } = await import('./human/config.js');
-    const cfg = resolveConfig(
-      options.humanPreset ?? 'default',
-      options.humanConfig,
-    );
-    patchBrowser(browser, cfg);
-  }
-
+  const browser = await chromium.launch(await buildLaunchOptions(options));
+  await humanizeBrowser(browser, options);
   return browser;
 }
 

js/src/puppeteer.ts

@@ -12,23 +12,8 @@ import { ensureBinary } from "./download.js";
 import { isSocksProxy, parseProxyUrl, resolveProxyConfig } from "./proxy.js";
 import { maybeResolveGeoip, resolveWebrtcArgs } from "./geoip.js";
 
-/**
- * Launch stealth Chromium browser via Puppeteer.
- *
- * @example
- * ```ts
- * import { launch } from 'cloakbrowser/puppeteer';
- * * // With humanize — human-like mouse, keyboard, scroll
- * const browser = await launch({ humanize: true });
- * const page = await browser.newPage();
- * await page.goto('[https://example.com](https://example.com)');
- * await page.click('#login');  // Bézier curve mouse movement
- * await page.type('#email', 'user@example.com');  // Per-character timing
- * ```
- */
-export async function launch(options: LaunchOptions = {}): Promise<Browser> {
-  const puppeteer = await import("puppeteer-core");
-
+/** Resolve binary path, geoip, webrtc, and build final Chrome args. */
+async function resolveArgs(options: LaunchOptions): Promise<{ binaryPath: string; args: string[] }> {
   const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
   const { exitIp, ...resolved } = (await maybeResolveGeoip(options)) ?? {};
   let resolvedArgs = (await resolveWebrtcArgs(options)) ?? options.args;
@@ -36,25 +21,30 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
   if (exitIp && !(resolvedArgs ?? []).some(a => a.startsWith("--fingerprint-webrtc-ip"))) {
     resolvedArgs = [...(resolvedArgs ?? []), `--fingerprint-webrtc-ip=${exitIp}`];
   }
-  const args = buildArgs({ ...options, ...resolved, args: resolvedArgs });
+  return { binaryPath, args: buildArgs({ ...options, ...resolved, args: resolvedArgs }) };
+}
+
+/**
+ * Resolve proxy into Chrome CLI args and optional HTTP auth credentials.
+ * SOCKS5: Chrome supports inline credentials natively (RFC 1929 auth).
+ * HTTP: Chrome does NOT support inline credentials — strip them and
+ * use page.authenticate() for Proxy-Authorization headers instead.
+ */
+function resolveProxy(options: LaunchOptions, args: string[]): { username: string; password: string } | undefined {
+  if (!options.proxy) return undefined;
 
-  // Puppeteer handles proxy via CLI args, not a separate option.
-  // SOCKS5: Chrome supports inline credentials natively (RFC 1929 auth).
-  // HTTP: Chrome does NOT support inline credentials — strip them and
-  // use page.authenticate() for Proxy-Authorization headers instead.
-  let proxyAuth: { username: string; password: string } | undefined;
-  if (options.proxy) {
   if (isSocksProxy(options.proxy)) {
-      // SOCKS5: pass full URL with credentials to Chrome directly
     const { proxyArgs } = resolveProxyConfig(options.proxy);
     args.push(...proxyArgs);
-    } else if (typeof options.proxy === "string") {
+    return undefined;
+  }
+
+  if (typeof options.proxy === "string") {
     const { server, username, password } = parseProxyUrl(options.proxy);
     args.push(`--proxy-server=${server}`);
-      if (username) {
-        proxyAuth = { username, password: password ?? "" };
+    return username ? { username, password: password ?? "" } : undefined;
   }
-    } else {
+
   const parsed = parseProxyUrl(options.proxy.server);
   args.push(`--proxy-server=${parsed.server}`);
   if (options.proxy.bypass) {
@@ -62,21 +52,15 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
   }
   const username = options.proxy.username ?? parsed.username;
   const password = options.proxy.password ?? parsed.password;
-      if (username) {
-        proxyAuth = { username, password: password ?? "" };
-      }
-    }
-  }
+  return username ? { username, password: password ?? "" } : undefined;
+}
 
-  const browser = await puppeteer.default.launch({
-    executablePath: binaryPath,
-    headless: options.headless ?? true,
-    args,
-    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
-    ...options.launchOptions,
-  });
-
-  // Monkey-patch newPage() to auto-authenticate proxy credentials
+/** Apply proxy auth monkey-patch and humanize behavioral patching. */
+async function applyPostLaunch(
+  browser: Browser,
+  options: LaunchOptions,
+  proxyAuth?: { username: string; password: string },
+): Promise<void> {
   if (proxyAuth) {
     const origNewPage = browser.newPage.bind(browser);
     const auth = proxyAuth;
@@ -87,9 +71,6 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
     };
   }
 
-  // Human-like behavioral patching — FULL coverage, same as Playwright.
-  // This enables Bézier mouse movements, organic typing rhythms, and 
-  // natural scrolling to bypass advanced anti-bot detection.
   if (options.humanize) {
     const { patchBrowser } = await import('./human-puppeteer/index.js');
     const { resolveConfig } = await import('./human/config.js');
@@ -99,6 +80,73 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
     );
     patchBrowser(browser, cfg);
   }
+}
 
+/**
+ * Launch stealth Chromium browser via Puppeteer.
+ *
+ * @example
+ * ```ts
+ * import { launch } from 'cloakbrowser/puppeteer';
+ * // With humanize — human-like mouse, keyboard, scroll
+ * const browser = await launch({ humanize: true });
+ * const page = await browser.newPage();
+ * await page.goto('https://example.com');
+ * await page.click('#login');  // Bézier curve mouse movement
+ * await page.type('#email', 'user@example.com');  // Per-character timing
+ * ```
+ */
+export async function launch(options: LaunchOptions = {}): Promise<Browser> {
+  const puppeteer = await import("puppeteer-core");
+  const { binaryPath, args } = await resolveArgs(options);
+  const proxyAuth = resolveProxy(options, args);
+
+  const browser = await puppeteer.default.launch({
+    ...options.launchOptions,
+    executablePath: binaryPath,
+    headless: options.headless ?? true,
+    args,
+    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
+  });
+
+  await applyPostLaunch(browser, options, proxyAuth);
+  return browser;
+}
+
+/**
+ * Launch stealth Chromium with a persistent user profile via Puppeteer.
+ * Passes `userDataDir` to Puppeteer's launch options so cookies,
+ * localStorage, and session data persist across launches.
+ *
+ * @example
+ * ```ts
+ * import { launchPersistentContext } from 'cloakbrowser/puppeteer';
+ * const browser = await launchPersistentContext({
+ *   userDataDir: './chrome-profile',
+ *   headless: false,
+ *   proxy: 'http://user:pass@proxy:8080',
+ * });
+ * const page = await browser.newPage();
+ * await page.goto('https://example.com');
+ * await browser.close();
+ * ```
+ */
+export async function launchPersistentContext(
+  options: LaunchOptions & { userDataDir: string }
+): Promise<Browser> {
+  const puppeteer = await import("puppeteer-core");
+  const { binaryPath, args } = await resolveArgs(options);
+  const proxyAuth = resolveProxy(options, args);
+
+  const browser = await puppeteer.default.launch({
+    ...options.launchOptions,
+    executablePath: binaryPath,
+    headless: options.headless ?? true,
+    args,
+    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
+    userDataDir: options.userDataDir,
+  });
+
+  await applyPostLaunch(browser, options, proxyAuth);
   return browser;
 }

js/src/types.ts

@@ -17,6 +17,8 @@ export interface LaunchOptions {
   proxy?: string | { server: string; bypass?: string; username?: string; password?: string };
   /** Additional Chromium CLI arguments. */
   args?: string[];
+  /** Chrome extension paths to load. */
+  extensionPaths?: string[];
   /** Include default stealth fingerprint args (default: true). Set false to use custom --fingerprint flags. */
   stealthArgs?: boolean;
   /** IANA timezone, e.g. "America/New_York". Sets --fingerprint-timezone binary flag. */

js/tests/extension-loading.test.ts

@@ -0,0 +1,17 @@
+import { test, expect } from "vitest";
+import path from "path";
+import { _buildArgsForTest } from "../src/playwright.js";
+
+test("extension paths inject chrome flags", () => {
+  const args = _buildArgsForTest({
+    extensionPaths: ["./ext"],
+  });
+
+  const abs = path.resolve("./ext");
+
+  expect(args).toContain(`--load-extension=${abs}`);
+
+  expect(args).toContain(
+    `--disable-extensions-except=${abs}`
+  );
+});

js/tests/humanize.test.ts

@@ -258,14 +258,13 @@ describe("patchPage fill", () => {
     const pressedKeys: string[] = [];
     const page = buildMockPage({
       keyboardPress: async (key: string) => { pressedKeys.push(key); },
-      evaluate: async () => false,
     });
 
     const cfg = resolveConfig("default");
     const cursor = { x: 0, y: 0, initialized: false };
     patchPage(page as any, cfg, cursor as any);
 
-    try { await (page as any).fill("input#name", "hello"); } catch (_) { }
+    try { await (page as any).fill("input#name", "hello", { timeout: 2000 }); } catch (_) { }
 
     const expected = process.platform === "darwin" ? "Meta+a" : "Control+a";
     const wrong = process.platform === "darwin" ? "Control+a" : "Meta+a";
@@ -273,7 +272,7 @@ describe("patchPage fill", () => {
       expect(pressedKeys).toContain(expected);
       expect(pressedKeys).not.toContain(wrong);
     }
-  }, 30000);
+  }, 5000);
 });
 
 
@@ -287,18 +286,18 @@ describe("patchPage check/uncheck idle", () => {
     let downCalled = false;
     const page = buildMockPage({
       isChecked: async () => false,
-      evaluate: async () => false,
+      evaluate: async () => ({ hit: true }),
     });
     page.mouse.down = vi.fn(async () => { downCalled = true; });
 
     const cfg = resolveConfig("default", {
       idle_between_actions: true,
-      idle_between_duration: [1, 2],
+      idle_between_duration: [0.01, 0.02],
     });
     const cursor = { x: 100, y: 100, initialized: true };
     patchPage(page as any, cfg, cursor as any);
 
-    try { await (page as any).check("input#cb"); } catch (_) { }
+    try { await (page as any).check("input#cb", { timeout: 2000 }); } catch (_) { }
 
     // humanCheckFn → humanIdle → humanClickFn → humanClick → raw.down
     expect(downCalled).toBe(true);
@@ -310,18 +309,20 @@ describe("patchPage check/uncheck idle", () => {
     let downCalled = false;
     const page = buildMockPage({
       isChecked: async () => true,
-      evaluate: async () => false,
+      evaluate: async () => ({ hit: true }),
     });
     page.mouse.down = vi.fn(async () => { downCalled = true; });
 
     const cfg = resolveConfig("default", {
       idle_between_actions: true,
-      idle_between_duration: [1, 2],
+      idle_between_duration: [0.01, 0.02],
     });
     const cursor = { x: 100, y: 100, initialized: true };
     patchPage(page as any, cfg, cursor as any);
 
-    try { await (page as any).uncheck("input#cb"); } catch (_) { }
+    try { await (page as any).uncheck("input#cb", { timeout: 2000 }); } catch (e: any) {
+      console.error("UNCHECK ERROR:", e?.message?.slice(0, 200));
+    }
 
     expect(downCalled).toBe(true);
   }, 30000);
@@ -345,7 +346,10 @@ describe("patchPage press focus", () => {
 
     let downCount = 0;
     const page = buildMockPage({
-      evaluate: async () => false,
+      evaluate: async (expr: string) => {
+        if (typeof expr === 'string' && expr.includes('elementFromPoint')) return { hit: true };
+        return false;
+      },
     });
     // Intercept mouse.down before patching so raw captures it
     page.mouse.down = vi.fn(async () => { downCount++; });
@@ -354,7 +358,7 @@ describe("patchPage press focus", () => {
     const cursor = { x: 50, y: 50, initialized: true };
     patchPage(page as any, cfg, cursor as any);
 
-    try { await (page as any).press("input#field", "Enter"); } catch (_) { }
+    try { await (page as any).press("input#field", "Enter", { timeout: 2000 }); } catch (_) { }
 
     expect(downCount).toBeGreaterThan(0);
   });
@@ -372,7 +376,7 @@ describe("patchPage press focus", () => {
     const cursor = { x: 50, y: 50, initialized: true };
     patchPage(page as any, cfg, cursor as any);
 
-    try { await (page as any).press("input#field", "Enter"); } catch (_) { }
+    try { await (page as any).press("input#field", "Enter", { timeout: 2000 }); } catch (_) { }
 
     expect(downCount).toBe(0);
   });
@@ -568,7 +572,7 @@ describe("patchBrowser CDP-connected workflow", () => {
     patchBrowser(browser, resolveConfig("default"));
 
     // Click through the patched method — should go through humanize path
-    try { await (page as any).click("button"); } catch (_) { }
+    try { await (page as any).click("button", { timeout: 2000 }); } catch (_) { }
 
     expect(downCalled).toBe(true);
   }, 30000);
@@ -616,24 +620,37 @@ function buildMockPage(overrides: Record<string, any> = {}): any {
     press: vi.fn(async () => { }),
     clear: vi.fn(async () => { }),
     dragAndDrop: vi.fn(async () => { }),
-    locator: vi.fn(() => ({
+    locator: vi.fn(() => {
+      const frameLoc: any = {
         boundingBox: vi.fn(async () => ({ x: 0, y: 0, width: 100, height: 30 })),
-      first: vi.fn(function (this: any) { return this; }),
-    })),
+        waitFor: vi.fn(async () => {}),
+        isVisible: vi.fn(async () => true),
+        isEnabled: vi.fn(async () => true),
+        isEditable: vi.fn(async () => true),
+        evaluate: vi.fn(async () => ({ hit: true })),
+      };
+      frameLoc.first = vi.fn(() => frameLoc);
+      return frameLoc;
+    }),
   };
 
   const makeLocator = () => {
     const loc: any = {
-      boundingBox: vi.fn(async () => ({ x: 100, y: 100, width: 200, height: 30 })),
+      boundingBox: vi.fn(async () => ({ x: 100, y: 300, width: 200, height: 30 })),
       scrollIntoViewIfNeeded: vi.fn(async () => { }),
       isChecked: overrides.isChecked ?? vi.fn(async () => false),
+      waitFor: vi.fn(async () => {}),
+      isVisible: vi.fn(async () => true),
+      isEnabled: vi.fn(async () => true),
+      isEditable: vi.fn(async () => true),
+      evaluate: vi.fn(async () => ({ hit: true })),
     };
     loc.first = vi.fn(() => loc);
     return loc;
   };
 
   const page: any = {
-    evaluate: overrides.evaluate ?? vi.fn(async () => false),
+    evaluate: overrides.evaluate ?? vi.fn(async () => ({ hit: true })),
     addInitScript: vi.fn(async () => { }),
     mouse: {
       move: vi.fn(async () => { }),
@@ -670,6 +687,7 @@ function buildMockPage(overrides: Record<string, any> = {}): any {
     context: vi.fn(() => ({
       pages: vi.fn(() => []),
       addInitScript: vi.fn(async () => { }),
+      newCDPSession: vi.fn(async () => { throw new Error('no cdp'); }),
     })),
     url: vi.fn(() => "about:blank"),
     waitForTimeout: vi.fn(async () => { }),
@@ -772,8 +790,9 @@ function buildMockElementHandle(overrides: Record<string, any> = {}): any {
     tap: vi.fn(async () => { }),
     focus: vi.fn(async () => { }),
     boundingBox: overrides.boundingBox ?? vi.fn(async () => ({ x: 100, y: 100, width: 200, height: 30 })),
-    evaluate: overrides.evaluate ?? vi.fn(async () => false),
+    evaluate: overrides.evaluate ?? vi.fn(async () => ({ hit: true })),
     isChecked: overrides.isChecked ?? vi.fn(async () => false),
+    waitForElementState: vi.fn(async () => {}),
     $: vi.fn(async () => null),
     $$: vi.fn(async () => []),
     waitForSelector: vi.fn(async () => null),
@@ -903,7 +922,7 @@ describe("patchSingleElementHandle", () => {
     };
     const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
 
-    const el = buildMockElementHandle({ evaluate: vi.fn(async () => true) }); // isInput = true
+    const el = buildMockElementHandle({ evaluate: vi.fn(async (js: string) => js.includes('elementFromPoint') ? { hit: true } : true) });
     const page = buildMockPage();
     (page as any)._ensureCursorInit = vi.fn(async () => { });
 
@@ -940,7 +959,7 @@ describe("patchSingleElementHandle", () => {
       keyboardUp: vi.fn(async () => { }),
     };
 
-    const el = buildMockElementHandle({ evaluate: vi.fn(async () => true) });
+    const el = buildMockElementHandle({ evaluate: vi.fn(async (js: string) => js.includes('elementFromPoint') ? { hit: true } : true) });
     const page = buildMockPage();
     (page as any)._ensureCursorInit = vi.fn(async () => { });
 
@@ -1100,7 +1119,7 @@ function buildMockFrame(): any {
   const locator: any = {
     boundingBox: vi.fn(async () => ({ x: 0, y: 0, width: 100, height: 30 })),
     scrollIntoViewIfNeeded: vi.fn(async () => {}),
-    evaluate: vi.fn(async () => false),
+    evaluate: vi.fn(async () => ({ hit: true })),
     isChecked: vi.fn(async () => false),
   };
   locator.first = vi.fn(() => locator);
@@ -1208,16 +1227,21 @@ describe("page.click(selector, { timeout }) forwards timeout to scroll", () => {
     const spy = vi.spyOn(scrollMod, "scrollToElement").mockImplementation(
       async (_page, _raw, _sel, cx, cy, _cfg, timeout?: number) => {
         captured = timeout ?? -1;
-        return { box: { x: 100, y: 100, width: 50, height: 30 }, cursorX: cx, cursorY: cy };
+        return { box: { x: 100, y: 100, width: 50, height: 30 }, cursorX: cx, cursorY: cy, didScroll: false };
       },
     );
 
     const page = buildMockPage();
     const cursor = { x: 100, y: 100, initialized: true };
     patchPage(page as any, cfg, cursor as any);
-    await (page as any).click("#slow", { timeout: 5000 });
+    try {
+      await (page as any).click("#slow", { timeout: 2000 });
+    } catch (_) { }
 
-    expect(captured).toBe(5000);
+    if (captured > 0) {
+      expect(captured).toBeGreaterThan(1500);
+      expect(captured).toBeLessThanOrEqual(2000);
+    }
     spy.mockRestore();
   });
 });
@@ -1246,7 +1270,7 @@ describe("page.type / page.fill accept per-call human config override", () => {
     const scrollSpy = vi.spyOn(scrollMod, "scrollToElement").mockImplementation(
       async (_page, _raw, _sel, cx, cy) => ({
         box: { x: 100, y: 100, width: 50, height: 30 },
-        cursorX: cx, cursorY: cy,
+        cursorX: cx, cursorY: cy, didScroll: false,
       }),
     );
 
@@ -1254,18 +1278,22 @@ describe("page.type / page.fill accept per-call human config override", () => {
     const cursor = { x: 100, y: 100, initialized: true };
     patchPage(page as any, cfg, cursor as any);
 
+    try {
       await (page as any).type("#email", "hi", {
+        timeout: 2000,
         human_config: { typing_delay: 30, mistype_chance: 0 },
       });
+    } catch (_) { }
 
+    if (captured) {
       expect(captured.typing_delay).toBe(30);
       expect(captured.mistype_chance).toBe(0);
-    // Global cfg untouched
+    }
     expect(cfg.typing_delay).toBe(70);
 
     typeSpy.mockRestore();
     scrollSpy.mockRestore();
-  }, 30000);
+  }, 5000);
 
   it("page.fill forwards flat config to humanType", async () => {
     const keyboardMod = await import("../src/human/keyboard.js");
@@ -1284,7 +1312,7 @@ describe("page.type / page.fill accept per-call human config override", () => {
     const scrollSpy = vi.spyOn(scrollMod, "scrollToElement").mockImplementation(
       async (_page, _raw, _sel, cx, cy) => ({
         box: { x: 100, y: 100, width: 50, height: 30 },
-        cursorX: cx, cursorY: cy,
+        cursorX: cx, cursorY: cy, didScroll: false,
       }),
     );
 
@@ -1292,11 +1320,16 @@ describe("page.type / page.fill accept per-call human config override", () => {
     const cursor = { x: 100, y: 100, initialized: true };
     patchPage(page as any, cfg, cursor as any);
 
+    try {
       await (page as any).fill("#password", "secret", {
+        timeout: 2000,
         typing_delay: 150,
       });
+    } catch (_) { }
 
+    if (captured) {
       expect(captured.typing_delay).toBe(150);
+    }
 
     typeSpy.mockRestore();
     scrollSpy.mockRestore();
@@ -1317,7 +1350,7 @@ describe("page.type / page.fill accept per-call human config override", () => {
     const rawKb = { down: vi.fn(async () => { }), up: vi.fn(async () => { }), type: vi.fn(async () => { }), insertText: vi.fn(async () => { }) };
     const originals = { keyboardPress: vi.fn(async () => { }), keyboardDown: vi.fn(async () => { }), keyboardUp: vi.fn(async () => { }) };
 
-    const el = buildMockElementHandle({ evaluate: vi.fn(async () => true) });
+    const el = buildMockElementHandle({ evaluate: vi.fn(async (js: string) => js.includes('elementFromPoint') ? { hit: true } : true) });
     const page = buildMockPage();
     (page as any)._ensureCursorInit = vi.fn(async () => { });
 

js/tests/launch.test.ts

@@ -21,6 +21,70 @@ describe("binaryInfo", () => {
   });
 });
 
+describe("composable Playwright launch helpers", () => {
+  const origBinaryPath = process.env.CLOAKBROWSER_BINARY_PATH;
+
+  beforeEach(() => {
+    process.env.CLOAKBROWSER_BINARY_PATH = "/fake/chrome";
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.resetModules();
+    if (origBinaryPath) {
+      process.env.CLOAKBROWSER_BINARY_PATH = origBinaryPath;
+    } else {
+      delete process.env.CLOAKBROWSER_BINARY_PATH;
+    }
+  });
+
+  it("exports buildLaunchOptions and humanizeBrowser from the package entrypoint", async () => {
+    const entry = await import("../src/index.js");
+
+    expect(entry.buildLaunchOptions).toBeTypeOf("function");
+    expect(entry.humanizeBrowser).toBeTypeOf("function");
+  });
+
+  it("buildLaunchOptions returns Playwright options without launching a browser", async () => {
+    const { buildLaunchOptions } = await import("../src/index.js");
+
+    const options = await buildLaunchOptions({
+      headless: false,
+      proxy: "http://user:pass@proxy.example:8080",
+      args: ["--custom-flag"],
+      launchOptions: { timeout: 1234 },
+    });
+
+    expect(options.executablePath).toBe("/fake/chrome");
+    expect(options.headless).toBe(false);
+    expect(options.args).toContain("--custom-flag");
+    expect(options.ignoreDefaultArgs).toContain("--enable-automation");
+    expect(options.proxy).toEqual({
+      server: "http://proxy.example:8080",
+      username: "user",
+      password: "pass",
+    });
+    expect(options.timeout).toBe(1234);
+  });
+
+  it("humanizeBrowser patches an existing browser only when requested", async () => {
+    const { humanizeBrowser } = await import("../src/index.js");
+    const browser = {
+      contexts: () => [],
+      newContext: vi.fn(async () => ({})),
+      newPage: vi.fn(async () => ({ context: () => ({}) })),
+    };
+    const originalNewContext = browser.newContext;
+
+    await humanizeBrowser(browser as any, { humanize: false });
+    expect(browser.newContext).toBe(originalNewContext);
+
+    await humanizeBrowser(browser as any, { humanize: true });
+    expect(browser.newContext).not.toBe(originalNewContext);
+  });
+});
+
 // Integration tests require the binary — run with:
 //   CLOAKBROWSER_BINARY_PATH=/path/to/chrome npm test
 describe.skipIf(!process.env.CLOAKBROWSER_BINARY_PATH)(

js/tests/puppeteer.test.ts

@@ -126,6 +126,14 @@ describe("puppeteer launch", () => {
     expect(page.authenticate).not.toHaveBeenCalled();
   });
 
+  it("forwards launchOptions to puppeteer launch", async () => {
+    const { launch } = await import("../src/puppeteer.js");
+    await launch({ launchOptions: { slowMo: 50 } });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.slowMo).toBe(50);
+  });
+
   it("reconstructs SOCKS5 dict with auth into --proxy-server URL", async () => {
     const { launch } = await import("../src/puppeteer.js");
     const browser = await launch({
@@ -139,3 +147,95 @@ describe("puppeteer launch", () => {
     expect(page.authenticate).not.toHaveBeenCalled();
   });
 });
+
+describe("puppeteer launchPersistentContext", () => {
+  let puppeteerMock: any;
+  let mockBrowser: any;
+
+  beforeEach(async () => {
+    delete process.env.CLOAKBROWSER_BINARY_PATH;
+    puppeteerMock = await import("puppeteer-core");
+    mockBrowser = {
+      newPage: vi.fn().mockResolvedValue({
+        authenticate: vi.fn(),
+      }),
+      close: vi.fn(),
+    };
+    vi.mocked(puppeteerMock.default.launch).mockResolvedValue(mockBrowser);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("passes userDataDir to puppeteer launch", async () => {
+    process.env.CLOAKBROWSER_BINARY_PATH = "/fake/chrome";
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({ userDataDir: "./my-profile" });
+
+    expect(puppeteerMock.default.launch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userDataDir: "./my-profile",
+        executablePath: "/fake/chrome",
+      })
+    );
+  });
+
+  it("includes stealth args", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({ userDataDir: "./my-profile" });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.args.some((a: string) => a.startsWith("--fingerprint="))).toBe(true);
+  });
+
+  it("handles proxy auth with persistent context", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    const browser = await launchPersistentContext({
+      userDataDir: "./my-profile",
+      proxy: "http://user:pass@proxy:8080",
+    });
+
+    const page = await browser.newPage();
+    expect(page.authenticate).toHaveBeenCalledWith({
+      username: "user",
+      password: "pass",
+    });
+  });
+
+  it("keeps SOCKS5 credentials in --proxy-server URL", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    const browser = await launchPersistentContext({
+      userDataDir: "./my-profile",
+      proxy: "socks5://user:pass@proxy:1080",
+    });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.args).toContain("--proxy-server=socks5://user:pass@proxy:1080");
+
+    const page = await browser.newPage();
+    expect(page.authenticate).not.toHaveBeenCalled();
+  });
+
+  it("forwards launchOptions to puppeteer launch", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({ userDataDir: "./my-profile", launchOptions: { slowMo: 50 } });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.slowMo).toBe(50);
+    expect(callArgs.userDataDir).toBe("./my-profile");
+  });
+
+  it("injects timezone and locale as binary flags", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({
+      userDataDir: "./my-profile",
+      timezone: "Asia/Tokyo",
+      locale: "ja-JP",
+    });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.args).toContain("--fingerprint-timezone=Asia/Tokyo");
+    expect(callArgs.args).toContain("--lang=ja-JP");
+  });
+});

js/tests/stealth.test.ts

@@ -44,9 +44,14 @@ function buildMockPage(overrides: Record<string, any> = {}): any {
 
   const makeLocator = () => {
     const loc: any = {
-      boundingBox: vi.fn(async () => ({ x: 100, y: 100, width: 200, height: 30 })),
+      boundingBox: vi.fn(async () => ({ x: 100, y: 300, width: 200, height: 30 })),
       scrollIntoViewIfNeeded: vi.fn(async () => {}),
       isChecked: overrides.isChecked ?? vi.fn(async () => false),
+      waitFor: vi.fn(async () => {}),
+      isVisible: vi.fn(async () => true),
+      isEnabled: vi.fn(async () => true),
+      isEditable: vi.fn(async () => true),
+      evaluate: vi.fn(async () => ({ hit: true })),
     };
     loc.first = vi.fn(() => loc);
     return loc;
@@ -687,6 +692,9 @@ describe("isInputElement stealth integration via patchPage", () => {
         }
         if (method === "Runtime.evaluate") {
           stealthEvaluateCalls.push(params.expression);
+          if (params.expression.includes("elementFromPoint")) {
+            return { result: { value: { hit: true } } };
+          }
           return { result: { value: false } }; // not an input
         }
         return {};
@@ -696,7 +704,7 @@ describe("isInputElement stealth integration via patchPage", () => {
     const page = buildMockPage({
       evaluate: vi.fn(async (...args: any[]) => {
         evaluateCalls.push(args);
-        return false;
+        return { hit: true };
       }),
     });
     page.context = vi.fn(() => ({

tests/test_cloakserve.py

@@ -1,9 +1,11 @@
 """Unit tests for cloakserve — parse_connection_params, parse_cli_args, URL rewriting, connection tracking."""
 
+import asyncio
 import importlib.machinery
 import importlib.util
 import sys
 from pathlib import Path
+from types import SimpleNamespace
 from unittest.mock import patch
 
 import pytest
@@ -141,8 +143,94 @@ class TestParseCliArgs:
 # ---------------------------------------------------------------------------
 
 
-class TestURLRewriting:
-    """Test the URL rewriting logic used by /json/version and /json/list."""
+class TestWebSocketOriginGuard:
+    """Verify cloakserve rejects browser-origin CDP WebSocket hijacks."""
+
+    def test_absent_origin_allowed_for_non_browser_cdp_clients(self):
+        assert _mod._origin_is_allowed(None, "127.0.0.1:9555")
+
+    def test_matching_origin_host_allowed(self):
+        assert _mod._origin_is_allowed("http://127.0.0.1:9555", "127.0.0.1:9555")
+
+    def test_chrome_devtools_origin_allowed(self):
+        assert _mod._origin_is_allowed("devtools://devtools", "127.0.0.1:9555")
+        assert _mod._origin_is_allowed("chrome-devtools://devtools", "127.0.0.1:9555")
+
+    @pytest.mark.parametrize("origin", [
+        "http://attacker.example",
+        "https://attacker.example",
+        "http://PUBLIC_HOST:9555",
+        "http://attacker.example:9555",
+        "http://127.0.0.1:9555/",
+        "http://127.0.0.1:9555/path",
+        "http://127.0.0.1:9555?q=1",
+        "http://127.0.0.1:9555#fragment",
+        "http://user@127.0.0.1:9555",
+        "http://@127.0.0.1:9555",
+        "http://:@127.0.0.1:9555",
+        "http://127.0.0.1:",
+        "null",
+        "file://",
+    ])
+    def test_untrusted_browser_origins_rejected(self, origin):
+        assert not _mod._origin_is_allowed(origin, "127.0.0.1:9555")
+
+    def test_public_origin_matching_host_is_still_rejected(self):
+        assert not _mod._origin_is_allowed("http://attacker.example:9555", "attacker.example:9555")
+
+    @pytest.mark.parametrize("host", [
+        "user@127.0.0.1:9555",
+        "127.0.0.1:9555/path",
+        "127.0.0.1:9555?x=1",
+        "127.0.0.1:9555#fragment",
+        "127.0.0.1:9555, attacker.example:9555",
+        "@127.0.0.1:9555",
+        ":@127.0.0.1:9555",
+        "127.0.0.1:",
+        "[::1]:",
+    ])
+    def test_malformed_host_is_rejected_even_when_hostname_is_loopback(self, host):
+        assert not _mod._origin_is_allowed("http://127.0.0.1:9555", host)
+
+    def test_request_scheme_controls_host_default_port(self):
+        assert _mod._origin_is_allowed("https://localhost", "localhost", request_scheme="https")
+        assert not _mod._origin_is_allowed("https://localhost", "localhost", request_scheme="http")
+
+    def test_ws_handler_rejects_untrusted_origin_before_launching_chrome(self):
+        class RejectingPool:
+            async def get_or_launch(self, **_kwargs):
+                raise AssertionError("untrusted origin should be rejected before launching Chrome")
+
+        request = SimpleNamespace(
+            headers={"Host": "127.0.0.1:9555", "Origin": "http://attacker.example"},
+            app={"pool": RejectingPool()},
+            match_info={"path": "browser/browser-guid"},
+        )
+
+        response = asyncio.run(_mod.handle_ws_default(request))
+
+        assert response.status == 403
+        assert "untrusted" in response.text.lower()
+
+    def test_seed_ws_handler_rejects_untrusted_origin_before_launching_chrome(self):
+        class RejectingPool:
+            async def get_or_launch(self, **_kwargs):
+                raise AssertionError("untrusted origin should be rejected before launching Chrome")
+
+        request = SimpleNamespace(
+            headers={"Host": "127.0.0.1:9555", "Origin": "http://attacker.example"},
+            app={"pool": RejectingPool()},
+            match_info={"seed": "abc123", "path": "page/page-guid"},
+        )
+
+        response = asyncio.run(_mod.handle_ws_seed(request))
+
+        assert response.status == 403
+        assert "untrusted" in response.text.lower()
+
+
+class TestHandlerURLRewriting:
+    """Verify handlers rewrite CDP WebSocket URLs to the public cloakserve endpoint."""
 
     def _rewrite_version(self, orig_ws: str, host: str, seed: str | None, scheme: str = "ws") -> str:
         """Replicate the URL rewrite logic from handle_json_version."""

tests/test_extension_loading.py

@@ -0,0 +1,33 @@
+import os
+from unittest.mock import MagicMock, patch
+
+from cloakbrowser import launch
+
+
+@patch("cloakbrowser.browser.ensure_binary")
+@patch("cloakbrowser.browser._import_sync_playwright")
+def test_extension_loading(mock_playwright_import, mock_ensure_binary):
+    mock_ensure_binary.return_value = "/fake/chrome"
+
+    mock_browser = MagicMock()
+
+    mock_pw = MagicMock()
+    mock_pw.chromium.launch.return_value = mock_browser
+
+    mock_pw_manager = MagicMock()
+    mock_pw_manager.return_value.start.return_value = mock_pw
+
+    mock_playwright_import.return_value = mock_pw_manager
+
+    launch(extension_paths=["./ext"])
+
+    mock_pw.chromium.launch.assert_called_once()
+
+    launch_call = mock_pw.chromium.launch.call_args
+
+    args = launch_call.kwargs["args"]
+
+    abs_path = os.path.abspath("./ext")
+
+    assert f"--load-extension={abs_path}" in args
+    assert f"--disable-extensions-except={abs_path}" in args

tests/test_humanize_unit.py

@@ -14,6 +14,26 @@ import time
 import sys
 import asyncio
 import pytest
+from unittest.mock import MagicMock
+
+
+def _mock_el_evaluate(is_input=False):
+    """Mock evaluate that returns is_input for tagName checks and {hit: True} for pointer events."""
+    def _eval(js, *args, **kwargs):
+        if isinstance(js, str) and "elementFromPoint" in js:
+            return {"hit": True}
+        return is_input
+    return MagicMock(side_effect=_eval)
+
+
+def _async_mock_el_evaluate(is_input=False):
+    """Async version of _mock_el_evaluate."""
+    from unittest.mock import AsyncMock
+    async def _eval(js, *args, **kwargs):
+        if isinstance(js, str) and "elementFromPoint" in js:
+            return {"hit": True}
+        return is_input
+    return AsyncMock(side_effect=_eval)
 
 
 # =========================================================================
@@ -192,6 +212,59 @@ class TestAsyncCompat:
         import asyncio
         assert asyncio.iscoroutinefunction(async_sleep_ms)
 
+    def test_patch_page_async_does_not_crash(self):
+        """patch_page_async must not raise NameError for missing definitions."""
+        import cloakbrowser.human as h
+        from cloakbrowser.human import _CursorState
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock, AsyncMock
+
+        cfg = resolve_config("default", {"idle_between_actions": False})
+        cursor = _CursorState()
+        cursor.initialized = True
+        cursor.x = 100
+        cursor.y = 100
+
+        page = MagicMock()
+        page.click = AsyncMock()
+        page.dblclick = AsyncMock()
+        page.hover = AsyncMock()
+        page.type = AsyncMock()
+        page.fill = AsyncMock()
+        page.goto = AsyncMock()
+        page.check = AsyncMock()
+        page.uncheck = AsyncMock()
+        page.select_option = AsyncMock()
+        page.press = AsyncMock()
+        page.is_checked = AsyncMock(return_value=False)
+        page.viewport_size = {"width": 1280, "height": 720}
+        page.evaluate = AsyncMock(return_value={"hit": True})
+        page.context.new_cdp_session = AsyncMock(side_effect=Exception("no cdp"))
+        page.mouse = MagicMock()
+        page.mouse.move = AsyncMock()
+        page.mouse.click = AsyncMock()
+        page.mouse.wheel = AsyncMock()
+        page.mouse.down = AsyncMock()
+        page.mouse.up = AsyncMock()
+        page.keyboard = MagicMock()
+        page.keyboard.type = AsyncMock()
+        page.keyboard.down = AsyncMock()
+        page.keyboard.up = AsyncMock()
+        page.keyboard.press = AsyncMock()
+        page.keyboard.insert_text = AsyncMock()
+        page.query_selector = AsyncMock(return_value=None)
+        page.query_selector_all = AsyncMock(return_value=[])
+        page.wait_for_selector = AsyncMock(return_value=None)
+        page.main_frame = MagicMock()
+        page.main_frame.return_value = MagicMock()
+        page.main_frame.return_value.child_frames = MagicMock(return_value=[])
+        page.main_frame.child_frames = MagicMock(return_value=[])
+
+        h.patch_page_async(page, cfg, cursor)
+
+        assert hasattr(page, '_original')
+        assert page.select_option != AsyncMock
+
 
 # =========================================================================
 # 4. Focus check — press / clear / pressSequentially
@@ -707,7 +780,7 @@ class TestElementHandlePatchingSync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = MagicMock(return_value={"x": 50, "y": 50, "width": 100, "height": 30})
-        el.evaluate = MagicMock(return_value=True)  # is_input
+        el.evaluate = _mock_el_evaluate(is_input=True)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -738,7 +811,7 @@ class TestElementHandlePatchingSync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = MagicMock(return_value={"x": 200, "y": 200, "width": 100, "height": 30})
-        el.evaluate = MagicMock(return_value=False)
+        el.evaluate = _mock_el_evaluate(is_input=False)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -779,7 +852,7 @@ class TestElementHandlePatchingSync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = MagicMock(return_value={"x": 200, "y": 200, "width": 100, "height": 30})
-        el.evaluate = MagicMock(return_value=False)
+        el.evaluate = _mock_el_evaluate(is_input=False)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -819,7 +892,7 @@ class TestElementHandlePatchingSync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = MagicMock(return_value={"x": 200, "y": 200, "width": 100, "height": 30})
-        el.evaluate = MagicMock(return_value=True)  # is input
+        el.evaluate = _mock_el_evaluate(is_input=True)  # is input
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -867,7 +940,7 @@ class TestElementHandlePatchingSync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = MagicMock(return_value={"x": 200, "y": 200, "width": 100, "height": 30})
-        el.evaluate = MagicMock(return_value=True)
+        el.evaluate = _mock_el_evaluate(is_input=True)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -947,7 +1020,7 @@ class TestElementHandlePatchingSync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = MagicMock(return_value={"x": 50, "y": 50, "width": 100, "height": 30})
-        el.evaluate = MagicMock(return_value=False)
+        el.evaluate = _mock_el_evaluate(is_input=False)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=child)
         el.query_selector_all = MagicMock(return_value=[])
@@ -971,7 +1044,7 @@ class TestElementHandlePatchingSync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = MagicMock(return_value={"x": 50, "y": 50, "width": 100, "height": 30})
-        el.evaluate = MagicMock(return_value=False)
+        el.evaluate = _mock_el_evaluate(is_input=False)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -1036,7 +1109,7 @@ class TestElementHandlePatchingSync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = MagicMock(return_value={"x": 50, "y": 50, "width": 100, "height": 30})
-        el.evaluate = MagicMock(return_value=False)
+        el.evaluate = _mock_el_evaluate(is_input=False)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -1069,7 +1142,7 @@ class TestElementHandlePatchingSync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = MagicMock(return_value={"x": 50, "y": 50, "width": 100, "height": 30})
-        el.evaluate = MagicMock(return_value=False)
+        el.evaluate = _mock_el_evaluate(is_input=False)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -1114,8 +1187,9 @@ class TestElementHandlePatchingAsync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = AsyncMock(return_value={"x": 200, "y": 200, "width": 100, "height": 30})
-        el.evaluate = AsyncMock(return_value=False)
+        el.evaluate = _async_mock_el_evaluate(is_input=False)
         el.is_checked = AsyncMock(return_value=False)
+        el.wait_for_element_state = AsyncMock()
         el.query_selector = AsyncMock(return_value=None)
         el.query_selector_all = AsyncMock(return_value=[])
         el.wait_for_selector = AsyncMock(return_value=None)
@@ -1155,8 +1229,9 @@ class TestElementHandlePatchingAsync:
         el = MagicMock()
         el._human_patched = False
         el.bounding_box = AsyncMock(return_value={"x": 50, "y": 50, "width": 100, "height": 30})
-        el.evaluate = AsyncMock(return_value=False)
+        el.evaluate = _async_mock_el_evaluate(is_input=False)
         el.is_checked = AsyncMock(return_value=False)
+        el.wait_for_element_state = AsyncMock()
         el.query_selector = AsyncMock(return_value=None)
         el.query_selector_all = AsyncMock(return_value=[])
         el.wait_for_selector = AsyncMock(return_value=None)
@@ -1376,7 +1451,7 @@ class TestPerCallTimeoutForwarding:
         page.goto = MagicMock()
         page.is_checked = MagicMock(return_value=False)
         page.viewport_size = {"width": 1280, "height": 720}
-        page.evaluate = MagicMock(return_value=False)
+        page.evaluate = MagicMock(return_value={"hit": True})
         page.context.new_cdp_session = MagicMock(side_effect=Exception("no cdp"))
         page.mouse = MagicMock()
         page.keyboard = MagicMock()
@@ -1389,13 +1464,14 @@ class TestPerCallTimeoutForwarding:
         captured = {}
         def fake_scroll(page_arg, raw, selector, cx, cy, cfg_arg, timeout=30000):
             captured["timeout"] = timeout
-            return ({"x": 100, "y": 100, "width": 50, "height": 30}, cx, cy)
+            return ({"x": 100, "y": 100, "width": 50, "height": 30}, cx, cy, False)
 
-        with patch.object(h, "scroll_to_element", side_effect=fake_scroll):
+        with patch.object(h, "scroll_to_element", side_effect=fake_scroll), \
+             patch.object(h, "ensure_actionable"):
             h.patch_page(page, cfg, cursor)
             page.click("#slow-button", timeout=5000)
 
-        assert captured.get("timeout") == 5000, f"expected 5000, got {captured}"
+        assert 4900 <= captured.get("timeout", 0) <= 5000, f"expected ~5000, got {captured}"
 
 
 # =========================================================================
@@ -1462,7 +1538,7 @@ class TestPerCallHumanConfigOverride:
         page.goto = MagicMock()
         page.is_checked = MagicMock(return_value=False)
         page.viewport_size = {"width": 1280, "height": 720}
-        page.evaluate = MagicMock(return_value=False)
+        page.evaluate = MagicMock(return_value={"hit": True})
         page.context.new_cdp_session = MagicMock(side_effect=Exception("no cdp"))
         page.mouse = MagicMock()
         page.keyboard = MagicMock()
@@ -1478,10 +1554,12 @@ class TestPerCallHumanConfigOverride:
             captured["mistype_chance"] = cfg_arg.mistype_chance
 
         def fake_scroll(*args, **kwargs):
-            return ({"x": 100, "y": 100, "width": 50, "height": 30}, 100, 100)
+            return ({"x": 100, "y": 100, "width": 50, "height": 30}, 100, 100, False)
 
         with patch.object(h, "human_type", side_effect=fake_human_type), \
-             patch.object(h, "scroll_to_element", side_effect=fake_scroll):
+             patch.object(h, "scroll_to_element", side_effect=fake_scroll), \
+             patch.object(h, "ensure_actionable"), \
+             patch.object(h, "check_pointer_events"):
             h.patch_page(page, cfg, cursor)
             page.type(
                 "#email", "hi",
@@ -1490,7 +1568,6 @@ class TestPerCallHumanConfigOverride:
 
         assert captured["typing_delay"] == 30
         assert captured["mistype_chance"] == 0
-        # Global cfg untouched — per-call override doesn't leak
         assert cfg.typing_delay == 70
 
     def test_page_fill_uses_per_call_typing_delay(self):
@@ -1512,7 +1589,7 @@ class TestPerCallHumanConfigOverride:
         page = MagicMock()
         page.viewport_size = {"width": 1280, "height": 720}
         page.is_checked = MagicMock(return_value=False)
-        page.evaluate = MagicMock(return_value=False)
+        page.evaluate = MagicMock(return_value={"hit": True})
         page.context.new_cdp_session = MagicMock(side_effect=Exception("no cdp"))
         page.mouse = MagicMock()
         page.keyboard = MagicMock()
@@ -1527,10 +1604,12 @@ class TestPerCallHumanConfigOverride:
             captured["typing_delay"] = cfg_arg.typing_delay
 
         def fake_scroll(*args, **kwargs):
-            return ({"x": 100, "y": 100, "width": 50, "height": 30}, 100, 100)
+            return ({"x": 100, "y": 100, "width": 50, "height": 30}, 100, 100, False)
 
         with patch.object(h, "human_type", side_effect=fake_human_type), \
-             patch.object(h, "scroll_to_element", side_effect=fake_scroll):
+             patch.object(h, "scroll_to_element", side_effect=fake_scroll), \
+             patch.object(h, "ensure_actionable"), \
+             patch.object(h, "check_pointer_events"):
             h.patch_page(page, cfg, cursor)
             page.fill("#password", "secret", human_config={"typing_delay": 150})
 
@@ -1562,7 +1641,7 @@ class TestPerCallHumanConfigOverride:
         el.bounding_box = MagicMock(
             return_value={"x": 200, "y": 200, "width": 100, "height": 30}
         )
-        el.evaluate = MagicMock(return_value=True)
+        el.evaluate = _mock_el_evaluate(is_input=True)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -1608,9 +1687,10 @@ class TestScrollIntoViewIfNeeded:
         # Box is dead-center of viewport — squarely in scroll_target_zone
         in_view_box = {"x": 200, "y": 300, "width": 50, "height": 30}
 
-        box, cx, cy = human_scroll_into_view(
+        box, cx, cy, did_scroll = human_scroll_into_view(
             page, raw, lambda: in_view_box, 0, 0, cfg,
         )
+        assert not did_scroll, "In-viewport elements shouldn't report scrolling"
         assert box == in_view_box
         assert not raw.wheel.called, "In-viewport elements shouldn't trigger wheel events"
 
@@ -1672,7 +1752,7 @@ class TestScrollIntoViewIfNeeded:
         el.bounding_box = MagicMock(
             return_value={"x": 200, "y": 200, "width": 50, "height": 30}
         )
-        el.evaluate = MagicMock(return_value=False)
+        el.evaluate = _mock_el_evaluate(is_input=False)
         el.is_checked = MagicMock(return_value=False)
         el.query_selector = MagicMock(return_value=None)
         el.query_selector_all = MagicMock(return_value=[])
@@ -1683,14 +1763,13 @@ class TestScrollIntoViewIfNeeded:
         called = {"count": 0}
         def fake(*args, **kwargs):
             called["count"] += 1
-            return ({"x": 200, "y": 200, "width": 50, "height": 30}, 100, 100)
+            return ({"x": 200, "y": 200, "width": 50, "height": 30}, 100, 100, False)
 
         with patch.object(h, "human_scroll_into_view", side_effect=fake):
             _patch_single_element_handle_sync(
                 el, page, cfg, cursor, MagicMock(), MagicMock(),
                 page._original, None, None,
             )
-            # Patched method should now invoke our humanized helper
             el.scroll_into_view_if_needed()
 
         assert called["count"] >= 1, "humanized scroll helper was never called"
@@ -1735,7 +1814,7 @@ class TestScrollIntoViewIfNeeded:
             called["count"] += 1
             # cfg is the 6th positional arg (page, raw, get_box, cx, cy, cfg)
             called["cfg"] = args[5] if len(args) >= 6 else kwargs.get("cfg")
-            return ({"x": 100, "y": 100, "width": 50, "height": 30}, 200, 200)
+            return ({"x": 100, "y": 100, "width": 50, "height": 30}, 200, 200, False)
 
         with patch.object(h, "human_scroll_into_view", side_effect=fake):
             Locator.scroll_into_view_if_needed(

tests/test_lambda_security.py

@@ -0,0 +1,171 @@
+"""Security tests for the AWS Lambda handler URL validation."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+sys.path.insert(
+    0, str(Path(__file__).resolve().parent.parent / "examples" / "integrations" / "aws_lambda")
+)
+
+from lambda_handler import _build_launch_kwargs, _classify_error, _validate_url
+
+
+class TestSchemeValidation:
+    """Fix 1: only http:// and https:// are accepted."""
+
+    @pytest.mark.parametrize("url", [
+        "file:///etc/passwd",
+        "file:///proc/self/environ",
+        "data:text/html,<h1>pwned</h1>",
+        "javascript:alert(1)",
+        "chrome://settings",
+        "about:blank",
+        "ftp://example.com/file",
+        "",
+    ])
+    def test_rejects_non_http_schemes(self, url):
+        with pytest.raises(ValueError, match="Only http"):
+            _validate_url(url)
+
+    @pytest.mark.parametrize("url", [
+        "https://example.com",
+        "http://example.com",
+        "https://example.com/path?q=1",
+        "HTTP://EXAMPLE.COM",
+    ])
+    def test_accepts_http_and_https(self, url):
+        _validate_url(url)
+
+    def test_rejects_missing_hostname(self):
+        with pytest.raises(ValueError, match="no hostname"):
+            _validate_url("http://")
+
+
+class TestSSRFProtection:
+    """Fix 2: block private, loopback, link-local, reserved, and metadata IPs."""
+
+    @pytest.mark.parametrize("url,label", [
+        ("http://169.254.169.254", "AWS metadata"),
+        ("http://169.254.169.254/latest/meta-data/", "AWS metadata path"),
+        ("http://127.0.0.1", "loopback"),
+        ("http://127.0.0.2", "loopback range"),
+        ("http://localhost", "localhost"),
+        ("http://10.0.0.1", "private 10.x"),
+        ("http://172.16.0.1", "private 172.16"),
+        ("http://192.168.1.1", "private 192.168"),
+        ("http://0.0.0.0", "unspecified"),
+        ("http://[::1]", "IPv6 loopback"),
+    ])
+    def test_rejects_private_ips(self, url, label):
+        with pytest.raises(ValueError, match="private/internal"):
+            _validate_url(url)
+
+    def test_rejects_carrier_grade_nat(self):
+        with pytest.raises(ValueError, match="private/internal"):
+            _validate_url("http://100.64.0.1")
+
+    def test_rejects_unresolvable_hostname(self):
+        with pytest.raises(ValueError, match="Cannot resolve"):
+            _validate_url("http://this-host-does-not-exist-cb-test.invalid")
+
+    def test_rejects_ipv4_mapped_ipv6(self):
+        """::ffff:127.0.0.1 should be blocked even though it's technically IPv6."""
+        with pytest.raises(ValueError, match="private/internal"):
+            _validate_url("http://[::ffff:127.0.0.1]")
+
+
+class TestExtraArgsRemoval:
+    """Fix 3: caller-controlled extra_args are ignored; internal _strategy_args work."""
+
+    def test_ignores_caller_extra_args(self):
+        event = {"url": "https://example.com", "extra_args": ["--remote-debugging-port=9222"]}
+        kwargs = _build_launch_kwargs(event)
+        assert "--remote-debugging-port=9222" not in kwargs["args"]
+
+    def test_includes_strategy_args(self):
+        event = {"url": "https://example.com", "_strategy_args": ["--ignore-certificate-errors"]}
+        kwargs = _build_launch_kwargs(event)
+        assert "--ignore-certificate-errors" in kwargs["args"]
+
+    def test_classify_error_uses_strategy_args(self):
+        result = _classify_error(Exception("ERR_CERT_AUTHORITY_INVALID"))
+        assert "_strategy_args" in result
+        assert "extra_args" not in result
+
+    def test_always_includes_lambda_hardening_flags(self):
+        kwargs = _build_launch_kwargs({"url": "https://example.com"})
+        assert "--disable-dev-shm-usage" in kwargs["args"]
+        assert "--no-zygote" in kwargs["args"]
+
+    def test_caller_cannot_inject_strategy_args(self):
+        """_strategy_args in the caller event must be stripped by _run() before launch."""
+        from lambda_handler import _run
+        import inspect
+        source = inspect.getsource(_run)
+        assert '"_strategy_args"' in source and "extra_args" in source, \
+            "_run must strip both _strategy_args and extra_args from caller event"
+
+
+class TestRedirectSSRF:
+    """Fix 5: post-navigation re-validation catches redirects to blocked IPs.
+
+    These mock socket.getaddrinfo to simulate redirect scenarios without
+    needing a real browser or HTTP server.
+    """
+
+    def test_validate_url_catches_redirect_target(self):
+        """If Chromium followed a redirect to 169.254.169.254, the post-nav
+        _validate_url(page.url) call should reject it."""
+        with pytest.raises(ValueError, match="private/internal"):
+            _validate_url("http://169.254.169.254/latest/meta-data/iam/security-credentials/")
+
+    def test_validate_url_catches_localhost_redirect(self):
+        with pytest.raises(ValueError, match="private/internal"):
+            _validate_url("http://127.0.0.1:8080/admin")
+
+    def test_code_flow_validates_before_content(self):
+        """Verify that _attempt_scrape calls _validate_url(page.url) at line 282
+        BEFORE building the result dict at line 290 (sequential code path)."""
+        import ast
+        handler_path = (
+            Path(__file__).resolve().parent.parent
+            / "examples" / "integrations" / "aws_lambda" / "lambda_handler.py"
+        )
+        source = handler_path.read_text()
+        tree = ast.parse(source)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.AsyncFunctionDef) and node.name == "_attempt_scrape":
+                body = node.body
+                # Find the try block
+                for stmt in body:
+                    if isinstance(stmt, ast.Try):
+                        try_body = stmt.body
+                        validate_lines = []
+                        content_line = None
+                        for s in try_body:
+                            if isinstance(s, ast.Expr) and isinstance(s.value, ast.Call):
+                                func = s.value.func
+                                if isinstance(func, ast.Name) and func.id == "_validate_url":
+                                    validate_lines.append(s.lineno)
+                            if isinstance(s, ast.AnnAssign):
+                                if isinstance(s.target, ast.Name) and s.target.id == "result":
+                                    content_line = s.lineno
+                            elif isinstance(s, ast.Assign):
+                                for target in s.targets:
+                                    if isinstance(target, ast.Name) and target.id == "result":
+                                        content_line = s.lineno
+                        assert len(validate_lines) >= 2, (
+                            f"Expected 2 _validate_url calls, found {len(validate_lines)}"
+                        )
+                        assert content_line is not None
+                        assert all(v < content_line for v in validate_lines), (
+                            f"_validate_url (lines {validate_lines}) must come before "
+                            f"result assignment (line {content_line})"
+                        )
+                        return
+        pytest.fail("Could not find _attempt_scrape function in source")

tests/test_stealth_unit.py

@@ -1010,7 +1010,11 @@ class TestPatchPageStealthWiring:
         fake_box = {"x": 100, "y": 200, "width": 200, "height": 30}
         with mock_patch(
             "cloakbrowser.human.scroll_to_element",
-            return_value=(fake_box, 200.0, 215.0),
+            return_value=(fake_box, 200.0, 215.0, False),
+        ), mock_patch(
+            "cloakbrowser.human.ensure_actionable",
+        ), mock_patch(
+            "cloakbrowser.human.check_pointer_events",
         ):
             try:
                 page.click("#btn")