fix(humanize): strip custom kwargs before forwarding to Playwright select_option

originals.select_option(**kwargs) passes human_config/force to Playwright which rejects unknown kwargs with TypeError.
fix(humanize): forward human_config in all chained methods, use evaluate args in handle pointer checks
2026-06-23 11:41:46 +02:00 · 2026-05-15 20:51:30 +02:00 · 2026-05-15 19:17:11 +02:00 · 2026-05-12 22:58:03 +02:00 · 2026-05-12 15:53:31 +02:00 · 2026-05-12 15:47:26 +02:00
53 changed files with 5816 additions and 712 deletions
@@ -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
@@ -23,7 +23,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
        with:
          node-version: 20
      - name: Install and build
@@ -32,7 +32,7 @@ jobs:
        run: |
          pip install -e ".[dev]" pytest pytest-asyncio
          pytest tests/ -v -m "not slow"
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
        with:
          node-version: 22
      - name: JavaScript tests
@@ -71,7 +71,7 @@ jobs:
          pip install build
          python -m build
      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # v1
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1

  publish-npm:
    needs: [test, validate-version]
@@ -81,7 +81,7 @@ jobs:
      id-token: write  # OIDC trusted publishing + provenance — no NPM_TOKEN needed
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
        with:
          node-version: 24  # npm 11.11.0 native — no upgrade needed (Node 22.22.2 has broken npm)
          registry-url: 'https://registry.npmjs.org'
@@ -113,7 +113,7 @@ jobs:
          password: ${{ secrets.DOCKER_PAT }}
      - name: Build and push
        id: build
-        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294  # v7.0.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7.1.0
        with:
          context: .
          platforms: linux/amd64,linux/arm64
@@ -123,7 +123,7 @@ jobs:
            cloakhq/cloakbrowser:latest
          provenance: true
          sbom: true
-      - uses: sigstore/cosign-installer@cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003  # v4.1.1
+      - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6  # v4.1.2
      - name: Sign image
        run: cosign sign --yes cloakhq/cloakbrowser@${{ steps.build.outputs.digest }}
      - name: Attest build provenance
@@ -6,6 +6,51 @@ Changes are tagged: **[wrapper]** for Python/JS wrapper, **[binary]** for Chromi

 ---

+## [Unreleased]
+
+## [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)
+- **[wrapper]** Fix GeoIP resolution hanging indefinitely — bounded with 10s timeout so `launch()` cannot stall (thanks [@manaskarra](https://github.com/manaskarra), #213)
+- **[wrapper]** JS: preserve iframe scope in humanized frame actions — `check()`, `uncheck()`, `selectOption()` now execute in the correct frame (thanks [@manaskarra](https://github.com/manaskarra), #201)
+- **[wrapper]** JS: add TypeScript types to humanized method options — `HumanActionOptions` type for `human_config` and `timeout` overrides (thanks [@eofreternal](https://github.com/eofreternal), #205)
+- **[wrapper]** Log when SOCKS5 credential auto-encoding rewrites a proxy URL (thanks [@Youhai020616](https://github.com/Youhai020616), #209)
+- **[wrapper]** JS: bump `playwright-core` peer dependency minimum to >=1.53.0 (#200)
+- **[meta]** Bump sigstore/cosign-installer in CI (#214)
+
+## [0.3.27] — 2026-05-06
+
+- **[wrapper]** Per-call `human_config` override — pass `human_config={...}` to individual humanized methods to override global HumanConfig on a per-action basis (#183)
+- **[wrapper]** Humanized `scrollIntoViewIfNeeded` — auto-scrolls with human-like behavior when `humanize=True` (#183)
+- **[wrapper]** Forward `timeout` parameter through humanized Playwright methods (#183)
+- **[wrapper]** Fix humanize timeout default to align with Playwright's 30s auto-retry instead of custom 2s (#172)
+
+## [0.3.26] — 2026-04-28
+
+- **[binary]** Windows x64 upgraded to Chromium 146.0.7680.177.4 — 57 source-level fingerprint patches (up from 33 on 145.0.7632.159.7), now matches Linux. Includes all binary improvements from 0.3.18–0.3.25: native SOCKS5 proxy with UDP ASSOCIATE (QUIC/HTTP3), WebRTC IP spoofing, proxy signal removal, CDP input stealth, storage quota normalization, WebAuthn/AAC/window position patches, WebGL and canvas consistency fixes, expanded GPU model database
+- **[wrapper]** Auto URL-encode SOCKS5 credentials containing special characters in string URLs (#157)
+- **[wrapper]** AWS Lambda integration example with cold-start hardening and handler-side retry orchestration (#177, thanks [@AlexTech314](https://github.com/AlexTech314))
+- **[docker]** Add emoji and extended font packages to resolve Kasada/Akamai canvas fingerprint blocks (#179)
+- **[docs]** Add Font Setup on Linux section to README (#179)
+- **[docs]** Add Deployment Integrations section to README (#177)
+- **[meta]** Bump GitHub Actions dependencies (#178)
+
+## [0.3.25] — 2026-04-16
+
+- **[wrapper]** Python: add `launch_context_async()` — async counterpart to `launch_context()`. Returns a BrowserContext with all kwargs forwarded to `browser.new_context()`, enabling `storage_state`, `permissions`, `extra_http_headers`, etc. without a persistent profile folder. Closes #141.
+- **[wrapper]** JS: `launchContext()` and `launchPersistentContext()` silently dropped unknown options (including `storageState`). New `contextOptions` escape hatch forwards arbitrary options to Playwright's `newContext()`.
+- **[wrapper]** Fix `humanConfig` TypeScript typing (#151).
+- **[binary]** New build 146.0.7680.177.3 for Linux x64 + arm64 — 57 source-level fingerprint patches (up from 49): WebAuthn capabilities, AAC audio encoder, and window position spoofing; WebGL and canvas format consistency fixes; SOCKS5 warm connection pool auth fix for credentialed proxies.
+- **[docs]** Add recommended anti-bot config and SOCKS5 tips to troubleshooting.
+
+## [0.3.24] — 2026-04-10
+
+- **[wrapper]** Native SOCKS5 proxy support — pass `proxy="socks5://user:pass@host:port"` directly. Credentials handled natively by Chrome. Works across all launch functions, Python + JS.
+- **[wrapper]** Add Playwright ElementHandle humanize support — `element_handle.click()`, `.fill()`, `.type()` now use human-like behavior when `humanize=True` (thanks [@evelaa123](https://github.com/evelaa123), #133)
+- **[binary]** Upgrade Linux arm64 to Chromium 146.0.7680.177.2 (49 patches) — now matches Linux x64
+- **[binary]** New build 146.0.7680.177.2 for both Linux platforms: native SOCKS5 proxy with UDP ASSOCIATE (QUIC/HTTP3 over SOCKS5)
+- **[docs]** Clarify humanize requires wrapper import over CDP (#126)
+
 ## [0.3.23] — 2026-04-09

 - **[wrapper]** Add full Puppeteer humanize support — human-like mouse, keyboard, and scroll behavior for `puppeteer-core` users (thanks [@evelaa123](https://github.com/evelaa123), #129)
@@ -9,6 +9,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
    libxcb1 libxext6 libxshmfence1 \
    libglib2.0-0 libgtk-3-0 libpangocairo-1.0-0 libcairo-gobject2 \
    libgdk-pixbuf-2.0-0 libxss1 libxtst6 fonts-liberation \
+    fonts-noto-color-emoji fonts-unifont fonts-freefont-ttf \
+    fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf \
    xvfb xdotool \
    curl ca-certificates \
    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
@@ -128,10 +128,13 @@ Open [http://localhost:8080](http://localhost:8080). Create a profile. Click **L

 ---

-## Latest: v0.3.22 (Chromium 146.0.7680.177.1)
+## Latest: v0.3.28 (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()`.
+- **Native SOCKS5 proxy** — `proxy="socks5://user:pass@host:port"` works directly in all launch functions, Python + JS. QUIC/HTTP3 tunnels through SOCKS5 via UDP ASSOCIATE.
 - **Chromium 146 upgrade** — rebased all patches from 145.0.7632.x to 146.0.7680.177
- **49 fingerprint patches** (Linux x64) — 1 new patch, all existing patches carried forward
+- **57 fingerprint patches** — additional detection-vector coverage (WebAuthn, AAC audio, window position) and WebGL/canvas consistency fixes
 - **WebRTC IP spoofing** — `--fingerprint-webrtc-ip=auto` resolves your proxy's exit IP and spoofs WebRTC ICE candidates. Auto-injected when using `geoip=True` (no extra network call)
 - **Proxy signal removal** — DNS/connect/SSL timing zeroed, proxy cache headers stripped, Proxy-Connection header leak removed
 - **`cloakserve` CDP multiplexer** — rewritten as a multi-connection CDP proxy with per-connection fingerprint seeds
@@ -315,6 +318,38 @@ page.goto("https://protected-site.com")
 context.close()
 ```

+Extra kwargs are forwarded to Playwright's `browser.new_context()` — use this for `storage_state`, `permissions`, `extra_http_headers`, etc. without needing a persistent profile folder:
+
+```python
+from cloakbrowser import launch_context
+
+# Restore a saved session (cookies, localStorage) from a JSON file
+context = launch_context(storage_state="state.json")
+page = context.new_page()
+page.goto("https://example.com")
+# Save state back for next run
+context.storage_state(path="state.json")
+context.close()
+```
+
+### `launch_context_async()`
+
+Async counterpart to `launch_context()`. Same signature and kwargs forwarding:
+
+```python
+import asyncio
+from cloakbrowser import launch_context_async
+
+async def main():
+    ctx = await launch_context_async(storage_state="state.json")
+    page = await ctx.new_page()
+    await page.goto("https://example.com")
+    await ctx.storage_state(path="state.json")
+    await ctx.close()
+
+asyncio.run(main())
+```
+
 ### `launch_persistent_context()`

 Same as `launch_context()`, but with a persistent user profile. Cookies, localStorage, and cache persist across sessions.
@@ -371,7 +406,7 @@ from cloakbrowser import binary_info, clear_cache, ensure_binary

 # Check binary installation status
 print(binary_info())
-# {'version': '146.0.7680.177.1', 'platform': 'linux-x64', 'installed': True, ...}
+# {'version': '146.0.7680.177.3', 'platform': 'linux-x64', 'installed': True, ...}

 # Force re-download
 clear_cache()
@@ -535,6 +570,7 @@ Access the original un-patched Playwright page at `page._original` if you need r
 | `CLOAKBROWSER_DOWNLOAD_URL` | `cloakbrowser.dev` | Custom download URL for binary |
 | `CLOAKBROWSER_AUTO_UPDATE` | `true` | Set to `false` to disable background update checks |
 | `CLOAKBROWSER_SKIP_CHECKSUM` | `false` | Set to `true` to skip SHA-256 verification after download |
+| `CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS` | `5` | Max seconds for GeoIP resolution before continuing without it |

 ## Fingerprint Management

@@ -591,13 +627,39 @@ Supported by the binary but **not set by default** — pass via `args` to custom
 | `--fingerprint-locale` | Locale (e.g. `en-US`) |
 | `--fingerprint-storage-quota` | Override storage quota in MB — affects `storage.estimate()`, `storageBuckets`, and legacy webkit APIs. Auto-normalized when `--fingerprint` is set |
 | `--fingerprint-taskbar-height` | Override taskbar height (binary defaults: Win=48, Mac=95, Linux=0) |
-| `--fingerprint-fonts-dir` | Path to cross-platform font directory |
+| `--fingerprint-fonts-dir` | Path to directory containing target-platform fonts (see [Font Setup on Linux](#font-setup-on-linux)) |
 | `--fingerprint-webrtc-ip` | WebRTC ICE candidate IP replacement. Use `auto` to resolve from proxy exit IP (makes an HTTP call through the proxy), or pass an explicit IP. Auto-injected when `geoip=True` |
 | `--fingerprint-noise=false` | Disable noise injection (canvas, WebGL, audio, client rects) while keeping the deterministic fingerprint seed active |
 | `--enable-blink-features=FakeShadowRoot` | Access closed shadow DOM elements |

 > **Note:** All stealth tests were verified with the default fingerprint config above. Changing these flags may affect detection results — test your configuration before using in production.

+### Font Setup on Linux
+
+**Required for aggressive anti-bot sites (Kasada, Akamai).** These systems render emoji on a hidden canvas and hash the pixel output. Minimal Linux environments (Docker, cloud VMs) often lack emoji and extended fonts, producing hashes that don't match any real browser. Install standard font packages to fix this:
+
+```bash
+sudo apt install -y fonts-noto-color-emoji fonts-freefont-ttf fonts-unifont \
+    fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf
+```
+
+The Docker image (`cloakhq/cloakbrowser`) ships with these pre-installed. If you run the binary directly on a Linux server or in a custom Docker image, install them manually.
+
+**Optional: Windows fonts for CreepJS font enumeration.** The packages above fix anti-bot canvas checks but won't improve your CreepJS font score. For that, you need actual Windows fonts (Segoe UI, Calibri, Bahnschrift, etc.) from a Windows machine's `C:\Windows\Fonts\` directory — `ttf-mscorefonts-installer` only has old XP-era fonts and isn't enough.
+
+```bash
+mkdir -p ~/.local/share/fonts/windows
+cp /path/to/windows/fonts/*.ttf ~/.local/share/fonts/windows/
+cp /path/to/windows/fonts/*.TTF ~/.local/share/fonts/windows/
+fc-cache -f  # mandatory for manually copied fonts
+```
+
+```python
+browser = launch(
+    args=["--fingerprint-fonts-dir=/home/user/.local/share/fonts/windows"],
+)
+```
+
 ### Examples

 ```python
@@ -668,15 +730,21 @@ browser = await launch_async(args=["--remote-debugging-port=9242"])
 | [undetected-chromedriver](https://github.com/ultrafunkamsterdam/undetected-chromedriver) | 12K | Python | [`undetected_chromedriver.py`](examples/integrations/undetected_chromedriver.py) |
 | [agent-browser](https://github.com/nichochar/agent-browser) | — | Shell | [`agent_browser.sh`](examples/integrations/agent_browser.sh) |

+### Deployment Integrations
+
+| Platform | Example |
+|----------|---------|
+| [AWS Lambda](https://aws.amazon.com/lambda/) | [`aws_lambda/`](examples/integrations/aws_lambda/) — One-shot scrapes in Lambda (container image) |
+
 ## Platforms

 | Platform | Chromium | Patches | Status |
 |---|---|---|---|
-| Linux x86_64 | 146 | 49 | ✅ Latest |
-| Linux arm64 (RPi, Graviton) | 145 | 48 | ✅ |
+| Linux x86_64 | 146 | 57 | ✅ Latest |
+| Linux arm64 (RPi, Graviton) | 146 | 57 | ✅ Latest |
 | macOS arm64 (Apple Silicon) | 145 | 26 | ✅ |
 | macOS x86_64 (Intel) | 145 | 26 | ✅ |
-| Windows x86_64 | 145 | 48 | ✅ |
+| Windows x86_64 | 146 | 57 | ✅ Latest |

 The wrapper auto-downloads the correct binary for your platform.

@@ -873,7 +941,47 @@ page.goto("https://heavily-protected-site.com")  # passes DataDome, etc.
 browser.close()
 ```

-This runs a real headed browser rendered on a virtual display — no physical monitor needed. Combined with a residential proxy, this passes even the most aggressive detection services. Datacenter IPs are often flagged by IP reputation regardless of browser fingerprint — a residential proxy makes the difference.
+This runs a real headed browser rendered on a virtual display — no physical monitor needed. Combine with the recommended config below for maximum stealth.
+
+---
+
+### Recommended config for anti-bot sites
+
+Most blocks come from missing one of these three things, not from browser fingerprint detection:
+
+```python
+browser = launch(
+    proxy="http://your-residential-proxy:port",  # residential IP — datacenter IPs get blocked by reputation alone
+    geoip=True,      # matches timezone + locale to proxy exit IP (without this: UTC + en-US = bot signal)
+    headless=False,   # headed mode — some sites detect headless even with C++ patches
+    humanize=True,    # human-like mouse, keyboard, scroll behavior
+)
+```
+
+```javascript
+const browser = await launch({
+    proxy: 'http://your-residential-proxy:port',
+    geoip: true,
+    headless: false,
+    humanize: true,
+});
+```
+
+If your proxy supports SOCKS5, use it for better compatibility — SOCKS5 tunnels raw TCP, avoiding HTTP CONNECT issues that some proxies have with HTTP/2:
+
+```python
+browser = launch(proxy="socks5://user:pass@proxy:1080", geoip=True, headless=False, humanize=True)
+```
+
+If you're still blocked after this, check the font setup below.
+
+---
+
+### Blocked on Kasada / Akamai sites despite correct config?
+
+On minimal Linux environments, missing font packages cause canvas emoji rendering to produce hashes that anti-bot systems don't recognize. This is the most common cause of blocks on aggressive sites after proxy, geoip, and headed mode are already set up correctly.
+
+Install the font packages listed in [Font Setup on Linux](#font-setup-on-linux) above.

 ---

@@ -909,7 +1017,7 @@ await ctx.close();
 ctx = await launchPersistentContext({ userDataDir: './profile' });
 ```

-For stateless/ephemeral use cases, `launch(args=["--disable-http2"])` forces HTTP/1.1 which bypasses the check. Only use this flag for sites that require it — most work fine with HTTP/2.
+For stateless/ephemeral use cases, `launch(args=["--disable-http2"])` forces HTTP/1.1 which bypasses the check. Only use this flag for sites that require it — most work fine with HTTP/2. If your proxy supports SOCKS5, use `proxy="socks5://user:pass@host:port"` instead — SOCKS5 bypasses HTTP CONNECT entirely.

 ---

@@ -1035,9 +1143,9 @@ A: Yes. Pass `proxy="http://user:pass@host:port"` or `proxy="socks5://user:pass@

 | Feature | Status |
 |---------|--------|
-| Linux x64 — Chromium 146 (49 patches) | ✅ Released |
+| Linux x64 — Chromium 146 (57 patches) | ✅ Released |
 | macOS arm64/x64 — Chromium 145 (26 patches) | ✅ Released |
-| Windows x64 — Chromium 145 (33 patches) | ✅ Released |
+| Windows x64 — Chromium 146 (57 patches) | ✅ Released |
 | JavaScript/Puppeteer + Playwright support | ✅ Released |
 | Fingerprint rotation per session | ✅ Released |
 | Built-in proxy rotation | 📋 Planned |
@@ -1059,7 +1167,7 @@ All releases are signed for supply chain verification.
 ```bash
 # Verify GPG signature (binary release tag)
 gpg --keyserver keyserver.ubuntu.com --recv-keys C60C0DDC9D0DE2DD
-git verify-tag chromium-v146.0.7680.177.1
+git verify-tag chromium-v146.0.7680.177.3

 # Verify GitHub binary attestation (Sigstore)
 gh attestation verify cloakbrowser-linux-x64.tar.gz --repo CloakHQ/cloakbrowser
@@ -1085,3 +1193,7 @@ Issues and PRs welcome. If something isn't working, [open an issue](https://gith
 - [@evelaa123](https://github.com/evelaa123) — humanize behavior, persistent contexts, Windows fix
 - [@yahooguntu](https://github.com/yahooguntu) — persistent contexts
 - [@kitiho](https://github.com/kitiho) — null viewport fix
+- [@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
@@ -22,6 +22,7 @@ import json
 import logging
 import os
 import random
+import re
 import shutil
 import socket
 import subprocess
@@ -36,7 +37,7 @@ import aiohttp
 import websockets
 from aiohttp import web

-from cloakbrowser.browser import build_args, maybe_resolve_geoip, _resolve_webrtc_args
+from cloakbrowser.browser import build_args, maybe_resolve_geoip, _resolve_webrtc_args, _normalize_socks_string_url
 from cloakbrowser.download import ensure_binary

 logging.basicConfig(
@@ -61,6 +62,9 @@ BASE_CHROME_ARGS = [

 BASE_CDP_PORT = 5100

+SAFE_SEED_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+RESERVED_SEEDS = {"__default__"}
+

 # ---------------------------------------------------------------------------
 # ChromeProcess — one running Chrome instance
@@ -111,6 +115,14 @@ class ChromePool:
            self._locks[seed] = asyncio.Lock()
        return self._locks[seed]

+    def _safe_rmtree(self, path: str) -> None:
+        resolved = Path(path).resolve()
+        data_resolved = Path(self._data_dir).resolve()
+        if resolved == data_resolved or not resolved.is_relative_to(data_resolved):
+            logger.error("Refusing to delete path outside data_dir: %s", resolved)
+            return
+        shutil.rmtree(path, True)
+
    def _allocate_port(self) -> int:
        """Find a free port starting from _next_port."""
        for _ in range(100):
@@ -159,6 +171,11 @@ class ChromePool:
            seed_key = "__default__"
            actual_seed = str(random.randint(10000, 99999))
        else:
+            if not SAFE_SEED_RE.match(seed) or seed in RESERVED_SEEDS:
+                raise web.HTTPBadRequest(
+                    text=json.dumps({"error": "Invalid fingerprint seed"}),
+                    content_type="application/json",
+                )
            seed_key = seed
            actual_seed = seed

@@ -189,7 +206,7 @@ class ChromePool:
            if extra_args:
                fp_extra.extend(extra_args)
            if proxy:
-                fp_extra.append(f"--proxy-server={proxy}")
+                fp_extra.append(f"--proxy-server={_normalize_socks_string_url(proxy)}")

            # WebRTC IP spoofing: resolve auto, inject geoip exit IP
            fp_extra = _resolve_webrtc_args(fp_extra, proxy)
@@ -232,7 +249,7 @@ class ChromePool:
            if not await self._wait_for_cdp(port):
                process.kill()
                await asyncio.to_thread(process.wait, timeout=5)
-                await asyncio.to_thread(shutil.rmtree, user_data_dir, True)
+                await asyncio.to_thread(self._safe_rmtree, user_data_dir)
                raise web.HTTPBadGateway(
                    text=json.dumps({"error": "Chrome failed to start"}),
                    content_type="application/json",
@@ -266,8 +283,7 @@ class ChromePool:
                await asyncio.to_thread(proc.process.wait, timeout=5)
            except subprocess.TimeoutExpired:
                proc.process.kill()
-        # Clean up user data dir (can be slow for large profiles)
-        await asyncio.to_thread(shutil.rmtree, proc.user_data_dir, True)
+        await asyncio.to_thread(self._safe_rmtree, proc.user_data_dir)
        if self._default is proc:
            self._default = None
        self._locks.pop(key, None)
@@ -559,8 +575,8 @@ async def on_shutdown(app: web.Application) -> None:
 # ---------------------------------------------------------------------------

 def _default_data_dir() -> str:
-    """Smart default: Docker → /tmp/cloakserve, bare metal → ~/.cloakbrowser/cloakserve."""
-    if os.path.exists("/.dockerenv"):
+    """Smart default: container → /tmp/cloakserve, bare metal → ~/.cloakbrowser/cloakserve."""
+    if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
        return "/tmp/cloakserve"
    return str(Path.home() / ".cloakbrowser" / "cloakserve")

@@ -624,6 +640,13 @@ def main() -> None:
    binary = ensure_binary()
    config, global_args = parse_cli_args(sys.argv[1:])

+    if config["default_seed"] and (
+        not SAFE_SEED_RE.match(config["default_seed"])
+        or config["default_seed"] in RESERVED_SEEDS
+    ):
+        logger.error("Invalid --fingerprint seed: %s", config["default_seed"])
+        sys.exit(1)
+
    pool = ChromePool(
        binary=binary,
        global_args=global_args,
@@ -662,7 +685,9 @@ def main() -> None:
        port,
    )

-    web.run_app(app, host="0.0.0.0", port=port, print=None)
+    in_container = os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv")
+    host = "0.0.0.0" if in_container else "127.0.0.1"
+    web.run_app(app, host=host, port=port, print=None)


 if __name__ == "__main__":
@@ -11,7 +11,7 @@ Usage:
    browser.close()
 """

-from .browser import launch, launch_async, launch_context, launch_persistent_context, launch_persistent_context_async, ProxySettings, build_args, maybe_resolve_geoip
+from .browser import launch, launch_async, launch_context, launch_context_async, launch_persistent_context, launch_persistent_context_async, ProxySettings, build_args, maybe_resolve_geoip
 from .config import CHROMIUM_VERSION, get_default_stealth_args
 from .download import binary_info, check_for_update, clear_cache, ensure_binary
 from ._version import __version__
@@ -32,6 +32,7 @@ __all__ = [
    "launch",
    "launch_async",
    "launch_context",
+    "launch_context_async",
    "launch_persistent_context",
    "launch_persistent_context_async",
    "ensure_binary",
@@ -1 +1 @@
-__version__ = "0.3.23"
+__version__ = "0.3.28"
@@ -21,9 +21,11 @@ from urllib.parse import quote, unquote, urlparse, urlunparse

 from .config import DEFAULT_VIEWPORT, IGNORE_DEFAULT_ARGS, get_default_stealth_args
 from .download import ensure_binary
+from .human.config import HumanConfigOverrides, HumanPreset

 logger = logging.getLogger("cloakbrowser")

+
 # Sentinel to distinguish "viewport not provided" from "viewport=None" (disable emulation)
 _VIEWPORT_UNSET = object()

@@ -60,8 +62,8 @@ def launch(
    geoip: bool = False,
    backend: str | None = None,
    humanize: bool = False,
-    human_preset: str = "default",
-    human_config: dict | None = None,
+    human_preset: HumanPreset = "default",
+    human_config: HumanConfigOverrides | None = None,
    **kwargs: Any,
 ) -> Any:
    """Launch stealth Chromium browser. Returns a Playwright Browser object.
@@ -87,7 +89,7 @@ def launch(
            Override globally with CLOAKBROWSER_BACKEND env var.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
-        human_config: Custom humanize config dict to override preset values.
+        human_config: Custom humanize config mapping to override preset values.
        **kwargs: Passed directly to playwright.chromium.launch().

    Returns:
@@ -155,8 +157,8 @@ async def launch_async(  # noqa: C901
    geoip: bool = False,
    backend: str | None = None,
    humanize: bool = False,
-    human_preset: str = "default",
-    human_config: dict | None = None,
+    human_preset: HumanPreset = "default",
+    human_config: HumanConfigOverrides | None = None,
    **kwargs: Any,
 ) -> Any:
    """Async version of launch(). Returns a Playwright Browser object.
@@ -172,7 +174,7 @@ async def launch_async(  # noqa: C901
        backend: Playwright backend — 'playwright' (default) or 'patchright'.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
-        human_config: Custom humanize config dict to override preset values.
+        human_config: Custom humanize config mapping to override preset values.
        **kwargs: Passed directly to playwright.chromium.launch().

    Returns:
@@ -249,8 +251,8 @@ def launch_persistent_context(
    geoip: bool = False,
    backend: str | None = None,
    humanize: bool = False,
-    human_preset: str = "default",
-    human_config: dict | None = None,
+    human_preset: HumanPreset = "default",
+    human_config: HumanConfigOverrides | None = None,
    **kwargs: Any,
 ) -> Any:
    """Launch stealth browser with a persistent profile and return a BrowserContext.
@@ -279,7 +281,7 @@ def launch_persistent_context(
        backend: Playwright backend — 'playwright' (default) or 'patchright'.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
-        human_config: Custom humanize config dict to override preset values.
+        human_config: Custom humanize config mapping to override preset values.
        **kwargs: Passed directly to playwright.chromium.launch_persistent_context().

    Returns:
@@ -373,8 +375,8 @@ async def launch_persistent_context_async(
    geoip: bool = False,
    backend: str | None = None,
    humanize: bool = False,
-    human_preset: str = "default",
-    human_config: dict | None = None,
+    human_preset: HumanPreset = "default",
+    human_config: HumanConfigOverrides | None = None,
    **kwargs: Any,
 ) -> Any:
    """Async version of launch_persistent_context().
@@ -400,7 +402,7 @@ async def launch_persistent_context_async(
        backend: Playwright backend — 'playwright' (default) or 'patchright'.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
-        human_config: Custom humanize config dict to override preset values.
+        human_config: Custom humanize config mapping to override preset values.
        **kwargs: Passed directly to playwright.chromium.launch_persistent_context().

    Returns:
@@ -498,8 +500,8 @@ def launch_context(
    geoip: bool = False,
    backend: str | None = None,
    humanize: bool = False,
-    human_preset: str = "default",
-    human_config: dict | None = None,
+    human_preset: HumanPreset = "default",
+    human_config: HumanConfigOverrides | None = None,
    **kwargs: Any,
 ) -> Any:
    """Launch stealth browser and return a BrowserContext with common options pre-set.
@@ -523,7 +525,7 @@ def launch_context(
        backend: Playwright backend — 'playwright' (default) or 'patchright'.
        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
-        human_config: Custom humanize config dict to override preset values.
+        human_config: Custom humanize config mapping to override preset values.
        **kwargs: Passed to browser.new_context().

    Returns:
@@ -584,6 +586,130 @@ def launch_context(
    return context


+async def launch_context_async(
+    headless: bool = True,
+    proxy: str | ProxySettings | None = None,
+    args: list[str] | None = None,
+    stealth_args: bool = True,
+    user_agent: str | None = None,
+    viewport: dict | None = _VIEWPORT_UNSET,
+    locale: str | None = None,
+    timezone: str | None = None,
+    color_scheme: Literal["light", "dark", "no-preference"] | None = None,
+    geoip: bool = False,
+    backend: str | None = None,
+    humanize: bool = False,
+    human_preset: HumanPreset = "default",
+    human_config: HumanConfigOverrides | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Async version of launch_context().
+
+    Launch stealth browser and return a BrowserContext with common options pre-set.
+    All extra kwargs are forwarded to ``browser.new_context()`` — use this for
+    ``storage_state``, ``permissions``, ``extra_http_headers``, etc. without needing
+    a persistent profile folder.
+
+    Args:
+        headless: Run in headless mode (default True).
+        proxy: Proxy URL string or Playwright proxy dict (see launch() for details).
+        args: Additional Chromium CLI arguments.
+        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}.
+            Pass None to disable viewport emulation (use OS window size).
+        locale: Browser locale, e.g. "en-US".
+        timezone: IANA timezone (e.g. 'America/New_York').
+        color_scheme: Color scheme preference — 'light', 'dark', or 'no-preference'.
+        geoip: Auto-detect timezone/locale from proxy IP (default False).
+        backend: Playwright backend — 'playwright' (default) or 'patchright'.
+        humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
+        human_preset: Humanize preset — 'default' or 'careful' (default 'default').
+        human_config: Custom humanize config mapping to override preset values.
+        **kwargs: Passed to browser.new_context() — e.g. storage_state, permissions.
+
+    Returns:
+        Playwright BrowserContext object (async API).
+        Call ``await .close()`` when done — this also closes the underlying browser.
+
+    Example:
+        >>> import asyncio
+        >>> from cloakbrowser import launch_context_async
+        >>>
+        >>> async def main():
+        ...     # Load saved session (cookies, localStorage)
+        ...     ctx = await launch_context_async(
+        ...         headless=True,
+        ...         storage_state="state.json",
+        ...     )
+        ...     page = await ctx.new_page()
+        ...     await page.goto("https://example.com")
+        ...     # Save state back
+        ...     await ctx.storage_state(path="state.json")
+        ...     await ctx.close()
+        >>>
+        >>> asyncio.run(main())
+    """
+    timezone = _resolve_timezone(timezone, kwargs)
+
+    # Resolve geoip BEFORE launch_async() to avoid double-resolution and ensure
+    # resolved values flow to binary flags
+    timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
+    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}")
+    # --fingerprint-timezone is process-wide (reads CommandLine in renderer),
+    # 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)
+
+    context_kwargs: dict[str, Any] = {}
+    if user_agent:
+        context_kwargs["user_agent"] = user_agent
+    if viewport is _VIEWPORT_UNSET:
+        context_kwargs["viewport"] = DEFAULT_VIEWPORT
+    elif viewport is None:
+        context_kwargs["no_viewport"] = True
+    else:
+        context_kwargs["viewport"] = viewport
+    if color_scheme:
+        context_kwargs["color_scheme"] = color_scheme
+    context_kwargs.update(kwargs)
+
+    # Catch BaseException (not just Exception) so that asyncio.CancelledError
+    # triggers browser cleanup — otherwise the underlying Chromium process
+    # leaks when the awaiting task is cancelled.
+    try:
+        context = await browser.new_context(**context_kwargs)
+    except BaseException:
+        try:
+            await browser.close()
+        except BaseException:
+            pass
+        raise
+
+    # Patch close() to also close the browser (and its Playwright instance)
+    _original_ctx_close = context.close
+
+    async def _close_context_with_cleanup() -> None:
+        try:
+            await _original_ctx_close()
+        finally:
+            await browser.close()
+
+    context.close = _close_context_with_cleanup
+
+    # Human-like behavioral patching (async variant)
+    if humanize:
+        from .human import patch_context_async
+        from .human.config import resolve_config
+        cfg = resolve_config(human_preset, human_config)
+        patch_context_async(context, cfg)
+
+    return context
+
+
 # ---------------------------------------------------------------------------
 # Backend resolution
 # ---------------------------------------------------------------------------
@@ -635,6 +761,37 @@ def _ensure_proxy_scheme(proxy_url: str) -> str:
    return proxy_url if "://" in proxy_url else f"http://{proxy_url}"


+def _assemble_socks_url(
+    scheme: str,
+    host: str,
+    port: int | None,
+    enc_user: str,
+    enc_pass: str | None,
+    path: str = "",
+    params: str = "",
+    query: str = "",
+    fragment: str = "",
+) -> str:
+    """Build a SOCKS URL from already-percent-encoded credentials and host parts.
+
+    ``enc_pass is None`` means no password (no colon in userinfo). Empty string
+    means present-but-empty (colon preserved). This mirrors the distinction
+    urlparse makes between ``user@host`` and ``user:@host``.
+    """
+    if ":" in host:  # IPv6 literal — re-add brackets
+        host = f"[{host}]"
+    if enc_pass is not None:
+        userinfo = f"{enc_user}:{enc_pass}@"
+    elif enc_user:
+        userinfo = f"{enc_user}@"
+    else:
+        userinfo = ""
+    netloc = f"{userinfo}{host}"
+    if port is not None:
+        netloc += f":{port}"
+    return urlunparse((scheme, netloc, path, params, query, fragment))
+
+
 def _reconstruct_socks_url(proxy: ProxySettings) -> str:
    """Reconstruct a SOCKS5 URL with inline credentials from a Playwright proxy dict."""
    server = proxy.get("server", "")
@@ -643,16 +800,63 @@ def _reconstruct_socks_url(proxy: ProxySettings) -> str:
    if not username:
        return server
    parsed = urlparse(server)
-    creds = quote(username, safe="")
-    if password:
-        creds += f":{quote(password, safe='')}"
-    host = parsed.hostname or ""
-    if ":" in host:  # IPv6 literal — re-add brackets
-        host = f"[{host}]"
-    netloc = f"{creds}@{host}"
-    if parsed.port:
-        netloc += f":{parsed.port}"
-    return urlunparse((parsed.scheme, netloc, parsed.path, "", "", ""))
+    enc_user = quote(username, safe="")
+    # Dict convention: empty/missing password → no colon.
+    enc_pass = quote(password, safe="") if password else None
+    return _assemble_socks_url(
+        parsed.scheme, parsed.hostname or "", parsed.port,
+        enc_user, enc_pass, parsed.path,
+    )
+
+
+def _normalize_socks_string_url(url: str) -> str:
+    """Re-encode credentials in a SOCKS5 URL string so Chromium's parser doesn't
+    truncate them at special chars like '='. Idempotent: pre-encoded input stays
+    the same (decoded then re-encoded).
+
+    Emits an INFO log when re-encoding actually changes the URL, so users who
+    previously hit silent SOCKS5 fallback (#157) can see what the wrapper did.
+    Silent on already-encoded inputs (no false-positive noise).
+
+    On unparseable input (invalid port, broken IPv6 literal, etc.) logs a
+    warning and returns the original string — preserves pre-fix pass-through
+    behavior so Chromium's own error handling kicks in.
+    """
+    try:
+        parsed = urlparse(url)
+        # Accessing .port raises ValueError on invalid port strings.
+        _ = parsed.port
+    except ValueError as e:
+        logger.warning("Malformed SOCKS5 proxy URL, passing through unchanged: %s", e)
+        return url
+    # Skip only if no credentials at all (username AND password both absent).
+    # urlparse returns None for absent components, "" for present-but-empty.
+    if parsed.username is None and parsed.password is None:
+        return url
+    raw_user = parsed.username or ""
+    enc_user = quote(unquote(raw_user), safe="") if raw_user else ""
+    # Preserve the colon separator when password component is present, even if
+    # empty, so `user:@host` stays `user:@host`.
+    if parsed.password is not None:
+        raw_pass = parsed.password
+        enc_pass = quote(unquote(raw_pass), safe="") if raw_pass else ""
+    else:
+        raw_pass = None
+        enc_pass = None
+    normalized = _assemble_socks_url(
+        parsed.scheme, parsed.hostname or "", parsed.port,
+        enc_user, enc_pass,
+        parsed.path, parsed.params, parsed.query, parsed.fragment,
+    )
+    # Compare credentials, not the full URL: urlparse cosmetically lowercases
+    # scheme and hostname, so a full-string compare would falsely fire on
+    # `socks5://USER:pass@HOST.com:1080` even when no encoding work happened.
+    if enc_user != raw_user or enc_pass != raw_pass:
+        logger.info(
+            "Auto URL-encoded SOCKS5 proxy credentials (special characters "
+            "detected). Pre-encode the URL to suppress this notice."
+        )
+    return normalized


 def _extract_proxy_url(proxy: str | ProxySettings | None) -> str | None:
@@ -687,7 +891,7 @@ def maybe_resolve_geoip(
    if not geoip or not proxy:
        return timezone, locale, None

-    from .geoip import resolve_proxy_geo_with_ip
+    from .geoip import resolve_proxy_exit_ip, resolve_proxy_geo_with_ip

    proxy_url = _extract_proxy_url(proxy)
    if not proxy_url:
@@ -695,8 +899,7 @@ def maybe_resolve_geoip(

    # When both tz/locale are explicit, still resolve exit IP for WebRTC
    if timezone is not None and locale is not None:
-        from .geoip import _resolve_exit_ip
-        exit_ip = _resolve_exit_ip(proxy_url)
+        exit_ip = resolve_proxy_exit_ip(proxy_url)
        return timezone, locale, exit_ip

    geo_tz, geo_locale, exit_ip = resolve_proxy_geo_with_ip(proxy_url)
@@ -731,8 +934,8 @@ def _resolve_webrtc_args(
        del args[idx]
        return args
    try:
-        from .geoip import _resolve_exit_ip
-        exit_ip = _resolve_exit_ip(proxy_url)
+        from .geoip import resolve_proxy_exit_ip
+        exit_ip = resolve_proxy_exit_ip(proxy_url)
    except Exception:
        logger.warning("Failed to resolve proxy exit IP for WebRTC spoofing; removing --fingerprint-webrtc-ip=auto")
        args = list(args)
@@ -801,11 +1004,14 @@ def build_args(


 def _parse_proxy_url(proxy: str) -> dict[str, Any]:
-    """Parse proxy URL, extracting credentials into separate Playwright fields.
+    """Parse HTTP(S) proxy URL, extracting credentials into separate Playwright fields.

    Handles: http://user:pass@host:port -> {server: "http://host:port", username: "user", password: "pass"}
-    Also handles: no credentials, URL-encoded special chars, socks5://, missing port,
+    Also handles: no credentials, URL-encoded special chars, missing port,
    and bare proxy strings without a scheme (e.g. 'user:pass@host:port' -> treated as http).
+
+    SOCKS5 URLs are NOT handled here — they take a dedicated path via
+    ``_normalize_socks_string_url`` in ``_resolve_proxy_config``.
    """
    # Bare format: "user:pass@host:port" — urlparse needs a scheme to extract credentials.
    normalized = proxy
@@ -863,8 +1069,9 @@ def _resolve_proxy_config(
            if proxy.get("bypass"):
                extra_args.append(f"--proxy-bypass-list={proxy['bypass']}")
            return {}, extra_args
-        # String URL — pass as-is (Chrome handles user:pass@ in the URL)
-        return {}, [f"--proxy-server={proxy}"]
+        # String URL — re-encode creds to work around Chromium parser truncating
+        # passwords at '=' and other special chars (#157).
+        return {}, [f"--proxy-server={_normalize_socks_string_url(proxy)}"]

    # HTTP/HTTPS: use Playwright's proxy dict as before
    if isinstance(proxy, dict):
@@ -15,14 +15,14 @@ from ._version import __version__
 # CHROMIUM_VERSION is the latest across all platforms (for display/reference).
 # Use get_chromium_version() for the current platform's actual version.
 # ---------------------------------------------------------------------------
-CHROMIUM_VERSION = "146.0.7680.177.1"
+CHROMIUM_VERSION = "146.0.7680.177.3"

 PLATFORM_CHROMIUM_VERSIONS: dict[str, str] = {
-    "linux-x64": "146.0.7680.177.1",
-    "linux-arm64": "145.0.7632.159.7",
+    "linux-x64": "146.0.7680.177.3",
+    "linux-arm64": "146.0.7680.177.3",
    "darwin-arm64": "145.0.7632.109.2",
    "darwin-x64": "145.0.7632.109.2",
-    "windows-x64": "145.0.7632.159.7",
+    "windows-x64": "146.0.7680.177.4",
 }

 # ---------------------------------------------------------------------------
@@ -60,7 +60,6 @@ def _show_welcome() -> None:
    sys.stderr.write("  CloakBrowser — stealth Chromium for automation\n")
    sys.stderr.write("  https://github.com/CloakHQ/CloakBrowser\n")
    sys.stderr.write("\n")
-    sys.stderr.write("  Issues?  https://github.com/CloakHQ/CloakBrowser/issues\n")
    sys.stderr.write("  Donate?  https://ko-fi.com/cloakhq\n")
    sys.stderr.write("  Star us if CloakBrowser helps your project!\n")
    sys.stderr.write("\n")
@@ -12,6 +12,8 @@ from __future__ import annotations

 import ipaddress
 import logging
+import math
+import os
 import socket
 import tempfile
 import threading
@@ -27,6 +29,8 @@ GEOIP_DB_URL = (
 )
 GEOIP_DB_FILENAME = "GeoLite2-City.mmdb"
 GEOIP_UPDATE_INTERVAL = 30 * 86_400  # 30 days
+DEFAULT_GEOIP_TIMEOUT_SECONDS = 5.0
+GEOIP_TIMEOUT_ENV = "CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS"

 # Country ISO code → BCP 47 locale (covers ~90 % of proxy traffic)
 COUNTRY_LOCALE_MAP: dict[str, str] = {
@@ -77,11 +81,16 @@ def resolve_proxy_geo_with_ip(
    if db_path is None:
        return None, None, None

+    timeout = _get_geoip_timeout_seconds()
+    deadline = _deadline_from_timeout(timeout)
+
    # Exit IP (through proxy) is most accurate — gateway DNS may differ from exit
-    ip = _resolve_exit_ip(proxy_url)
-    if ip is None:
+    ip = _resolve_exit_ip(proxy_url, timeout=_remaining_seconds(deadline))
+    if ip is None and not _deadline_expired(deadline):
        ip = _resolve_proxy_ip(proxy_url)
-    if ip is None:
+    if ip is None or _deadline_expired(deadline):
+        if deadline is not None and _deadline_expired(deadline):
+            logger.warning("GeoIP resolution timed out after %.1fs; continuing without GeoIP", timeout)
        return None, None, None

    try:
@@ -152,13 +161,64 @@ _IP_ECHO_URLS = [
 ]


-def _resolve_exit_ip(proxy_url: str) -> str | None:
+def _get_geoip_timeout_seconds() -> float:
+    raw = os.getenv(GEOIP_TIMEOUT_ENV)
+    if not raw:
+        return DEFAULT_GEOIP_TIMEOUT_SECONDS
+    try:
+        timeout = float(raw)
+    except ValueError:
+        timeout = float("nan")
+    if not math.isfinite(timeout):
+        logger.warning(
+            "Invalid %s=%r; using %.1fs",
+            GEOIP_TIMEOUT_ENV,
+            raw,
+            DEFAULT_GEOIP_TIMEOUT_SECONDS,
+        )
+        return DEFAULT_GEOIP_TIMEOUT_SECONDS
+    return max(timeout, 0.0)
+
+
+def _deadline_from_timeout(timeout: float) -> float | None:
+    if timeout <= 0:
+        return None
+    return time.monotonic() + timeout
+
+
+def _remaining_seconds(deadline: float | None) -> float | None:
+    if deadline is None:
+        return None
+    return max(deadline - time.monotonic(), 0.0)
+
+
+def _deadline_expired(deadline: float | None) -> bool:
+    return deadline is not None and time.monotonic() >= deadline
+
+
+def resolve_proxy_exit_ip(proxy_url: str) -> str | None:
+    """Resolve only the proxy exit IP, bounded by the GeoIP timeout."""
+    timeout = _get_geoip_timeout_seconds()
+    deadline = _deadline_from_timeout(timeout)
+    ip = _resolve_exit_ip(proxy_url, timeout=timeout)
+    if ip is None and _deadline_expired(deadline):
+        logger.warning("GeoIP resolution timed out after %.1fs; continuing without GeoIP", timeout)
+    return ip
+
+
+def _resolve_exit_ip(proxy_url: str, timeout: float | None = None) -> str | None:
    """Discover the proxy's actual exit IP by connecting through it."""
    import httpx

+    deadline = _deadline_from_timeout(timeout or 0)
+
    for url in _IP_ECHO_URLS:
        try:
-            resp = httpx.get(url, proxy=proxy_url, timeout=10.0)
+            remaining = _remaining_seconds(deadline)
+            if remaining is not None and remaining <= 0:
+                return None
+            request_timeout = min(10.0, remaining) if remaining is not None else 10.0
+            resp = httpx.get(url, proxy=proxy_url, timeout=request_timeout)
            resp.raise_for_status()
            ip = resp.text.strip()
            # Validate it looks like an IP
@@ -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
@@ -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
@@ -10,7 +10,7 @@ import math
 import random
 import time
 from dataclasses import dataclass, field
-from typing import Literal, Tuple
+from typing import Literal, Tuple, TypedDict

 # ---------------------------------------------------------------------------
 # Type alias
@@ -20,6 +20,50 @@ Range = Tuple[float, float]
 HumanPreset = Literal["default", "careful"]


+class HumanConfigOverrides(TypedDict, total=False):
+    typing_delay: float
+    typing_delay_spread: float
+    typing_pause_chance: float
+    typing_pause_range: Range
+    shift_down_delay: Range
+    shift_up_delay: Range
+    key_hold: Range
+    field_switch_delay: Range
+    mistype_chance: float
+    mistype_delay_notice: Range
+    mistype_delay_correct: Range
+    mouse_steps_divisor: float
+    mouse_min_steps: int
+    mouse_max_steps: int
+    mouse_wobble_max: float
+    mouse_overshoot_chance: float
+    mouse_overshoot_px: Range
+    mouse_burst_size: Range
+    mouse_burst_pause: Range
+    click_aim_delay_input: Range
+    click_aim_delay_button: Range
+    click_hold_input: Range
+    click_hold_button: Range
+    click_input_x_range: Range
+    idle_drift_px: float
+    idle_pause_range: Range
+    scroll_delta_base: Range
+    scroll_delta_variance: float
+    scroll_pause_fast: Range
+    scroll_pause_slow: Range
+    scroll_accel_steps: Range
+    scroll_decel_steps: Range
+    scroll_overshoot_chance: float
+    scroll_overshoot_px: Range
+    scroll_settle_delay: Range
+    scroll_target_zone: Range
+    scroll_pre_move_delay: Range
+    initial_cursor_x: Range
+    initial_cursor_y: Range
+    idle_between_actions: bool
+    idle_between_duration: Range
+
+
 # ---------------------------------------------------------------------------
 # Configuration dataclass
 # ---------------------------------------------------------------------------
@@ -130,13 +174,13 @@ _PRESETS: dict[str, HumanConfig] = {

 def resolve_config(
    preset: HumanPreset = "default",
-    overrides: dict | None = None,
+    overrides: HumanConfigOverrides | None = None,
 ) -> HumanConfig:
    """Resolve a preset name + optional overrides into a full HumanConfig.

    Args:
        preset: 'default' or 'careful'.
-        overrides: Dict of field names to override values.
+        overrides: Typed mapping of HumanConfig field names to override values.

    Returns:
        A new HumanConfig instance.
@@ -157,6 +201,25 @@ def resolve_config(
    return HumanConfig(**merged)


+def merge_config(base: HumanConfig, overrides: dict | None) -> HumanConfig:
+    """Merge ``overrides`` (a dict of HumanConfig field names → values) on top of
+    ``base``. Returns a new HumanConfig — ``base`` is never mutated.
+
+    Used by per-call overrides like ``page.type(sel, text, human_config={...})``
+    so the same page can use different timings for different inputs without
+    re-patching.
+
+    Unknown keys are ignored silently to keep this forgiving for callers.
+    """
+    if not overrides:
+        return base
+    merged = {k: getattr(base, k) for k in base.__dataclass_fields__}
+    for k, v in overrides.items():
+        if k in base.__dataclass_fields__:
+            merged[k] = v
+    return HumanConfig(**merged)
+
+
 # ---------------------------------------------------------------------------
 # Utility functions
 # ---------------------------------------------------------------------------
@@ -4,7 +4,7 @@ from __future__ import annotations

 import math
 import random
-from typing import Any, Optional, Tuple
+from typing import Any, Callable, Optional, Tuple

 from .config import HumanConfig, rand, rand_range, rand_int_range, sleep_ms
 from .mouse import RawMouse, human_move
@@ -18,10 +18,15 @@ def _is_in_viewport(bounds: dict, viewport_height: int, cfg: HumanConfig) -> boo
    return top_edge >= zone_top and bottom_edge <= zone_bottom


-def _get_element_box(page: Any, selector: str) -> Optional[dict]:
+def _get_element_box(page: Any, selector: str, timeout: float = 30000) -> Optional[dict]:
+    """Locate ``selector`` and return its bounding box.
+
+    The ``timeout`` is forwarded to Playwright's ``boundingBox(timeout=...)``
+    so callers can extend it for slow-loading elements (#172).
+    """
    try:
        el = page.locator(selector).first
-        return el.bounding_box(timeout=2000)
+        return el.bounding_box(timeout=max(1, timeout))
    except Exception:
        return None

@@ -39,13 +44,24 @@ def _smooth_wheel(raw: RawMouse, delta: int, cfg: HumanConfig) -> None:
        sleep_ms(rand(8, 20))


-def scroll_to_element(
+def human_scroll_into_view(
    page: Any,
    raw: RawMouse,
-    selector: str,
+    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.
+
+    Used both by ``scroll_to_element`` (selector-based) and by
+    ``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:
        raise RuntimeError("Viewport size not available")
@@ -53,15 +69,12 @@ def scroll_to_element(
    viewport_height = viewport["height"]
    viewport_width = viewport["width"]

-    box = _get_element_box(page, selector)
+    box = get_box()
    if box is None:
-        sleep_ms(200)
-        box = _get_element_box(page, selector)
-        if box is None:
-            raise RuntimeError(f"Element not found: {selector}")
+        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))
@@ -105,7 +118,7 @@ def scroll_to_element(

        # Check visibility every 3 steps
        if i % 3 == 2 or i == total_clicks - 1:
-            box = _get_element_box(page, selector)
+            box = get_box()
            if box and _is_in_viewport(box, viewport_height, cfg):
                break
        if scrolled >= abs_distance * 1.1:
@@ -125,8 +138,31 @@ def scroll_to_element(
    # Settle
    sleep_ms(rand_range(cfg.scroll_settle_delay))

-    box = _get_element_box(page, selector)
+    box = get_box()
    if box is None:
-        raise RuntimeError(f"Element lost after scrolling: {selector}")
+        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(
+    page: Any,
+    raw: RawMouse,
+    selector: str,
+    cursor_x: float, cursor_y: float,
+    cfg: HumanConfig,
+    timeout: float = 30000,
+) -> 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,
+        lambda: _get_element_box(page, selector, timeout),
+        cursor_x, cursor_y, cfg,
+    )
@@ -8,17 +8,22 @@ from __future__ import annotations

 import math
 import random
-from typing import Any, Optional, Tuple
+from typing import Any, Awaitable, Callable, Optional, Tuple

 from .config import HumanConfig, rand, rand_range, rand_int_range, async_sleep_ms
 from .mouse_async import AsyncRawMouse, async_human_move
 from .scroll import _is_in_viewport


-async def _get_element_box_async(page: Any, selector: str) -> Optional[dict]:
+async def _get_element_box_async(
+    page: Any, selector: str, timeout: float = 30000,
+) -> Optional[dict]:
+    """Async variant. ``timeout`` is forwarded to Playwright's
+    ``boundingBox(timeout=...)`` so callers can extend it for slow-loading
+    elements (#172)."""
    try:
        el = page.locator(selector).first
-        return await el.bounding_box(timeout=2000)
+        return await el.bounding_box(timeout=max(1, timeout))
    except Exception:
        return None

@@ -36,13 +41,23 @@ async def _async_smooth_wheel(raw: AsyncRawMouse, delta: int, cfg: HumanConfig)
        await async_sleep_ms(rand(8, 20))


-async def async_scroll_to_element(
+async def async_human_scroll_into_view(
    page: Any,
    raw: AsyncRawMouse,
-    selector: str,
+    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:
        raise RuntimeError("Viewport size not available")
@@ -50,15 +65,12 @@ async def async_scroll_to_element(
    viewport_height = viewport["height"]
    viewport_width = viewport["width"]

-    box = await _get_element_box_async(page, selector)
+    box = await get_box()
    if box is None:
-        await async_sleep_ms(200)
-        box = await _get_element_box_async(page, selector)
-        if box is None:
-            raise RuntimeError(f"Element not found: {selector}")
+        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))
@@ -102,7 +114,7 @@ async def async_scroll_to_element(

        # Check visibility every 3 steps
        if i % 3 == 2 or i == total_clicks - 1:
-            box = await _get_element_box_async(page, selector)
+            box = await get_box()
            if box and _is_in_viewport(box, viewport_height, cfg):
                break
        if scrolled >= abs_distance * 1.1:
@@ -122,8 +134,31 @@ async def async_scroll_to_element(
    # Settle
    await async_sleep_ms(rand_range(cfg.scroll_settle_delay))

-    box = await _get_element_box_async(page, selector)
+    box = await get_box()
    if box is None:
-        raise RuntimeError(f"Element lost after scrolling: {selector}")
+        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(
+    page: Any,
+    raw: AsyncRawMouse,
+    selector: str,
+    cursor_x: float, cursor_y: float,
+    cfg: HumanConfig,
+    timeout: float = 30000,
+) -> 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)
+    return await async_human_scroll_into_view(
+        page, raw, _get, cursor_x, cursor_y, cfg,
+    )
@@ -0,0 +1,79 @@
+# CloakBrowser on AWS Lambda — derived from the official CloakHQ image.
+#
+# `FROM cloakhq/cloakbrowser:<tag>` is an official distribution channel under
+# the CloakBrowser Binary License — pulling it isn't redistribution. We just
+# layer Lambda glue on top: the Lambda Runtime Interface Client (awslambdaric),
+# the Lambda Runtime Interface Emulator (for local `docker run` testing), the
+# dual-mode entrypoint, and the handler module.
+#
+# This directory is self-contained — copy/clone it anywhere and build from
+# inside it. No files outside this directory are referenced.
+#
+# ─── Lambda invocation (default CMD) ──────────────────────────────────────────
+#   # From inside this directory:
+#   docker buildx build --platform linux/arm64 -t cloakbrowser-lambda:arm64 --load .
+#
+#   # Or from a parent dir, pointing at this directory as the build context:
+#   docker buildx build --platform linux/arm64 \
+#     -f path/to/aws_lambda/Dockerfile -t cloakbrowser-lambda:arm64 --load \
+#     path/to/aws_lambda
+#
+#   docker run --rm -p 9000:8080 cloakbrowser-lambda:arm64
+#   curl -XPOST http://localhost:9000/2015-03-31/functions/function/invocations \
+#     -d '{"url":"https://example.com"}'
+#
+# ─── Same as the canonical CloakHQ image (CMD overridden) ─────────────────────
+#   docker run --rm -it cloakbrowser-lambda:arm64 python                          # REPL
+#   docker run --rm cloakbrowser-lambda:arm64 python examples/basic.py            # examples
+#   docker run --rm -p 9222:9222 cloakbrowser-lambda:arm64 cloakserve --port=9222 # CDP server
+#   docker run --rm cloakbrowser-lambda:arm64 cloaktest                           # stealth tests
+#   docker run --rm -it cloakbrowser-lambda:arm64 node                            # JS wrapper
+#   docker run --rm -it cloakbrowser-lambda:arm64 bash                            # shell
+#
+# Pin a specific tag (e.g. cloakhq/cloakbrowser:0.3.25) for reproducible builds;
+# `latest` floats with CloakHQ's release cadence.
+
+FROM cloakhq/cloakbrowser:latest
+
+# ─── Lambda Runtime Interface Client ──────────────────────────────────────────
+RUN pip install --no-cache-dir awslambdaric
+
+# ─── Lambda Runtime Interface Emulator (local `docker run` testing) ───────────
+# Bundled into the image so users can hit the standard local-invoke endpoint
+# without mounting the RIE separately. TARGETARCH is provided by buildx.
+ARG TARGETARCH
+ADD https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie-${TARGETARCH} \
+    /usr/local/bin/aws-lambda-rie
+RUN chmod +x /usr/local/bin/aws-lambda-rie
+
+# ─── Lambda glue ──────────────────────────────────────────────────────────────
+# Dual-mode entrypoint replaces the canonical bin/docker-entrypoint.sh: same
+# Xvfb startup, plus routing for `module.func` CMDs through awslambdaric.
+COPY lambda-entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Handler sits at /app (already on Python's import path in the canonical image,
+# WORKDIR=/app), imports cloakbrowser as a normal library.
+COPY lambda_handler.py /app/lambda_handler.py
+
+# ─── Lambda non-root readability fix ──────────────────────────────────────────
+# The canonical image bakes the Chromium binary at /root/.cloakbrowser/ (root's
+# HOME at build time). Lambda runs the container as a non-root user that can't
+# read /root by default (mode 750). Make the whole binary tree world-readable
+# and traversable. Also restore the .welcome_shown marker the canonical image
+# rm's (Lambda's read-only runtime FS can't recreate it, so the welcome would
+# print to CloudWatch on every cold start otherwise).
+RUN touch /root/.cloakbrowser/.welcome_shown \
+    && chmod -R o+rX /root /root/.cloakbrowser
+
+# ─── Lambda runtime env ───────────────────────────────────────────────────────
+# HOME=/tmp gives Chromium a writable scratch dir (Lambda only allows writes
+# under /tmp). CLOAKBROWSER_CACHE_DIR points at the baked binary location since
+# HOME=/tmp would otherwise make get_cache_dir() resolve to /tmp/.cloakbrowser
+# (empty). Auto-update is disabled because the runtime FS is read-only.
+ENV HOME=/tmp \
+    CLOAKBROWSER_CACHE_DIR=/root/.cloakbrowser \
+    CLOAKBROWSER_AUTO_UPDATE=false
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["lambda_handler.handler"]
@@ -0,0 +1,181 @@
+# CloakBrowser on AWS Lambda
+
+Run stealth Chromium one-shot scrapes inside an AWS Lambda function (container image package type). The image derives directly from the official CloakHQ Docker Hub image (`cloakhq/cloakbrowser`) and adds Lambda runtime support on top — Lambda is an additional invocation surface, not a replacement. Every other surface from the canonical image (`python`, `cloakserve`, `cloaktest`, `node`, `bash`, examples) keeps working.
+
+This document covers what the image is, how to build and locally test it, and the event/response contract. **It does not prescribe a deployment method** — push the resulting image to ECR and create the Lambda function however you prefer (AWS CLI, CDK, Terraform, SAM, console, etc.). Configuration tips for whichever tool you use are at the bottom.
+
+## Files in this directory
+
+| File | Purpose |
+|---|---|
+| `Dockerfile` | `FROM cloakhq/cloakbrowser` plus a thin Lambda layer. Self-contained — no files outside this directory are referenced. |
+| `lambda-entrypoint.sh` | Dual-mode entrypoint. Starts Xvfb, then routes `module.func` CMDs through `awslambdaric` (via the bundled `aws-lambda-rie` locally, or the AWS Runtime API in production), and execs everything else (`python`, `cloakserve`, `cloaktest`, `node`, `bash`) directly. |
+| `lambda_handler.py` | Default handler. Takes `{url, ...}`, returns `{title, url, html, screenshot_b64?}`. Always headed via Xvfb. |
+| `INSTRUCTIONS.md` | This file. |
+
+The Lambda layer is ~30 lines on top of the official image — no apt list, no Node install, no JS-wrapper build, no Chromium download. The canonical CloakHQ image owns those.
+
+This directory is **standalone**: copy or clone it anywhere (its own repo, a subdirectory of an existing project, a CI artifact bundle) and the build still works. It depends only on the upstream `cloakhq/cloakbrowser` image on Docker Hub and the `aws-lambda-rie` binary on GitHub Releases — both fetched at build time.
+
+## Build
+
+From inside this directory:
+
+```bash
+docker buildx build --platform linux/arm64 -t cloakbrowser-lambda:arm64 --load .
+```
+
+Or from anywhere, pointing at this directory as the build context:
+
+```bash
+docker buildx build --platform linux/arm64 \
+  -f path/to/aws_lambda/Dockerfile \
+  -t cloakbrowser-lambda:arm64 --load \
+  path/to/aws_lambda
+```
+
+The build pulls `cloakhq/cloakbrowser:latest` from Docker Hub and adds the Lambda layer on top. Pin a specific tag (e.g. `cloakhq/cloakbrowser:0.3.25`) in the `FROM` line for reproducible builds; `latest` floats with the upstream release cadence.
+
+For x86_64, switch `--platform linux/amd64` (slower on Apple Silicon under emulation).
+
+## Local smoke test (no AWS account needed)
+
+> **What's the RIE?** Lambda container images can't be run with a plain `docker run` — they expect to talk to AWS's Runtime API (the HTTP service Lambda exposes inside its sandbox to deliver events and collect responses). AWS publishes a small binary called the **Runtime Interface Emulator** that stands up a fake Runtime API on localhost so you can test the container exactly the way Lambda will invoke it, without deploying. We bake the RIE into the image, and the dual-mode entrypoint uses it automatically when `AWS_LAMBDA_RUNTIME_API` isn't set (i.e. you're not running in real Lambda).
+
+The image bakes in `aws-lambda-rie`, so the standard Lambda local-invoke endpoint works without mounting anything:
+
+```bash
+docker run --rm -p 9000:8080 cloakbrowser-lambda:arm64
+
+# In another shell:
+curl -sS -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" \
+  -d '{"url":"https://example.com"}'
+```
+
+Other invocation surfaces stay intact (these match the canonical CloakHQ image):
+
+```bash
+docker run --rm -it cloakbrowser-lambda:arm64 python                          # REPL
+docker run --rm cloakbrowser-lambda:arm64 python examples/basic.py            # examples
+docker run --rm -p 9222:9222 cloakbrowser-lambda:arm64 cloakserve --port=9222 # CDP server
+docker run --rm cloakbrowser-lambda:arm64 cloaktest                           # stealth tests
+docker run --rm -it cloakbrowser-lambda:arm64 node                            # JS wrapper
+```
+
+## Event schema
+
+Only `url` is required. Everything else is optional.
+
+### Launch options (forwarded to `cloakbrowser.launch_context_async`)
+
+| Field | Type | Default |
+|---|---|---|
+| `url` | str | required |
+| `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"` |
+| `geoip` | bool | `false` — auto timezone+locale from proxy IP |
+| `timezone` | str | none — IANA tz, e.g. `"America/New_York"` |
+| `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
+
+| Field | Type | Default |
+|---|---|---|
+| `wait_until` | str | `"domcontentloaded"` — `load` / `domcontentloaded` / `networkidle` / `commit` |
+| `goto_timeout_ms` | int | `30000` |
+
+### Post-navigation waits
+
+`smart_wait` is the default when no other wait is specified. It polls `document.documentElement.outerHTML.length` and returns when the size hasn't changed for `dom_stable_ms`. Robust for at-scale scraping because it ignores network activity (analytics beacons, long-poll, websockets) that doesn't mutate the DOM — `wait_until: "networkidle"` is unreliable on modern SPAs for exactly this reason.
+
+| Field | Type | Default |
+|---|---|---|
+| `smart_wait` | bool | `true` if no other wait is set |
+| `dom_stable_ms` | int | `1500` |
+| `max_settle_ms` | int | `15000` |
+| `wait_for_load_state` | str | none — `load` / `domcontentloaded` / `networkidle` |
+| `wait_for_load_state_timeout_ms` | int | `30000` |
+| `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
+
+| Field | Type | Default |
+|---|---|---|
+| `screenshot` | bool | `true` |
+| `full_page_screenshot` | bool | `false` |
+
+### Retry orchestration
+
+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.
+
+| Field | Type | Default |
+|---|---|---|
+| `retries` | int | `1` — number of strategy-retry attempts after the first failure. Set to `0` to disable retry entirely. |
+
+Strategies (priority order — first match wins):
+
+| Error pattern | Strategy applied |
+|---|---|
+| `ERR_CERT_*` (any cert error) | `extra_args: ["--ignore-certificate-errors"]`, `goto_timeout_ms: 60000` |
+| `Timeout … exceeded` | `goto_timeout_ms: 90000`, `max_settle_ms: 25000` |
+| `ERR_CONNECTION_TIMED_OUT` | same as `Timeout … exceeded` |
+
+Errors that are **not retried** (no anonymous scraper can recover): `ERR_NAME_NOT_RESOLVED`, `ERR_SSL_PROTOCOL_ERROR`, `ERR_CONNECTION_REFUSED`, `ERR_HTTP_RESPONSE_CODE_FAILURE`. These bail immediately.
+
+On final failure, the raised `RuntimeError`'s message includes a `retry_history` block listing every attempt (strategy applied + error seen). Successful invocations return the standard response shape unchanged — no surprise fields when retries didn't fire.
+
+### Response
+
+```json
+{
+  "title": "...",
+  "url": "https://example.com/",
+  "html": "<!DOCTYPE html>...",
+  "screenshot_b64": "<base64 PNG>"
+}
+```
+
+## Lambda-specific Chromium hardening (baked in, do not remove)
+
+Two flags are forced on every launch by `lambda_handler.py`:
+
+- `--disable-dev-shm-usage` — Lambda's `/dev/shm` is ~64 MB; Chromium's renderer crashes mid-paint without this.
+- `--no-zygote` — Lambda's restricted process model can't fork from Chromium's zygote process; without this the browser launches but child renderers fail to spawn and the first `page.new_page()` raises `TargetClosedError`.
+
+## Function configuration recommendations
+
+Whatever tool you use to create the Lambda function (CLI, CDK, Terraform, SAM, console), apply these settings:
+
+| Setting | Value | Why |
+|---|---|---|
+| Package type | Image | Required — this is a container image, not a zip. |
+| Architecture | `arm64` | Roughly 20% cheaper than x86_64. Native build on Apple Silicon. Match the architecture you built for. |
+| Memory | 3008 MB | Memory in Lambda is tied to vCPU. Below ~1769 MB Chromium starts noticeably slower. |
+| Timeout | 120–180 s | Single-attempt scrapes complete in 3–15 s warm; under retry, a `Timeout`-class first failure (30 s default) plus a longer-budget retry (90 s) plus cleanup can total ~120-130 s. 180 s leaves headroom; below 120 s the function will time out before the retry completes. Cold-start init adds 5-10 s on top. |
+| Ephemeral storage (`/tmp`) | 1024 MB | Chromium profile dirs and screenshots can fill the 512 MB default. |
+| Networking | Default (no VPC) | Binary is baked in, no network needed at cold start. Add VPC + NAT only if your proxy egress requires it. |
+| Execution role | `AWSLambdaBasicExecutionRole` | Just CloudWatch Logs. Add more permissions only if your handler needs them. |
+
+## Cold start
+
+First invocation in a new container takes ~80–90 s (image extraction, Chromium binary mmap, JS engine warmup, no DNS/TLS caches). Subsequent warm invocations on the same container are 3–15 s.
+
+For latency-sensitive use cases: provision concurrency, schedule a CloudWatch/EventBridge warmer ping, or accept the cold tail.
+
+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.
+
+## 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.
@@ -0,0 +1,52 @@
+#!/bin/sh
+# Dual-mode entrypoint for the CloakBrowser Lambda image.
+#
+#   1. Always start Xvfb on :99 (same as the canonical bin/docker-entrypoint.sh)
+#      so headed Chromium works no matter how the container is invoked.
+#   2. Detect whether the CMD looks like a Lambda handler (a single
+#      `module.func`-shaped argument). If yes, route through the Lambda runtime
+#      client (using the bundled aws-lambda-rie locally, or talking to the real
+#      Lambda Runtime API when AWS_LAMBDA_RUNTIME_API is set in production).
+#   3. Otherwise exec the CMD directly — preserving the canonical Dockerfile's
+#      interaction surface (`python`, `cloakserve`, `cloaktest`, `node`, `bash`,
+#      `python examples/basic.py`, etc.).
+set -e
+
+mkdir -p /tmp/.X11-unix
+chmod 1777 /tmp/.X11-unix 2>/dev/null || true
+
+# Clean any stale Xvfb state. If a previous Xvfb died and left its lock file
+# behind (we observed this in cold-start storms), a new Xvfb refuses to start
+# with "Server is already active for display 99". Removing both files makes
+# Xvfb start cleanly every time.
+rm -f /tmp/.X99-lock /tmp/.X11-unix/X99
+
+Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp >/tmp/Xvfb.log 2>&1 &
+
+# Wait for the X11 socket to appear AND for Xvfb to be ready to serve. The
+# socket file appears at bind(), but listen() and the first accept() come
+# slightly later — under cold-start CPU contention this gap matters.
+i=0
+while [ ! -e /tmp/.X11-unix/X99 ] && [ "$i" -lt 200 ]; do
+    i=$((i + 1))
+    sleep 0.05
+done
+# Small buffer after the socket appears so Xvfb has a moment to call listen()
+# and start accepting clients. Cheap insurance against the bind/listen gap.
+sleep 0.2
+
+# Lambda handler shape: exactly one arg, dotted identifier (no spaces, no slashes,
+# no leading dot). `python`, `cloakserve`, `cloaktest`, `bash`, `node` all fail
+# this test and pass through to plain exec.
+if [ $# -eq 1 ] && \
+   echo "$1" | grep -qE '^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$'; then
+    if [ -z "${AWS_LAMBDA_RUNTIME_API}" ]; then
+        # Local invocation via bundled RIE.
+        exec /usr/local/bin/aws-lambda-rie /usr/local/bin/python -m awslambdaric "$@"
+    else
+        # Real Lambda — runtime API endpoint already provided by the platform.
+        exec /usr/local/bin/python -m awslambdaric "$@"
+    fi
+fi
+
+exec "$@"
@@ -0,0 +1,336 @@
+"""AWS Lambda handler for one-off stealth-browser invocations.
+
+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
+        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"
+        geoip               bool             False — auto timezone+locale from proxy IP
+        timezone            str              IANA tz, e.g. "America/New_York"
+        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"
+                                              default "domcontentloaded"
+        goto_timeout_ms     int              30000
+
+    Post-navigation waits (run in this order if specified):
+        smart_wait                       bool ON by default if no other wait is set.
+                                              Polls document.outerHTML.length and bails when it
+                                              hasn't changed for `dom_stable_ms`. Handles lazy
+                                              hydration, async chunks, and lazy images, and is
+                                              immune to analytics beacons / long-poll that keep
+                                              the network busy without mutating the DOM.
+        dom_stable_ms                    int  1500   — how long DOM must be quiet
+        max_settle_ms                    int  15000  — hard cap on smart_wait
+        wait_for_load_state              str  "load"|"domcontentloaded"|"networkidle"
+        wait_for_load_state_timeout_ms   int  30000
+        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:
+        screenshot              bool         True
+        full_page_screenshot    bool         False — capture entire scrollable page
+
+    Retry orchestration:
+        retries     int  default 1. Number of retry attempts after the first
+                          failure. Set to 0 to disable retries entirely (the
+                          handler will fail fast on the first error).
+                          Retried errors:
+                            ERR_CERT_*                -> retry with --ignore-certificate-errors
+                            Timeout exceeded          -> retry with goto_timeout_ms=90000, max_settle_ms=25000
+                            ERR_CONNECTION_TIMED_OUT  -> same as Timeout
+                          Not retried (unrecoverable): ERR_NAME_NOT_RESOLVED,
+                          ERR_SSL_PROTOCOL_ERROR, generic ERR_CONNECTION_REFUSED.
+                          On final failure, the error message includes a
+                          retry_history block with strategy + error per attempt.
+
+Returns:
+    {"title": ..., "url": ..., "html": ..., "screenshot_b64"?: ...}
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from cloakbrowser import launch_context_async
+
+logger = logging.getLogger("cloakbrowser.lambda")
+logger.setLevel(logging.INFO)
+
+
+def _diag_snapshot() -> str:
+    """Capture Xvfb status, Xvfb log, X11 socket state, and env for error reports."""
+    import os
+    parts = []
+    try:
+        r = subprocess.run(["pgrep", "-fa", "Xvfb"], capture_output=True, text=True)
+        parts.append(f"pgrep Xvfb: rc={r.returncode} stdout={r.stdout.strip()!r}")
+    except Exception as e:
+        parts.append(f"pgrep failed: {e}")
+    try:
+        r = subprocess.run(["ls", "-la", "/tmp/.X11-unix"], capture_output=True, text=True)
+        parts.append(f"ls /tmp/.X11-unix:\n{r.stdout}{r.stderr}")
+    except Exception as e:
+        parts.append(f"ls /tmp/.X11-unix failed: {e}")
+    try:
+        log = Path("/tmp/Xvfb.log").read_text()
+        parts.append(f"/tmp/Xvfb.log:\n{log}")
+    except Exception as e:
+        parts.append(f"Xvfb log unreadable: {e}")
+    parts.append(f"env: DISPLAY={os.environ.get('DISPLAY')!r} HOME={os.environ.get('HOME')!r}")
+    return "\n".join(parts)
+
+
+def handler(event: dict, context: Any) -> dict:
+    return asyncio.run(_run(event))
+
+
+def _build_launch_kwargs(event: dict) -> dict:
+    """Translate the event dict into kwargs for launch_context_async.
+
+    Only includes keys explicitly set in the event so cloakbrowser's defaults
+    (DEFAULT_VIEWPORT etc.) kick in when fields are absent — passing
+    viewport=None would *disable* viewport emulation, which we don't want.
+    """
+    kwargs: dict = {
+        "headless": False,  # always headed via Xvfb
+        "args": [
+            # Lambda /dev/shm is ~64 MB — Chromium crashes mid-render without this.
+            "--disable-dev-shm-usage",
+            # 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", []),
+        ],
+    }
+    for key in ("proxy", "humanize", "human_preset", "geoip",
+                "timezone", "locale", "viewport", "user_agent"):
+        if key in event:
+            kwargs[key] = event[key]
+    return kwargs
+
+
+async def _smart_wait(page, dom_stable_ms: int = 1500, max_settle_ms: int = 15000) -> None:
+    """Wait until the document HTML hasn't changed for `dom_stable_ms`.
+
+    Generic stopping condition for at-scale scraping when you can't tune
+    selectors per site. More robust than `networkidle` because it ignores
+    network activity that doesn't mutate the DOM (analytics beacons,
+    long-poll, websockets, web vitals streams).
+    """
+    js = f"""
+    (() => {{
+        if (!window.__cb_settle) {{
+            window.__cb_settle = {{ len: -1, since: Date.now() }};
+        }}
+        const cur = document.documentElement.outerHTML.length;
+        const s = window.__cb_settle;
+        if (cur !== s.len) {{
+            s.len = cur;
+            s.since = Date.now();
+            return false;
+        }}
+        return (Date.now() - s.since) >= {int(dom_stable_ms)};
+    }})()
+    """
+    try:
+        await page.wait_for_function(js, timeout=max_settle_ms, polling=200)
+    except Exception:
+        # Hit max_settle_ms cap — return what we have rather than fail the whole invoke
+        logger.warning("smart_wait hit max_settle_ms=%d cap", max_settle_ms)
+
+
+_EXPLICIT_WAIT_KEYS = (
+    "wait_for_load_state", "wait_for_selector", "wait_for_function", "wait_ms",
+)
+
+
+async def _post_nav_waits(page, event: dict) -> None:
+    """Run waits in priority order. smart_wait is the default unless the
+    caller asked for a more specific stopping condition."""
+    explicit = any(k in event for k in _EXPLICIT_WAIT_KEYS)
+    if event.get("smart_wait", not explicit):
+        await _smart_wait(
+            page,
+            dom_stable_ms=event.get("dom_stable_ms", 1500),
+            max_settle_ms=event.get("max_settle_ms", 15000),
+        )
+    if "wait_for_load_state" in event:
+        await page.wait_for_load_state(
+            event["wait_for_load_state"],
+            timeout=event.get("wait_for_load_state_timeout_ms", 30000),
+        )
+    if "wait_for_selector" in event:
+        await page.wait_for_selector(
+            event["wait_for_selector"],
+            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"])
+
+
+async def _launch_with_retry(event: dict, attempts: int = 3, backoff_s: float = 0.3):
+    """Retry launch_context_async up to `attempts` times with linear backoff.
+
+    Lambda cold-start storms occasionally race Xvfb readiness or hit transient
+    Chromium spawn failures — both surface as "Target page, context or browser
+    has been closed" at launch. The failure is fast (~0.5s) so retries are
+    cheap, and a retry on a now-warm container almost always succeeds.
+
+    Pairs with the lock-cleanup + socket-poll in lambda-entrypoint.sh: the
+    entrypoint catches the common case at container init; this catches the
+    residual race when the first invocation hits before Xvfb is fully ready.
+    """
+    last_err: Exception | None = None
+    for i in range(attempts):
+        try:
+            return await launch_context_async(**_build_launch_kwargs(event))
+        except Exception as e:
+            last_err = e
+            logger.warning("launch attempt %d/%d failed: %s",
+                           i + 1, attempts, str(e)[:200])
+            if i + 1 < attempts:
+                await asyncio.sleep(backoff_s * (i + 1))  # 0.3s, 0.6s
+    raise last_err  # type: ignore[misc]
+
+
+def _classify_error(err: Exception) -> dict | None:
+    """Map a Playwright error to a retry-strategy override dict, or None
+    if the error is unrecoverable.
+
+    Match on str(e) because Playwright errors carry their codes inside the
+    message (Error.__str__ includes ERR_CERT_AUTHORITY_INVALID etc.); there
+    is no stable structured `.error_code` attribute to rely on.
+
+    Strategies (priority order — first match wins):
+      ERR_CERT_*                  -> --ignore-certificate-errors + 60s goto budget
+      Timeout exceeded            -> 90s goto budget + 25s smart_wait cap
+      ERR_CONNECTION_TIMED_OUT    -> same as Timeout
+    Returns None for unrecoverable site issues (DNS, SSL, refused, HTTP 4xx/5xx).
+    """
+    msg = str(err)
+    if "ERR_CERT" in msg:
+        return {
+            "extra_args": ["--ignore-certificate-errors"],
+            "goto_timeout_ms": 60000,
+        }
+    if ("Timeout" in msg and "exceeded" in msg) or "ERR_CONNECTION_TIMED_OUT" in msg:
+        return {
+            "goto_timeout_ms": 90000,
+            "max_settle_ms": 25000,
+        }
+    return None
+
+
+async def _attempt_scrape(url: str, event: dict) -> dict:
+    """One self-contained scrape attempt: launch, navigate, wait, capture, close.
+
+    Extracted from `_run` so the retry loop can call it repeatedly with an
+    overridden event dict. Each attempt relaunches the browser — uniform
+    behavior across strategies (the cert-bypass strategy *requires* a relaunch
+    because `--ignore-certificate-errors` is a Chromium CLI arg, not a per-
+    context switch), and the ~3-5s relaunch cost is fine on the slow path.
+    """
+    ctx = await _launch_with_retry(event)
+    try:
+        page = await ctx.new_page()
+        await page.goto(
+            url,
+            wait_until=event.get("wait_until", "domcontentloaded"),
+            timeout=event.get("goto_timeout_ms", 30000),
+        )
+
+        await _post_nav_waits(page, event)
+
+        result: dict = {
+            "title": await page.title(),
+            "url": page.url,
+            "html": await page.content(),
+        }
+
+        if event.get("screenshot", True):
+            png = await page.screenshot(
+                full_page=event.get("full_page_screenshot", False),
+            )
+            result["screenshot_b64"] = base64.b64encode(png).decode()
+
+        return result
+    finally:
+        try:
+            await ctx.close()
+        except Exception:
+            pass
+
+
+def _raise_with_history(err: Exception, history: list[dict]) -> None:
+    """Surface a final failure with a retry_history block embedded in the
+    error message, so callers see what was tried before bailing."""
+    diag = _diag_snapshot()
+    if history:
+        diag = "retry_history: " + json.dumps(history, default=str) + "\n\n" + diag
+    logger.error("scrape failed (after %d retries): %s\nDIAG:\n%s",
+                 len(history), err, diag)
+    raise RuntimeError(f"scrape failed: {err}\n--- DIAG ---\n{diag}") from err
+
+
+async def _run(event: dict) -> dict:
+    """Top-level scrape with strategy-based retry orchestration.
+
+    First attempt uses the event verbatim. If it fails with a classifiable
+    error (cert / timeout), retry with that strategy's overrides merged into
+    the event. `retries` bounds the number of strategy retries (default 1;
+    set to 0 to disable retry entirely).
+    """
+    url = event["url"]
+    retries_left = max(0, int(event.get("retries", 1)))
+    history: list[dict] = []
+    current_event = event
+
+    while True:
+        try:
+            return await _attempt_scrape(url, current_event)
+        except Exception as e:
+            if retries_left <= 0:
+                _raise_with_history(e, history)
+            strategy = _classify_error(e)
+            if strategy is None:
+                _raise_with_history(e, history)
+            history.append({
+                "attempt": len(history) + 1,
+                "error": str(e)[:300],
+                "strategy": strategy,
+            })
+            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}
+            retries_left -= 1
+            # No backoff: strategy overrides change goto budget directly;
+            # the prior failure was either fast (cert reject) or already
+            # waited its full timeout. Container is warm.
+
+
@@ -215,7 +215,7 @@ const page = await browser.newPage();
 ## Requirements

 - Node.js >= 20
- One of: `playwright-core` >= 1.40 or `puppeteer-core` >= 21
+- One of: `playwright-core` >= 1.53 or `puppeteer-core` >= 21

 ## Troubleshooting

@@ -1,12 +1,12 @@
 {
  "name": "cloakbrowser",
-  "version": "0.3.23",
+  "version": "0.3.28",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "cloakbrowser",
-      "version": "0.3.23",
+      "version": "0.3.28",
      "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": {
@@ -1329,7 +1329,8 @@
      "resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1232444.tgz",
      "integrity": "sha512-pM27vqEfxSxRkTMnF+XCmxSEb6duO5R+t8A9DEEJgy4Wz2RVanje2mmj99B6A3zv2r/qGfYlOvYznUhuokizmg==",
      "dev": true,
-      "license": "BSD-3-Clause"
+      "license": "BSD-3-Clause",
+      "peer": true
    },
    "node_modules/diff-sequences": {
      "version": "29.6.3",
@@ -1684,9 +1685,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 +2115,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 +2497,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",
@@ -1,6 +1,6 @@
 {
  "name": "cloakbrowser",
-  "version": "0.3.23",
+  "version": "0.3.28",
  "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",
@@ -59,7 +59,7 @@
  },
  "peerDependencies": {
    "mmdb-lib": ">=2.0.0",
-    "playwright-core": ">=1.40.0",
+    "playwright-core": ">=1.53.0",
    "puppeteer-core": ">=21.0.0",
    "socks-proxy-agent": ">=10.0.0"
  },
@@ -84,7 +84,7 @@
    "@types/node": "^20.10.0",
    "mmdb-lib": "^3.0.2",
    "socks-proxy-agent": "^10.0.0",
-    "playwright-core": "^1.40.0",
+    "playwright-core": "^1.53.0",
    "puppeteer-core": "^21.0.0",
    "typescript": "^5.3.0",
    "vitest": "^1.0.0"
@@ -27,14 +27,14 @@ export { WRAPPER_VERSION };
 // CHROMIUM_VERSION is the latest across all platforms (for display/reference).
 // Use getChromiumVersion() for the current platform's actual version.
 // ---------------------------------------------------------------------------
-export const CHROMIUM_VERSION = "146.0.7680.177.1";
+export const CHROMIUM_VERSION = "146.0.7680.177.3";

 export const PLATFORM_CHROMIUM_VERSIONS: Record<string, string> = {
-  "linux-x64": "146.0.7680.177.1",
-  "linux-arm64": "145.0.7632.159.7",
+  "linux-x64": "146.0.7680.177.3",
+  "linux-arm64": "146.0.7680.177.3",
  "darwin-arm64": "145.0.7632.109.2",
  "darwin-x64": "145.0.7632.109.2",
-  "windows-x64": "145.0.7632.159.7",
+  "windows-x64": "146.0.7680.177.4",
 };

 // ---------------------------------------------------------------------------
@@ -22,6 +22,7 @@ const GEOIP_DB_URL =
  "https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-City.mmdb";
 const GEOIP_DB_FILENAME = "GeoLite2-City.mmdb";
 const GEOIP_UPDATE_INTERVAL_MS = 30 * 86_400_000; // 30 days
+const DEFAULT_GEOIP_TIMEOUT_MS = 5_000;

 /** Country ISO code → BCP 47 locale (covers ~90% of proxy traffic). */
 export const COUNTRY_LOCALE_MAP: Record<string, string> = {
@@ -68,10 +69,18 @@ export async function resolveProxyGeo(
  const dbPath = await ensureGeoipDb();
  if (!dbPath) return { timezone: null, locale: null, exitIp: null };

+  const timeoutMs = getGeoipTimeoutMs();
+  const deadline = deadlineFromTimeout(timeoutMs);
+
  // Exit IP (through proxy) is most accurate — gateway DNS may differ from exit
-  let ip = await resolveExitIp(proxyUrl);
-  if (!ip) ip = await resolveProxyIp(proxyUrl);
-  if (!ip) return { timezone: null, locale: null, exitIp: null };
+  let ip = await resolveExitIp(proxyUrl, remainingMs(deadline));
+  if (!ip && !deadlineExpired(deadline)) ip = await resolveProxyIp(proxyUrl);
+  if (!ip || deadlineExpired(deadline)) {
+    if (deadlineExpired(deadline)) {
+      console.warn(`[cloakbrowser] GeoIP resolution timed out after ${timeoutMs}ms; continuing without GeoIP`);
+    }
+    return { timezone: null, locale: null, exitIp: null };
+  }

  try {
    const buf = fs.readFileSync(dbPath);
@@ -87,6 +96,30 @@ export async function resolveProxyGeo(
  }
 }

+function getGeoipTimeoutMs(): number {
+  const raw = process.env.CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS;
+  if (!raw) return DEFAULT_GEOIP_TIMEOUT_MS;
+  const timeoutSeconds = Number(raw);
+  if (!Number.isFinite(timeoutSeconds)) {
+    console.warn(`[cloakbrowser] Invalid CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS=${raw}; using ${DEFAULT_GEOIP_TIMEOUT_MS / 1000}s`);
+    return DEFAULT_GEOIP_TIMEOUT_MS;
+  }
+  return Math.max(timeoutSeconds, 0) * 1000;
+}
+
+function deadlineFromTimeout(timeoutMs: number): number | null {
+  return timeoutMs > 0 ? performance.now() + timeoutMs : null;
+}
+
+function remainingMs(deadline: number | null): number | undefined {
+  if (deadline === null) return undefined;
+  return Math.max(deadline - performance.now(), 0);
+}
+
+function deadlineExpired(deadline: number | null): boolean {
+  return deadline !== null && performance.now() >= deadline;
+}
+
 // ---------------------------------------------------------------------------
 // Proxy IP resolution
 // ---------------------------------------------------------------------------
@@ -128,7 +161,8 @@ const IP_ECHO_URLS = [
  "https://ifconfig.me/ip",
 ];

-async function resolveExitIp(proxyUrl: string): Promise<string | null> {
+async function resolveExitIp(proxyUrl: string, timeoutMs?: number): Promise<string | null> {
+  const deadline = timeoutMs && timeoutMs > 0 ? performance.now() + timeoutMs : null;
  const isSocks = isSocksProxy(proxyUrl);

  // SOCKS5: tunnel through the SOCKS5 proxy via socks-proxy-agent
@@ -144,9 +178,11 @@ async function resolveExitIp(proxyUrl: string): Promise<string | null> {
    const agent = new SocksProxyAgent(proxyUrl);

    for (const echoUrl of IP_ECHO_URLS) {
+      const remaining = remainingMs(deadline);
+      if (remaining !== undefined && remaining <= 0) return null;
      try {
        const ip = await new Promise<string | null>((resolve) => {
-          const req = https.request(echoUrl, { agent, timeout: 10_000 }, (res) => {
+          const req = https.request(echoUrl, { agent, timeout: Math.min(10_000, remaining ?? 10_000) }, (res) => {
            let data = "";
            res.on("data", (chunk: Buffer) => (data += chunk.toString()));
            res.on("end", () => {
@@ -173,6 +209,8 @@ async function resolveExitIp(proxyUrl: string): Promise<string | null> {
    const proxyUrlObj = new URL(proxyUrl);

    for (const echoUrl of IP_ECHO_URLS) {
+      const remaining = remainingMs(deadline);
+      if (remaining !== undefined && remaining <= 0) return null;
      try {
        const ip = await new Promise<string | null>((resolve, reject) => {
          const targetUrl = new URL(echoUrl);
@@ -190,13 +228,14 @@ async function resolveExitIp(proxyUrl: string): Promise<string | null> {
                    ).toString("base64"),
                }
              : {},
-            timeout: 10_000,
+            timeout: Math.min(10_000, remaining ?? 10_000),
          });

          connectReq.on("connect", (_res, socket) => {
+            const innerRemaining = remainingMs(deadline);
            const req = https.request(
              echoUrl,
-              { socket, timeout: 5_000 } as any,
+              { socket, timeout: Math.min(5_000, innerRemaining ?? 5_000) } as any,
              (res) => {
                let data = "";
                res.on("data", (chunk: Buffer) => (data += chunk.toString()));
@@ -207,6 +246,7 @@ async function resolveExitIp(proxyUrl: string): Promise<string | null> {
              }
            );
            req.on("error", () => resolve(null));
+            req.on("timeout", () => { req.destroy(); resolve(null); });
            req.end();
          });

@@ -261,7 +301,9 @@ async function downloadGeoipDb(dest: string): Promise<void> {

  const tmpPath = `${dest}.tmp.${Date.now()}`;
  try {
-    const response = await fetch(GEOIP_DB_URL, { redirect: "follow" });
+    const response = await fetch(GEOIP_DB_URL, {
+      redirect: "follow",
+    });
    if (!response.ok || !response.body) {
      throw new Error(`HTTP ${response.status}`);
    }
@@ -329,7 +371,8 @@ export async function maybeResolveGeoip(

  // When both tz/locale are explicit, still resolve exit IP for WebRTC
  if (options.timezone && options.locale) {
-    const exitIp = await resolveExitIp(proxyUrl) ?? undefined;
+    const timeoutMs = getGeoipTimeoutMs();
+    const exitIp = await resolveExitIp(proxyUrl, timeoutMs) ?? undefined;
    return { timezone: options.timezone, locale: options.locale, exitIp };
  }

@@ -363,7 +406,7 @@ export async function resolveWebrtcArgs(
  }

  try {
-    const ip = await resolveExitIp(proxyUrl);
+    const ip = await resolveExitIp(proxyUrl, getGeoipTimeoutMs());
    const result = [...args];
    if (ip) {
      result[idx] = `--fingerprint-webrtc-ip=${ip}`;
@@ -47,17 +47,17 @@
 */

 import type { Browser, Page, Frame, CDPSession, ElementHandle, BrowserContext } from 'puppeteer-core';
-import type { HumanConfig } from '../human/config.js';
-import { resolveConfig, rand, randRange, sleep } from '../human/config.js';
+import type { HumanConfig, HumanActionOptions } from '../human/config.js';
+import { resolveConfig, mergeConfig, rand, randRange, sleep } from '../human/config.js';
 import { RawMouse, RawKeyboard, humanMove, humanClick, clickTarget, humanIdle } from '../human/mouse.js';
 import { humanType } from './keyboard.js';
-import { scrollToElement, smoothWheel } from './scroll.js';
+import { scrollToElement, humanScrollIntoView, smoothWheel } from './scroll.js';

 export type { HumanConfig } from '../human/config.js';
-export { resolveConfig } from '../human/config.js';
+export { resolveConfig, mergeConfig } from '../human/config.js';
 export { humanMove, humanClick, clickTarget, humanIdle } from '../human/mouse.js';
 export { humanType } from './keyboard.js';
-export { scrollToElement } from './scroll.js';
+export { scrollToElement, humanScrollIntoView } from './scroll.js';


 // ============================================================================
@@ -319,7 +319,11 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  }

  // ==== goto ====
-  const humanGoto = async (url: string, options?: any) => {
+  const humanGoto = async (url: string, options?: {
+    referer?: string;
+    timeout?: number;
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+  }) => {
    const response = await originals.goto(url, options);
    stealth.invalidate();
    patchFrames(page, cfg, cursor, raw, rawKb, originals, stealth);
@@ -327,54 +331,64 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  };

  // ==== click (with clickCount support for dblclick) ====
-  const humanClickFn = async (selector: string, options?: any) => {
+  const humanClickFn = async (selector: string, options?: HumanActionOptions & {
+    button?: 'left' | 'right' | 'middle' | 'back' | 'forward';
+    clickCount?: number;
+    count?: number;
+    delay?: number;
+  }) => {
    await ensureCursorInit();
-    if (cfg.idle_between_actions) {
-      await humanIdle(raw, rand(cfg.idle_between_duration[0], cfg.idle_between_duration[1]), cursor.x, cursor.y, cfg);
+    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    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, cfg);
+    const { box, cursorX, cursorY } = await scrollToElement(page, raw, selector, cursor.x, cursor.y, callCfg, options?.timeout);
    cursor.x = cursorX;
    cursor.y = cursorY;
    const isInput = await isInputElement(stealth, page, selector);
-    const target = clickTarget(box, isInput, cfg);
-    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, cfg);
+    const target = clickTarget(box, isInput, callCfg);
+    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, callCfg);
    cursor.x = target.x;
    cursor.y = target.y;

    const clickCount = options?.clickCount ?? options?.count ?? 1;
    if (clickCount >= 2) {
-      await humanClick(raw, isInput, cfg);
+      await humanClick(raw, isInput, callCfg);
      await sleep(rand(40, 90));
      await raw.down({ clickCount: 2 });
      await sleep(rand(30, 60));
      await raw.up({ clickCount: 2 });
    } else {
-      await humanClick(raw, isInput, cfg);
+      await humanClick(raw, isInput, callCfg);
    }
  };

  // ==== hover ====
-  const humanHoverFn = async (selector: string, options?: any) => {
+  const humanHoverFn = async (selector: string, options?: HumanActionOptions) => {
    await ensureCursorInit();
-    if (cfg.idle_between_actions) {
-      await humanIdle(raw, rand(cfg.idle_between_duration[0], cfg.idle_between_duration[1]), cursor.x, cursor.y, cfg);
+    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    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, cfg);
+    const { box, cursorX, cursorY } = await scrollToElement(page, raw, selector, cursor.x, cursor.y, callCfg, options?.timeout);
    cursor.x = cursorX;
    cursor.y = cursorY;
-    const target = clickTarget(box, false, cfg);
-    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, cfg);
+    const target = clickTarget(box, false, callCfg);
+    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, callCfg);
    cursor.x = target.x;
    cursor.y = target.y;
  };

  // ==== type ====
-  const humanTypeFn = async (selector: string, text: string, options?: any) => {
-    await sleep(randRange(cfg.field_switch_delay));
-    await humanClickFn(selector);
+  const humanTypeFn = async (selector: string, text: string, options?: HumanActionOptions & {
+    delay?: number;
+  }) => {
+    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    await sleep(randRange(callCfg.field_switch_delay));
+    await humanClickFn(selector, options);
    await sleep(rand(100, 250));
    const cdp = await ensureCdp();
-    await humanType(page, rawKb, text, cfg, cdp);
+    await humanType(page, rawKb, text, callCfg, cdp);
  };

  // ==== select ====
@@ -392,7 +406,7 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  };

  // ==== tap ====
-  const humanTapFn = async (selector: string, options?: any) => {
+  const humanTapFn = async (selector: string, options?: HumanActionOptions) => {
    await humanClickFn(selector, options);
  };

@@ -410,14 +424,19 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  // ============================================================
  // Mouse patches
  // ============================================================
-  page.mouse.move = async (x: number, y: number, options?: any) => {
+  page.mouse.move = async (x: number, y: number, options?: { steps?: number }) => {
    await ensureCursorInit();
    await humanMove(raw, cursor.x, cursor.y, x, y, cfg);
    cursor.x = x;
    cursor.y = y;
  };

-  page.mouse.click = async (x: number, y: number, options?: any) => {
+  page.mouse.click = async (x: number, y: number, options?: {
+    button?: 'left' | 'right' | 'middle' | 'back' | 'forward';
+    clickCount?: number;
+    count?: number;
+    delay?: number;
+  }) => {
    await ensureCursorInit();
    await humanMove(raw, cursor.x, cursor.y, x, y, cfg);
    cursor.x = x;
@@ -452,7 +471,7 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
    (page.mouse as any).dragAndDrop = async (
      start: { x: number; y: number },
      target: { x: number; y: number },
-      options?: any,
+      options?: { delay?: number },
    ) => {
      await ensureCursorInit();
      await humanMove(raw, cursor.x, cursor.y, start.x, start.y, cfg);
@@ -472,12 +491,12 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  // ============================================================
  // Keyboard patches
  // ============================================================
-  page.keyboard.type = async (text: string, options?: any) => {
+  page.keyboard.type = async (text: string, options?: { delay?: number }) => {
    const cdp = await ensureCdp();
    await humanType(page, rawKb, text, cfg, cdp);
  };

-  page.keyboard.press = async (key: any, options?: any) => {
+  page.keyboard.press = async (key: any, options?: { delay?: number }) => {
    await sleep(rand(20, 60));
    await originals.keyboardDown(key as any);
    await sleep(randRange(cfg.key_hold));
@@ -548,7 +567,11 @@ function patchElementHandle(
    return els;
  };

-  (page as any).waitForSelector = async (selector: string, options?: any) => {
+  (page as any).waitForSelector = async (selector: string, options?: {
+    hidden?: boolean;
+    timeout?: number;
+    visible?: boolean;
+  }) => {
    const el = await origWaitForSelector(selector, options);
    if (el) patchSingleElementHandle(el, page, cfg, cursor, raw, rawKb, originals, stealth);
    return el;
@@ -577,6 +600,9 @@ function patchSingleElementHandle(
  const origElDragAndDrop = (el as any).dragAndDrop?.bind(el);
  const origElSelect = (el as any).select?.bind(el);
  const origElDrop = (el as any).drop?.bind(el);
+  // Puppeteer v22+ adds ElementHandle.scrollIntoView(); earlier versions
+  // expose it implicitly via evaluate(node => node.scrollIntoView()).
+  const origElScrollIntoView = (el as any).scrollIntoView?.bind(el);

  // --- Nested selectors ---
  const origEl$ = el.$.bind(el);
@@ -597,45 +623,69 @@ function patchSingleElementHandle(
    return children;
  };

-  (el as any).waitForSelector = async (selector: string, options?: any) => {
+  (el as any).waitForSelector = async (selector: string, options?: {
+    hidden?: boolean;
+    timeout?: number;
+    visible?: boolean;
+  }) => {
    const child = await origElWaitForSelector(selector, options);
    if (child) patchSingleElementHandle(child, page, cfg, cursor, raw, rawKb, originals, stealth);
    return child;
  };

-  // --- Helper: get box and move cursor ---
-  const moveToElement = async () => {
+  // --- Helper: get box and move cursor. Accepts a per-call ``callCfg``
+  // so type/fill overrides like ``el.type(text, { typing_delay: 30 })``
+  // carry through to mouse timing for that single call. Also scrolls into
+  // view first so off-screen elements work (#129, #172 follow-up).
+  const moveToElement = async (callCfg: HumanConfig = cfg) => {
    await (page as any)._ensureCursorInit();
+
+    try {
+      const { cursorX, cursorY } = await humanScrollIntoView(
+        page, raw,
+        () => el.boundingBox().then(b => b ?? null),
+        cursor.x, cursor.y, callCfg,
+      );
+      cursor.x = cursorX;
+      cursor.y = cursorY;
+    } catch { /* let boundingBox() decide */ }
+
    const box = await el.boundingBox();
    if (!box) return null;

    const isInp = await isInputElementHandle(stealth, el);
-    const target = clickTarget(box, isInp, cfg);
+    const target = clickTarget(box, isInp, callCfg);

-    if (cfg.idle_between_actions) {
-      await humanIdle(raw, rand(cfg.idle_between_duration[0], cfg.idle_between_duration[1]), cursor.x, cursor.y, cfg);
+    if (callCfg.idle_between_actions) {
+      await humanIdle(raw, cursor.x, cursor.y, callCfg);
    }

-    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, cfg);
+    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, callCfg);
    cursor.x = target.x;
    cursor.y = target.y;
    return { box, isInp };
  };

  // --- el.click() ---
-  (el as any).click = async (options?: any) => {
-    const info = await moveToElement();
+  (el as any).click = async (options?: HumanActionOptions & {
+    button?: 'left' | 'right' | 'middle' | 'back' | 'forward';
+    clickCount?: number;
+    count?: number;
+    delay?: number;
+  }) => {
+    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const info = await moveToElement(callCfg);
    if (!info) return origElClick(options);

    const clickCount = options?.clickCount ?? options?.count ?? 1;
    if (clickCount >= 2) {
-      await humanClick(raw, info.isInp, cfg);
+      await humanClick(raw, info.isInp, callCfg);
      await sleep(rand(40, 90));
      await raw.down({ clickCount: 2 });
      await sleep(rand(30, 60));
      await raw.up({ clickCount: 2 });
    } else {
-      await humanClick(raw, info.isInp, cfg);
+      await humanClick(raw, info.isInp, callCfg);
    }
  };

@@ -646,18 +696,43 @@ function patchSingleElementHandle(
  };

  // --- el.type() ---
-  (el as any).type = async (text: string, options?: any) => {
-    const info = await moveToElement();
+  (el as any).type = async (text: string, options?: HumanActionOptions & { delay?: number }) => {
+    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    const info = await moveToElement(callCfg);
    if (!info) return origElType(text, options);
-    await humanClick(raw, info.isInp, cfg);
+    await humanClick(raw, info.isInp, callCfg);
    await sleep(rand(100, 250));
    const cdp = await stealth.getCdpSession().catch(() => null);
-    await humanType(page, rawKb, text, cfg, cdp);
+    await humanType(page, rawKb, text, callCfg, cdp);
  };

+  // --- el.scrollIntoView() ---
+  // Puppeteer-only equivalent of Playwright's scrollIntoViewIfNeeded.
+  // Replaces the native snap-scroll (a strong bot signal) with the same
+  // accelerate → cruise → decelerate → overshoot wheel sequence used by
+  // page.click(). Only patched when the underlying ElementHandle exposes
+  // ``scrollIntoView`` (Puppeteer v22+).
+  if (origElScrollIntoView) {
+    (el as any).scrollIntoView = async (options?: HumanActionOptions) => {
+      const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+      await (page as any)._ensureCursorInit();
+      try {
+        const { cursorX, cursorY } = await humanScrollIntoView(
+          page, raw,
+          () => el.boundingBox().then(b => b ?? null),
+          cursor.x, cursor.y, callCfg,
+        );
+        cursor.x = cursorX;
+        cursor.y = cursorY;
+      } catch {
+        return origElScrollIntoView(options);
+      }
+    };
+  }
+
  // --- el.press() ---
  if (origElPress) {
-    (el as any).press = async (key: string, options?: any) => {
+    (el as any).press = async (key: string, options?: { delay?: number }) => {
      await sleep(rand(20, 60));
      await originals.keyboardDown(key as any);
      await sleep(randRange(cfg.key_hold));
@@ -696,7 +771,7 @@ function patchSingleElementHandle(

  // --- el.drop() ---
  if (origElDrop) {
-    (el as any).drop = async (draggable: ElementHandle, options?: any) => {
+    (el as any).drop = async (draggable: ElementHandle, options?: { delay?: number }) => {
      const srcBox = await draggable.boundingBox();
      const tgtBox = await el.boundingBox();

@@ -726,7 +801,7 @@ function patchSingleElementHandle(

  // --- el.dragAndDrop() ---
  if (origElDragAndDrop) {
-    (el as any).dragAndDrop = async (targetEl: ElementHandle, options?: any) => {
+    (el as any).dragAndDrop = async (targetEl: ElementHandle, options?: { delay?: number }) => {
      const srcBox = await el.boundingBox();
      const tgtBox = await targetEl.boundingBox();

@@ -790,15 +865,22 @@ function patchSingleFrame(

  const origFrameSelect = frame.select.bind(frame);

-  (frame as any).click = async (selector: string, options?: any) => {
+  (frame as any).click = async (selector: string, options?: HumanActionOptions & {
+    button?: 'left' | 'right' | 'middle' | 'back' | 'forward';
+    clickCount?: number;
+    count?: number;
+    delay?: number;
+  }) => {
    await (page as any).click(selector, options);
  };

-  (frame as any).hover = async (selector: string, options?: any) => {
+  (frame as any).hover = async (selector: string, options?: HumanActionOptions) => {
    await (page as any).hover(selector, options);
  };

-  (frame as any).type = async (selector: string, text: string, options?: any) => {
+  (frame as any).type = async (selector: string, text: string, options?: HumanActionOptions & {
+    delay?: number;
+  }) => {
    await (page as any).type(selector, text, options);
  };

@@ -812,7 +894,7 @@ function patchSingleFrame(
    await (page as any).focus(selector);
  };

-  (frame as any).tap = async (selector: string, options?: any) => {
+  (frame as any).tap = async (selector: string, options?: HumanActionOptions) => {
    await (page as any).click(selector, options);
  };

@@ -835,7 +917,11 @@ function patchSingleFrame(
    return els;
  };

-  (frame as any).waitForSelector = async (selector: string, options?: any) => {
+  (frame as any).waitForSelector = async (selector: string, options?: {
+    hidden?: boolean;
+    timeout?: number;
+    visible?: boolean;
+  }) => {
    const el = await origFrameWaitForSelector(selector, options);
    if (el) patchSingleElementHandle(el, page, cfg, cursor, raw, rawKb, originals, stealth);
    return el;
@@ -881,7 +967,7 @@ export function patchBrowser(browser: Browser, cfg: HumanConfig): void {
  for (const methodName of ['createBrowserContext', 'createIncognitoBrowserContext'] as const) {
    if (typeof (browser as any)[methodName] === 'function') {
      const origCreateContext = (browser as any)[methodName].bind(browser);
-      (browser as any)[methodName] = async (options?: any) => {
+      (browser as any)[methodName] = async (options?: Parameters<typeof origCreateContext>[0]) => {
        const context: BrowserContext = await origCreateContext(options);

        const origCtxNewPage = context.newPage.bind(context);
@@ -5,7 +5,7 @@
 * Changes from Playwright version:
 *   - page.viewport() instead of page.viewportSize()
 *   - page.$(selector) + el.boundingBox() instead of page.locator().boundingBox()
- *   - No timeout parameter on boundingBox()
+ *   - boundingBox() has no timeout param — we poll page.$() up to ``timeout`` ms
 */

 import type { Page } from 'puppeteer-core';
@@ -55,22 +55,40 @@ export async function smoothWheel(
  }
 }

-async function getElementBox(page: Page, selector: string): Promise<ElementBounds | null> {
-  try {
-    const el = await page.$(selector);
-    if (!el) return null;
-    const box = await el.boundingBox();
-    if (!box) return null;
-    return { x: box.x, y: box.y, width: box.width, height: box.height };
-  } catch {
-    return null;
+/**
+ * Poll ``page.$(selector)`` for up to ``timeout`` ms, returning the element's
+ * bounding box when found. ``timeout`` defaults to 30000ms when not specified.
+ */
+async function getElementBox(
+  page: Page,
+  selector: string,
+  timeout: number = 30000,
+): Promise<ElementBounds | null> {
+  const start = Date.now();
+  const pollInterval = 100;
+  while (true) {
+    try {
+      const el = await page.$(selector);
+      if (el) {
+        const box = await el.boundingBox();
+        if (box) return { x: box.x, y: box.y, width: box.width, height: box.height };
+      }
+    } catch { /* keep polling */ }
+
+    if (Date.now() - start >= timeout) return null;
+    await sleep(pollInterval);
  }
 }

-export async function scrollToElement(
+/**
+ * Humanized scrolling that takes an arbitrary ``getBox`` callable.
+ * Used by both ``scrollToElement`` (selector-based) and the ElementHandle
+ * ``scrollIntoView`` patch.
+ */
+export async function humanScrollIntoView(
  page: Page,
  raw: RawMouse,
-  selector: string,
+  getBox: () => Promise<ElementBounds | null>,
  cursorX: number,
  cursorY: number,
  cfg: HumanConfig,
@@ -78,12 +96,8 @@ export async function scrollToElement(
  const viewport = page.viewport();
  if (!viewport) throw new Error('Viewport size not available');

-  let box = await getElementBox(page, selector);
-  if (!box) {
-    await sleep(200);
-    box = await getElementBox(page, selector);
-    if (!box) throw new Error(`Element not found: ${selector}`);
-  }
+  let box = await getBox();
+  if (!box) throw new Error('Element not found while scrolling into view');

  if (isInViewport(box, viewport.height, cfg)) {
    return { box, cursorX, cursorY };
@@ -134,7 +148,7 @@ export async function scrollToElement(
    await sleep(pause);

    if (i % 3 === 2 || i === totalClicks - 1) {
-      box = await getElementBox(page, selector);
+      box = await getBox();
      if (box && isInViewport(box, viewport.height, cfg)) {
        break;
      }
@@ -159,8 +173,31 @@ export async function scrollToElement(

  await sleep(randRange(cfg.scroll_settle_delay));

-  box = await getElementBox(page, selector);
-  if (!box) throw new Error(`Element lost after scrolling: ${selector}`);
+  box = await getBox();
+  if (!box) throw new Error('Element lost after scrolling into view');

  return { box, cursorX, cursorY };
 }
+
+/**
+ * Selector-based humanized scroll (Puppeteer).
+ *
+ * ``timeout`` controls how long we poll ``page.$(selector)`` before giving up,
+ * so callers like ``page.click('#x', { timeout: 5000 })`` can wait longer for
+ * slow-loading elements (#172). Default matches Playwright's 30000ms when not specified.
+ */
+export async function scrollToElement(
+  page: Page,
+  raw: RawMouse,
+  selector: string,
+  cursorX: number,
+  cursorY: number,
+  cfg: HumanConfig,
+  timeout?: number,
+): Promise<{ box: ElementBounds; cursorX: number; cursorY: number }> {
+  return humanScrollIntoView(
+    page, raw,
+    () => getElementBox(page, selector, timeout),
+    cursorX, cursorY, cfg,
+  );
+}
@@ -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++;
+  }
+}
@@ -70,6 +70,12 @@ export interface HumanConfig {

 export type HumanPreset = 'default' | 'careful';

+export type HumanActionOptions = Partial<HumanConfig> & {
+  timeout?: number;
+  force?: boolean;
+  human_config?: Partial<HumanConfig>;
+};
+
 // ---------------------------------------------------------------------------
 // Default preset
 // ---------------------------------------------------------------------------
@@ -201,6 +207,22 @@ export function resolveConfig(
  return { ...base, ...overrides };
 }

+/**
+ * Merge a partial overrides object on top of an existing HumanConfig.
+ * Returns a new object — the original ``cfg`` is never mutated.
+ *
+ * Used by per-call overrides such as ``page.type(sel, text, { human_config: { typing_delay: 30 } })``
+ * so the same patched page can type different fields at different speeds
+ * without re-patching.
+ */
+export function mergeConfig(
+  cfg: HumanConfig,
+  overrides?: Partial<HumanConfig> | null,
+): HumanConfig {
+  if (!overrides) return cfg;
+  return { ...cfg, ...overrides };
+}
+

 // ---------------------------------------------------------------------------
 // Utility: random number in range
@@ -17,10 +17,15 @@
 */

 import type { Page, Frame, ElementHandle, CDPSession } from 'playwright-core';
-import type { HumanConfig } from './config.js';
-import { rand, randRange, sleep } from './config.js';
+import type { HumanConfig, HumanActionOptions } from './config.js';
+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';
@@ -102,6 +107,7 @@ export function patchSingleElementHandle(
  const origElSetChecked = (el as any).setChecked?.bind(el);
  const origElTap = el.tap.bind(el);
  const origElFocus = el.focus.bind(el);
+  const origElScrollIntoViewIfNeeded = (el as any).scrollIntoViewIfNeeded?.bind(el);

  // Nested selectors
  const origEl$ = el.$.bind(el);
@@ -123,86 +129,161 @@ export function patchSingleElementHandle(
    return children;
  };

-  (el as any).waitForSelector = async (selector: string, options?: any) => {
-    const child = await origElWaitForSelector(selector, options);
+  (el as any).waitForSelector = async (selector: string, options?: {
+    state?: 'attached' | 'detached' | 'visible' | 'hidden';
+    strict?: boolean;
+    timeout?: number;
+  }) => {
+    const child = await origElWaitForSelector(selector, options ?? {});
    if (child) patchSingleElementHandle(child, page, cfg, cursor, raw, rawKb, originals, stealth);
    return child;
  };

  // --- Helper: get bounding box and move cursor to element ---
-  const moveToElement = async () => {
+  // Accepts a per-call ``callCfg`` so type/fill overrides like
+  // ``el.type(text, { human_config: { typing_delay: 30 } })`` or
+  // ``el.type(text, { typing_delay: 30 })`` carry through to mouse movement
+  // & idle timing for that single call.
+  // Also scrolls the element into view first so off-screen elements work
+  // (#129, #172 follow-up): otherwise boundingBox() returns null and we'd
+  // silently fall back to the unpatched native method.
+  const moveToElement = async (callCfg: HumanConfig = cfg) => {
    // Ensure cursor is initialized
    const ensureCursorInit = (page as any)._ensureCursorInit;
    if (ensureCursorInit) await ensureCursorInit();

+    // Scroll into view first so boundingBox() returns coordinates even when
+    // the element starts below the fold. Best-effort — if humanScrollIntoView
+    // throws (e.g. detached element), we let boundingBox() decide whether to
+    // proceed or fall back to the original method.
+    try {
+      const { cursorX, cursorY } = await humanScrollIntoView(
+        page, raw,
+        () => el.boundingBox(),
+        cursor.x, cursor.y, callCfg,
+      );
+      cursor.x = cursorX;
+      cursor.y = cursorY;
+    } catch { /* let boundingBox() decide */ }
+
    const box = await el.boundingBox();
    if (!box) return null;

    const isInp = await isInputElementHandle(stealth, el);
-    const target = clickTarget(box, isInp, cfg);
+    const target = clickTarget(box, isInp, callCfg);

-    if (cfg.idle_between_actions) {
-      await humanIdle(raw, rand(cfg.idle_between_duration[0], cfg.idle_between_duration[1]), cursor.x, cursor.y, cfg);
+    if (callCfg.idle_between_actions) {
+      await humanIdle(raw, cursor.x, cursor.y, callCfg);
    }

-    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, cfg);
+    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, callCfg);
    cursor.x = target.x;
    cursor.y = target.y;
    return { box, isInp };
  };

  // --- el.click() ---
-  (el as any).click = async (options?: any) => {
-    const info = await moveToElement();
+  (el as any).click = async (options?: HumanActionOptions & {
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+    delay?: number;
+    force?: boolean;
+    modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>;
+    noWaitAfter?: boolean;
+    position?: { x: number; y: number };
+    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);
-    await humanClick(raw, info.isInp, cfg);
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
+    await humanClick(raw, info.isInp, callCfg);
  };

  // --- el.dblclick() ---
-  (el as any).dblclick = async (options?: any) => {
-    const info = await moveToElement();
+  (el as any).dblclick = async (options?: HumanActionOptions & {
+    button?: 'left' | 'right' | 'middle';
+    delay?: number;
+    force?: boolean;
+    modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>;
+    noWaitAfter?: boolean;
+    position?: { x: number; y: number };
+    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 });
  };

  // --- el.hover() ---
-  (el as any).hover = async (options?: any) => {
-    const info = await moveToElement();
+  (el as any).hover = async (options?: HumanActionOptions & {
+    force?: boolean;
+    modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>;
+    position?: { x: number; y: number };
+    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() ---
-  (el as any).type = async (text: string, options?: any) => {
-    const info = await moveToElement();
+  (el as any).type = async (text: string, options?: HumanActionOptions & {
+    delay?: number;
+    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);
-    await humanClick(raw, info.isInp, cfg);
+    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;
    try { cdpSession = await stealth?.getCdpSession(); } catch {}
-    await humanType(page, rawKb, text, cfg, cdpSession);
+    await humanType(page, rawKb, text, callCfg, cdpSession);
  };

  // --- el.fill() ---
-  (el as any).fill = async (value: string, options?: any) => {
-    const info = await moveToElement();
+  (el as any).fill = async (value: string, options?: HumanActionOptions & {
+    force?: boolean;
+    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);
-    await humanClick(raw, info.isInp, cfg);
+    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');
    await sleep(rand(50, 150));
    let cdpSession: CDPSession | null = null;
    try { cdpSession = await stealth?.getCdpSession(); } catch {}
-    await humanType(page, rawKb, value, cfg, cdpSession);
+    await humanType(page, rawKb, value, callCfg, cdpSession);
  };

  // --- el.press() ---
-  (el as any).press = async (key: string, options?: any) => {
+  (el as any).press = async (key: string, options?: { delay?: number; noWaitAfter?: boolean; timeout?: number }) => {
    await sleep(rand(20, 60));
    await originals.keyboardDown(key);
    await sleep(randRange(cfg.key_hold));
@@ -210,7 +291,14 @@ export function patchSingleElementHandle(
  };

  // --- el.selectOption() ---
-  (el as any).selectOption = async (values: any, options?: any) => {
+  (el as any).selectOption = async (values: any, options?: {
+    force?: boolean;
+    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);
@@ -219,42 +307,79 @@ export function patchSingleElementHandle(
  };

  // --- el.check() ---
-  (el as any).check = async (options?: any) => {
+  (el as any).check = async (options?: {
+    force?: boolean;
+    noWaitAfter?: boolean;
+    position?: { x: number; y: number };
+    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);
  };

  // --- el.uncheck() ---
-  (el as any).uncheck = async (options?: any) => {
+  (el as any).uncheck = async (options?: {
+    force?: boolean;
+    noWaitAfter?: boolean;
+    position?: { x: number; y: number };
+    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);
  };

  // --- el.setChecked() ---
  if (origElSetChecked) {
-    (el as any).setChecked = async (checked: boolean, options?: any) => {
+    (el as any).setChecked = async (checked: boolean, options?: {
+      force?: boolean;
+      noWaitAfter?: boolean;
+      position?: { x: number; y: number };
+      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);
    };
  }

  // --- el.tap() ---
-  (el as any).tap = async (options?: any) => {
+  (el as any).tap = async (options?: {
+    force?: boolean;
+    modifiers?: Array<'Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift'>;
+    noWaitAfter?: boolean;
+    position?: { x: number; y: number };
+    timeout?: number;
+    trial?: boolean;
+  }) => {
    const info = await moveToElement();
    if (!info) return origElTap(options);
    await humanClick(raw, info.isInp, cfg);
@@ -268,6 +393,30 @@ export function patchSingleElementHandle(
    await moveToElement();  // human-like Bézier cursor movement
    await origElFocus();    // programmatic focus, no click
  };
+
+  // --- el.scrollIntoViewIfNeeded() ---
+  // Playwright's native version snaps the page — a strong bot signal.
+  // Replace with the same accelerate → cruise → decelerate → overshoot
+  // wheel sequence used by page.click() etc. Falls back to the native
+  // method if the element is detached or scrolling fails.
+  if (origElScrollIntoViewIfNeeded) {
+    (el as any).scrollIntoViewIfNeeded = async (options?: HumanActionOptions) => {
+      const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+      const ensureCursorInit = (page as any)._ensureCursorInit;
+      if (ensureCursorInit) await ensureCursorInit();
+      try {
+        const { cursorX, cursorY } = await humanScrollIntoView(
+          page, raw,
+          () => el.boundingBox(),
+          cursor.x, cursor.y, callCfg,
+        );
+        cursor.x = cursorX;
+        cursor.y = cursorY;
+      } catch {
+        return origElScrollIntoViewIfNeeded(options);
+      }
+    };
+  }
 }


@@ -309,8 +458,12 @@ export function patchPageElementHandles(
  // Patch page.waitForSelector()
  if (typeof page.waitForSelector === 'function') {
    const origWaitForSelector = page.waitForSelector.bind(page);
-    (page as any).waitForSelector = async (selector: string, options?: any) => {
-      const el = await origWaitForSelector(selector, options);
+    (page as any).waitForSelector = async (selector: string, options?: {
+      state?: 'attached' | 'detached' | 'visible' | 'hidden';
+      strict?: boolean;
+      timeout?: number;
+    }) => {
+      const el = await origWaitForSelector(selector, options ?? {});
      if (el) patchSingleElementHandle(el, page, cfg, cursor, raw, rawKb, originals, stealth);
      return el;
    };
@@ -357,8 +510,12 @@ export function patchFrameElementHandles(
  // Patch frame.waitForSelector()
  if (typeof frame.waitForSelector === 'function') {
    const origFrameWaitForSelector = frame.waitForSelector.bind(frame);
-    (frame as any).waitForSelector = async (selector: string, options?: any) => {
-      const el = await origFrameWaitForSelector(selector, options);
+    (frame as any).waitForSelector = async (selector: string, options?: {
+      state?: 'attached' | 'detached' | 'visible' | 'hidden';
+      strict?: boolean;
+      timeout?: number;
+    }) => {
+      const el = await origFrameWaitForSelector(selector, options ?? {});
      if (el) patchSingleElementHandle(el, page, cfg, cursor, raw, rawKb, originals, stealth);
      return el;
    };
@@ -23,16 +23,21 @@
 */

 import type { Browser, BrowserContext, Page, Frame, CDPSession } from 'playwright-core';
-import { HumanConfig, resolveConfig, rand, randRange, sleep } from './config.js';
+import { HumanConfig, HumanActionOptions, resolveConfig, mergeConfig, rand, randRange, sleep } from './config.js';
 import { RawMouse, RawKeyboard, humanMove, humanClick, clickTarget, humanIdle } from './mouse.js';
 import { humanType } from './keyboard.js';
-import { scrollToElement } from './scroll.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 } from './config.js';
+export { HumanConfig, resolveConfig, mergeConfig } from './config.js';
 export { humanMove, humanClick, clickTarget, humanIdle } from './mouse.js';
 export { humanType } from './keyboard.js';
-export { scrollToElement } from './scroll.js';
+export { scrollToElement, humanScrollIntoView } from './scroll.js';
 export { patchSingleElementHandle } from './elementhandle.js';

 // --- Platform-aware select-all shortcut (macOS uses Meta, others use Control) ---
@@ -295,7 +300,11 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  }

  // --- goto (invalidate isolated world on navigation) ---
-  const humanGoto = async (url: string, options?: any) => {
+  const humanGoto = async (url: string, options?: {
+    referer?: string;
+    timeout?: number;
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+  }) => {
    const response = await originals.goto(url, options);
    stealth.invalidate();
    patchFrames(page, cfg, cursor, raw, rawKb, originals, stealth);
@@ -303,34 +312,67 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  };

  // --- click ---
-  const humanClickFn = async (selector: string, options?: any) => {
+  const humanClickFn = async (selector: string, options?: HumanActionOptions & { _skipChecks?: boolean }) => {
    await ensureCursorInit();
-    if (cfg.idle_between_actions) {
-      await humanIdle(raw, rand(cfg.idle_between_duration[0], cfg.idle_between_duration[1]), cursor.x, cursor.y, cfg);
+    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);
    }
-    const { box, cursorX, cursorY } = await scrollToElement(page, raw, selector, cursor.x, cursor.y, cfg);
+    if (callCfg.idle_between_actions) {
+      await humanIdle(raw, cursor.x, cursor.y, callCfg);
+    }
+    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, cfg);
-    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, cfg);
+    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;
-    await humanClick(raw, isInput, cfg);
+    await humanClick(raw, isInput, callCfg);
  };

  // --- dblclick ---
-  const humanDblclickFn = async (selector: string, options?: any) => {
+  const humanDblclickFn = async (selector: string, options?: HumanActionOptions) => {
    await ensureCursorInit();
-    if (cfg.idle_between_actions) {
-      await humanIdle(raw, rand(cfg.idle_between_duration[0], cfg.idle_between_duration[1]), cursor.x, cursor.y, cfg);
+    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, cfg);
+    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, cfg);
-    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, cfg);
+    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;
    await raw.down({ clickCount: 2 });
@@ -339,46 +381,82 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  };

  // --- hover ---
-  const humanHoverFn = async (selector: string, options?: any) => {
+  const humanHoverFn = async (selector: string, options?: HumanActionOptions & { _skipChecks?: boolean }) => {
    await ensureCursorInit();
-    if (cfg.idle_between_actions) {
-      await humanIdle(raw, rand(cfg.idle_between_duration[0], cfg.idle_between_duration[1]), cursor.x, cursor.y, cfg);
+    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, cfg);
+    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, cfg);
-    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, cfg);
+    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;
  };

  // --- type ---
-  const humanTypeFn = async (selector: string, text: string, options?: any) => {
-    await sleep(randRange(cfg.field_switch_delay));
-    await humanClickFn(selector);
+  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, { _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, cfg, cdp);
+    await humanType(page, rawKb, text, callCfg, cdp);
  };

  // --- fill (clears existing content first) ---
-  const humanFillFn = async (selector: string, value: string, options?: any) => {
-    await sleep(randRange(cfg.field_switch_delay));
-    await humanClickFn(selector);
+  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, { _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));
    await originals.keyboardPress('Backspace');
    await sleep(rand(50, 150));
    const cdp = await ensureCdp();
-    await humanType(page, rawKb, value, cfg, cdp);
+    await humanType(page, rawKb, value, callCfg, cdp);
  };

  // --- clear ---
-  const humanClearFn = async (selector: string, options?: any) => {
+  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);
+      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);
@@ -387,55 +465,88 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  };

  // --- check ---
-  const humanCheckFn = async (selector: string, options?: any) => {
-    if (cfg.idle_between_actions) {
-      await humanIdle(raw, rand(cfg.idle_between_duration[0], cfg.idle_between_duration[1]), cursor.x, cursor.y, cfg);
+  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);
+      await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
    }
  };

  // --- uncheck ---
-  const humanUncheckFn = async (selector: string, options?: any) => {
-    if (cfg.idle_between_actions) {
-      await humanIdle(raw, rand(cfg.idle_between_duration[0], cfg.idle_between_duration[1]), cursor.x, cursor.y, cfg);
+  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);
+      await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
    }
  };

  // --- selectOption ---
-  const humanSelectOptionFn = async (selector: string, values: any, options?: any) => {
-    await humanHoverFn(selector);
+  const humanSelectOptionFn = async (selector: string, values: any, 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);
+    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?: any) => {
+  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);
+      await humanClickFn(selector, { _skipChecks: true, timeout: remainingMs(), force, human_config: options?.human_config } as any);
    }
    await sleep(rand(50, 150));
    await originals.keyboardPress(key);
  };

  // --- pressSequentially ---
-  const humanPressSequentiallyFn = async (selector: string, text: string, options?: any) => {
+  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);
+      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, cfg, cdp);
+    await humanType(page, rawKb, text, callCfg, cdp);
  };

  // --- tap ---
-  const humanTapFn = async (selector: string, options?: any) => {
+  const humanTapFn = async (selector: string, options?: HumanActionOptions) => {
    await humanClickFn(selector, options);
  };

@@ -455,14 +566,20 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  (page as any).clear = humanClearFn;

  // --- mouse patches ---
-  page.mouse.move = async (x: number, y: number, options?: any) => {
+  page.mouse.move = async (x: number, y: number, options?: {
+    steps?: number;
+  }) => {
    await ensureCursorInit();
    await humanMove(raw, cursor.x, cursor.y, x, y, cfg);
    cursor.x = x;
    cursor.y = y;
  };

-  page.mouse.click = async (x: number, y: number, options?: any) => {
+  page.mouse.click = async (x: number, y: number, options?: {
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+    delay?: number;
+  }) => {
    await ensureCursorInit();
    await humanMove(raw, cursor.x, cursor.y, x, y, cfg);
    cursor.x = x;
@@ -471,7 +588,7 @@ function patchPage(page: Page, cfg: HumanConfig, cursor: CursorState): void {
  };

  // --- keyboard patches ---
-  page.keyboard.type = async (text: string, options?: any) => {
+  page.keyboard.type = async (text: string, options?: { delay?: number }) => {
    const cdp = await ensureCdp();
    await humanType(page, rawKb, text, cfg, cdp);
  };
@@ -523,16 +640,37 @@ function patchFrames(
  stealth: StealthEval,
 ): void {
  for (const frame of iterFrames(page)) {
-    patchSingleFrame(frame, page, cfg, originals, stealth);
+    patchSingleFrame(frame, page, cfg, cursor, raw, rawKb, originals, stealth);
    // Patch frame-level ElementHandle selectors ($, $$, waitForSelector)
    patchFrameElementHandles(frame, page, cfg, cursor, raw, rawKb, originals, stealth);
  }
 }

+function firstFrameLocator(frame: Frame, selector: string): any {
+  const locator = frame.locator(selector) as any;
+  return typeof locator.first === 'function' ? locator.first() : locator;
+}
+
+async function isFrameInputElement(frame: Frame, selector: string): Promise<boolean> {
+  return firstFrameLocator(frame, selector).evaluate((el: Element) => {
+    const tag = el.tagName.toLowerCase();
+    return tag === 'input' || tag === 'textarea'
+      || el.getAttribute('contenteditable') === 'true';
+  }).catch(() => false);
+}
+
+async function isFrameSelectorFocused(frame: Frame, selector: string): Promise<boolean> {
+  return firstFrameLocator(frame, selector).evaluate((el: Element) => el === document.activeElement)
+    .catch(() => false);
+}
+
 function patchSingleFrame(
  frame: Frame,
  page: Page,
  cfg: HumanConfig,
+  cursor: CursorState,
+  raw: RawMouse,
+  rawKb: RawKeyboard,
  originals: any,
  stealth: StealthEval,
 ): void {
@@ -540,58 +678,132 @@ function patchSingleFrame(
  (frame as any)._humanPatched = true;

  // Save originals for methods that need fallback
+  const origFrameClick = frame.click.bind(frame);
+  const origFrameDblclick = frame.dblclick.bind(frame);
+  const origFrameHover = frame.hover.bind(frame);
+  const origFrameType = frame.type.bind(frame);
+  const origFrameFill = frame.fill.bind(frame);
+  const origFrameCheck = frame.check.bind(frame);
+  const origFrameUncheck = frame.uncheck.bind(frame);
  const origFrameSelectOption = frame.selectOption.bind(frame);
+  const origFramePress = frame.press.bind(frame);
+  const origFramePressSequentially = (frame as any).pressSequentially?.bind(frame);
+  const origFrameTap = (frame as any).tap?.bind(frame);
  const origFrameDragAndDrop = frame.dragAndDrop.bind(frame);

-  (frame as any).click = async (selector: string, options?: any) => {
-    await (page as any).click(selector, options);
+  const moveToFrameSelector = async (selector: string, options?: HumanActionOptions, inputBias = false) => {
+    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    if (callCfg.idle_between_actions) {
+      await humanIdle(raw, cursor.x, cursor.y, callCfg);
+    }
+
+    const locator = firstFrameLocator(frame, selector);
+    if (typeof locator.scrollIntoViewIfNeeded === 'function') {
+      await locator.scrollIntoViewIfNeeded({ timeout: options?.timeout }).catch(() => undefined);
+    }
+    const box = await locator.boundingBox({ timeout: options?.timeout ?? 30000 }).catch(() => null);
+    if (!box) return null;
+
+    const isInput = inputBias || await isFrameInputElement(frame, selector);
+    const target = clickTarget(box, isInput, callCfg);
+    await humanMove(raw, cursor.x, cursor.y, target.x, target.y, callCfg);
+    cursor.x = target.x;
+    cursor.y = target.y;
+    return { callCfg, isInput };
  };

-  (frame as any).dblclick = async (selector: string, options?: any) => {
-    await (page as any).dblclick(selector, options);
+  const frameClick = async (selector: string, options?: HumanActionOptions) => {
+    const moved = await moveToFrameSelector(selector, options);
+    if (!moved) return origFrameClick(selector, options);
+    await humanClick(raw, moved.isInput, moved.callCfg);
  };

-  (frame as any).hover = async (selector: string, options?: any) => {
-    await (page as any).hover(selector, options);
+  const getFrameCdp = async () => stealth.getCdpSession().catch(() => null);
+
+  const frameHover = async (selector: string, options?: HumanActionOptions) => {
+    const moved = await moveToFrameSelector(selector, options, false);
+    if (!moved) return origFrameHover(selector, options);
  };

-  (frame as any).type = async (selector: string, text: string, options?: any) => {
-    await (page as any).type(selector, text, options);
+  (frame as any).click = frameClick;
+
+  (frame as any).dblclick = async (selector: string, options?: HumanActionOptions) => {
+    const moved = await moveToFrameSelector(selector, options);
+    if (!moved) return origFrameDblclick(selector, options);
+    await raw.down({ clickCount: 2 });
+    await sleep(rand(30, 60));
+    await raw.up({ clickCount: 2 });
  };

-  (frame as any).fill = async (selector: string, value: string, options?: any) => {
-    await (page as any).fill(selector, value, options);
+  (frame as any).hover = frameHover;
+
+  (frame as any).type = async (selector: string, text: string, options?: HumanActionOptions) => {
+    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    await sleep(randRange(callCfg.field_switch_delay));
+    await frameClick(selector, options);
+    await sleep(rand(100, 250));
+    const cdp = await getFrameCdp();
+    await humanType(page, rawKb, text, callCfg, cdp).catch(() => origFrameType(selector, text, options));
  };

-  (frame as any).check = async (selector: string, options?: any) => {
-    await (page as any).check(selector, options);
+  (frame as any).fill = async (selector: string, value: string, options?: HumanActionOptions) => {
+    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    await sleep(randRange(callCfg.field_switch_delay));
+    await frameClick(selector, options);
+    await sleep(rand(100, 250));
+    await originals.keyboardPress(SELECT_ALL);
+    await sleep(rand(30, 80));
+    await originals.keyboardPress('Backspace');
+    await sleep(rand(50, 150));
+    const cdp = await getFrameCdp();
+    await humanType(page, rawKb, value, callCfg, cdp).catch(() => origFrameFill(selector, value, options));
  };

-  (frame as any).uncheck = async (selector: string, options?: any) => {
-    await (page as any).uncheck(selector, options);
+  (frame as any).check = async (selector: string, options?: HumanActionOptions) => {
+    const locator = firstFrameLocator(frame, selector);
+    if (typeof locator.isChecked !== 'function') return origFrameCheck(selector, options);
+    const checked = await locator.isChecked();
+    if (!checked) await frameClick(selector, options).catch(() => origFrameCheck(selector, options));
  };

-  (frame as any).selectOption = async (selector: string, values: any, options?: any) => {
-    await (page as any).hover(selector);
+  (frame as any).uncheck = async (selector: string, options?: HumanActionOptions) => {
+    const locator = firstFrameLocator(frame, selector);
+    if (typeof locator.isChecked !== 'function') return origFrameUncheck(selector, options);
+    const checked = await locator.isChecked();
+    if (checked) await frameClick(selector, options).catch(() => origFrameUncheck(selector, options));
+  };
+
+  (frame as any).selectOption = async (selector: string, values: any, options?: HumanActionOptions) => {
+    await frameHover(selector, options);
    await sleep(rand(100, 300));
    return origFrameSelectOption(selector, values, options);
  };

-  (frame as any).press = async (selector: string, key: string, options?: any) => {
-    await (page as any).press(selector, key, options);
+  (frame as any).press = async (selector: string, key: string, options?: HumanActionOptions) => {
+    if (!await isFrameSelectorFocused(frame, selector)) {
+      await frameClick(selector, options);
+    }
+    await sleep(rand(50, 150));
+    await originals.keyboardPress(key);
  };

-  (frame as any).pressSequentially = async (selector: string, text: string, options?: any) => {
-    await (page as any).pressSequentially(selector, text, options);
+  (frame as any).pressSequentially = async (selector: string, text: string, options?: HumanActionOptions) => {
+    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
+    if (!await isFrameSelectorFocused(frame, selector)) {
+      await frameClick(selector, options);
+    }
+    await sleep(rand(100, 250));
+    const cdp = await getFrameCdp();
+    await humanType(page, rawKb, text, callCfg, cdp).catch(() => origFramePressSequentially?.(selector, text, options));
  };

-  (frame as any).tap = async (selector: string, options?: any) => {
-    await (page as any).tap(selector, options);
+  (frame as any).tap = async (selector: string, options?: HumanActionOptions) => {
+    await frameClick(selector, options).catch(() => origFrameTap?.(selector, options));
  };

-  (frame as any).clear = async (selector: string, options?: any) => {
-    if (!await isSelectorFocused(stealth, page, selector)) {
-      await (page as any).click(selector);
+  (frame as any).clear = async (selector: string, options?: HumanActionOptions) => {
+    if (!await isFrameSelectorFocused(frame, selector)) {
+      await frameClick(selector, options);
    }
    await sleep(rand(50, 150));
    await originals.keyboardPress(SELECT_ALL);
@@ -599,9 +811,17 @@ function patchSingleFrame(
    await originals.keyboardPress('Backspace');
  };

-  (frame as any).dragAndDrop = async (source: string, target: string, options?: any) => {
-    const srcBox = await frame.locator(source).boundingBox().catch(() => null);
-    const tgtBox = await frame.locator(target).boundingBox().catch(() => null);
+  (frame as any).dragAndDrop = async (source: string, target: string, options?: {
+    force?: boolean;
+    noWaitAfter?: boolean;
+    sourcePosition?: { x: number; y: number };
+    strict?: boolean;
+    targetPosition?: { x: number; y: number };
+    timeout?: number;
+    trial?: boolean;
+  }) => {
+    const srcBox = await firstFrameLocator(frame, source).boundingBox({ timeout: options?.timeout ?? 30000 }).catch(() => null);
+    const tgtBox = await firstFrameLocator(frame, target).boundingBox({ timeout: options?.timeout ?? 30000 }).catch(() => null);

    if (srcBox && tgtBox) {
      const sx = srcBox.x + srcBox.width / 2;
@@ -670,14 +890,14 @@ export function patchBrowser(browser: Browser, cfg: HumanConfig): void {
  }

  const origNewContext = browser.newContext.bind(browser);
-  (browser as any).newContext = async (options?: any) => {
+  (browser as any).newContext = async (options?: Parameters<typeof origNewContext>[0]) => {
    const context = await origNewContext(options);
    patchContext(context, cfg);
    return context;
  };

  const origNewPage = browser.newPage.bind(browser);
-  (browser as any).newPage = async (options?: any) => {
+  (browser as any).newPage = async (options?: Parameters<typeof origNewPage>[0]) => {
    const page = await origNewPage(options);
    if (!(page as any)._original) {
      const ctx = page.context();
@@ -172,13 +172,33 @@ export async function humanClick(
 // Human idle / drift
 // ---------------------------------------------------------------------------

-export async function humanIdle(
+export function humanIdle(
+  raw: RawMouse,
+  cx: number,
+  cy: number,
+  cfg: HumanConfig,
+): Promise<void>;
+export function humanIdle(
  raw: RawMouse,
  seconds: number,
  cx: number,
  cy: number,
  cfg: HumanConfig,
+): Promise<void>;
+export async function humanIdle(
+  raw: RawMouse,
+  secondsOrCx: number,
+  cxOrCy: number,
+  cyOrCfg: number | HumanConfig,
+  maybeCfg?: HumanConfig,
 ): Promise<void> {
+  const hasExplicitSeconds = maybeCfg !== undefined;
+  const seconds = hasExplicitSeconds
+    ? secondsOrCx
+    : rand((cyOrCfg as HumanConfig).idle_between_duration[0], (cyOrCfg as HumanConfig).idle_between_duration[1]);
+  const cx = hasExplicitSeconds ? cxOrCy : secondsOrCx;
+  const cy = hasExplicitSeconds ? (cyOrCfg as number) : cxOrCy;
+  const cfg = hasExplicitSeconds ? maybeCfg! : (cyOrCfg as HumanConfig);
  const endTime = Date.now() + seconds * 1000;
  let x = cx;
  let y = cy;
@@ -38,26 +38,29 @@ async function smoothWheel(raw: RawMouse, delta: number, cfg: HumanConfig): Prom
  }
 }

-export async function scrollToElement(
+/**
+ * Humanized scrolling that takes an arbitrary ``getBox`` callable.
+ *
+ * Used by both ``scrollToElement`` (selector-based) and the ElementHandle
+ * ``scrollIntoViewIfNeeded`` patch so the same accelerate → cruise →
+ * decelerate → overshoot behavior runs everywhere.
+ */
+export async function humanScrollIntoView(
  page: Page,
  raw: RawMouse,
-  selector: string,
+  getBox: () => Promise<ElementBounds | null>,
  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');

-  let box = await getElementBox(page, selector);
-  if (!box) {
-    await sleep(200);
-    box = await getElementBox(page, selector);
-    if (!box) throw new Error(`Element not found: ${selector}`);
-  }
+  let box = await getBox();
+  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
@@ -107,7 +110,7 @@ export async function scrollToElement(

    // Check visibility every 3 steps
    if (i % 3 === 2 || i === totalClicks - 1) {
-      box = await getElementBox(page, selector);
+      box = await getBox();
      if (box && isInViewport(box, viewport.height, cfg)) {
        break;
      }
@@ -133,16 +136,45 @@ export async function scrollToElement(
  // Settle
  await sleep(randRange(cfg.scroll_settle_delay));

-  box = await getElementBox(page, selector);
-  if (!box) throw new Error(`Element lost after scrolling: ${selector}`);
+  box = await getBox();
+  if (!box) throw new Error('Element lost after scrolling into view');

-  return { box, cursorX, cursorY };
+  return { box, cursorX, cursorY, didScroll: true };
 }

-async function getElementBox(page: Page, selector: string): Promise<ElementBounds | null> {
+/**
+ * Selector-based humanized scroll.
+ *
+ * ``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,
+  raw: RawMouse,
+  selector: string,
+  cursorX: number,
+  cursorY: number,
+  cfg: HumanConfig,
+  timeout?: number,
+): Promise<{ box: ElementBounds; cursorX: number; cursorY: number; didScroll: boolean }> {
+  return humanScrollIntoView(
+    page, raw,
+    () => getElementBox(page, selector, timeout),
+    cursorX, cursorY, cfg,
+  );
+}
+
+async function getElementBox(
+  page: Page,
+  selector: string,
+  timeout: number = 30000,
+): Promise<ElementBounds | null> {
  const el = page.locator(selector).first();
  try {
-    const box = await el.boundingBox({ timeout: 2000 });
+    const box = await el.boundingBox({ timeout: Math.max(1, timeout) });
    return box;
  } catch {
    return null;
@@ -3,7 +3,7 @@
 * Mirrors Python cloakbrowser/browser.py.
 */

-import type { Browser, BrowserContext } from "playwright-core";
+import type { Browser, BrowserContext, BrowserContextOptions } 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";
@@ -21,6 +21,29 @@ export function resolveTimezone<T extends { timezone?: string; timezoneId?: stri
  return options;
 }

+/**
+ * Strip `locale` and `timezoneId` from user-provided contextOptions — both route
+ * through detectable CDP emulation. The wrapper's top-level `locale`/`timezone`
+ * fields use binary flags instead (undetectable). Warn so users notice.
+ */
+function filterStealthCtxOptions(ctx?: BrowserContextOptions): Partial<BrowserContextOptions> {
+  if (!ctx) return {};
+  const { locale, timezoneId, ...rest } = ctx;
+  if (locale !== undefined) {
+    console.warn(
+      "[cloakbrowser] contextOptions.locale ignored — use top-level `locale` " +
+      "instead (routes through binary flag, avoids detectable CDP emulation)."
+    );
+  }
+  if (timezoneId !== undefined) {
+    console.warn(
+      "[cloakbrowser] contextOptions.timezoneId ignored — use top-level `timezone` " +
+      "instead (routes through binary flag, avoids detectable CDP emulation)."
+    );
+  }
+  return rest;
+}
+
 /**
 * Launch stealth Chromium browser via Playwright.
 *
@@ -60,8 +83,8 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
    const { patchBrowser } = await import('./human/index.js');
    const { resolveConfig } = await import('./human/config.js');
    const cfg = resolveConfig(
-      (options.humanPreset as any) ?? 'default',
-      options.humanConfig as any,
+      options.humanPreset ?? 'default',
+      options.humanConfig,
    );
    patchBrowser(browser, cfg);
  }
@@ -104,6 +127,9 @@ export async function launchContext(
  let context: BrowserContext;
  try {
    context = await browser.newContext({
+      // contextOptions first — explicit wrapper fields below override it.
+      // filterStealthCtxOptions strips locale/timezoneId to prevent CDP detection.
+      ...filterStealthCtxOptions(options.contextOptions),
      ...(options.userAgent ? { userAgent: options.userAgent } : {}),
      viewport: options.viewport === undefined ? DEFAULT_VIEWPORT : options.viewport,
      ...(options.colorScheme ? { colorScheme: options.colorScheme } : {}),
@@ -125,8 +151,8 @@ export async function launchContext(
    const { patchContext } = await import('./human/index.js');
    const { resolveConfig } = await import('./human/config.js');
    const cfg = resolveConfig(
-      (options.humanPreset as any) ?? 'default',
-      options.humanConfig as any,
+      options.humanPreset ?? 'default',
+      options.humanConfig,
    );
    patchContext(context, cfg);
  }
@@ -178,6 +204,9 @@ export async function launchPersistentContext(
    args,
    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
    ...(proxyOption ? { proxy: proxyOption } : {}),
+    // contextOptions before explicit wrapper fields so explicit wins.
+    // filterStealthCtxOptions strips locale/timezoneId to prevent CDP detection.
+    ...filterStealthCtxOptions(options.contextOptions),
    ...(options.userAgent ? { userAgent: options.userAgent } : {}),
    viewport: options.viewport === undefined ? DEFAULT_VIEWPORT : options.viewport,
    ...(options.colorScheme ? { colorScheme: options.colorScheme } : {}),
@@ -189,8 +218,8 @@ export async function launchPersistentContext(
    const { patchContext } = await import('./human/index.js');
    const { resolveConfig } = await import('./human/config.js');
    const cfg = resolveConfig(
-      (options.humanPreset as any) ?? 'default',
-      options.humanConfig as any,
+      options.humanPreset ?? 'default',
+      options.humanConfig,
    );
    patchContext(context, cfg);
  }
@@ -43,6 +43,40 @@ export function isSocksProxy(proxy: string | ProxyDict | undefined | null): bool
  return /^socks5h?:\/\//i.test(url);
 }

+/**
+ * Build a SOCKS URL from already-percent-encoded credentials and a host suffix.
+ *
+ * `encPass === null` means no password (no colon in userinfo). Empty string
+ * means present-but-empty (colon preserved).
+ */
+function assembleSocksUrl(
+  scheme: string,
+  encUser: string,
+  encPass: string | null,
+  hostAndRest: string,
+): string {
+  let userinfo: string;
+  if (encPass !== null) {
+    userinfo = `${encUser}:${encPass}@`;
+  } else if (encUser) {
+    userinfo = `${encUser}@`;
+  } else {
+    userinfo = "";
+  }
+  return `${scheme}://${userinfo}${hostAndRest}`;
+}
+
+/**
+ * Lenient percent-decode that handles malformed escapes gracefully, matching
+ * Python's ``urllib.parse.unquote``: valid ``%XX`` sequences are decoded,
+ * bare ``%`` not followed by two hex digits is left as a literal ``%``.
+ */
+function lenientDecodeURIComponent(s: string): string {
+  return s.replace(/%([0-9A-Fa-f]{2})|%/g, (match, hex) =>
+    hex ? String.fromCharCode(parseInt(hex, 16)) : "%",
+  );
+}
+
 /**
 * Reconstruct a SOCKS5 URL with inline credentials from a proxy dict.
 */
@@ -55,6 +89,72 @@ export function reconstructSocksUrl(proxy: ProxyDict): string {
  return url.href.replace(/\/$/, "");
 }

+/**
+ * Re-encode credentials in a SOCKS5 URL string so Chromium's parser doesn't
+ * truncate them at special chars like '='. Idempotent: pre-encoded input stays
+ * the same (decoded then re-encoded).
+ *
+ * Parsing is done manually rather than via `new URL` + setters, because WHATWG
+ * URL's username/password setters re-encode `%` on assignment, causing
+ * double-encoding when we round-trip decode-then-encode.
+ *
+ * On any unexpected failure, logs a warning and returns the original string
+ * so Chromium's own error handling can surface the real problem.
+ */
+export function normalizeSocksStringUrl(urlStr: string): string {
+  // Split userinfo from host at the LAST '@' (RFC 3986), so a raw '@' inside
+  // a password like `socks5://user:p@ss@host:1080` parses correctly. Matches
+  // Python urlparse's rpartition('@') behavior.
+  const schemeMatch = urlStr.match(/^([a-z][a-z0-9+\-.]*):\/\/(.*)$/i);
+  if (!schemeMatch) return urlStr;
+  const [, scheme, rest] = schemeMatch;
+  const hostStart = rest.search(/[/?#]/);
+  const authority = hostStart === -1 ? rest : rest.slice(0, hostStart);
+  const suffix = hostStart === -1 ? "" : rest.slice(hostStart);
+  const atIdx = authority.lastIndexOf("@");
+  if (atIdx === -1) return urlStr;  // no creds
+  const userinfo = authority.slice(0, atIdx);
+  const hostPart = authority.slice(atIdx + 1);
+  // Validate port (matches Python's urlparse().port ValueError guard).
+  // Extract port after last ':' — but skip IPv6 brackets (e.g. [::1]:1080).
+  const bracketEnd = hostPart.lastIndexOf("]");
+  const portColonIdx = hostPart.indexOf(":", Math.max(bracketEnd, 0));
+  if (portColonIdx !== -1) {
+    const portStr = hostPart.slice(portColonIdx + 1);
+    if (portStr && !/^\d+$/.test(portStr)) {
+      console.warn(`[cloakbrowser] Malformed SOCKS5 proxy URL, passing through unchanged: invalid port`);
+      return urlStr;
+    }
+  }
+  const hostAndRest = hostPart + suffix;
+  const colonIdx = userinfo.indexOf(":");
+  const rawUserEnc = colonIdx === -1 ? userinfo : userinfo.slice(0, colonIdx);
+  const hasPassword = colonIdx !== -1;
+  const rawPassEnc = hasPassword ? userinfo.slice(colonIdx + 1) : "";
+  try {
+    const encUser = rawUserEnc ? encodeURIComponent(lenientDecodeURIComponent(rawUserEnc)) : "";
+    const encPass = hasPassword
+      ? (rawPassEnc ? encodeURIComponent(lenientDecodeURIComponent(rawPassEnc)) : "")
+      : null;
+    const normalized = assembleSocksUrl(scheme, encUser, encPass, hostAndRest);
+    // Compare credentials, not the full URL: keeps the log condition focused
+    // on real encoding work, not cosmetic differences (parity with the Python
+    // implementation, which has to skip urlparse's hostname lowercasing).
+    const credsChanged = encUser !== rawUserEnc
+      || (hasPassword ? encPass !== rawPassEnc : false);
+    if (credsChanged) {
+      console.info(
+        "[cloakbrowser] Auto URL-encoded SOCKS5 proxy credentials (special " +
+        "characters detected). Pre-encode the URL to suppress this notice.",
+      );
+    }
+    return normalized;
+  } catch (e) {
+    console.warn(`[cloakbrowser] Could not normalize SOCKS5 proxy URL, passing through unchanged: ${(e as Error).message}`);
+    return urlStr;
+  }
+}
+
 /**
 * Resolve proxy into Playwright option and/or Chrome args.
 *
@@ -67,7 +167,9 @@ export function resolveProxyConfig(proxy: string | ProxyDict | undefined): Proxy
  if (isSocksProxy(proxy)) {
    // SOCKS5: bypass Playwright, pass directly to Chrome via --proxy-server.
    if (typeof proxy === "string") {
-      return { proxyArgs: [`--proxy-server=${proxy}`] };
+      // Re-encode creds to work around Chromium parser truncating passwords
+      // at '=' and other special chars (#157).
+      return { proxyArgs: [`--proxy-server=${normalizeSocksStringUrl(proxy)}`] };
    }
    const socksUrl = reconstructSocksUrl(proxy);
    const args = [`--proxy-server=${socksUrl}`];
@@ -94,8 +94,8 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
    const { patchBrowser } = await import('./human-puppeteer/index.js');
    const { resolveConfig } = await import('./human/config.js');
    const cfg = resolveConfig(
-      (options.humanPreset as any) ?? 'default',
-      options.humanConfig as any,
+      options.humanPreset ?? 'default',
+      options.humanConfig,
    );
    patchBrowser(browser, cfg);
  }
@@ -2,6 +2,9 @@
 * Shared types for cloakbrowser launch wrappers.
 */

+import type { BrowserContextOptions } from "playwright-core";
+import type { HumanConfig, HumanPreset } from "./human/config.js";
+
 export interface LaunchOptions {
  /** Run in headless mode (default: true). */
  headless?: boolean;
@@ -27,9 +30,9 @@ export interface LaunchOptions {
  /** Enable human-like mouse, keyboard, and scroll behavior. */
  humanize?: boolean;
  /** Human behavior preset: 'default' or 'careful'. */
-  humanPreset?: 'default' | 'careful';
+  humanPreset?: HumanPreset;
  /** Override individual human behavior parameters. */
-  humanConfig?: Record<string, unknown>;
+  humanConfig?: Partial<HumanConfig>;
 }

 export interface LaunchContextOptions extends LaunchOptions {
@@ -43,6 +46,15 @@ export interface LaunchContextOptions extends LaunchOptions {
  timezoneId?: string;
  /** Color scheme preference — 'light', 'dark', or 'no-preference'. */
  colorScheme?: "light" | "dark" | "no-preference";
+  /**
+   * Extra options forwarded directly to Playwright's `browser.newContext()` —
+   * e.g. `storageState`, `permissions`, `geolocation`, `extraHTTPHeaders`,
+   * `httpCredentials`. Use this for context-level options not surfaced as
+   * top-level fields. `locale` and `timezoneId` are stripped here to avoid
+   * detectable CDP emulation — use the top-level `locale` and `timezone`
+   * wrapper fields instead (they route through undetectable binary flags).
+   */
+  contextOptions?: BrowserContextOptions;
 }

 export interface LaunchPersistentContextOptions extends LaunchContextOptions {
@@ -1,5 +1,17 @@
-import { describe, it, expect } from "vitest";
-import { COUNTRY_LOCALE_MAP, resolveProxyIp } from "../src/geoip.js";
+import { describe, it, expect, afterEach, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { COUNTRY_LOCALE_MAP, maybeResolveGeoip, resolveProxyGeo, resolveProxyIp } from "../src/geoip.js";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  delete process.env.CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS;
+  delete process.env.CLOAKBROWSER_CACHE_DIR;
+  for (const dir of tempDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});

 describe("resolveProxyIp", () => {
  it("returns literal IPv4 from proxy URL", async () => {
@@ -38,6 +50,51 @@ describe("resolveProxyIp", () => {
  });
 });

+describe("maybeResolveGeoip", () => {
+  it("does not apply the GeoIP resolution timeout to first-use database download", async () => {
+    const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "cloak-geoip-download-"));
+    tempDirs.push(cacheDir);
+    process.env.CLOAKBROWSER_CACHE_DIR = cacheDir;
+    process.env.CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS = "0.001";
+
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      body: new ReadableStream({
+        start(controller) {
+          controller.enqueue(new Uint8Array([1, 2, 3]));
+          controller.close();
+        },
+      }),
+    } as Response);
+
+    const result = await resolveProxyGeo("http://203.0.113.10:8080");
+
+    expect(result).toEqual({ timezone: null, locale: null, exitIp: null });
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    expect(fetchSpy.mock.calls[0][1]).toEqual({ redirect: "follow" });
+  });
+
+  it("returns quickly when GeoIP resolution times out", async () => {
+    const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "cloak-geoip-timeout-"));
+    tempDirs.push(cacheDir);
+    process.env.CLOAKBROWSER_CACHE_DIR = cacheDir;
+    process.env.CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS = "0.025";
+
+    const start = performance.now();
+    const result = await maybeResolveGeoip({
+      geoip: true,
+      proxy: "http://203.0.113.10:8080",
+      timezone: "Europe/Paris",
+      locale: "fr-FR",
+    });
+    const elapsed = performance.now() - start;
+
+    expect(result).toEqual({ timezone: "Europe/Paris", locale: "fr-FR", exitIp: undefined });
+    expect(elapsed).toBeLessThan(500);
+  });
+});
+
+
 describe("COUNTRY_LOCALE_MAP", () => {
  it("contains common countries", () => {
    for (const code of ["US", "GB", "DE", "FR", "JP", "BR", "IL", "RU"]) {
@@ -4,14 +4,20 @@ import { DEFAULT_VIEWPORT, getChromiumVersion } from "../src/config.js";

 describe("binaryInfo", () => {
  it("returns correct structure", () => {
-    const info = binaryInfo();
+    const orig = process.env.CLOAKBROWSER_CACHE_DIR;
+    process.env.CLOAKBROWSER_CACHE_DIR = `/tmp/cloakbrowser-test-${Date.now()}`;
+    try {
+      const info = binaryInfo();

-    expect(info.version).toBe(getChromiumVersion());
-    expect(info.platform).toMatch(/^(linux|darwin|windows)-(x64|arm64)$/);
-    expect(info.binaryPath).toBeTruthy();
-    expect(typeof info.installed).toBe("boolean");
-    expect(info.cacheDir).toContain("cloakbrowser");
-    expect(info.downloadUrl).toContain(".tar.gz");
+      expect(info.version).toBe(getChromiumVersion());
+      expect(info.platform).toMatch(/^(linux|darwin|windows)-(x64|arm64)$/);
+      expect(info.binaryPath).toBeTruthy();
+      expect(typeof info.installed).toBe("boolean");
+      expect(info.cacheDir).toContain("cloakbrowser");
+    } finally {
+      if (orig) process.env.CLOAKBROWSER_CACHE_DIR = orig;
+      else delete process.env.CLOAKBROWSER_CACHE_DIR;
+    }
  });
 });

@@ -130,6 +136,60 @@ describe("launchContext (unit)", () => {
    // Browser also closed
    expect(mockBrowser.close).toHaveBeenCalledOnce();
  });
+
+  it("forwards contextOptions to newContext (storageState, etc.)", async () => {
+    const { launchContext } = await import("../src/playwright.js");
+    await launchContext({
+      contextOptions: {
+        storageState: "state.json",
+        permissions: ["geolocation"],
+      },
+    });
+
+    const ctxArgs = mockBrowser.newContext.mock.calls[0][0];
+    expect(ctxArgs.storageState).toBe("state.json");
+    expect(ctxArgs.permissions).toEqual(["geolocation"]);
+  });
+
+  it("explicit top-level fields win over contextOptions on collision", async () => {
+    const { launchContext } = await import("../src/playwright.js");
+    await launchContext({
+      userAgent: "Explicit/1.0",
+      viewport: { width: 1280, height: 720 },
+      colorScheme: "dark",
+      contextOptions: {
+        userAgent: "ShouldBeOverridden/9.9",
+        viewport: { width: 9999, height: 9999 },
+        colorScheme: "light",
+      },
+    });
+
+    const ctxArgs = mockBrowser.newContext.mock.calls[0][0];
+    expect(ctxArgs.userAgent).toBe("Explicit/1.0");
+    expect(ctxArgs.viewport).toEqual({ width: 1280, height: 720 });
+    expect(ctxArgs.colorScheme).toBe("dark");
+  });
+
+  it("strips locale and timezoneId from contextOptions (stealth-sensitive)", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { launchContext } = await import("../src/playwright.js");
+    await launchContext({
+      contextOptions: {
+        storageState: "state.json",
+        locale: "de-DE",
+        timezoneId: "Europe/Berlin",
+      },
+    });
+
+    const ctxArgs = mockBrowser.newContext.mock.calls[0][0];
+    // Stealth-sensitive keys stripped — they would reintroduce detectable CDP emulation.
+    expect(ctxArgs.locale).toBeUndefined();
+    expect(ctxArgs.timezoneId).toBeUndefined();
+    // Benign keys preserved
+    expect(ctxArgs.storageState).toBe("state.json");
+    // Warning was logged for both stripped keys
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+  });
 });

 describe("launchPersistentContext (unit)", () => {
@@ -207,4 +267,53 @@ describe("launchPersistentContext (unit)", () => {
    expect(args.userAgent).toBe("Custom/1.0");
    expect(args.colorScheme).toBe("dark");
  });
+
+  it("forwards contextOptions to launchPersistentContext", async () => {
+    const { launchPersistentContext } = await import("../src/playwright.js");
+    await launchPersistentContext({
+      userDataDir: "/tmp/profile",
+      contextOptions: {
+        permissions: ["geolocation"],
+        extraHTTPHeaders: { "X-Custom": "1" },
+      },
+    });
+
+    const args = mockChromium.launchPersistentContext.mock.calls[0][1];
+    expect(args.permissions).toEqual(["geolocation"]);
+    expect(args.extraHTTPHeaders).toEqual({ "X-Custom": "1" });
+  });
+
+  it("explicit top-level fields win over contextOptions in persistent context", async () => {
+    const { launchPersistentContext } = await import("../src/playwright.js");
+    await launchPersistentContext({
+      userDataDir: "/tmp/profile",
+      userAgent: "Explicit/1.0",
+      viewport: { width: 1280, height: 720 },
+      contextOptions: {
+        userAgent: "ShouldBeOverridden/9.9",
+        viewport: { width: 9999, height: 9999 },
+      },
+    });
+
+    const args = mockChromium.launchPersistentContext.mock.calls[0][1];
+    expect(args.userAgent).toBe("Explicit/1.0");
+    expect(args.viewport).toEqual({ width: 1280, height: 720 });
+  });
+
+  it("strips locale and timezoneId from contextOptions (persistent context)", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { launchPersistentContext } = await import("../src/playwright.js");
+    await launchPersistentContext({
+      userDataDir: "/tmp/profile",
+      contextOptions: {
+        locale: "de-DE",
+        timezoneId: "Europe/Berlin",
+      },
+    });
+
+    const args = mockChromium.launchPersistentContext.mock.calls[0][1];
+    expect(args.locale).toBeUndefined();
+    expect(args.timezoneId).toBeUndefined();
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+  });
 });
@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { parseProxyUrl, isSocksProxy, resolveProxyConfig } from "../src/proxy.js";
 import type { LaunchOptions } from "../src/types.js";

@@ -191,8 +191,7 @@ describe("resolveProxyConfig", () => {
      password: "p@ss",
    });
    expect(proxyOption).toBeUndefined();
-    expect(proxyArgs.length).toBe(1);
-    expect(proxyArgs[0]).toContain("--proxy-server=socks5://user:p%40ss@host:1080");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://user:p%40ss@host:1080"]);
  });

  it("includes bypass for socks5 dict", () => {
@@ -203,4 +202,123 @@ describe("resolveProxyConfig", () => {
    expect(proxyArgs).toContain("--proxy-server=socks5://host:1080");
    expect(proxyArgs).toContain("--proxy-bypass-list=.example.com");
  });
+
+  // Chromium's --proxy-server parser truncates passwords at '=' (#157).
+  // Wrapper must auto URL-encode before passing to Chrome.
+  it("encodes '=' in socks5 string password", () => {
+    const { proxyArgs } = resolveProxyConfig("socks5://user:pass=123@host:1080");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://user:pass%3D123@host:1080"]);
+  });
+
+  it("encoding is idempotent for already-encoded socks5 string", () => {
+    const { proxyArgs } = resolveProxyConfig("socks5://user:pass%3D123@host:1080");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://user:pass%3D123@host:1080"]);
+  });
+
+  it("leaves socks5 string without creds unchanged", () => {
+    const { proxyArgs } = resolveProxyConfig("socks5://host:1080");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://host:1080"]);
+  });
+
+  it("encodes password even with empty username (password-only userinfo)", () => {
+    // Regression: empty-username bypass would skip encoding, leaving the
+    // Chromium truncation bug alive for this userinfo shape.
+    const { proxyArgs } = resolveProxyConfig("socks5://:pass=123@host:1080");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://:pass%3D123@host:1080"]);
+  });
+
+  it("handles literal '%' in password without throwing (malformed escape)", () => {
+    // JS's decodeURIComponent throws on '%sure' (% not followed by 2 hex digits).
+    // Must fall back to treating '%' as literal and percent-encoding it.
+    const { proxyArgs } = resolveProxyConfig("socks5://user:100%sure@host:1080");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://user:100%25sure@host:1080"]);
+  });
+
+  it("passes malformed SOCKS5 URLs through unchanged (no throw)", () => {
+    // Broken IPv6 bracket — wrapper must not throw;
+    // Chromium will surface its own error.
+    const { proxyArgs: a1 } = resolveProxyConfig("socks5://user:pass@[::1");
+    expect(a1).toEqual(["--proxy-server=socks5://user:pass@[::1"]);
+  });
+
+  it("passes non-numeric port through unchanged", () => {
+    const { proxyArgs } = resolveProxyConfig("socks5://user:pass@host:abc");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://user:pass@host:abc"]);
+  });
+
+  it("encodes special chars in IPv6 SOCKS5 string password", () => {
+    const { proxyArgs } = resolveProxyConfig("socks5://user:pass=eq@[::1]:1080");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://user:pass%3Deq@[::1]:1080"]);
+  });
+
+  // Regression #157: userinfo must be split at the LAST '@' (RFC 3986),
+  // not the first, so raw '@' in a password parses correctly.
+  it("encodes raw '@' in socks5 string password (last-@ split)", () => {
+    const { proxyArgs } = resolveProxyConfig("socks5://user:p@ss@host:1080");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://user:p%40ss@host:1080"]);
+  });
+
+  it("handles multiple raw '@' in password (splits at last)", () => {
+    const { proxyArgs } = resolveProxyConfig("socks5://user:a@b@c@host:1080");
+    expect(proxyArgs).toEqual(["--proxy-server=socks5://user:a%40b%40c@host:1080"]);
+  });
+
+  // Visibility for #157: when wrapper actually rewrites the URL, surface an
+  // info log so users debugging silent SOCKS5 fallback can see what happened.
+  it("logs info message when SOCKS5 credentials get re-encoded", () => {
+    const debugSpy = vi.spyOn(console, "info").mockImplementation(() => {});
+    try {
+      resolveProxyConfig("socks5://user:pass=123@host:1080");
+      expect(debugSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Auto URL-encoded SOCKS5"),
+      );
+      // Credentials must not leak into the log.
+      const calls = debugSpy.mock.calls.flat().join(" ");
+      expect(calls).not.toContain("pass=123");
+      expect(calls).not.toContain("pass%3D123");
+    } finally {
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("stays silent when SOCKS5 URL is already encoded (no log spam)", () => {
+    const debugSpy = vi.spyOn(console, "info").mockImplementation(() => {});
+    try {
+      resolveProxyConfig("socks5://user:pass%3D123@host:1080");
+      const reencodedCalls = debugSpy.mock.calls
+        .flat()
+        .filter((arg) => typeof arg === "string" && arg.includes("Auto URL-encoded SOCKS5"));
+      expect(reencodedCalls).toHaveLength(0);
+    } finally {
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("stays silent when SOCKS5 URL has no credentials", () => {
+    const debugSpy = vi.spyOn(console, "info").mockImplementation(() => {});
+    try {
+      resolveProxyConfig("socks5://host:1080");
+      const reencodedCalls = debugSpy.mock.calls
+        .flat()
+        .filter((arg) => typeof arg === "string" && arg.includes("Auto URL-encoded SOCKS5"));
+      expect(reencodedCalls).toHaveLength(0);
+    } finally {
+      debugSpy.mockRestore();
+    }
+  });
+
+  it("stays silent when only host case differs (no credential rewrite)", () => {
+    // Parity with Python: log condition must track credential changes, not
+    // cosmetic URL-string differences (regression for Copilot's PR #209 review).
+    const debugSpy = vi.spyOn(console, "info").mockImplementation(() => {});
+    try {
+      resolveProxyConfig("socks5://USER:pass@HOST.com:1080");
+      const reencodedCalls = debugSpy.mock.calls
+        .flat()
+        .filter((arg) => typeof arg === "string" && arg.includes("Auto URL-encoded SOCKS5"));
+      expect(reencodedCalls).toHaveLength(0);
+    } finally {
+      debugSpy.mockRestore();
+    }
+  });
 });
@@ -532,6 +532,52 @@ describe("Puppeteer: non-ASCII text avoids CDP shift path", () => {
 });


+// =========================================================================
+// Per-call human config override (Puppeteer page-level)
+// =========================================================================
+describe("Puppeteer: page.type accepts per-call human config override", () => {
+  it("page.type forwards merged config to humanType", async () => {
+    const keyboardMod = await import("../src/human-puppeteer/keyboard.js");
+    const scrollMod = await import("../src/human-puppeteer/scroll.js");
+
+    const cfg = resolveConfig("default", {
+      idle_between_actions: false,
+      field_switch_delay: [0, 1],
+    });
+    expect(cfg.typing_delay).toBe(70);
+
+    let captured: any = null;
+    const typeSpy = vi.spyOn(keyboardMod, "humanType").mockImplementation(
+      async (_page, _raw, _text, callCfg) => { captured = callCfg; },
+    );
+    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,
+      }),
+    );
+
+    const { patchPage } = await import("../src/human-puppeteer/index.js");
+    const page = buildMockPage();
+    const cursor = { x: 100, y: 100, initialized: true };
+    patchPage(page as any, cfg, cursor as any);
+
+    await (page as any).type("#email", "hi", {
+      typing_delay: 30,
+      mistype_chance: 0,
+    });
+
+    expect(captured.typing_delay).toBe(30);
+    expect(captured.mistype_chance).toBe(0);
+    expect(cfg.typing_delay).toBe(70);
+
+    typeSpy.mockRestore();
+    scrollSpy.mockRestore();
+  });
+});
+
+
 // =========================================================================
 // patchPage stealth infrastructure (Puppeteer)
 // =========================================================================
@@ -1671,11 +1717,13 @@ describe("Puppeteer: isInputElement stealth integration via patchPage", () => {
      }),
    });

+    const mockEl = buildMockElementHandle();
    const page = buildMockPage({
      evaluate: vi.fn(async (...args: any[]) => {
        evaluateCalls.push(args);
        return false;
      }),
+      $: vi.fn(async () => mockEl),
    });
    page.createCDPSession = vi.fn(async () => mockCdp);

@@ -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(() => ({
@@ -320,8 +320,14 @@ describe("download fallback", () => {

 describe("effective version", () => {
  it("returns platform version when no marker exists", () => {
-    // Default behavior — no marker file in test environment
-    expect(getEffectiveVersion()).toBe(getChromiumVersion());
+    const orig = process.env.CLOAKBROWSER_CACHE_DIR;
+    process.env.CLOAKBROWSER_CACHE_DIR = `/tmp/cloakbrowser-test-${Date.now()}`;
+    try {
+      expect(getEffectiveVersion()).toBe(getChromiumVersion());
+    } finally {
+      if (orig) process.env.CLOAKBROWSER_CACHE_DIR = orig;
+      else delete process.env.CLOAKBROWSER_CACHE_DIR;
+    }
  });
 });

@@ -22,6 +22,8 @@ parse_connection_params = _mod.parse_connection_params
 parse_cli_args = _mod.parse_cli_args
 ChromePool = _mod.ChromePool
 _default_data_dir = _mod._default_data_dir
+SAFE_SEED_RE = _mod.SAFE_SEED_RE
+RESERVED_SEEDS = _mod.RESERVED_SEEDS


 # ---------------------------------------------------------------------------
@@ -244,3 +246,95 @@ class TestConnectionTracking:
        pool.disconnect("a")
        assert pool._connections["a"] == 1
        assert pool._connections["b"] == 1
+
+
+# ---------------------------------------------------------------------------
+# Seed validation (CVE fix — path traversal via fingerprint param)
+# ---------------------------------------------------------------------------
+
+
+class TestSeedValidation:
+    """Verify SAFE_SEED_RE rejects path traversal and reserved names."""
+
+    @pytest.mark.parametrize("seed", [
+        "../foo", "../../etc", "/etc/passwd", "..", ".", "foo/bar",
+        "foo\\bar", "\x00evil", "", "a" * 129,
+    ])
+    def test_malicious_seeds_rejected(self, seed):
+        assert not SAFE_SEED_RE.match(seed)
+
+    @pytest.mark.parametrize("seed", [
+        "__default__",
+    ])
+    def test_reserved_seeds_rejected(self, seed):
+        assert seed in RESERVED_SEEDS
+
+    @pytest.mark.parametrize("seed", [
+        "12345", "my-seed_01", "ABC", "a" * 128, "0", "test-seed",
+    ])
+    def test_valid_seeds_accepted(self, seed):
+        assert SAFE_SEED_RE.match(seed)
+        assert seed not in RESERVED_SEEDS
+
+
+# ---------------------------------------------------------------------------
+# Path containment (_safe_rmtree)
+# ---------------------------------------------------------------------------
+
+
+class TestSafeRmtree:
+    """Verify _safe_rmtree refuses to delete outside data_dir."""
+
+    def _make_pool(self, data_dir: str):
+        return ChromePool(
+            binary="/fake/chrome",
+            global_args=[],
+            headless=True,
+            data_dir=data_dir,
+        )
+
+    def test_refuses_path_outside_data_dir(self, tmp_path):
+        data_dir = tmp_path / "profiles"
+        data_dir.mkdir()
+        victim = tmp_path / "victim"
+        victim.mkdir()
+        (victim / "sentinel").touch()
+
+        pool = self._make_pool(str(data_dir))
+        pool._safe_rmtree(str(victim))
+
+        assert victim.exists(), "Directory outside data_dir must not be deleted"
+
+    def test_refuses_data_dir_itself(self, tmp_path):
+        data_dir = tmp_path / "profiles"
+        data_dir.mkdir()
+        (data_dir / "sentinel").touch()
+
+        pool = self._make_pool(str(data_dir))
+        pool._safe_rmtree(str(data_dir))
+
+        assert data_dir.exists(), "data_dir itself must not be deleted"
+
+    def test_deletes_valid_subdirectory(self, tmp_path):
+        data_dir = tmp_path / "profiles"
+        data_dir.mkdir()
+        subdir = data_dir / "seed-12345"
+        subdir.mkdir()
+        (subdir / "data").touch()
+
+        pool = self._make_pool(str(data_dir))
+        pool._safe_rmtree(str(subdir))
+
+        assert not subdir.exists(), "Valid subdirectory should be deleted"
+
+    def test_refuses_traversal_path(self, tmp_path):
+        data_dir = tmp_path / "profiles"
+        data_dir.mkdir()
+        victim = tmp_path / "victim"
+        victim.mkdir()
+
+        traversal = str(data_dir / ".." / "victim")
+        pool = self._make_pool(str(data_dir))
+        pool._safe_rmtree(traversal)
+
+        assert victim.exists(), "Traversal path must not be deleted"
@@ -1,6 +1,7 @@
 """Unit tests for GeoIP-based timezone/locale detection."""

 from unittest.mock import patch
+import time

 import pytest

@@ -144,6 +145,20 @@ def test_maybe_resolve_fills_both():
        assert ip == "5.6.7.8"


+def test_maybe_resolve_geoip_timeout_returns_existing_values(monkeypatch):
+    """A stalled proxy lookup should not block launch indefinitely."""
+    mock_geoip2 = type("module", (), {"database": type("db", (), {"Reader": None})})()
+    monkeypatch.setenv("CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS", "0.05")
+    with patch.dict("sys.modules", {"geoip2": mock_geoip2, "geoip2.database": mock_geoip2.database}):
+        with patch("cloakbrowser.geoip._ensure_geoip_db", return_value=object()):
+            start = time.monotonic()
+            tz, loc, ip = maybe_resolve_geoip(True, "http://203.0.113.10:8080", None, "fr-FR")
+            elapsed = time.monotonic() - start
+
+    assert (tz, loc, ip) == (None, "fr-FR", None)
+    assert elapsed < 0.5
+
+
 # ---------------------------------------------------------------------------
 # _is_private_ip
 # ---------------------------------------------------------------------------
@@ -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)
@@ -1296,6 +1371,463 @@ class TestAsyncElementHandle:
        await browser.close()


+# =========================================================================
+# 15. Per-call timeout forwarding (issue #137)
+# =========================================================================
+
+class TestPerCallTimeoutForwarding:
+    """page.click('#x', timeout=5000) must forward 5000 to bounding_box(),
+    not silently use the hardcoded 2000ms in scroll."""
+
+    def test_get_element_box_default_timeout(self):
+        """Default timeout matches Playwright's 30000ms."""
+        from cloakbrowser.human.scroll import _get_element_box
+        from unittest.mock import MagicMock
+
+        page = MagicMock()
+        loc = MagicMock()
+        loc.bounding_box = MagicMock(return_value={"x": 0, "y": 0, "width": 1, "height": 1})
+        page.locator = MagicMock(return_value=MagicMock(first=loc))
+
+        _get_element_box(page, "#x")
+        loc.bounding_box.assert_called_once_with(timeout=30000)
+
+    def test_get_element_box_custom_timeout(self):
+        """Caller can pass a custom timeout that overrides the default."""
+        from cloakbrowser.human.scroll import _get_element_box
+        from unittest.mock import MagicMock
+
+        page = MagicMock()
+        loc = MagicMock()
+        loc.bounding_box = MagicMock(return_value={"x": 0, "y": 0, "width": 1, "height": 1})
+        page.locator = MagicMock(return_value=MagicMock(first=loc))
+
+        _get_element_box(page, "#x", timeout=5000)
+        loc.bounding_box.assert_called_once_with(timeout=5000)
+
+    def test_scroll_to_element_forwards_timeout(self):
+        """scroll_to_element passes timeout through to bounding_box()."""
+        from cloakbrowser.human.scroll import scroll_to_element
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock
+
+        cfg = resolve_config("default", None)
+        page = MagicMock()
+        page.viewport_size = {"width": 1280, "height": 720}
+        loc = MagicMock()
+        # Already in viewport so we don't actually scroll — just verify
+        # the timeout was forwarded on the first bounding_box() call.
+        loc.bounding_box = MagicMock(return_value={"x": 100, "y": 200, "width": 50, "height": 30})
+        page.locator = MagicMock(return_value=MagicMock(first=loc))
+
+        raw = MagicMock()
+        scroll_to_element(page, raw, "#x", 0, 0, cfg, timeout=7500)
+        loc.bounding_box.assert_called_with(timeout=7500)
+
+    def test_page_click_forwards_timeout_kwarg(self):
+        """page.click(selector, timeout=...) reaches scroll_to_element.
+
+        Patches scroll_to_element module-side via monkey-patching the
+        cloakbrowser.human module attribute used by patch_page.
+        """
+        import cloakbrowser.human as h
+        from cloakbrowser.human import _CursorState
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock, patch
+
+        cfg = resolve_config("default", {"idle_between_actions": False})
+        cursor = _CursorState()
+        cursor.initialized = True
+        cursor.x = 100
+        cursor.y = 100
+
+        # Build a minimal page mock
+        page = MagicMock()
+        page.click = MagicMock()
+        page.dblclick = MagicMock()
+        page.hover = MagicMock()
+        page.type = MagicMock()
+        page.fill = MagicMock()
+        page.goto = MagicMock()
+        page.is_checked = MagicMock(return_value=False)
+        page.viewport_size = {"width": 1280, "height": 720}
+        page.evaluate = MagicMock(return_value={"hit": True})
+        page.context.new_cdp_session = MagicMock(side_effect=Exception("no cdp"))
+        page.mouse = MagicMock()
+        page.keyboard = MagicMock()
+        page.query_selector = MagicMock(return_value=None)
+        page.query_selector_all = MagicMock(return_value=[])
+        page.wait_for_selector = MagicMock(return_value=None)
+        page.main_frame = MagicMock()
+        page.main_frame.child_frames = []
+
+        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, False)
+
+        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 4900 <= captured.get("timeout", 0) <= 5000, f"expected ~5000, got {captured}"
+
+
+# =========================================================================
+# 16. Per-call human_config override (typing speed customization)
+# =========================================================================
+
+class TestPerCallHumanConfigOverride:
+    """page.type('#email', text, human_config={'typing_delay': 30}) lets users
+    override typing speed (and any other HumanConfig field) on a per-call
+    basis without re-patching the page."""
+
+    def test_merge_config_creates_new_instance(self):
+        from cloakbrowser.human.config import resolve_config, merge_config
+
+        base = resolve_config("default", None)
+        merged = merge_config(base, {"typing_delay": 30})
+
+        assert merged.typing_delay == 30
+        assert base.typing_delay != 30  # not mutated
+        # Non-overridden fields are preserved
+        assert merged.mouse_min_steps == base.mouse_min_steps
+
+    def test_merge_config_none_returns_base(self):
+        from cloakbrowser.human.config import resolve_config, merge_config
+
+        base = resolve_config("default", None)
+        merged = merge_config(base, None)
+        assert merged is base
+
+    def test_merge_config_ignores_unknown_keys(self):
+        from cloakbrowser.human.config import resolve_config, merge_config
+
+        base = resolve_config("default", None)
+        # ``not_a_real_field`` is silently dropped — callers shouldn't crash
+        # if they pass typos or future field names.
+        merged = merge_config(base, {"typing_delay": 30, "not_a_real_field": 99})
+        assert merged.typing_delay == 30
+
+    def test_page_type_uses_per_call_typing_delay(self):
+        """page.type(..., human_config={'typing_delay': 30}) reaches human_type
+        with cfg.typing_delay == 30 even when patch was done with default 70."""
+        import cloakbrowser.human as h
+        from cloakbrowser.human import _CursorState
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock, patch
+
+        cfg = resolve_config("default", {
+            "idle_between_actions": False,
+            "field_switch_delay": (0, 1),
+        })
+        assert cfg.typing_delay == 70  # baseline
+
+        cursor = _CursorState()
+        cursor.initialized = True
+        cursor.x = 100
+        cursor.y = 100
+
+        page = MagicMock()
+        page.click = MagicMock()
+        page.dblclick = MagicMock()
+        page.hover = MagicMock()
+        page.type = MagicMock()
+        page.fill = MagicMock()
+        page.goto = MagicMock()
+        page.is_checked = MagicMock(return_value=False)
+        page.viewport_size = {"width": 1280, "height": 720}
+        page.evaluate = MagicMock(return_value={"hit": True})
+        page.context.new_cdp_session = MagicMock(side_effect=Exception("no cdp"))
+        page.mouse = MagicMock()
+        page.keyboard = MagicMock()
+        page.query_selector = MagicMock(return_value=None)
+        page.query_selector_all = MagicMock(return_value=[])
+        page.wait_for_selector = MagicMock(return_value=None)
+        page.main_frame = MagicMock()
+        page.main_frame.child_frames = []
+
+        captured = {}
+        def fake_human_type(page_arg, raw, text, cfg_arg, cdp_session=None):
+            captured["typing_delay"] = cfg_arg.typing_delay
+            captured["mistype_chance"] = cfg_arg.mistype_chance
+
+        def fake_scroll(*args, **kwargs):
+            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, "ensure_actionable"), \
+             patch.object(h, "check_pointer_events"):
+            h.patch_page(page, cfg, cursor)
+            page.type(
+                "#email", "hi",
+                human_config={"typing_delay": 30, "mistype_chance": 0},
+            )
+
+        assert captured["typing_delay"] == 30
+        assert captured["mistype_chance"] == 0
+        assert cfg.typing_delay == 70
+
+    def test_page_fill_uses_per_call_typing_delay(self):
+        """Same as type, but for fill (which also clears the field first)."""
+        import cloakbrowser.human as h
+        from cloakbrowser.human import _CursorState
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock, patch
+
+        cfg = resolve_config("default", {
+            "idle_between_actions": False,
+            "field_switch_delay": (0, 1),
+        })
+        cursor = _CursorState()
+        cursor.initialized = True
+        cursor.x = 100
+        cursor.y = 100
+
+        page = MagicMock()
+        page.viewport_size = {"width": 1280, "height": 720}
+        page.is_checked = 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()
+        page.query_selector = MagicMock(return_value=None)
+        page.query_selector_all = MagicMock(return_value=[])
+        page.wait_for_selector = MagicMock(return_value=None)
+        page.main_frame = MagicMock()
+        page.main_frame.child_frames = []
+
+        captured = {}
+        def fake_human_type(page_arg, raw, text, cfg_arg, cdp_session=None):
+            captured["typing_delay"] = cfg_arg.typing_delay
+
+        def fake_scroll(*args, **kwargs):
+            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, "ensure_actionable"), \
+             patch.object(h, "check_pointer_events"):
+            h.patch_page(page, cfg, cursor)
+            page.fill("#password", "secret", human_config={"typing_delay": 150})
+
+        assert captured["typing_delay"] == 150
+
+    def test_element_handle_type_uses_per_call_human_config(self):
+        """el.type(text, human_config={...}) merges per-call overrides on the
+        ElementHandle path (which doesn't go through page.type)."""
+        from cloakbrowser.human import _patch_single_element_handle_sync, _CursorState
+        from cloakbrowser.human.config import resolve_config
+        import cloakbrowser.human as h
+        from unittest.mock import MagicMock, patch
+
+        cfg = resolve_config("default", {
+            "idle_between_actions": False,
+            "field_switch_delay": (0, 1),
+        })
+        cursor = _CursorState()
+        cursor.initialized = True
+        cursor.x = 50
+        cursor.y = 50
+
+        page = MagicMock()
+        page.viewport_size = {"width": 1280, "height": 720}
+        page._original = MagicMock()
+
+        el = MagicMock()
+        el._human_patched = False
+        el.bounding_box = MagicMock(
+            return_value={"x": 200, "y": 200, "width": 100, "height": 30}
+        )
+        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=[])
+        el.wait_for_selector = MagicMock(return_value=None)
+        el.scroll_into_view_if_needed = MagicMock()
+
+        raw_mouse = MagicMock()
+        raw_keyboard = MagicMock()
+
+        captured = {}
+        def fake_human_type(page_arg, raw, text, cfg_arg, cdp_session=None):
+            captured["typing_delay"] = cfg_arg.typing_delay
+
+        with patch.object(h, "human_type", side_effect=fake_human_type):
+            _patch_single_element_handle_sync(
+                el, page, cfg, cursor, raw_mouse, raw_keyboard,
+                page._original, None, None,
+            )
+            el.type("abc", human_config={"typing_delay": 25})
+
+        assert captured["typing_delay"] == 25
+
+
+# =========================================================================
+# 17. scroll_into_view_if_needed humanization
+# =========================================================================
+
+class TestScrollIntoViewIfNeeded:
+    """scroll_into_view_if_needed should run through the same
+    accelerate → cruise → decelerate → overshoot wheel sequence as page.click—
+    not Playwright's instant-snap default."""
+
+    def test_human_scroll_into_view_skips_when_in_viewport(self):
+        """Already-visible elements: no wheel events, just return."""
+        from cloakbrowser.human.scroll import human_scroll_into_view
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock
+
+        cfg = resolve_config("default", None)
+        page = MagicMock()
+        page.viewport_size = {"width": 1280, "height": 720}
+        raw = MagicMock()
+        # 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, 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"
+
+    def test_human_scroll_into_view_scrolls_when_below_fold(self):
+        """Below-fold elements: wheel events fire, eventually box becomes visible."""
+        from cloakbrowser.human.scroll import human_scroll_into_view
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock
+
+        cfg = resolve_config("default", {
+            "scroll_overshoot_chance": 0,        # deterministic
+            "scroll_pre_move_delay": (0, 1),
+            "scroll_pause_fast": (0, 1),
+            "scroll_pause_slow": (0, 1),
+            "scroll_settle_delay": (0, 1),
+        })
+        page = MagicMock()
+        page.viewport_size = {"width": 1280, "height": 720}
+        raw = MagicMock()
+
+        # First box is far below the fold; subsequent boxes "come into view"
+        # so the loop terminates after a few wheel bursts.
+        boxes = [
+            {"x": 200, "y": 2000, "width": 50, "height": 30},
+            {"x": 200, "y": 1500, "width": 50, "height": 30},
+            {"x": 200, "y": 1000, "width": 50, "height": 30},
+            {"x": 200, "y": 400, "width": 50, "height": 30},   # in viewport
+            {"x": 200, "y": 400, "width": 50, "height": 30},
+            {"x": 200, "y": 400, "width": 50, "height": 30},
+        ]
+        idx = {"i": 0}
+        def get_box():
+            i = min(idx["i"], len(boxes) - 1)
+            idx["i"] += 1
+            return boxes[i]
+
+        human_scroll_into_view(page, raw, get_box, 0, 0, cfg)
+        assert raw.wheel.called, "Below-fold scroll should produce wheel events"
+
+    def test_element_handle_scroll_into_view_if_needed_humanized(self):
+        """el.scroll_into_view_if_needed() routes through human_scroll_into_view."""
+        from cloakbrowser.human import _patch_single_element_handle_sync, _CursorState
+        from cloakbrowser.human.config import resolve_config
+        import cloakbrowser.human as h
+        from unittest.mock import MagicMock, patch
+
+        cfg = resolve_config("default", None)
+        cursor = _CursorState()
+        cursor.initialized = True
+        cursor.x = 50
+        cursor.y = 50
+
+        page = MagicMock()
+        page.viewport_size = {"width": 1280, "height": 720}
+        page._original = MagicMock()
+
+        el = MagicMock()
+        el._human_patched = False
+        el.bounding_box = MagicMock(
+            return_value={"x": 200, "y": 200, "width": 50, "height": 30}
+        )
+        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=[])
+        el.wait_for_selector = MagicMock(return_value=None)
+        # Make sure the original method exists so the patch is wired up
+        el.scroll_into_view_if_needed = MagicMock()
+
+        called = {"count": 0}
+        def fake(*args, **kwargs):
+            called["count"] += 1
+            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,
+            )
+            el.scroll_into_view_if_needed()
+
+        assert called["count"] >= 1, "humanized scroll helper was never called"
+
+    def test_locator_scroll_into_view_if_needed_humanized(self):
+        """Locator.scroll_into_view_if_needed() also goes through humanized scroll."""
+        import cloakbrowser.human as h
+        from cloakbrowser.human import _CursorState
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock, patch
+
+        # Patch Locator class fresh
+        _ensure_locator_patched()
+
+        from playwright.sync_api._generated import Locator
+
+        cfg = resolve_config("default", None)
+        cursor = _CursorState()
+        cursor.x = 50
+        cursor.y = 50
+        cursor.initialized = True
+
+        page = MagicMock()
+        page._original = MagicMock()
+        page._human_cfg = cfg
+        page._human_cursor = cursor
+        page._human_raw_mouse = MagicMock()
+        page.viewport_size = {"width": 1280, "height": 720}
+
+        # Build a Locator-like object satisfying the patched method
+        loc = MagicMock(spec=Locator)
+        loc.page = page
+        impl_obj = MagicMock()
+        impl_obj._selector = "#x"
+        loc._impl_obj = impl_obj
+        loc.bounding_box = MagicMock(
+            return_value={"x": 100, "y": 100, "width": 50, "height": 30}
+        )
+
+        called = {"count": 0, "cfg": None}
+        def fake(*args, **kwargs):
+            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, False)
+
+        with patch.object(h, "human_scroll_into_view", side_effect=fake):
+            Locator.scroll_into_view_if_needed(
+                loc, human_config={"scroll_overshoot_chance": 0.5},
+            )
+
+        assert called["count"] == 1
+        # Per-call override merged into the cfg passed downstream
+        assert called["cfg"].scroll_overshoot_chance == 0.5
+        # Cursor was updated from the helper's return value
+        assert cursor.x == 200 and cursor.y == 200
+
+
 # =========================================================================
 # Direct runner (backwards compat)
 # =========================================================================
@@ -1,6 +1,6 @@
 """Unit tests for launch_context() — context kwargs, viewport defaults, close cleanup."""

-from unittest.mock import MagicMock, call, patch
+from unittest.mock import AsyncMock, MagicMock, call, patch

 import pytest

@@ -207,3 +207,125 @@ def test_kwargs_passthrough(mock_launch, _mock_bin):
    # Verify kwarg did NOT leak to launch()
    launch_kwargs = mock_launch.call_args[1]
    assert "record_video_dir" not in launch_kwargs
+
+
+# ---------------------------------------------------------------------------
+# Async: launch_context_async()
+# ---------------------------------------------------------------------------
+
+
+def _make_mock_async_browser():
+    """Create a mock async browser whose new_context() returns a mock context."""
+    browser = AsyncMock()
+    context = AsyncMock()
+    browser.new_context.return_value = context
+    return browser, context
+
+
+@pytest.mark.asyncio
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch_async")
+async def test_async_storage_state_forwarded(mock_launch_async, _mock_bin):
+    """storage_state kwarg forwarded to browser.new_context() in async path.
+
+    This is the motivating use case from issue #141.
+    """
+    browser, context = _make_mock_async_browser()
+    mock_launch_async.return_value = browser
+
+    from cloakbrowser.browser import launch_context_async
+    await launch_context_async(storage_state="state.json")
+
+    ctx_kwargs = browser.new_context.call_args
+    assert ctx_kwargs[1]["storage_state"] == "state.json"
+
+
+@pytest.mark.asyncio
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch_async")
+async def test_async_default_viewport(mock_launch_async, _mock_bin):
+    """DEFAULT_VIEWPORT applied when no viewport given (async)."""
+    browser, context = _make_mock_async_browser()
+    mock_launch_async.return_value = browser
+
+    from cloakbrowser.browser import launch_context_async
+    await launch_context_async()
+
+    ctx_kwargs = browser.new_context.call_args
+    assert ctx_kwargs[1]["viewport"] == DEFAULT_VIEWPORT
+
+
+@pytest.mark.asyncio
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch_async")
+async def test_async_locale_flows_to_binary_not_cdp(mock_launch_async, _mock_bin):
+    """locale flows to launch_async() for --lang flag, NOT to new_context() CDP."""
+    browser, context = _make_mock_async_browser()
+    mock_launch_async.return_value = browser
+
+    from cloakbrowser.browser import launch_context_async
+    await launch_context_async(locale="de-DE", timezone="Europe/Berlin")
+
+    # Binary flags
+    assert mock_launch_async.call_args[1]["locale"] == "de-DE"
+    assert mock_launch_async.call_args[1]["timezone"] == "Europe/Berlin"
+    # Not in context — would trigger detectable CDP emulation
+    ctx_kwargs = browser.new_context.call_args
+    assert "locale" not in ctx_kwargs[1]
+    assert "timezone_id" not in ctx_kwargs[1]
+
+
+@pytest.mark.asyncio
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch_async")
+async def test_async_close_closes_browser(mock_launch_async, _mock_bin):
+    """await ctx.close() also closes the underlying browser."""
+    browser, context = _make_mock_async_browser()
+    original_ctx_close = context.close
+    mock_launch_async.return_value = browser
+
+    from cloakbrowser.browser import launch_context_async
+    ctx = await launch_context_async()
+
+    await ctx.close()
+    original_ctx_close.assert_called_once()
+    browser.close.assert_called_once()
+
+
+@pytest.mark.asyncio
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch_async")
+async def test_async_error_closes_browser(mock_launch_async, _mock_bin):
+    """If new_context() raises in async path, browser is still closed."""
+    browser = AsyncMock()
+    browser.new_context.side_effect = RuntimeError("context creation failed")
+    mock_launch_async.return_value = browser
+
+    from cloakbrowser.browser import launch_context_async
+    with pytest.raises(RuntimeError, match="context creation failed"):
+        await launch_context_async()
+
+    browser.close.assert_called_once()
+
+
+@pytest.mark.asyncio
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch_async")
+async def test_async_cancellation_closes_browser(mock_launch_async, _mock_bin):
+    """asyncio.CancelledError during new_context() still closes browser.
+
+    CancelledError derives from BaseException (not Exception) in Python 3.8+,
+    so the cleanup must catch BaseException to prevent browser process leaks
+    when the awaiting task is cancelled.
+    """
+    import asyncio
+
+    browser = AsyncMock()
+    browser.new_context.side_effect = asyncio.CancelledError()
+    mock_launch_async.return_value = browser
+
+    from cloakbrowser.browser import launch_context_async
+    with pytest.raises(asyncio.CancelledError):
+        await launch_context_async()
+
+    browser.close.assert_called_once()
@@ -266,3 +266,111 @@ class TestResolveProxyConfig:
        assert kwargs == {}
        assert "--proxy-server=socks5://host:1080" in args
        assert "--proxy-bypass-list=.example.com" in args
+
+    def test_socks5_string_encodes_equals_in_password(self):
+        # Chromium's --proxy-server parser truncates passwords at '=' (#157).
+        # Wrapper must auto URL-encode before passing to Chrome.
+        _, args = _resolve_proxy_config("socks5://user:pass=123@host:1080")
+        assert args == ["--proxy-server=socks5://user:pass%3D123@host:1080"]
+
+    def test_socks5_string_encodes_at_in_password(self):
+        _, args = _resolve_proxy_config("socks5://user:p@ss@host:1080")
+        # Note: parsing "user:p@ss@host" — urlparse takes everything up to LAST @
+        # as userinfo, so password = "p@ss".
+        assert args == ["--proxy-server=socks5://user:p%40ss@host:1080"]
+
+    def test_socks5_string_encoding_idempotent(self):
+        # Already-encoded input should remain encoded (not double-encoded).
+        _, args = _resolve_proxy_config("socks5://user:pass%3D123@host:1080")
+        assert args == ["--proxy-server=socks5://user:pass%3D123@host:1080"]
+
+    def test_socks5_string_logs_info_when_reencoding(self, caplog):
+        # When wrapper actually rewrites the URL (e.g. unencoded '=' in pwd),
+        # surface an INFO log so users debugging SOCKS5 connectivity (#157)
+        # can see what the wrapper did instead of being silently surprised.
+        import logging
+        with caplog.at_level(logging.INFO, logger="cloakbrowser"):
+            _resolve_proxy_config("socks5://user:pass=123@host:1080")
+        assert any("Auto URL-encoded SOCKS5" in r.message for r in caplog.records)
+        # Credentials must not leak into the log.
+        for r in caplog.records:
+            assert "pass=123" not in r.message
+            assert "pass%3D123" not in r.message
+
+    def test_socks5_string_silent_when_already_encoded(self, caplog):
+        # Idempotent path: pre-encoded URL produces no log noise.
+        import logging
+        with caplog.at_level(logging.INFO, logger="cloakbrowser"):
+            _resolve_proxy_config("socks5://user:pass%3D123@host:1080")
+        assert not any("Auto URL-encoded SOCKS5" in r.message for r in caplog.records)
+
+    def test_socks5_string_silent_when_no_credentials(self, caplog):
+        # No userinfo at all → no encoding work → no log.
+        import logging
+        with caplog.at_level(logging.INFO, logger="cloakbrowser"):
+            _resolve_proxy_config("socks5://host:1080")
+        assert not any("Auto URL-encoded SOCKS5" in r.message for r in caplog.records)
+
+    def test_socks5_string_silent_when_only_cosmetic_change(self, caplog):
+        # urlparse lowercases scheme and hostname, but credentials are
+        # untouched. The log must NOT fire for these cosmetic-only rewrites
+        # (regression for Copilot's review on PR #209).
+        import logging
+        with caplog.at_level(logging.INFO, logger="cloakbrowser"):
+            _resolve_proxy_config("socks5://USER:pass@HOST.com:1080")
+        assert not any("Auto URL-encoded SOCKS5" in r.message for r in caplog.records)
+
+    def test_socks5_string_no_creds_unchanged(self):
+        _, args = _resolve_proxy_config("socks5://host:1080")
+        assert args == ["--proxy-server=socks5://host:1080"]
+
+    def test_socks5_string_password_only_still_encoded(self):
+        # Empty username with password: fix must still re-encode the password
+        # (regression test for empty-username bypass).
+        _, args = _resolve_proxy_config("socks5://:pass=123@host:1080")
+        assert args == ["--proxy-server=socks5://:pass%3D123@host:1080"]
+
+    def test_socks5_string_empty_password_preserves_colon(self):
+        # `user:@host` (empty password) must NOT collapse to `user@host` —
+        # semantics differ between the two forms.
+        _, args = _resolve_proxy_config("socks5://user:@host:1080")
+        assert args == ["--proxy-server=socks5://user:@host:1080"]
+
+    def test_socks5_string_literal_percent_in_password(self):
+        # Literal '%' not followed by 2 hex digits must be encoded as '%25'
+        # so Chrome decodes it back to '%'. Must not crash.
+        _, args = _resolve_proxy_config("socks5://user:100%sure@host:1080")
+        assert args == ["--proxy-server=socks5://user:100%25sure@host:1080"]
+
+    def test_socks5_string_malformed_port_passes_through(self, caplog):
+        # Invalid port (non-numeric) raises in urlparse.port. Wrapper should
+        # log a warning and pass original through to Chromium.
+        import logging
+        with caplog.at_level(logging.WARNING, logger="cloakbrowser"):
+            _, args = _resolve_proxy_config("socks5://user:pass@host:abc")
+        assert args == ["--proxy-server=socks5://user:pass@host:abc"]
+        assert any("Malformed SOCKS5" in r.message for r in caplog.records)
+
+    def test_socks5_string_malformed_ipv6_passes_through(self, caplog):
+        # Broken IPv6 bracket — must not crash, and must reach Chromium
+        # verbatim so its own error surfaces instead of a silent rewrite.
+        import logging
+        with caplog.at_level(logging.WARNING, logger="cloakbrowser"):
+            _, args = _resolve_proxy_config("socks5://user:pass@[::1")
+        assert args == ["--proxy-server=socks5://user:pass@[::1"]
+
+    def test_socks5_string_preserves_path_and_query(self):
+        # Nonstandard for SOCKS5, but don't silently drop user-supplied suffixes.
+        # Matches JS behavior.
+        _, args = _resolve_proxy_config("socks5://user:pass@host:1080/p?x=1#f")
+        assert args[0] == "--proxy-server=socks5://user:pass@host:1080/p?x=1#f"
+
+    def test_socks5_string_ipv6_with_special_char_password(self):
+        # IPv6 host + special char in password — both must be handled.
+        _, args = _resolve_proxy_config("socks5://user:pass=eq@[::1]:1080")
+        assert args[0] == "--proxy-server=socks5://user:pass%3Deq@[::1]:1080"
+
+    def test_socks5_string_port_zero_preserved(self):
+        # Port 0 is an unusual but valid URL component; don't silently strip it.
+        _, args = _resolve_proxy_config("socks5://user:pass=1@host:0")
+        assert args[0] == "--proxy-server=socks5://user:pass%3D1@host:0"
@@ -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")
Author	SHA1	Message	Date
CloakHQ	749ed561a6	fix(humanize): strip custom kwargs before forwarding to Playwright select_option originals.select_option(**kwargs) passes human_config/force to Playwright which rejects unknown kwargs with TypeError.	2026-05-15 20:51:30 +02:00
CloakHQ	f4f6a3f8fd	fix(humanize): forward human_config in all chained methods, use evaluate args in handle pointer checks - Add human_config=kwargs.get("human_config") to check/uncheck/select_option/press inner calls (sync+async+JS) - Convert check_pointer_events_handle from f-string interpolation to evaluate args pattern (sync+async+JS)	2026-05-15 19:17:11 +02:00
CloakHQ	39f807f246	feat(humanize): add Playwright-style actionability checks to all interaction methods Humanized locator/page methods now perform pre-action validation matching Playwright's native behavior: attached, visible, enabled, editable, stable, and receives-pointer-events checks with retry loop and backoff. - New error hierarchy: ActionabilityError base with ElementNotAttachedError, ElementNotVisibleError, ElementNotStableError, ElementNotEnabledError, ElementNotEditableError, ElementNotReceivingEventsError - force=True parameter skips all actionability checks (matches Playwright) - Shared deadline across all steps (checks + scroll + stable + pointer) - Post-scroll stability check only runs when scroll actually happened - Chained methods (type/fill/check/uncheck/press) skip inner click checks but still run pointer-events check at actual click coordinates - Frame methods now forward kwargs (force, timeout, human_config) - Locator patches forward force via _forward_kwargs - Python sync + async, JS/TS implementation	2026-05-12 22:58:03 +02:00
@aaronjmarsandGitHub	95a98b6747	fix(security): isolate workflow_dispatch input to avoid shell injection in attest-release (#223 ) Security hardening: route workflow_dispatch input through env var to prevent shell injection in attest-release workflow.	2026-05-12 15:53:31 +02:00
@aaronjmars GitHub Aeon	23f1d4098c	fix(security): bump tar + transitive deps via npm audit fix (#222 ) Detected by Aeon + osv-scanner. Severity: high (runtime tar) / high+moderate (dev deps) Patches 8 of 14 CVEs flagged by osv-scanner — all that can be fixed within current semver ranges via `npm audit fix --package-lock-only`. The remaining 6 are gated on a puppeteer-core/vitest major-version bump (out of scope for this PR). Runtime (shipped to users): - tar 7.5.9 -> 7.5.15 - GHSA-9ppj-qmqm-q256 HIGH: Symlink Path Traversal via Drive-Relative Linkpath - GHSA-qffp-2rhf-9h96 HIGH: Hardlink Path Traversal via Drive-Relative Linkpath - Reachable in js/src/download.ts (extractTar) — the existing filter() rejects absolute paths and "..", but does not inspect linkpath, so a malicious Chromium tarball could write outside the cache dir on Windows. Dev (build-time only): - basic-ftp 5.2.0 -> 5.3.1 (4 HIGH: CRLF injection x2, DoS x2) - ip-address 10.1.0 -> 10.2.0 (1 MOD: XSS in Address6 HTML methods) - postcss 8.5.6 -> 8.5.14 (1 MOD: XSS via unescaped </style>) Lockfile metadata side-effects (npm-regenerated, not editorial): - name@version block synced from package.json (0.3.23 -> 0.3.28) - devDependencies + peerDependencies version ranges synced to current package.json (the lockfile was stale relative to head package.json) Verification: - `npm test` -> 320 passed / 11 skipped / 0 failed (9 test files) - `npm run typecheck` -> clean - osv-scanner before: 14 CVEs; after: 6 (those 6 need a breaking major-version bump to land — happy to follow up if you want it) Co-authored-by: Aeon <aeon@aaronjmars.eth>	2026-05-12 15:47:26 +02:00
Novi Kurnia HutapeaandGitHub	d45d7de9a9	chore(js): sync package-lock metadata (#219 )	2026-05-12 15:39:22 +02:00
CloakHQ	db0b5f1946	release: v0.3.28 — cloakserve path traversal fix, GeoIP timeout guard, humanize iframe scope	2026-05-11 21:43:14 +02:00
CloakHQ	babef04e07	fix(cloakserve): sanitize fingerprint seed to prevent path traversal (#217 ) Validate seed format with strict regex, add path containment check before rmtree, and bind to 127.0.0.1 by default on bare metal.	2026-05-11 21:36:09 +02:00
CloakHQ	f8026a7b39	chore: clean up GeoIP timeout follow-up (#213 ) Remove dead null checks, document CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS env var, credit contributor. Fix review findings: - Use timeout-bounded resolve_proxy_exit_ip in _resolve_webrtc_args - Add missing timeout handler on tunneled HTTPS request in JS - Reject nan/inf in Python timeout parsing (parity with JS) - Recompute deadline after CONNECT succeeds in JS proxy tunnel	2026-05-11 21:15:36 +02:00
manaskarraandGitHub	71f57d00d1	fix: bound GeoIP resolution so launch cannot hang (#213 ) * Fix geoip resolution timeout * fix: keep GeoIP timeout inside resolution path	2026-05-11 20:55:49 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	e9735392e8	chore(deps): bump sigstore/cosign-installer in the actions group (#214 ) Bumps the actions group with 1 update: [sigstore/cosign-installer](https://github.com/sigstore/cosign-installer). Updates `sigstore/cosign-installer` from 4.1.1 to 4.1.2 - [Release notes](https://github.com/sigstore/cosign-installer/releases) - [Commits](https://github.com/sigstore/cosign-installer/compare/cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003...6f9f17788090df1f26f669e9d70d6ae9567deba6) --- updated-dependencies: - dependency-name: sigstore/cosign-installer dependency-version: 4.1.2 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: actions ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-05-11 20:55:41 +02:00
CloakHQ	0d41a4f023	refactor(js): extract HumanActionOptions type, fix frame check/uncheck error handling, align SOCKS5 log level - Extract HumanActionOptions type alias to replace ~40 inline copies - Frame check/uncheck: let isChecked errors propagate instead of silently clicking non-checkbox elements - SOCKS5 credential log: console.debug → console.info (parity with Python logger.info) - Add contributors to README	2026-05-11 00:23:31 +02:00
EternalandCloakHQ	80d9f7c14e	feat(js): add types to humanized method options (#205 ) Replace `any` with proper TypeScript types on all humanized method options (Playwright, Puppeteer, ElementHandle, Frame). Support flat per-call config overrides alongside existing `human_config` style. Internalize `humanIdle` duration computation with backward-compatible overloads. Co-authored-by: Eternal <chasezou09@gmail.com>	2026-05-10 23:50:01 +02:00
manaskarra GitHub manaskarra	114b3c826b	fix(js): preserve iframe scope in humanized frame actions (#201 ) fix(js): preserve iframe scope in humanized frame actions Frame actions (click, type, fill, etc.) now resolve selectors through frame.locator() instead of delegating to page.* methods, fixing iframe-scoped interactions. Closes #184 Co-authored-by: manaskarra <manas.karra@gmail.com>	2026-05-10 18:13:29 +02:00
YouhaiandGitHub	c07c2b6b4a	fix(proxy): log when SOCKS5 credential auto-encoding rewrites URL (#157 ) (#209 ) * fix(proxy): log when SOCKS5 credential auto-encoding rewrites URL (#157) Auto URL-encoding of SOCKS5 credentials (added in v0.3.26 to fix Chromium's '=' truncation bug) currently happens silently. Users debugging connectivity have no way to know the wrapper rewrote their proxy URL — the original #157 thread took 8 round-trips to surface this exact ambiguity. Emit a log when re-encoding actually changes the URL: INFO on Python's 'cloakbrowser' logger, console.debug in JavaScript. Stays silent on already-encoded inputs and credential-less URLs to avoid false-positive noise. Credentials are not included in the log message. Tests: 3 new cases per language (Python caplog, JS vi.spyOn console.debug) covering trigger / silent-when-encoded / silent-when-no-creds. * fix(proxy): gate log on credential change, not full URL diff Per Copilot review on #209: urlparse cosmetically lowercases scheme and hostname, so comparing the full reconstructed URL to the input would emit "Auto URL-encoded SOCKS5..." even for inputs like `socks5://USER:pass@HOST.com:1080` where no credential encoding happened. Compare raw vs encoded user/password substrings instead. Mirror the same condition in JS for parity (JS's manual parser preserves case today, but the credential-level compare is more robust against future changes). Adds one regression test per language.	2026-05-10 18:09:46 +02:00
CloakHQ	13b1b98b68	fix(js): bump playwright-core minimum to >=1.53.0 (#200 ) playwright-core <=1.52.0 injects __pwInitScripts into window, which deviceandbrowserinfo.com detects as isPlaywright:true. Fixed in 1.53.0.	2026-05-07 17:31:07 +02:00
CloakHQ	0d6ce76b1d	release: v0.3.27 — per-call human_config, humanize timeout fix, scrollIntoViewIfNeeded	2026-05-06 18:32:41 +02:00
CloakHQ	f01902025a	fix: align humanize timeout default with Playwright's 30s auto-retry (#172 ) The humanize layer hardcoded timeout=2000ms for element lookups, causing locator.click() and page.click() to fail instantly instead of retrying for 30s like standard Playwright. Aligned all defaults to 30000ms across Python sync/async, JS Playwright, and JS Puppeteer paths. Bumped the outer retry sleep from 200ms to 500ms for DOM mutation settle time.	2026-05-01 20:48:06 +02:00
CloakHQ	2df8c7e2d1	fix(js): correct issue references #137 → #172 in humanize comments	2026-04-28 20:37:09 +02:00
lilosandGitHub	661b873dad	feat: per-call human_config, timeout forwarding, humanized scrollIntoViewIfNeeded (#183 )	2026-04-28 20:34:17 +02:00
CloakHQ	ee346a6a57	release: v0.3.26 — Windows x64 upgraded to Chromium 146, SOCKS5 credential encoding, Lambda integration	2026-04-28 05:38:06 +02:00
CloakHQ	3e699f554c	fix(docker): add emoji and extended font packages to resolve Kasada/Akamai canvas blocks (#179 ) Dockerfile: add fonts-noto-color-emoji, fonts-freefont-ttf, fonts-unifont, fonts-ipafont-gothic, fonts-wqy-zenhei, fonts-tlwg-loma-otf. README: separate anti-bot font fix (apt packages) from CreepJS font enumeration (Windows fonts + --fingerprint-fonts-dir).	2026-04-28 04:11:19 +02:00
Alex StepanskyandGitHub	9eb90da012	feat(lambda): cold-start hardening + handler-side retry orchestration (#180 ) * feat(lambda): cold-start hardening + handler-side retry orchestration Two related improvements based on benchmarking the integration at scale (3454-site sample, multiple iterations). Cold-start hardening (lambda-entrypoint.sh + lambda_handler.py): - Clean stale Xvfb lock file before starting the X server. We observed that under cold-start storms, a previous Xvfb sometimes died and left /tmp/.X99-lock + /tmp/.X11-unix/X99 behind, so the next start failed with "Server is already active for display 99". Removing both files makes Xvfb start cleanly every time. - Replace `sleep 0.5` with a poll-for-X11-socket loop (up to 10s) plus a 200ms post-socket buffer for listen()/accept() to settle. The fixed sleep lost the race during concurrent cold inits, surfacing as "Looks like you launched a headed browser without having a XServer running" failures (~10% rate at 100-concurrent cold-start storm). - Add _launch_with_retry helper in the handler: 3 attempts with linear backoff (0.3s, 0.6s) on launch_context_async failures. Belt-and- suspenders for whatever the entrypoint fix doesn't catch — a retry on a now-warm container almost always succeeds. Handler-side retry orchestration (lambda_handler.py): - Add _classify_error() — maps Playwright errors to retry-strategy overrides: ERR_CERT_* -> --ignore-certificate-errors + 60s goto Timeout exceeded -> 90s goto + 25s smart_wait cap ERR_CONNECTION_TIMED_OUT -> same as Timeout Returns None for unrecoverable site issues (DNS, SSL, refused, HTTP 4xx/5xx) — those bail immediately without burning a retry slot. - Add _attempt_scrape() — extracted scrape body so the retry loop can call it with overridden event dicts. Each attempt relaunches the browser; uniform behavior across strategies. - Rewrite _run() as a retry loop: first attempt uses event verbatim; on a classifiable failure, merge the strategy's overrides into the event and retry. Bounded by the new `retries` event field (default 1; set to 0 to disable retry). - Add _raise_with_history() — surfaces a final failure with a retry_history block embedded in the error message so callers see exactly what was tried before bailing. Successful invocations return the standard response shape unchanged — no surprise fields. INSTRUCTIONS.md updates: - Bump function timeout recommendation from 60-120s to 120-180s. Under retry, a Timeout-class first failure (30s) plus a longer-budget retry (90s) plus cleanup can total ~120-130s; 180s leaves headroom. - Document the new `retries` event field in the schema. - Add a "Retry orchestration" subsection covering both layers (launch retries and strategy retries) with the full strategy table. Bench results on the 3454-site sample (seed=1): v1 baseline (no fixes, c=100): 13.5% failure rate, $1.07 v2 (entrypoint Xvfb poll only, c=100): 9.9% failure rate, $1.11 v3 (cold-start fix + bench-side retry): 3.3% failure rate, $1.32 This change (handler retry, c=250): 2.1% failure rate, $1.13 The remaining 2.1% are all genuinely unrecoverable: DNS doesn't exist, broken SSL, connection refused, 4xx/5xx responses, payload >6MB Lambda limit. No retry logic can fix those. * fix(lambda): merge extra_args on strategy retry instead of clobbering A flat dict spread replaced caller-supplied extra_args (e.g. --proxy-server=...) with the strategy's extra_args on a cert retry. Append both lists so caller flags survive the merge.	2026-04-28 03:33:04 +02:00
CloakHQ	6b8d8b6378	docs: add Font Setup on Linux section to README (#179 )	2026-04-28 00:23:08 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	252e79b17d	chore(deps): bump the actions group across 1 directory with 3 updates (#178 ) Bumps the actions group with 3 updates in the / directory: [actions/setup-node](https://github.com/actions/setup-node), [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish) and [docker/build-push-action](https://github.com/docker/build-push-action). Updates `actions/setup-node` from 6.3.0 to 6.4.0 - [Release notes](https://github.com/actions/setup-node/releases) - [Commits](https://github.com/actions/setup-node/compare/53b83947a5a98c8d113130e565377fae1a50d02f...48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e) Updates `pypa/gh-action-pypi-publish` from 1.13.0 to 1.14.0 - [Release notes](https://github.com/pypa/gh-action-pypi-publish/releases) - [Commits](https://github.com/pypa/gh-action-pypi-publish/compare/ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e...cef221092ed1bacb1cc03d23a2d87d1d172e277b) Updates `docker/build-push-action` from 7.0.0 to 7.1.0 - [Release notes](https://github.com/docker/build-push-action/releases) - [Commits](https://github.com/docker/build-push-action/compare/d08e5c354a6adb9ed34480a06d141179aa583294...bcafcacb16a39f128d818304e6c9c0c18556b85f) --- updated-dependencies: - dependency-name: actions/setup-node dependency-version: 6.4.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions - dependency-name: pypa/gh-action-pypi-publish dependency-version: 1.14.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions - dependency-name: docker/build-push-action dependency-version: 7.1.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-04-27 17:32:05 +02:00
CloakHQ	0ccdc71e47	docs: add @AlexTech314 to contributors, add Deployment Integrations section (#177 )	2026-04-27 17:23:24 +02:00
Alex StepanskyandGitHub	74b1ff64db	feat(lambda): add AWS Lambda integration in examples/integrations/aws_lambda/ (#177 ) feat(lambda): add AWS Lambda one-shot scrape integration Self-contained example in examples/integrations/aws_lambda/ — Dockerfile, entrypoint, handler, and docs for running CloakBrowser stealth scrapes in AWS Lambda (container image). Includes smart_wait DOM-stability polling, Xvfb headed mode, and Lambda-specific Chromium flags. Contributed by @AlexTech314.	2026-04-27 17:20:02 +02:00
CloakHQ	a9a0ba13ba	fix(proxy): auto URL-encode SOCKS5 credentials in string URLs (#157 ) Chromium's --proxy-server parser truncates passwords at '=' and other special chars, causing SOCKS5 auth to silently fail and fall back to direct connection. The dict path already encoded creds; now the string path does too. Idempotent: pre-encoded input stays encoded.	2026-04-25 23:01:16 +02:00
CloakHQ	b04ad6ec2a	docs: credit @eofreternal for humanConfig type fix (#151 )	2026-04-16 23:12:57 +02:00
CloakHQ	4459f66593	release: v0.3.25 — Chromium 146.0.7680.177.3, launch_context_async, contextOptions	2026-04-16 22:24:36 +02:00
CloakHQ	ce8b92ba4f	feat: add launch_context_async() + JS contextOptions escape hatch (#141 ) Python: add async counterpart to launch_context(). Forwards all kwargs to browser.new_context() — enables storage_state, permissions, extra_http_headers, etc. without needing a persistent profile folder. JS: launchContext() and launchPersistentContext() silently dropped unknown options. New contextOptions field in LaunchContextOptions is spread into newContext() to forward arbitrary Playwright context options (e.g. storageState, permissions, geolocation).	2026-04-16 21:30:40 +02:00
CloakHQ	4e1027847e	fix: bump CHROMIUM_VERSION display constant to .2 (#157 )	2026-04-15 18:20:01 +02:00
EternalandGitHub	f164c1c874	fix(types): type humanConfig properly (#151 )	2026-04-12 22:58:48 +02:00
lilosandGitHub	f5e242a160	Update CHANGELOG for version 0.3.24 (#139 ) Wrong username :(	2026-04-11 01:03:29 +02:00
CloakHQ	935beef980	docs: add recommended anti-bot config and SOCKS5 tips to troubleshooting Based on recurring GitHub issue patterns (#117, #78, #130, #131).	2026-04-10 23:47:42 +02:00
CloakHQ	c6d3469e4c	release: v0.3.24 — SOCKS5 proxy support, arm64 146 upgrade, ElementHandle humanize	2026-04-10 22:42:29 +02:00