release: v0.3.32 — Windows extraction security fix, Widevine CDM seeding, cloakserve fixes

fix(download): pass extract paths to PowerShell via env vars
Windows zip extraction interpolated archive/dest paths directly into the PowerShell -Command string. A single quote in the path (e.g. a Windows account like C:\Users\O'Brien) closed the string literal early, breaking extraction and creating a code-injection shape. execFileSync guards the OS-shell boundary but not the PowerShell interpreter inside. Pass both paths via env vars ($env:CB_ARCHIVE / $env:CB_DEST) so PowerShell reads them as data, never as code. No escaping needed. Python wrapper unaffected (zipfile module + argv).
2026-06-23 11:41:46 +02:00 · 2026-06-20 03:17:07 +02:00 · 2026-06-20 02:19:48 +02:00 · 2026-06-15 17:58:50 +02:00 · 2026-06-09 17:38:09 +02:00 · 2026-06-09 17:22:33 +02:00
38 changed files with 2467 additions and 834 deletions
@@ -8,3 +8,21 @@ updates:
      actions:
        patterns:
          - "*"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "npm"
+    directory: "/js"
+    schedule:
+      interval: "weekly"
+    groups:
+      javascript:
+        patterns:
+          - "*"
@@ -10,7 +10,7 @@ jobs:
  python:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: "3.12"
@@ -22,7 +22,7 @@ jobs:
  javascript:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
        with:
          node-version: 20
@@ -24,7 +24,7 @@ jobs:
  test:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: "3.12"
@@ -42,7 +42,7 @@ jobs:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: "3.12"
@@ -62,7 +62,7 @@ jobs:
    permissions:
      id-token: write  # OIDC trusted publishing — no PYPI_TOKEN needed
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: "3.12"
@@ -80,7 +80,7 @@ jobs:
    permissions:
      id-token: write  # OIDC trusted publishing + provenance — no NPM_TOKEN needed
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
      - 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)
@@ -100,20 +100,20 @@ jobs:
      attestations: write
      packages: write
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
      - name: Extract version
        run: |
          VERSION=$(python -c 'import re; print(re.search(r"__version__\s*=\s*[\"'\'']([^\"'\'']+)", open("cloakbrowser/_version.py").read()).group(1))')
          echo "VERSION=$VERSION" >> $GITHUB_ENV
-      - uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a  # v4.0.0
-      - uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd  # v4.0.0
-      - uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121  # v4.1.0
+      - uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3  # v4.1.0
+      - uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+      - uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
        with:
          username: ${{ secrets.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PAT }}
      - name: Build and push
        id: build
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7.1.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
        with:
          context: .
          platforms: linux/amd64,linux/arm64
@@ -8,6 +8,24 @@ Changes are tagged: **[wrapper]** for Python/JS wrapper, **[binary]** for Chromi

 ## [Unreleased]

+## [0.3.32] — 2026-06-20
+
+- **[wrapper]** **Security**: Windows binary extraction — pass archive/destination paths to PowerShell via env vars instead of interpolating into the `-Command` string, closing a code-injection shape on paths containing single quotes (e.g. `C:\Users\O'Brien`)
+- **[wrapper]** Widevine: auto-seed CDM hint file for persistent contexts on Linux, so DRM playback works without manual pre-seeding
+- **[wrapper]** `cloakserve`: rewrite CDP WebSocket URLs so clients connect through the proxy correctly (thanks [@honor2030](https://github.com/honor2030), #234)
+- **[wrapper]** `cloakserve`: add idle cleanup for seeded profiles (thanks [@Kumario1](https://github.com/Kumario1), #352)
+- **[meta]** Fix `recaptcha_score.py` example — wait for the reCAPTCHA score to render before screenshot (thanks [@igo](https://github.com/igo) for the report, #374)
+- **[meta]** Bump GitHub Actions in the actions group (#358)
+
+## [0.3.31] — 2026-05-26
+
+- **[wrapper]** Route HTTP proxy credentials through `--proxy-server` flag, removing the need for Playwright's proxy auth handler on HTTP proxies
+- **[wrapper]** JS: export `buildContextOptions` helper for custom context creation (thanks [@honor2030](https://github.com/honor2030), #262)
+- **[wrapper]** Humanize: fix iframe coordinate offset in pointer-events check (thanks [@eofreternal](https://github.com/eofreternal), #303)
+- **[wrapper]** Humanize: use shared deadline for timeout budget in frame and ElementHandle methods (#307)
+- **[docker]** Clean up stale Xvfb lock so container survives restarts (thanks [@sparanoid](https://github.com/sparanoid), #284)
+- **[meta]** Add pip and npm ecosystems to Dependabot, bump GitHub Actions (#309)
+
 ## [0.3.30] — 2026-05-21

 - **[binary]** New build 146.0.7680.177.5 for Linux x64 + Windows x64 — 58 source-level fingerprint patches (up from 57)
@@ -59,7 +59,7 @@ from cloakbrowser import launch

 browser = launch()
 page = browser.new_page()
-page.goto("https://protected-site.com")  # no more blocks
+page.goto("https://example.com")
 browser.close()
 ```

@@ -69,12 +69,34 @@ import { launch } from 'cloakbrowser';

 const browser = await launch();
 const page = await browser.newPage();
-await page.goto('https://protected-site.com');
+await page.goto('https://example.com');
 await browser.close();
 ```

 Also works with Puppeteer: `import { launch } from 'cloakbrowser/puppeteer'` ([details](#puppeteer))

+**For sites with anti-bot protection**, add a residential proxy and these flags:
+
+```python
+browser = launch(
+    proxy="http://user:pass@residential-proxy:port",  # residential IP, not datacenter
+    geoip=True,       # match timezone + locale to proxy IP
+    headless=False,    # some sites detect headless even with C++ patches
+    humanize=True,     # human-like mouse, keyboard, scroll
+)
+```
+
+```javascript
+const browser = await launch({
+    proxy: 'http://user:pass@residential-proxy:port',
+    geoip: true,
+    headless: false,
+    humanize: true,
+});
+```
+
+See [Troubleshooting](#troubleshooting) for site-specific issues (FingerprintJS, Kasada, reCAPTCHA).
+
 ## Install

 **Python:**
@@ -128,7 +150,7 @@ Open [http://localhost:8080](http://localhost:8080). Create a profile. Click **L

 ---

-## Latest: v0.3.30 (Chromium 146.0.7680.177.5)
+## Latest: v0.3.32 (Chromium 146.0.7680.177.5)

 - **58 fingerprint patches** — rendering consistency improvements across Linux and Windows, corrected GPU/display/graphics parameters to match stock Chrome 146 profiles
 - **Windows native GPU passthrough** — real hardware values pass through directly instead of being spoofed, matching real browser behavior
@@ -361,6 +383,7 @@ Use this when you need to:
 - **Bypass incognito detection** (some sites flag empty, ephemeral profiles)
 - **Load Chrome extensions** (extensions only work from a real user data dir)
 - **Build natural browsing history** (cached fonts, service workers, IndexedDB accumulate over time, making the profile look more realistic)
+- **Play DRM-protected video** (Widevine) — with a sideloaded CDM, the wrapper enables Widevine on the first launch (see [Widevine / DRM](#widevine--drm))

 ```python
 from cloakbrowser import launch_persistent_context
@@ -397,6 +420,26 @@ ctx = launch_persistent_context("./my-profile", args=["--fingerprint-storage-quo
 | Default (auto, ~500MB) | PASS | -10 (flagged as incognito) |
 | `--fingerprint-storage-quota=5000` | May trigger detection | PASS (appears non-incognito) |

+### Widevine / DRM
+
+The binary is built with Widevine support, but the Widevine CDM is a proprietary Google component we can't redistribute. Sideload it once by copying a `WidevineCdm/` directory from a real Chrome install next to the binary (full steps in [#96](https://github.com/CloakHQ/CloakBrowser/issues/96)):
+
+```bash
+cp -r /opt/google/chrome/WidevineCdm ~/.cloakbrowser/chromium-<version>/WidevineCdm
+```
+
+With the CDM in place, `launch_persistent_context()` enables Widevine **on the first launch** — the wrapper auto-writes the CDM hint file into the profile, so you don't need the manual two-launch workaround. This lets you play DRM-protected video (e.g. Netflix, Spotify Web) and makes a persistent profile present as a regular Chrome install to detection services that probe for DRM/EME support as a real-browser signal.
+
+```python
+from cloakbrowser import launch_persistent_context
+
+# WidevineCdm sideloaded next to the binary -> Widevine works on first launch
+ctx = launch_persistent_context("./my-profile", headless=False)
+```
+
+- **Linux only.** Chromium's hint-file mechanism is Linux/ChromeOS-specific. On Windows the CDM can't initialise (DRM host verification) and macOS uses a different layout, so seeding is a no-op there.
+- **Auto by presence.** No flag needed — a sideloaded CDM is the opt-in. Point at a CDM in a non-default location with `CLOAKBROWSER_WIDEVINE_CDM=/path/to/WidevineCdm`, or disable seeding entirely with `CLOAKBROWSER_WIDEVINE=0`.
+
 ### CLI

 Pre-download the binary or check installation status from the command line:
@@ -580,6 +623,8 @@ Access the original un-patched Playwright page at `page._original` if you need r
 | `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 |
+| `CLOAKBROWSER_WIDEVINE_CDM` | — | Path to a sideloaded `WidevineCdm` directory (overrides auto-detection next to the binary). See [Widevine / DRM](#widevine--drm) |
+| `CLOAKBROWSER_WIDEVINE` | `1` | Set to `0` to disable automatic Widevine hint-file seeding for persistent contexts |

 ## Fingerprint Management

@@ -817,6 +862,26 @@ print(page.title())
 browser.close()
 ```

+If your framework needs a direct WebSocket endpoint, fetch Chrome's discovery document and use the rewritten `webSocketDebuggerUrl`. The URL points back through `cloakserve` so the CDP proxy can keep per-seed routing intact:
+
+```bash
+curl http://localhost:9222/json/version | jq -r .webSocketDebuggerUrl
+# ws://localhost:9222/devtools/browser/<browser-id>
+
+curl 'http://localhost:9222/json/version?fingerprint=11111' | jq -r .webSocketDebuggerUrl
+# ws://localhost:9222/fingerprint/11111/devtools/browser/<browser-id>
+```
+
+When `cloakserve` runs behind a reverse proxy or TLS terminator, forward the public host/protocol headers so generated WebSocket URLs use the address clients can actually reach:
+
+```nginx
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-Host $host;
+proxy_set_header X-Forwarded-Proto $scheme;
+```
+
+With those headers, `/json/version` returns public endpoints such as `wss://cdp.example.com/fingerprint/11111/devtools/browser/<browser-id>` instead of an internal container host.
+
 Pass extra flags to the browser:

 ```bash
@@ -827,6 +892,10 @@ docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
 # Headed mode (renders to Xvfb inside container)
 docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
  cloakserve --headless=false
+
+# Reap disconnected per-seed browser processes after 5 minutes
+docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
+  cloakserve --idle-timeout=300
 ```

 Stop the server:
@@ -878,7 +947,9 @@ b4 = pw.chromium.connect_over_cdp(
 )
 ```

-Supported query params: `fingerprint`, `timezone`, `locale`, `platform`, `platform-version`, `brand`, `brand-version`, `gpu-vendor`, `gpu-renderer`, `hardware-concurrency`, `device-memory`, `screen-width`, `screen-height`, `proxy`, `geoip`. Same seed reuses the same process (first connection's params win). No seed = shared default process (backward compatible). Check active processes at `GET /` (returns JSON with PIDs, ports, and connection counts).
+Supported query params: `fingerprint`, `timezone`, `locale`, `platform`, `platform-version`, `brand`, `brand-version`, `gpu-vendor`, `gpu-renderer`, `hardware-concurrency`, `device-memory`, `screen-width`, `screen-height`, `proxy`, `geoip`. Same seed reuses the same process (first connection's params win). No seed = shared default process (backward compatible).
+
+By default, per-seed processes stay alive until `cloakserve` exits. If clients create many unique seeds, set `--idle-timeout=SECONDS` or `CLOAKSERVE_IDLE_TIMEOUT=SECONDS` to automatically terminate a seed's Chrome process after its last CDP WebSocket disconnects. `0`, `off`, `false`, `none`, or `disabled` disable idle cleanup. When cleanup runs, the seed's temporary profile directory under `--data-dir` is removed too. Check active processes at `GET /` (returns JSON with PIDs, ports, connection counts, idle timeout, and pending cleanup status).

 **Persistent profiles** — mount a volume to keep cookies and sessions across container restarts:

@@ -986,6 +1057,53 @@ If you're still blocked after this, check the font setup below.

 ---

+### Detected by FingerprintJS?
+
+FingerprintJS (`demo.fingerprint.com/playground`) checks multiple signals. Each detection has a specific cause:
+
+| Detection | Cause | Fix |
+|-----------|-------|-----|
+| **`nodriver` / bad bot** | IP reputation or missing flags | Residential proxy + config below |
+| **Browser tampering** | Noise injection detected by ML | `--fingerprint-noise=false` |
+| **Virtual machine** | Screen dimensions don't match viewport | `--fingerprint-screen-width/height` matching viewport |
+| **Incognito** | Storage quota normalized to ~500MB | Expected tradeoff — see below |
+
+Config that passes FPJS (verified on v0.3.30, Linux + Windows):
+
+```python
+browser = launch(
+    headless=False,
+    proxy="http://user:pass@residential-proxy:port",
+    geoip=True,
+    args=[
+        "--fingerprint-noise=false",          # prevents tampering detection
+        "--fingerprint-screen-width=1920",    # match your viewport
+        "--fingerprint-screen-height=1080",
+    ],
+)
+```
+
+```javascript
+const browser = await launch({
+    headless: false,
+    proxy: 'http://user:pass@residential-proxy:port',
+    geoip: true,
+    args: [
+        '--fingerprint-noise=false',
+        '--fingerprint-screen-width=1920',
+        '--fingerprint-screen-height=1080',
+    ],
+});
+```
+
+For persistent contexts (`launch_persistent_context` / `launchPersistentContext`), also add `--fingerprint-storage-quota=500` to the args.
+
+**Storage quota tradeoff:** The binary normalizes storage quota to ~500MB to pass FPJS, but this makes the session look like incognito to other detection services (e.g. BrowserScan's `notPrivate` check, -10 points). Setting `--fingerprint-storage-quota=5000` passes incognito checks but may trigger FPJS. With quota alone you can't satisfy both — choose based on what your target site checks. See the [storage quota tradeoff table](#launch_persistent_context) for details.
+
+**Resolving the tradeoff (Linux):** Sideloading the Widevine CDM lets a persistent context pass FPJS at a higher quota, so you can satisfy both at once. See [Widevine / DRM](#widevine--drm).
+
+---
+
 ### 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.
@@ -1202,7 +1320,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
+- [@eofreternal](https://github.com/eofreternal) — humanConfig type fix, humanized method option types, iframe pointer-events fix
 - [@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, cold-start hardening
@@ -1211,5 +1329,7 @@ Issues and PRs welcome. If something isn't working, [open an issue](https://gith
 - [@aaronjmars](https://github.com/aaronjmars) — security fixes (shell injection, dep bumps)
 - [@Seryiza](https://github.com/Seryiza) — Nix/NixOS flake
 - [@245678000000](https://github.com/245678000000) — package-lock sync
- [@honor2030](https://github.com/honor2030) — cloakserve WebSocket origin guard, composable JS launch helpers
+- [@honor2030](https://github.com/honor2030) — cloakserve WebSocket origin guard, CDP WebSocket URL rewrite, composable JS launch helpers
+- [@sparanoid](https://github.com/sparanoid) — Docker Xvfb lock cleanup
+- [@Kumario1](https://github.com/Kumario1) — cloakserve idle cleanup for seeded profiles
 - [@0xlally](https://github.com/0xlally) — security reports (cloakserve path traversal, WebSocket origin bypass)
@@ -181,6 +181,7 @@ class ChromePool:
        default_seed: str | None = None,
        default_locale: str | None = None,
        default_timezone: str | None = None,
+        idle_timeout: float = 0.0,
    ):
        self._binary = binary
        self._global_args = global_args
@@ -189,12 +190,14 @@ class ChromePool:
        self._default_seed = default_seed
        self._default_locale = default_locale
        self._default_timezone = default_timezone
+        self._idle_timeout = idle_timeout
        self._processes: dict[str, ChromeProcess] = {}
        self._default: ChromeProcess | None = None
        self._locks: dict[str, asyncio.Lock] = {}
        self._next_port = BASE_CDP_PORT
        # Connection refcounting for status reporting
        self._connections: dict[str, int] = {}
+        self._idle_tasks: dict[str, asyncio.Task] = {}

    def _get_lock(self, seed: str) -> asyncio.Lock:
        if seed not in self._locks:
@@ -224,6 +227,7 @@ class ChromePool:

    def connect(self, seed_key: str) -> None:
        """Increment connection refcount for a seed."""
+        self._cancel_idle_cleanup(seed_key)
        self._connections[seed_key] = self._connections.get(seed_key, 0) + 1

    def disconnect(self, seed_key: str) -> None:
@@ -231,9 +235,54 @@ class ChromePool:
        count = self._connections.get(seed_key, 0) - 1
        if count <= 0:
            self._connections.pop(seed_key, None)
+            self._schedule_idle_cleanup(seed_key)
        else:
            self._connections[seed_key] = count

+    def _cancel_idle_cleanup(self, seed_key: str) -> None:
+        task = self._idle_tasks.pop(seed_key, None)
+        if task is None or task.done():
+            return
+        try:
+            current_task = asyncio.current_task()
+        except RuntimeError:
+            current_task = None
+        if task is not current_task:
+            task.cancel()
+
+    def _discard_idle_task(self, seed_key: str, task: asyncio.Task) -> None:
+        if self._idle_tasks.get(seed_key) is task:
+            self._idle_tasks.pop(seed_key, None)
+
+    def _schedule_idle_cleanup(self, seed_key: str) -> None:
+        if self._idle_timeout <= 0 or seed_key not in self._processes:
+            return
+
+        self._cancel_idle_cleanup(seed_key)
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+
+        task = loop.create_task(
+            self._cleanup_after_idle(seed_key, self._idle_timeout),
+            name=f"cloakserve-idle-cleanup-{seed_key}",
+        )
+        self._idle_tasks[seed_key] = task
+        task.add_done_callback(lambda done_task: self._discard_idle_task(seed_key, done_task))
+
+    async def _cleanup_after_idle(self, seed_key: str, timeout: float) -> None:
+        try:
+            await asyncio.sleep(timeout)
+            if self._connections.get(seed_key, 0) > 0 or seed_key not in self._processes:
+                return
+            logger.info("Cleaning up idle Chrome process (seed=%s)", seed_key)
+            await self._cleanup_process(seed_key)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.exception("Idle cleanup failed for seed=%s", seed_key)
+
    async def get_or_launch(
        self,
        seed: str | None,
@@ -271,6 +320,8 @@ class ChromePool:
            if seed_key in self._processes:
                proc = self._processes[seed_key]
                if proc.process.poll() is None:
+                    if seed_key in self._idle_tasks:
+                        self._schedule_idle_cleanup(seed_key)
                    if any([extra_args, timezone, locale, proxy, geoip]):
                        logger.warning(
                            "Seed %s already running (port %d, tz=%s, locale=%s, proxy=%s) — "
@@ -360,6 +411,7 @@ class ChromePool:

    async def _cleanup_process(self, key: str) -> None:
        """Terminate a Chrome process and clean up."""
+        self._cancel_idle_cleanup(key)
        proc = self._processes.pop(key, None)
        if not proc:
            return
@@ -377,6 +429,13 @@ class ChromePool:

    async def shutdown(self) -> None:
        """Terminate all Chrome processes."""
+        idle_tasks = list(self._idle_tasks.values())
+        self._idle_tasks.clear()
+        for task in idle_tasks:
+            if not task.done():
+                task.cancel()
+        if idle_tasks:
+            await asyncio.gather(*idle_tasks, return_exceptions=True)
        for key in list(self._processes.keys()):
            await self._cleanup_process(key)
        logger.info("All Chrome processes terminated")
@@ -453,9 +512,21 @@ def parse_connection_params(query_string: str) -> dict:
 def _ws_scheme(request: web.Request) -> str:
    """Return 'wss' if client connected via HTTPS (e.g. TLS-terminating proxy), else 'ws'."""
    proto = request.headers.get("X-Forwarded-Proto", request.scheme)
+    proto = proto.split(",", 1)[0].strip().lower()
    return "wss" if proto == "https" else "ws"


+def _external_host(request: web.Request) -> str:
+    """Return the public host to use in rewritten CDP WebSocket URLs."""
+    fallback_host = request.headers.get("Host") or f"localhost:{request.app['port']}"
+    forwarded_host = request.headers.get("X-Forwarded-Host")
+    if forwarded_host:
+        public_host = forwarded_host.split(",", 1)[0].strip()
+        if public_host:
+            return public_host
+    return fallback_host
+
+
 async def handle_root(request: web.Request) -> web.Response:
    """Health check / process status."""
    pool: ChromePool = request.app["pool"]
@@ -467,6 +538,7 @@ async def handle_root(request: web.Request) -> web.Response:
                "port": proc.cdp_port,
                "seed": proc.seed,
                "connections": pool._connections.get(key, 0),
+                "idle_cleanup_pending": key in pool._idle_tasks,
                "timezone": proc.timezone,
                "locale": proc.locale,
                "proxy": proc.proxy,
@@ -474,6 +546,7 @@ async def handle_root(request: web.Request) -> web.Response:
    return web.json_response({
        "status": "ok",
        "active": len(processes),
+        "idle_timeout": pool._idle_timeout,
        "processes": processes,
    })

@@ -504,7 +577,7 @@ async def handle_json_version(request: web.Request) -> web.Response:
        return web.json_response({"error": "CDP endpoint unreachable"}, status=502)

    # Rewrite webSocketDebuggerUrl to route through our multiplexer
-    host = request.headers.get("Host", f"localhost:{request.app['port']}")
+    host = _external_host(request)
    seed_key = params["seed"]
    if seed_key:
        ws_path = f"fingerprint/{seed_key}/devtools/browser"
@@ -545,7 +618,7 @@ async def handle_json_list(request: web.Request) -> web.Response:
        logger.error("Failed to reach Chrome CDP (port %d): %s", cp.cdp_port, exc)
        return web.json_response({"error": "CDP endpoint unreachable"}, status=502)

-    host = request.headers.get("Host", f"localhost:{request.app['port']}")
+    host = _external_host(request)
    scheme = _ws_scheme(request)
    seed_key = params["seed"]

@@ -675,6 +748,23 @@ def _default_data_dir() -> str:
    return str(Path.home() / ".cloakbrowser" / "cloakserve")


+def _parse_idle_timeout(value: str) -> float:
+    value = value.strip()
+    if value.lower() in {"0", "false", "off", "none", "disabled"}:
+        return 0.0
+    timeout = float(value)
+    if timeout < 0:
+        raise ValueError("--idle-timeout must be greater than or equal to 0")
+    return timeout
+
+
+def _default_idle_timeout() -> float:
+    value = os.environ.get("CLOAKSERVE_IDLE_TIMEOUT")
+    if value is None:
+        return 0.0
+    return _parse_idle_timeout(value)
+
+
 def parse_cli_args(argv: list[str]) -> tuple[dict, list[str]]:
    """Parse cloakserve-specific args, return (config, passthrough_args).

@@ -690,12 +780,14 @@ def parse_cli_args(argv: list[str]) -> tuple[dict, list[str]]:
        "default_seed": None,
        "default_locale": None,
        "default_timezone": None,
+        "idle_timeout": _default_idle_timeout(),
    }
    passthrough = []
    # Flags consumed by cloakserve (not passed to Chrome)
    consumed_prefixes = (
        "--port=",
        "--data-dir=",
+        "--idle-timeout=",
        "--remote-debugging-port=",
        "--remote-debugging-address=",
    )
@@ -705,6 +797,8 @@ def parse_cli_args(argv: list[str]) -> tuple[dict, list[str]]:
            config["port"] = int(arg.split("=", 1)[1])
        elif arg.startswith("--data-dir="):
            config["data_dir"] = arg.split("=", 1)[1]
+        elif arg.startswith("--idle-timeout="):
+            config["idle_timeout"] = _parse_idle_timeout(arg.split("=", 1)[1])
        elif arg == "--headless=false" or arg == "--headless=False":
            config["headless"] = False
            passthrough.append(arg)
@@ -749,6 +843,7 @@ def main() -> None:
        default_seed=config["default_seed"],
        default_locale=config["default_locale"],
        default_timezone=config["default_timezone"],
+        idle_timeout=config["idle_timeout"],
    )

    app = web.Application()
@@ -1,4 +1,12 @@
 #!/bin/bash
+# Clean up any stale Xvfb lock left behind by a previous container instance.
+# `/tmp` is not a tmpfs in this image, so on `docker restart` the previous
+# container's `/tmp/.X99-lock` survives, and Xvfb refuses to start with an
+# existing lock — leaving the container with no X server, every Chrome
+# launch dying with "Missing X server or $DISPLAY", and `cloakserve`
+# returning 502 forever. See CloakHQ/CloakBrowser#283.
+rm -f /tmp/.X99-lock /tmp/.X11-unix/X99
+
 # Start Xvfb for headed mode (Turnstile, CAPTCHAs), then run user command
 Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp &
 sleep 1
@@ -1 +1 @@
-__version__ = "0.3.30"
+__version__ = "0.3.32"
@@ -22,6 +22,7 @@ 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
+from .widevine import seed_widevine_hint

 logger = logging.getLogger("cloakbrowser")

@@ -336,6 +337,8 @@ def launch_persistent_context(
        context_kwargs["color_scheme"] = color_scheme
    context_kwargs.update(kwargs)

+    seed_widevine_hint(user_data_dir, binary_path)
+
    pw = sync_playwright().start()
    context = pw.chromium.launch_persistent_context(
        user_data_dir=os.fspath(user_data_dir),
@@ -464,6 +467,8 @@ async def launch_persistent_context_async(
        context_kwargs["color_scheme"] = color_scheme
    context_kwargs.update(kwargs)

+    seed_widevine_hint(user_data_dir, binary_path)
+
    pw = await async_playwright().start()
    context = await pw.chromium.launch_persistent_context(
        user_data_dir=os.fspath(user_data_dir),
@@ -774,7 +779,7 @@ def _ensure_proxy_scheme(proxy_url: str) -> str:
    return proxy_url if "://" in proxy_url else f"http://{proxy_url}"


-def _assemble_socks_url(
+def _assemble_proxy_url(
    scheme: str,
    host: str,
    port: int | None,
@@ -785,7 +790,7 @@ def _assemble_socks_url(
    query: str = "",
    fragment: str = "",
 ) -> str:
-    """Build a SOCKS URL from already-percent-encoded credentials and host parts.
+    """Build a proxy 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
@@ -816,7 +821,7 @@ def _reconstruct_socks_url(proxy: ProxySettings) -> str:
    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(
+    return _assemble_proxy_url(
        parsed.scheme, parsed.hostname or "", parsed.port,
        enc_user, enc_pass, parsed.path,
    )
@@ -856,7 +861,7 @@ def _normalize_socks_string_url(url: str) -> str:
    else:
        raw_pass = None
        enc_pass = None
-    normalized = _assemble_socks_url(
+    normalized = _assemble_proxy_url(
        parsed.scheme, parsed.hostname or "", parsed.port,
        enc_user, enc_pass,
        parsed.path, parsed.params, parsed.query, parsed.fragment,
@@ -1061,6 +1066,81 @@ def _parse_proxy_url(proxy: str) -> dict[str, Any]:
    return result


+def _has_credentials(proxy: str | ProxySettings) -> bool:
+    """Check if the proxy has inline or dict-level credentials."""
+    if isinstance(proxy, dict):
+        return bool(proxy.get("username"))
+    return "@" in proxy
+
+
+def _reconstruct_http_url(proxy: ProxySettings) -> str:
+    """Reconstruct an HTTP(S) proxy URL with inline credentials from a Playwright proxy dict."""
+    server = proxy.get("server", "")
+    username = proxy.get("username", "")
+    password = proxy.get("password", "")
+    if not username:
+        return server
+    parsed = urlparse(_ensure_proxy_scheme(server))
+    enc_user = quote(username, safe="")
+    enc_pass = quote(password, safe="") if password else None
+    return _assemble_proxy_url(
+        parsed.scheme, parsed.hostname or "", parsed.port,
+        enc_user, enc_pass, parsed.path,
+    )
+
+
+def _normalize_http_string_url(url: str) -> str:
+    """Re-encode credentials in an HTTP(S) proxy URL string for --proxy-server.
+
+    Same pattern as ``_normalize_socks_string_url`` — decode then re-encode to
+    ensure Chromium's proxy URL parser handles special chars correctly.
+    """
+    normalized = url if "://" in url else f"http://{url}"
+    try:
+        parsed = urlparse(normalized)
+        _ = parsed.port
+    except ValueError as e:
+        logger.warning("Malformed HTTP proxy URL, passing through unchanged: %s", e)
+        return normalized
+    if parsed.username is None and parsed.password is None:
+        return normalized
+    raw_user = parsed.username or ""
+    enc_user = quote(unquote(raw_user), safe="") if raw_user else ""
+    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
+    result = _assemble_proxy_url(
+        parsed.scheme, parsed.hostname or "", parsed.port,
+        enc_user, enc_pass,
+        parsed.path, parsed.params, parsed.query, parsed.fragment,
+    )
+    if enc_user != raw_user or enc_pass != raw_pass:
+        logger.info(
+            "Auto URL-encoded HTTP proxy credentials (special characters "
+            "detected). Pre-encode the URL to suppress this notice."
+        )
+    return result
+
+
+_HTTP_PROXY_INLINE_AUTH_MIN_VERSION = "146.0.7680.177.5"
+_HTTP_PROXY_INLINE_AUTH_PLATFORMS = {"linux-x64", "windows-x64"}
+
+
+def _supports_http_proxy_inline_auth() -> bool:
+    """Check if the current platform's binary supports HTTP proxy inline credentials.
+
+    Requires both a supported platform AND a binary version with preemptive proxy auth.
+    """
+    from .config import get_platform_tag, get_chromium_version, _version_tuple
+    tag = get_platform_tag()
+    if tag not in _HTTP_PROXY_INLINE_AUTH_PLATFORMS:
+        return False
+    return _version_tuple(get_chromium_version()) >= _version_tuple(_HTTP_PROXY_INLINE_AUTH_MIN_VERSION)
+
+
 def _is_socks_proxy(proxy: str | ProxySettings | None) -> bool:
    """Check if the proxy uses SOCKS5 protocol."""
    if proxy is None:
@@ -1074,8 +1154,9 @@ def _resolve_proxy_config(
 ) -> tuple[dict[str, Any], list[str]]:
    """Resolve proxy into Playwright kwargs and Chrome args.

-    Playwright rejects SOCKS5 proxies with credentials in its proxy dict,
-    so SOCKS5 is passed via --proxy-server Chrome arg instead.
+    Proxies with credentials (SOCKS5 or HTTP/HTTPS) are passed via Chrome's
+    --proxy-server flag with inline credentials, bypassing Playwright's CDP
+    auth interceptor which breaks on some proxies and Google domains (#182).

    Returns:
        (proxy_kwargs, extra_chrome_args) — one or both will be empty.
@@ -1096,7 +1177,20 @@ def _resolve_proxy_config(
        # 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
+    # HTTP/HTTPS with credentials on supported platforms: bypass Playwright's
+    # CDP auth interceptor, pass directly to Chrome via --proxy-server with
+    # inline creds. Chrome sends Proxy-Authorization preemptively, avoiding
+    # the 407 round-trip that breaks on some proxies (#182).
+    if _has_credentials(proxy) and _supports_http_proxy_inline_auth():
+        if isinstance(proxy, dict):
+            url = _reconstruct_http_url(proxy)
+            extra_args = [f"--proxy-server={url}"]
+            if proxy.get("bypass"):
+                extra_args.append(f"--proxy-bypass-list={proxy['bypass']}")
+            return {}, extra_args
+        return {}, [f"--proxy-server={_normalize_http_string_url(proxy)}"]
+
+    # HTTP/HTTPS without credentials: use Playwright's proxy dict
    if isinstance(proxy, dict):
        return {"proxy": proxy}, []
    return {"proxy": _parse_proxy_url(proxy)}, []
@@ -1257,13 +1257,16 @@ def _patch_single_element_handle_sync(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            ensure_actionable_handle(page, el, CHECKS_CLICK, timeout=timeout, force=force)
+            ensure_actionable_handle(page, el, CHECKS_CLICK, timeout=_remaining_ms(), force=force)
        info = _move_to_element(call_cfg)
        if info is None:
            return _orig_click(**kwargs)
        if not force:
-            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        human_click(raw_mouse, info['is_inp'], call_cfg)

    # --- el.dblclick() ---
@@ -1271,13 +1274,16 @@ def _patch_single_element_handle_sync(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            ensure_actionable_handle(page, el, CHECKS_CLICK, timeout=timeout, force=force)
+            ensure_actionable_handle(page, el, CHECKS_CLICK, timeout=_remaining_ms(), force=force)
        info = _move_to_element(call_cfg)
        if info is None:
            return _orig_dblclick(**kwargs)
        if not force:
-            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        raw_mouse.down(click_count=2)
        sleep_ms(rand(30, 60))
        raw_mouse.up(click_count=2)
@@ -1287,8 +1293,11 @@ def _patch_single_element_handle_sync(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            ensure_actionable_handle(page, el, CHECKS_HOVER, timeout=timeout, force=force)
+            ensure_actionable_handle(page, el, CHECKS_HOVER, timeout=_remaining_ms(), force=force)
        info = _move_to_element(call_cfg)
        if info is None:
            return _orig_hover(**kwargs)
@@ -1298,13 +1307,16 @@ def _patch_single_element_handle_sync(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            ensure_actionable_handle(page, el, CHECKS_INPUT, timeout=timeout, force=force)
+            ensure_actionable_handle(page, el, CHECKS_INPUT, timeout=_remaining_ms(), force=force)
        info = _move_to_element(call_cfg)
        if info is None:
            return _orig_type(text, **kwargs)
        if not force:
-            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        human_click(raw_mouse, info['is_inp'], call_cfg)
        sleep_ms(rand(100, 250))
        human_type(page, raw_keyboard, text, call_cfg, cdp_session=cdp_session)
@@ -1314,13 +1326,16 @@ def _patch_single_element_handle_sync(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            ensure_actionable_handle(page, el, CHECKS_INPUT, timeout=timeout, force=force)
+            ensure_actionable_handle(page, el, CHECKS_INPUT, timeout=_remaining_ms(), force=force)
        info = _move_to_element(call_cfg)
        if info is None:
            return _orig_fill(value, **kwargs)
        if not force:
-            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        human_click(raw_mouse, info['is_inp'], call_cfg)
        sleep_ms(rand(100, 250))
        originals.keyboard_press(_SELECT_ALL)
@@ -1367,8 +1382,11 @@ def _patch_single_element_handle_sync(
    def _human_el_select_option(value: Any = None, **kwargs: Any) -> Any:
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            ensure_actionable_handle(page, el, CHECKS_FOCUS, timeout=timeout, force=force)
+            ensure_actionable_handle(page, el, CHECKS_FOCUS, timeout=_remaining_ms(), force=force)
        info = _move_to_element()
        if info is None:
            return _orig_select_option(value, **kwargs)
@@ -1380,8 +1398,11 @@ def _patch_single_element_handle_sync(
    def _human_el_check(**kwargs: Any) -> None:
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=timeout, force=force)
+            ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=_remaining_ms(), force=force)
        try:
            if el.is_checked():
                return
@@ -1391,15 +1412,18 @@ def _patch_single_element_handle_sync(
        if info is None:
            return _orig_check(**kwargs)
        if not force:
-            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        human_click(raw_mouse, info['is_inp'], cfg)

    # --- el.uncheck() ---
    def _human_el_uncheck(**kwargs: Any) -> None:
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=timeout, force=force)
+            ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=_remaining_ms(), force=force)
        try:
            if not el.is_checked():
                return
@@ -1409,15 +1433,18 @@ def _patch_single_element_handle_sync(
        if info is None:
            return _orig_uncheck(**kwargs)
        if not force:
-            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        human_click(raw_mouse, info['is_inp'], cfg)

    # --- el.set_checked() ---
    def _human_el_set_checked(checked: bool, **kwargs: Any) -> None:
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=timeout, force=force)
+            ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=_remaining_ms(), force=force)
        try:
            current = el.is_checked()
            if current == checked:
@@ -1429,7 +1456,7 @@ def _patch_single_element_handle_sync(
            return _orig_set_checked(checked, **kwargs)
        if info:
            if not force:
-                check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+                check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
            human_click(raw_mouse, info['is_inp'], cfg)

    # --- el.tap() ---
@@ -2158,13 +2185,16 @@ def _patch_single_element_handle_async(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            await async_ensure_actionable_handle(page, el, CHECKS_CLICK, timeout=timeout, force=force)
+            await async_ensure_actionable_handle(page, el, CHECKS_CLICK, timeout=_remaining_ms(), force=force)
        info = await _move_to_element(call_cfg)
        if info is None:
            return await _orig_click(**kwargs)
        if not force:
-            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        await async_human_click(raw_mouse, info['is_inp'], call_cfg)

    # --- el.dblclick() ---
@@ -2172,13 +2202,16 @@ def _patch_single_element_handle_async(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            await async_ensure_actionable_handle(page, el, CHECKS_CLICK, timeout=timeout, force=force)
+            await async_ensure_actionable_handle(page, el, CHECKS_CLICK, timeout=_remaining_ms(), force=force)
        info = await _move_to_element(call_cfg)
        if info is None:
            return await _orig_dblclick(**kwargs)
        if not force:
-            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        await raw_mouse.down(click_count=2)
        await async_sleep_ms(rand(30, 60))
        await raw_mouse.up(click_count=2)
@@ -2188,8 +2221,11 @@ def _patch_single_element_handle_async(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            await async_ensure_actionable_handle(page, el, CHECKS_HOVER, timeout=timeout, force=force)
+            await async_ensure_actionable_handle(page, el, CHECKS_HOVER, timeout=_remaining_ms(), force=force)
        info = await _move_to_element(call_cfg)
        if info is None:
            return await _orig_hover(**kwargs)
@@ -2199,13 +2235,16 @@ def _patch_single_element_handle_async(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            await async_ensure_actionable_handle(page, el, CHECKS_INPUT, timeout=timeout, force=force)
+            await async_ensure_actionable_handle(page, el, CHECKS_INPUT, timeout=_remaining_ms(), force=force)
        info = await _move_to_element(call_cfg)
        if info is None:
            return await _orig_type(text, **kwargs)
        if not force:
-            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        await async_human_click(raw_mouse, info['is_inp'], call_cfg)
        await async_sleep_ms(rand(100, 250))
        cdp = await _get_cdp()
@@ -2216,13 +2255,16 @@ def _patch_single_element_handle_async(
        call_cfg = merge_config(cfg, kwargs.get("human_config"))
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            await async_ensure_actionable_handle(page, el, CHECKS_INPUT, timeout=timeout, force=force)
+            await async_ensure_actionable_handle(page, el, CHECKS_INPUT, timeout=_remaining_ms(), force=force)
        info = await _move_to_element(call_cfg)
        if info is None:
            return await _orig_fill(value, **kwargs)
        if not force:
-            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        await async_human_click(raw_mouse, info['is_inp'], call_cfg)
        await async_sleep_ms(rand(100, 250))
        await originals.keyboard_press(_SELECT_ALL)
@@ -2269,8 +2311,11 @@ def _patch_single_element_handle_async(
    async def _human_el_select_option(value: Any = None, **kwargs: Any) -> Any:
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            await async_ensure_actionable_handle(page, el, CHECKS_FOCUS, timeout=timeout, force=force)
+            await async_ensure_actionable_handle(page, el, CHECKS_FOCUS, timeout=_remaining_ms(), force=force)
        info = await _move_to_element()
        if info is None:
            return await _orig_select_option(value, **kwargs)
@@ -2282,8 +2327,11 @@ def _patch_single_element_handle_async(
    async def _human_el_check(**kwargs: Any) -> None:
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            await async_ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=timeout, force=force)
+            await async_ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=_remaining_ms(), force=force)
        try:
            if await el.is_checked():
                return
@@ -2293,15 +2341,18 @@ def _patch_single_element_handle_async(
        if info is None:
            return await _orig_check(**kwargs)
        if not force:
-            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        await async_human_click(raw_mouse, info['is_inp'], cfg)

    # --- el.uncheck() ---
    async def _human_el_uncheck(**kwargs: Any) -> None:
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            await async_ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=timeout, force=force)
+            await async_ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=_remaining_ms(), force=force)
        try:
            if not await el.is_checked():
                return
@@ -2311,15 +2362,18 @@ def _patch_single_element_handle_async(
        if info is None:
            return await _orig_uncheck(**kwargs)
        if not force:
-            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+            await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
        await async_human_click(raw_mouse, info['is_inp'], cfg)

    # --- el.set_checked() ---
    async def _human_el_set_checked(checked: bool, **kwargs: Any) -> None:
        force = kwargs.get("force", False)
        timeout = kwargs.get("timeout", 30000)
+        deadline = time.monotonic() + timeout / 1000.0
+        def _remaining_ms():
+            return max(0, (deadline - time.monotonic()) * 1000)
        if not force:
-            await async_ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=timeout, force=force)
+            await async_ensure_actionable_handle(page, el, CHECKS_CHECK, timeout=_remaining_ms(), force=force)
        try:
            current = await el.is_checked()
            if current == checked:
@@ -2331,7 +2385,7 @@ def _patch_single_element_handle_async(
            return await _orig_set_checked(checked, **kwargs)
        if info:
            if not force:
-                await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(timeout, 5000))
+                await async_check_pointer_events_handle(page, el, cursor.x, cursor.y, timeout=min(_remaining_ms(), 5000))
            await async_human_click(raw_mouse, info['is_inp'], cfg)

    # --- el.tap() ---
@@ -196,8 +196,14 @@ def ensure_stable(
 # Pointer-events check (post-scroll, at actual click coordinates)
 # ---------------------------------------------------------------------------

-_POINTER_EVENTS_LOCATOR_JS = """(expected, coords) => {
-    const target = document.elementFromPoint(coords.x, coords.y);
+# data.box is page-space (from bounding_box); rect is frame-local. Their delta
+# is the iframe offset, needed to map page-space click coords into the frame's
+# own viewport before elementFromPoint. For main-frame elements the offset is 0.
+_POINTER_EVENTS_LOCATOR_JS = """(expected, data) => {
+    const rect = expected.getBoundingClientRect();
+    const frameOffsetX = data.box ? data.box.x - rect.x : 0;
+    const frameOffsetY = data.box ? data.box.y - rect.y : 0;
+    const target = document.elementFromPoint(data.x - frameOffsetX, data.y - frameOffsetY);
    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; }
@@ -205,8 +211,11 @@ _POINTER_EVENTS_LOCATOR_JS = """(expected, coords) => {
    return { hit: false, reason: 'covered', covering: target.tagName || 'unknown' };
 }"""

-_POINTER_EVENTS_HANDLE_JS = """(expected, coords) => {
-    const target = document.elementFromPoint(coords.x, coords.y);
+_POINTER_EVENTS_HANDLE_JS = """(expected, data) => {
+    const rect = expected.getBoundingClientRect();
+    const frameOffsetX = data.box ? data.box.x - rect.x : 0;
+    const frameOffsetY = data.box ? data.box.y - rect.y : 0;
+    const target = document.elementFromPoint(data.x - frameOffsetX, data.y - frameOffsetY);
    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; }
@@ -230,17 +239,19 @@ def check_pointer_events(
    """
    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)
+            box = loc.bounding_box(timeout=max(1, min((deadline - time.monotonic()) * 1000, 1000)))
+            result = loc.evaluate(_POINTER_EVENTS_LOCATOR_JS, {"x": x, "y": y, "box": box})
        except Exception as exc:
            logger.debug("pointer_events check failed for %r: %s", selector, exc)
            result = None

-        if result and result.get("hit", False):
+        # Proceed if the check confirms a hit, or if it could not be determined
+        # (None) — failing closed would block legitimate clicks.
+        if result is None or result.get("hit", False):
            return

        covering = (result or {}).get("covering", "unknown")
@@ -322,15 +333,16 @@ def check_pointer_events_handle(
    deadline = time.monotonic() + timeout / 1000.0
    attempt = 0

-    coords = {"x": x, "y": y}
-
    while True:
        try:
-            result = el.evaluate(_POINTER_EVENTS_HANDLE_JS, coords)
+            box = el.bounding_box()
+            result = el.evaluate(_POINTER_EVENTS_HANDLE_JS, {"x": x, "y": y, "box": box})
        except Exception:
            result = None

-        if result and result.get("hit", False):
+        # Proceed if the check confirms a hit, or if it could not be determined
+        # (None) — failing closed would block legitimate clicks.
+        if result is None or result.get("hit", False):
            return

        covering = (result or {}).get("covering", "unknown")
@@ -140,17 +140,19 @@ async def async_check_pointer_events(
 ) -> 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)
+            box = await loc.bounding_box(timeout=max(1, min((deadline - time.monotonic()) * 1000, 1000)))
+            result = await loc.evaluate(_POINTER_EVENTS_LOCATOR_JS, {"x": x, "y": y, "box": box})
        except Exception as exc:
            logger.debug("pointer_events check failed for %r: %s", selector, exc)
            result = None

-        if result and result.get("hit", False):
+        # Proceed if the check confirms a hit, or if it could not be determined
+        # (None) — failing closed would block legitimate clicks.
+        if result is None or result.get("hit", False):
            return

        covering = (result or {}).get("covering", "unknown")
@@ -227,15 +229,16 @@ async def async_check_pointer_events_handle(
    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)
+            box = await el.bounding_box()
+            result = await el.evaluate(_POINTER_EVENTS_HANDLE_JS, {"x": x, "y": y, "box": box})
        except Exception:
            result = None

-        if result and result.get("hit", False):
+        # Proceed if the check confirms a hit, or if it could not be determined
+        # (None) — failing closed would block legitimate clicks.
+        if result is None or result.get("hit", False):
            return

        covering = (result or {}).get("covering", "unknown")
@@ -0,0 +1,112 @@
+"""Widevine CDM hint-file seeding for persistent contexts.
+
+CloakBrowser's binary is built with Widevine support but ships no CDM (the CDM
+is a proprietary Google binary we can't redistribute). Users sideload it by
+copying a ``WidevineCdm/`` directory from a real Chrome install next to the
+binary (see issue #96).
+
+Chromium discovers a sideloaded CDM in two phases: an early-startup pass that
+reads a "hint file" from the user-data-dir, and a later async component-updater
+pass that writes that hint file. On a fresh profile the hint file doesn't exist
+on the first launch, and Playwright passes ``--disable-component-update``, so the
+updater never writes it — Widevine only works after a manual two-launch dance.
+
+This module pre-seeds the hint file before launch so a sideloaded CDM works on
+the very first launch. It never bundles, downloads, or copies the CDM itself —
+it only writes the hint when a CDM the user provided is already present.
+
+Linux only: Chromium's hint-file mechanism is Linux/ChromeOS-specific. On Windows
+the CDM can't initialise (DRM host verification), and macOS uses a different CDM
+layout, so seeding is a no-op there.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import platform
+from pathlib import Path
+
+logger = logging.getLogger("cloakbrowser")
+
+# Chromium reads this file from <user-data-dir>/WidevineCdm/ at early startup.
+_HINT_FILENAME = "latest-component-updated-widevine-cdm"
+
+
+def _seeding_disabled() -> bool:
+    """True if CLOAKBROWSER_WIDEVINE is set to a falsey value (kill switch)."""
+    val = os.environ.get("CLOAKBROWSER_WIDEVINE", "").strip().lower()
+    return val in ("0", "false", "off", "no")
+
+
+def resolve_widevine_cdm_dir(binary_path: str | os.PathLike) -> Path | None:
+    """Locate a sideloaded Widevine CDM directory, or None if absent.
+
+    Resolution:
+      - If CLOAKBROWSER_WIDEVINE_CDM is set, it is used **exclusively** (overrides
+        auto-detection). An invalid value (no ``manifest.json``) skips seeding.
+      - Otherwise, ``<dir of the chrome binary>/WidevineCdm`` — where a user
+        naturally drops it, and where it ends up for both downloaded and
+        CLOAKBROWSER_BINARY_PATH (local build / Docker mount) binaries.
+
+    A directory counts only if it contains ``manifest.json`` (so we don't seed a
+    hint pointing at a bogus path). The returned path is absolute and
+    symlink-resolved (``Path.resolve()``).
+    """
+    custom = os.environ.get("CLOAKBROWSER_WIDEVINE_CDM")
+    # `is not None` (not truthiness): a present-but-empty env var is "set" and
+    # used exclusively — it resolves to an invalid path and skips seeding.
+    cdm_dir = Path(custom) if custom is not None else Path(os.fspath(binary_path)).parent / "WidevineCdm"
+    return cdm_dir.resolve() if (cdm_dir / "manifest.json").is_file() else None
+
+
+def seed_widevine_hint(user_data_dir: str | os.PathLike, binary_path: str | os.PathLike) -> None:
+    """Write the Widevine CDM hint file into a persistent profile before launch.
+
+    ``binary_path`` is the resolved chrome executable; the CDM is looked for next
+    to it. No-op on non-Linux platforms, when seeding is disabled via
+    CLOAKBROWSER_WIDEVINE, or when no sideloaded CDM is present. Never raises —
+    a failure here must not break the browser launch.
+    """
+    if platform.system() != "Linux":
+        return
+    if _seeding_disabled():
+        logger.debug("Widevine hint seeding disabled via CLOAKBROWSER_WIDEVINE")
+        return
+    if not user_data_dir:
+        # Empty user_data_dir = Playwright's ephemeral profile (its own temp dir);
+        # a persistent hint can't be placed there, and "" would pollute the CWD.
+        return
+
+    # Everything below is best-effort and must never break the browser launch,
+    # so the whole body (resolution + write) is guarded.
+    try:
+        cdm_dir = resolve_widevine_cdm_dir(binary_path)
+        if cdm_dir is None:
+            if os.environ.get("CLOAKBROWSER_WIDEVINE_CDM") is not None:
+                logger.warning(
+                    "CLOAKBROWSER_WIDEVINE_CDM is set but has no manifest.json; "
+                    "skipping Widevine hint seeding"
+                )
+            else:
+                logger.debug("No sideloaded Widevine CDM found; skipping hint seeding")
+            return
+
+        hint_dir = Path(os.fspath(user_data_dir)) / "WidevineCdm"
+        hint_dir.mkdir(parents=True, exist_ok=True)
+        hint_file = hint_dir / _HINT_FILENAME
+        # cdm_dir is already absolute/resolved. Compact separators + ensure_ascii=False
+        # byte-match the JS wrapper's JSON.stringify (UTF-8) output.
+        content = json.dumps({"Path": str(cdm_dir)}, separators=(",", ":"), ensure_ascii=False)
+
+        try:
+            if hint_file.is_file() and hint_file.read_text(encoding="utf-8") == content:
+                return  # already seeded correctly
+        except Exception:
+            logger.warning("Existing Widevine hint unreadable; rewriting")
+
+        hint_file.write_text(content, encoding="utf-8")
+        logger.info("Seeded Widevine CDM hint -> %s", cdm_dir)
+    except Exception as e:
+        logger.warning("Failed to seed Widevine CDM hint file: %s", e)
@@ -5,7 +5,7 @@ Expected: 0.9 (human-level) with cloakbrowser.
 Default Playwright typically scores 0.1-0.3.
 """

-import time
+import re

 from cloakbrowser import launch

@@ -13,19 +13,20 @@ print("Launching stealth browser...", flush=True)
 browser = launch(headless=True)
 page = browser.new_page()

-# Google's official reCAPTCHA v3 demo
+# Google's official reCAPTCHA v3 demo — scores automatically on page load.
 page.goto("https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php")
-page.wait_for_load_state("networkidle")

-# Click to trigger reCAPTCHA scoring
-button = page.query_selector("button")
-if button:
-    button.click()
-    time.sleep(3)
+# The score renders only after an async token + backend-verify round-trip,
+# which can finish *after* "networkidle". Wait for the actual result text
+# instead of a proxy signal, or the screenshot races the scoring.
+page.wait_for_function(
+    "() => document.body.innerText.includes('Received response from our backend')",
+    timeout=20000,
+)

-# Extract score from page
-content = page.content()
-print("Page loaded. Check the score in the response.")
+# Extract score from the rendered response
+match = re.search(r'"score":\s*([0-9.]+)', page.inner_text("body"))
+print(f"reCAPTCHA v3 score: {match.group(1) if match else 'not found'}")
 print(f"URL: {page.url}")

 # Take screenshot as proof
@@ -11,7 +11,7 @@

 Drop-in Playwright/Puppeteer replacement. Same API, same code — just swap the import. **3 lines of code, 30 seconds to unblock.**

- **48 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, WebRTC, network timing, automation signals
+- **58 source-level C++ patches** — canvas, WebGL, audio, fonts, GPU, screen, WebRTC, network timing, automation signals
 - **0.9 reCAPTCHA v3 score** — human-level, server-verified
 - **Passes Cloudflare Turnstile**, FingerprintJS, BrowserScan — tested against 30+ detection sites
 - **`npm install cloakbrowser`** — binary auto-downloads, auto-updates, zero config
@@ -39,11 +39,24 @@ import { launch } from 'cloakbrowser';

 const browser = await launch();
 const page = await browser.newPage();
-await page.goto('https://protected-site.com');
+await page.goto('https://example.com');
 console.log(await page.title());
 await browser.close();
 ```

+**For sites with anti-bot protection**, add a residential proxy and these flags:
+
+```javascript
+const browser = await launch({
+    proxy: 'http://user:pass@residential-proxy:port',
+    geoip: true,       // match timezone + locale to proxy IP
+    headless: false,    // some sites detect headless even with C++ patches
+    humanize: true,     // human-like mouse, keyboard, scroll
+});
+```
+
+See the [main README](https://github.com/CloakHQ/CloakBrowser#troubleshooting) for site-specific troubleshooting (FingerprintJS, Kasada, reCAPTCHA).
+
 ### Puppeteer

 > **Note:** Playwright is recommended for sites with reCAPTCHA Enterprise. Puppeteer's CDP protocol leaks automation signals that reCAPTCHA Enterprise can detect. This is a known Puppeteer limitation, not specific to CloakBrowser.
@@ -53,7 +66,7 @@ import { launch } from 'cloakbrowser/puppeteer';

 const browser = await launch();
 const page = await browser.newPage();
-await page.goto('https://protected-site.com');
+await page.goto('https://example.com');
 console.log(await page.title());
 await browser.close();
 ```
@@ -189,6 +202,18 @@ if (newVersion) console.log(`Updated to ${newVersion}`);
 | `CLOAKBROWSER_DOWNLOAD_URL` | `cloakbrowser.dev` | Custom download URL |
 | `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_WIDEVINE_CDM` | — | Path to a sideloaded `WidevineCdm` directory (overrides auto-detection next to the binary) |
+| `CLOAKBROWSER_WIDEVINE` | `1` | Set to `0` to disable automatic Widevine hint-file seeding for persistent contexts |
+
+### Widevine / DRM
+
+The binary supports Widevine, but the CDM is proprietary and can't be redistributed. Sideload it once by copying a `WidevineCdm/` directory from a real Chrome install next to the binary (full steps in [#96](https://github.com/CloakHQ/CloakBrowser/issues/96)):
+
+```bash
+cp -r /opt/google/chrome/WidevineCdm ~/.cloakbrowser/chromium-<version>/WidevineCdm
+```
+
+With the CDM in place, `launchPersistentContext()` enables Widevine on the **first** launch — the wrapper auto-seeds the CDM hint file into the profile. This plays DRM-protected video (Netflix, Spotify Web) and makes a persistent profile present as a regular Chrome install to detection services that probe for DRM/EME support. **Linux only.** A sideloaded CDM is the opt-in (no flag); set `CLOAKBROWSER_WIDEVINE_CDM` for a custom path or `CLOAKBROWSER_WIDEVINE=0` to disable. See the [main README](https://github.com/CloakHQ/CloakBrowser#widevine--drm) for details.

 ## Migrate From Playwright

@@ -1,6 +1,6 @@
 {
  "name": "cloakbrowser",
-  "version": "0.3.30",
+  "version": "0.3.32",
  "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",
@@ -81,12 +81,12 @@
    "tar": "^7.0.0"
  },
  "devDependencies": {
-    "@types/node": "^20.10.0",
+    "@types/node": "^25.9.1",
    "mmdb-lib": "^3.0.2",
+    "playwright-core": "1.60",
+    "puppeteer-core": "^25.0.4",
    "socks-proxy-agent": "^10.0.0",
-    "playwright-core": "^1.53.0",
-    "puppeteer-core": "^21.0.0",
-    "typescript": "^5.3.0",
+    "typescript": "^6.0.3",
    "vitest": "^1.0.0"
  },
  "scripts": {
@@ -425,11 +425,16 @@ async function extractZip(archivePath: string, destDir: string): Promise<void> {
  if (process.platform === "win32") {
    // PowerShell 5.1's Expand-Archive uses .NET FileStream which can conflict
    // with recently-closed Node.js file handles. Use ZipFile API directly.
+    // Pass paths via env vars (not interpolated into the script) so a quote or
+    // other special char in the path can't break out and be parsed as code.
    execFileSync("powershell", [
      "-NoProfile", "-Command",
      `Add-Type -AssemblyName System.IO.Compression.FileSystem; ` +
-      `[System.IO.Compression.ZipFile]::ExtractToDirectory('${archivePath}', '${destDir}')`,
-    ], { timeout: 120_000 });
+      `[System.IO.Compression.ZipFile]::ExtractToDirectory($env:CB_ARCHIVE, $env:CB_DEST)`,
+    ], {
+      timeout: 120_000,
+      env: { ...process.env, CB_ARCHIVE: archivePath, CB_DEST: destDir },
+    });
  } else {
    execFileSync("unzip", ["-o", archivePath, "-d", destDir], { timeout: 120_000 });
  }
@@ -197,8 +197,11 @@ export async function ensureStable(
 // Pointer-events check (post-scroll, at actual click coordinates)
 // ---------------------------------------------------------------------------

-const POINTER_EVENTS_LOCATOR_JS = `(expected, coords) => {
-  const target = document.elementFromPoint(coords.x, coords.y);
+const POINTER_EVENTS_LOCATOR_JS = `(expected, data) => {
+  const rect = expected.getBoundingClientRect();
+  const frameOffsetX = data.box ? data.box.x - rect.x : 0;
+  const frameOffsetY = data.box ? data.box.y - rect.y : 0;
+  const target = document.elementFromPoint(data.x - frameOffsetX, data.y - frameOffsetY);
  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; }
@@ -206,8 +209,11 @@ const POINTER_EVENTS_LOCATOR_JS = `(expected, coords) => {
  return { hit: false, reason: 'covered', covering: target.tagName || 'unknown' };
 }`;

-const POINTER_EVENTS_HANDLE_JS = `(expected, coords) => {
-  const target = document.elementFromPoint(coords.x, coords.y);
+const POINTER_EVENTS_HANDLE_JS = `(expected, data) => {
+  const rect = expected.getBoundingClientRect();
+  const frameOffsetX = data.box ? data.box.x - rect.x : 0;
+  const frameOffsetY = data.box ? data.box.y - rect.y : 0;
+  const target = document.elementFromPoint(data.x - frameOffsetX, data.y - frameOffsetY);
  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; }
@@ -225,18 +231,18 @@ export async function checkPointerEvents(
 ): 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);
+      const box = await loc.boundingBox({ timeout: Math.max(1, Math.min(deadline - Date.now(), 1000)) });
+      result = await loc.evaluate(POINTER_EVENTS_LOCATOR_JS, { x, y, box });
    } catch {
      result = null;
    }

-    if (result && result.hit) return;
+    if (!result || result.hit) return;
    const covering = (result as any)?.covering ?? 'unknown';
    if (Date.now() >= deadline) throw new ElementNotReceivingEventsError(selector, covering);

@@ -317,17 +323,16 @@ export async function checkPointerEventsHandle(
  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);
+      const box = await el.boundingBox();
+      result = await el.evaluate(POINTER_EVENTS_HANDLE_JS, { x, y, box });
    } catch {
      result = null;
    }

-    if (result && result.hit) return;
+    if (!result || result.hit) return;

    const covering = (result as any)?.covering ?? 'unknown';
    if (Date.now() >= deadline) throw new ElementNotReceivingEventsError('<ElementHandle>', covering);
@@ -196,10 +196,12 @@ export function patchSingleElementHandle(
    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 deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    if (!force) await ensureActionableHandle(el, CHECKS_CLICK, remainingMs(), force);
    const info = await moveToElement(callCfg);
    if (!info) return origElClick(options);
-    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(remainingMs(), 5000));
    await humanClick(raw, info.isInp, callCfg);
  };

@@ -216,10 +218,12 @@ export function patchSingleElementHandle(
    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 deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    if (!force) await ensureActionableHandle(el, CHECKS_CLICK, remainingMs(), force);
    const info = await moveToElement(callCfg);
    if (!info) return origElDblclick(options);
-    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(remainingMs(), 5000));
    await raw.down({ clickCount: 2 });
    await sleep(rand(30, 60));
    await raw.up({ clickCount: 2 });
@@ -235,7 +239,9 @@ export function patchSingleElementHandle(
    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 deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    if (!force) await ensureActionableHandle(el, CHECKS_HOVER, remainingMs(), force);
    const info = await moveToElement(callCfg);
    if (!info) return origElHover(options);
  };
@@ -248,10 +254,12 @@ export function patchSingleElementHandle(
    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 deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    if (!force) await ensureActionableHandle(el, CHECKS_INPUT, remainingMs(), force);
    const info = await moveToElement(callCfg);
    if (!info) return origElType(text, options);
-    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(remainingMs(), 5000));
    await humanClick(raw, info.isInp, callCfg);
    await sleep(rand(100, 250));
    let cdpSession: CDPSession | null = null;
@@ -267,10 +275,12 @@ export function patchSingleElementHandle(
    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 deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    if (!force) await ensureActionableHandle(el, CHECKS_INPUT, remainingMs(), force);
    const info = await moveToElement(callCfg);
    if (!info) return origElFill(value, options);
-    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(timeout, 5000));
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(remainingMs(), 5000));
    await humanClick(raw, info.isInp, callCfg);
    await sleep(rand(100, 250));
    await originals.keyboardPress(SELECT_ALL);
@@ -298,7 +308,9 @@ export function patchSingleElementHandle(
  }) => {
    const force = options?.force ?? false;
    const timeout = options?.timeout ?? 30000;
-    if (!force) await ensureActionableHandle(el, CHECKS_FOCUS, timeout, force);
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    if (!force) await ensureActionableHandle(el, CHECKS_FOCUS, remainingMs(), force);
    const info = await moveToElement();
    if (!info) return origElSelectOption(values, options);
    await humanClick(raw, false, cfg);
@@ -316,14 +328,16 @@ export function patchSingleElementHandle(
  }) => {
    const force = options?.force ?? false;
    const timeout = options?.timeout ?? 30000;
-    if (!force) await ensureActionableHandle(el, CHECKS_CHECK, timeout, force);
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    if (!force) await ensureActionableHandle(el, CHECKS_CHECK, remainingMs(), force);
    try {
      const checked = await el.isChecked();
      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));
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(remainingMs(), 5000));
    await humanClick(raw, info.isInp, cfg);
  };

@@ -337,14 +351,16 @@ export function patchSingleElementHandle(
  }) => {
    const force = options?.force ?? false;
    const timeout = options?.timeout ?? 30000;
-    if (!force) await ensureActionableHandle(el, CHECKS_CHECK, timeout, force);
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    if (!force) await ensureActionableHandle(el, CHECKS_CHECK, remainingMs(), force);
    try {
      const checked = await el.isChecked();
      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));
+    if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(remainingMs(), 5000));
    await humanClick(raw, info.isInp, cfg);
  };

@@ -359,14 +375,16 @@ export function patchSingleElementHandle(
    }) => {
      const force = options?.force ?? false;
      const timeout = options?.timeout ?? 30000;
-      if (!force) await ensureActionableHandle(el, CHECKS_CHECK, timeout, force);
+      const deadline = Date.now() + timeout;
+      const remainingMs = () => Math.max(0, deadline - Date.now());
+      if (!force) await ensureActionableHandle(el, CHECKS_CHECK, remainingMs(), 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));
+      if (!force) await checkPointerEventsHandle(el, cursor.x, cursor.y, Math.min(remainingMs(), 5000));
      await humanClick(raw, info.isInp, cfg);
    };
  }
@@ -691,7 +691,12 @@ function patchSingleFrame(
  const origFrameTap = (frame as any).tap?.bind(frame);
  const origFrameDragAndDrop = frame.dragAndDrop.bind(frame);

-  const moveToFrameSelector = async (selector: string, options?: HumanActionOptions, inputBias = false) => {
+  const moveToFrameSelector = async (
+    selector: string,
+    options: HumanActionOptions | undefined,
+    inputBias: boolean,
+    remainingMs: () => number,
+  ) => {
    const callCfg = mergeConfig(cfg, options?.human_config ?? options);
    if (callCfg.idle_between_actions) {
      await humanIdle(raw, cursor.x, cursor.y, callCfg);
@@ -699,9 +704,9 @@ function patchSingleFrame(

    const locator = firstFrameLocator(frame, selector);
    if (typeof locator.scrollIntoViewIfNeeded === 'function') {
-      await locator.scrollIntoViewIfNeeded({ timeout: options?.timeout }).catch(() => undefined);
+      await locator.scrollIntoViewIfNeeded({ timeout: Math.max(1, remainingMs()) }).catch(() => undefined);
    }
-    const box = await locator.boundingBox({ timeout: options?.timeout ?? 30000 }).catch(() => null);
+    const box = await locator.boundingBox({ timeout: Math.max(1, remainingMs()) }).catch(() => null);
    if (!box) return null;

    const isInput = inputBias || await isFrameInputElement(frame, selector);
@@ -713,23 +718,32 @@ function patchSingleFrame(
  };

  const frameClick = async (selector: string, options?: HumanActionOptions) => {
-    const moved = await moveToFrameSelector(selector, options);
-    if (!moved) return origFrameClick(selector, options);
+    const timeout = options?.timeout ?? 30000;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    const moved = await moveToFrameSelector(selector, options, false, remainingMs);
+    if (!moved) return origFrameClick(selector, { ...options, timeout: Math.max(1, remainingMs()) });
    await humanClick(raw, moved.isInput, moved.callCfg);
  };

  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);
+    const timeout = options?.timeout ?? 30000;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    const moved = await moveToFrameSelector(selector, options, false, remainingMs);
+    if (!moved) return origFrameHover(selector, { ...options, timeout: Math.max(1, remainingMs()) });
  };

  (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);
+    const timeout = options?.timeout ?? 30000;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(0, deadline - Date.now());
+    const moved = await moveToFrameSelector(selector, options, false, remainingMs);
+    if (!moved) return origFrameDblclick(selector, { ...options, timeout: Math.max(1, remainingMs()) });
    await raw.down({ clickCount: 2 });
    await sleep(rand(30, 60));
    await raw.up({ clickCount: 2 });
@@ -820,8 +834,11 @@ function patchSingleFrame(
    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);
+    const timeout = options?.timeout ?? 30000;
+    const deadline = Date.now() + timeout;
+    const remainingMs = () => Math.max(1, deadline - Date.now());
+    const srcBox = await firstFrameLocator(frame, source).boundingBox({ timeout: remainingMs() }).catch(() => null);
+    const tgtBox = await firstFrameLocator(frame, target).boundingBox({ timeout: remainingMs() }).catch(() => null);

    if (srcBox && tgtBox) {
      const sx = srcBox.x + srcBox.width / 2;
@@ -837,7 +854,7 @@ function patchSingleFrame(
      await sleep(rand(80, 150));
      await originals.mouseUp();
    } else {
-      return origFrameDragAndDrop(source, target, options);
+      return origFrameDragAndDrop(source, target, { ...options, timeout: Math.max(1, remainingMs()) });
    }
  };
 }
@@ -16,7 +16,7 @@
 */

 // Launch functions (Playwright API)
-export { launch, launchContext, launchPersistentContext, buildLaunchOptions, humanizeBrowser } from "./playwright.js";
+export { launch, launchContext, launchPersistentContext, buildLaunchOptions, buildContextOptions, humanizeBrowser } from "./playwright.js";

 // Binary management
 export { ensureBinary, clearCache, binaryInfo, checkForUpdate } from "./download.js";
@@ -10,6 +10,7 @@ import { buildArgs } from "./args.js";
 import { ensureBinary } from "./download.js";
 import { resolveProxyConfig } from "./proxy.js";
 import { maybeResolveGeoip, resolveWebrtcArgs } from "./geoip.js";
+import { seedWidevineHint } from "./widevine.js";

 /** @internal Accept both timezone and timezoneId — either works, no warning. Exported for testing. */
 export function resolveTimezone<T extends { timezone?: string; timezoneId?: string }>(options: T): T {
@@ -44,6 +45,26 @@ function filterStealthCtxOptions(ctx?: BrowserContextOptions): Partial<BrowserCo
  return rest;
 }

+/**
+ * Build Playwright BrowserContext options for CloakBrowser without launching a browser
+ * or creating a context.
+ *
+ * Useful when integrating CloakBrowser with an existing Playwright Browser while
+ * keeping the wrapper's stealth-safe defaults for `newContext()`.
+ */
+export function buildContextOptions(
+  options: LaunchContextOptions = {}
+): BrowserContextOptions {
+  return {
+    // 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 } : {}),
+  } as BrowserContextOptions;
+}
+
 /**
 * Build Playwright launch options for CloakBrowser without starting Chromium.
 *
@@ -144,14 +165,7 @@ 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 } : {}),
-    });
+    context = await browser.newContext(buildContextOptions(options));
  } catch (err) {
    await browser.close();
    throw err;
@@ -214,6 +228,8 @@ export async function launchPersistentContext(
  }
  const args = buildArgs({ ...options, ...resolved, args: [...(resolvedArgs ?? []), ...proxyArgs] });

+  seedWidevineHint(options.userDataDir, binaryPath);
+
  // locale and timezone are set via binary flags (--lang, --fingerprint-timezone)
  // — NOT via Playwright context kwargs which use detectable CDP emulation.
  const context = await chromium.launchPersistentContext(options.userDataDir, {
@@ -222,12 +238,7 @@ 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 } : {}),
+    ...buildContextOptions(options),
    ...options.launchOptions,
  });

@@ -2,6 +2,8 @@
 * Shared proxy URL parsing for Playwright and Puppeteer wrappers.
 */

+import { getChromiumVersion, getPlatformTag, parseVersion } from "./config.js";
+
 export interface ParsedProxy {
  server: string;
  username?: string;
@@ -155,11 +157,106 @@ export function normalizeSocksStringUrl(urlStr: string): string {
  }
 }

+const HTTP_PROXY_INLINE_AUTH_MIN_VERSION = "146.0.7680.177.5";
+const HTTP_PROXY_INLINE_AUTH_PLATFORMS = new Set(["linux-x64", "windows-x64"]);
+
+export function supportsHttpProxyInlineAuth(): boolean {
+  try {
+    const tag = getPlatformTag();
+    if (!HTTP_PROXY_INLINE_AUTH_PLATFORMS.has(tag)) return false;
+    const current = parseVersion(getChromiumVersion());
+    const minimum = parseVersion(HTTP_PROXY_INLINE_AUTH_MIN_VERSION);
+    for (let i = 0; i < Math.max(current.length, minimum.length); i++) {
+      if ((current[i] ?? 0) > (minimum[i] ?? 0)) return true;
+      if ((current[i] ?? 0) < (minimum[i] ?? 0)) return false;
+    }
+    return true; // equal = supported
+  } catch {
+    return false;
+  }
+}
+
+function hasCredentials(proxy: string | ProxyDict): boolean {
+  if (typeof proxy === "string") return proxy.includes("@");
+  return !!proxy.username;
+}
+
+/**
+ * Reconstruct an HTTP(S) proxy URL with inline credentials from a proxy dict.
+ */
+export function reconstructHttpUrl(proxy: ProxyDict): string {
+  if (!proxy.username) return proxy.server;
+  const url = new URL(ensureProxyScheme(proxy.server));
+  url.username = encodeURIComponent(proxy.username);
+  if (proxy.password) url.password = encodeURIComponent(proxy.password);
+  return url.href.replace(/\/$/, "");
+}
+
+/**
+ * Re-encode credentials in an HTTP(S) proxy URL string for --proxy-server.
+ * Same pattern as normalizeSocksStringUrl.
+ */
+export function normalizeHttpStringUrl(urlStr: string): string {
+  const normalized = urlStr.includes("://") ? urlStr : `http://${urlStr}`;
+  const schemeMatch = normalized.match(/^([a-z][a-z0-9+\-.]*):\/\/(.*)$/i);
+  if (!schemeMatch) return normalized;
+  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 normalized;
+  const userinfo = authority.slice(0, atIdx);
+  const hostPart = authority.slice(atIdx + 1);
+  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 HTTP proxy URL, passing through unchanged: invalid port`);
+      return normalized;
+    }
+  }
+  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;
+    let userinfoPart: string;
+    if (encPass !== null) {
+      userinfoPart = `${encUser}:${encPass}@`;
+    } else if (encUser) {
+      userinfoPart = `${encUser}@`;
+    } else {
+      userinfoPart = "";
+    }
+    const result = `${scheme}://${userinfoPart}${hostAndRest}`;
+    const credsChanged = encUser !== rawUserEnc
+      || (hasPassword ? encPass !== rawPassEnc : false);
+    if (credsChanged) {
+      console.info(
+        "[cloakbrowser] Auto URL-encoded HTTP proxy credentials (special " +
+        "characters detected). Pre-encode the URL to suppress this notice.",
+      );
+    }
+    return result;
+  } catch (e) {
+    console.warn(`[cloakbrowser] Could not normalize HTTP proxy URL, passing through unchanged: ${(e as Error).message}`);
+    return normalized;
+  }
+}
+
 /**
 * Resolve proxy into Playwright option and/or Chrome args.
 *
- * Playwright rejects SOCKS5 proxies with credentials in its proxy dict,
- * so SOCKS5 is passed via --proxy-server Chrome arg instead.
+ * Proxies with credentials (SOCKS5 or HTTP/HTTPS on supported platforms) are
+ * passed via Chrome's --proxy-server flag with inline credentials, bypassing
+ * Playwright's CDP auth interceptor which breaks on some proxies (#182).
 */
 export function resolveProxyConfig(proxy: string | ProxyDict | undefined): ProxyConfig {
  if (!proxy) return { proxyArgs: [] };
@@ -177,7 +274,19 @@ export function resolveProxyConfig(proxy: string | ProxyDict | undefined): Proxy
    return { proxyArgs: args };
  }

-  // HTTP/HTTPS: use Playwright's proxy dict
+  // HTTP/HTTPS with credentials on supported platforms: bypass Playwright's
+  // CDP auth interceptor, use Chrome's preemptive Proxy-Authorization (#182).
+  if (hasCredentials(proxy) && supportsHttpProxyInlineAuth()) {
+    if (typeof proxy === "string") {
+      return { proxyArgs: [`--proxy-server=${normalizeHttpStringUrl(proxy)}`] };
+    }
+    const httpUrl = reconstructHttpUrl(proxy);
+    const args = [`--proxy-server=${httpUrl}`];
+    if (proxy.bypass) args.push(`--proxy-bypass-list=${proxy.bypass}`);
+    return { proxyArgs: args };
+  }
+
+  // HTTP/HTTPS without credentials (or unsupported platform): use Playwright's proxy dict
  if (typeof proxy === "string") {
    return { proxyOption: parseProxyUrl(proxy), proxyArgs: [] };
  }
@@ -9,8 +9,9 @@ import type { LaunchOptions } from "./types.js";
 import { IGNORE_DEFAULT_ARGS } from "./config.js";
 import { buildArgs } from "./args.js";
 import { ensureBinary } from "./download.js";
-import { isSocksProxy, parseProxyUrl, resolveProxyConfig } from "./proxy.js";
+import { isSocksProxy, normalizeHttpStringUrl, parseProxyUrl, reconstructHttpUrl, resolveProxyConfig, supportsHttpProxyInlineAuth } from "./proxy.js";
 import { maybeResolveGeoip, resolveWebrtcArgs } from "./geoip.js";
+import { seedWidevineHint } from "./widevine.js";

 /** Resolve binary path, geoip, webrtc, and build final Chrome args. */
 async function resolveArgs(options: LaunchOptions): Promise<{ binaryPath: string; args: string[] }> {
@@ -26,9 +27,9 @@ async function resolveArgs(options: LaunchOptions): Promise<{ binaryPath: string

 /**
 * Resolve proxy into Chrome CLI args and optional HTTP auth credentials.
- * SOCKS5: Chrome supports inline credentials natively (RFC 1929 auth).
- * HTTP: Chrome does NOT support inline credentials — strip them and
- * use page.authenticate() for Proxy-Authorization headers instead.
+ * SOCKS5: Chrome handles inline credentials natively (RFC 1929 auth).
+ * HTTP on supported platforms: inline credentials via --proxy-server.
+ * HTTP on unsupported platforms: strip credentials, use page.authenticate() fallback.
 */
 function resolveProxy(options: LaunchOptions, args: string[]): { username: string; password: string } | undefined {
  if (!options.proxy) return undefined;
@@ -39,6 +40,23 @@ function resolveProxy(options: LaunchOptions, args: string[]): { username: strin
    return undefined;
  }

+  // On supported platforms: pass full URL with inline creds to --proxy-server
+  if (supportsHttpProxyInlineAuth()) {
+    if (typeof options.proxy === "string") {
+      args.push(`--proxy-server=${normalizeHttpStringUrl(options.proxy)}`);
+      return undefined;
+    }
+    const url = options.proxy.username
+      ? reconstructHttpUrl(options.proxy)
+      : options.proxy.server;
+    args.push(`--proxy-server=${url}`);
+    if (options.proxy.bypass) {
+      args.push(`--proxy-bypass-list=${options.proxy.bypass}`);
+    }
+    return undefined;
+  }
+
+  // Unsupported platform: strip credentials, fall back to page.authenticate()
  if (typeof options.proxy === "string") {
    const { server, username, password } = parseProxyUrl(options.proxy);
    args.push(`--proxy-server=${server}`);
@@ -55,7 +73,7 @@ function resolveProxy(options: LaunchOptions, args: string[]): { username: strin
  return username ? { username, password: password ?? "" } : undefined;
 }

-/** Apply proxy auth monkey-patch and humanize behavioral patching. */
+/** Apply proxy auth fallback (unsupported platforms) and humanize patching. */
 async function applyPostLaunch(
  browser: Browser,
  options: LaunchOptions,
@@ -138,6 +156,8 @@ export async function launchPersistentContext(
  const { binaryPath, args } = await resolveArgs(options);
  const proxyAuth = resolveProxy(options, args);

+  seedWidevineHint(options.userDataDir, binaryPath);
+
  const browser = await puppeteer.default.launch({
    ...options.launchOptions,
    executablePath: binaryPath,
@@ -0,0 +1,111 @@
+/**
+ * Widevine CDM hint-file seeding for persistent contexts.
+ * Mirrors Python cloakbrowser/widevine.py.
+ *
+ * CloakBrowser's binary supports Widevine but ships no CDM (proprietary, can't
+ * redistribute). Users sideload it by copying a `WidevineCdm/` directory from a
+ * real Chrome install next to the binary (see issue #96). Chromium reads a
+ * "hint file" from the user-data-dir at early startup to register the CDM, but
+ * on a fresh profile it doesn't exist yet, and Playwright disables the component
+ * updater that would write it. This seeds the hint file before launch so a
+ * sideloaded CDM works on the first run. It never bundles, downloads, or copies
+ * the CDM — only writes the hint when a user-provided CDM is already present.
+ *
+ * Linux only: Chromium's hint-file mechanism is Linux/ChromeOS-specific.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const HINT_FILENAME = "latest-component-updated-widevine-cdm";
+
+/** True if `file` exists and is a regular file (mirrors Python's Path.is_file()). */
+function isFile(file: string): boolean {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Absolute, symlink-resolved path (mirrors Python's Path.resolve()). */
+function realPath(p: string): string {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+function seedingDisabled(): boolean {
+  const val = (process.env.CLOAKBROWSER_WIDEVINE ?? "").trim().toLowerCase();
+  return val === "0" || val === "false" || val === "off" || val === "no";
+}
+
+/**
+ * Locate a sideloaded Widevine CDM directory, or null if absent.
+ *
+ * Resolution:
+ *   - If CLOAKBROWSER_WIDEVINE_CDM is set, it is used exclusively (overrides
+ *     auto-detection). An invalid value (no `manifest.json`) skips seeding.
+ *   - Otherwise, `<dir of the chrome binary>/WidevineCdm` — where a user naturally
+ *     drops it, and where it lives for both downloaded and CLOAKBROWSER_BINARY_PATH binaries.
+ *
+ * A directory counts only if it contains `manifest.json`. The returned path is
+ * absolute and symlink-resolved (mirrors Python's Path.resolve()).
+ * @internal Exported for testing.
+ */
+export function resolveWidevineCdmDir(binaryPath: string): string | null {
+  const custom = process.env.CLOAKBROWSER_WIDEVINE_CDM;
+  // `!== undefined` (not truthiness): a present-but-empty env var is "set" and
+  // used exclusively — it resolves to an invalid path and skips seeding.
+  const cdmDir = custom !== undefined ? custom : path.join(path.dirname(binaryPath), "WidevineCdm");
+  return isFile(path.join(cdmDir, "manifest.json")) ? realPath(cdmDir) : null;
+}
+
+/**
+ * Write the Widevine CDM hint file into a persistent profile before launch.
+ * `binaryPath` is the resolved chrome executable; the CDM is looked for next to
+ * it. No-op on non-Linux, when disabled via CLOAKBROWSER_WIDEVINE, or when no
+ * sideloaded CDM is present. Never throws — a failure must not break launch.
+ */
+export function seedWidevineHint(userDataDir: string, binaryPath: string): void {
+  if (process.platform !== "linux") return;
+  if (seedingDisabled()) return;
+  // Empty userDataDir = Playwright's ephemeral profile (its own temp dir);
+  // a persistent hint can't be placed there, and "" would pollute the CWD.
+  if (!userDataDir) return;
+
+  // Everything below is best-effort and must never break the browser launch,
+  // so the whole body (resolution + write) is guarded.
+  try {
+    const cdmDir = resolveWidevineCdmDir(binaryPath);
+    if (cdmDir === null) {
+      if (process.env.CLOAKBROWSER_WIDEVINE_CDM !== undefined) {
+        console.warn(
+          "[cloakbrowser] CLOAKBROWSER_WIDEVINE_CDM is set but has no manifest.json; " +
+            "skipping Widevine hint seeding",
+        );
+      }
+      return;
+    }
+
+    const hintDir = path.join(userDataDir, "WidevineCdm");
+    fs.mkdirSync(hintDir, { recursive: true });
+    const hintFile = path.join(hintDir, HINT_FILENAME);
+    // cdmDir is already absolute/resolved.
+    const content = JSON.stringify({ Path: cdmDir });
+
+    try {
+      if (isFile(hintFile) && fs.readFileSync(hintFile, "utf-8") === content) {
+        return; // already seeded correctly
+      }
+    } catch {
+      console.warn("[cloakbrowser] Existing Widevine hint unreadable; rewriting");
+    }
+    fs.writeFileSync(hintFile, content);
+  } catch (e) {
+    // Best-effort: never break the launch, but surface the failure.
+    console.warn("[cloakbrowser] Failed to seed Widevine CDM hint file:", e);
+  }
+}
@@ -1479,3 +1479,123 @@ describe("el.scrollIntoViewIfNeeded humanization", () => {
    spy.mockRestore();
  });
 });
+
+
+// =========================================================================
+// Issue #307: frame.click timeout should not multiply
+// =========================================================================
+describe("frame.click timeout budget (#307)", () => {
+  it("total wait time should not exceed the specified timeout", async () => {
+    const { patchPage } = await import("../src/human/index.js");
+
+    const TIMEOUT_MS = 500;
+    const delay = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+    // Build a frame where the element does NOT exist:
+    // scrollIntoViewIfNeeded and boundingBox each wait until their
+    // individual timeout before failing, and origFrameClick does the same.
+    const frameLoc: any = {
+      boundingBox: vi.fn(async (opts?: { timeout?: number }) => {
+        await delay(opts?.timeout ?? 30000);
+        return null;
+      }),
+      scrollIntoViewIfNeeded: vi.fn(async (opts?: { timeout?: number }) => {
+        await delay(opts?.timeout ?? 30000);
+        throw new Error("timeout");
+      }),
+      evaluate: vi.fn(async () => ({ hit: true })),
+      isChecked: vi.fn(async () => false),
+    };
+    frameLoc.first = vi.fn(() => frameLoc);
+
+    const origClickFn = vi.fn(async (_sel: string, opts?: any) => {
+      await delay(opts?.timeout ?? 30000);
+      throw new Error("timeout");
+    });
+
+    const childFrame: any = {
+      click: origClickFn,
+      dblclick: vi.fn(async () => {}),
+      hover: vi.fn(async () => {}),
+      type: vi.fn(async () => {}),
+      fill: vi.fn(async () => {}),
+      check: vi.fn(async () => {}),
+      uncheck: vi.fn(async () => {}),
+      selectOption: vi.fn(async () => {}),
+      press: vi.fn(async () => {}),
+      pressSequentially: vi.fn(async () => {}),
+      tap: vi.fn(async () => {}),
+      clear: vi.fn(async () => {}),
+      dragAndDrop: vi.fn(async () => {}),
+      locator: vi.fn(() => frameLoc),
+      childFrames: vi.fn(() => []),
+    };
+
+    const mainFrame = {
+      ...buildMockFrame(),
+      childFrames: vi.fn(() => [childFrame]),
+    };
+
+    const page = buildMockPage({ mainFrameReturn: mainFrame });
+    const cfg = resolveConfig("default", {
+      mouse_min_steps: 1,
+      mouse_max_steps: 1,
+      idle_between_actions: false,
+    });
+    const cursor = { x: 0, y: 0, initialized: true };
+    patchPage(page as any, cfg, cursor as any);
+
+    const start = Date.now();
+    try {
+      await (childFrame as any).click("#does-not-exist", { timeout: TIMEOUT_MS });
+    } catch {
+      // expected — element doesn't exist
+    }
+    const elapsed = Date.now() - start;
+
+    // With the bug, elapsed ≈ 3 * TIMEOUT_MS (scrollIntoView + boundingBox + origClick).
+    // Fixed: elapsed should be ≈ 1 * TIMEOUT_MS (shared deadline).
+    // Allow 1.8x as upper bound to account for test overhead but catch the 3x bug.
+    expect(elapsed).toBeLessThan(TIMEOUT_MS * 1.8);
+  });
+});
+
+describe("pointer-events check fail-open", () => {
+  // When the check itself cannot run (evaluate / boundingBox throws -> result
+  // null), proceed with the click instead of blocking it until the timeout.
+  it("checkPointerEventsHandle returns promptly when evaluate throws", async () => {
+    const { checkPointerEventsHandle } = await import("../src/human/actionability.js");
+    const el = {
+      boundingBox: vi.fn().mockRejectedValue(new Error("stale handle")),
+      evaluate: vi.fn().mockRejectedValue(new Error("execution context destroyed")),
+    };
+    const start = Date.now();
+    await checkPointerEventsHandle(el as any, 100, 100, 2000); // must not throw
+    expect(Date.now() - start).toBeLessThan(500);
+  });
+
+  it("checkPointerEvents returns promptly when evaluate throws", async () => {
+    const { checkPointerEvents } = await import("../src/human/actionability.js");
+    const loc = {
+      first: () => loc,
+      boundingBox: vi.fn().mockRejectedValue(new Error("no element")),
+      evaluate: vi.fn().mockRejectedValue(new Error("no element")),
+    };
+    const page = { locator: vi.fn().mockReturnValue(loc) };
+    const start = Date.now();
+    await checkPointerEvents(page as any, "#x", 100, 100, null, 2000); // must not throw
+    expect(Date.now() - start).toBeLessThan(500);
+  });
+
+  it("checkPointerEventsHandle still throws when genuinely covered", async () => {
+    const { checkPointerEventsHandle, ElementNotReceivingEventsError } =
+      await import("../src/human/actionability.js");
+    const el = {
+      boundingBox: vi.fn().mockResolvedValue({ x: 0, y: 0, width: 10, height: 10 }),
+      evaluate: vi.fn().mockResolvedValue({ hit: false, covering: "DIV" }),
+    };
+    await expect(checkPointerEventsHandle(el as any, 5, 5, 200)).rejects.toBeInstanceOf(
+      ElementNotReceivingEventsError,
+    );
+  });
+});
@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
 import { binaryInfo } from "../src/download.js";
 import { DEFAULT_VIEWPORT, getChromiumVersion } from "../src/config.js";
+import * as config from "../src/config.js";

 describe("binaryInfo", () => {
  it("returns correct structure", () => {
@@ -39,33 +40,76 @@ describe("composable Playwright launch helpers", () => {
    }
  });

-  it("exports buildLaunchOptions and humanizeBrowser from the package entrypoint", async () => {
+  it("exports composable helpers from the package entrypoint", async () => {
    const entry = await import("../src/index.js");

    expect(entry.buildLaunchOptions).toBeTypeOf("function");
+    expect(entry.buildContextOptions).toBeTypeOf("function");
    expect(entry.humanizeBrowser).toBeTypeOf("function");
  });

+  it("buildContextOptions returns Playwright context options without launching a browser", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { buildContextOptions } = await import("../src/index.js");
+
+    const options = buildContextOptions({
+      userAgent: "Explicit/1.0",
+      viewport: { width: 1280, height: 720 },
+      colorScheme: "dark",
+      contextOptions: {
+        userAgent: "Context/9.9",
+        viewport: { width: 9999, height: 9999 },
+        colorScheme: "light",
+        storageState: "state.json",
+        locale: "de-DE",
+        timezoneId: "Europe/Berlin",
+      },
+    });
+
+    expect(options).toMatchObject({
+      userAgent: "Explicit/1.0",
+      viewport: { width: 1280, height: 720 },
+      colorScheme: "dark",
+      storageState: "state.json",
+    });
+    expect(options.locale).toBeUndefined();
+    expect(options.timezoneId).toBeUndefined();
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("buildContextOptions applies DEFAULT_VIEWPORT by default and allows null viewport", async () => {
+    const { buildContextOptions } = await import("../src/index.js");
+
+    expect(buildContextOptions().viewport).toEqual(DEFAULT_VIEWPORT);
+    expect(buildContextOptions({ viewport: null }).viewport).toBeNull();
+  });
+
  it("buildLaunchOptions returns Playwright options without launching a browser", async () => {
-    const { buildLaunchOptions } = await import("../src/index.js");
+    const freshConfig = await import("../src/config.js");
+    vi.spyOn(freshConfig, "getPlatformTag").mockReturnValue("darwin-arm64");
+    try {
+      const { buildLaunchOptions } = await import("../src/index.js");

-    const options = await buildLaunchOptions({
-      headless: false,
-      proxy: "http://user:pass@proxy.example:8080",
-      args: ["--custom-flag"],
-      launchOptions: { timeout: 1234 },
-    });
+      const options = await buildLaunchOptions({
+        headless: false,
+        proxy: "http://user:pass@proxy.example:8080",
+        args: ["--custom-flag"],
+        launchOptions: { timeout: 1234 },
+      });

-    expect(options.executablePath).toBe("/fake/chrome");
-    expect(options.headless).toBe(false);
-    expect(options.args).toContain("--custom-flag");
-    expect(options.ignoreDefaultArgs).toContain("--enable-automation");
-    expect(options.proxy).toEqual({
-      server: "http://proxy.example:8080",
-      username: "user",
-      password: "pass",
-    });
-    expect(options.timeout).toBe(1234);
+      expect(options.executablePath).toBe("/fake/chrome");
+      expect(options.headless).toBe(false);
+      expect(options.args).toContain("--custom-flag");
+      expect(options.ignoreDefaultArgs).toContain("--enable-automation");
+      expect(options.proxy).toEqual({
+        server: "http://proxy.example:8080",
+        username: "user",
+        password: "pass",
+      });
+      expect(options.timeout).toBe(1234);
+    } finally {
+      vi.restoreAllMocks();
+    }
  });

  it("humanizeBrowser patches an existing browser only when requested", async () => {
@@ -307,16 +351,22 @@ describe("launchPersistentContext (unit)", () => {
  });

  it("forwards proxy string", async () => {
-    const { launchPersistentContext } = await import("../src/playwright.js");
-    await launchPersistentContext({
-      userDataDir: "/tmp/profile",
-      proxy: "http://user:pass@proxy:8080",
-    });
+    const freshConfig = await import("../src/config.js");
+    vi.spyOn(freshConfig, "getPlatformTag").mockReturnValue("darwin-arm64");
+    try {
+      const { launchPersistentContext } = await import("../src/playwright.js");
+      await launchPersistentContext({
+        userDataDir: "/tmp/profile",
+        proxy: "http://user:pass@proxy:8080",
+      });

-    const args = mockChromium.launchPersistentContext.mock.calls[0][1];
-    expect(args.proxy.server).toBe("http://proxy:8080");
-    expect(args.proxy.username).toBe("user");
-    expect(args.proxy.password).toBe("pass");
+      const args = mockChromium.launchPersistentContext.mock.calls[0][1];
+      expect(args.proxy.server).toBe("http://proxy:8080");
+      expect(args.proxy.username).toBe("user");
+      expect(args.proxy.password).toBe("pass");
+    } finally {
+      vi.restoreAllMocks();
+    }
  });

  it("forwards userAgent and colorScheme", async () => {
@@ -1,5 +1,6 @@
 import { describe, it, expect, vi } from "vitest";
-import { parseProxyUrl, isSocksProxy, resolveProxyConfig } from "../src/proxy.js";
+import { parseProxyUrl, isSocksProxy, resolveProxyConfig, reconstructHttpUrl, normalizeHttpStringUrl } from "../src/proxy.js";
+import * as config from "../src/config.js";
 import type { LaunchOptions } from "../src/types.js";

 describe("parseProxyUrl", () => {
@@ -153,10 +154,15 @@ describe("resolveProxyConfig", () => {
    expect(proxyArgs).toEqual([]);
  });

-  it("returns playwright dict for http string", () => {
-    const { proxyOption, proxyArgs } = resolveProxyConfig("http://user:pass@proxy:8080");
-    expect(proxyOption).toEqual({ server: "http://proxy:8080", username: "user", password: "pass" });
-    expect(proxyArgs).toEqual([]);
+  it("returns playwright dict for http string on unsupported platform", () => {
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("darwin-arm64");
+    try {
+      const { proxyOption, proxyArgs } = resolveProxyConfig("http://user:pass@proxy:8080");
+      expect(proxyOption).toEqual({ server: "http://proxy:8080", username: "user", password: "pass" });
+      expect(proxyArgs).toEqual([]);
+    } finally {
+      vi.restoreAllMocks();
+    }
  });

  it("returns playwright dict for http dict", () => {
@@ -321,4 +327,96 @@ describe("resolveProxyConfig", () => {
      debugSpy.mockRestore();
    }
  });
+
+  // --- HTTP with credentials → --proxy-server (supported platform + version) ---
+
+  it("routes http string with creds through --proxy-server on linux-x64 v177.5", () => {
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("linux-x64");
+    vi.spyOn(config, "getChromiumVersion").mockReturnValue("146.0.7680.177.5");
+    try {
+      const { proxyOption, proxyArgs } = resolveProxyConfig("http://user:pass@proxy:8080");
+      expect(proxyOption).toBeUndefined();
+      expect(proxyArgs).toEqual(["--proxy-server=http://user:pass@proxy:8080"]);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("routes http dict with creds through --proxy-server on linux-x64 v177.5", () => {
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("linux-x64");
+    vi.spyOn(config, "getChromiumVersion").mockReturnValue("146.0.7680.177.5");
+    try {
+      const { proxyOption, proxyArgs } = resolveProxyConfig({
+        server: "http://proxy:8080",
+        username: "user",
+        password: "pass",
+      });
+      expect(proxyOption).toBeUndefined();
+      expect(proxyArgs).toEqual(["--proxy-server=http://user:pass@proxy:8080"]);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("includes bypass for http dict with creds on windows-x64 v177.5", () => {
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("windows-x64");
+    vi.spyOn(config, "getChromiumVersion").mockReturnValue("146.0.7680.177.5");
+    try {
+      const { proxyArgs } = resolveProxyConfig({
+        server: "http://proxy:8080",
+        username: "user",
+        password: "pass",
+        bypass: ".google.com",
+      });
+      expect(proxyArgs).toContain("--proxy-server=http://user:pass@proxy:8080");
+      expect(proxyArgs).toContain("--proxy-bypass-list=.google.com");
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("encodes special chars in http proxy password on supported platform v177.5", () => {
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("linux-x64");
+    vi.spyOn(config, "getChromiumVersion").mockReturnValue("146.0.7680.177.5");
+    try {
+      const { proxyArgs } = resolveProxyConfig("http://user:pass=123@proxy:8080");
+      expect(proxyArgs).toEqual(["--proxy-server=http://user:pass%3D123@proxy:8080"]);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("falls back on linux-x64 with old version (pre-inline-auth)", () => {
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("linux-x64");
+    vi.spyOn(config, "getChromiumVersion").mockReturnValue("146.0.7680.177.3");
+    try {
+      const { proxyOption, proxyArgs } = resolveProxyConfig("http://user:pass@proxy:8080");
+      expect(proxyOption).toBeDefined();
+      expect(proxyArgs).toEqual([]);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("falls back to playwright dict for http with creds on darwin-arm64", () => {
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("darwin-arm64");
+    try {
+      const { proxyOption, proxyArgs } = resolveProxyConfig("http://user:pass@proxy:8080");
+      expect(proxyOption).toEqual({ server: "http://proxy:8080", username: "user", password: "pass" });
+      expect(proxyArgs).toEqual([]);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("falls back to playwright dict for http with creds on linux-arm64", () => {
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("linux-arm64");
+    try {
+      const { proxyOption, proxyArgs } = resolveProxyConfig("http://user:pass@proxy:8080");
+      expect(proxyOption).toBeDefined();
+      expect(proxyArgs).toEqual([]);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
 });
@@ -84,16 +84,39 @@ describe("puppeteer launch", () => {
    expect(callArgs.args).toContain("--proxy-bypass-list=.google.com,localhost");
  });

-  it("monkey-patches newPage for proxy auth", async () => {
-    const { launch } = await import("../src/puppeteer.js");
-    const browser = await launch({ proxy: "http://user:pass@proxy:8080" });
+  it("uses page.authenticate fallback for http proxy on unsupported platform", async () => {
+    const config = await import("../src/config.js");
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("darwin-arm64");
+    try {
+      const { launch } = await import("../src/puppeteer.js");
+      const browser = await launch({ proxy: "http://user:pass@proxy:8080" });

-    // newPage should auto-authenticate
-    const page = await browser.newPage();
-    expect(page.authenticate).toHaveBeenCalledWith({
-      username: "user",
-      password: "pass",
-    });
+      const page = await browser.newPage();
+      expect(page.authenticate).toHaveBeenCalledWith({
+        username: "user",
+        password: "pass",
+      });
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("passes inline creds via --proxy-server on supported platform (no page.authenticate)", async () => {
+    const config = await import("../src/config.js");
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("linux-x64");
+    vi.spyOn(config, "getChromiumVersion").mockReturnValue("146.0.7680.177.5");
+    try {
+      const { launch } = await import("../src/puppeteer.js");
+      const browser = await launch({ proxy: "http://user:pass@proxy:8080" });
+
+      const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+      expect(callArgs.args).toContain("--proxy-server=http://user:pass@proxy:8080");
+
+      const page = await browser.newPage();
+      expect(page.authenticate).not.toHaveBeenCalled();
+    } finally {
+      vi.restoreAllMocks();
+    }
  });

  it("injects timezone and locale as binary flags", async () => {
@@ -189,18 +212,24 @@ describe("puppeteer launchPersistentContext", () => {
    expect(callArgs.args.some((a: string) => a.startsWith("--fingerprint="))).toBe(true);
  });

-  it("handles proxy auth with persistent context", async () => {
-    const { launchPersistentContext } = await import("../src/puppeteer.js");
-    const browser = await launchPersistentContext({
-      userDataDir: "./my-profile",
-      proxy: "http://user:pass@proxy:8080",
-    });
+  it("uses page.authenticate fallback for http proxy in persistent context on unsupported platform", async () => {
+    const config = await import("../src/config.js");
+    vi.spyOn(config, "getPlatformTag").mockReturnValue("darwin-arm64");
+    try {
+      const { launchPersistentContext } = await import("../src/puppeteer.js");
+      const browser = await launchPersistentContext({
+        userDataDir: "./my-profile",
+        proxy: "http://user:pass@proxy:8080",
+      });

-    const page = await browser.newPage();
-    expect(page.authenticate).toHaveBeenCalledWith({
-      username: "user",
-      password: "pass",
-    });
+      const page = await browser.newPage();
+      expect(page.authenticate).toHaveBeenCalledWith({
+        username: "user",
+        password: "pass",
+      });
+    } finally {
+      vi.restoreAllMocks();
+    }
  });

  it("keeps SOCKS5 credentials in --proxy-server URL", async () => {
@@ -418,7 +418,7 @@ describe("humanType mixed text with CDP", () => {
  });

  it("password-like text 'SecurePass!123' uses CDP for '!'", async () => {
-    const cfg = resolveConfig("default", { mistype_chance: 0 });
+    const cfg = resolveConfig("default", { mistype_chance: 0, typing_delay: 0 });
    const { raw } = buildRawKeyboard();
    const page = buildMockPage();
    const cdpCalls: Array<[string, any]> = [];
@@ -0,0 +1,57 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+
+// Assert the persistent-context launchers actually invoke seedWidevineHint,
+// so accidental removal of the wiring fails CI (parity with the Python
+// test_persistent_context_seeds_widevine tests).
+
+vi.mock("../src/widevine.js", () => ({
+  seedWidevineHint: vi.fn(),
+  resolveWidevineCdmDir: vi.fn(),
+}));
+vi.mock("../src/download.js", () => ({
+  ensureBinary: vi.fn().mockResolvedValue("/fake/chrome"),
+}));
+vi.mock("../src/geoip.js", () => ({
+  resolveProxyGeo: vi.fn().mockResolvedValue({ timezone: null, locale: null }),
+  maybeResolveGeoip: vi.fn().mockResolvedValue({}),
+  resolveWebrtcArgs: vi.fn().mockImplementation((opts: any) => Promise.resolve(opts.args)),
+}));
+vi.mock("playwright-core", () => ({ chromium: { launchPersistentContext: vi.fn() } }));
+vi.mock("puppeteer-core", () => ({ default: { launch: vi.fn() } }));
+
+describe("persistent context seeds Widevine (integration)", () => {
+  beforeEach(() => {
+    delete process.env.CLOAKBROWSER_BINARY_PATH;
+  });
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("Playwright launchPersistentContext seeds with (userDataDir, binaryPath)", async () => {
+    const pw = await import("playwright-core");
+    vi.mocked(pw.chromium.launchPersistentContext).mockResolvedValue({
+      close: vi.fn(),
+      pages: () => [],
+    } as any);
+
+    const { seedWidevineHint } = await import("../src/widevine.js");
+    const { launchPersistentContext } = await import("../src/playwright.js");
+    await launchPersistentContext({ userDataDir: "/tmp/profile" });
+
+    expect(seedWidevineHint).toHaveBeenCalledWith("/tmp/profile", "/fake/chrome");
+  });
+
+  it("Puppeteer launchPersistentContext seeds with (userDataDir, binaryPath)", async () => {
+    const pptr = await import("puppeteer-core");
+    vi.mocked(pptr.default.launch).mockResolvedValue({
+      newPage: vi.fn().mockResolvedValue({ authenticate: vi.fn() }),
+      close: vi.fn(),
+    } as any);
+
+    const { seedWidevineHint } = await import("../src/widevine.js");
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({ userDataDir: "/tmp/profile" });
+
+    expect(seedWidevineHint).toHaveBeenCalledWith("/tmp/profile", "/fake/chrome");
+  });
+});
@@ -0,0 +1,160 @@
+import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveWidevineCdmDir, seedWidevineHint } from "../src/widevine.js";
+
+const HINT = "WidevineCdm/latest-component-updated-widevine-cdm";
+const tempDirs: string[] = [];
+const origPlatform = process.platform;
+
+function tmpDir(prefix: string): string {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(d);
+  return d;
+}
+
+function makeCdm(dir: string): string {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "manifest.json"), '{"version":"4.10.3050.0"}');
+  return dir;
+}
+
+/** A fake chrome binary path inside its own dir. */
+function fakeBinary(): string {
+  const bdir = path.join(tmpDir("cloak-bin-"), "bin");
+  fs.mkdirSync(bdir, { recursive: true });
+  return path.join(bdir, "chrome");
+}
+
+function setPlatform(value: string) {
+  Object.defineProperty(process, "platform", { value, configurable: true });
+}
+
+beforeEach(() => {
+  setPlatform("linux"); // seeding is Linux-only; default to Linux in tests
+  delete process.env.CLOAKBROWSER_WIDEVINE;
+  delete process.env.CLOAKBROWSER_WIDEVINE_CDM;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  Object.defineProperty(process, "platform", { value: origPlatform, configurable: true });
+  delete process.env.CLOAKBROWSER_WIDEVINE;
+  delete process.env.CLOAKBROWSER_WIDEVINE_CDM;
+  for (const dir of tempDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe("resolveWidevineCdmDir", () => {
+  it("returns env-var dir when it has manifest.json", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    expect(resolveWidevineCdmDir(fakeBinary())).toBe(fs.realpathSync(cdm));
+  });
+
+  it("returns null when dir lacks manifest.json", () => {
+    const bogus = path.join(tmpDir("cloak-wv-"), "WidevineCdm");
+    fs.mkdirSync(bogus, { recursive: true });
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = bogus;
+    expect(resolveWidevineCdmDir(fakeBinary())).toBeNull();
+  });
+
+  it("falls back to <binary dir>/WidevineCdm", () => {
+    const binary = fakeBinary();
+    expect(resolveWidevineCdmDir(binary)).toBeNull(); // no CDM yet
+    const cdm = makeCdm(path.join(path.dirname(binary), "WidevineCdm"));
+    expect(resolveWidevineCdmDir(binary)).toBe(fs.realpathSync(cdm));
+  });
+
+  it("env var is exclusive — invalid env skips, no fallback to binary dir", () => {
+    const binary = fakeBinary();
+    makeCdm(path.join(path.dirname(binary), "WidevineCdm")); // valid CDM next to binary
+    const bogus = path.join(tmpDir("cloak-wv-"), "bogus");
+    fs.mkdirSync(bogus, { recursive: true }); // set but no manifest.json
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = bogus;
+    expect(resolveWidevineCdmDir(binary)).toBeNull();
+  });
+
+  it("empty env var is exclusive — no fallback to binary dir", () => {
+    const binary = fakeBinary();
+    makeCdm(path.join(path.dirname(binary), "WidevineCdm")); // valid CDM next to binary
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = ""; // set but empty
+    expect(resolveWidevineCdmDir(binary)).toBeNull();
+  });
+});
+
+describe("seedWidevineHint", () => {
+  it("writes the hint file with the absolute CDM path", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+
+    seedWidevineHint(profile, fakeBinary());
+
+    const hint = path.join(profile, HINT);
+    expect(fs.existsSync(hint)).toBe(true);
+    expect(JSON.parse(fs.readFileSync(hint, "utf-8")).Path).toBe(fs.realpathSync(cdm));
+  });
+
+  it("no-ops when no CDM present", () => {
+    const profile = tmpDir("cloak-prof-");
+    seedWidevineHint(profile, fakeBinary());
+    expect(fs.existsSync(path.join(profile, HINT))).toBe(false);
+  });
+
+  it("kill switch CLOAKBROWSER_WIDEVINE=0 disables seeding", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    process.env.CLOAKBROWSER_WIDEVINE = "0";
+    const profile = tmpDir("cloak-prof-");
+    seedWidevineHint(profile, fakeBinary());
+    expect(fs.existsSync(path.join(profile, HINT))).toBe(false);
+  });
+
+  it("is idempotent", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+    seedWidevineHint(profile, fakeBinary());
+    seedWidevineHint(profile, fakeBinary());
+    expect(JSON.parse(fs.readFileSync(path.join(profile, HINT), "utf-8")).Path).toBe(
+      fs.realpathSync(cdm),
+    );
+  });
+
+  it("no-ops on non-Linux", () => {
+    setPlatform("win32");
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+    seedWidevineHint(profile, fakeBinary());
+    expect(fs.existsSync(path.join(profile, HINT))).toBe(false);
+  });
+
+  it("skips empty userDataDir (no CWD pollution)", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    seedWidevineHint("", fakeBinary());
+    expect(fs.existsSync(path.join(process.cwd(), "WidevineCdm"))).toBe(false);
+  });
+
+  it("never throws on write failure", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+    // Block mkdir of <profile>/WidevineCdm by occupying that path with a file.
+    fs.writeFileSync(path.join(profile, "WidevineCdm"), "not a dir");
+    expect(() => seedWidevineHint(profile, fakeBinary())).not.toThrow();
+  });
+
+  it("rewrites a mismatched existing hint", () => {
+    const cdm = makeCdm(path.join(tmpDir("cloak-wv-"), "WidevineCdm"));
+    process.env.CLOAKBROWSER_WIDEVINE_CDM = cdm;
+    const profile = tmpDir("cloak-prof-");
+    const hint = path.join(profile, HINT);
+    fs.mkdirSync(path.dirname(hint), { recursive: true });
+    fs.writeFileSync(hint, '{"Path":"/stale/path"}');
+    seedWidevineHint(profile, fakeBinary());
+    expect(JSON.parse(fs.readFileSync(hint, "utf-8")).Path).toBe(fs.realpathSync(cdm));
+  });
+});
@@ -3,6 +3,7 @@
 import asyncio
 import importlib.machinery
 import importlib.util
+import json
 import sys
 from pathlib import Path
 from types import SimpleNamespace
@@ -24,6 +25,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
+_external_host = _mod._external_host
+_ws_scheme = _mod._ws_scheme
 SAFE_SEED_RE = _mod.SAFE_SEED_RE
 RESERVED_SEEDS = _mod.RESERVED_SEEDS

@@ -90,6 +93,7 @@ class TestParseCliArgs:
        assert config["port"] == 9222
        assert config["headless"] is True
        assert config["data_dir"] is not None
+        assert config["idle_timeout"] == 0.0
        assert passthrough == []

    def test_custom_port(self):
@@ -128,6 +132,31 @@ class TestParseCliArgs:
        _, passthrough = parse_cli_args(["--data-dir=/tmp/test"])
        assert not any(a.startswith("--data-dir=") for a in passthrough)

+    def test_idle_timeout_not_in_passthrough(self):
+        config, passthrough = parse_cli_args(["--idle-timeout=30", "--no-sandbox"])
+        assert config["idle_timeout"] == 30.0
+        assert "--idle-timeout=30" not in passthrough
+        assert "--no-sandbox" in passthrough
+
+    @pytest.mark.parametrize("value", ["0", "off", "false", "none", "disabled"])
+    def test_idle_timeout_disabled_values(self, value):
+        config, _ = parse_cli_args([f"--idle-timeout={value}"])
+        assert config["idle_timeout"] == 0.0
+
+    def test_idle_timeout_env_default(self, monkeypatch):
+        monkeypatch.setenv("CLOAKSERVE_IDLE_TIMEOUT", "2.5")
+        config, _ = parse_cli_args([])
+        assert config["idle_timeout"] == 2.5
+
+    def test_idle_timeout_cli_overrides_env(self, monkeypatch):
+        monkeypatch.setenv("CLOAKSERVE_IDLE_TIMEOUT", "2.5")
+        config, _ = parse_cli_args(["--idle-timeout=9"])
+        assert config["idle_timeout"] == 9.0
+
+    def test_idle_timeout_rejects_negative_values(self):
+        with pytest.raises(ValueError):
+            parse_cli_args(["--idle-timeout=-1"])
+
    @patch("os.path.exists", return_value=True)
    def test_default_data_dir_docker(self, _mock):
        assert _default_data_dir() == "/tmp/cloakserve"
@@ -138,6 +167,141 @@ class TestParseCliArgs:
        assert result.endswith(".cloakbrowser/cloakserve")


+# ---------------------------------------------------------------------------
+# External host detection
+# ---------------------------------------------------------------------------
+
+
+class TestExternalHost:
+    """Test public host selection for rewritten CDP WebSocket URLs."""
+
+    class _Request:
+        def __init__(self, headers, port=9222, scheme="http", query_string=""):
+            self.headers = headers
+            self.app = {"port": port}
+            self.scheme = scheme
+            self.query_string = query_string
+
+    def test_forwarded_host_overrides_internal_host(self):
+        request = self._Request({
+            "Host": "localhost:8080",
+            "X-Forwarded-Host": "cdp.example.com:443",
+        })
+        assert _external_host(request) == "cdp.example.com:443"
+
+    def test_forwarded_host_uses_first_value(self):
+        request = self._Request({
+            "Host": "internal:9222",
+            "X-Forwarded-Host": "public.example.com, internal:9222",
+        })
+        assert _external_host(request) == "public.example.com"
+
+    def test_blank_forwarded_host_falls_back_to_host_header(self):
+        request = self._Request({
+            "Host": "internal:9222",
+            "X-Forwarded-Host": "   ",
+        })
+        assert _external_host(request) == "internal:9222"
+
+    def test_falls_back_to_host_header(self):
+        request = self._Request({"Host": "localhost:9222"})
+        assert _external_host(request) == "localhost:9222"
+
+    def test_falls_back_to_app_port_without_host_header(self):
+        request = self._Request({}, port=9333)
+        assert _external_host(request) == "localhost:9333"
+
+    def test_forwarded_proto_selects_wss(self):
+        request = self._Request({"X-Forwarded-Proto": "https"}, scheme="http")
+        assert _ws_scheme(request) == "wss"
+
+    def test_forwarded_proto_uses_first_value(self):
+        request = self._Request({"X-Forwarded-Proto": "https, http"}, scheme="http")
+        assert _ws_scheme(request) == "wss"
+
+
+class TestHandlerURLRewriting:
+    """Verify handlers rewrite CDP WebSocket URLs to the public cloakserve endpoint."""
+
+    class _Request:
+        def __init__(self, headers, query_string="fingerprint=seed1", port=9222, scheme="http"):
+            self.headers = headers
+            self.query_string = query_string
+            self.scheme = scheme
+            self.app = {"port": port, "pool": self._Pool()}
+
+        class _Pool:
+            async def get_or_launch(self, **_kwargs):
+                return SimpleNamespace(cdp_port=5100)
+
+    class _FakeResponse:
+        def __init__(self, data):
+            self._data = data
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *_exc):
+            return None
+
+        async def json(self):
+            return self._data
+
+    class _FakeSession:
+        def __init__(self, data):
+            self._data = data
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *_exc):
+            return None
+
+        def get(self, *_args, **_kwargs):
+            return TestHandlerURLRewriting._FakeResponse(self._data)
+
+    def _patch_session(self, monkeypatch, data):
+        monkeypatch.setattr(
+            _mod.aiohttp,
+            "ClientSession",
+            lambda *_args, **_kwargs: self._FakeSession(data),
+        )
+
+    def test_json_version_uses_forwarded_host_and_proto(self, monkeypatch):
+        self._patch_session(monkeypatch, {
+            "webSocketDebuggerUrl": "ws://127.0.0.1:5100/devtools/browser/browser-guid",
+        })
+        request = self._Request({
+            "Host": "internal:9222",
+            "X-Forwarded-Host": "cdp.example.com",
+            "X-Forwarded-Proto": "https",
+        })
+
+        response = asyncio.run(_mod.handle_json_version(request))
+        payload = json.loads(response.text)
+
+        assert payload["webSocketDebuggerUrl"] == (
+            "wss://cdp.example.com/fingerprint/seed1/devtools/browser/browser-guid"
+        )
+
+    def test_json_list_uses_forwarded_host_and_proto(self, monkeypatch):
+        self._patch_session(monkeypatch, [{
+            "webSocketDebuggerUrl": "ws://127.0.0.1:5100/devtools/page/page-guid",
+        }])
+        request = self._Request({
+            "Host": "internal:9222",
+            "X-Forwarded-Host": "cdp.example.com",
+            "X-Forwarded-Proto": "https",
+        })
+
+        response = asyncio.run(_mod.handle_json_list(request))
+        payload = json.loads(response.text)
+
+        assert payload[0]["webSocketDebuggerUrl"] == (
+            "wss://cdp.example.com/fingerprint/seed1/devtools/page/page-guid"
+        )
+
+
 # ---------------------------------------------------------------------------
 # URL rewriting logic (pure string manipulation, extracted from handlers)
 # ---------------------------------------------------------------------------
@@ -293,12 +457,21 @@ class TestHandlerURLRewriting:
 class TestConnectionTracking:
    """Test ChromePool.connect() / disconnect() without real Chrome."""

-    def _make_pool(self):
+    def _make_pool(self, idle_timeout: float = 0.0):
        return ChromePool(
            binary="/fake/chrome",
            global_args=[],
            headless=True,
            data_dir="/tmp/test-cloakserve",
+            idle_timeout=idle_timeout,
+        )
+
+    def _track_process(self, pool, seed="seed1"):
+        pool._processes[seed] = SimpleNamespace()
+
+    def _track_live_process(self, pool, seed="seed1"):
+        pool._processes[seed] = SimpleNamespace(
+            process=SimpleNamespace(poll=lambda: None),
        )

    def test_connect_increments(self):
@@ -335,6 +508,83 @@ class TestConnectionTracking:
        assert pool._connections["a"] == 1
        assert pool._connections["b"] == 1

+    def test_idle_cleanup_disabled_by_default(self):
+        async def run():
+            pool = self._make_pool()
+            self._track_process(pool)
+
+            pool.connect("seed1")
+            pool.disconnect("seed1")
+
+            await asyncio.sleep(0)
+            assert pool._idle_tasks == {}
+
+        asyncio.run(run())
+
+    def test_disconnect_to_zero_schedules_idle_cleanup(self):
+        async def run():
+            pool = self._make_pool(idle_timeout=0.01)
+            self._track_process(pool)
+            cleaned = []
+
+            async def fake_cleanup(seed):
+                cleaned.append(seed)
+                pool._processes.pop(seed, None)
+
+            pool._cleanup_process = fake_cleanup
+            pool.connect("seed1")
+            pool.disconnect("seed1")
+
+            assert "seed1" in pool._idle_tasks
+            await asyncio.sleep(0.05)
+            assert cleaned == ["seed1"]
+            assert "seed1" not in pool._idle_tasks
+
+        asyncio.run(run())
+
+    def test_reconnect_cancels_pending_idle_cleanup(self):
+        async def run():
+            pool = self._make_pool(idle_timeout=0.03)
+            self._track_process(pool)
+            cleaned = []
+
+            async def fake_cleanup(seed):
+                cleaned.append(seed)
+                pool._processes.pop(seed, None)
+
+            pool._cleanup_process = fake_cleanup
+            pool.connect("seed1")
+            pool.disconnect("seed1")
+            assert "seed1" in pool._idle_tasks
+
+            pool.connect("seed1")
+            await asyncio.sleep(0.06)
+
+            assert cleaned == []
+            assert pool._connections["seed1"] == 1
+            assert "seed1" not in pool._idle_tasks
+
+        asyncio.run(run())
+
+    def test_discovery_refreshes_pending_idle_cleanup(self):
+        async def run():
+            pool = self._make_pool(idle_timeout=1.0)
+            self._track_live_process(pool)
+
+            pool.connect("seed1")
+            pool.disconnect("seed1")
+            first_task = pool._idle_tasks["seed1"]
+
+            await pool.get_or_launch("seed1")
+            second_task = pool._idle_tasks["seed1"]
+
+            assert second_task is not first_task
+            pool._cancel_idle_cleanup("seed1")
+            await asyncio.sleep(0)
+            assert "seed1" not in pool._idle_tasks
+
+        asyncio.run(run())
+

 # ---------------------------------------------------------------------------
 # Seed validation (CVE fix — path traversal via fingerprint param)
@@ -708,7 +708,7 @@ class TestBrowserBotDetection:
        time.sleep(0.3)
        page.locator('#password').fill('SecurePass!123')
        time.sleep(0.5)
-        page.locator('button[type="submit"]').click()
+        page.locator('#loginForm button[type="submit"]').click()
        time.sleep(5)
        body = page.locator('body').text_content()
        assert '"superHumanSpeed": true' not in body
@@ -725,7 +725,7 @@ class TestBrowserBotDetection:
        t0 = time.time()
        page.locator('#email').fill('test@example.com')
        page.locator('#password').fill('MyPassword!99')
-        page.locator('button[type="submit"]').click()
+        page.locator('#loginForm button[type="submit"]').click()
        elapsed_ms = int((time.time() - t0) * 1000)
        time.sleep(3)
        assert elapsed_ms > 3000
@@ -1828,6 +1828,118 @@ class TestScrollIntoViewIfNeeded:
        assert cursor.x == 200 and cursor.y == 200


+# =========================================================================
+# Issue #307: frame/page click timeout should not multiply
+# =========================================================================
+
+class TestTimeoutBudget307:
+    """Verify timeout budget is shared across sequential operations."""
+
+    def test_page_click_total_time_within_budget(self):
+        """page.click on a missing element should not exceed ~1x the timeout."""
+        import cloakbrowser.human as h
+        from cloakbrowser.human import _CursorState
+        from cloakbrowser.human.config import resolve_config
+        from unittest.mock import MagicMock, patch
+
+        TIMEOUT_MS = 500
+        cfg = resolve_config("default", {"idle_between_actions": False})
+        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 = []
+
+        loc = MagicMock()
+        loc.wait_for = MagicMock(side_effect=lambda **kw: time.sleep(kw.get("timeout", 30000) / 1000.0))
+        loc.is_visible = MagicMock(return_value=False)
+        loc.first = loc
+        page.locator = MagicMock(return_value=loc)
+
+        h.patch_page(page, cfg, cursor)
+
+        start = time.monotonic()
+        try:
+            page.click("#does-not-exist", timeout=TIMEOUT_MS)
+        except Exception:
+            pass
+        elapsed_ms = (time.monotonic() - start) * 1000
+
+        assert elapsed_ms < TIMEOUT_MS * 1.8, (
+            f"expected <{TIMEOUT_MS * 1.8}ms, got {elapsed_ms:.0f}ms"
+        )
+
+
+class TestPointerEventsFailOpen:
+    """The pointer-events check must fail open: when it cannot run (evaluate /
+    bounding_box throws -> result None), proceed with the click instead of
+    blocking it until the timeout expires."""
+
+    def test_handle_failopen_returns_on_evaluate_error(self):
+        from cloakbrowser.human.actionability import check_pointer_events_handle
+        el = MagicMock()
+        el.bounding_box = MagicMock(side_effect=Exception("stale handle"))
+        el.evaluate = MagicMock(side_effect=Exception("execution context destroyed"))
+        start = time.monotonic()
+        check_pointer_events_handle(MagicMock(), el, 100, 100, timeout=2000)  # must not raise
+        elapsed_ms = (time.monotonic() - start) * 1000
+        assert elapsed_ms < 500, f"fail-open should return promptly, took {elapsed_ms:.0f}ms"
+
+    def test_locator_failopen_returns_on_evaluate_error(self):
+        from cloakbrowser.human.actionability import check_pointer_events
+        page = MagicMock()
+        loc = MagicMock()
+        loc.first = loc
+        loc.bounding_box = MagicMock(side_effect=Exception("no element"))
+        loc.evaluate = MagicMock(side_effect=Exception("no element"))
+        page.locator = MagicMock(return_value=loc)
+        start = time.monotonic()
+        check_pointer_events(page, "#x", 100, 100, timeout=2000)  # must not raise
+        elapsed_ms = (time.monotonic() - start) * 1000
+        assert elapsed_ms < 500, f"fail-open should return promptly, took {elapsed_ms:.0f}ms"
+
+    def test_handle_still_raises_when_covered(self):
+        """A genuine 'covered' result (not None) must still raise — fail-open
+        only applies when the check could not be determined."""
+        from cloakbrowser.human.actionability import (
+            check_pointer_events_handle, ElementNotReceivingEventsError,
+        )
+        el = MagicMock()
+        el.bounding_box = MagicMock(return_value={"x": 0, "y": 0, "width": 10, "height": 10})
+        el.evaluate = MagicMock(return_value={"hit": False, "covering": "DIV"})
+        with pytest.raises(ElementNotReceivingEventsError):
+            check_pointer_events_handle(MagicMock(), el, 5, 5, timeout=200)
+
+    def test_async_handle_failopen_returns_on_evaluate_error(self):
+        from cloakbrowser.human.actionability_async import async_check_pointer_events_handle
+        from unittest.mock import AsyncMock
+        el = MagicMock()
+        el.bounding_box = AsyncMock(side_effect=Exception("stale handle"))
+        el.evaluate = AsyncMock(side_effect=Exception("execution context destroyed"))
+        start = time.monotonic()
+        asyncio.run(async_check_pointer_events_handle(MagicMock(), el, 100, 100, timeout=2000))
+        elapsed_ms = (time.monotonic() - start) * 1000
+        assert elapsed_ms < 500, f"fail-open should return promptly, took {elapsed_ms:.0f}ms"
+
+
 # =========================================================================
 # Direct runner (backwards compat)
 # =========================================================================
@@ -165,10 +165,11 @@ def test_persistent_context_close_stops_pw(_mock_geoip, _mock_bin):
    pw.stop.assert_called_once()


+@patch("cloakbrowser.config.get_platform_tag", return_value="darwin-arm64")
@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None, None))
-def test_persistent_context_proxy_string(_mock_geoip, _mock_bin):
-    """Proxy string parsed and passed."""
+def test_persistent_context_proxy_string(_mock_geoip, _mock_bin, _mock_platform):
+    """Proxy string parsed and passed (unsupported platform → Playwright dict)."""
    pw_cm, pw, context = _make_mock_pw_and_context()

    with patch("playwright.sync_api.sync_playwright", return_value=pw_cm):
@@ -257,3 +258,32 @@ async def test_persistent_context_async_timezone_id_alias(_mock_bin):
    call_kwargs = pw.chromium.launch_persistent_context.call_args[1]
    assert "--fingerprint-timezone=Europe/Paris" in call_kwargs["args"]
    assert "timezone_id" not in call_kwargs
+
+
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None, None))
+@patch("cloakbrowser.browser.seed_widevine_hint")
+def test_persistent_context_seeds_widevine(_mock_seed, _mock_geoip, _mock_bin):
+    """Sync persistent launch seeds the Widevine hint with the profile path."""
+    pw_cm, pw, context = _make_mock_pw_and_context()
+
+    with patch("playwright.sync_api.sync_playwright", return_value=pw_cm):
+        from cloakbrowser.browser import launch_persistent_context
+        launch_persistent_context("/tmp/profile")
+
+    _mock_seed.assert_called_once_with("/tmp/profile", "/fake/chrome")
+
+
+@pytest.mark.asyncio
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None, None))
+@patch("cloakbrowser.browser.seed_widevine_hint")
+async def test_persistent_context_async_seeds_widevine(_mock_seed, _mock_geoip, _mock_bin):
+    """Async persistent launch seeds the Widevine hint with the profile path."""
+    pw_cm, pw, context = _make_mock_async_pw_and_context()
+
+    with patch("playwright.async_api.async_playwright", return_value=pw_cm):
+        from cloakbrowser.browser import launch_persistent_context_async
+        await launch_persistent_context_async("/tmp/profile")
+
+    _mock_seed.assert_called_once_with("/tmp/profile", "/fake/chrome")
@@ -55,12 +55,12 @@ class TestBuildProxyKwargs:
        assert kwargs == {"proxy": {"server": "http://proxy:8080"}}
        assert args == []

-    def test_proxy_with_auth(self):
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_proxy_with_auth(self, *_):
        kwargs, args = _resolve_proxy_config("http://user:pass@proxy:8080")
-        assert kwargs == {
-            "proxy": {"server": "http://proxy:8080", "username": "user", "password": "pass"}
-        }
-        assert args == []
+        assert kwargs == {}
+        assert args == ["--proxy-server=http://user:pass@proxy:8080"]

    def test_proxy_dict_passthrough(self):
        proxy_dict = {"server": "http://proxy:8080", "bypass": ".google.com,localhost"}
@@ -68,7 +68,9 @@ class TestBuildProxyKwargs:
        assert kwargs == {"proxy": proxy_dict}
        assert args == []

-    def test_proxy_dict_with_auth(self):
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_proxy_dict_with_auth(self, *_):
        proxy_dict = {
            "server": "http://proxy:8080",
            "username": "user",
@@ -76,8 +78,11 @@ class TestBuildProxyKwargs:
            "bypass": ".example.com",
        }
        kwargs, args = _resolve_proxy_config(proxy_dict)
-        assert kwargs == {"proxy": proxy_dict}
-        assert args == []
+        assert kwargs == {}
+        assert args == [
+            "--proxy-server=http://user:pass@proxy:8080",
+            "--proxy-bypass-list=.example.com",
+        ]


 class TestMaybeResolveGeoip:
@@ -183,11 +188,12 @@ class TestBareProxyFormat:
        r = _parse_proxy_url("proxy:8080")
        assert r == {"server": "proxy:8080"}

-    def test_resolve_proxy_config_bare(self):
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_resolve_proxy_config_bare(self, *_):
        kwargs, args = _resolve_proxy_config("user:pass@proxy:8080")
-        assert kwargs["proxy"]["username"] == "user"
-        assert kwargs["proxy"]["password"] == "pass"
-        assert "user" not in kwargs["proxy"]["server"]
+        assert kwargs == {}
+        assert args == ["--proxy-server=http://user:pass@proxy:8080"]


 class TestIsSocksProxy:
@@ -219,11 +225,17 @@ class TestResolveProxyConfig:
        assert kwargs == {}
        assert args == []

-    def test_http_string_returns_playwright_dict(self):
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_http_string_with_creds_returns_chrome_arg(self, *_):
        kwargs, args = _resolve_proxy_config("http://user:pass@proxy:8080")
+        assert kwargs == {}
+        assert args == ["--proxy-server=http://user:pass@proxy:8080"]
+
+    def test_http_string_no_creds_returns_playwright_dict(self):
+        kwargs, args = _resolve_proxy_config("http://proxy:8080")
        assert "proxy" in kwargs
        assert kwargs["proxy"]["server"] == "http://proxy:8080"
-        assert kwargs["proxy"]["username"] == "user"
        assert args == []

    def test_http_dict_passthrough(self):
@@ -374,3 +386,95 @@ class TestResolveProxyConfig:
        # 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"
+
+    # --- HTTP with credentials → --proxy-server (supported platforms + version) ---
+
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_http_string_with_creds_on_supported_platform(self, *_):
+        kwargs, args = _resolve_proxy_config("http://user:pass@proxy:8080")
+        assert kwargs == {}
+        assert args == ["--proxy-server=http://user:pass@proxy:8080"]
+
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_http_dict_with_creds_on_supported_platform(self, *_):
+        proxy = {"server": "http://proxy:8080", "username": "user", "password": "pass"}
+        kwargs, args = _resolve_proxy_config(proxy)
+        assert kwargs == {}
+        assert args == ["--proxy-server=http://user:pass@proxy:8080"]
+
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_http_dict_with_creds_and_bypass(self, *_):
+        proxy = {
+            "server": "http://proxy:8080",
+            "username": "user",
+            "password": "pass",
+            "bypass": ".google.com",
+        }
+        kwargs, args = _resolve_proxy_config(proxy)
+        assert kwargs == {}
+        assert "--proxy-server=http://user:pass@proxy:8080" in args
+        assert "--proxy-bypass-list=.google.com" in args
+
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_http_string_encodes_special_chars_in_password(self, *_):
+        _, args = _resolve_proxy_config("http://user:pass=123@proxy:8080")
+        assert args == ["--proxy-server=http://user:pass%3D123@proxy:8080"]
+
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_http_string_encoding_idempotent(self, *_):
+        _, args = _resolve_proxy_config("http://user:pass%3D123@proxy:8080")
+        assert args == ["--proxy-server=http://user:pass%3D123@proxy:8080"]
+
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.5")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="windows-x64")
+    def test_http_string_with_creds_on_windows(self, *_):
+        kwargs, args = _resolve_proxy_config("http://user:pass@proxy:8080")
+        assert kwargs == {}
+        assert args == ["--proxy-server=http://user:pass@proxy:8080"]
+
+    @patch("cloakbrowser.config.get_chromium_version", return_value="146.0.7680.177.3")
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-x64")
+    def test_http_with_creds_old_version_falls_back(self, *_):
+        kwargs, args = _resolve_proxy_config("http://user:pass@proxy:8080")
+        assert "proxy" in kwargs
+        assert args == []
+
+    # --- HTTP with credentials on unsupported platform → fallback to Playwright ---
+
+    @patch("cloakbrowser.config.get_platform_tag", return_value="darwin-arm64")
+    def test_http_string_with_creds_on_macos_falls_back(self, _mock):
+        kwargs, args = _resolve_proxy_config("http://user:pass@proxy:8080")
+        assert "proxy" in kwargs
+        assert kwargs["proxy"]["username"] == "user"
+        assert args == []
+
+    @patch("cloakbrowser.config.get_platform_tag", return_value="darwin-arm64")
+    def test_http_dict_with_creds_on_macos_falls_back(self, _mock):
+        proxy = {"server": "http://proxy:8080", "username": "user", "password": "pass"}
+        kwargs, args = _resolve_proxy_config(proxy)
+        assert kwargs == {"proxy": proxy}
+        assert args == []
+
+    @patch("cloakbrowser.config.get_platform_tag", return_value="linux-arm64")
+    def test_http_string_with_creds_on_linux_arm_falls_back(self, _mock):
+        kwargs, args = _resolve_proxy_config("http://user:pass@proxy:8080")
+        assert "proxy" in kwargs
+        assert args == []
+
+    # --- HTTP without credentials (all platforms) ---
+
+    def test_http_no_creds_returns_playwright_dict(self):
+        kwargs, args = _resolve_proxy_config("http://proxy:8080")
+        assert "proxy" in kwargs
+        assert args == []
+
+    def test_http_dict_no_creds_returns_playwright_dict(self):
+        proxy = {"server": "http://proxy:8080", "bypass": ".example.com"}
+        kwargs, args = _resolve_proxy_config(proxy)
+        assert kwargs == {"proxy": proxy}
+        assert args == []
@@ -0,0 +1,158 @@
+"""Unit tests for Widevine CDM hint-file seeding (cloakbrowser/widevine.py)."""
+
+import json
+
+import pytest
+
+from cloakbrowser import widevine
+from cloakbrowser.widevine import resolve_widevine_cdm_dir, seed_widevine_hint
+
+_HINT = "WidevineCdm/latest-component-updated-widevine-cdm"
+
+
+@pytest.fixture(autouse=True)
+def _force_linux(monkeypatch):
+    """Run as if on Linux unless a test overrides it (seeding is Linux-only)."""
+    monkeypatch.setattr(widevine.platform, "system", lambda: "Linux")
+    monkeypatch.delenv("CLOAKBROWSER_WIDEVINE", raising=False)
+    monkeypatch.delenv("CLOAKBROWSER_WIDEVINE_CDM", raising=False)
+
+
+def _make_cdm(dirpath):
+    """Create a fake WidevineCdm dir with a manifest.json."""
+    dirpath.mkdir(parents=True, exist_ok=True)
+    (dirpath / "manifest.json").write_text('{"version": "4.10.3050.0"}')
+    return dirpath
+
+
+def _binary(tmp_path):
+    """Return a fake chrome binary path inside its own dir."""
+    bdir = tmp_path / "bin"
+    bdir.mkdir(parents=True, exist_ok=True)
+    return bdir / "chrome"
+
+
+def test_seeds_hint_next_to_binary(tmp_path):
+    """CDM in <binary dir>/WidevineCdm -> hint file written with abs Path."""
+    binary = _binary(tmp_path)
+    cdm = _make_cdm(binary.parent / "WidevineCdm")
+
+    profile = tmp_path / "profile"
+    seed_widevine_hint(profile, binary)
+
+    hint = profile / _HINT
+    assert hint.is_file()
+    assert json.loads(hint.read_text())["Path"] == str(cdm.resolve())
+
+
+def test_seeds_hint_from_env_var(tmp_path, monkeypatch):
+    """CLOAKBROWSER_WIDEVINE_CDM takes priority and is used as the Path."""
+    cdm = _make_cdm(tmp_path / "custom_cdm")
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", str(cdm))
+
+    profile = tmp_path / "profile"
+    seed_widevine_hint(profile, _binary(tmp_path))
+
+    assert json.loads((profile / _HINT).read_text())["Path"] == str(cdm.resolve())
+
+
+def test_no_cdm_no_file(tmp_path):
+    """No CDM present -> nothing written, no exception."""
+    profile = tmp_path / "profile"
+    seed_widevine_hint(profile, _binary(tmp_path))
+    assert not (profile / _HINT).exists()
+
+
+def test_kill_switch_disables(tmp_path, monkeypatch):
+    """CLOAKBROWSER_WIDEVINE=0 disables seeding even when a CDM exists."""
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", str(_make_cdm(tmp_path / "custom_cdm")))
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE", "0")
+
+    profile = tmp_path / "profile"
+    seed_widevine_hint(profile, _binary(tmp_path))
+    assert not (profile / _HINT).exists()
+
+
+def test_idempotent(tmp_path, monkeypatch):
+    """Seeding twice leaves the same correct content and doesn't error."""
+    cdm = _make_cdm(tmp_path / "custom_cdm")
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", str(cdm))
+
+    profile = tmp_path / "profile"
+    binary = _binary(tmp_path)
+    seed_widevine_hint(profile, binary)
+    seed_widevine_hint(profile, binary)
+    assert json.loads((profile / _HINT).read_text())["Path"] == str(cdm.resolve())
+
+
+def test_noop_on_non_linux(tmp_path, monkeypatch):
+    """On non-Linux, seeding is a no-op even with a CDM present."""
+    monkeypatch.setattr(widevine.platform, "system", lambda: "Windows")
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", str(_make_cdm(tmp_path / "cdm")))
+
+    profile = tmp_path / "profile"
+    seed_widevine_hint(profile, _binary(tmp_path))
+    assert not (profile / _HINT).exists()
+
+
+def test_resolve_requires_manifest(tmp_path, monkeypatch):
+    """A WidevineCdm dir without manifest.json is not treated as a CDM."""
+    bogus = tmp_path / "custom_cdm"
+    bogus.mkdir()
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", str(bogus))
+    assert resolve_widevine_cdm_dir(_binary(tmp_path)) is None
+
+
+def test_env_var_is_exclusive(tmp_path, monkeypatch):
+    """An invalid CLOAKBROWSER_WIDEVINE_CDM skips seeding — no fallback to binary dir."""
+    binary = _binary(tmp_path)
+    _make_cdm(binary.parent / "WidevineCdm")  # valid CDM next to binary
+    bogus = tmp_path / "bogus"
+    bogus.mkdir()  # set but no manifest.json
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", str(bogus))
+    assert resolve_widevine_cdm_dir(binary) is None
+
+
+def test_empty_env_var_is_exclusive(tmp_path, monkeypatch):
+    """An empty (but set) CLOAKBROWSER_WIDEVINE_CDM is exclusive — no binary-dir fallback."""
+    binary = _binary(tmp_path)
+    _make_cdm(binary.parent / "WidevineCdm")  # valid CDM next to binary
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", "")
+    monkeypatch.chdir(tmp_path)  # so a stray ./manifest.json can't match
+    assert resolve_widevine_cdm_dir(binary) is None
+
+
+def test_empty_user_data_dir_skips(tmp_path, monkeypatch):
+    """Empty user_data_dir (ephemeral profile) -> no CWD pollution, no seeding."""
+    cdm = _make_cdm(tmp_path / "custom_cdm")
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", str(cdm))
+    monkeypatch.chdir(tmp_path)
+    seed_widevine_hint("", _binary(tmp_path))
+    assert not (tmp_path / "WidevineCdm").exists()
+
+
+def test_never_raises_on_write_failure(tmp_path, monkeypatch):
+    """A write failure (hint dir path is a file) must not raise — launch must not break."""
+    cdm = _make_cdm(tmp_path / "custom_cdm")
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", str(cdm))
+    profile = tmp_path / "profile"
+    profile.mkdir()
+    # Block mkdir of <profile>/WidevineCdm by occupying that path with a file.
+    (profile / "WidevineCdm").write_text("not a dir")
+
+    seed_widevine_hint(profile, _binary(tmp_path))  # must not raise
+
+
+def test_rewrites_corrupt_existing_hint(tmp_path, monkeypatch):
+    """A non-UTF8 / mismatched existing hint is overwritten, without raising."""
+    cdm = _make_cdm(tmp_path / "custom_cdm")
+    monkeypatch.setenv("CLOAKBROWSER_WIDEVINE_CDM", str(cdm))
+    profile = tmp_path / "profile"
+    hint = profile / "WidevineCdm" / _HINT.split("/")[-1]
+    hint.parent.mkdir(parents=True)
+    hint.write_bytes(b"\xff\xfe not valid utf-8")
+
+    seed_widevine_hint(profile, _binary(tmp_path))  # must not raise
+
+    # corrupt content replaced with a valid hint pointing at the CDM
+    assert json.loads(hint.read_text())["Path"] == str(cdm.resolve())
Author	SHA1	Message	Date
CloakHQ	776630e08b	release: v0.3.32 — Windows extraction security fix, Widevine CDM seeding, cloakserve fixes	2026-06-20 03:17:07 +02:00
CloakHQ	402a884088	fix(download): pass extract paths to PowerShell via env vars Windows zip extraction interpolated archive/dest paths directly into the PowerShell -Command string. A single quote in the path (e.g. a Windows account like C:\Users\O'Brien) closed the string literal early, breaking extraction and creating a code-injection shape. execFileSync guards the OS-shell boundary but not the PowerShell interpreter inside. Pass both paths via env vars ($env:CB_ARCHIVE / $env:CB_DEST) so PowerShell reads them as data, never as code. No escaping needed. Python wrapper unaffected (zipfile module + argv).	2026-06-20 02:19:48 +02:00
CloakHQ	39db492b04	fix(examples): wait for reCAPTCHA score to render before screenshot (#374 ) networkidle raced the async scoring and the dead button-click never ran. Wait on the rendered result instead. Verified 4/4 in Docker.	2026-06-15 17:58:50 +02:00
CloakHQ	b06499b0c1	test(humanize): deterministic timing for password CDP test Zero typing_delay so the '!'-uses-CDP assertion no longer races the 5s default timeout under random thinking-pauses + CI load. Test only checks which chars route through CDP, not timing.	2026-06-09 17:38:09 +02:00
KumarioandGitHub	a6b1363244	fix(cloakserve): add idle cleanup for seeded profiles (#352 ) * fix(cloakserve): add idle cleanup for seeded profiles * docs(cloakserve): document idle process cleanup	2026-06-09 17:22:33 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	b4a4ad21ab	chore(deps): bump the actions group across 1 directory with 2 updates (#358 ) Bumps the actions group with 2 updates in the / directory: [actions/checkout](https://github.com/actions/checkout) and [docker/setup-qemu-action](https://github.com/docker/setup-qemu-action). Updates `actions/checkout` from 6.0.2 to 6.0.3 - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/checkout/compare/de0fac2e4500dabe0009e67214ff5f5447ce83dd...df4cb1c069e1874edd31b4311f1884172cec0e10) Updates `docker/setup-qemu-action` from 4.0.0 to 4.1.0 - [Release notes](https://github.com/docker/setup-qemu-action/releases) - [Commits](https://github.com/docker/setup-qemu-action/compare/ce360397dd3f832beb865e1373c09c0e9f86d70a...06116385d9baf250c9f4dcb4858b16962ea869c3) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 6.0.3 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: actions - dependency-name: docker/setup-qemu-action dependency-version: 4.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-06-09 16:53:44 +02:00
CloakHQ	dcf9ba55d6	feat(widevine): auto-seed CDM hint file for persistent contexts (Linux) Sideloaded Widevine works on the first launch of a persistent context instead of needing a manual two-launch hint-file workaround. The wrapper writes Chromium's CDM hint file into the profile before launch when a WidevineCdm directory is present next to the binary. - New cloakbrowser/widevine.py and js/src/widevine.ts: resolve a sideloaded CDM (CLOAKBROWSER_WIDEVINE_CDM env var, else next to the binary) and seed the hint file. Linux only; no-op elsewhere. CLOAKBROWSER_WIDEVINE=0 disables. - Never bundles/downloads/copies the CDM (proprietary); seeds only when the user-provided CDM is already present. - Wired into launch_persistent_context[_async] and launchPersistentContext. - README + js/README: Widevine / DRM section, env vars, FPJS tradeoff note. - Tests: tests/test_widevine.py, js/tests/widevine.test.ts, persistent-context integration assertions.	2026-05-29 22:59:59 +02:00
이민재 GitHub honor2030	14ec2ebf5f	fix: rewrite cloakserve CDP WebSocket URLs (#234 ) * fix: rewrite cloakserve CDP WebSocket URLs * fix: guard against blank forwarded host --------- Co-authored-by: honor2030 <19909783+honor2030@users.noreply.github.com>	2026-05-26 23:13:10 +02:00
CloakHQ	0caa14bf7b	release: v0.3.31 — proxy credential routing, humanize iframe fixes	2026-05-26 20:30:28 +02:00
CloakHQ	2a99081850	docs: add recommended config to quick-start, FPJS troubleshooting, update contributors - Add production-ready snippet (proxy, geoip, headless, humanize) near top of both READMEs - Add "Detected by FingerprintJS?" troubleshooting with verified flags: noise=false, screen dimensions, storage quota, geoip, residential proxy - Add @sparanoid to contributors (Docker Xvfb lock fix) - Update @eofreternal credit (iframe pointer-events fix) - Fix stale "48 patches" in JS README	2026-05-26 18:46:13 +02:00
CloakHQ	7fc577e5c6	fix(humanize): port #303 iframe pointer-events fix to Python Mirror the JS fix from #303 in the sync and async Python actionability checks: compute and apply the iframe coordinate offset before elementFromPoint, and fail open when the check itself cannot run. Add fail-open regression tests for both Python and JS.	2026-05-25 01:17:05 +02:00
EternalandGitHub	12d02c3547	fix(humanize): correct iframe coordinate offset in pointer-events check (#303 ) The ElementHandle pointer-events check passed page-space click coordinates to elementFromPoint, which runs inside the target element's frame. For elements in an iframe the coordinate spaces differ, so the check looked at the wrong point and wrongly reported the element as covered. Now the iframe offset is computed and applied. Also fails open when the check itself cannot run. Thanks @eofreternal for the fix.	2026-05-25 01:15:09 +02:00
이민재 GitHub 이민재	243c1385a0	feat(js): export buildContextOptions helper (#262 ) Co-authored-by: 이민재 <19909783+honor2030@users.noreply.github.com>	2026-05-25 00:15:27 +02:00
CloakHQ	0f3dc7201b	chore(deps): bump JS dev dependencies puppeteer-core 21→25 (fixes CVEs in tar-fs, ws), typescript 5→6, @types/node 20→25, playwright-core 1.58→1.60. Vitest stays on v1 (v4 breaks dynamic import mocking).	2026-05-24 23:57:47 +02:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	34d2f78e87	chore(deps): bump the actions group across 1 directory with 3 updates (#309 ) Bumps the actions group with 3 updates in the / directory: [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action), [docker/login-action](https://github.com/docker/login-action) and [docker/build-push-action](https://github.com/docker/build-push-action). Updates `docker/setup-buildx-action` from 4.0.0 to 4.1.0 - [Release notes](https://github.com/docker/setup-buildx-action/releases) - [Commits](https://github.com/docker/setup-buildx-action/compare/4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd...d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5) Updates `docker/login-action` from 4.1.0 to 4.2.0 - [Release notes](https://github.com/docker/login-action/releases) - [Commits](https://github.com/docker/login-action/compare/4907a6ddec9925e35a0a9e82d7399ccc52663121...650006c6eb7dba73a995cc03b0b2d7f5ca915bee) Updates `docker/build-push-action` from 7.1.0 to 7.2.0 - [Release notes](https://github.com/docker/build-push-action/releases) - [Commits](https://github.com/docker/build-push-action/compare/bcafcacb16a39f128d818304e6c9c0c18556b85f...f9f3042f7e2789586610d6e8b85c8f03e5195baf) --- updated-dependencies: - dependency-name: docker/build-push-action dependency-version: 7.2.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions - dependency-name: docker/login-action dependency-version: 4.2.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions - dependency-name: docker/setup-buildx-action dependency-version: 4.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-05-24 23:40:28 +02:00
CloakHQ	41be4e0e30	chore(ci): add pip and npm ecosystems to Dependabot	2026-05-24 23:17:45 +02:00
CloakHQ	58ccdb683c	fix(humanize): use shared deadline for timeout budget in frame and ElementHandle methods (#307 ) Frame-level methods (click, dblclick, hover, dragAndDrop) passed the raw timeout to each sequential operation independently, causing 3x actual wait time when elements don't exist. ElementHandle methods had a similar 2x issue between actionability and pointer-events checks. Port the deadline + remainingMs() pattern already used by page-level methods. Also fix bot detection test selector after site added a hidden duplicate submit button.	2026-05-24 23:12:07 +02:00
CloakHQ	8028ddefef	feat: route HTTP proxy credentials through --proxy-server Bypass Playwright's CDP Fetch.authRequired interceptor for authenticated HTTP proxies by passing inline credentials via Chrome's --proxy-server flag. Chrome sends Proxy-Authorization preemptively, avoiding the 407 round-trip that breaks on some proxies and Google domains (#182). Gated on platform (linux-x64, windows-x64) and binary version >= 146.0.7680.177.5. Unsupported platforms fall back to Playwright's proxy dict. Puppeteer falls back to page.authenticate() on unsupported platforms.	2026-05-21 05:51:03 +02:00
sparanoidandGitHub	864cae2493	fix(docker): clean up stale Xvfb lock so container survives restarts (#284 ) On `docker restart`, `/tmp` is preserved across container instances, so the previous Xvfb's `/tmp/.X99-lock` survives into the new container. The new Xvfb sees the existing lock and refuses to start, leaving the container with no X server. Every Chrome launch then dies with "Missing X server or $DISPLAY", and `cloakserve` returns 502 from `/json/version` forever. Any orchestrator that restarts on unhealthy (the README-recommended healthcheck + `restart: always`, autoheal sidecars, etc.) then enters a permanent restart loop because every restart hits the same broken state. This is silent for first-time users: the container appears to start successfully (Xvfb did launch once), then degrades only after the first restart. The fix is one line in the entrypoint: remove the stale lock before starting Xvfb. Fixes #283	2026-05-21 05:27:49 +02:00